From 9441c5e77ba98741c4494af87c594ee6441762c0 Mon Sep 17 00:00:00 2001 From: Roman Khimov Date: Wed, 18 Sep 2019 10:55:39 +0300 Subject: [PATCH] rpc: split README into developer and user parts Most of the document is written for developers and thus belongs to godoc. User-related document is now moved to docs as per #339. --- README.md | 3 +- docs/rpc.md | 63 ++++++++++++++++++++++++++ pkg/rpc/README.md | 110 ---------------------------------------------- pkg/rpc/doc.go | 85 +++++++++++++++++++++++++++++++++-- 4 files changed, 145 insertions(+), 116 deletions(-) create mode 100644 docs/rpc.md delete mode 100644 pkg/rpc/README.md diff --git a/README.md b/README.md index 2c919b68d..240add95d 100644 --- a/README.md +++ b/README.md @@ -22,8 +22,7 @@ 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) +- [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/pkg/vm/README.md) 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/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