From 51b93a9a555b9985a8c5c413c8645d79db8561ba Mon Sep 17 00:00:00 2001 From: Vsevolod Brekelov Date: Mon, 2 Sep 2019 16:43:44 +0300 Subject: [PATCH] Add neo-go cli documentation Comments fix --- README.md | 89 +---------------------- cli/README.md | 191 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 193 insertions(+), 87 deletions(-) create mode 100644 cli/README.md diff --git a/README.md b/README.md index e8db4c4db..8f59f0eb0 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ A complete toolkit for the NEO blockchain, including: - Consensus node (WIP) - [RPC node & client](https://github.com/nspcc-dev/neo-go/tree/master/pkg/rpc/README.md) - [RPC client](https://github.com/nspcc-dev/neo-go/blob/master/pkg/rpc/README.md) -- CLI tool +- [CLI tool](https://github.com/nspcc-dev/neo-go/blob/master/cli/README.md) - [Smart contract compiler](https://github.com/nspcc-dev/neo-go/blob/master/pkg/vm/compiler/README.md) - [NEO virtual machine](https://github.com/nspcc-dev/neo-go/blob/master/pkg/vm/README.md) @@ -73,7 +73,7 @@ make run To run the binary directly: ``` -./bin/neo-go node -seed 127.0.0.1:20333,127.0.0.1:20334 +./bin/neo-go node ``` By default the node will run on the `private network`, to change his: @@ -87,91 +87,6 @@ Available network flags: - `--privnet, -p` - `--testnet, -t` -If you want in-depth customization for your node, there are `yaml` config files for each `network` available in the `config` directory. Those files are automatically loaded, corresponding the provided `netmode` flag. - -```yaml -ProtocolConfiguration: - Magic: 56753 - AddressVersion: 23 - 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 - SystemFee: - EnrollmentTransaction: 1000 - IssueTransaction: 500 - PublishTransaction: 500 - RegisterTransaction: 10000 - -ApplicationConfiguration: - DataDirectoryPath: "./chains/privnet" - RPCPort: 20332 - NodePort: 20333 - Relay: true - DialTimeout: 3 - ProtoTickInterval: 2 - MaxPeers: 50 -``` - -## Writing smart contracts in Go -In depth documentation about the **neo-go** compiler and smart contract examples can be found inside the [compiler package](https://github.com/nspcc-dev/neo-go/tree/master/pkg/vm/compiler). - -### Compile a smart contract - -``` -./bin/neo-go contract compile -i mycontract.go -``` - -By default the filename will be the name of your `.go` file with the `.avm` 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: - -``` -./bin/neo-go contract compile -i mycontract.go --out /Users/foo/bar/contract.avm -``` - -### Debugging your smart contract -You can dump the opcodes generated by the compiler with the following command: - -``` -./bin/neo-go contract inspect -i mycontract.go -``` - -This will result in something like this: - -``` -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 -``` - # Contributing Feel free to contribute to this project after reading the diff --git a/cli/README.md b/cli/README.md new file mode 100644 index 000000000..3748401aa --- /dev/null +++ b/cli/README.md @@ -0,0 +1,191 @@ +# NEO-GO client + +The Neo-Go client is used to run node, create/compile/deploy/invoke/debug smart contracts, run vm and operate with the wallet. + +## 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. + +To run node you can use +``` +make run +``` + +or run the binary directly: + +``` +./bin/neo-go node +``` + +By default the node will run on the `private network`, to change this use additional network flag: + +``` +./bin/neo-go node --mainnet +``` + +#### Available network flags +- `--mainnet, -m` +- `--privnet, -p` +- `--testnet, -t` + +#### Configuration path + +If you want to use some specific configuration path you have to use `--config-path` flag + +`./bin/neo-go node --config-path /user/yourConfigPath` + +## Configuration + +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 + +Those files are automatically loaded, corresponding the provided `netmode` flag. +Example of such configuration: +```yaml +ProtocolConfiguration: + Magic: 56753 + AddressVersion: 23 + 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 + SystemFee: + EnrollmentTransaction: 1000 + IssueTransaction: 500 + PublishTransaction: 500 + RegisterTransaction: 10000 + +ApplicationConfiguration: + DataDirectoryPath: "./chains/privnet" + RPCPort: 20332 + NodePort: 20333 + Relay: true + DialTimeout: 3 + ProtoTickInterval: 2 + MaxPeers: 50 +``` +#### Node debug mode + +There is a debug mode available by additional flag: `--debug, -d` + +## 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] +``` + +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 + +``` +./bin/neo-go contract compile -i mycontract.go +``` + +By default the output filename will be the name of your `.go` file with the `.avm` 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: + +``` +./bin/neo-go contract compile -i mycontract.go --out /Users/foo/bar/contract.avm +``` + +### Deploy +//Not implemented yet + +### Invoke +//Implemented in test mode. It means that it won't affect the blockchain + +``` +./bin/neo-go contract testinvoke -i mycontract.avm +``` + +### Debug +You can dump the opcodes generated by the compiler with the following command: + +``` +./bin/neo-go contract inspect -i mycontract.go +``` + +This will result in something like this: + +``` +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 +``` + +In depth documentation about the **neo-go** compiler and smart contract examples can be found inside +the [compiler package](https://github.com/nspcc-dev/neo-go/tree/master/pkg/vm/compiler). + +## VM run +To run VM use + +``` +./bin/neo-go vm +``` + +For the detailed help use `help` in VM console. +There is a small subset of commands: + +- `loadgo` -- loads smart contract `NEO-GO-VM > loadgo TestContract/main.go` +- `ops` -- show the opcodes of currently loaded contract +- `run` -- executes currently loaded contract + +More details can be found in + [vm package]([compiler package](https://github.com/nspcc-dev/neo-go/tree/master/pkg/vm/compiler)) +## Wallet operations + +- `./bin/neo-go wallet create -p newWallet` to create new wallet in the path `newWallet` +- `./bin/neo-go wallet open -p newWallet` to open created wallet in the path `newWallet` +- `./bin/neo-go wallet create -p newWallet -a` to create new account \ No newline at end of file