solution: docs for access logging

2021-07-19 23:15:31 -04:00
parent 3a12efd0a0
commit e8fc025966
11 changed files with 141 additions and 25 deletions
--- a/docs/07-methods.adoc
+++ b/docs/07-methods.adoc
@@ -0,0 +1,173 @@
+== Enhanced Methods
+
+IMPORTANT: Dshackle provides an enhanced API based on gRPC and Protobuf, in addition to JSON RPC proxy
+
+Dshackle provides an enhanced and unified API based on HTTP2, gRPC and Protobuf.
+It works in addition to JSON RPC proxy and can be used separately.
+Clients can be generated for all major programming languages, and there're official libraries for Java and Javascript.
+
+NOTE: It's not necessary to use gRPC, as Dshackle can provide standard JSON RPC proxy, but Dshackle gRPC interface improves performance and provides additional features.
+
+=== gRPC definition
+
+The source code for the Protobuf definitions could be found in link:../proto/[/proto].
+
+.Service API
+[source,proto]
+----
+service Blockchain {
+    rpc SubscribeHead (Chain) returns (stream ChainHead) {}
+    rpc SubscribeBalance (BalanceRequest) returns (stream AddressBalance) {}
+    rpc SubscribeTxStatus (TxStatusRequest) returns (stream TxStatus) {}
+
+    rpc GetBalance (BalanceRequest) returns (stream AddressBalance) {}
+
+    rpc NativeCall (NativeCallRequest) returns (stream NativeCallReplyItem) {}
+
+    rpc Describe (DescribeRequest) returns (DescribeResponse) {}
+    rpc SubscribeStatus (StatusRequest) returns (stream ChainStatus) {}
+}
+----
+
+=== Wrapped JSON RPC methods
+
+To call standard JSON RPC methods provided by Ethereum/Bitcoin you use `NativeCall` wrapping method, which provides additional flexibility and configuration for the calls.
+
+.NativeCallRequest
+[source,proto]
+----
+message NativeCallRequest {
+    ChainRef chain = 1;
+    repeated NativeCallItem items = 2;
+    Selector selector = 3;
+    int32 quorum = 4;
+    AvailabilityEnum min_availability = 5;
+}
+
+message NativeCallItem {
+    uint32 id = 1;
+    string method = 3;
+    bytes payload = 4;
+}
+----
+
+Where:
+
+- `chain` target chain (see reference for ids)
+- `items` as a list of independent requests, which may be executed in different nodes in parallels or in different order, with:
+* `method` - a JSON RPC standard name, ex: `eth_getBlockByHash`
+* `payload` - list of parameters for the methods, encoded as JSON string, ex. `["0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", true]`
+- `Selector` and `AvailabilityEnum` are described in reference, in short they allow to specify which nodes must be selected
+to execute the reques (i.e. "execute only on an archive node")
+
+.NativeCallReplyItem
+[source,proto]
+----
+
+message NativeCallReplyItem {
+    uint32 id = 1;
+    bool succeed = 2;
+    bytes payload = 3;
+    bytes error = 4;
+}
+----
+
+Where:
+
+- `payload` is JSON response for a particular call (`result` field), encoded into a string (`succeed` is true)
+- or `error` if request failed (`succeed` is false)
+
+NOTE: Reply Items comes right after their execution on an upstream, therefore streaming response.
+It allows to build non-blocking queries
+
+=== SubscribeHead
+
+This methods provides subscription to the new blocks on the specified chain.
+Returns stream of blocks right after it was accepted (and verified by Dshackle) by any of the upstreams.
+
+.ChainHead
+[source,proto]
+----
+message ChainHead {
+    ChainRef chain = 1;
+    uint64 height = 2;
+    string block_id = 3;
+    uint64 timestamp = 4;
+    bytes weight = 5;
+    uint64 reorg = 6;
+}
+----
+
+Where:
+
+- `chain` - chain id
+- `height` - block number
+- `block_id` - block hash, as a string (please note that it doesn't have `0x` prefix)
+- `timestamp` - timestamp of that block
+- `weight` - total network difficulty on that block, as raw bytes
+- `reorg` - number of reorganized blocks, if reorg happened
+
+=== SubscribeBalance or GetBalance
+
+Subscribes to changes (`SubscribeBalance`) or get current (`GetBalance`) balance for a single address, or a set of addresses.
+By default, it supports only main protocol coin (i.e. `bitcoin`, `ether`), but can be configured to support ERC-20 on Ethereum (see link:reference-configuration.adoc[Reference Configuration])
+
+.Request
+[source,proto]
+----
+message BalanceRequest {
+    Asset asset = 1;
+    AnyAddress address = 2;
+}
+
+message AnyAddress {
+    oneof addr_type {
+        SingleAddress address_single = 1;
+        MultiAddress address_multi = 2;
+        XpubAddress address_xpub = 3;
+        ReferenceAddress address_ref = 4;
+    }
+}
+----
+
+.Response
+[source,proto]
+----
+message AddressBalance {
+    Asset asset = 1;
+    SingleAddress address = 2;
+    string balance = 3;
+}
+----
+
+==== SubscribeTxStatus
+
+Subscribes to transaction confirmations.
+Allows to send a transactions and then listen to all changes until it gets enough confirmations.
+Changes are `NOTFOUND -> BROADCASTED <- -> MINED <- -> CONFIRMED`
+
+.Request
+[source,proto]
+----
+message TxStatusRequest {
+    ChainRef chain = 1;
+    string tx_id = 2;
+    uint32 confirmation_limit = 3;
+}
+----
+
+.Response (stream of)
+[source,proto]
+----
+message TxStatus {
+    string tx_id = 1;
+    bool broadcasted = 2;
+    bool mined = 3;
+    BlockInfo block = 4;
+    uint32 confirmations = 5;
+}
+----
+
+=== gRPC Client Libraries
+
+See link:11-client-libraries.adoc[Client Libraries] documentation.