TrueCloudLab/neo-go
8
0
Fork 0
mirror of https://github.com/nspcc-dev/neo-go.git synced 2024-12-23 03:41:34 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs: refactor documentation

Browse source 
CLI:
* Typos are fixed
* Documentation on NEP-11 tokens is added
* NeoGo node configuration is moved to a separate file

Compiler:
* Typos and indentations are fixed
* Ops dump example is updated

Consensus:
* Typos are fixed
* Links are fixed

Notifications:
* Minor adjustments

RPC:
* `getversion` response is updated
* `getunclamedgas` comment is removed (not valid since
https://github.com/neo-project/neo-modules/pull/243)

VM:
* Update help message
* `load*` command adjustments
* `astack` command removal
This commit is contained in:
Anna Shaleva 2021-09-06 18:40:41 +03:00
parent 7371593bdc
commit cbc75afd4d
10 changed files with 465 additions and 343 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
cli/wallet/nep11.go
View file

@ -114,7 +114,7 @@ func newNEP11Commands() []cli.Command {
}, },
{ {
Name: "tokensOf", Name: "tokensOf",
Usage: "print list of tokens IDs for the specified divisible NFT owner", Usage: "print list of tokens IDs for the specified NFT owner",
UsageText: "tokensOf --rpc-endpoint <node> --timeout <time> --token <hash> --address <addr>", UsageText: "tokensOf --rpc-endpoint <node> --timeout <time> --token <hash> --address <addr>",
Action: printNEP11TokensOf, Action: printNEP11TokensOf,
Flags: append([]cli.Flag{ Flags: append([]cli.Flag{

305
docs/cli.md
View file

@ -3,7 +3,7 @@
NeoGo CLI provides all functionality from one binary, so it's used to run 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 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 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 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 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 as a client that connects to this RPC node and does things you want it to do
(like transferring some NEP-17 asset). (like transferring some NEP-17 asset).
@ -35,220 +35,8 @@ If you want to use some non-default configuration directory path, specify
The file loaded is chosen automatically depending on network mode flag. The file loaded is chosen automatically depending on network mode flag.
Each config file contains two sections. `ApplicationConfiguration` describes node-related Refer to the [node configuration documentation](./node-configuration.md) for
settings and `ProtocolConfiguration` contains protocol-related settings. See the detailed configuration file description.
[Application Configuration](#Application-Configuration) and
[Protocol Configuration](#Protocol-Configuration) sections for details on configurable
values.
#### Application Configuration
ApplicationConfiguration section of `yaml` node configuration file contains
node-related settings described in the table below.
| Section | Type | Default value | Description |
| --- | --- | --- | --- |
| Address | `string` | `127.0.0.1` | Node address that P2P protocol handler binds to. |
| AnnouncedPort | `uint16` | Same as the `NodePort` | Node port which should be used to announce node's port on P2P layer, can differ from `NodePort` node is bound to (for example, if your node is behind NAT). |
| AttemptConnPeers | `int` | `20` | Number of connection to try to establish when the connection count drops below the `MinPeers` value.|
| DBConfiguration | [DB Configuration](#DB-Configuration) | | Describes configuration for database. See the [DB Configuration](#DB-Configuration) section for details. |
| DialTimeout | `int64` | `0` | Maximum duration a single dial may take in seconds. |
| ExtensiblePoolSize | `int` | `20` | Maximum amount of the extensible payloads from a single sender stored in a local pool. |
| LogPath | `string` | "", so only console logging | File path where to store node logs. |
| MaxPeers | `int` | `100` | Maximum numbers of peers that can be connected to the server. |
| MinPeers | `int` | `5` | Minimum number of peers for normal operation, when the node has less than this number of peers it tries to connect with some new ones. |
| NodePort | `uint16` | `0`, which is any free port | The actual node port it is bound to. |
| Oracle | [Oracle Configuration](#Oracle-Configuration) | | Oracle module configuration. See the [Oracle Configuration](#Oracle-Configuration) section for details. |
| P2PNotary | [P2P Notary Configuration](#P2P-Notary-Configuration) | | P2P Notary module configuration. See the [P2P Notary Configuration](#P2P-Notary-Configuration) section for details. |
| PingInterval | `int64` | `30` | Interval in seconds used in pinging mechanism for syncing blocks. |
| PingTimeout | `int64` | `90` | Time to wait for pong (response for sent ping request). |
| Pprof | [Metrics Services Configuration](#Metrics-Services-Configuration) | | Configuration for pprof service (profiling statistics gathering). See the [Metrics Services Configuration](#Metrics-Services-Configuration) section for details. |
| Prometheus | [Metrics Services Configuration](#Metrics-Services-Configuration) | | Configuration for Prometheus (monitoring system). See the [Metrics Services Configuration](#Metrics-Services-Configuration) section for details |
| ProtoTickInterval | `int64` | `5` | Duration in seconds between protocol ticks with each connected peer. |
| Relay | `bool` | `true` | Determines whether the server is forwarding its inventory. |
| RPC | [RPC Configuration](#RPC-Configuration) | | Describes [RPC subsystem](rpc.md) configuration. See the [RPC Configuration](#RPC-Configuration) for details. |
| StateRoot | [State Root Configuration](#State-Root-Configuration) | | State root module configuration. See the [State Root Configuration](#State-Root-Configuration) section for details. |
| UnlockWallet | [Unlock Wallet Configuration](#Unlock-Wallet-Configuration) | | Node wallet configuration used for consensus (dBFT) operation. See the [Unlock Wallet Configuration](#Unlock-Wallet-Configuration) section for details. |
##### DB Configuration
`DBConfiguration` section describes configuration for node database and has
the following format:
```
DBConfiguration:
Type: leveldb
LevelDBOptions:
DataDirectoryPath: /chains/privnet
RedisDBOptions:
Addr: localhost:6379
Password: ""
DB: 0
BoltDBOptions:
FilePath: ./chains/privnet.bolt
BadgerDBOptions:
BadgerDir: ./chains/privnet.badger
```
where:
- `Type` is the database type (string value). Supported types: `levelDB`,
`redisDB`, `boltDB`, `badgerDB`.
- `LevelDBOptions` are settings for LevelDB.
- `RedisDBOptions` are options for RedisDB.
- `BoltDBOptions` configures BoltDB.
- `BadgerDBOptions` are options for BadgerDB.
Only options for the specified database type will be used.
##### Oracle Configuration
`Oracle` configuration section describes configuration for Oracle node module
and has the following structure:
```
Oracle:
Enabled: false
AllowPrivateHost: false
MaxTaskTimeout: 3600s
MaxConcurrentRequests: 10
Nodes: ["172.200.0.1:30333", "172.200.0.2:30334"]
NeoFS:
Nodes: ["172.200.0.1:30335", "172.200.0.2:30336"]
Timeout: 2
RefreshInterval: 180s
RequestTimeout: 5s
ResponseTimeout: 5s
UnlockWallet:
Path: "./oracle_wallet.json"
Password: "pass"
```
Please, refer to the [Oracle module documentation](./oracle.md#Configuration) for
details on configurable values.
##### P2P Notary Configuration
`P2PNotary` configuration section describes configuration for P2P Notary node
module and has the following structure:
```
P2PNotary:
Enabled: false
UnlockWallet:
Path: "/notary_wallet.json"
Password: "pass"
```
where:
- `Enabled` denotes whether P2P Notary module is active.
- `UnlockWallet` is a Notary node wallet configuration, see the
[Unlock Wallet Configuration](#Unlock-Wallet-Configuration) section for
structure details.
Please, refer to the [Notary module documentation](./notary.md#NeoGo-Notary-service) for
details on module features.
##### Metrics Services Configuration
Metrics services configuration describes options for metrics services (pprof,
Prometheus) and has the following structure:
```
Pprof:
Enabled: false
Address: ""
Port: "30001"
Prometheus:
Enabled: false
Address: ""
Port: "40001"
```
where:
- `Enabled` denotes whether the service is enabled.
- `Address` is a service address to be running at.
- `Port` is a service port to be bound to.
##### RPC Configuration
`RPC` configuration section describes settings for the RPC server and has
the following structure:
```
RPC:
Enabled: true
Address: ""
EnableCORSWorkaround: false
MaxGasInvoke: 50
Port: 10332
TLSConfig:
Address: ""
CertFile: serv.crt
Enabled: true
Port: 10331
KeyFile: serv.key
```
where:
- `Enabled` denotes whether RPC server should be started.
- `Address` is an RPC server address to be running at.
- `EnableCORSWorkaround` enables Cross-Origin Resource Sharing and is useful if
you're accessing RPC interface from the browser.
- `MaxGasInvoke` is the maximum GAS allowed to spend during `invokefunction` and
`invokescript` RPC-calls.
- `Port` is an RPC server port it should be bound to.
- `TLS` section configures TLS protocol.
##### State Root Configuration
`StateRoot` configuration section contains settings for state roots exchange and has
the following structure:
```
StateRoot:
Enabled: false
UnlockWallet:
Path: "./wallet.json"
Password: "pass"
```
where:
- `Enabled` enables state root module.
- `UnlockWallet` contains wallet settings, see
[Unlock Wallet Configuration](#Unlock-Wallet-Configuration) section for
structure details.
##### Unlock Wallet Configuration
`UnlockWallet` configuration section contains wallet settings and has the following
structure:
```
UnlockWallet:
Path: "./wallet.json"
Password: "pass"
```
where:
- `Path` is a path to wallet.
- `Password` is a wallet password.
#### Protocol configuration
ProtocolConfiguration section of `yaml` node configuration file contains
protocol-related settings described in the table below.
| Section | Type | Default value | Description | Notes |
| --- | --- | --- | --- | --- |
| KeepOnlyLatestState | `bool` | `false` | Specifies if MPT should only store latest state. If true, DB size will be smaller, but older roots won't be accessible. This value should remain the same for the same database. |
| Magic | `uint32` | `0` | Magic number which uniquely identifies NEO network. |
| MaxBlockSize | `uint32` | `262144` | Maximum block size in bytes. |
| MaxBlockSystemFee | `int64` | `900000000000` | Maximum overall transactions system fee per block. |
| MaxTraceableBlocks | `uint32` | `2102400` | Length of the chain accessible to smart contracts. | `RemoveUntraceableBlocks` should be enabled to use this setting. |
| MaxTransactionsPerBlock | `uint16` | `512` | Maximum number of transactions per block. |
| MemPoolSize | `int` | `50000` | Size of the node's memory pool where transactions are stored before they are added to block. |
| NativeActivations | `map[string][]uint32` | ContractManagement: [0]<br>StdLib: [0]<br>CryptoLib: [0]<br>LedgerContract: [0]<br>NeoToken: [0]<br>GasToken: [0]<br>PolicyContract: [0]<br>RoleManagement: [0]<br>OracleContract: [0] | The list of histories of native contracts updates. Each list item shod be presented as a known native contract name with the corresponding list of chain's heights. The contract is not active until chain reaches the first height value specified in the list. | `Notary` is supported. |
| P2PNotaryRequestPayloadPoolSize | `int` | `1000` | Size of the node's P2P Notary request payloads memory pool where P2P Notary requests are stored before main or fallback transaction is completed and added to the chain.<br>This option is valid only if `P2PSigExtensions` are enabled. | Not supported by the C# node, thus may affect heterogeneous networks functionality. |
| P2PSigExtensions | `bool` | `false` | Enables following additional Notary service related logic:<br>• Transaction attributes `NotValidBefore`, `Conflicts` and `NotaryAssisted`<br>• Network payload of the `P2PNotaryRequest` type<br>• Native `Notary` contract<br>• Notary node module | Not supported by the C# node, thus may affect heterogeneous networks functionality. |
| P2PStateExchangeExtensions | `bool` | `false` | Enables following P2P MPT state data exchange logic: <br>• `StateSyncInterval` protocol setting <br>• P2P commands `GetMPTDataCMD` and `MPTDataCMD` | Not supported by the C# node, thus may affect heterogeneous networks functionality. |
| RemoveUntraceableBlocks | `bool`| `false` | Denotes whether old blocks should be removed from cache and database. If enabled, then only last `MaxTraceableBlocks` are stored and accessible to smart contracts. |
| ReservedAttributes | `bool` | `false` | Allows to have reserved attributes range for experimental or private purposes. |
| SaveStorageBatch | `bool` | `false` | Enables storage batch saving before every persist. It is similar to StorageDump plugin for C# node. |
| SecondsPerBlock | `int` | `15` | Minimal time that should pass before next block is accepted. |
| SeedList | `[]string` | [] | List of initial nodes addresses used to establish connectivity. |
| StandbyCommittee | `[]string` | [] | List of public keys of standby committee validators are chosen from. |
| StateRootInHeader | `bool` | `false` | Enables storing state root in block header. | Experimental protocol extension! |
| StateSyncInterval | `int` | `40000` | The number of blocks between state heights available for MPT state data synchronization. | `P2PStateExchangeExtensions` should be enabled to use this setting. |
| ValidatorsCount | `int` | `0` | Number of validators. |
| VerifyBlocks | `bool` | `false` | Denotes whether to verify received blocks. |
| VerifyTransactions | `bool` | `false` | Denotes whether to verify transactions in received blocks. |
### Starting a node ### Starting a node
@ -264,12 +52,12 @@ Or specify a different network with appropriate flag like this:
./bin/neo-go node --mainnet ./bin/neo-go node --mainnet
``` ```
By default the node will run in foreground using current standard output for By default, the node will run in foreground using current standard output for
logging. logging.
### Restarting node services ### Restarting node services
To restart some of the node services without full node restart, send the SIGHUP To restart some node services without full node restart, send the SIGHUP
signal. List of the services to be restarted on SIGHUP receiving: signal. List of the services to be restarted on SIGHUP receiving:
| Service | Action | | Service | Action |
@ -469,6 +257,11 @@ 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 ./bin/neo-go wallet candidate vote -a NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E -w wallet.json -r http://localhost:20332 -c 03cecd63d7d8120c3b194c3b2880dd4aafe1475c57e40c852872d7305615258140
``` ```
Do not provide candidate argument to perform unvoting:
```
./bin/neo-go wallet candidate vote -a NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E -w wallet.json -r http://localhost:20332
```
### Getting data from chain ### Getting data from chain
#### Node height/validated height #### Node height/validated height
@ -583,7 +376,7 @@ Getting balance is easy:
./bin/neo-go wallet nep17 balance -w /etc/neo-go/wallet.json -r http://localhost:20332 ./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 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 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) with `--token` flag (token hash or name can be used as parameter)
@ -602,6 +395,10 @@ 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 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. sending it to the network if it needs to be signed by multiple parties.
To add optional `data` transfer parameter specify `data` positional argument
after all required flags. Refer to `wallet nep17 transfer --help` command
description for details.
One `transfer` invocation creates one transaction, but in case you need to do 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 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 one transaction by using `wallet nep17 multitransfer` command. It can transfer
@ -622,6 +419,78 @@ 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 transaction that transfers all of your NEO to yourself thereby triggering GAS
distribution. distribution.
### NEP-11 token functions
`wallet nep11` contains a set of commands to use for NEP-11 tokens. Token
metadata related commands (`info`, `import` and `remove`) works the same way as
for NEP-17 tokens. The syntax of other commands is very similar to NEP-17
commands with the following adjustments.
#### Balance
Specify token ID via `--id` flag to call divisible NEP-11 `balanceOf` method:
```
./bin/neo-go wallet nep11 balance -w /etc/neo-go/wallet.json --token 67ecb7766dba4acf7c877392207984d1b4d15731 --id R5OREI5BU+Uyd23/MuV/xzI3F+Q= -r http://localhost:20332
```
By default, no token ID specified, i.e. common `balanceOf` method is called.
#### Transfers
Specify token ID via `--id` flag to transfer NEP-11 token. Specify amount to
transfer divisible NEP-11 token:
```
./bin/neo-go wallet nep11 transfer -w wallet.nep6 -r http://localhost:20332 --to NjEQfanGEXihz85eTnacQuhqhNnA6LxpLp --from NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E --token 67ecb7766dba4acf7c877392207984d1b4d15731 --id R5OREI5BU+Uyd23/MuV/xzI3F+Q= --amount 5
```
By default, no amount is specified, i.e. the whole token is transferred for
non-divisible tokens and 100% of the token is transferred if there is only one
owner of this token for divisible tokens.
Unlike NEP-17 tokens functionality, `multitransfer` command currently not
supported on NEP-11 tokens.
#### Tokens Of
To print token IDs owned by the specified owner, use `tokensOf` command with
`--token` and `--address` flags:
```
./bin/neo-go wallet nep11 tokensOf -r http://localhost:20332 --token 67ecb7766dba4acf7c877392207984d1b4d15731 --address NbrUYaZgyhSkNoRo9ugRyEMdUZxrhkNaWB
```
#### Owner Of
For non-divisible NEP-11 tokens only. To print owner of non-divisible NEP11 token
use `ownerOf` method, specify token hash via `--token` flag and token ID via
`--id` flag:
```
./bin/neo-go wallet nep11 ownerOf -r http://localhost:20332 --token 67ecb7766dba4acf7c877392207984d1b4d15731 --id R5OREI5BU+Uyd23/MuV/xzI3F+Q=
```
#### Optional methods
##### 1. Properties
If NEP-11 token supports optional `properties` method, specify token hash via
`--token` flag and token ID via `--id` flag to print properties:
```
./bin/neo-go wallet nep11 properties -r http://localhost:20332 --token 67ecb7766dba4acf7c877392207984d1b4d15731 --id 7V5gjT2WwjP3pBCQMKGMfyZsp/w=
```
##### 2. Tokens
If NEP-11 token supports optional `tokens` method, specify token hash via
`--token` flag to print the list of token IDs minted by the specified NFT:
```
./bin/neo-go wallet nep11 tokens -r http://localhost:20332 --token 67ecb7766dba4acf7c877392207984d1b4d15731
```
## Conversion utility ## Conversion utility
NeoGo provides conversion utility command to reverse data, convert script NeoGo provides conversion utility command to reverse data, convert script

162
docs/compiler.md
View file

@ -1,4 +1,4 @@
# NEO-GO smart contract compiler # NeoGo smart contract compiler
The neo-go compiler compiles Go programs to bytecode that the NEO virtual machine can understand. The neo-go compiler compiles Go programs to bytecode that the NEO virtual machine can understand.
@ -33,11 +33,13 @@ pkg.go.dev](https://pkg.go.dev/github.com/nspcc-dev/neo-go/pkg/interop)
for full API documentation. In general it provides the same level of for full API documentation. In general it provides the same level of
functionality as Neo .net Framework library. functionality as Neo .net Framework library.
Compiler provides some helpful builtins in `util` and `convert` packages. Compiler provides some helpful builtins in `util`, `convert` and `math` packages.
Refer to them for detailed documentation. Refer to them for detailed documentation.
`_deploy()` function has a special meaning and is executed when contract is deployed. `_deploy()` function has a special meaning and is executed when contract is deployed.
It should return no value and accept single bool argument which will be true on contract update. It should return no value and accept two arguments: the first one is `data` containing
all values `deploy` is aware of and able to make use of; the second one is a bool
argument which will be true on contract update.
`_deploy()` functions are called for every imported package in the same order as `init()`. `_deploy()` functions are called for every imported package in the same order as `init()`.
## Quick start ## Quick start
@ -57,13 +59,15 @@ export GOROOT=/usr/lib64/go/1.15
./bin/neo-go contract compile -i contract.go ./bin/neo-go contract compile -i contract.go
``` ```
By default the filename will be the name of your .go file with the .nef extension, the file will be located in the same directory where your Go contract is. If you want another location for your compiled contract: By default, the filename will be the name of your .go file with the .nef
extension, the file will be located in the same directory where your Go contract
is. If you want another location for your compiled contract:
``` ```
./bin/neo-go contract compile -i contract.go --out /Users/foo/bar/contract.nef ./bin/neo-go contract compile -i contract.go --out /Users/foo/bar/contract.nef
``` ```
If you contract is split across multiple files, you must provide a path If your contract is split across multiple files, you must provide a path
to the directory where package files are contained instead of a single Go file to the directory where package files are contained instead of a single Go file
(`out.nef` will be used as the default output file in this case): (`out.nef` will be used as the default output file in this case):
``` ```
@ -80,58 +84,96 @@ You can dump the opcodes generated by the compiler with the following command:
This will result in something like this: This will result in something like this:
``` ```
INDEX OPCODE PARAMETER INDEX OPCODE PARAMETER
0 INITSLOT 0500 ("\x05\x00") << 0 INITSLOT 4 local, 2 arg <<
3 PUSH0 3 LDARG1
4 REVERSEN 4 NOT
5 SYSCALL "\x9a\x1f\x19J" 5 JMPIFNOT_L 151 (146/92000000)
10 NOP 10 SYSCALL System.Storage.GetContext (9bf667ce)
11 STLOC0 15 NOP
12 LDLOC0 16 STLOC0
13 PUSH1 17 PUSHDATA1 53746f72616765206b6579206e6f7420796574207365742e2053657474696e6720746f2030 ("Storage key not yet set. Setting to 0")
14 REVERSEN 56 CONVERT Buffer (30)
15 PUSH1 58 PUSH1
16 PACK 59 PACK
17 SYSCALL "\x05\a\x92\x16" 60 STLOC1
22 NOP 61 PUSHDATA1 696e666f ("info")
23 PUSH0 67 LDLOC1
24 REVERSEN 68 SWAP
25 SYSCALL "E\x99Z\\" 69 SYSCALL System.Runtime.Notify (95016f61)
30 NOP 74 NOP
31 STLOC1 75 PUSH0
32 LDLOC1 76 STLOC2
33 PUSH1 77 LDLOC0
34 REVERSEN 78 PUSHDATA1 746573742d73746f726167652d6b6579 ("test-storage-key")
35 PUSH1 96 LDLOC2
36 PACK 97 REVERSE3
37 SYSCALL "\x05\a\x92\x16" 98 SYSCALL System.Storage.Put (e63f1884)
42 NOP 103 NOP
43 PUSH0 104 PUSHDATA1 53746f72616765206b657920697320696e697469616c69736564 ("Storage key is initialised")
44 REVERSEN 132 CONVERT Buffer (30)
45 SYSCALL "\x87\xc3\xd2d" 134 PUSH1
50 NOP 135 PACK
51 STLOC2 136 STLOC3
52 LDLOC2 137 PUSHDATA1 696e666f ("info")
53 PUSH1 143 LDLOC3
54 REVERSEN 144 SWAP
55 PUSH1 145 SYSCALL System.Runtime.Notify (95016f61)
56 PACK 150 NOP
57 SYSCALL "\x05\a\x92\x16" 151 RET
62 NOP 152 INITSLOT 5 local, 0 arg
63 PUSH0 155 SYSCALL System.Storage.GetContext (9bf667ce)
64 REVERSEN 160 NOP
65 SYSCALL "\x1dY\xe1\x19" 161 STLOC0
70 NOP 162 LDLOC0
71 STLOC3 163 PUSHDATA1 746573742d73746f726167652d6b6579 ("test-storage-key")
72 LDLOC3 181 SWAP
73 PUSH1 182 SYSCALL System.Storage.Get (925de831)
74 REVERSEN 187 NOP
75 PUSH1 188 STLOC1
76 PACK 189 PUSHDATA1 56616c756520726561642066726f6d2073746f72616765 ("Value read from storage")
77 SYSCALL "\x05\a\x92\x16" 214 CONVERT Buffer (30)
82 NOP 216 PUSH1
83 PUSH1 217 PACK
84 RET 218 STLOC2
219 PUSHDATA1 696e666f ("info")
225 LDLOC2
226 SWAP
227 SYSCALL System.Runtime.Notify (95016f61)
232 NOP
233 PUSHDATA1 53746f72616765206b657920616c7265616479207365742e20496e6372656d656e74696e672062792031 ("Storage key already set. Incrementing by 1")
277 CONVERT Buffer (30)
279 PUSH1
280 PACK
281 STLOC3
282 PUSHDATA1 696e666f ("info")
288 LDLOC3
289 SWAP
290 SYSCALL System.Runtime.Notify (95016f61)
295 NOP
296 LDLOC1
297 CONVERT Integer (21)
299 PUSH1
300 ADD
301 STLOC1
302 LDLOC0
303 PUSHDATA1 746573742d73746f726167652d6b6579 ("test-storage-key")
321 LDLOC1
322 REVERSE3
323 SYSCALL System.Storage.Put (e63f1884)
328 NOP
329 PUSHDATA1 4e65772076616c7565207772697474656e20696e746f2073746f72616765 ("New value written into storage")
361 CONVERT Buffer (30)
363 PUSH1
364 PACK
365 STLOC4
366 PUSHDATA1 696e666f ("info")
372 LDLOC4
373 SWAP
374 SYSCALL System.Runtime.Notify (95016f61)
379 NOP
380 LDLOC1
381 RET
``` ```
#### Neo Smart Contract Debugger support #### Neo Smart Contract Debugger support
@ -168,7 +210,7 @@ events:
- name: info - name: info
parameters: parameters:
- name: message - name: message
type: ByteString type: String
``` ```
Then the manifest can be passed to the `deploy` command via `-m` option: Then the manifest can be passed to the `deploy` command via `-m` option:
@ -227,7 +269,7 @@ As an example consider `Transfer` event from `NEP-17` standard:
type: Integer type: Integer
``` ```
By default compiler performs some sanity checks. Most of the time By default, compiler performs some sanity checks. Most of the time
it will report missing events and/or parameter type mismatch. it will report missing events and/or parameter type mismatch.
Using variable as an event name in code isn't prohibited but will prevent Using variable as an event name in code isn't prohibited but will prevent
compiler from analyzing an event. It is better to use either constant or string literal. compiler from analyzing an event. It is better to use either constant or string literal.
@ -316,7 +358,7 @@ mandatory parameter.
Example call (contract `f84d6a337fbc3d3a201d41da99e86b479e7a2554` with method Example call (contract `f84d6a337fbc3d3a201d41da99e86b479e7a2554` with method
`balanceOf` and method's parameter `AK2nJJpJr6o664CWJKi1QRXjqeic2zRp8y` using `balanceOf` and method's parameter `AK2nJJpJr6o664CWJKi1QRXjqeic2zRp8y` using
given RPC server and wallet and paying 0.00001 GAS for this transaction): given RPC server and wallet and paying 0.00001 extra GAS for this transaction):
``` ```
$ ./bin/neo-go contract invokefunction -r http://localhost:20331 -w my_wallet.json -g 0.00001 f84d6a337fbc3d3a201d41da99e86b479e7a2554 balanceOf AK2nJJpJr6o664CWJKi1QRXjqeic2zRp8y $ ./bin/neo-go contract invokefunction -r http://localhost:20331 -w my_wallet.json -g 0.00001 f84d6a337fbc3d3a201d41da99e86b479e7a2554 balanceOf AK2nJJpJr6o664CWJKi1QRXjqeic2zRp8y

9
docs/consensus.md
View file

@ -1,4 +1,4 @@
# NEO-GO consensus node # NeoGo consensus node
NeoGo node can act as a consensus node. A consensus node differs from regular NeoGo node can act as a consensus node. A consensus node differs from regular
one in that it participates in block acceptance process using dBFT one in that it participates in block acceptance process using dBFT
@ -67,8 +67,9 @@ systemd service file to run automatically on system startup.
Notice that the default configuration has RPC and Prometheus services enabled, Notice that the default configuration has RPC and Prometheus services enabled,
you can turn them off for security purposes or restrict access to them with a you can turn them off for security purposes or restrict access to them with a
firewall. Carefuly review all other configuration options to see if they meet firewall. Carefuly review all other configuration options to see if they meet
your expectations. Details on various configuration options (as well as CLI your expectations. Details on various configuration options are provided in the
commands) are provided [here](cli.md). [node configuration documentation](node-configuration.md), CLI commands are
provided in the [CLI documentation](cli.md).
### Registration ### Registration
@ -179,7 +180,7 @@ Examples can be found at `config/protocol.privnet.docker.one.yml` (`two`, `three
the number of nodes participating in consensus. the number of nodes participating in consensus.
This requirement is needed for nodes to correctly This requirement is needed for nodes to correctly
start and can be weakened in future. start and can be weakened in future.
3. Set you `Address`, `Port` and `RPC.Port` to the appropriate values. 3. Set `Address`, `Port` and `RPC.Port` to the appropriate values.
They must differ between nodes. They must differ between nodes.
4. If you start binary from the same directory, you will probably want to change 4. If you start binary from the same directory, you will probably want to change
`DataDirectoryPath` from the `LevelDBOptions`. `DataDirectoryPath` from the `LevelDBOptions`.

18
docs/conventions.md
View file

@ -1,12 +1,15 @@
# Conventions # Conventions
This document will list conventions that this repo should follow. These are guidelines and if you believe that one should not be followed, then please state why in your PR. If you believe that a piece of code does not follow one of the conventions listed, then please open an issue before making any changes. This document will list conventions that this repo should follow. These are
guidelines and if you believe that one should not be followed, then please state
why in your PR. If you believe that a piece of code does not follow one of the
conventions listed, then please open an issue before making any changes.
When submitting a new convention, please open an issue for discussion, if possible please highlight parts in the code where this convention could help the code readiblity or simplicity. When submitting a new convention, please open an issue for discussion, if
possible please highlight parts in the code where this convention could help the
code readability or simplicity.
## Avoid Named return paramters
## Avoid named return parameters
func example(test int) (num int) { func example(test int) (num int) {
a = test + 1 a = test + 1
@ -14,7 +17,10 @@ func example(test int) (num int) {
return return
} }
In the above function we have used a named return paramter, which allows you to include a simple return statement without the variables you are returning. This practice can cause confusion when functions become large or the logic becomes complex, so these should be avoided. In the above function we have used a named return parameter, which allows you to
include a simple return statement without the variables you are returning. This
practice can cause confusion when functions become large or the logic becomes
complex, so these should be avoided.
## Use error wrapping ## Use error wrapping

219
docs/node-configuration.md Normal file
View file

@ -0,0 +1,219 @@
# NeoGo node configuration file
This section contains detailed NeoGo node configuration file description
including default config values and tips to set up configurable values.
Each config file contains two sections. `ApplicationConfiguration` describes node-related
settings and `ProtocolConfiguration` contains protocol-related settings. See the
[Application Configuration](#Application-Configuration) and
[Protocol Configuration](#Protocol-Configuration) sections for details on configurable
values.
## Application Configuration
`ApplicationConfiguration` section of `yaml` node configuration file contains
node-related settings described in the table below.
| Section | Type | Default value | Description |
| --- | --- | --- | --- |
| Address | `string` | `127.0.0.1` | Node address that P2P protocol handler binds to. |
| AnnouncedPort | `uint16` | Same as the `NodePort` | Node port which should be used to announce node's port on P2P layer, can differ from `NodePort` node is bound to (for example, if your node is behind NAT). |
| AttemptConnPeers | `int` | `20` | Number of connection to try to establish when the connection count drops below the `MinPeers` value.|
| DBConfiguration | [DB Configuration](#DB-Configuration) | | Describes configuration for database. See the [DB Configuration](#DB-Configuration) section for details. |
| DialTimeout | `int64` | `0` | Maximum duration a single dial may take in seconds. |
| ExtensiblePoolSize | `int` | `20` | Maximum amount of the extensible payloads from a single sender stored in a local pool. |
| LogPath | `string` | "", so only console logging | File path where to store node logs. |
| MaxPeers | `int` | `100` | Maximum numbers of peers that can be connected to the server. |
| MinPeers | `int` | `5` | Minimum number of peers for normal operation, when the node has less than this number of peers it tries to connect with some new ones. |
| NodePort | `uint16` | `0`, which is any free port | The actual node port it is bound to. |
| Oracle | [Oracle Configuration](#Oracle-Configuration) | | Oracle module configuration. See the [Oracle Configuration](#Oracle-Configuration) section for details. |
| P2PNotary | [P2P Notary Configuration](#P2P-Notary-Configuration) | | P2P Notary module configuration. See the [P2P Notary Configuration](#P2P-Notary-Configuration) section for details. |
| PingInterval | `int64` | `30` | Interval in seconds used in pinging mechanism for syncing blocks. |
| PingTimeout | `int64` | `90` | Time to wait for pong (response for sent ping request). |
| Pprof | [Metrics Services Configuration](#Metrics-Services-Configuration) | | Configuration for pprof service (profiling statistics gathering). See the [Metrics Services Configuration](#Metrics-Services-Configuration) section for details. |
| Prometheus | [Metrics Services Configuration](#Metrics-Services-Configuration) | | Configuration for Prometheus (monitoring system). See the [Metrics Services Configuration](#Metrics-Services-Configuration) section for details |
| ProtoTickInterval | `int64` | `5` | Duration in seconds between protocol ticks with each connected peer. |
| Relay | `bool` | `true` | Determines whether the server is forwarding its inventory. |
| RPC | [RPC Configuration](#RPC-Configuration) | | Describes [RPC subsystem](rpc.md) configuration. See the [RPC Configuration](#RPC-Configuration) for details. |
| StateRoot | [State Root Configuration](#State-Root-Configuration) | | State root module configuration. See the [State Root Configuration](#State-Root-Configuration) section for details. |
| UnlockWallet | [Unlock Wallet Configuration](#Unlock-Wallet-Configuration) | | Node wallet configuration used for consensus (dBFT) operation. See the [Unlock Wallet Configuration](#Unlock-Wallet-Configuration) section for details. |
### DB Configuration
`DBConfiguration` section describes configuration for node database and has
the following format:
```
DBConfiguration:
Type: leveldb
LevelDBOptions:
DataDirectoryPath: /chains/privnet
RedisDBOptions:
Addr: localhost:6379
Password: ""
DB: 0
BoltDBOptions:
FilePath: ./chains/privnet.bolt
BadgerDBOptions:
BadgerDir: ./chains/privnet.badger
```
where:
- `Type` is the database type (string value). Supported types: `levelDB`,
`redisDB`, `boltDB`, `badgerDB`.
- `LevelDBOptions` are settings for LevelDB.
- `RedisDBOptions` are options for RedisDB.
- `BoltDBOptions` configures BoltDB.
- `BadgerDBOptions` are options for BadgerDB.
Only options for the specified database type will be used.
### Oracle Configuration
`Oracle` configuration section describes configuration for Oracle node module
and has the following structure:
```
Oracle:
Enabled: false
AllowPrivateHost: false
MaxTaskTimeout: 3600s
MaxConcurrentRequests: 10
Nodes: ["172.200.0.1:30333", "172.200.0.2:30334"]
NeoFS:
Nodes: ["172.200.0.1:30335", "172.200.0.2:30336"]
Timeout: 2
RefreshInterval: 180s
RequestTimeout: 5s
ResponseTimeout: 5s
UnlockWallet:
Path: "./oracle_wallet.json"
Password: "pass"
```
Please, refer to the [Oracle module documentation](./oracle.md#Configuration) for
details on configurable values.
### P2P Notary Configuration
`P2PNotary` configuration section describes configuration for P2P Notary node
module and has the following structure:
```
P2PNotary:
Enabled: false
UnlockWallet:
Path: "/notary_wallet.json"
Password: "pass"
```
where:
- `Enabled` denotes whether P2P Notary module is active.
- `UnlockWallet` is a Notary node wallet configuration, see the
[Unlock Wallet Configuration](#Unlock-Wallet-Configuration) section for
structure details.
Please, refer to the [Notary module documentation](./notary.md#Notary node module) for
details on module features.
### Metrics Services Configuration
Metrics services configuration describes options for metrics services (pprof,
Prometheus) and has the following structure:
```
Pprof:
Enabled: false
Address: ""
Port: "30001"
Prometheus:
Enabled: false
Address: ""
Port: "40001"
```
where:
- `Enabled` denotes whether the service is enabled.
- `Address` is a service address to be running at.
- `Port` is a service port to be bound to.
### RPC Configuration
`RPC` configuration section describes settings for the RPC server and has
the following structure:
```
RPC:
Enabled: true
Address: ""
EnableCORSWorkaround: false
MaxGasInvoke: 50
Port: 10332
TLSConfig:
Address: ""
CertFile: serv.crt
Enabled: true
Port: 10331
KeyFile: serv.key
```
where:
- `Enabled` denotes whether RPC server should be started.
- `Address` is an RPC server address to be running at.
- `EnableCORSWorkaround` enables Cross-Origin Resource Sharing and is useful if
you're accessing RPC interface from the browser.
- `MaxGasInvoke` is the maximum GAS allowed to spend during `invokefunction` and
`invokescript` RPC-calls.
- `Port` is an RPC server port it should be bound to.
- `TLS` section configures TLS protocol.
### State Root Configuration
`StateRoot` configuration section contains settings for state roots exchange and has
the following structure:
```
StateRoot:
Enabled: false
UnlockWallet:
Path: "./wallet.json"
Password: "pass"
```
where:
- `Enabled` enables state root module.
- `UnlockWallet` contains wallet settings, see
[Unlock Wallet Configuration](#Unlock-Wallet-Configuration) section for
structure details.
### Unlock Wallet Configuration
`UnlockWallet` configuration section contains wallet settings and has the following
structure:
```
UnlockWallet:
Path: "./wallet.json"
Password: "pass"
```
where:
- `Path` is a path to wallet.
- `Password` is a wallet password.
## Protocol Configuration
`ProtocolConfiguration` section of `yaml` node configuration file contains
protocol-related settings described in the table below.
| Section | Type | Default value | Description | Notes |
| --- | --- | --- | --- | --- |
| KeepOnlyLatestState | `bool` | `false` | Specifies if MPT should only store latest state. If true, DB size will be smaller, but older roots won't be accessible. This value should remain the same for the same database. |
| Magic | `uint32` | `0` | Magic number which uniquely identifies NEO network. |
| MaxBlockSize | `uint32` | `262144` | Maximum block size in bytes. |
| MaxBlockSystemFee | `int64` | `900000000000` | Maximum overall transactions system fee per block. |
| MaxTraceableBlocks | `uint32` | `2102400` | Length of the chain accessible to smart contracts. | `RemoveUntraceableBlocks` should be enabled to use this setting. |
| MaxTransactionsPerBlock | `uint16` | `512` | Maximum number of transactions per block. |
| MemPoolSize | `int` | `50000` | Size of the node's memory pool where transactions are stored before they are added to block. |
| NativeActivations | `map[string][]uint32` | ContractManagement: [0]<br>StdLib: [0]<br>CryptoLib: [0]<br>LedgerContract: [0]<br>NeoToken: [0]<br>GasToken: [0]<br>PolicyContract: [0]<br>RoleManagement: [0]<br>OracleContract: [0] | The list of histories of native contracts updates. Each list item shod be presented as a known native contract name with the corresponding list of chain's heights. The contract is not active until chain reaches the first height value specified in the list. | `Notary` is supported. |
| P2PNotaryRequestPayloadPoolSize | `int` | `1000` | Size of the node's P2P Notary request payloads memory pool where P2P Notary requests are stored before main or fallback transaction is completed and added to the chain.<br>This option is valid only if `P2PSigExtensions` are enabled. | Not supported by the C# node, thus may affect heterogeneous networks functionality. |
| P2PSigExtensions | `bool` | `false` | Enables following additional Notary service related logic:<br>• Transaction attributes `NotValidBefore`, `Conflicts` and `NotaryAssisted`<br>• Network payload of the `P2PNotaryRequest` type<br>• Native `Notary` contract<br>• Notary node module | Not supported by the C# node, thus may affect heterogeneous networks functionality. |
| P2PStateExchangeExtensions | `bool` | `false` | Enables following P2P MPT state data exchange logic: <br>• `StateSyncInterval` protocol setting <br>• P2P commands `GetMPTDataCMD` and `MPTDataCMD` | Not supported by the C# node, thus may affect heterogeneous networks functionality. |
| RemoveUntraceableBlocks | `bool`| `false` | Denotes whether old blocks should be removed from cache and database. If enabled, then only last `MaxTraceableBlocks` are stored and accessible to smart contracts. |
| ReservedAttributes | `bool` | `false` | Allows to have reserved attributes range for experimental or private purposes. |
| SaveStorageBatch | `bool` | `false` | Enables storage batch saving before every persist. It is similar to StorageDump plugin for C# node. |
| SecondsPerBlock | `int` | `15` | Minimal time that should pass before next block is accepted. |
| SeedList | `[]string` | [] | List of initial nodes addresses used to establish connectivity. |
| StandbyCommittee | `[]string` | [] | List of public keys of standby committee validators are chosen from. |
| StateRootInHeader | `bool` | `false` | Enables storing state root in block header. | Experimental protocol extension! |
| StateSyncInterval | `int` | `40000` | The number of blocks between state heights available for MPT state data synchronization. | `P2PStateExchangeExtensions` should be enabled to use this setting. |
| ValidatorsCount | `int` | `0` | Number of validators. |
| VerifyBlocks | `bool` | `false` | Denotes whether to verify received blocks. |
| VerifyTransactions | `bool` | `false` | Denotes whether to verify transactions in received blocks. |

18
docs/notifications.md
View file

@ -9,19 +9,21 @@ receive them as JSON-RPC notifications from the server.
## Events ## Events
Currently supported events: Currently supported events:
* new block added * new block added
Contents: block.
Filters: primary ID. Contents: block. Filters: primary ID.
* new transaction in the block * new transaction in the block
Contents: transaction.
Filters: sender and signer. Contents: transaction. Filters: sender and signer.
* notification generated during execution * notification generated during execution
Contents: container hash, contract script hash, stack item.
Filters: contract script hash. Contents: container hash, contract script hash, stack item. Filters: contract script hash.
* transaction executed * transaction executed
Contents: application execution result.
Filters: VM state. Contents: application execution result. Filters: VM state.
* new/removed P2P notary request (if `P2PSigExtensions` are enabled) * new/removed P2P notary request (if `P2PSigExtensions` are enabled)
Contents: P2P notary request. Filters: request sender and main tx signer.
Filters use conjunctional logic. Filters use conjunctional logic.
## Ordering and persistence guarantees ## Ordering and persistence guarantees

18
docs/rpc.md
View file

@ -21,13 +21,14 @@ which would yield the response:
```json ```json
{ {
"result" : {
"useragent" : "/NEO-GO:0.97.2/",
"tcpport" : 10333,
"network" : 860833102,
"nonce" : 105745208
},
"jsonrpc" : "2.0", "jsonrpc" : "2.0",
"id" : 1, "id" : 1
"result" : {
"port" : 20333,
"useragent" : "/NEO-GO:0.36.0-dev/",
"nonce" : 9318417
}
} }
``` ```
### Supported methods ### Supported methods
@ -82,11 +83,6 @@ It's possible to use `invokefunction` not only with contract scripthash, but als
with contract name (for native contracts) or contract ID (for all contracts). This with contract name (for native contracts) or contract ID (for all contracts). This
feature is not supported by the C# node. feature is not supported by the C# node.
##### `getunclaimedgas`
It's possible to call this method for any address with neo-go, unlike with C#
node where it only works for addresses from opened wallet.
##### `getcontractstate` ##### `getcontractstate`
It's possible to get non-native contract state by its ID, unlike with C# node where It's possible to get non-native contract state by its ID, unlike with C# node where

51
docs/vm.md
View file

@ -37,22 +37,25 @@ NEO-GO-VM >
NEO-GO-VM > help NEO-GO-VM > help
Commands: Commands:
astack Show alt stack contents break Place a breakpoint
break Place a breakpoint clear clear the screen
clear clear the screen cont Continue execution of the current loaded script
cont Continue execution of the current loaded script estack Show evaluation stack contents
estack Show evaluation stack contents exit Exit the VM prompt
exit Exit the VM prompt help display help
help display help ip Show current instruction
ip Show current instruction istack Show invocation stack contents
istack Show invocation stack contents loadbase64 Load a base64-encoded script string into the VM
loadnef Load an avm script in NEF format into the VM loadgo Compile and load a Go file with the manifest into the VM
loadgo Compile and load a Go file into the VM loadhex Load a hex-encoded script string into the VM
loadhex Load a hex-encoded script string into the VM loadnef Load a NEF-consistent script into the VM
ops Dump opcodes of the current loaded program ops Dump opcodes of the current loaded program
run Execute the current loaded script parse Parse provided argument and convert it into other possible formats
step Step (n) instruction in the program run Execute the current loaded script
step Step (n) instruction in the program
stepinto Stepinto instruction to take in the debugger
stepout Stepout instruction to take in the debugger
stepover Stepover instruction to take in the debugger
``` ```
@ -96,7 +99,7 @@ NEO-GO-VM > loadgo ../contract.go
READY: loaded 36 instructions READY: loaded 36 instructions
``` ```
To make it even more complete, you can directly load hex strings into the VM: To make it even more complete, you can directly load hex or base64 strings into the VM:
``` ```
NEO-GO-VM > loadhex 54c56b006c766b00527ac46c766b00c391640b006203005a616c756662030000616c7566 NEO-GO-VM > loadhex 54c56b006c766b00527ac46c766b00c391640b006203005a616c756662030000616c7566
@ -119,16 +122,7 @@ package rollthedice
import "github.com/nspcc-dev/neo-go/pkg/interop/runtime" import "github.com/nspcc-dev/neo-go/pkg/interop/runtime"
func Main(method string, args []interface{}) int { func RollDice(number int) {
if method == "rollDice" {
// args parameter is always of type []interface, hence we need to
// cast it to an int.
rollDice(args[0].(int))
}
return 0
}
func rollDice(number int) {
if number == 0 { if number == 0 {
runtime.Log("you rolled 0, better luck next time!") runtime.Log("you rolled 0, better luck next time!")
} }
@ -227,7 +221,6 @@ NEO-GO-VM > estack
] ]
``` ```
There are more stacks that you can inspect. There is one more stack that you can inspect.
- `astack` alt stack
- `istack` invocation stack - `istack` invocation stack

6
pkg/vm/cli/cli.go
View file

@ -67,12 +67,6 @@ var commands = []*ishell.Cmd{
LongHelp: "Show evaluation stack contents", LongHelp: "Show evaluation stack contents",
Func: handleXStack, Func: handleXStack,
}, },
{
Name: "astack",
Help: "Show alt stack contents",
LongHelp: "Show alt stack contents",
Func: handleXStack,
},
{ {
Name: "istack", Name: "istack",
Help: "Show invocation stack contents", Help: "Show invocation stack contents",