dstepanov-yadro/neoneo-go
1
0
Fork 0
forked from TrueCloudLab/neoneo-go
Code Pull requests Activity

Merge pull request #1843 from nspcc-dev/doc-update

Browse source 
Documentation update and microfixes
This commit is contained in:
Roman Khimov 2021-03-19 17:17:53 +03:00 committed by GitHub
commit f6e0414707
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
35 changed files with 517 additions and 204 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
Makefile
View file

@ -19,7 +19,7 @@ IMAGE_REPO=nspccdev/neo-go
# All of the targets are phony here because we don't really use make dependency # All of the targets are phony here because we don't really use make dependency
# tracking for files # tracking for files
.PHONY: build deps image image-latest image-push image-push-latest check-version clean-cluster push-tag \ .PHONY: build deps image image-latest image-push image-push-latest check-version clean-cluster push-tag \
run run-cluster test vet lint fmt cover test vet lint fmt cover
build: deps build: deps
@echo "=> Building binary" @echo "=> Building binary"
@ -77,9 +77,6 @@ push-tag:
git tag ${VERSION} git tag ${VERSION}
git push origin ${VERSION} git push origin ${VERSION}
run: build
${BINARY} node -config-path ./config -${NETMODE}
test: test:
@go test ./... -cover @go test ./... -cover

82
README.md
View file

