TrueCloudLab/neoneo-go
7
0
Fork 2
Code Issues Pull requests Projects Releases Packages Wiki Activity

rpc: split README into developer and user parts

Browse source 
Most of the document is written for developers and thus belongs to
godoc. User-related document is now moved to docs as per #339.
This commit is contained in:
Roman Khimov 2019-09-18 10:55:39 +03:00
parent 778d29f543
commit 9441c5e77b
4 changed files with 145 additions and 116 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
README.md
View file

@ -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)

63
docs/rpc.md Normal file
View file

@ -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)

110
pkg/rpc/README.md
View file

@ -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 | - |

85
pkg/rpc/doc.go
View file

@ -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