chainlink

command module
v2.12.0-beta3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 28, 2024 License: MIT Imports: 2 Imported by: 0

README


Chainlink logo


GitHub tag (latest SemVer) GitHub license GitHub workflow changeset GitHub contributors GitHub commit activity Official documentation

Chainlink expands the capabilities of smart contracts by enabling access to real-world data and off-chain computation while maintaining the security and reliability guarantees inherent to blockchain technology.

This repo contains the Chainlink core node and contracts. The core node is the bundled binary available to be run by node operators participating in a decentralized oracle network. All major release versions have pre-built docker images available for download from the Chainlink dockerhub. If you are interested in contributing please see our contribution guidelines. If you are here to report a bug or request a feature, please check currently open Issues. For more information about how to get started with Chainlink, check our official documentation. Resources for Solidity developers can be found in the Chainlink Hardhat Box.

Community

Chainlink has an active and ever growing community. Discord is the primary communication channel used for day to day communication, answering development questions, and aggregating Chainlink related content. Take a look at the community docs for more information regarding Chainlink social accounts, news, and networking.

  1. Install Go 1.21.1, and add your GOPATH's bin directory to your PATH
    • Example Path for macOS export PATH=$GOPATH/bin:$PATH & export GOPATH=/Users/$USER/go
  2. Install NodeJS v16 & pnpm via npm.
    • It might be easier long term to use nvm to switch between node versions for different projects. For example, assuming $NODE_VERSION was set to a valid version of NodeJS, you could run: nvm install $NODE_VERSION && nvm use $NODE_VERSION
  3. Install Postgres (>= 12.x). It is recommended to run the latest major version of postgres.
    • Note if you are running the official Chainlink docker image, the highest supported Postgres version is 16.x due to the bundled client.
    • You should configure Postgres to use SSL connection (or for testing you can set ?sslmode=disable in your Postgres query string).
  4. Ensure you have Python 3 installed (this is required by solc-select which is needed to compile solidity contracts)
  5. Download Chainlink: git clone https://github.com/smartcontractkit/chainlink && cd chainlink
  6. Build and install Chainlink: make install
  7. Run the node: chainlink help

For the latest information on setting up a development environment, see the Development Setup Guide.

Apple Silicon - ARM64

Native builds on the Apple Silicon should work out of the box, but the Docker image requires more consideration.

$ docker build . -t chainlink-develop:latest -f ./core/chainlink.Dockerfile

Ethereum Execution Client Requirements

In order to run the Chainlink node you must have access to a running Ethereum node with an open websocket connection. Any Ethereum based network will work once you've configured the chain ID. Ethereum node versions currently tested and supported:

[Officially supported]

[Supported but broken] These clients are supported by Chainlink, but have bugs that prevent Chainlink from working reliably on these execution clients.

We cannot recommend specific version numbers for ethereum nodes since the software is being continually updated, but you should usually try to run the latest version available.

NOTE: By default, chainlink will run in TLS mode. For local development you can disable this by using a dev build using make chainlink-dev and setting the TOML fields:

[WebServer]
SecureCookies = false
TLS.HTTPSPort = 0

[Insecure]
DevWebServer = true

Alternatively, you can generate self signed certificates using tools/bin/self-signed-certs or manually.

To start your Chainlink node, simply run:

chainlink node start

By default this will start on port 6688. You should be able to access the UI at http://localhost:6688/.

Chainlink provides a remote CLI client as well as a UI. Once your node has started, you can open a new terminal window to use the CLI. You will need to log in to authorize the client first:

chainlink admin login

(You can also set ADMIN_CREDENTIALS_FILE=/path/to/credentials/file in future if you like, to avoid having to login again).

Now you can view your current jobs with:

chainlink jobs list

To find out more about the Chainlink CLI, you can always run chainlink help.

Check out the doc pages on Jobs to learn more about how to create Jobs.

Configuration

Node configuration is managed by a combination of environment variables and direct setting via API/UI/CLI.

Check the official documentation for more information on how to configure your node.

External Adapters

External adapters are what make Chainlink easily extensible, providing simple integration of custom computations and specialized APIs. A Chainlink node communicates with external adapters via a simple REST API.

For more information on creating and using external adapters, please see our external adapters page.

Development

Running tests

  1. Install pnpm via npm

  2. Install gencodec and jq to be able to run go generate ./... and make abigen

  3. Install mockery

make mockery

Using the make command will install the correct version.

  1. Build contracts:
pushd contracts
pnpm i
pnpm compile:native
popd
  1. Generate and compile static assets:
go generate ./...
  1. Prepare your development environment:

The tests require a postgres database. In turn, the environment variable CL_DATABASE_URL must be set to value that can connect to _test database, and the user must be able to create and drop the given _test database.

Note: Other environment variables should not be set for all tests to pass

There helper script for initial setup to create an appropriate test user. It requires postgres to be running on localhost at port 5432. You will be prompted for the postgres user password

make setup-testdb

This script will save the CL_DATABASE_URL in .dbenv

