== 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}"
          ws: # <7>
            url: "wss://mainnet.infura.io/ws/v3/${INFURA_USER}"
    - id: infura-kovan
      chain: kovan # <8>
      connection:
        ethereum:
          rpc:
            url: "https://kovan.infura.io/v3/${INFURA_USER}" # <9>
----
<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> Websocket conection
<8> and another for Kovan Testnet
<9> `${INFURA_USER}` value is provided through environment variable

Both upstreams are configured for Infura for demo purposes, but you can use other compatible endpoints.
Infura authentication is omitted for this demo

==== Run as docker

Official Docker image you can find at: 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
----

==== 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 io.emeraldpay.api.Blockchain/SubscribeHead
----

.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 a method provided by Dshackle, available in additional to methods provided by RPC JSON of underlying nodes.