152 lines
4.5 KiB
Plaintext
152 lines
4.5 KiB
Plaintext
== Quick Start
|
|
:version: 0.12.0
|
|
:version-short: 0.12
|
|
|
|
=== 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:
|
|
[source,yaml]
|
|
----
|
|
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 xref:reference-configuration.adoc[Configuration Reference]
|
|
|
|
==== Run as docker
|
|
|
|
Official Docker image you can find at: https://hub.docker.com/r/drpcorg/dshackle[drpcorg/dshackle]
|
|
|
|
.Setup DRPC key
|
|
[source,bash]
|
|
----
|
|
export DRPC_KEY=...
|
|
----
|
|
|
|
.Run Dshackle
|
|
[source,bash,subs="attributes"]
|
|
----
|
|
docker run -p 2449:2449 -p 8545:8545 -v $(pwd):/etc/dshackle -e "DRPC_KEY=$DRPC_KEY" drpcorg/dshackle:{version-short}
|
|
----
|
|
|
|
==== 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
|
|
[source,bash]
|
|
----
|
|
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
|
|
[source,bash]
|
|
----
|
|
{"jsonrpc":"2.0","id":1,"result":"0x72fa5e0181"}
|
|
----
|
|
|
|
==== Access using gRPC
|
|
|
|
.Connect and listen for new blocks on Ethereum Mainnet
|
|
[source,bash]
|
|
----
|
|
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 xref:07-methods.adoc[Documentation for Enhanced Methods]
|