Skip to content

Latest commit

 

History

History
173 lines (137 loc) · 4.9 KB

07-methods.adoc

File metadata and controls

173 lines (137 loc) · 4.9 KB

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 /proto.

Service API
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
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
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
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 Reference Configuration)

Request
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
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
message TxStatusRequest {
    ChainRef chain = 1;
    string tx_id = 2;
    uint32 confirmation_limit = 3;
}
Response (stream of)
message TxStatus {
    string tx_id = 1;
    bool broadcasted = 2;
    bool mined = 3;
    BlockInfo block = 4;
    uint32 confirmations = 5;
}

gRPC Client Libraries

See Client Libraries documentation.