Quick Start

Prerequisites

Dshackle is designed for the cloud environment and supposed to be used withing Docker and/or Kubernetes. However, it’s a JVM based application and, therefore, can be used in most of the standard environments where Java Virtual Machine can be installed.

We’re going to use Docker image for this quick start.

For demo access, we use gRPCurl tool, which can be installed from https://github.com/fullstorydev/grpcurl

Configuration

Note
 you can find following example configuration in demo/quick-start directory of the project

Create file dshackle.yaml with following content:

version: v1
host: 0.0.0.0 # (1)
port: 2449
tls: # (2)
  enabled: false
proxy:
  host: 0.0.0.0 # (3)
  port: 8545
  routes:
    - id: eth
      blockchain: ethereum
    - id: kovan
      blockchain: kovan
cluster:
  upstreams: # (4)
    - id: drpc-eth
      chain: ethereum # (5)
      method-groups:
       enabled:
         - trace
      connection:
        ethereum:
          rpc: # (6)
            url: "https://lb.drpc.org/ogrpc?network=ethereum&dkey=${DRPC_KEY}" # (7)
          ws: # (8)
            url: "wss://lb.drpc.org/ogws?network=ethereum&dkey=${DRPC_KEY}"
    - id: local-eth # (9)
      chain: ethereum
      connection:
        ethereum:
          rpc:
            url: "http://192.168.1.100:8545/" # (10)
          ws:
            url: "ws://192.168.1.100:8546"
    - id: bitcoin-main
      chain: bitcoin # (11)
      connection:
        bitcoin:
          rpc:
            url: "http://localhost:8332"
            basic-auth: # (12)
              username: bitcoin
              password: test

  1. application listen for gRPC connections on 0.0.0.0:2449

  2. with TLS security for gRPC disabled (never use in production!)

  3. listen for HTTP JSON RPC connections on 0.0.0.0:8545, without TLS security too (again, don’t use in production, it’s insecure)

  4. sets up 2 upstreams

  5. one for Ethereum Mainnet, using

  6. HTTP and

  7. ${DRPC_KEY} value is provided through environment variable

  8. in addition to HTTPS is uses Websocket protocol to connect to DRPC, used to subscribe to updates

  9. setup another upstream for Ethereum Mainnet

  10. which connects to a node in the internal networks, without any authentication at this case

  11. and another for Bitcoin

  12. with Basic Auth for bitcoin node connection

The configuration above sets up the Dshackle to provide a fault-tolerant access to Bitcoin and Ethereum blockchain. And for Ethereum, at this particular example, it uses a Round Robin Load Balancing over the DRPC and the local node.

See detailed Configuration Reference

Run as docker

Official Docker image you can find at: drpcorg/dshackle

Setup DRPC key
export DRPC_KEY=...
Run Dshackle
docker run -p 2449:2449 -p 8545:8545 -v $(pwd):/etc/dshackle -e "DRPC_KEY=$DRPC_KEY" drpcorg/dshackle:0.12

Access using JSON RPC

Dshackle implements standard JSON RPC interface, providing additional caching layer, upstream readiness/liveness checks, retry and other features for building Fault Tolerant services.

Request using Curl
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"]}'
Output
{"jsonrpc":"2.0","id":1,"result":"0x72fa5e0181"}

Access using gRPC

Connect and listen for new blocks on Ethereum Mainnet
grpcurl -d "{\"type\": 100}" -plaintext 127.0.0.1:2449 emerald.Blockchain/SubscribeHead

type: 100 specifies the blockchain id, and 100 means Ethereum Mainnet.

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

The output above is for a streaming subscription to all new blocks on Ethereum Mainnet. It’s one of the services provided by Dshackle, in addition to standard methods provided by RPC JSON of underlying nodes.

See other enhanced methods in the Documentation for Enhanced Methods