diff --git a/rpc/core/README.md b/rpc/core/README.md new file mode 100644 index 000000000..7dff4dfca --- /dev/null +++ b/rpc/core/README.md @@ -0,0 +1,15 @@ +# Tendermint RPC + +## Generate markdown for [Slate](https://github.com/tendermint/slate) + +We are using [Slate](https://github.com/lord/slate) to power our RPC +documentation. If you are changing a comment, make sure to copy the resulting +changes to the slate repo and make a PR +[there](https://github.com/tendermint/slate) as well. For generating markdown +use: + +```shell +go get github.com/melekes/godoc2md + +godoc2md -template rpc/core/doc_template.txt github.com/tendermint/tendermint/rpc/core | grep -v -e "pipe.go" -e "routes.go" -e "dev.go" | sed 's$/src/target$https://github.com/tendermint/tendermint/tree/master/rpc/core$' +``` diff --git a/rpc/core/doc.go b/rpc/core/doc.go new file mode 100644 index 000000000..7902ade25 --- /dev/null +++ b/rpc/core/doc.go @@ -0,0 +1,107 @@ +/* +# Introduction + +Tendermint supports the following RPC protocols: + +* URI over HTTP +* JSONRPC over HTTP +* JSONRPC over websockets + +Tendermint RPC is build using [our own RPC library](https://github.com/tendermint/tendermint/tree/master/rpc/lib). Documentation and tests for that library could be found at `tendermint/rpc/lib` directory. + +## Configuration + +Set the `laddr` config parameter under `[rpc]` table in the `$TMHOME/config.toml` file or the `--rpc.laddr` command-line flag to the desired protocol://host:port setting. Default: `tcp://0.0.0.0:46657`. + +## Arguments + +Arguments which expect strings or byte arrays may be passed as quoted strings, like `"abc"` or as `0x`-prefixed strings, like `0x616263`. + +## URI/HTTP + +```bash +curl 'localhost:46657/broadcast_tx_sync?tx="abc"' +``` + +> Response: + +```json +{ + "error": "", + "result": { + "hash": "2B8EC32BA2579B3B8606E42C06DE2F7AFA2556EF", + "log": "", + "data": "", + "code": 0 + }, + "id": "", + "jsonrpc": "2.0" +} +``` + +The first entry in the result-array (`96`) is the method this response correlates with. `96` refers to "ResultTypeBroadcastTx", see [responses.go](https://github.com/tendermint/tendermint/blob/master/rpc/core/types/responses.go) for a complete overview. + +## JSONRPC/HTTP + +JSONRPC requests can be POST'd to the root RPC endpoint via HTTP (e.g. `http://localhost:46657/`). + +```json +{ + "method": "broadcast_tx_sync", + "jsonrpc": "2.0", + "params": [ "abc" ], + "id": "dontcare" +} +``` + +## JSONRPC/websockets + +JSONRPC requests can be made via websocket. The websocket endpoint is at `/websocket`, e.g. `localhost:46657/websocket`. Asynchronous RPC functions like event `subscribe` and `unsubscribe` are only available via websockets. + + +## More Examples + +See the various bash tests using curl in `test/`, and examples using the `Go` API in `rpc/client/`. + +## Get the list + +An HTTP Get request to the root RPC endpoint shows a list of available endpoints. + +```bash +curl 'localhost:46657' +``` + +> Response: + +```plain +Available endpoints: +/abci_info +/dump_consensus_state +/genesis +/net_info +/num_unconfirmed_txs +/status +/unconfirmed_txs +/unsafe_flush_mempool +/unsafe_stop_cpu_profiler +/validators + +Endpoints that require arguments: +/abci_query?path=_&data=_&prove=_ +/block?height=_ +/blockchain?minHeight=_&maxHeight=_ +/broadcast_tx_async?tx=_ +/broadcast_tx_commit?tx=_ +/broadcast_tx_sync?tx=_ +/commit?height=_ +/dial_seeds?seeds=_ +/subscribe?event=_ +/tx?hash=_&prove=_ +/unsafe_start_cpu_profiler?filename=_ +/unsafe_write_heap_profile?filename=_ +/unsubscribe?event=_ +``` + +# Endpoints +*/ +package core diff --git a/rpc/core/doc_template.txt b/rpc/core/doc_template.txt new file mode 100644 index 000000000..896d0c271 --- /dev/null +++ b/rpc/core/doc_template.txt @@ -0,0 +1,8 @@ +{{with .PDoc}} +{{comment_md .Doc}} +{{example_html $ ""}} + +{{range .Funcs}}{{$name_html := html .Name}}## [{{$name_html}}]({{posLink_url $ .Decl}}) +{{comment_md .Doc}}{{end}} +{{end}} +---