TrueCloudLab/neo-go
8
0
Fork 0
mirror of https://github.com/nspcc-dev/neo-go.git synced 2024-11-22 09:29:38 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #2162 from nspcc-dev/docs/update

Browse source 
docs: minor documentation updates and adjustments
This commit is contained in:
Roman Khimov 2021-09-09 12:38:20 +03:00 committed by GitHub
commit b502c5f148
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
17 changed files with 503 additions and 360 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",
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>",
Action: printNEP11TokensOf,
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
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
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).
@ -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.
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#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. |
Refer to the [node configuration documentation](./node-configuration.md) for
detailed configuration file description.
### Starting a node
@ -264,12 +52,12 @@ Or specify a different network with appropriate flag like this:
./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.
### 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:
| 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
```
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
#### 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
```
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
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
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
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
@ -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
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
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.
@ -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
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.
`_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()`.
## Quick start
@ -57,13 +59,15 @@ export GOROOT=/usr/lib64/go/1.15
./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
```
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
(`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:
```
INDEX OPCODE PARAMETER
0 INITSLOT 0500 ("\x05\x00") <<
3 PUSH0
4 REVERSEN
5 SYSCALL "\x9a\x1f\x19J"
10 NOP
11 STLOC0
12 LDLOC0
13 PUSH1
14 REVERSEN
15 PUSH1
16 PACK
17 SYSCALL "\x05\a\x92\x16"
22 NOP
23 PUSH0
24 REVERSEN
25 SYSCALL "E\x99Z\\"
30 NOP
31 STLOC1
32 LDLOC1
33 PUSH1
34 REVERSEN
35 PUSH1
36 PACK
37 SYSCALL "\x05\a\x92\x16"
42 NOP
43 PUSH0
44 REVERSEN
45 SYSCALL "\x87\xc3\xd2d"
50 NOP
51 STLOC2
52 LDLOC2
53 PUSH1
54 REVERSEN
55 PUSH1
56 PACK
57 SYSCALL "\x05\a\x92\x16"
62 NOP
63 PUSH0
64 REVERSEN
65 SYSCALL "\x1dY\xe1\x19"
70 NOP
71 STLOC3
72 LDLOC3
73 PUSH1
74 REVERSEN
75 PUSH1
76 PACK
77 SYSCALL "\x05\a\x92\x16"
82 NOP
83 PUSH1
84 RET
INDEX OPCODE PARAMETER
0 INITSLOT 4 local, 2 arg <<
3 LDARG1
4 NOT
5 JMPIFNOT_L 151 (146/92000000)
10 SYSCALL System.Storage.GetContext (9bf667ce)
15 NOP
16 STLOC0
17 PUSHDATA1 53746f72616765206b6579206e6f7420796574207365742e2053657474696e6720746f2030 ("Storage key not yet set. Setting to 0")
56 CONVERT Buffer (30)
58 PUSH1
59 PACK
60 STLOC1
61 PUSHDATA1 696e666f ("info")
67 LDLOC1
68 SWAP
69 SYSCALL System.Runtime.Notify (95016f61)
74 NOP
75 PUSH0
76 STLOC2
77 LDLOC0
78 PUSHDATA1 746573742d73746f726167652d6b6579 ("test-storage-key")
96 LDLOC2
97 REVERSE3
98 SYSCALL System.Storage.Put (e63f1884)
103 NOP
104 PUSHDATA1 53746f72616765206b657920697320696e697469616c69736564 ("Storage key is initialised")
132 CONVERT Buffer (30)
134 PUSH1
135 PACK
136 STLOC3
137 PUSHDATA1 696e666f ("info")
143 LDLOC3
144 SWAP
145 SYSCALL System.Runtime.Notify (95016f61)
150 NOP
151 RET
152 INITSLOT 5 local, 0 arg
155 SYSCALL System.Storage.GetContext (9bf667ce)
160 NOP
161 STLOC0
162 LDLOC0
163 PUSHDATA1 746573742d73746f726167652d6b6579 ("test-storage-key")
181 SWAP
182 SYSCALL System.Storage.Get (925de831)
187 NOP
188 STLOC1
189 PUSHDATA1 56616c756520726561642066726f6d2073746f72616765 ("Value read from storage")
214 CONVERT Buffer (30)
216 PUSH1
217 PACK
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
@ -168,7 +210,7 @@ events:
- name: info
parameters:
- name: message
type: ByteString
type: String
```
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
```
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.
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.
@ -316,7 +358,7 @@ mandatory parameter.
Example call (contract `f84d6a337fbc3d3a201d41da99e86b479e7a2554` with method
`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

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
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,
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
your expectations. Details on various configuration options (as well as CLI
commands) are provided [here](cli.md).
your expectations. Details on various configuration options are provided in the
[node configuration documentation](node-configuration.md), CLI commands are
provided in the [CLI documentation](cli.md).
### 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.
This requirement is needed for nodes to correctly
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.
4. If you start binary from the same directory, you will probably want to change
`DataDirectoryPath` from the `LevelDBOptions`.

