Skip to content

Latest commit

 

History

History
281 lines (194 loc) · 8.41 KB

quickstart.md

File metadata and controls

281 lines (194 loc) · 8.41 KB
Raw

Quick Start

Follow the guide on this page to run either a broker or a worker node:

  • Broker nodes are nodes that are responsible for connecting to each party and validate incoming data, and broadcast the results for consumers.
  • Worker nodes are nodes that only validate data, but they don't store any of the validated data points. It's easier to set up a worker node than a broker node.
  • Consumer nodes are nodes that consume data from the brokers and store them in a database. They don't validate data, but they have the ability to store the network's results and provide a standard GraphQL for easy exploring. you can set a local Postgres instance or use DBaaS such as Neon, AWS RDS, ElephantSQL or any other.

You can setup a node using a docker deployment or local deployment:

  • Docker deployment requires Docker and makes the installation and management of the node straighforward.
  • Local deployment runs Unchained locally on your machine and requires you to manually setup Unchained.

Using Docker

Running Unchained with Docker is straightforward. Make sure you have Docker installed. Then, head over to the Unchained release page on GitHub, find the latest Docker release file (file name ends with -docker.zip), download it, and uncompress it.

Once done, head to the uncompressed release directory.

Node types

The docker deployment is compatible with the 3 different node types:

  • broker: Unchained and Postgres run in Docker.
  • worker: Unchained runs in Docker, no need for Postgres.
  • remote: Unchained runs in Docker, Postgres runs elsewhere.

Choose which node type you'd like to run on your machine.

Configuring your node

Prerequisites

Create a directory for the config files to be mounted in your docker container:

mkdir conf

Broker node

Make a copy of the environment template:

cp .env.template conf/.env

Edit the newly created file with a username and password of your choice for Postgres and Grafana.

Make a copy of the broker configuration template:

cp conf.broker.yaml.template conf/conf.broker.yaml

Edit the newly created file. Set a name for your node. Set the Postgres username, password, and database name to the ones you defined in the previous step. Set the host of the Postgres local instance to postgres, and the port to 5432.

Worker node

Make a copy of the worker configuration template:

cp conf.worker.yaml.template conf/conf.worker.yaml

Edit the newly created file and set a name for your node.

Remote node

Make a copy of the remote configuration template:

cp conf.remote.yaml.template conf/conf.remote.yaml

Edit the newly created file. Set a name for your node. Set the Postgres username, password, database name, host, and port to the ones of your DBaaS instance.

Managing your node

To manage your node, use the following commands in your favorite terminal emulator.

Start Node

To start the node, run this command while in the release directory:

./unchained.sh [node] up -d

Note: If you are running the node for the first time, Unchained will generate a random secret key. This key will be saved to the conf/secrets.<NODE_TYPE>.yaml file. It is your responsibility to keep this file safe.

Stop Node

To stop the node, run this command while in the release directory:

./unchained.sh [node] stop

Restart Node

To restart the node, run this command while in the release directory:

./unchained.sh [node] restart

View Node

To view the node, run this command while in the release directory:

./unchained.sh [node] logs -f

Update Node

To update the node to the latest docker image version, run this command while in the release directory:

./unchained.sh [node] pull
./unchained.sh [node] up -d --force-recreate

Grafana Dashboard

Running a local node starts a Grafana dashboard instance on port 3000. You can access it in your browser by visiting http://localhost:3000. You must set username and password of your Grafana instance in the .env file mentioned above.

Installing Locally

Follow these instructions if you want to install Unchained and its dependencies locally, on a RaspberryPi, on a server, or on your computer/laptop.

Prerequisites

To run a Unchained node, you need to download the latest release. Head over to the Unchained release page on GitHub, find the latest release corresponding to your architecture and OS and download it.

On Unix-like operating systems, you'll first need to make the file executable:

chmod +x unchained.OS.ARCH

Updates

To get the latest update of Unchained, you can download the latest release on the Unchained release page.

Postgres

Note: Skip this step if you're not planning to run a consumer node.

To run a consumer node, you need to have an instance of Postgres. You can either run your own, or make a subscription to a cloud service.

Contact us on Telegram if you need help with this step.

Installing Postgres Locally

If you want to install Postgres locally, first follow the official Postgres installation instructions, then use the following url in your Unchained config file:

postgres://<user>:<pass>@localhost:5432/<database>

Replace <user>, <pass>, and <database> with the user, password, and name of the database you have created.

Configuration

You need a configuration file to get started. You can start with the following config:

system:
  log: info
  name: <name>

network:
  bind: 127.0.0.1:9123
  broker-uri: ws://127.0.0.1:9123

rpc:
  - name: ethereum
    nodes:
      - https://ethereum.publicnode.com
      - https://eth.llamarpc.com
      - wss://ethereum.publicnode.com
      - https://eth.rpc.blxrbdn.com

  - name: arbitrumSepolia
    nodes:
      - https://sepolia-rollup.arbitrum.io/rpc

plugins:
  uniswap:
    schedule:
      ethereum: 5s

    tokens:
      - name: ethereum
        chain: ethereum
        pair: "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
        delta: 12
        invert: true
        unit: USDT
        send: true

      - name: arbitrum
        chain: ethereum
        pair: "0x59354356Ec5d56306791873f567d61EBf11dfbD5"
        delta: 0
        invert: false
        unit: ETH
        send: true

      - name: bitcoin
        chain: ethereum
        pair: "0x9db9e0e53058c89e5b94e29621a205198648425b"
        delta: 2
        invert: false
        unit: USDT
        send: true

Save the above configuration in a file named conf.yaml on your system and make the following modifications if required:

  • log: Defines the validator log level. Change it to silly or debug to see all messages. Leaving this at info level gives you all the important messages.
  • name: This name will be associated with your validator node, and is published to all peers.
  • rpc.ethereum: Unchained testnet has automatic RPC rotation and renewal when issues are detected with the RPC connection. You can find a list of Ethereum RPC nodes on Chainlist.
  • plugins.uniswap.tokens: UniSwap V3 pool information for fetching and indexing token prices.

You can also use RPC nodes that start with wss:// instead of https://.

Starting an Unchained worker node

To start a worker node and join the Unchained network, you need to run the following command (in CMD or terminal, depending on your OS) in the directory where you saved the above configuration file:

unchained.OS.ARCH worker

**Note: If you are running the node for the first time, Unchained needs to have permission to generating a random secret key (You can pass this permission with -a flag) . This key will be saved to the secrets.yaml file and it is your responsibility to keep this file safe. If the app can't find the secret file location and doesn't have permission to generate it, it leads to panic and exits the app with an error **

Help

Running the following command in CMD or terminal should give you a list of available options for the validator CLI tool:

unchained help

If you need more help, reach out on Telegram.