Changes to database require migrations to be run. Similarly, pull'ing the repo may require migrations to run. After the one-time setup above:

source .dbenv
make testdb
  1. Run tests:
go test ./...
Notes
  • The parallel flag can be used to limit CPU usage, for running tests in the background (-parallel=4) - the default is GOMAXPROCS
  • The p flag can be used to limit the number of packages tested concurrently, if they are interferring with one another (-p=1)
  • The -short flag skips tests which depend on the database, for quickly spot checking simpler tests in around one minute
Race Detector

As of Go 1.1, the runtime includes a data race detector, enabled with the -race flag. This is used in CI via the tools/bin/go_core_race_tests script. If the action detects a race, the artifact on the summary page will include race.* files with detailed stack traces.

It will not issue false positives, so take its warnings seriously.

For local, targeted race detection, you can run:

GORACE="log_path=$PWD/race" go test -race ./core/path/to/pkg -count 10
GORACE="log_path=$PWD/race" go test -race ./core/path/to/pkg -count 100 -run TestFooBar/sub_test

https://go.dev/doc/articles/race_detector

Fuzz tests

As of Go 1.18, fuzz tests func FuzzXXX(*testing.F) are included as part of the normal test suite, so existing cases are executed with go test.

Additionally, you can run active fuzzing to search for new cases:

go test ./pkg/path -run=XXX -fuzz=FuzzTestName

https://go.dev/doc/fuzz/

Go Modules

This repository contains three Go modules:

flowchart RL
    github.com/smartcontractkit/chainlink/v2
    github.com/smartcontractkit/chainlink/integration-tests --> github.com/smartcontractkit/chainlink/v2
    github.com/smartcontractkit/chainlink/core/scripts --> github.com/smartcontractkit/chainlink/v2

The integration-tests and core/scripts modules import the root module using a relative replace in their go.mod files, so dependency changes in the root go.mod often require changes in those modules as well. After making a change, go mod tidy can be run on all three modules using:

make gomodtidy

Solidity

Inside the contracts/ directory:

  1. Install dependencies:
pnpm i
  1. Run tests:
pnpm test

NOTE: Chainlink is currently in the process of migrating to Foundry and contains both Foundry and Hardhat tests in some versions. More information can be found here: Chainlink Foundry Documentation. Any 't.sol' files associated with Foundry tests, contained within the src directories will be ignored by Hardhat.

Code Generation

Go generate is used to generate mocks in this project. Mocks are generated with mockery and live in core/internal/mocks.

Nix

A shell.nix is provided for use with the Nix package manager, with optional flakes support. It defines a declarative, reproducible development environment. Flakes version use deterministic, frozen (flake.lock) dependencies, while non-flakes shell will use your channel's packages versions.

To use it:

  1. Install nix package manager in your system.
  1. Run nix-shell. You will be put in shell containing all the dependencies.
  • To use the flakes version, run nix develop instead of nix-shell. Optionally, nix develop --command $SHELL will make use of your current shell instead of the default (bash).
  • You can use direnv to enable it automatically when cd-ing into the folder; for that, enable nix-direnv and use nix or use flake on it.
  1. Create a local postgres database:
mkdir -p $PGDATA && cd $PGDATA/
initdb
pg_ctl -l postgres.log -o "--unix_socket_directories='$PWD'" start
createdb chainlink_test -h localhost
createuser --superuser --password chainlink -h localhost
# then type a test password, e.g.: chainlink, and set it in shell.nix CL_DATABASE_URL
  1. When re-entering project, you can restart postgres: cd $PGDATA; pg_ctl -l postgres.log -o "--unix_socket_directories='$PWD'" start Now you can run tests or compile code as usual.
  2. When you're done, stop it: cd $PGDATA; pg_ctl -o "--unix_socket_directories='$PWD'" stop

Changesets

We use changesets to manage versioning for libs and the services.

Every PR that modifies any configuration or code, should most likely accompanied by a changeset file.

To install changesets:

  1. Install pnpm if it is not already installed - docs.
  2. Run pnpm install.

Either after or before you create a commit, run the pnpm changeset command to create an accompanying changeset entry which will reflect on the CHANGELOG for the next release.

The format is based on Keep a Changelog,

and this project adheres to Semantic Versioning.

Tips

For more tips on how to build and test Chainlink, see our development tips page.

Contributing

Contributions are welcome to Chainlink's source code.

Please check out our contributing guidelines for more details.

