Development Tips

Hello Chainlink

We have an area of example apps, Hello Chainlink, that you may find useful when developing apps that use Chainlink.

Local Development Quickstart

In order to make it easy to develop locally with Ethereum, we have packaged up an Ethereum development network in a docker node, and pre-funded an account for your development Chainlink node.

In order to use devnet:

1. Install Docker

2. Add the chainlink repo's subdirectory tools/bin to your path via direnv. If you don't want to add those to your path, just prefix all {devnet,cldev} commands with ./tools/bin/.

3. Open a new window and start the network:

devnet

4. Deploy the related contracts:

cd solidity && yarn install
truffle migrate --network development

5. Run your local version of Chainlink against devnet (needs to be invoked from the chainlink directory):

cldev node

6. Open a new window and explore devnet via a truffle console:

cd solidity && truffle console --network development

Geth

Geth needs to be invoked with websockets enabled. An example of how to do this is:

geth --ws --ws.addr 127.0.0.1 --ws.port 8546 --ws.origins "*"

This would make Geth listen on ws://127.0.0.1:8546 and accept all incoming connections. Alternatively, you could change the --wsorigins parameter to 127.0.0.1 as well to only accept local connections.

For details on how to install, configure, and run Geth, please refer to their documentation.

Parity

Parity also needs to be invoked with the websockets API enabled:

parity --ws-interface 127.0.0.1 --ws-port 8546 --ws-origins "all"

For details on how to install, configure, and run Parity, please refer to their documentation.

Postgres

Postgres can optionally be used for Chainlinks database. If you would like to quickly get setup, we suggest using Docker and follow the instructions below.

docker run -d \
  -p 5432:5432 \
  --name postgres \
  -e POSTGRES_USER=chainlink \
  -e POSTGRES_DB=chainlink \
  postgres:11

You can now point chainlink at it on startup by setting an environment variable:

export DATABASE_URL="postgres://chainlink@localhost:5432/chainlink?sslmode=disable"

Logging SQL queries

Chainlink uses gorm to interface with Postgresql. While this simplifies some aspects of working with the database, it can also make it difficult to debug the queries. However, you can tell gorm to print all the queries it sends to Postgres by starting the chainlink node with the following environment variables:

LOG_LEVEL=debug
LOG_SQL=true

direnv

We use direnv to set up PATH and aliases for a friendlier developer experience. Here is an example .envrc that we use:

cat .envrc
export ROOT=tmp/.chainlink
PATH_add tools/bin
PATH_add tmp

Direnv can be installed by running

go get -u github.com/direnv/direnv

Then hooking direnv into your shell.

Environment variables that can be set in .envrc, along with default values that get used if no corresponding enviornment variable is found:

LOG_LEVEL                    Default: "info"
ROOT                         Default: "~/.chainlink"
CHAINLINK_PORT               Default: "6688"
GUI_PORT                     Default: "6689"
USERNAME                     Default: "chainlink"
PASSWORD                     Default: "twochains"
ETH_URL                      Default: "ws://localhost:8546"
ETH_CHAIN_ID                 Default: "0"
CLIENT_NODE_URL              Default: "http://localhost:6688"
MIN_INCOMING_CONFIRMATIONS   Default: "0"
MIN_OUTGOING_CONFIRMATIONS   Default: "12"
ETH_GAS_BUMP_THRESHOLD       Default: "12"
ETH_GAS_BUMP_WEI             Default: "5000000000"
ETH_GAS_PRICE_DEFAULT        Default: "20000000000"
LINK_CONTRACT_ADDRESS        Default: "0x514910771AF9Ca656af840dff83E8264EcF986CA"
MINIMUM_CONTRACT_PAYMENT     Default: "1000000000000000000"
ORACLE_CONTRACT_ADDRESS      Default: ""
DATABASE_POLL_INTERVAL       Default: "500ms"

Colorized Test Output

Use grc to colorize your test output and make it more readable.

Development Dependencies

The following is a list of dependencies that need to be installed on the host machine, categorized by role. A guide for installing each of these is located here

Chainlink

• Go
• gcc (for secp256k1 in go-ethereum)
• yarn (for Node Operator UI development)

Devnet

• Docker

Solidity contract development

• Node.js & npm
• Yarn
• Truffle
• Python 2.7 (for sha3 in node_modules)

Setting up Paths

Setting up paths for Golang development involves using a GOPATH environment variable, and adding two paths to your Go binaries to your PATH environment variable.

First, create a workspace for Go development:

mkdir ~/go

This will serve as your GOPATH environment variable. You'll want this to be persisted every time you run a terminal, so add this to the appropriate file that is ran when you log in. You can determine which one that is here, we'll be using ~/.bashrc for these examples.

echo "export GOPATH=~/go" >> ~/.bashrc

Next, you'll want to add the binaries for the Go installation, and for installed Go programs to your PATH environment variable. We're going to assume that your default Go installation is located at /usr/local/go, so adjust accordingly if it's different:

echo "export PATH=$PATH:/usr/local/go/bin:$GOPATH/bin" >> ~/.bashrc

Now when logging out and logging on, your Go binaries will automatically be available for you to run, and the $GOPATH environment variable will persist.

Ignoring Developer-Specific Files

Instead of adding IDE-specific files to the .gitignore file in our repo, we ask that you add them to your own global .gitignore file.

You can do this by running:

git config --global core.excludesfile '~/.gitignore'

Or on Windows:

git config --global core.excludesfile "%USERPROFILE%\.gitignore"

Then you'll add files that are specific to your development here. For example, if you use Visual Studio Code, you'll want to add:

.vscode\
debug

Node Operator UI Development

The operator UI is compiled as part of node compilation. However, this is not suitable for development, as each change requires the node to be recompiled via a restart which can several minutes depending on your machine.

To aid with the speed of development we recommend using webpack-dev-server which is available via the yarn start command. This watches your file system in /gui and recompiles when there are changes. It also supports hot module replacement so that the changes are visible without having to reload the page. We recommend running the command with the CHAINLINK_PORT environment variable so that API requests are sent to your local node. You can do this when running the command:

$ CHAINLINK_PORT=6688 yarn start

Or, if using direnv

# .envrc
export CHAINLINK_PORT=6688

# bash
$ yarn start