From 8db7700fe769ed59f49c4a42ea4ddcd37ea77ce9 Mon Sep 17 00:00:00 2001 From: Roman Khimov Date: Thu, 18 Mar 2021 22:08:14 +0300 Subject: [PATCH] docs: rework CLI document Bring it up to date, make it more useful. --- docs/cli.md | 421 ++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 293 insertions(+), 128 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 6eb7eba0a..c463dedad 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,183 +1,348 @@ -# NEO-GO client +# NeoGo CLI interface -The Neo-Go client is used to run node, create/compile/deploy/invoke/debug smart contracts, run vm and operate with the wallet. +NeoGo CLI provides all functionality from one binary, so it's used to run +node, create/compile/deploy/invoke/debug smart contracts, run vm and operate +with the wallet. The standard setup assumes that you're running a node as a +separate process and it doesn't provide any CLI of its own, instead it just +makes RPC interface available for you. To perform any actions you invoke NeoGo +as a client that connects to this RPC node and does things you want it to do +(like transferring some NEP-17 asset). + +All CLI commands have corresponding help messages, use `--help` option to get +them, for example: +``` +./bin/neo-go db --help +``` ## Running node -To start Neo Go node locally it's required to run -[neo-privatenet](https://hub.docker.com/r/cityofzion/neo-privatenet/) Docker image on your machine. +Use `node` command to run a NeoGo node, it will be configured using a YAML +file that contains network parameters as well as node settings. -To run node you can use -``` -make run -``` +### Configuration -or run the binary directly: +All config files are located in `./config` and they are differentiated according to the network type: +- `protocol.mainnet.yml` belongs to `--mainnet` network mode (`-m` short option) +- `protocol.privnet.yml` belongs to `--privnet` network mode (`-p` short + option) and is used by default +- `protocol.testnet.yml` belongs to `--testnet` network mode (`-t` short option) +- `protocol.unit_testnet.yml` is used by unit tests + +If you want to use some non-default configuration directory path, specify +`--config-path` flag: + +`./bin/neo-go node --config-path /user/yourConfigPath` + +The file loaded is chosen automatically depending on network mode flag. + +### Starting a node + +To start Neo node on private network use: ``` ./bin/neo-go node ``` -By default the node will run on the `private network`, to change this use additional network flag: +Or specify a different network with appropriate flag like this: ``` ./bin/neo-go node --mainnet ``` -#### Available network flags -- `--mainnet, -m` -- `--privnet, -p` -- `--testnet, -t` +By default the node will run in foreground using current standard output for +logging. -#### Configuration path +### DB import/exports -If you want to use some specific configuration path you have to use `--config-path` flag +Node operates using some database as a backend to store blockchain data. NeoGo +allows to dump chain into file from the database (when node is stopped) or to +import blocks from file into the database (also when node is stopped). Use +`db` command for that. -`./bin/neo-go node --config-path /user/yourConfigPath` +## Smart contracts -## Configuration +Use `contract` command to create/compile/deploy/invoke/debug smart contracts, +see [compiler documentation](compiler.md). -All config files are located in `./config` and they are differentiated according to the network type: -- `protocol.mainnet.yml` belongs to `--mainnet` network mode -- `protocol.privnet.yml` belongs to `--privnet` network mode and used be default -- `protocol.testnet.yml` belongs to `--testnet` network mode -- `protocol.unit_testnet.yml` used by unit tests +## Wallet operations -Those files are automatically loaded, corresponding the provided `netmode` flag. -Example of such configuration: -```yaml -ProtocolConfiguration: - Magic: 56753 - StandbyValidators: - - 02b3622bf4017bdfe317c58aed5f4c753f206b7db896046fa7d774bbc4bf7f8dc2 - - 02103a7f7dd016558597f7960d27c516a4394fd968b9e65155eb4b013e4040406e - - 03d90c07df63e690ce77912e10ab51acc944b66860237b608c4f8f8309e71ee699 - - 02a7bc55fe8684e0119768d104ba30795bdcc86619e864add26156723ed185cd62 - SeedList: - - 127.0.0.1:20333 - - 127.0.0.1:20334 - - 127.0.0.1:20335 - - 127.0.0.1:20336 +`wallet` command provides interface for all operations requiring a wallet +(except contract deployment and invocations that are done via `contract +deploy` and `contract invokefunction`). Wallet management (creating wallet, +adding addresses/keys to it) is available there as well as wallet-related +functions like NEP-17 transfers, NEO votes, multi-signature signing and other +things. -ApplicationConfiguration: - DataDirectoryPath: "./chains/privnet" - RPCPort: 20332 - NodePort: 20333 - Relay: true - DialTimeout: 3 - ProtoTickInterval: 2 - MaxPeers: 50 +### Wallet management + +#### Create wallet + +Use `wallet init` command to create new wallet: ``` -#### Node debug mode +./bin/neo-go wallet init -w wallet.nep6 -There is a debug mode available by additional flag: `--debug, -d` +{ + "version": "3.0", + "accounts": [], + "scrypt": { + "n": 16384, + "r": 8, + "p": 8 + }, + "extra": { + "Tokens": null + } + } -## Smart contract create/compile/deploy/invoke/debug - -### Create - -In order to create new smart contract: -`./bin/neo-go contract init -n TestContract` - -where -`init` used to initialize new contract and `--name, -n` - to specify contract name. - -It will run wizard with a few questions: -``` -Author: TestAuthor -Email: test@gmail.com -Version: 1 -Project name: Test -Description: desc -Successfully initialized smart contract [TestContract] +wallet successfully created, file location is wallet.nep6 ``` -After that you will have a package with `TestContract` name and it will include -- `main.go` smart contract file -- `neo-go.yml` project section containing information about the contact - -In case you don't want to provide details use `--skip-details, -skip`. - -### Compile - +where "wallet.nep6" is a wallet file name. This wallet will be empty, to +generate a new key pair and add an account for it use `-a` option: ``` -./bin/neo-go contract compile -i mycontract.go +./bin/neo-go wallet init -w wallet.nep6 -a +Enter the name of the account > Name +Enter passphrase > +Confirm passphrase > + +{ + "version": "3.0", + "accounts": [ + { + "address": "NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E", + "key": "6PYL2UrC11nWFJWSLiqsPKCNm9u4zr4ttX1ZbV9f2fLDqXsePioVxEsYdg", + "label": "Name", + "contract": { + "script": "DCEDzs1j19gSDDsZTDsogN1Kr+FHXFfkDIUoctcwVhUlgUBBdHR2qg==", + "parameters": [ + { + "name": "parameter0", + "type": "Signature" + } + ], + "deployed": false + }, + "lock": false, + "isdefault": false + } + ], + "scrypt": { + "n": 16384, + "r": 8, + "p": 8 + }, + "extra": { + "Tokens": null + } + } + +wallet successfully created, file location is wallet.nep6 ``` -By default the output filename will be the name of your `.go` file with the `.nef` extension, the file will be located -in the same directory where you called the command from. If you want another location for your compiled contract: - +or use `wallet create` command to create new account in existing wallet: ``` -./bin/neo-go contract compile -i mycontract.go --out /Users/foo/bar/contract.nef +./bin/neo-go wallet create -w wallet.nep6 +Enter the name of the account > Joe Random +Enter passphrase > +Confirm passphrase > ``` -### Deploy -//Not implemented yet - -### Invoke -//Implemented in test mode. It means that it won't affect the blockchain +#### Convert Neo Legacy wallets to Neo N3 +Use `wallet convert` to update addresses in NEP-6 wallets used with Neo +Legacy. New wallet is specified in `-o` option, it will have the same keys +with Neo N3 addresses. ``` -./bin/neo-go contract testinvoke -i mycontract.nef +./bin/neo-go wallet convert -w old.nep6 -o new.nep6 ``` -### Debug -You can dump the opcodes generated by the compiler with the following command: - +#### Check wallet contents +`wallet dump` can be used to see wallet contents in more user-friendly way, +its output is the same NEP-6 JSON, but better formatted. You can also decrypt +keys at the same time with `-d` option (you'll be prompted for password): ``` -./bin/neo-go contract inspect -i mycontract.go +./bin/neo-go wallet dump -w wallet.nep6 -d +Enter wallet password > + +{ + "version": "3.0", + "accounts": [ + { + "address": "NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E", + "key": "6PYL2UrC11nWFJWSLiqsPKCNm9u4zr4ttX1ZbV9f2fLDqXsePioVxEsYdg", + "label": "Name", + "contract": { + "script": "DCEDzs1j19gSDDsZTDsogN1Kr+FHXFfkDIUoctcwVhUlgUBBdHR2qg==", + "parameters": [ + { + "name": "parameter0", + "type": "Signature" + } + ], + "deployed": false + }, + "lock": false, + "isdefault": false + } + ], + "scrypt": { + "n": 16384, + "r": 8, + "p": 8 + }, + "extra": { + "Tokens": null + } + } ``` -This will result in something like this: - +You can also get public keys for addresses stored in your wallet with `wallet +dump-keys` command: ``` -INDEX OPCODE DESC -0 0x54 PUSH4 -1 0xc5 NEWARRAY -2 0x6b TOALTSTACK -3 0x5a PUSH10 -4 0x6a DUPFROMALTSTACK -5 0x0 PUSH0 -6 0x52 PUSH2 -7 0x7a ROLL -8 0xc4 SETITEM -9 0x6a DUPFROMALTSTACK -10 0x0 PUSH0 -11 0xc3 PICKITEM -12 0x5a PUSH10 -13 0xa2 GTE -14 0x64 JMPIFNOT -15 0x7 7 -15 0x0 0 -17 0x51 PUSH1 -18 0x6c FROMALTSTACK -19 0x75 DROP -20 0x66 RET -21 0x0 PUSH0 -22 0x6c FROMALTSTACK -23 0x75 DROP -24 0x66 RET +./bin/neo-go wallet dump-keys -w wallet.nep6 +NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E (simple signature contract): +03cecd63d7d8120c3b194c3b2880dd4aafe1475c57e40c852872d7305615258140 ``` -In depth documentation about the **neo-go** compiler and smart contract examples can be found inside -the [compiler package](pkg/compiler). +#### Private key export +`wallet export` allows you to export private key in NEP-2 encrypted or WIF +(unencrypted) form (`-d` flag). +``` +$ ./bin/neo-go wallet export -w wallet.nep6 -d NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E +Enter password > +KyswN8r48dhsvyQJVy97RWnZmKgYLrXv9mCL81Kb4vAagZiCsePv +``` -## VM run -To run VM use +#### Private key import +You can import NEP-2 or WIF private key along with verification contract (if +it's non-standard): +``` +./bin/neo-go wallet import --wif KwYgW8gcxj1JWJXhPSu4Fqwzfhp5Yfi42mdYmMa4XqK7NJxXUSK7 -w wallet.nep6 +Provided WIF was unencrypted. Wallet can contain only encrypted keys. +Enter the name of the account > New Account +Enter passphrase > +Confirm passphrase > +``` + +#### Special accounts +Multisignature accounts can be imported with `wallet import-multisig`, you'll +need all public keys and one private key to do that. Then you could sign +transactions for this multisignature account with imported key. + +`wallet import-deployed` can be used to create wallet accounts for deployed +contracts. They also can have WIF keys associated with them (in case your +contract's `verify` method needs some signature). + +### Neo voting +`wallet candidate` provides commands to register or unregister a committee +(and therefore validator) candidate key: +``` +./bin/neo-go wallet candidate register -a NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E -w wallet.json -r http://localhost:20332 +``` + +You can also vote for candidates if you own NEO: +``` +./bin/neo-go wallet candidate vote -a NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E -w wallet.json -r http://localhost:20332 -c 03cecd63d7d8120c3b194c3b2880dd4aafe1475c57e40c852872d7305615258140 +``` + +### NEP-17 token functions + +`wallet nep17` contains a set of commands to use for NEP-17 tokens. + +#### Token metadata + +NEP-17 commands are designed to work with any NEP-17 tokens, but NeoGo needs +some metadata for these tokens to function properly. Native NEO or GAS are +known to NeoGo by default, but other tokens are not. NeoGo can get this +metadata from the specified RPC server, but that's an additional request to +make, so if you care about command processing delay you can import token +metadata into the wallet with `wallet nep17 import` command. It'll be stored +in the `extra` section of the wallet. +``` +./bin/neo-go wallet nep17 import -w wallet.nep6 -r http://localhost:20332 -t abcdefc189f30098b0ba6a2eb90b3a925800ffff +``` + +You can later see what token data you have in your wallet with `wallet nep17 +info` command and remove tokens you don't need with `wallet nep17 remove`. + +#### Balance +Getting balance is easy: +``` +./bin/neo-go wallet nep17 balance -w /etc/neo-go/wallet.json -r http://localhost:20332 +``` + +By default you'll get data for all tokens for the default wallet's +address. You can select non-default address with `-a` flag and/or select token +with `--token` flag (token hash or name can be used as parameter) + +#### Transfers + +`wallet nep17 transfer` creates a token transfer transaction and pushes it to +the RPC server (or saves to file if it needs to be signed by multiple +parties). For example, transferring 100 GAS looks like this: + +``` +./bin/neo-go wallet nep17 transfer -w wallet.nep6 -r http://localhost:20332 --to NjEQfanGEXihz85eTnacQuhqhNnA6LxpLp --from NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E --token GAS --amount 100 +``` + +You can omit `--from` parameter (default wallet's address will be used in this +case), you can add `--gas` for extra network fee (raising priority of your +transaction). And you can save transaction to file with `--out` instead of +sending it to the network if it needs to be signed by multiple parties. + +One `transfer` invocation creates one transaction, but in case you need to do +many transfers you can save on network fees by doing multiple token moves with +one transaction by using `wallet nep17 multitransfer` command. It can transfer +things from one account to many, its syntax differs from `transfer` in that +you don't have `--token`, `--to` and `--amount` options, but instead you can +specify multiple "token:addr:amount" sets after all other options. The same +transfer as above can be done with `multitransfer` by doing this: +``` +./bin/neo-go wallet nep17 multitransfer -w wallet.nep6 -r http://localhost:20332 --from NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E GAS:NjEQfanGEXihz85eTnacQuhqhNnA6LxpLp:100 +``` + +#### GAS claims + +While Neo N3 doesn't have any notion of "claim transaction" and has GAS +automatically distributed with every NEO transfer for NEO owners you still +won't get GAS if you don't do any actions. So the old `wallet claim` command +was updated to be an easier way to do NEO "flipping" when you send a +transaction that transfers all of your NEO to yourself thereby triggering GAS +distribution. + +## Conversion utility + +NeoGo provides conversion utility command to reverse data, convert script +hashes to/from address, convert data to/from hexadecimal or base64 +representation. All of this is done by a single `util convert` command like +this: +``` +$ ./bin/neo-go util convert deee79c189f30098b0ba6a2eb90b3a9258a6c7ff +BE ScriptHash to Address NgEisvCqr2h8wpRxQb7bVPWUZdbVCY8Uo6 +LE ScriptHash to Address NjEQfanGEXihz85eTnacQuhqhNnA6LxpLp +Hex to String "\xde\xeey\xc1\x89\xf3\x00\x98\xb0\xbaj.\xb9\v:\x92X\xa6\xc7\xff" +Hex to Integer -1256651697634605895065630637163547727407485218 +Swap Endianness ffc7a658923a0bb92e6abab09800f389c179eede +Base64 to String "u\xe7\x9e\xef\xd75\xf3\xd7\xf7\xd3O|oF\xda魞o\xdd\x1bݯv\xe7ƺs\xb7\xdf" +Base64 to BigInteger -222811771454869584930239486728381018152491835874567723544539443409000587 +String to Hex 64656565373963313839663330303938623062613661326562393062336139323538613663376666 +String to Base64 ZGVlZTc5YzE4OWYzMDA5OGIwYmE2YTJlYjkwYjNhOTI1OGE2YzdmZg== +``` + +## VM CLI +There is a VM CLI that you can use to load/analyze/run/step through some code: ``` ./bin/neo-go vm ``` -For the detailed help use `help` in VM console. -There is a small subset of commands: +Some basic commands available there: - `loadgo` -- loads smart contract `NEO-GO-VM > loadgo TestContract/main.go` - `ops` -- show the opcodes of currently loaded contract - `run` -- executes currently loaded contract -## Wallet operations - -- `./bin/neo-go wallet init -w newWallet` to create new wallet in the path `newWallet` -- `./bin/neo-go wallet dump -w newWallet` to open created wallet in the path `newWallet` -- `./bin/neo-go wallet init -w newWallet -a` to create new account +Use `help` command to get more detailed information on all possibilities and +particular commands. Note that this VM is completely disconnected from the +blockchain, so you won't have all interop functionality available for smart +contracts (use test invocations via RPC for that).