@ -36,60 +36,38 @@ Neo 3 code (0.90.0 being compatible with Neo 3 preview2).
## Installation ## Installation
Go: 1.14+ NeoGo is distributed as a single binary that includes all the functionality
provided (but smart contract compiler requires Go compiler to operate). You
Install dependencies. can grab it from [releases
page](https://github.com/nspcc-dev/neo-go/releases), use a Docker image (see
`neo-go` uses [GoModules](https://github.com/golang/go/wiki/Modules) as dependency manager: [Docker Hub](https://hub.docker.com/r/nspccdev/neo-go) for various releases of
NeoGo, `:latest` points to the latest release) or build yourself.
```
make deps
```
## How to setup a node
### Docker
Each tagged build is published to docker hub and the `:latest` tag pointing at the latest tagged master build.
By default the `CMD` is set to run a node on `privnet`, so to do this simply run:
```bash
docker run -d --name neo-go -p 20332:20332 -p 20331:20331 nspccdev/neo-go
```
Which will start a node on `privnet` and expose the nodes port `20332` and `20331` for the `JSON-RPC` server.
### Building ### Building
Build the **neo-go** CLI: To build NeoGo you need Go 1.14+ and `make`:
``` ```
make build make build
``` ```
### Running The resulting binary is `bin/neo-go`.
Quick start a NEO node on the private network. ## Running a node
To build and run the private network image locally, use:
```
make env_image
make env_up
```
To start a NEO node on the private network: A node needs to connect to some network, either local one (usually referred to
``` as `privnet`) or public (like `mainnet` or `testnet`). Network configuration
make run is stored in a file and NeoGo allows you to store multiple files in one
``` directory (`./config` by default) and easily switch between them using network
flags.
To run the binary directly: To start Neo node on private network use:
``` ```
./bin/neo-go node ./bin/neo-go node
``` ```
By default the node will run on the private network, to change this: Or specify a different network with appropriate flag like this:
``` ```
./bin/neo-go node --mainnet ./bin/neo-go node --mainnet
@ -100,7 +78,18 @@ Available network flags:
- `--privnet, -p` - `--privnet, -p`
- `--testnet, -t` - `--testnet, -t`
#### Importing mainnet/testnet dump files ### Docker
By default the `CMD` is set to run a node on `privnet`, so to do this simply run:
```bash
docker run -d --name neo-go -p 20332:20332 -p 20331:20331 nspccdev/neo-go
```
Which will start a node on `privnet` and expose node's ports `20332` (P2P
protocol) and `20331` (JSON-RPC server).
### Importing mainnet/testnet dump files
If you want to jump-start your mainnet or testnet node with [chain archives If you want to jump-start your mainnet or testnet node with [chain archives
provided by NGD](https://sync.ngd.network/) follow these instructions (when provided by NGD](https://sync.ngd.network/) follow these instructions (when
@ -114,6 +103,10 @@ $ ./bin/neo-go db restore -m -i chain.acc # for testnet use '-t' flag instead of
The process differs from the C# node in that block importing is a separate The process differs from the C# node in that block importing is a separate
mode, after it ends the node can be started normally. mode, after it ends the node can be started normally.
## Running a private network
Refer to [consensus node documentation](docs/consensus.md).
## Smart contract development ## Smart contract development
Please refer to [neo-go smart contract development Please refer to [neo-go smart contract development
@ -123,6 +116,17 @@ and private network. For details on how Go code is translated to Neo VM
bytecode and what you can and can not do in smart contract please refer to the bytecode and what you can and can not do in smart contract please refer to the
[compiler documentation](docs/compiler.md). [compiler documentation](docs/compiler.md).
## Wallets
NeoGo differs substantially from C# implementation in its approach to
wallets. NeoGo wallet is just a
[NEP-6](https://github.com/neo-project/proposals/blob/68398d28b6932b8dd2b377d5d51bca7b0442f532/nep-6.mediawiki)
file that is used by CLI commands to sign various things. There is no database
behind it, the blockchain is the database and CLI commands use RPC to query
data from it. At the same time it's not required to open the wallet on RPC
node to perform various actions (unless your node is providing some service
for the network like consensus or oracle nodes).
# Developer notes # Developer notes
Nodes have such features as [Prometheus](https://prometheus.io/docs/guides/go-application) and Nodes have such features as [Prometheus](https://prometheus.io/docs/guides/go-application) and
[Pprof](https://golang.org/pkg/net/http/pprof/) in order to have additional information about them for debugging. [Pprof](https://golang.org/pkg/net/http/pprof/) in order to have additional information about them for debugging.

2
config/protocol.testnet.yml
View file

@ -1,5 +1,5 @@
ProtocolConfiguration: ProtocolConfiguration:
Magic: 894448462 Magic: 1951352142
MaxTraceableBlocks: 2102400 MaxTraceableBlocks: 2102400
SecondsPerBlock: 15 SecondsPerBlock: 15
MemPoolSize: 50000 MemPoolSize: 50000

421
docs/cli.md
View file

@ -1,183 +1,348 @@
# NEO-GO client # NeoGo CLI interface
The Neo-Go client is used to run node, create/compile/deploy/invoke/debug smart contracts, run vm and operate with the wallet. NeoGo CLI provides all functionality from one binary, so it's used to run
node, create/compile/deploy/invoke/debug smart contracts, run vm and operate
with the wallet. The standard setup assumes that you're running a node as a
separate process and it doesn't provide any CLI of its own, instead it just
makes RPC interface available for you. To perform any actions you invoke NeoGo
as a client that connects to this RPC node and does things you want it to do
(like transferring some NEP-17 asset).
All CLI commands have corresponding help messages, use `--help` option to get
them, for example:
```
./bin/neo-go db --help
```
## Running node ## Running node
To start Neo Go node locally it's required to run Use `node` command to run a NeoGo node, it will be configured using a YAML
[neo-privatenet](https://hub.docker.com/r/cityofzion/neo-privatenet/) Docker image on your machine. file that contains network parameters as well as node settings.
To run node you can use ### Configuration
```
make run
```
or run the binary directly: All config files are located in `./config` and they are differentiated according to the network type:
- `protocol.mainnet.yml` belongs to `--mainnet` network mode (`-m` short option)
- `protocol.privnet.yml` belongs to `--privnet` network mode (`-p` short
option) and is used by default
- `protocol.testnet.yml` belongs to `--testnet` network mode (`-t` short option)
- `protocol.unit_testnet.yml` is used by unit tests
If you want to use some non-default configuration directory path, specify
`--config-path` flag:
`./bin/neo-go node --config-path /user/yourConfigPath`
The file loaded is chosen automatically depending on network mode flag.
### Starting a node
To start Neo node on private network use:
``` ```
./bin/neo-go node ./bin/neo-go node
``` ```
By default the node will run on the `private network`, to change this use additional network flag: Or specify a different network with appropriate flag like this:
``` ```
./bin/neo-go node --mainnet ./bin/neo-go node --mainnet
``` ```
#### Available network flags By default the node will run in foreground using current standard output for
- `--mainnet, -m` logging.
- `--privnet, -p`
- `--testnet, -t`
#### Configuration path ### DB import/exports
If you want to use some specific configuration path you have to use `--config-path` flag Node operates using some database as a backend to store blockchain data. NeoGo
allows to dump chain into file from the database (when node is stopped) or to
import blocks from file into the database (also when node is stopped). Use
`db` command for that.
`./bin/neo-go node --config-path /user/yourConfigPath` ## Smart contracts
## Configuration Use `contract` command to create/compile/deploy/invoke/debug smart contracts,
see [compiler documentation](compiler.md).
All config files are located in `./config` and they are differentiated according to the network type: ## Wallet operations
- `protocol.mainnet.yml` belongs to `--mainnet` network mode
- `protocol.privnet.yml` belongs to `--privnet` network mode and used be default
- `protocol.testnet.yml` belongs to `--testnet` network mode
- `protocol.unit_testnet.yml` used by unit tests
Those files are automatically loaded, corresponding the provided `netmode` flag. `wallet` command provides interface for all operations requiring a wallet
Example of such configuration: (except contract deployment and invocations that are done via `contract
```yaml deploy` and `contract invokefunction`). Wallet management (creating wallet,
ProtocolConfiguration: adding addresses/keys to it) is available there as well as wallet-related
Magic: 56753 functions like NEP-17 transfers, NEO votes, multi-signature signing and other
StandbyValidators: things.
- 02b3622bf4017bdfe317c58aed5f4c753f206b7db896046fa7d774bbc4bf7f8dc2
- 02103a7f7dd016558597f7960d27c516a4394fd968b9e65155eb4b013e4040406e
- 03d90c07df63e690ce77912e10ab51acc944b66860237b608c4f8f8309e71ee699
- 02a7bc55fe8684e0119768d104ba30795bdcc86619e864add26156723ed185cd62
SeedList:
- 127.0.0.1:20333
- 127.0.0.1:20334
- 127.0.0.1:20335
- 127.0.0.1:20336
ApplicationConfiguration: ### Wallet management
DataDirectoryPath: "./chains/privnet"
RPCPort: 20332 #### Create wallet
NodePort: 20333
Relay: true Use `wallet init` command to create new wallet:
DialTimeout: 3
ProtoTickInterval: 2
MaxPeers: 50
``` ```
#### Node debug mode ./bin/neo-go wallet init -w wallet.nep6
There is a debug mode available by additional flag: `--debug, -d` {
"version": "3.0",
"accounts": [],
"scrypt": {
"n": 16384,
"r": 8,
"p": 8
},
"extra": {
"Tokens": null
}
}
## Smart contract create/compile/deploy/invoke/debug wallet successfully created, file location is wallet.nep6
### Create
In order to create new smart contract:
`./bin/neo-go contract init -n TestContract`
where
`init` used to initialize new contract and `--name, -n` - to specify contract name.
It will run wizard with a few questions:
```
Author: TestAuthor
Email: test@gmail.com
Version: 1
Project name: Test
Description: desc
Successfully initialized smart contract [TestContract]
``` ```
After that you will have a package with `TestContract` name and it will include where "wallet.nep6" is a wallet file name. This wallet will be empty, to
- `main.go` smart contract file generate a new key pair and add an account for it use `-a` option:
- `neo-go.yml` project section containing information about the contact
In case you don't want to provide details use `--skip-details, -skip`.
### Compile
``` ```
./bin/neo-go contract compile -i mycontract.go ./bin/neo-go wallet init -w wallet.nep6 -a
Enter the name of the account > Name
Enter passphrase >
Confirm passphrase >
{
"version": "3.0",
"accounts": [
{
"address": "NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E",
"key": "6PYL2UrC11nWFJWSLiqsPKCNm9u4zr4ttX1ZbV9f2fLDqXsePioVxEsYdg",
"label": "Name",
"contract": {
"script": "DCEDzs1j19gSDDsZTDsogN1Kr+FHXFfkDIUoctcwVhUlgUBBdHR2qg==",
"parameters": [
{
"name": "parameter0",
"type": "Signature"
}
],
"deployed": false
},
"lock": false,
"isdefault": false
}
],
"scrypt": {
"n": 16384,
"r": 8,
"p": 8
},
"extra": {
"Tokens": null
}
}
wallet successfully created, file location is wallet.nep6
``` ```
By default the output filename will be the name of your `.go` file with the `.nef` extension, the file will be located or use `wallet create` command to create new account in existing wallet:
in the same directory where you called the command from. If you want another location for your compiled contract:
``` ```
./bin/neo-go contract compile -i mycontract.go --out /Users/foo/bar/contract.nef ./bin/neo-go wallet create -w wallet.nep6
Enter the name of the account > Joe Random
Enter passphrase >
Confirm passphrase >
``` ```
### Deploy #### Convert Neo Legacy wallets to Neo N3
//Not implemented yet
### Invoke
//Implemented in test mode. It means that it won't affect the blockchain
Use `wallet convert` to update addresses in NEP-6 wallets used with Neo
Legacy. New wallet is specified in `-o` option, it will have the same keys
with Neo N3 addresses.
``` ```
./bin/neo-go contract testinvoke -i mycontract.nef ./bin/neo-go wallet convert -w old.nep6 -o new.nep6
``` ```
### Debug #### Check wallet contents
You can dump the opcodes generated by the compiler with the following command: `wallet dump` can be used to see wallet contents in more user-friendly way,
its output is the same NEP-6 JSON, but better formatted. You can also decrypt
keys at the same time with `-d` option (you'll be prompted for password):
``` ```
./bin/neo-go contract inspect -i mycontract.go ./bin/neo-go wallet dump -w wallet.nep6 -d
Enter wallet password >
{
"version": "3.0",
"accounts": [
{
"address": "NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E",
"key": "6PYL2UrC11nWFJWSLiqsPKCNm9u4zr4ttX1ZbV9f2fLDqXsePioVxEsYdg",
"label": "Name",
"contract": {
"script": "DCEDzs1j19gSDDsZTDsogN1Kr+FHXFfkDIUoctcwVhUlgUBBdHR2qg==",
"parameters": [
{
"name": "parameter0",
"type": "Signature"
}
],
"deployed": false
},
"lock": false,
"isdefault": false
}
],
"scrypt": {
"n": 16384,
"r": 8,
"p": 8
},
"extra": {
"Tokens": null
}
}
``` ```
This will result in something like this: You can also get public keys for addresses stored in your wallet with `wallet
dump-keys` command:
``` ```
INDEX OPCODE DESC ./bin/neo-go wallet dump-keys -w wallet.nep6
0 0x54 PUSH4 NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E (simple signature contract):
1 0xc5 NEWARRAY 03cecd63d7d8120c3b194c3b2880dd4aafe1475c57e40c852872d7305615258140
2 0x6b TOALTSTACK
3 0x5a PUSH10
4 0x6a DUPFROMALTSTACK
5 0x0 PUSH0
6 0x52 PUSH2
7 0x7a ROLL
8 0xc4 SETITEM
9 0x6a DUPFROMALTSTACK
10 0x0 PUSH0
11 0xc3 PICKITEM
12 0x5a PUSH10
13 0xa2 GTE
14 0x64 JMPIFNOT
15 0x7 7
15 0x0 0
17 0x51 PUSH1
18 0x6c FROMALTSTACK
19 0x75 DROP
20 0x66 RET
21 0x0 PUSH0
22 0x6c FROMALTSTACK
23 0x75 DROP
24 0x66 RET
``` ```
In depth documentation about the **neo-go** compiler and smart contract examples can be found inside #### Private key export
the [compiler package](pkg/compiler). `wallet export` allows you to export private key in NEP-2 encrypted or WIF
(unencrypted) form (`-d` flag).
```
$ ./bin/neo-go wallet export -w wallet.nep6 -d NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E
Enter password >
KyswN8r48dhsvyQJVy97RWnZmKgYLrXv9mCL81Kb4vAagZiCsePv
```
## VM run #### Private key import
To run VM use You can import NEP-2 or WIF private key along with verification contract (if
it's non-standard):
```
./bin/neo-go wallet import --wif KwYgW8gcxj1JWJXhPSu4Fqwzfhp5Yfi42mdYmMa4XqK7NJxXUSK7 -w wallet.nep6
Provided WIF was unencrypted. Wallet can contain only encrypted keys.
Enter the name of the account > New Account
Enter passphrase >
Confirm passphrase >
```
#### Special accounts
Multisignature accounts can be imported with `wallet import-multisig`, you'll
need all public keys and one private key to do that. Then you could sign
transactions for this multisignature account with imported key.
`wallet import-deployed` can be used to create wallet accounts for deployed
contracts. They also can have WIF keys associated with them (in case your
contract's `verify` method needs some signature).
### Neo voting
`wallet candidate` provides commands to register or unregister a committee
(and therefore validator) candidate key:
```
./bin/neo-go wallet candidate register -a NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E -w wallet.json -r http://localhost:20332
```
You can also vote for candidates if you own NEO:
```
./bin/neo-go wallet candidate vote -a NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E -w wallet.json -r http://localhost:20332 -c 03cecd63d7d8120c3b194c3b2880dd4aafe1475c57e40c852872d7305615258140
```
### NEP-17 token functions
`wallet nep17` contains a set of commands to use for NEP-17 tokens.
#### Token metadata
NEP-17 commands are designed to work with any NEP-17 tokens, but NeoGo needs
some metadata for these tokens to function properly. Native NEO or GAS are
known to NeoGo by default, but other tokens are not. NeoGo can get this
metadata from the specified RPC server, but that's an additional request to
make, so if you care about command processing delay you can import token
metadata into the wallet with `wallet nep17 import` command. It'll be stored
in the `extra` section of the wallet.
```
./bin/neo-go wallet nep17 import -w wallet.nep6 -r http://localhost:20332 -t abcdefc189f30098b0ba6a2eb90b3a925800ffff
```
You can later see what token data you have in your wallet with `wallet nep17
info` command and remove tokens you don't need with `wallet nep17 remove`.
#### Balance
Getting balance is easy:
```
./bin/neo-go wallet nep17 balance -w /etc/neo-go/wallet.json -r http://localhost:20332
```
By default you'll get data for all tokens for the default wallet's
address. You can select non-default address with `-a` flag and/or select token
with `--token` flag (token hash or name can be used as parameter)
#### Transfers
`wallet nep17 transfer` creates a token transfer transaction and pushes it to
the RPC server (or saves to file if it needs to be signed by multiple
parties). For example, transferring 100 GAS looks like this:
```
./bin/neo-go wallet nep17 transfer -w wallet.nep6 -r http://localhost:20332 --to NjEQfanGEXihz85eTnacQuhqhNnA6LxpLp --from NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E --token GAS --amount 100
```
You can omit `--from` parameter (default wallet's address will be used in this
case), you can add `--gas` for extra network fee (raising priority of your
transaction). And you can save transaction to file with `--out` instead of
sending it to the network if it needs to be signed by multiple parties.
One `transfer` invocation creates one transaction, but in case you need to do
many transfers you can save on network fees by doing multiple token moves with
one transaction by using `wallet nep17 multitransfer` command. It can transfer
things from one account to many, its syntax differs from `transfer` in that
you don't have `--token`, `--to` and `--amount` options, but instead you can
specify multiple "token:addr:amount" sets after all other options. The same
transfer as above can be done with `multitransfer` by doing this:
```
./bin/neo-go wallet nep17 multitransfer -w wallet.nep6 -r http://localhost:20332 --from NMe64G6j6nkPZby26JAgpaCNrn1Ee4wW6E GAS:NjEQfanGEXihz85eTnacQuhqhNnA6LxpLp:100
```
#### GAS claims
While Neo N3 doesn't have any notion of "claim transaction" and has GAS
automatically distributed with every NEO transfer for NEO owners you still
won't get GAS if you don't do any actions. So the old `wallet claim` command
was updated to be an easier way to do NEO "flipping" when you send a
transaction that transfers all of your NEO to yourself thereby triggering GAS
distribution.
## Conversion utility
NeoGo provides conversion utility command to reverse data, convert script
hashes to/from address, convert data to/from hexadecimal or base64
representation. All of this is done by a single `util convert` command like
this:
```
$ ./bin/neo-go util convert deee79c189f30098b0ba6a2eb90b3a9258a6c7ff
BE ScriptHash to Address NgEisvCqr2h8wpRxQb7bVPWUZdbVCY8Uo6
LE ScriptHash to Address NjEQfanGEXihz85eTnacQuhqhNnA6LxpLp
Hex to String "\xde\xeey\xc1\x89\xf3\x00\x98\xb0\xbaj.\xb9\v:\x92X\xa6\xc7\xff"
Hex to Integer -1256651697634605895065630637163547727407485218
Swap Endianness ffc7a658923a0bb92e6abab09800f389c179eede
Base64 to String "u\xe7\x9e\xef\xd75\xf3\xd7\xf7\xd3O|oF\xda魞o\xdd\x1bݯv\xe7ƺs\xb7\xdf"
Base64 to BigInteger -222811771454869584930239486728381018152491835874567723544539443409000587
String to Hex 64656565373963313839663330303938623062613661326562393062336139323538613663376666
String to Base64 ZGVlZTc5YzE4OWYzMDA5OGIwYmE2YTJlYjkwYjNhOTI1OGE2YzdmZg==
```
## VM CLI
There is a VM CLI that you can use to load/analyze/run/step through some code:
``` ```
./bin/neo-go vm ./bin/neo-go vm
``` ```
For the detailed help use `help` in VM console. Some basic commands available there:
There is a small subset of commands:
- `loadgo` -- loads smart contract `NEO-GO-VM > loadgo TestContract/main.go` - `loadgo` -- loads smart contract `NEO-GO-VM > loadgo TestContract/main.go`
- `ops` -- show the opcodes of currently loaded contract - `ops` -- show the opcodes of currently loaded contract
- `run` -- executes currently loaded contract - `run` -- executes currently loaded contract
## Wallet operations Use `help` command to get more detailed information on all possibilities and
particular commands. Note that this VM is completely disconnected from the
- `./bin/neo-go wallet init -w newWallet` to create new wallet in the path `newWallet` blockchain, so you won't have all interop functionality available for smart
- `./bin/neo-go wallet dump -w newWallet` to open created wallet in the path `newWallet` contracts (use test invocations via RPC for that).
- `./bin/neo-go wallet init -w newWallet -a` to create new account

29
docs/consensus.md
View file

@ -6,33 +6,32 @@ It uses pure Go dBFT implementation from [nspcc-dev/dbft](https://github.com/nsp
## How to start your own privnet with neo-go nodes ## How to start your own privnet with neo-go nodes
### Using existing Dockerfile ### Using existing Dockerfile
neo-go comes with a preconfigured private network setup that consists of four neo-go comes with two preconfigured private network setups, the first one has
consensus nodes and 6000 blocks to make it more usable out of the box. Nodes four consensus nodes and the second one uses single node. Nodes are packed
are packed into Docker containers with one shared volume for chain data (they into Docker containers and four-node setup shares a volume for chain data.
don't share actual DB, each node has its own DB in this volume). They use ports
20333-20336 for P2P communication and ports 30333-30336 for RPC (Prometheus
monitoring is also available at ports 20001-20004).
On the first container start they import 6K of blocks from a file, these Four-node setup uses ports 20333-20336 for P2P communication and ports
blocks contain several transactions that transfer all NEO into one address and 30333-30336 for RPC (Prometheus monitoring is also available at ports
claim some GAS for it. NEO/GAS owner is: 20001-20004). Single-node is on ports 20333/30333/20001 for
* address: AK2nJJpJr6o664CWJKi1QRXjqeic2zRp8y P2P/RPC/Prometheus.
* wif: KxDgvEKzgSBPPfuVfw67oPQBSjidEiqTHURKSDL1R7yGaGYAeYnr
and you can use it to make some transactions of your own on this privnet. NeoGo default privnet configuration is made to work with four node consensus,
you have to modify it if you're to use single consensus node.
Basically, this setup is closely resembling the one `neo-local` had for C# nodes Node wallets are located in the `.docker/wallets` directory where
before the switch to single-node mode. `wallet1_solo.json` is used for single-node setup and all the other ones for
four-node setup.
#### Prerequisites #### Prerequisites
- `docker` - `docker`
- `docker-compose` - `docker-compose`
- `go` compiler - `go` compiler
#### Instructions #### Instructions
You can use existing docker-compose file located in `.docker/docker-compose.yml`: You can use existing docker-compose file located in `.docker/docker-compose.yml`:
```bash ```bash
make env_image # build image make env_image # build image
make env_up # start containers make env_up # start containers, use "make env_single" for single CN
``` ```
To monitor logs: To monitor logs:
```bash ```bash

48
docs/rpc.md
View file

@ -41,31 +41,37 @@ which would yield the response:
| `getblockhash` | | `getblockhash` |
| `getblockheader` | | `getblockheader` |
| `getblockheadercount` | | `getblockheadercount` |
| `getblocksysfee` | | `getcommittee` |
| `getconnectioncount` | | `getconnectioncount` |
| `getcontractstate` | | `getcontractstate` |
| `getnativecontracts` |
| `getnep17balances` | | `getnep17balances` |
| `getnep17transfers` | | `getnep17transfers` |
| `getnextblockvalidators` |
| `getpeers` | | `getpeers` |
| `getproof` |
| `getrawmempool` | | `getrawmempool` |
| `getrawtransaction` | | `getrawtransaction` |
| `getstateheight` |
| `getstateroot` |
| `getstorage` | | `getstorage` |
| `gettransactionheight` | | `gettransactionheight` |
| `getunclaimedgas` | | `getunclaimedgas` |
| `getvalidators` |
| `getversion` | | `getversion` |
| `invoke` | | `invokecontractverify` |
| `invokefunction` | | `invokefunction` |
| `invokescript` | | `invokescript` |
| `sendrawtransaction` | | `sendrawtransaction` |
| `submitblock` | | `submitblock` |
| `submitoracleresponse` |
| `validateaddress` | | `validateaddress` |
| `verifyproof` |
#### Implementation notices #### Implementation notices
##### `invokefunction` and `invoke` ##### `invokefunction`
neo-go's implementation of `invokefunction` and `invoke` does not return `tx` neo-go's implementation of `invokefunction` does not return `tx`
field in the answer because that requires signing the transaction with some field in the answer because that requires signing the transaction with some
key in the server which doesn't fit the model of our node-client interactions. key in the server which doesn't fit the model of our node-client interactions.
Lacking this signature the transaction is almost useless, so there is no point Lacking this signature the transaction is almost useless, so there is no point
@ -97,23 +103,35 @@ and we're not accepting issues related to them.
| Method | Reason | | Method | Reason |
| ------- | ------------| | ------- | ------------|
| `claimgas` | Doesn't fit neo-go wallet model, use CLI to do that | | `closewallet` | Doesn't fit neo-go wallet model |
| `dumpprivkey` | Shouldn't exist for security reasons, see `claimgas` comment also | | `dumpprivkey` | Shouldn't exist for security reasons, see `closewallet` comment also |
| `getbalance` | To be implemented | | `getnewaddress` | See `closewallet` comment, use CLI to do that |
| `getmetricblocktimestamp` | Not really useful, use other means for node monitoring | | `getwalletbalance` | See `closewallet` comment, use `getnep17balances` for that |
| `getnewaddress` | See `claimgas` comment | | `getwalletunclaimedgas` | See `closewallet` comment, use `getunclaimedgas` for that |
| `getwalletheight` | Not applicable to neo-go, see `claimgas` comment | | `importprivkey` | Not applicable to neo-go, see `closewallet` comment |
| `importprivkey` | Not applicable to neo-go, see `claimgas` comment | | `listaddress` | Not applicable to neo-go, see `closewallet` comment |
| `listaddress` | Not applicable to neo-go, see `claimgas` comment |
| `listplugins` | neo-go doesn't have any plugins, so it makes no sense | | `listplugins` | neo-go doesn't have any plugins, so it makes no sense |
| `sendfrom` | Not applicable to neo-go, see `claimgas` comment | | `openwallet` | Doesn't fit neo-go wallet model |
| `sendmany` | Not applicable to neo-go, see `claimgas` comment | | `sendfrom` | Not applicable to neo-go, see `openwallet` comment |
| `sendmany` | Not applicable to neo-go, see `openwallet` comment |
| `sendtoaddress` | Not applicable to neo-go, see `claimgas` comment | | `sendtoaddress` | Not applicable to neo-go, see `claimgas` comment |
### Extensions ### Extensions
Some additional extensions are implemented as a part of this RPC server. Some additional extensions are implemented as a part of this RPC server.
#### `getblocksysfee` call
This method returns cumulative system fee for all transactions included in a
block. It can be removed in future versions, but at the moment you can use it
to see how much GAS is burned with particular block (because system fees are
burned).
#### `submitnotaryrequest` call
This method can be used on P2P Notary enabled networks to submit new notary
payloads to be relayed from RPC to P2P.
#### Limits and paging for getnep17transfers #### Limits and paging for getnep17transfers
`getnep17transfers` RPC call never returns more than 1000 results for one `getnep17transfers` RPC call never returns more than 1000 results for one

4
pkg/compiler/doc.go Normal file
View file

@ -0,0 +1,4 @@
/*
Package compiler implements Go to NEF smart contract compiler.
*/
package compiler

1
pkg/compiler/native_test.go
View file

@ -71,6 +71,7 @@ func TestContractParameterTypes(t *testing.T) {
func TestRoleManagementRole(t *testing.T) { func TestRoleManagementRole(t *testing.T) {
require.EqualValues(t, native.RoleOracle, roles.Oracle) require.EqualValues(t, native.RoleOracle, roles.Oracle)
require.EqualValues(t, native.RoleStateValidator, roles.StateValidator) require.EqualValues(t, native.RoleStateValidator, roles.StateValidator)
require.EqualValues(t, native.RoleNeoFSAlphabet, roles.NeoFSAlphabet)
require.EqualValues(t, native.RoleP2PNotary, roles.P2PNotary) require.EqualValues(t, native.RoleP2PNotary, roles.P2PNotary)
} }

4
pkg/config/doc.go Normal file
View file

@ -0,0 +1,4 @@
/*
Package config contains NeoGo node configuration definition.
*/
package config

4
pkg/config/netmode/doc.go Normal file
View file

@ -0,0 +1,4 @@
/*
Package netmode contains well-known network magic numbers.
*/
package netmode

2
pkg/config/netmode/netmode.go
View file

@ -6,7 +6,7 @@ const (
// MainNet contains magic code used in the NEO main official network. // MainNet contains magic code used in the NEO main official network.
MainNet Magic = 0x004f454e // 5195086 MainNet Magic = 0x004f454e // 5195086
// TestNet contains magic code used in the NEO testing network. // TestNet contains magic code used in the NEO testing network.
TestNet Magic = 0x3550334E // 894448462 TestNet Magic = 0x744f454e // 1951352142
// PrivNet contains magic code usually used for NEO private networks. // PrivNet contains magic code usually used for NEO private networks.
PrivNet Magic = 56753 // docker privnet PrivNet Magic = 56753 // docker privnet
// UnitTestNet is a stub magic code used for testing purposes. // UnitTestNet is a stub magic code used for testing purposes.

7
pkg/consensus/doc.go Normal file
View file

@ -0,0 +1,7 @@
/*
Package consensus contains Neo consensus node implementation.
It uses external dBFT library for the core algorithm and basically joins this
library with Neo node internals implemented in NeoGo.
*/
package consensus

6
pkg/core/block/doc.go Normal file
View file

@ -0,0 +1,6 @@
/*
Package block contains Neo block definition.
This is one of the core structures of Neo blockchain.
*/
package block

7
pkg/core/interop/doc.go Normal file
View file

@ -0,0 +1,7 @@
/*
Package interop contains implementations of Neo interop functions.
This is not the package you use from smart contracts, refer to pkg/interop
for that.
*/
package interop

4
pkg/core/native/doc.go Normal file
View file

@ -0,0 +1,4 @@
/*
Package native contains Neo native contracts.
*/
package native

6
pkg/core/transaction/doc.go Normal file
View file

@ -0,0 +1,6 @@
/*
Package transaction contains Neo transaction definition.
This is one of the core structures of Neo blockchain.
*/
package transaction

6
pkg/crypto/doc.go Normal file
View file

@ -0,0 +1,6 @@
/*
Package crypto contains implementation of crypto functions used by Neo.
This package itself just has some useful interfaces.
*/
package crypto

6
pkg/crypto/hash/doc.go Normal file
View file

@ -0,0 +1,6 @@
/*
Package hash contains wrappers for Neo hashing algorithms.
It also implements Merkle tree.
*/
package hash

4
pkg/crypto/keys/doc.go Normal file
View file

@ -0,0 +1,4 @@
/*
Package keys wraps public/private keys and implements NEP-2 and WIF.
*/
package keys

4
pkg/encoding/address/doc.go Normal file
View file

@ -0,0 +1,4 @@
/*
Package address implements conversion of script hash to/from Neo address.
*/
package address

4
pkg/encoding/bigint/doc.go Normal file
View file

@ -0,0 +1,4 @@
/*
Package bigint implements Neo-specific big.Int (de)serialization to/from []byte.
*/
package bigint

4
pkg/encoding/fixedn/doc.go Normal file
View file

@ -0,0 +1,4 @@
/*
Package fixedn implements fixed point integers with arbitrary precision.
*/
package fixedn

3
pkg/interop/math/math.go
View file

@ -1,3 +1,6 @@
/*
Package math provides access to useful numeric functions available in Neo VM.
*/
package math package math
import "github.com/nspcc-dev/neo-go/pkg/interop/neogointernal" import "github.com/nspcc-dev/neo-go/pkg/interop/neogointernal"

4
pkg/interop/native/crypto/crypto.go
View file

@ -1,3 +1,7 @@
/*
Package crypto provides interface to CryptoLib native contract.
It implements some cryptographic functions.
*/
package crypto package crypto
import ( import (

4
pkg/interop/native/gas/gas.go
View file

@ -1,3 +1,7 @@
/*
Package gas provides interface to GasToken native contract.
It implements regular NEP-17 functions for GAS token.
*/
package gas package gas
import ( import (

4
pkg/interop/native/ledger/ledger.go
View file

@ -1,3 +1,7 @@
/*
Package ledger provides interface to LedgerContract native contract.
It allows to access ledger contents like transactions and blocks.
*/
package ledger package ledger
import ( import (

4
pkg/interop/native/management/management.go
View file

@ -1,3 +1,7 @@
/*
Package management provides interface to ContractManagement native contract.
It allows to get/deploy/update contracts as well as get/set deployment fee.
*/
package management package management
import ( import (

4
pkg/interop/native/nameservice/name_service.go
View file

@ -1,3 +1,7 @@
/*
Package nameservice provides interface to NameService native contract.
It's a NEP-11 contract implementing a domain name service.
*/
package nameservice package nameservice
import ( import (

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

@ -1,3 +1,9 @@
/*
Package neo provides interface to NeoToken native contract.
NEO token is special, it's not just a regular NEP-17 contract, it also
provides access to chain-specific settings and implements commmittee
voting system.
*/
package neo package neo
import ( import (

5
pkg/interop/native/notary/notary.go
View file

@ -1,3 +1,8 @@
/*
Package notary provides interface to Notary native contract.
This contract is a NeoGo extension and is not available on regular Neo
networks. To use it you need to have this extension enabled on the network.
*/
package notary package notary
import ( import (

5
pkg/interop/native/oracle/oracle.go
View file

@ -1,3 +1,8 @@
/*
Package oracle provides interface to OracleContract native contract.
Oracles allow you to get external (non-blockchain) data using HTTPS or NeoFS
protocols.
*/
package oracle package oracle
import ( import (

4
pkg/interop/native/policy/policy.go
View file

@ -1,3 +1,7 @@
/*
Package policy provides interface to PolicyContract native contract.
This contract holds various network-wide settings.
*/
package policy package policy
import ( import (

9
pkg/interop/native/roles/roles.go
View file

@ -1,3 +1,8 @@
/*
Package roles provides interface to RoleManagement native contract.
Role management contract is used by committee to designate some nodes as
providing some service on the network.
*/
package roles package roles
import ( import (
@ -15,7 +20,9 @@ type Role byte
const ( const (
StateValidator Role = 4 StateValidator Role = 4
Oracle Role = 8 Oracle Role = 8
P2PNotary Role = 128 NeoFSAlphabet Role = 16
// P2PNotary is an extension of Neo protocol available on specifically configured NeoGo networks.
P2PNotary Role = 128
) )
// GetDesignatedByRole represents `getDesignatedByRole` method of RoleManagement native contract. // GetDesignatedByRole represents `getDesignatedByRole` method of RoleManagement native contract.

4
pkg/interop/native/std/std.go
View file

@ -1,3 +1,7 @@
/*
Package std provides interface to StdLib native contract.
It implements various useful conversion functions.
*/
package std package std
import ( import (

5
pkg/interop/neogointernal/doc.go Normal file
View file

@ -0,0 +1,5 @@
/*
Package neogointernal contains definitions of compiler intrinsics.
It's not intended to be used directly by smart contracts.
*/
package neogointernal