== 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
port: 2449
tls:
  enabled: false
proxy:
  host: 0.0.0.0
  port: 8545
  routes:
    - id: eth
      blockchain: ethereum
    - id: kovan
      blockchain: kovan
upstreams:
  upstreams:
    - id: infura-eth
      chain: ethereum
      connection:
        ethereum:
          rpc:
            url: "https://mainnet.infura.io/v3/${INFURA_USER}"
          ws:
            url: "wss://mainnet.infura.io/ws/v3/${INFURA_USER}"
    - id: infura-kovan
      chain: kovan
      connection:
        ethereum:
          rpc:
            url: "https://kovan.infura.io/v3/${INFURA_USER}"
----

This very basic config says that:

- application listen for gRPC connections on 0.0.0.0:2449, with TLS security disabled (_never use in production!_)
- 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_)
- sets up 2 upstreams, one for Ethereum Mainnet and another for Kovan Testnet (both upstreams are configured for Infura for demo purposes, but you can use other compatible endpoints)
- for Ethereum Mainnet it connects using JSON RPC and Websockets connections, for Kovan just JSON RPC is used
- Infura authentication config is omitted for this demo
- `${INFURA_USER}` value can be provided through environment variables

==== 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.
