Emerald Dshackle is a Fault Tolerant Load Balancer for Blockchain API.

The goal of the Emerald Dshackle is to provide a stable routing to multiple nodes, and ensure that each request is executed on an appropriate provider. It considers nodes locations, state, current height, RPC methods it can provide and other characteristics.

It tries to recover from connection errors, faulty nodes, invalid responses, etc. If upstream lags behind others, lost peers below required, started to resync or went down, then Dshackle temporarily excludes it from requests and returns it when the upstream problem is fixed.

The upstreams may be blockchain nodes such as Bitcoind, Geth, Parity, or public providers like Infura, QuickNode, etc. It automatically verifies their availability and the current status of the network, executes commands making sure that the response is consistent and/or data successfully broadcast to the network.

Provides:

• Standard Bitcoin and Ethereum JSON RPC API over HTTP and WebSocket

• Enhanced gRPC-based API, with upstream selection, async execution, etc

• Secure TLS with optional client authentication

• Blockchain-aware edge caching, in memory and Redis

• Routing based on data availability (peers, height, sync status)

• Data consistency, it always gives a most actual state

• Automatic failover and retry

• Separate public blockchain nodes from your internal servers

Blockchains support:

• Ethereum and Ethereum Classic

• Kovan, Goerli, Ropsten, Rinkeby testnets

• Bitcoin

• Bitcoin testnet

• ❏ Subscription to bitcoind notification over gRPC (instead of ZeroMQ)

• ❏ Lightweight sidecar node connector

• ❏ Configurable upstream roles

Configuration

version: v1
port: 2449
tls:
  enabled: false

proxy:
  host: 0.0.0.0
  port: 8545
  routes:
    - id: eth
      blockchain: ethereum
    - id: kovan
      blockchain: kovan
    - id: btc
      blockchain: bitcoin

cluster:
  upstreams:
    - id: infura-eth
      chain: ethereum
      connection:
        ethereum:
          rpc:
            url: "https://mainnet.infura.io/v3/${INFURA_USER}"
          ws:
            url: "wss://mainnet.infura.io/ws/v3/${INFURA_USER}"
    - id: infura-kovan
      chain: kovan
      connection:
        ethereum:
          rpc:
            url: "https://kovan.infura.io/v3/${INFURA_USER}"
          ws:
            url: "wss://kovan.infura.io/ws/v3/${INFURA_USER}"
    - id: bitcoin-main
      chain: bitcoin
      connection:
        bitcoin:
          rpc:
            url: "http://localhost:8332"
            basic-auth:
              username: bitcoin
              password: mypassword

export INFURA_USER=...

docker run -p 2449:2449 -p 8545:8545 -v $(pwd):/etc/dshackle -e "INFURA_USER=$INFURA_USER" emeraldpay/dshackle:0.12

curl --request POST \
  --url http://localhost:8545/eth \
  --header 'content-type: application/json' \
  --data '{"jsonrpc":"2.0", "method":"eth_getBalance", "id":1, "params":["0x690b2bdf41f33f9f251ae0459e5898b856ed96be", "latest"]}'

{"jsonrpc":"2.0","id":1,"result":"0x72fa5e0181"}

websocat ws://localhost:8545/eth

> | {"jsonrpc":"2.0", "id": 1, "method": "eth_subscribe", "params": ["newHeads"]}

< | {"jsonrpc":"2.0","id":1,"result":"1f8"}
< | {"jsonrpc":"2.0","method":"eth_subscription","params":{"result":{....},"subscription":"1f8"}}

grpcurl -import-path ./proto/ -proto blockchain.proto -d '{\"type\": 100}' -plaintext 127.0.0.1:2449 emerald.Blockchain/SubscribeHead

{
  "chain": "CHAIN_ETHEREUM",
  "height": 8396159,
  "blockId": "fc58a258adccc94466ae967b1178eea721349b0667f59d5fe1b0b436460bce75",
  "timestamp": 1566423564000,
  "weight": "AnMcf2VJB5kOSQ=="
}
{
  "chain": "CHAIN_ETHEREUM",
  "height": 8396160,
  "blockId": "787899711b862b77df8d2faa69de664048598265a9f96abf178d341076e200e0",
  "timestamp": 1566423574000,
  "weight": "AnMch35tO6hSGg=="
}
...
...

grpcurl -import-path ./proto/ -proto blockchain.proto -d '{\"asset\": {\"chain\": \"100\", \"code\": \"ether\"}, \"address\": {\"address_single\": {\"address\": \"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\"}}}' -plaintext 127.0.0.1:2449 emerald.Blockchain/SubscribeBalance

{
  "asset": {
    "chain": "CHAIN_ETHEREUM",
    "code": "ETHER"
  },
  "address": {
    "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
  },
  "balance": "2410941696896999943701015"
}
{
  "asset": {
    "chain": "CHAIN_ETHEREUM",
    "code": "ETHER"
  },
  "address": {
    "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
  },
  "balance": "2410930748488073834320430"
}
...

For detailed documentation see docs/ directory.

JSON RPC

Java gRPC Client

repositories {
    maven { url  "https://maven.emrld.io" }
}

dependencies {
    implementation 'io.emeraldpay:emerald-api:0.9.2'
}

Javascript gRPC Client

"dependencies": {
    "@emeraldpay/api-node": "0.2.0-beta.1",
}

Setting up environment

Build Dshackle

gradle build

gradle distZip

gradle jib -Pdocker=gcr.io/myproject

Development Chat

Want to support the project, prioritize a specific feature, or get commercial help with using Dshackle in your project? Please contact [email protected] to discuss the possibility

Copyright 2021 EmeraldPay, Inc

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.