Thank you!

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
common
fee
build
Package build utilizes build tags and package testing API to determine the environment that this binary was built to target.
Package build utilizes build tags and package testing API to determine the environment that this binary was built to target.
chains/evm/client
The simulated backend cannot access old blocks and will return an error if anything other than `latest`, `nil`, or the latest block are passed to `CallContract`.
The simulated backend cannot access old blocks and will return an error if anything other than `latest`, `nil`, or the latest block are passed to `CallContract`.
chains/evm/logpoller
Package logpoller is a service for querying EVM log data.
Package logpoller is a service for querying EVM log data.
cmd
Package cmd is the front-end interface for the application as a command-line utility.
Package cmd is the front-end interface for the application as a command-line utility.
config/docs/cmd/generate
Docs prints core node documentation and/or a list of errors.
Docs prints core node documentation and/or a list of errors.
gethwrappers
Package gethwrappers provides infrastructure for generating and verifying go-ethereum wrapper packages for smart contracts.
Package gethwrappers provides infrastructure for generating and verifying go-ethereum wrapper packages for smart contracts.
gethwrappers/functions
Package gethwrappers provides tools for wrapping solidity contracts with golang packages, using abigen.
Package gethwrappers provides tools for wrapping solidity contracts with golang packages, using abigen.
gethwrappers/keystone
Package gethwrappers provides tools for wrapping solidity contracts with golang packages, using abigen.
Package gethwrappers provides tools for wrapping solidity contracts with golang packages, using abigen.
gethwrappers/llo-feeds
Package gethwrappers provides tools for wrapping solidity contracts with golang packages, using abigen.
Package gethwrappers provides tools for wrapping solidity contracts with golang packages, using abigen.
gethwrappers/ocr2vrf
Package gethwrappers provides tools for wrapping solidity contracts with golang packages, using abigen.
Package gethwrappers provides tools for wrapping solidity contracts with golang packages, using abigen.
gethwrappers/shared
Package gethwrappers provides tools for wrapping solidity contracts with golang packages, using abigen.
Package gethwrappers provides tools for wrapping solidity contracts with golang packages, using abigen.
gethwrappers/transmission
Package gethwrappers provides tools for wrapping solidity contracts with golang packages, using abigen.
Package gethwrappers provides tools for wrapping solidity contracts with golang packages, using abigen.
internal/cltest
Importing cltest should only be for top level black box (X_test package) integration tests, for example testing against the Application object itself.
Importing cltest should only be for top level black box (X_test package) integration tests, for example testing against the Application object itself.
internal/cltest/heavyweight
Package heavyweight contains test helpers that are costly and you should think **real carefully** before using in your tests.
Package heavyweight contains test helpers that are costly and you should think **real carefully** before using in your tests.
services
Package services contain the key components of the Chainlink node.
Package services contain the key components of the Chainlink node.
services/blockhashstore
The blockhash store package provides a service that stores blockhashes such that they are available for on-chain proofs beyond the EVM 256 block limit.
The blockhash store package provides a service that stores blockhashes such that they are available for on-chain proofs beyond the EVM 256 block limit.
services/blockheaderfeeder
The block header feeder package enables automated lookback and blockhash filling beyond the EVM 256 block lookback window to catch missed block hashes.
The block header feeder package enables automated lookback and blockhash filling beyond the EVM 256 block lookback window to catch missed block hashes.
services/ocr2/plugins/promwrapper
promwrapper wraps another OCR2 reporting plugin and provides standardized prometheus metrics for each of the OCR2 phases (Query, Observation, Report, ShouldAcceptFinalizedReport, ShouldTransmitAcceptedReport, and Close).
promwrapper wraps another OCR2 reporting plugin and provides standardized prometheus metrics for each of the OCR2 phases (Query, Observation, Report, ShouldAcceptFinalizedReport, ShouldTransmitAcceptedReport, and Close).
services/signatures/cryptotest
Package cryptotest provides convenience functions for kyber-based APIs.
Package cryptotest provides convenience functions for kyber-based APIs.
services/signatures/ethdss
Package ethdss implements the Distributed Schnorr Signature protocol from the //////////////////////////////////////////////////////////////////////////////
Package ethdss implements the Distributed Schnorr Signature protocol from the //////////////////////////////////////////////////////////////////////////////
services/signatures/ethschnorr
Package ethschnorr implements a version of the Schnorr signature which is //////////////////////////////////////////////////////////////////////////////
Package ethschnorr implements a version of the Schnorr signature which is //////////////////////////////////////////////////////////////////////////////
services/signatures/secp256k1
Package secp256k1 is an implementation of the kyber.{Group,Point,Scalar} //////////////////////////////////////////////////////////////////////////////
Package secp256k1 is an implementation of the kyber.{Group,Point,Scalar} //////////////////////////////////////////////////////////////////////////////
sessions/ldapauth
The LDAP authentication package forwards the credentials in the user session request for authentication with a configured upstream LDAP server
The LDAP authentication package forwards the credentials in the user session request for authentication with a configured upstream LDAP server
store
Package store is used to keep application events in sync between the database on the node and the blockchain.
Package store is used to keep application events in sync between the database on the node and the blockchain.
utils
Package utils is used for common functions and tools used across the codebase.
Package utils is used for common functions and tools used across the codebase.
utils/big_math
Package bigmath compensates for awkward big.Int API.
Package bigmath compensates for awkward big.Int API.
web
web/schema
Package schema is used to read schema files go:generate go-bindata -ignore=\.go -pkg=schema -o=bindata.go ./...
Package schema is used to read schema files go:generate go-bindata -ignore=\.go -pkg=schema -o=bindata.go ./...
internal
tools

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL