docs: rework CLI document

Bring it up to date, make it more useful.
This commit is contained in:
Roman Khimov 2021-03-18 22:08:14 +03:00
parent b7625aaa2d
commit 8db7700fe7

View file

@ -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).