From 86cf72c35e88ca13ae2b0f493354d33b39a1da68 Mon Sep 17 00:00:00 2001 From: Samsung Date: Sat, 24 Jun 2023 09:38:10 +0200 Subject: [PATCH] Create a .readme file with usage examples #22 --- README.md | 585 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 556 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index bc2d4a0..88f94b2 100644 --- a/README.md +++ b/README.md @@ -42,17 +42,18 @@ See also prior version [aurora-cli](https://github.com/aurora-is-near/aurora-cli - 🔍 Check out what each command is for in the official Aurora [docs](https://doc.aurora.dev/tools/aurora-cli) - ✋ Have questions? Ask them at the official Aurora [forum](https://forum.aurora.dev/) -## Example of usage +## Usage In the following example, we will see how to deploy Aurora EVM on the `localnet`. Also, we will deploy a simple EVM smart contract and will be interacting with it. -#### What we need to have +### **Requirements** - Rust 1.68.0 or newer - Python3 First what we need to do is to install `aurora-cli`: +### **Installing aurora-cli** ```shell git clone https://github.com/aurora-engine/aurora-cli-rs cd aurora-cli-rs && cargo install --path . @@ -60,6 +61,7 @@ cd aurora-cli-rs && cargo install --path . Next we need to start a NEAR node locally. We can use the NEAR utility, `nearup`. +### **Start a NEAR node locally** Install `nearup`: ```shell pip3 install --user nearup @@ -70,11 +72,10 @@ Start NEAR node: nearup run localnet --home /tmp/localnet ``` -After that we need to prepare an account and create a file with a private key for the Aurora EVM. - +### **Prepare an account and create a private key file for Aurora EVM** ```shell aurora-cli --near-key-path /tmp/localnet/node0/validator_key.json create-account \ - --account aurora.node0 --balance 100 > /tmp/localnet/auora_key.json + --account aurora.node0 --balance 100 > /tmp/localnet/aurora_key.json ``` Let's check if the account has been created successfully: @@ -82,32 +83,24 @@ Let's check if the account has been created successfully: aurora-cli view-account aurora.node0 ``` -If everything went well, the response should be like this: -```json -{ - "amount": "100000000000000000000000000", - "locked": "0", - "code_hash": "11111111111111111111111111111111", - "storage_usage": 182, - "storage_paid_at": 0 -} -``` - -Now we can deploy and initialize the Aurora EVM. To download the latest version, run the following command: +### **Download and deploy Aurora EVM** +To download the latest version, run the following command: ```shell curl -sL https://github.com/aurora-is-near/aurora-engine/releases/download/latest/aurora-mainnet.wasm -o /tmp/aurora-mainnet.wasm ``` Deploy Aurora EVM: ```shell -aurora-cli --near-key-path /tmp/localnet/auora_key.json deploy-aurora /tmp/aurora-mainnet.wasm +aurora-cli --near-key-path /tmp/localnet/aurora_key.json deploy-aurora /tmp/aurora-mainnet.wasm ``` Initialize Aurora EVM: ```shell -aurora-cli --engine aurora.node0 --near-key-path /tmp/localnet/auora_key.json init --chain-id 1313161556 --owner-id aurora.node0 +aurora-cli --engine aurora.node0 --near-key-path /tmp/localnet/aurora_key.json init --chain-id 1313161556 --owner-id aurora.node0 ``` +### **Deploy the EVM smart contract** + And now we can deploy the EVM smart contract. In our example, it will be a simple counter that can return its current value and increment and decrement its value. @@ -126,7 +119,7 @@ The response should be similar to this: Deploy EVM smart contract: ```shell -aurora-cli --engine aurora.node0 --near-key-path /tmp/localnet/auora_key.json deploy \ +aurora-cli --engine aurora.node0 --near-key-path /tmp/localnet/aurora_key.json deploy \ --code $(cat docs/res/Counter.hex) \ --abi-path docs/res/Counter.abi \ --args '{"init_value":"5"}' \ @@ -134,23 +127,25 @@ aurora-cli --engine aurora.node0 --near-key-path /tmp/localnet/auora_key.json de ``` If everything went well, the response should be like this: ``` -Contract has been deployed to address: 0x8417907c7158f02b42b0962cac27c4b4fd4a11f2 successfully +Contract has been deployed to address: 0x53a9fed853e02a39bf8d298f751374de8b5a6ddf successfully ``` -So. Now we have deployed the smart contract at address: `0x8417907c7158f02b42b0962cac27c4b4fd4a11f2`. +So. Now we have deployed the smart contract at address: `0x53a9fed853e02a39bf8d298f751374de8b5a6ddf`. + +### **Interact with the smart contract** -Let's interact with our smart contract. First, let's check that the current value is the same as we set in the +First, let's check that the current value is the same as we set in the initialization stage. For that, we will use the `view-call` operation, which doesn't demand a private key because it is a read-only operation: ```shell -aurora-cli --engine aurora.node0 view-call -a 0x8417907c7158f02b42b0962cac27c4b4fd4a11f2 -f value \ +aurora-cli --engine aurora.node0 view-call -a 0x53a9fed853e02a39bf8d298f751374de8b5a6ddf -f value \ --abi-path docs/res/Counter.abi ``` If we see `5` then everything is right. Now let's try to increment the value: ```shell -aurora-cli --engine aurora.node0 --near-key-path /tmp/localnet/auora_key.json call \ - --address 0x8417907c7158f02b42b0962cac27c4b4fd4a11f2 \ +aurora-cli --engine aurora.node0 --near-key-path /tmp/localnet/aurora_key.json call \ + --address 0x53a9fed853e02a39bf8d298f751374de8b5a6ddf \ -f increment \ --abi-path docs/res/Counter.abi \ --aurora-secret-key 3fac6dca1c6fc056b971a4e9090afbbfbdf3bc443e9cda595facb653cb1c01e1 @@ -160,14 +155,546 @@ transaction. Let's make sure that our value was incremented: ```shell -aurora-cli --engine aurora.node0 view-call -a 0x8417907c7158f02b42b0962cac27c4b4fd4a11f2 -f value \ +aurora-cli --engine aurora.node0 view-call -a 0x53a9fed853e02a39bf8d298f751374de8b5a6ddf -f value \ --abi-path docs/res/Counter.abi ``` So, if we can see `6` in the output then the demo was successful. That's it! -Also, `aurora-cli` can be built with the advanced command line interface. Advanced CLI provides more options and -advanced features. You can try it by building with the following command: +### **Build aurora-cli with the advanced command line interface (Advanced CLI)** + +Advanced CLI provides more options andadvanced features. You can try it by building with the following command: ```shell cargo install --path . --no-default-features -F advanced ``` Documentation on how to work with the advanced version of `aurora-cli` can be found [here](docs/localnet.md). + +### **Browse Deployed EVM Metadata** + +```shell +aurora-cli --engine aurora.node0 get-version +aurora-cli --engine aurora.node0 get-owner +aurora-cli --engine aurora.node0 get-bridge-prover +aurora-cli --engine aurora.node0 get-chain-id +``` + +### **Examining EVM contract state** + +```shell +aurora-cli --engine aurora.node0 get-nonce 0x53a9fed853e02a39bf8d298f751374de8b5a6ddf +aurora-cli --engine aurora.node0 get-code 0x53a9fed853e02a39bf8d298f751374de8b5a6ddf +aurora-cli --engine aurora.node0 get-balance 0x53a9fed853e02a39bf8d298f751374de8b5a6ddf +aurora-cli --engine aurora.node0 get-storage-at --address 0x53a9fed853e02a39bf8d298f751374de8b5a6ddf --key 0 +``` + + +## Reference + +- [`aurora-cli help`](#aurora-cli-help) +- [`aurora-cli create-account`](#aurora-cli-create-account) +- [`aurora-cli view-account`](#aurora-cli-view-account) +- [`aurora-cli deploy-aurora`](#aurora-cli-deploy-aurora) +- [`aurora-cli init`](#aurora-cli-init) +- [`aurora-cli get-chain-id`](#aurora-cli-get-chain-id) +- [`aurora-cli get-nonce`](#aurora-cli-get-nonce) +- [`aurora-cli get-block-hash`](#aurora-cli-get-block-hash) +- [`aurora-cli get-code`](#aurora-cli-get-code) +- [`aurora-cli get-balance`](#aurora-cli-get-balance) +- [`aurora-cli get-upgrade-index`](#aurora-cli-get-upgrade-index) +- [`aurora-cli get-version`](#aurora-cli-get-version) +- [`aurora-cli get-owner`](#aurora-cli-get-owner) +- [`aurora-cli set-owner`](#aurora-cli-set-owner) +- [`aurora-cli get-bridge-prover`](#aurora-cli-get-bridge-prover) +- [`aurora-cli get-storage-at`](#aurora-cli-get-storage-at) +- [`aurora-cli register-relayer`](#aurora-cli-register-relayer) +- [`aurora-cli pause-precompiles`](#aurora-cli-pause-precompiles) +- [`aurora-cli resume-precompiles`](#aurora-cli-resume-precompiles) +- [`aurora-cli paused-precompiles`](#aurora-cli-paused-precompiles) +- [`aurora-cli factory-update`](#aurora-cli-factory-update) +- [`aurora-cli factory-set-wnear-address`](#aurora-cli-factory-set-wnear-address) +- [`aurora-cli fund-xcc-sub-account`](#aurora-cli-fund-xcc-sub-account) +- [`aurora-cli stage-upgrade`](#aurora-cli-stage-upgrade) +- [`aurora-cli deploy-upgrade`](#aurora-cli-deploy-upgrade) +- [`aurora-cli deploy`](#aurora-cli-deploy) +- [`aurora-cli view-call`](#aurora-cli-view-call) +- [`aurora-cli call`](#aurora-cli-call) +- [`aurora-cli encode-address`](#aurora-cli-encode-address) +- [`aurora-cli key-pair`](#aurora-cli-key-pair) + + +### `aurora-cli help` + +```console +$ aurora-cli help +Simple command line interface for communication with Aurora Engine + +Usage: aurora-cli [OPTIONS] + +Commands: + create-account Create new NEAR account + view-account View NEAR account + deploy-aurora Deploy Aurora EVM smart contract + init Initialize Aurora EVM and ETH connector + get-chain-id Return chain id of the network + get-nonce Return next nonce for address + get-block-hash Return block hash of the specified height + get-code Return smart contract's code for contract address + get-balance Return balance for address + get-upgrade-index Return a height for a staged upgrade + get-version Return Aurora EVM version + get-owner Return Aurora EVM owner + set-owner Set a new owner of Aurora EVM + get-bridge-prover Return bridge prover + get-storage-at Return a value from storage at address with key + register-relayer Register relayer address + pause-precompiles Pause precompiles + resume-precompiles Resume precompiles + paused-precompiles Return paused precompiles + factory-update Updates the bytecode for user's router contracts + factory-set-wnear-address Sets the address for the `wNEAR` ERC-20 contract + fund-xcc-sub-account Create and/or fund an XCC sub-account directly + stage-upgrade Stage a new code for upgrade + deploy-upgrade Deploy staged upgrade + deploy Deploy EVM smart contract's code in hex + view-call Call a view method of the smart contract + call Call a modified method of the smart contract + encode-address Encode address + key-pair Return Public and Secret ED25519 keys + help Print this message or the help of the given subcommand(s) + +Options: + --network NEAR network ID [default: localnet] + --engine Aurora EVM account [default: aurora] + --near-key-path Path to file with NEAR account id and secret key in JSON format + -h, --help Print help + -V, --version Print version +``` + +### `aurora-cli view-account` + +```console +$ aurora-cli help create-account +Create new NEAR account + +Usage: aurora-cli create-account --account --balance + +Options: + -a, --account AccountId + -b, --balance Initial account balance in NEAR + -h, --help Print help +``` + +### `aurora-cli create-account` + +```console +$ aurora-cli help view-account +View NEAR account + +Usage: aurora-cli view-account + +Arguments: + AccountId + +Options: + -h, --help Print help +``` + +### `aurora-cli deploy-aurora` + +```console +$ aurora-cli help deploy-aurora +Deploy Aurora EVM smart contract + +Usage: aurora-cli deploy-aurora + +Arguments: + Path to the WASM file + +Options: + -h, --help Print help +``` + +### `aurora-cli init` + +```console +$ aurora-cli help init +Initialize Aurora EVM and ETH connector + +Usage: aurora-cli init [OPTIONS] + +Options: + --chain-id + Chain ID [default: 1313161556] + --owner-id + Owner of the Aurora EVM + --bridge-prover-id + Account of the bridge prover + --upgrade-delay-blocks + How many blocks after staging upgrade can deploy it + --custodian-address + Custodian ETH address + --ft-metadata-path + Path to the file with the metadata of the fungible token + -h, --help + Print help +``` + +### `aurora-cli get-chain-id` + +```console +$ aurora-cli help get-chain-id +Return chain id of the network + +Usage: aurora-cli get-chain-id + +Options: + -h, --help Print help +``` + +### `aurora-cli get-nonce` + +```console +$ aurora-cli help get-nonce +Return next nonce for address + +Usage: aurora-cli get-nonce
+ +Arguments: +
+ +Options: + -h, --help Print help + +``` + +### `aurora-cli get-block-hash` + +```console +$ aurora-cli help get-block-hash +Return block hash of the specified height + +Usage: aurora-cli get-block-hash + +Arguments: + + +Options: + -h, --help Print help +``` + +### `aurora-cli get-code` + +```console +$ aurora-cli help get-code +Return smart contract's code for contract address + +Usage: aurora-cli get-code
+ +Arguments: +
+ +Options: + -h, --help Print help + +``` + +### `aurora-cli get-balance` + +```console +$ aurora-cli help get-balance +Return balance for address + +Usage: aurora-cli get-balance
+ +Arguments: +
+ +Options: + -h, --help Print help +``` + +### `aurora-cli get-upgrade-index` + +```console +$ aurora-cli help get-upgrade-index +Return a height for a staged upgrade + +Usage: aurora-cli get-upgrade-index + +Options: + -h, --help Print help +``` + +### `aurora-cli get-version` + +```console +$ aurora-cli help get-version +Return Aurora EVM version + +Usage: aurora-cli get-version + +Options: + -h, --help Print help +``` + +### `aurora-cli get-owner` + +```console +$ aurora-cli help get-owner +Return Aurora EVM owner + +Usage: aurora-cli get-owner + +Options: + -h, --help Print help +``` + +### `aurora-cli set-owner` + +```console +$ aurora-cli help set-owner +Set a new owner of Aurora EVM + +Usage: aurora-cli set-owner + +Arguments: + + +Options: + -h, --help Print help +``` + +### `aurora-cli get-bridge-prover` + +```console +$ aurora-cli help get-bridge-prover +Return bridge prover + +Usage: aurora-cli get-bridge-prover + +Options: + -h, --help Print help +``` + +### `aurora-cli get-storage-at` + +```console +$ aurora-cli help get-storage-at +Return a value from storage at address with key + +Usage: aurora-cli get-storage-at --address
--key + +Options: + -a, --address
+ -k, --key + -h, --help Print help +``` + +### `aurora-cli register-relayer` + +```console +$ aurora-cli help register-relayer +Register relayer address + +Usage: aurora-cli register-relayer
+ +Arguments: +
+ +Options: + -h, --help Print help +``` + +### `aurora-cli pause-precompiles` + +```console +$ aurora-cli help pause-precompiles +Pause precompiles + +Usage: aurora-cli pause-precompiles + +Arguments: + + +Options: + -h, --help Print help +``` + +### `aurora-cli resume-precompiles` + +```console +$ aurora-cli help resume-precompiles +Resume precompiles + +Usage: aurora-cli resume-precompiles + +Arguments: + + +Options: + -h, --help Print help +``` + +### `aurora-cli paused-precompiles` + +```console +$ aurora-cli help paused-precompiles +Return paused precompiles + +Usage: aurora-cli paused-precompiles + +Options: + -h, --help Print help +``` + +### `aurora-cli factory-update` + +```console +$ aurora-cli help factory-update +Updates the bytecode for user's router contracts + +Usage: aurora-cli factory-update + +Arguments: + + +Options: + -h, --help Print help +``` + +### `aurora-cli factory-set-wnear-address` + +```console +$ aurora-cli help factory-set-wnear-address +Sets the address for the `wNEAR` ERC-20 contract + +Usage: aurora-cli factory-set-wnear-address
+ +Arguments: +
+ +Options: + -h, --help Print help +``` + +### `aurora-cli fund-xcc-sub-account` + +```console +$ aurora-cli help fund-xcc-sub-account +Create and/or fund an XCC sub-account directly + +Usage: aurora-cli fund-xcc-sub-account [WNEAR_ACCOUNT_ID] + +Arguments: + Address of the target + [WNEAR_ACCOUNT_ID] Wnear Account Id + Attached deposit in NEAR + +Options: + -h, --help Print help +``` + +### `aurora-cli stage-upgrade` + +```console +$ aurora-cli help stage-upgrade +Stage a new code for upgrade + +Usage: aurora-cli stage-upgrade + +Arguments: + + +Options: + -h, --help Print help +``` + +### `aurora-cli deploy-upgrade` + +```console +$ aurora-cli help deploy-upgrade +Deploy staged upgrade + +Usage: aurora-cli deploy-upgrade + +Options: + -h, --help Print help +``` + +### `aurora-cli deploy` + +```console +$ aurora-cli help deploy +Deploy EVM smart contract's code in hex + +Usage: aurora-cli deploy [OPTIONS] --code + +Options: + --code Code in HEX to deploy + --args Constructor arguments with values in JSON + --abi-path Path to ABI of the contract + --aurora-secret-key Aurora EVM secret key + -h, --help Print help +``` + +### `aurora-cli view-call` + +```console +$ aurora-cli help view-call +Call a view method of the smart contract + +Usage: aurora-cli view-call [OPTIONS] --address
--function --abi-path + +Options: + -a, --address
Address of the smart contract + -f, --function Name of the function to call + --args Arguments with values in JSON + --abi-path Path to ABI of the contract + -h, --help Print help +``` + +### `aurora-cli call` + +```console +aurora-cli help call +Call a modified method of the smart contract + +Usage: aurora-cli call [OPTIONS] --address
--function --abi-path + +Options: + -a, --address
Address of the smart contract + -f, --function Name of the function to call + --args Arguments with values in JSON + --abi-path Path to ABI of the contract + --value Value sending in EVM transaction + --aurora-secret-key Aurora EVM secret key + -h, --help Print help +``` + +### `aurora-cli encode-address` + +```console +$ aurora-cli help encode-address +Encode address + +Usage: aurora-cli encode-address + +Arguments: + + +Options: + -h, --help Print help +``` + +### `aurora-cli key-pair` + +```console +$ aurora-cli help key-pair +Return Public and Secret ED25519 keys + +Usage: aurora-cli key-pair [OPTIONS] + +Options: + --random Random + --seed From seed + -h, --help Print help +``` \ No newline at end of file