Skip to content

Latest commit

 

History

History
179 lines (154 loc) · 5.38 KB

02-quick-start.adoc

File metadata and controls

179 lines (154 loc) · 5.38 KB
Raw

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: infura-eth
      blockchain: ethereum # (5)
      connection:
        ethereum:
          rpc: # (6)
            url: "https://mainnet.infura.io/v3/${INFURA_USER}" # (7)
          ws: # (8)
            url: "wss://mainnet.infura.io/ws/v3/${INFURA_USER}"
    - id: local-eth # (9)
      blockchain: ethereum
      connection:
        ethereum:
          rpc:
            url: "http://192.168.1.100:8545/" # (10)
          ws:
            url: "ws://192.168.1.100:8546"
    - id: bitcoin-main
      blockchain: 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. ${INFURA_USER} value is provided through environment variable

  8. in addition to HTTPS is uses Websocket protocol to connect to Infura, 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 Infura and the local node.

Run as docker

Official Docker image you can find at: emeraldpay/dshackle

Setup Infura username
export INFURA_USER=...
Run Dshackle
docker run -p 2449:2449 -p 8545:8545 -v $(pwd):/etc/dshackle -e "INFURA_USER=$INFURA_USER" emeraldpay/dshackle:0.15

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 -import-path ./proto/ -proto blockchain.proto -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.

You can also subscribe to balances changes of the balance on an address:
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
and see how balance of the contract responsible for Wrapped Ether is changing:
{
  "asset": {
    "chain": "CHAIN_ETHEREUM",
    "code": "ETHER"
  },
  "address": {
    "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
  },
  "balance": "2410941696896999943701015"
}
{
  "asset": {
    "chain": "CHAIN_ETHEREUM",
    "code": "ETHER"
  },
  "address": {
    "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
  },
  "balance": "2410930748488073834320430"
}
...

See other enhanced methods in the Documentation for Enhanced Methods