178 lines
5.3 KiB
Plaintext
178 lines
5.3 KiB
Plaintext
== 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:
|
|
[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: infura-eth
|
|
chain: 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>
|
|
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> `${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.
|
|
|
|
See detailed link:reference-configuration.adoc[Configuration Reference]
|
|
|
|
==== Run as docker
|
|
|
|
Official Docker image you can find at: https://hub.docker.com/r/emeraldpay/dshackle[emeraldpay/dshackle]
|
|
|
|
.Setup Infura username
|
|
[source,bash]
|
|
----
|
|
export INFURA_USER=...
|
|
----
|
|
|
|
.Run Dshackle
|
|
[source,bash]
|
|
----
|
|
docker run -p 2449:2449 -p 8545:8545 -v $(pwd):/etc/dshackle -e "INFURA_USER=$INFURA_USER" emeraldpay/dshackle:0.10
|
|
----
|
|
|
|
==== 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 -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:
|
|
[source,bash]
|
|
----
|
|
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 link:07-methods.adoc[Documentation for Enhanced Methods]
|