== 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: infura-eth
      chain: ethereum # <5>
      method-groups:
       enabled:
         - trace
      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,subs="attributes"]
----
docker run -p 2449:2449 -p 8545:8545 -v $(pwd):/etc/dshackle -e "INFURA_USER=$INFURA_USER" emeraldpay/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 -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]
