diff --git a/README.md b/README.md index 6992149f2..888042b72 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ [![codecov](https://codecov.io/gh/nspcc-dev/neo-go/branch/master/graph/badge.svg)](https://codecov.io/gh/nspcc-dev/neo-go) [![CircleCI](https://circleci.com/gh/nspcc-dev/neo-go/tree/master.svg?style=svg)](https://circleci.com/gh/nspcc-dev/neo-go/tree/master) [![Report](https://goreportcard.com/badge/github.com/nspcc-dev/neo-go)](https://goreportcard.com/report/github.com/nspcc-dev/neo-go) +[![GoDoc](https://godoc.org/github.com/nspcc-dev/neo-go?status.svg)](https://godoc.org/github.com/nspcc-dev/neo-go) ![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/nspcc-dev/neo-go?sort=semver) ![License](https://img.shields.io/github/license/nspcc-dev/neo-go.svg?style=popout) @@ -21,11 +22,10 @@ This project aims to be a full port of the original C# [NEO project](https://git A complete toolkit for the NEO blockchain, including: - Consensus node (WIP) -- [RPC node & client](https://github.com/nspcc-dev/neo-go/tree/master/pkg/rpc/README.md) -- [RPC client](https://github.com/nspcc-dev/neo-go/blob/master/pkg/rpc/README.md) -- [CLI tool](https://github.com/nspcc-dev/neo-go/blob/master/cli/README.md) -- [Smart contract compiler](https://github.com/nspcc-dev/neo-go/blob/master/pkg/vm/compiler/README.md) -- [NEO virtual machine](https://github.com/nspcc-dev/neo-go/blob/master/pkg/vm/README.md) +- [RPC node & client](https://github.com/nspcc-dev/neo-go/tree/master/docs/rpc.md) +- [CLI tool](https://github.com/nspcc-dev/neo-go/blob/master/docs/cli.md) +- [Smart contract compiler](https://github.com/nspcc-dev/neo-go/blob/master/docs/compiler.md) +- [NEO virtual machine](https://github.com/nspcc-dev/neo-go/blob/master/docs/vm.md) # Getting started diff --git a/ROADMAP.md b/ROADMAP.md index 78be2f026..1a4c29596 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,4 +1,16 @@ # Roadmap for neo-go -## Version x.x.x -* Define roadmap for this version +This defines approximate plan of neo-go releases and key features planned for +them. + +## Version 0.51.0 (mid-October 2019) +* VM compabitibility with neo-vm for all JSON-based tests in neo-vm +* further refactoring the code +* block verification +* implementing missing protocol messages + +## Version 0.60.0 (mid-November 2019) +* consensus node + +## Version 1.0 (2020, aligned with NEO 3.0 release) +* full NEO 3.0 support diff --git a/cli/README.md b/docs/cli.md similarity index 100% rename from cli/README.md rename to docs/cli.md diff --git a/pkg/vm/compiler/README.md b/docs/compiler.md similarity index 84% rename from pkg/vm/compiler/README.md rename to docs/compiler.md index 88287451e..7d44bfa67 100644 --- a/pkg/vm/compiler/README.md +++ b/docs/compiler.md @@ -23,32 +23,41 @@ The neo-go compiler compiles Go programs to bytecode that the NEO virtual machin - append ### VM API (interop layer) -- storage -- runtime -- block -- header -- transaction +Compiler translates interop function calls into NEO VM syscalls or (for custom +functions) into NEO VM instructions. [Refer to GoDoc](https://godoc.org/github.com/nspcc-dev/neo-go/pkg/interop) for full API documentation. + +#### Standard NEO Smart Contract API +- account - asset +- attribute +- block - blockchain +- contract +- engine +- header +- input +- iterator +- output +- runtime +- storage +- transaction -### VM utility helper functions -- SHA1 -- SHA256 -- Hash256 -- Hash160 -- other.. - -### Custom utility functions -- `FromAddress(address string) []byte` - -## Not yet implemented -- very small part of the interop layer (VM API) +#### Custom VM utility helper functions +- crypto: + - `SHA1` + - `SHA256` + - `Hash256` + - `Hash160` +- enumerator +- util: + - `Equals` (to emit `EQUALS` opcode, not needed usually) + - `FromAddress(address string) []byte` ## Not supported Due to the limitations of the NEO virtual machine, features listed below will not be supported. - channels - goroutines -- multiple returns +- returning multiple values from functions ## Quick start @@ -125,8 +134,12 @@ Will output something like: ``` +At the moment this is implemented via RPC call to the remote server. + ## Smart contract examples +Some examples are provided in the [examples directory](https://github.com/nspcc-dev/neo-go/tree/master/examples). + ### Check if the invoker of the contract is the owning address ```Golang @@ -214,4 +227,3 @@ func Main(operation string, args []interface{}) bool { 2. Create an issue on Github 3. Make a PR with a reference to the created issue, containing the testcase that proves the bug 4. Either you fix the bug yourself or wait for patch that solves the problem - diff --git a/docs/rpc.md b/docs/rpc.md new file mode 100644 index 000000000..6d42ce123 --- /dev/null +++ b/docs/rpc.md @@ -0,0 +1,63 @@ +# RPC + +## Client + +Client is provided as a Go package, so please refer to the +[relevant godocs page](https://godoc.org/github.com/nspcc-dev/neo-go/pkg/rpc). + +## Server + +The server is written to support as much of the [JSON-RPC 2.0 Spec](http://www.jsonrpc.org/specification) as possible. The server is run as part of the node currently. + +### Example call + +An example would be viewing the version of the node: + +```bash +$ curl -X POST -d '{"jsonrpc": "2.0", "method": "getversion", "params": [], "id": 1}' http://localhost:20332 +``` + +which would yield the response: + +```json +{ + "jsonrpc" : "2.0", + "id" : 1, + "result" : { + "port" : 20333, + "useragent" : "/NEO-GO:0.36.0-dev/", + "nonce" : 9318417 + } +} +``` + +### Supported methods + +| Method | Implemented | +| ------- | ------------| +| `getaccountstate` | Yes | +| `getassetstate` | Yes | +| `getbestblockhash` | Yes | +| `getblock` | Yes | +| `getblockcount` | Yes | +| `getblockhash` | Yes | +| `getblocksysfee` | No | +| `getconnectioncount` | Yes | +| `getcontractstate` | No | +| `getpeers` | Yes | +| `getrawmempool` | No | +| `getrawtransaction` | No | +| `getstorage` | No | +| `gettxout` | No | +| `getversion` | Yes | +| `invoke` | No | +| `invokefunction` | No | +| `invokescript` | No | +| `sendrawtransaction` | No | +| `submitblock` | No | +| `validateaddress` | Yes | + +## Reference + +* [JSON-RPC 2.0 Specification](http://www.jsonrpc.org/specification) +* [NEO JSON-RPC 2.0 docs](https://docs.neo.org/en-us/node/cli/apigen.html) diff --git a/pkg/vm/README.md b/docs/vm.md similarity index 67% rename from pkg/vm/README.md rename to docs/vm.md index cff6635d4..5871a6247 100644 --- a/pkg/vm/README.md +++ b/docs/vm.md @@ -4,28 +4,16 @@ A cross platform virtual machine implementation for `avm` compatible programs. # Installation -## With neo-go -Install dependencies. +VM is provided as part of neo-go binary, so usual neo-go build instructions +are applicable. -`neo-go` uses [dep](https://github.com/golang/dep) as its dependency manager. After installing `deps` you can run: - -``` -make deps -``` - -Build the `neo-go` cli: - -``` -make build -``` +# Running the VM Start the virtual machine: ``` -./bin/neo-go vm -``` +$ ./bin/neo-go vm -``` _ ____________ __________ _ ____ ___ / | / / ____/ __ \ / ____/ __ \ | | / / |/ / / |/ / __/ / / / /_____/ / __/ / / /____| | / / /|_/ / @@ -36,9 +24,6 @@ Start the virtual machine: NEO-GO-VM > ``` -## Standalone -More information about standalone installation coming soon. - # Usage ``` @@ -51,24 +36,39 @@ More information about standalone installation coming soon. NEO-GO-VM > help -COMMAND USAGE -astack show alt stack details -break place a breakpoint (> break 1) -cont continue execution of the current loaded script -estack show evaluation stack details -exit exit the VM prompt -help show available commands -ip show the current instruction -istack show invocation stack details -loadavm load an avm script into the VM (> load /path/to/script.avm) -loadgo compile and load a .go file into the VM (> load /path/to/file.go) -loadhex load a hex string into the VM (> loadhex 006166 ) -ops show the opcodes of the current loaded program -run execute the current loaded script -step step (n) instruction in the program (> step 10) +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 + loadavm Load an avm script 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 + + ``` -### Loading in your script +You can get help for each command and its parameters adding `help` as a +parameter to the command: + +``` +NEO-GO-VM > step help + +Usage: step [] + is optional parameter to specify number of instructions to run, example: +> step 10 + +``` + +## Loading in your script To load an avm script into the VM: @@ -111,7 +111,7 @@ NEO-GO-VM > run ``` -### Running programs with arguments +## Running programs with arguments You can invoke smart contracts with arguments. Take the following ***roll the dice*** smartcontract as example. ``` @@ -146,7 +146,10 @@ func rollDice(number int) { To invoke this contract we need to specify both the method and the arguments. -The first parameter (called method or operation) is always of type string. Notice that arguments can have different types, to make the VM aware of the type we need to specify it when calling `run`: +The first parameter (called method or operation) is always of type +string. Notice that arguments can have different types, they can inferred +automatically (please refer to the `run` command help), but in you need to +pass parameter of specific type you can specify it in `run`'s arguments: ``` NEO-GO-VM > run rollDice int:1 @@ -154,45 +157,52 @@ NEO-GO-VM > run rollDice int:1 > The method is always of type string, hence we don't need to specify the type. -To add more then 1 argument: +To add more than 1 argument: ``` NEO-GO-VM > run someMethod int:1 int:2 string:foo string:bar ``` -Current supported types: +Currently supported types: +- `bool (bool:false and bool:true)` - `int (int:1 int:100)` - `string (string:foo string:this is a string)` -### Debugging +## Debugging The `neo-go-vm` provides a debugger to inspect your program in-depth. + +### Stepping through the program Step 4 instructions. ``` NEO-GO-VM > step 4 -at breakpoint 4 (Opush4) -NEO-GO-VM 4 > +at breakpoint 3 (DUPFROMALTSTACK) +NEO-GO-VM 3 > ``` Using just `step` will execute 1 instruction at a time. ``` -NEO-GO-VM > step -instruction pointer at 5 (Odup) -NEO-GO-VM 5 > +NEO-GO-VM 3 > step +at breakpoint 4 (PUSH0) +NEO-GO-VM 4 > ``` +### Breakpoints + To place breakpoints: ``` NEO-GO-VM > break 10 breakpoint added at instruction 10 NEO-GO-VM > cont -at breakpoint 10 (Osetitem) +at breakpoint 10 (SETITEM) NEO-GO-VM 10 > cont ``` +## Inspecting stack + Inspecting the evaluation stack: ``` diff --git a/pkg/core/storage/README.md b/pkg/core/storage/README.md deleted file mode 100644 index 171a62b56..000000000 --- a/pkg/core/storage/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# Storage - diff --git a/pkg/rpc/README.md b/pkg/rpc/README.md deleted file mode 100644 index ba731c751..000000000 --- a/pkg/rpc/README.md +++ /dev/null @@ -1,110 +0,0 @@ -# RPC - -## What - -* Structs used by `JSON-RPC` server and for interacting with a `JSON-RPC` endpoint. -* Server for running the `JSON-RPC` protocol based on port in configuration. - -> This package is currently in `alpha` and is subject to change. - -## Reference - -* [JSON-RPC 2.0 Specification](http://www.jsonrpc.org/specification) -* [NEO JSON-RPC 2.0 docs](https://docs.neo.org/en-us/node/cli/apigen.html) - -## Client - -You can create a new client and start interacting with any NEO node that exposes their -`JSON-RPC` endpoint. See [godocs](https://godoc.org/github.com/CityOfZion/neo-go/pkg/rpc) for example. - -> Not all methods are currently supported in the client, please see table below for supported methods. - -### TODO - -* Merge structs so can be used by both server and client. -* Add missing methods to client. -* Allow client to connect using client cert. - -### Supported methods - -| Method | Implemented | Required to implement | -| ------- | ------------| --------------------- | -| `getblock` | Yes | - | -| `getaccountstate` | Yes | - | -| `invokescript` | Yes | - | -| `invokefunction` | Yes | - | -| `sendrawtransaction` | Yes | - | -| `invoke` | Yes | - | -| `getrawtransaction` | Yes | - | -| `validateaddress` | No | Handler and result struct | -| `getblocksysfee` | No | Handler and result struct | -| `getcontractstate` | No | Handler and result struct | -| `getrawmempool` | No | Handler and result struct | -| `getstorage` | No | Handler and result struct | -| `submitblock` | No | Handler and result struct | -| `gettxout` | No | Handler and result struct | -| `getassetstate` | No | Handler and result struct | -| `getpeers` | No | Handler and result struct | -| `getversion` | No | Handler and result struct | -| `getconnectioncount` | No | Handler and result struct | -| `getblockhash` | No | Handler and result struct | -| `getblockcount` | No | Handler and result struct | -| `getbestblockhash` | No | Handler and result struct | - -## Server - -The server is written to support as much of the [JSON-RPC 2.0 Spec](http://www.jsonrpc.org/specification) as possible. The server is run as part of the node currently. - -### TODO - -* Implement HTTPS server. -* Add remaining methods (Documented below). -* Add Swagger spec and test using dredd in circleCI. - -### Example call - -An example would be viewing the version of the node: - -```bash -$ curl -X POST -d '{"jsonrpc": "2.0", "method": "getversion", "params": [], "id": 1}' http://localhost:20332 -``` - -which would yield the response: - -```json -{ - "jsonrpc" : "2.0", - "id" : 1, - "result" : { - "port" : 20333, - "useragent" : "/NEO-GO:0.36.0-dev/", - "nonce" : 9318417 - } -} -``` - -### Supported methods - -| Method | Implemented | Required to implement | -| ------- | ------------| --------------------- | -| `getblock` | Yes | - | -| `getaccountstate` | Yes | - | -| `invokescript` | No | VM | -| `invokefunction` | No | VM | -| `sendrawtransaction` | No | Needs to be implemented in `pkg/core/blockchain.go` | -| `validateaddress` | Yes | - | -| `getblocksysfee` | No | N/A | -| `getcontractstate` | No | Needs to be implemented in `pkg/core/blockchain.go` | -| `getrawmempool` | No | Needs to be implemented on in `pkg/network/server.go` | -| `getrawtransaction` | No | Needs to be implemented in `pkg/core/blockchain.go` | -| `getstorage` | No | VM | -| `submitblock` | No | Needs to be implemented in `pkg/core/blockchain.go` | -| `gettxout` | No | Needs to be implemented in `pkg/core/blockchain.go` | -| `invoke` | No | VM | -| `getassetstate` | Yes |-| -| `getpeers` | Yes | - | -| `getversion` | Yes | - | -| `getconnectioncount` | Yes | - | -| `getblockhash` | Yes | - | -| `getblockcount` | Yes | - | -| `getbestblockhash` | Yes | - | diff --git a/pkg/rpc/doc.go b/pkg/rpc/doc.go index 36e114081..57246e7ca 100644 --- a/pkg/rpc/doc.go +++ b/pkg/rpc/doc.go @@ -1,7 +1,9 @@ -package rpc - /* -Package rpc provides interaction with a NEO node over JSON-RPC. +Package rpc implements NEO-specific JSON-RPC 2.0 client and server. +This package is currently in alpha and is subject to change. + +Client + After creating a client instance with or without a ClientConfig you can interact with the NEO blockchain by its exposed methods. @@ -29,5 +31,80 @@ An example: log.Println(resp.Result.ScriptHash) log.Println(resp.Result.Balances) -To be continued with more in depth examples. +TODO: + Merge structs so can be used by both server and client. + Add missing methods to client. + Allow client to connect using client cert. + More in-depth examples. + +Supported methods + + getblock + getaccountstate + invokescript + invokefunction + sendrawtransaction + invoke + getrawtransaction + +Unsupported methods + + validateaddress + getblocksysfee + getcontractstate + getrawmempool + getstorage + submitblock + gettxout + getassetstate + getpeers + getversion + getconnectioncount + getblockhash + getblockcount + getbestblockhash + +Server + +The server is written to support as much of the JSON-RPC 2.0 Spec as possible. +The server is run as part of the node currently. + +TODO: + Implement HTTPS server. + Add remaining methods (Documented below). + Add Swagger spec and test using dredd in circleCI. + +Example call + +An example would be viewing the version of the node: + + $ curl -X POST -d '{"jsonrpc": "2.0", "method": "getversion", "params": [], "id": 1}' http://localhost:20332 + +which would yield the response: + + { + "jsonrpc" : "2.0", + "id" : 1, + "result" : { + "port" : 20333, + "useragent" : "/NEO-GO:0.36.0-dev/", + "nonce" : 9318417 + } + } + +Unsupported methods + + getblocksysfee + getcontractstate (needs to be implemented in pkg/core/blockchain.go) + getrawmempool (needs to be implemented on in pkg/network/server.go) + getrawtransaction (needs to be implemented in pkg/core/blockchain.go) + getstorage (lacks VM functionality) + gettxout (needs to be implemented in pkg/core/blockchain.go) + invoke (lacks VM functionality) + invokefunction (lacks VM functionality) + invokescript (lacks VM functionality) + sendrawtransaction (needs to be implemented in pkg/core/blockchain.go) + submitblock (needs to be implemented in pkg/core/blockchain.go) + */ +package rpc