18
docs/conventions.md
View file

@ -1,12 +1,15 @@
# 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.
## Avoid Named return paramters
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 parameters
func example(test int) (num int) {
a = test + 1
@ -14,7 +17,10 @@ func example(test int) (num int) {
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

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
Currently supported events:
* new block added
Contents: block.
Filters: primary ID.
Contents: block. Filters: primary ID.
* new transaction in the block
Contents: transaction.
Filters: sender and signer.
Contents: transaction. Filters: sender and signer.
* 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
Contents: application execution result.
Filters: VM state.
Contents: application execution result. Filters: VM state.
* new/removed P2P notary request (if `P2PSigExtensions` are enabled)
Contents: P2P notary request. Filters: request sender and main tx signer.
Filters use conjunctional logic.
## Ordering and persistence guarantees

18
docs/rpc.md
View file

@ -21,13 +21,14 @@ which would yield the response:
```json
{
"result" : {
"useragent" : "/NEO-GO:0.97.2/",
"tcpport" : 10333,
"network" : 860833102,
"nonce" : 105745208
},
"jsonrpc" : "2.0",
"id" : 1,
"result" : {
"port" : 20333,
"useragent" : "/NEO-GO:0.36.0-dev/",
"nonce" : 9318417
}
"id" : 1
}
```
### 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
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`
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
Commands:
astack Show alt stack contents
break Place a breakpoint
clear clear the screen
cont Continue execution of the current loaded script
estack Show evaluation stack contents
exit Exit the VM prompt
help display help
ip Show current instruction
istack Show invocation stack contents
loadnef Load an avm script in NEF format into the VM
loadgo Compile and load a Go file into the VM
loadhex Load a hex-encoded script string into the VM
ops Dump opcodes of the current loaded program
run Execute the current loaded script
step Step (n) instruction in the program
break Place a breakpoint
clear clear the screen
cont Continue execution of the current loaded script
estack Show evaluation stack contents
exit Exit the VM prompt
help display help
ip Show current instruction
istack Show invocation stack contents
loadbase64 Load a base64-encoded script string into the VM
loadgo Compile and load a Go file with the manifest 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
parse Parse provided argument and convert it into other possible formats
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
```
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
@ -119,16 +122,7 @@ package rollthedice
import "github.com/nspcc-dev/neo-go/pkg/interop/runtime"
func Main(method string, args []interface{}) 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) {
func RollDice(number int) {
if number == 0 {
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.
- `astack` alt stack
There is one more stack that you can inspect.
- `istack` invocation stack

2
pkg/interop/doc.go
View file

@ -16,7 +16,7 @@ correspond to smartcontract and VM types:
non-byte slice - Array
map[K]V - map
Other types are defined explicitly in this pkg:
Hash160, Hash256, InteropInterface, PublicKey, Signature
Hash160, Hash256, Interface, PublicKey, Signature
Note that unless written otherwise structures defined in this packages can't be
correctly created by new() or composite literals, they should be received from

13
pkg/interop/iterator/iterator.go
View file

@ -6,14 +6,15 @@ package iterator
import "github.com/nspcc-dev/neo-go/pkg/interop/neogointernal"
// Iterator represents a Neo iterator, it's an opaque data structure that can
// be properly created by Create or storage.Find. Unlike enumerators, iterators
// range over key-value pairs, so it's convenient to use them for maps. This
// structure is similar in function to Neo .net framework's Iterator.
// be properly created by Create or storage.Find. Iterators range over key-value
// pairs, so it's convenient to use them for maps. This structure is similar in
// function to Neo .net framework's Iterator.
type Iterator struct{}
// Next advances the iterator returning true if it is was successful (and you
// can use Key or Value) and false otherwise (and there are no more elements in
// this Iterator). This function uses `System.Iterator.Next` syscall.
// Next advances the iterator returning true if it was successful (and you
// can use Value to get value for slices or key-value pair for maps) and false
// otherwise (and there are no more elements in this Iterator). This function
// uses `System.Iterator.Next` syscall.
func Next(it Iterator) bool {
return neogointernal.Syscall1("System.Iterator.Next", it).(bool)
}

2
pkg/interop/native/neo/neo.go
View file

@ -1,7 +1,7 @@
/*
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
provides access to chain-specific settings and implements committee
voting system.
*/
package neo

7
pkg/rpc/client/client.go
View file

@ -110,9 +110,10 @@ func New(ctx context.Context, endpoint string, opts Options) (*Client, error) {
return cl, nil
}
// Init sets magic of the network client connected to and native NEO and GAS
// contracts scripthashes. This method should be called before any transaction-,
// header- or block-related requests in order to deserialize responses properly.
// Init sets magic of the network client connected to, stateRootInHeader option
// and native NEO, GAS and Policy contracts scripthashes. This method should be
// called before any transaction-, header- or block-related requests in order to
// deserialize responses properly.
func (c *Client) Init() error {
version, err := c.GetVersion()
if err != nil {

17
pkg/rpc/client/doc.go
View file

@ -12,38 +12,47 @@ return a more pretty printed response from the server instead of
a raw hex string.
TODO:
Add missing methods to client.
Allow client to connect using client cert.
More in-depth examples.
Supported methods
calculatenetworkfee
getapplicationlog
getbestblockhash
getblock
getblockcount
getblockhash
getblockheader
getblocksysfee
getblockheadercount
getcommittee
getconnectioncount
getcontractstate
getnativecontracts
getnep17balances
getnep17transfers
getpeers
getrawmempool
getrawtransaction
getstateheight
getstorage
gettransactionheight
getunclaimedgas
getvalidators
getnextblockvalidators
getversion
invoke
invokefunction
invokescript
invokecontractverify
sendrawtransaction
submitblock
submitoracleresponse
validateaddress
Extensions:
getblocksysfee
submitnotaryrequest
Unsupported methods
claimgas

6
pkg/rpc/client/doc_test.go
View file

@ -19,6 +19,12 @@ func Example() {
os.Exit(1)
}
err = c.Init()
if err != nil {
fmt.Println(err)
os.Exit(1)
}
if err := c.Ping(); err != nil {
fmt.Println(err)
os.Exit(1)

4
pkg/rpc/client/wsclient.go
View file

@ -38,8 +38,8 @@ type WSClient struct {
}
// Notification represents server-generated notification for client subscriptions.
// Value can be one of block.Block, result.ApplicationLog, result.NotificationEvent
// or transaction.Transaction based on Type.
// Value can be one of block.Block, state.AppExecResult, state.NotificationEvent
// transaction.Transaction or response.NotaryRequestEvent based on Type.
type Notification struct {
Type response.EventID
Value interface{}

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

@ -67,12 +67,6 @@ var commands = []*ishell.Cmd{
LongHelp: "Show evaluation stack contents",
Func: handleXStack,
},
{
Name: "astack",
Help: "Show alt stack contents",
LongHelp: "Show alt stack contents",
Func: handleXStack,
},
{
Name: "istack",
Help: "Show invocation stack contents",
@ -410,6 +404,10 @@ func handleRun(c *ishell.Context) {
v.Estack().PushVal(params[i])
}
if runCurrent {
if !v.Ready() {
c.Err(fmt.Errorf("no program loaded"))
return
}
v.Jump(v.Context(), offset)
if initMD := m.ABI.GetMethod(manifest.MethodInit, 0); initMD != nil {
v.Call(v.Context(), initMD.Offset)