diff --git a/Makefile b/Makefile index 1855c41a6..06261b346 100644 --- a/Makefile +++ b/Makefile @@ -19,7 +19,7 @@ IMAGE_REPO=nspccdev/neo-go # All of the targets are phony here because we don't really use make dependency # tracking for files .PHONY: build deps image image-latest image-push image-push-latest check-version clean-cluster push-tag \ - run run-cluster test vet lint fmt cover + test vet lint fmt cover build: deps @echo "=> Building binary" @@ -77,9 +77,6 @@ push-tag: git tag ${VERSION} git push origin ${VERSION} -run: build - ${BINARY} node -config-path ./config -${NETMODE} - test: @go test ./... -cover diff --git a/README.md b/README.md index 808a97a40..f2a978e42 100644 --- a/README.md +++ b/README.md @@ -36,60 +36,38 @@ Neo 3 code (0.90.0 being compatible with Neo 3 preview2). ## Installation -Go: 1.14+ - -Install dependencies. - -`neo-go` uses [GoModules](https://github.com/golang/go/wiki/Modules) as dependency manager: - -``` -make deps -``` - -## How to setup a node - -### Docker - -Each tagged build is published to docker hub and the `:latest` tag pointing at the latest tagged master build. - -By default the `CMD` is set to run a node on `privnet`, so to do this simply run: - -```bash -docker run -d --name neo-go -p 20332:20332 -p 20331:20331 nspccdev/neo-go -``` - -Which will start a node on `privnet` and expose the nodes port `20332` and `20331` for the `JSON-RPC` server. - +NeoGo is distributed as a single binary that includes all the functionality +provided (but smart contract compiler requires Go compiler to operate). You +can grab it from [releases +page](https://github.com/nspcc-dev/neo-go/releases), use a Docker image (see +[Docker Hub](https://hub.docker.com/r/nspccdev/neo-go) for various releases of +NeoGo, `:latest` points to the latest release) or build yourself. ### Building -Build the **neo-go** CLI: +To build NeoGo you need Go 1.14+ and `make`: ``` make build ``` -### Running +The resulting binary is `bin/neo-go`. -Quick start a NEO node on the private network. -To build and run the private network image locally, use: -``` -make env_image -make env_up -``` +## Running a node -To start a NEO node on the private network: -``` -make run -``` +A node needs to connect to some network, either local one (usually referred to +as `privnet`) or public (like `mainnet` or `testnet`). Network configuration +is stored in a file and NeoGo allows you to store multiple files in one +directory (`./config` by default) and easily switch between them using network +flags. -To run the binary directly: +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: +Or specify a different network with appropriate flag like this: ``` ./bin/neo-go node --mainnet @@ -100,7 +78,18 @@ Available network flags: - `--privnet, -p` - `--testnet, -t` -#### Importing mainnet/testnet dump files +### Docker + +By default the `CMD` is set to run a node on `privnet`, so to do this simply run: + +```bash +docker run -d --name neo-go -p 20332:20332 -p 20331:20331 nspccdev/neo-go +``` + +Which will start a node on `privnet` and expose node's ports `20332` (P2P +protocol) and `20331` (JSON-RPC server). + +### Importing mainnet/testnet dump files If you want to jump-start your mainnet or testnet node with [chain archives provided by NGD](https://sync.ngd.network/) follow these instructions (when @@ -114,6 +103,10 @@ $ ./bin/neo-go db restore -m -i chain.acc # for testnet use '-t' flag instead of The process differs from the C# node in that block importing is a separate mode, after it ends the node can be started normally. +## Running a private network + +Refer to [consensus node documentation](docs/consensus.md). + ## Smart contract development Please refer to [neo-go smart contract development @@ -123,6 +116,17 @@ and private network. For details on how Go code is translated to Neo VM bytecode and what you can and can not do in smart contract please refer to the [compiler documentation](docs/compiler.md). +## Wallets + +NeoGo differs substantially from C# implementation in its approach to +wallets. NeoGo wallet is just a +[NEP-6](https://github.com/neo-project/proposals/blob/68398d28b6932b8dd2b377d5d51bca7b0442f532/nep-6.mediawiki) +file that is used by CLI commands to sign various things. There is no database +behind it, the blockchain is the database and CLI commands use RPC to query +data from it. At the same time it's not required to open the wallet on RPC +node to perform various actions (unless your node is providing some service +for the network like consensus or oracle nodes). + # Developer notes Nodes have such features as [Prometheus](https://prometheus.io/docs/guides/go-application) and [Pprof](https://golang.org/pkg/net/http/pprof/) in order to have additional information about them for debugging. diff --git a/config/protocol.testnet.yml b/config/protocol.testnet.yml index 1668e7c93..bbe525884 100644 --- a/config/protocol.testnet.yml +++ b/config/protocol.testnet.yml @@ -1,5 +1,5 @@ ProtocolConfiguration: - Magic: 894448462 + Magic: 1951352142 MaxTraceableBlocks: 2102400 SecondsPerBlock: 15 MemPoolSize: 50000 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). diff --git a/docs/consensus.md b/docs/consensus.md index 65e846396..3acd17cb3 100644 --- a/docs/consensus.md +++ b/docs/consensus.md @@ -6,33 +6,32 @@ It uses pure Go dBFT implementation from [nspcc-dev/dbft](https://github.com/nsp ## How to start your own privnet with neo-go nodes ### Using existing Dockerfile -neo-go comes with a preconfigured private network setup that consists of four -consensus nodes and 6000 blocks to make it more usable out of the box. Nodes -are packed into Docker containers with one shared volume for chain data (they -don't share actual DB, each node has its own DB in this volume). They use ports -20333-20336 for P2P communication and ports 30333-30336 for RPC (Prometheus -monitoring is also available at ports 20001-20004). +neo-go comes with two preconfigured private network setups, the first one has +four consensus nodes and the second one uses single node. Nodes are packed +into Docker containers and four-node setup shares a volume for chain data. -On the first container start they import 6K of blocks from a file, these -blocks contain several transactions that transfer all NEO into one address and -claim some GAS for it. NEO/GAS owner is: - * address: AK2nJJpJr6o664CWJKi1QRXjqeic2zRp8y - * wif: KxDgvEKzgSBPPfuVfw67oPQBSjidEiqTHURKSDL1R7yGaGYAeYnr +Four-node setup uses ports 20333-20336 for P2P communication and ports +30333-30336 for RPC (Prometheus monitoring is also available at ports +20001-20004). Single-node is on ports 20333/30333/20001 for +P2P/RPC/Prometheus. -and you can use it to make some transactions of your own on this privnet. +NeoGo default privnet configuration is made to work with four node consensus, +you have to modify it if you're to use single consensus node. -Basically, this setup is closely resembling the one `neo-local` had for C# nodes -before the switch to single-node mode. +Node wallets are located in the `.docker/wallets` directory where +`wallet1_solo.json` is used for single-node setup and all the other ones for +four-node setup. #### Prerequisites - `docker` - `docker-compose` - `go` compiler + #### Instructions You can use existing docker-compose file located in `.docker/docker-compose.yml`: ```bash make env_image # build image -make env_up # start containers +make env_up # start containers, use "make env_single" for single CN ``` To monitor logs: ```bash diff --git a/docs/rpc.md b/docs/rpc.md index 51e070d0a..23fffb6ec 100644 --- a/docs/rpc.md +++ b/docs/rpc.md @@ -41,31 +41,37 @@ which would yield the response: | `getblockhash` | | `getblockheader` | | `getblockheadercount` | -| `getblocksysfee` | +| `getcommittee` | | `getconnectioncount` | | `getcontractstate` | +| `getnativecontracts` | | `getnep17balances` | | `getnep17transfers` | +| `getnextblockvalidators` | | `getpeers` | +| `getproof` | | `getrawmempool` | | `getrawtransaction` | +| `getstateheight` | +| `getstateroot` | | `getstorage` | | `gettransactionheight` | | `getunclaimedgas` | -| `getvalidators` | | `getversion` | -| `invoke` | +| `invokecontractverify` | | `invokefunction` | | `invokescript` | | `sendrawtransaction` | | `submitblock` | +| `submitoracleresponse` | | `validateaddress` | +| `verifyproof` | #### Implementation notices -##### `invokefunction` and `invoke` +##### `invokefunction` -neo-go's implementation of `invokefunction` and `invoke` does not return `tx` +neo-go's implementation of `invokefunction` does not return `tx` field in the answer because that requires signing the transaction with some key in the server which doesn't fit the model of our node-client interactions. Lacking this signature the transaction is almost useless, so there is no point @@ -97,23 +103,35 @@ and we're not accepting issues related to them. | Method | Reason | | ------- | ------------| -| `claimgas` | Doesn't fit neo-go wallet model, use CLI to do that | -| `dumpprivkey` | Shouldn't exist for security reasons, see `claimgas` comment also | -| `getbalance` | To be implemented | -| `getmetricblocktimestamp` | Not really useful, use other means for node monitoring | -| `getnewaddress` | See `claimgas` comment | -| `getwalletheight` | Not applicable to neo-go, see `claimgas` comment | -| `importprivkey` | Not applicable to neo-go, see `claimgas` comment | -| `listaddress` | Not applicable to neo-go, see `claimgas` comment | +| `closewallet` | Doesn't fit neo-go wallet model | +| `dumpprivkey` | Shouldn't exist for security reasons, see `closewallet` comment also | +| `getnewaddress` | See `closewallet` comment, use CLI to do that | +| `getwalletbalance` | See `closewallet` comment, use `getnep17balances` for that | +| `getwalletunclaimedgas` | See `closewallet` comment, use `getunclaimedgas` for that | +| `importprivkey` | Not applicable to neo-go, see `closewallet` comment | +| `listaddress` | Not applicable to neo-go, see `closewallet` comment | | `listplugins` | neo-go doesn't have any plugins, so it makes no sense | -| `sendfrom` | Not applicable to neo-go, see `claimgas` comment | -| `sendmany` | Not applicable to neo-go, see `claimgas` comment | +| `openwallet` | Doesn't fit neo-go wallet model | +| `sendfrom` | Not applicable to neo-go, see `openwallet` comment | +| `sendmany` | Not applicable to neo-go, see `openwallet` comment | | `sendtoaddress` | Not applicable to neo-go, see `claimgas` comment | ### Extensions Some additional extensions are implemented as a part of this RPC server. +#### `getblocksysfee` call + +This method returns cumulative system fee for all transactions included in a +block. It can be removed in future versions, but at the moment you can use it +to see how much GAS is burned with particular block (because system fees are +burned). + +#### `submitnotaryrequest` call + +This method can be used on P2P Notary enabled networks to submit new notary +payloads to be relayed from RPC to P2P. + #### Limits and paging for getnep17transfers `getnep17transfers` RPC call never returns more than 1000 results for one diff --git a/pkg/compiler/doc.go b/pkg/compiler/doc.go new file mode 100644 index 000000000..6d5842f04 --- /dev/null +++ b/pkg/compiler/doc.go @@ -0,0 +1,4 @@ +/* +Package compiler implements Go to NEF smart contract compiler. +*/ +package compiler diff --git a/pkg/compiler/native_test.go b/pkg/compiler/native_test.go index 8d8771f55..644d9bace 100644 --- a/pkg/compiler/native_test.go +++ b/pkg/compiler/native_test.go @@ -71,6 +71,7 @@ func TestContractParameterTypes(t *testing.T) { func TestRoleManagementRole(t *testing.T) { require.EqualValues(t, native.RoleOracle, roles.Oracle) require.EqualValues(t, native.RoleStateValidator, roles.StateValidator) + require.EqualValues(t, native.RoleNeoFSAlphabet, roles.NeoFSAlphabet) require.EqualValues(t, native.RoleP2PNotary, roles.P2PNotary) } diff --git a/pkg/config/doc.go b/pkg/config/doc.go new file mode 100644 index 000000000..645279cdf --- /dev/null +++ b/pkg/config/doc.go @@ -0,0 +1,4 @@ +/* +Package config contains NeoGo node configuration definition. +*/ +package config diff --git a/pkg/config/netmode/doc.go b/pkg/config/netmode/doc.go new file mode 100644 index 000000000..54c3d609d --- /dev/null +++ b/pkg/config/netmode/doc.go @@ -0,0 +1,4 @@ +/* +Package netmode contains well-known network magic numbers. +*/ +package netmode diff --git a/pkg/config/netmode/netmode.go b/pkg/config/netmode/netmode.go index 226d6ebc2..5b77244a4 100644 --- a/pkg/config/netmode/netmode.go +++ b/pkg/config/netmode/netmode.go @@ -6,7 +6,7 @@ const ( // MainNet contains magic code used in the NEO main official network. MainNet Magic = 0x004f454e // 5195086 // TestNet contains magic code used in the NEO testing network. - TestNet Magic = 0x3550334E // 894448462 + TestNet Magic = 0x744f454e // 1951352142 // PrivNet contains magic code usually used for NEO private networks. PrivNet Magic = 56753 // docker privnet // UnitTestNet is a stub magic code used for testing purposes. diff --git a/pkg/consensus/doc.go b/pkg/consensus/doc.go new file mode 100644 index 000000000..6eaa2f4f1 --- /dev/null +++ b/pkg/consensus/doc.go @@ -0,0 +1,7 @@ +/* +Package consensus contains Neo consensus node implementation. + +It uses external dBFT library for the core algorithm and basically joins this +library with Neo node internals implemented in NeoGo. +*/ +package consensus diff --git a/pkg/core/block/doc.go b/pkg/core/block/doc.go new file mode 100644 index 000000000..c69918fb5 --- /dev/null +++ b/pkg/core/block/doc.go @@ -0,0 +1,6 @@ +/* +Package block contains Neo block definition. + +This is one of the core structures of Neo blockchain. +*/ +package block diff --git a/pkg/core/interop/doc.go b/pkg/core/interop/doc.go new file mode 100644 index 000000000..0d080ddb6 --- /dev/null +++ b/pkg/core/interop/doc.go @@ -0,0 +1,7 @@ +/* +Package interop contains implementations of Neo interop functions. + +This is not the package you use from smart contracts, refer to pkg/interop +for that. +*/ +package interop diff --git a/pkg/core/native/doc.go b/pkg/core/native/doc.go new file mode 100644 index 000000000..72fe6a758 --- /dev/null +++ b/pkg/core/native/doc.go @@ -0,0 +1,4 @@ +/* +Package native contains Neo native contracts. +*/ +package native diff --git a/pkg/core/transaction/doc.go b/pkg/core/transaction/doc.go new file mode 100644 index 000000000..41daa0dd8 --- /dev/null +++ b/pkg/core/transaction/doc.go @@ -0,0 +1,6 @@ +/* +Package transaction contains Neo transaction definition. + +This is one of the core structures of Neo blockchain. +*/ +package transaction diff --git a/pkg/crypto/doc.go b/pkg/crypto/doc.go new file mode 100644 index 000000000..ca41a956d --- /dev/null +++ b/pkg/crypto/doc.go @@ -0,0 +1,6 @@ +/* +Package crypto contains implementation of crypto functions used by Neo. + +This package itself just has some useful interfaces. +*/ +package crypto diff --git a/pkg/crypto/hash/doc.go b/pkg/crypto/hash/doc.go new file mode 100644 index 000000000..198b4f523 --- /dev/null +++ b/pkg/crypto/hash/doc.go @@ -0,0 +1,6 @@ +/* +Package hash contains wrappers for Neo hashing algorithms. + +It also implements Merkle tree. +*/ +package hash diff --git a/pkg/crypto/keys/doc.go b/pkg/crypto/keys/doc.go new file mode 100644 index 000000000..9239e185b --- /dev/null +++ b/pkg/crypto/keys/doc.go @@ -0,0 +1,4 @@ +/* +Package keys wraps public/private keys and implements NEP-2 and WIF. +*/ +package keys diff --git a/pkg/encoding/address/doc.go b/pkg/encoding/address/doc.go new file mode 100644 index 000000000..8ce8c7c9a --- /dev/null +++ b/pkg/encoding/address/doc.go @@ -0,0 +1,4 @@ +/* +Package address implements conversion of script hash to/from Neo address. +*/ +package address diff --git a/pkg/encoding/bigint/doc.go b/pkg/encoding/bigint/doc.go new file mode 100644 index 000000000..3e2c1d4a6 --- /dev/null +++ b/pkg/encoding/bigint/doc.go @@ -0,0 +1,4 @@ +/* +Package bigint implements Neo-specific big.Int (de)serialization to/from []byte. +*/ +package bigint diff --git a/pkg/encoding/fixedn/doc.go b/pkg/encoding/fixedn/doc.go new file mode 100644 index 000000000..dc053fbdd --- /dev/null +++ b/pkg/encoding/fixedn/doc.go @@ -0,0 +1,4 @@ +/* +Package fixedn implements fixed point integers with arbitrary precision. +*/ +package fixedn diff --git a/pkg/interop/math/math.go b/pkg/interop/math/math.go index 6097bae1c..851e318a4 100644 --- a/pkg/interop/math/math.go +++ b/pkg/interop/math/math.go @@ -1,3 +1,6 @@ +/* +Package math provides access to useful numeric functions available in Neo VM. +*/ package math import "github.com/nspcc-dev/neo-go/pkg/interop/neogointernal" diff --git a/pkg/interop/native/crypto/crypto.go b/pkg/interop/native/crypto/crypto.go index 32684d551..1a2c8709f 100644 --- a/pkg/interop/native/crypto/crypto.go +++ b/pkg/interop/native/crypto/crypto.go @@ -1,3 +1,7 @@ +/* +Package crypto provides interface to CryptoLib native contract. +It implements some cryptographic functions. +*/ package crypto import ( diff --git a/pkg/interop/native/gas/gas.go b/pkg/interop/native/gas/gas.go index e93941429..1d0cc9329 100644 --- a/pkg/interop/native/gas/gas.go +++ b/pkg/interop/native/gas/gas.go @@ -1,3 +1,7 @@ +/* +Package gas provides interface to GasToken native contract. +It implements regular NEP-17 functions for GAS token. +*/ package gas import ( diff --git a/pkg/interop/native/ledger/ledger.go b/pkg/interop/native/ledger/ledger.go index 1f3a124ba..028eb6e59 100644 --- a/pkg/interop/native/ledger/ledger.go +++ b/pkg/interop/native/ledger/ledger.go @@ -1,3 +1,7 @@ +/* +Package ledger provides interface to LedgerContract native contract. +It allows to access ledger contents like transactions and blocks. +*/ package ledger import ( diff --git a/pkg/interop/native/management/management.go b/pkg/interop/native/management/management.go index d65e9a1fe..97c109391 100644 --- a/pkg/interop/native/management/management.go +++ b/pkg/interop/native/management/management.go @@ -1,3 +1,7 @@ +/* +Package management provides interface to ContractManagement native contract. +It allows to get/deploy/update contracts as well as get/set deployment fee. +*/ package management import ( diff --git a/pkg/interop/native/nameservice/name_service.go b/pkg/interop/native/nameservice/name_service.go index ebb24fd26..065f6d747 100644 --- a/pkg/interop/native/nameservice/name_service.go +++ b/pkg/interop/native/nameservice/name_service.go @@ -1,3 +1,7 @@ +/* +Package nameservice provides interface to NameService native contract. +It's a NEP-11 contract implementing a domain name service. +*/ package nameservice import ( diff --git a/pkg/interop/native/neo/neo.go b/pkg/interop/native/neo/neo.go index 8144986f3..b72a16404 100644 --- a/pkg/interop/native/neo/neo.go +++ b/pkg/interop/native/neo/neo.go @@ -1,3 +1,9 @@ +/* +Package neo provides interface to NeoToken native contract. +NEO token is special, it's not just a regular NEP-17 contract, it also +provides access to chain-specific settings and implements commmittee +voting system. +*/ package neo import ( diff --git a/pkg/interop/native/notary/notary.go b/pkg/interop/native/notary/notary.go index ed83dff4d..67c2861d7 100644 --- a/pkg/interop/native/notary/notary.go +++ b/pkg/interop/native/notary/notary.go @@ -1,3 +1,8 @@ +/* +Package notary provides interface to Notary native contract. +This contract is a NeoGo extension and is not available on regular Neo +networks. To use it you need to have this extension enabled on the network. +*/ package notary import ( diff --git a/pkg/interop/native/oracle/oracle.go b/pkg/interop/native/oracle/oracle.go index edb6534de..44329d354 100644 --- a/pkg/interop/native/oracle/oracle.go +++ b/pkg/interop/native/oracle/oracle.go @@ -1,3 +1,8 @@ +/* +Package oracle provides interface to OracleContract native contract. +Oracles allow you to get external (non-blockchain) data using HTTPS or NeoFS +protocols. +*/ package oracle import ( diff --git a/pkg/interop/native/policy/policy.go b/pkg/interop/native/policy/policy.go index 4acfc97ad..37272f81d 100644 --- a/pkg/interop/native/policy/policy.go +++ b/pkg/interop/native/policy/policy.go @@ -1,3 +1,7 @@ +/* +Package policy provides interface to PolicyContract native contract. +This contract holds various network-wide settings. +*/ package policy import ( diff --git a/pkg/interop/native/roles/roles.go b/pkg/interop/native/roles/roles.go index b095466fc..a8c22b1ae 100644 --- a/pkg/interop/native/roles/roles.go +++ b/pkg/interop/native/roles/roles.go @@ -1,3 +1,8 @@ +/* +Package roles provides interface to RoleManagement native contract. +Role management contract is used by committee to designate some nodes as +providing some service on the network. +*/ package roles import ( @@ -15,7 +20,9 @@ type Role byte const ( StateValidator Role = 4 Oracle Role = 8 - P2PNotary Role = 128 + NeoFSAlphabet Role = 16 + // P2PNotary is an extension of Neo protocol available on specifically configured NeoGo networks. + P2PNotary Role = 128 ) // GetDesignatedByRole represents `getDesignatedByRole` method of RoleManagement native contract. diff --git a/pkg/interop/native/std/std.go b/pkg/interop/native/std/std.go index 3fcc5332a..fa5f4dadc 100644 --- a/pkg/interop/native/std/std.go +++ b/pkg/interop/native/std/std.go @@ -1,3 +1,7 @@ +/* +Package std provides interface to StdLib native contract. +It implements various useful conversion functions. +*/ package std import ( diff --git a/pkg/interop/neogointernal/doc.go b/pkg/interop/neogointernal/doc.go new file mode 100644 index 000000000..11e1b5025 --- /dev/null +++ b/pkg/interop/neogointernal/doc.go @@ -0,0 +1,5 @@ +/* +Package neogointernal contains definitions of compiler intrinsics. +It's not intended to be used directly by smart contracts. +*/ +package neogointernal