Chainbridge Core

Chainbridge-core is the project that was born from the existing version of Chainbridge. It was built to improve the maintainability and modularity of the current solution. The fundamental distinction is that chainbridge-core is more of a framework rather than a stand-alone application.

Project still in deep beta

Chat with us on discord.

`Installation`

Refer to installation guide for assistance in installing.

`Modules`

The chainbridge-core-example currently supports two modules:

EVM-CLI
Celo-CLI
Substrate

Usage

Since chainbridge-core is the modular framework it will require writing some code to get it running.

You can find some examples here.

`Metrics`

Metrics, in chainbridge-core are handled via injecting metrics provider compatible with Metrics interface into Relayer instance. It currently needs only one method, TrackDepositMessage(m *message.Message) which is called inside relayer router when a Deposit event appears and should contain all necessary metrics data for extraction in custom implementations.

`OpenTelementry`

chainbridge-core provides already implemented metrics provider via OpenTelemetry that is vendor-agnostic. It sends metrics to a separate collector that then sends metrics via configured exporters to one or many metrics back-ends.

`EVM-CLI`

This module provides instruction for communicating with EVM-compatible chains.

Usage:
   evm-cli [flags]
   evm-cli [command]

Available Commands:
  accounts    Set of commands for managing accounts
  admin       Set of commands for executing various admin actions
  bridge      Set of commands for interacting with a bridge
  centrifuge  Set of commands for interacting with a cetrifuge asset store contract
  deploy      Deploy smart contracts
  erc20       Set of commands for interacting with ERC20 contract
  erc721      Set of commands for interacting with an ERC721 contract
  utils       Set of utility commands

Flags:
  -h, --help   help for evm-cli
      --gas-limit uint              Gas limit used in transactions (default 6721975)
      --gas-price uint              Used as upperLimitGasPrice for transactions if not 0. Transactions gasPrice is defined by estimating it on network for pre London fork networks and by estimating BaseFee and MaxTipFeePerGas in post London networks
      --json-wallet string          Encrypted JSON wallet
      --json-wallet-password string Password for encrypted JSON wallet
      --network uint                ID of the Network
      --private-key string          Private key to use
      --url string                  URL of the node to receive RPC calls (default "ws://localhost:8545")
      --prepare                     Generate calldata for contract calls (doesn't require private key and doesn't send a transaction)

`Accounts`

Set of commands for managing accounts.

Usage:
   evm-cli accounts [command]

Available Commands:
  generate    Generate bridge keystore (Secp256k1)
  import      Import a bridge keystore
  transfer    Transfer base currency

Flags:
  -h, --help   help for accounts

`generate`

The generate subcommand is used to generate the bridge keystore. If no options are specified, a Secp256k1 key will be made.

Usage:
   evm-cli accounts generate [flags]

Flags:
  -h, --help   help for generate

`import`

The import subcommand is used to import a keystore for the bridge.

Usage:
   evm-cli accounts import [flags]

Flags:
  -h, --help               help for import
      --private-key string Private key to use
      --password string    Password to encrypt with

`transfer`

The transfer subcommand is used to transfer the base currency.

Usage:
   evm-cli accounts transfer [flags]

Flags:
      --amount string      Transfer amount
      --decimals uint      Base token decimals (default 0)
  -h, --help               help for transfer
      --recipient string   Recipient address

`Admin`

Set of commands for executing various admin actions.

Usage:
   evm-cli admin [command]

Available Commands:
  add-admin         Add a new admin
  add-relayer       Add a new relayer
  get-threshold     Get the relayer vote threshold
  is-relayer        Check if an address is registered as a relayer
  pause             Pause deposits and proposals
  remove-admin      Remove an existing admin
  remove-relayer    Remove an existing relayer
  set-deposit-nonce Set the deposit nonce
  set-fee           Set a new fee for deposits
  set-threshold     Set a new relayer vote threshold
  unpause           Unpause deposits and proposals
  withdraw          Withdraw tokens from a handler contract

Flags:
  -h, --help   help for admin

`add-admin`

The add-admin subcommand sets an address as a bridge admin.

Usage:
   evm-cli admin add-admin [flags]

Flags:
      --admin string    Address to add
      --bridge string   Bridge contract address
  -h, --help            help for add-admin

`add-relayer`

The add-relayer subcommand sets an address as a bridge relayer.

Usage:
   evm-cli admin add-relayer [flags]

Flags:
      --bridge string    Bridge contract address
  -h, --help             help for add-relayer
      --relayer string   Address to add

`get-threshold`

The get-threshold subcommand returns the relayer vote threshold.

Usage:
   evm-cli admin get-threshold [flags]

Flags:
      --bridge string    Bridge contract address
  -h, --help             help for get-threshold

`is-relayer`

The is-relayer subcommand checks if an address is registered as a relayer.

Usage:
   evm-cli admin is-relayer [flags]

Flags:
      --bridge string    Bridge contract address
  -h, --help             help for is-relayer
      --relayer string   Address to check

`pause`

The pause subcommand pauses deposits and proposals.

Usage:
   evm-cli admin pause [flags]

Flags:
      --bridge string   Bridge contract address
  -h, --help            help for pause

`remove-admin`

The remove-admin subcommand removes an existing admin.

Usage:
   evm-cli admin remove-admin [flags]

Flags:
      --admin string    Address to remove
      --bridge string   Bridge contract address
  -h, --help            help for remove-admin

`remove-relayer`

The remove-relayer subcommand removes an existing relayer.

Usage:
   evm-cli admin remove-relayer [flags]

Flags:
      --bridge string    Bridge contract address
  -h, --help             help for remove-relayer
      --relayer string   Address to remove

`set-deposit-nonce`

The set-deposit-nonce subcommand sets the deposit nonce. This nonce cannot be less than what is currently stored in the contract.

Usage:
   evm-cli admin set-deposit-nonce [flags]

Flags:
      --domain string   Domain ID of chain
      --deposit-nonce   Deposit nonce to set (does not decrement)
      --bridge string   Bridge contract address
  -h, --help            help for set-fee

`set-fee`

The set-fee subcommand sets a new fee for deposits.

Usage:
   evm-cli admin set-fee [flags]

Flags:
      --bridge string   Bridge contract address
      --fee string      New fee (in ether)
  -h, --help            help for set-fee

`set-threshold`

The set-threshold subcommand sets a new relayer vote threshold.

Usage:
   evm-cli admin set-threshold [flags]

Flags:
      --bridge string    Bridge contract address
  -h, --help             help for set-threshold
      --threshold uint   New relayer threshold

`unpause`

The unpause subcommand unpauses deposits and proposals.

Usage:
   evm-cli admin unpause [flags]

Flags:
      --bridge string   Bridge contract address
  -h, --help            help for unpause

`withdraw`

The withdraw subcommand withdrawals tokens from a handler contract.

Usage:
   evm-cli admin withdraw [flags]

Flags:
      --amount string         Token amount to withdraw, use only if ERC20 token is withdrawn. If both amount and token are set an error will occur
      --token string          Token ID to withdraw, use only if ERC721 token is withdrawn. If both amount and token are set an error will occur
      --bridge string         Bridge contract address
      --decimals uint         ERC20 token decimals
      --handler string        Handler contract address
  -h, --help                  help for withdraw
      --recipient string      Address to withdraw to
      --token-contract string ERC20 or ERC721 token contract address

`Bridge`

Set of commands for interacting with a bridge.

Usage:
   evm-cli bridge [command]

Available Commands:
  cancel-proposal           Cancel an expired proposal
  query-proposal            Query an inbound proposal
  query-resource            Query the resource ID for a handler contract
  register-generic-resource Register a generic resource ID
  register-resource         Register a resource ID
  set-burn                  Set a token contract as mintable/burnable

Flags:
  -h, --help   help for bridge

`cancel-proposal`

The cancel-proposal subcommand cancels an expired proposal.

Usage:
   evm-cli bridge cancel-proposal [flags]

Flags:
      --bridge string        Bridge contract address
      --data-hash string     Hash of proposal metadata
      --deposit-nonce uint   Deposit nonce of proposal to cancel
      --domain uint          Domain ID of proposal to cancel
  -h, --help                 help for cancel-proposal

`query-proposal`

The query-proposal subcommand queries an inbound proposal.

Usage:
   evm-cli bridge query-proposal [flags]

Flags:
      --bridge string        Bridge contract address
      --data-hash string     Hash of proposal metadata
      --deposit-nonce uint   Deposit nonce of proposal
      --domain uint          Source domain ID of proposal
  -h, --help                 help for query-proposal

`query-resource`

The query-resource subcommand queries the contract address with the provided resource ID for a specific handler contract.

Usage:
   evm-cli bridge query-resource [flags]

Flags:
      --handler string    Handler contract address
  -h, --help              help for query-resource
      --resource string   Resource ID to query

`register-generic-resource`

The register-generic-resource subcommand registers a resource ID with a contract address for a generic handler.

Usage:
   evm-cli bridge register-generic-resource [flags]

Flags:
      --bridge string     Bridge contract address
      --deposit string    Deposit function signature (default "0x00000000")
      --execute string    Execute proposal function signature (default "0x00000000")
      --handler string    Handler contract address
      --hash              Treat signature inputs as function prototype strings, hash and take the first 4 bytes
  -h, --help              help for register-generic-resource
      --resource string   Resource ID to query
      --target string     Contract address or hash storage to be registered

`register-resource`

The register-resource subcommand registers a resource ID with a contract address for a handler.

Usage:
   evm-cli bridge register-resource [flags]

Flags:
      --bridge string     Bridge contract address
      --handler string    Handler contract address
  -h, --help              help for register-resource
      --resource string   Resource ID to be registered
      --target string     Contract address to be registered

`set-burn`

The set-burn subcommand sets a token contract as mintable/burnable in a handler.

Usage:
   evm-cli bridge set-burn [flags]

Flags:
      --bridge string         Bridge contract address
      --handler string        ERC20 handler contract address
  -h, --help                  help for set-burn
      --token-contract string Token contract to be registered

`Deploy`

The deploy subcommand deploys all or some of the contracts required for bridging. Selection of contracts can be made by either specifying --all or a subset of flags.

Usage:
   evm-cli deploy [flags]

Flags:
      --all                      Deploy all
      --bridge                   Deploy bridge
      --bridge-address string    Bridge contract address. Should be provided if handlers are deployed separately
      --domain uint8             Domain ID for the instance (default 1)
      --erc20                    Deploy ERC20
      --erc20-handler            Deploy ERC20 handler
      --erc20-name string        ERC20 contract name
      --erc20-symbol string      ERC20 contract symbol
      --erc721                   Deploy ERC721
      --erc721-base-uri string   ERC721 base URI
      --erc721-handler           Deploy ERC721 handler
      --erc721-name string       ERC721 contract name
      --erc721-symbol string     ERC721 contract symbol
      --fee uint                 Fee to be taken when making a deposit (in ETH, decimals are allowed)
      --generic-handler          Deploy generic handler
  -h, --help                     help for deploy
      --relayer-threshold uint   Number of votes required for a proposal to pass (default 1)
      --relayers strings         List of initial relayers

`ERC20`

Set of commands for interacting with an ERC20 contract.

Usage:
   evm-cli erc20 [command]

Available Commands:
  add-minter    Add a new ERC20 minter
  approve       Approve an ERC20 tokens
  balance       Query an ERC20 token balance
  deposit       Deposit an ERC20 token
  get-allowance Get the allowance of a spender for an address
  mint          Mint an ERC20 token

Flags:
  -h, --help   help for erc20

`add-minter`

The add-minter subcommand adds a minter to an ERC20 mintable contract.

Usage:
   evm-cli erc20 add-minter [flags]

Flags:
      --contract string   ERC20 contract address
  -h, --help              help for add-minter
      --minter string     Minter address

`get-allowance`

The get-allowance subcommand returns the allowance of a spender for an address.

Usage:
   evm-cli erc20 get-allowance [flags]

Flags:
      --contract string   ERC20 contract address
  -h, --help              help for get-allowance
      --owner string      Address of token owner
      --spender string    Address of spender

`approve`

The approve subcommand approves tokens in an ERC20 contract for transfer.

Usage:
   evm-cli erc20 approve [flags]

Flags:
      --amount string      Amount to grant allowance
      --contract string    ERC20 contract address
      --decimals uint      ERC20 token decimals
  -h, --help               help for approve
      --recipient string   Recipient address

`balance`

The balance subcommand queries the balance of an account in an ERC20 contract.

Usage:
   evm-cli erc20 balance [flags]

Flags:
      --address string    Address to receive balance of
      --contract string   ERC20 contract address
  -h, --help              help for balance

`deposit`

The deposit subcommand creates a new ERC20 token deposit on the bridge contract.

Usage:
   evm-cli erc20 deposit [flags]

Flags:
      --amount string      Amount to deposit
      --bridge string      Address of bridge contract
      --decimals uint      ERC20 token decimals
      --domain uint        Destination domain ID
  -h, --help               help for deposit
      --recipient string   Address of recipient
      --resource string    Resource ID for transfer

`mint`

The mint subcommand mints a token on an ERC20 mintable contract.

Usage:
   evm-cli erc20 mint [flags]

Flags:
      --amount string        Deposit amount
      --contract string      ERC20 contract address
      --decimals uint        ERC20 token decimals
      --recipient string     Recipient address
  -h, --help                 help for mint

`ERC721`

ERC721-related instructions.

Usage:
   evm-cli erc721 [command]

Available Commands:
  add-minter  Add a new ERC721 minter
  approve     Approve an ERC721 token
  deposit     Deposit an ERC721 token
  mint        Mint an ERC721 token
  owner       Get an ERC721 token owner

`add-minter`

The add-minter subcommand adds a new minter address to an ERC721 mintable contract.

Usage:
   evm-cli erc721 add-minter [flags]

Flags:
      --contract string   ERC721 contract address
  -h, --help              help for add-minter
      --minter string     Minter address

`approve`

The approve subcommand approves a token in an ERC721 contract for transfer.

Usage:
   evm-cli erc721 approve [flags]

Flags:
      --contract string    ERC721 contract address
  -h, --help               help for approve
      --recipient string   Recipient address
      --token string       ERC721 token ID

`deposit`

The deposit subcommand creates a new ERC721 token deposit on the bridge contract.

Usage:
   evm-cli erc721 deposit [flags]

Flags:
      --bridge string        Bridge contract address
      --destination string   Destination domain ID
  -h, --help                 help for deposit
      --metadata string      ERC721 token metadata
      --recipient string     Recipient address
      --resource string      Resource ID for transfer
      --token string         ERC721 token ID

`mint`

The mint subcommand mints a token on an ERC721 mintable contract.

Usage:
   evm-cli erc721 mint [flags]

Flags:
      --contract string    ERC721 contract address
  -h, --help               help for mint
      --metadata string    ERC721 token metadata
      --recipient string   Recipient address
      --token string       ERC721 token ID

`owner`

The owner subcommand gets a token owner from an ERC721 mintable contract.

Usage:
   evm-cli erc721 owner [flags]

Flags:
      --contract string   ERC721 contract address
  -h, --help              help for owner
      --token string      ERC721 token ID

`Utils`

Set of utility commands.

Usage:
   evm-cli utils [command]

Available Commands:
  hash-list   List tx hashes within N number of blocks
  simulate    Simulate the invocation of a transaction

Flags:
  -h, --help   help for utils

`hash-list`

The hash-list subcommand accepts a starting block to query, loops over N number of blocks past it, then prints this list of blocks to review hashes contained within.

Usage:
   evm-cli utils hash-list [flags]

Flags:
      --block-number string   Block number to start at
      --blocks string         Number of blocks past the provided block-number to review
  -h, --help                  help for hash-list

`simulate`

The simulate subcommand simulates a transaction result by simulating invocation; not state-altering.

Usage:
   evm-cli utils simulate [flags]

Flags:
      --block-number string   Block number
      --from string           Address of sender
  -h, --help                  help for simulate
      --tx-hash string        Transaction hash

`Centrifuge`

Set of commands for interacting with a cetrifuge asset store contract.

Usage:
   evm-cli centrifuge [command]

Available Commands:
  deploy      Deploy a centrifuge asset store contract
  get-hash    Returns the status of whether a given hash exists in an asset store

`deploy`

The deploy subcommand deploys a Centrifuge asset store contract that represents bridged Centrifuge assets.

Usage:
   evm-cli centrifuge deploy

Flags:
  -h, --help   help for deploy

`get-hash`

The get-hash subcommand checks the _assetsStored map on a Centrifuge asset store contract to determine whether the asset hash exists or not.

Usage:
   evm-cli centrifuge get-hash [flags]

Flags:
      --address string   Centrifuge asset store contract address
      --hash string      A hash to lookup
  -h, --help             help for get-hash

`Celo-CLI`

This module provides instruction for communicating with Celo-compatible chains.

More information can be found about this module within its repository, listed below.

Celo Module Repository

`Substrate`

This module provides instruction for communicating with Substrate-compatible chains.

Currently there is no CLI for this, though more information can be found about this module within its repository, listed below.

Substrate Module Repository

`Contributing`

Chainbridge-core is a open project and welcomes contributions of all kinds: code, docs, and more. If you wish to submit more complex changes, please check up with the core devs first on our Discord Server (look for CHAINBRIDGE category) or submit an issue on the repo to ensure those changes are in line with the general philoshophy of the project or get some early feedback.

When implementing a change:

Adhere to the standard Go formatting guidelines, e.g. Effective Go. Run go fmt.
Stick to the idioms and patterns used in the codebase. Familiar-looking code has a higher chance of being accepted than eerie code. Pay attention to commonly used variable and parameter names, avoidance of naked returns, error handling patterns, etc.
Comments: follow the advice on the Commentary section of Effective Go.
Minimize code churn. Modify only what is strictly necessary. Well-encapsulated changesets will get a quicker response from maintainers.
Lint your code with golangci-lint (CI will reject your PR if unlinted).
Add tests.
Title the PR in a meaningful way and describe the rationale and the thought process in the PR description.
Write clean, thoughtful, and detailed commit messages.

If change entails an update that needs to be documented, please submit a PR to chainbridge-docs repo.

Submiting a PR

Fork the repository, make changes and open a PR to the main branch of the repo. Pull requests must be cleanly rebased on top of main and changes require at least 2 PR approvals for them to be merged.

Reporting an issue

A great way to contribute to the project is to send a detailed report when you encounter an issue. We always appreciate a well-written, thorough bug report, and will thank you for it!

When reporting issues, always include:

chainbridge-core version
modules used
logs (don't forget to remove sensitive data)
tx hashes related to issue (if applicable)
steps required to reproduce the problem

Putting large logs into a gist will be appreciated.

`Local Setup`

This section allows developers with a way to quickly and with minimal effort stand-up a local development environment in order to fully test out functionality of the chainbridge.

`local`

The local-setup command deploys a bridge, ERC20, ERC721 and generic handler contracts with preconfigured accounts and appropriate handlers.

Usage:
   local-setup [flags]

Flags:
  -h, --help   help for local-setup

This can be easily run by building the chainbridge-core-example app, or by issuing a Makefile instruction directly from the root of the chainbridge-core itself.

make local-setup

^ this command will run a shell script that contains instructions for running two EVM chains via Docker (`docker-compose`). Note: this will likely take a few minutes to run.

You can also review our Local Setup Guide for a more detailed example of setting up a local development environment manually.

ChainSafe Security Policy

Reporting a Security Bug

We take all security issues seriously, if you believe you have found a security issue within a ChainSafe project please notify us immediately. If an issue is confirmed, we will take all necessary precautions to ensure a statement and patch release is made in a timely manner.

Please email us a description of the flaw and any related information (e.g. reproduction steps, version) to security at chainsafe dot io.

License

GNU Lesser General Public License v3.0

Name		Name	Last commit message	Last commit date
Latest commit History 141 Commits
.github		.github
chains		chains
config		config
crypto		crypto
e2e		e2e
flags		flags
keystore		keystore
logger		logger
lvldb		lvldb
opentelemetry		opentelemetry
relayer		relayer
scripts		scripts
sender		sender
store		store
types		types
util		util
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum

License

simone1999/sygma-core

Folders and files

Latest commit

History

Repository files navigation

Chainbridge Core

Table of Contents

Installation

Modules

Usage

Metrics

OpenTelementry

EVM-CLI

Accounts

generate

import

transfer

Admin

add-admin

add-relayer

get-threshold

is-relayer

pause

remove-admin

remove-relayer

set-deposit-nonce

set-fee

set-threshold

unpause

withdraw

Bridge

cancel-proposal

query-proposal

query-resource

register-generic-resource

register-resource

set-burn

Deploy

ERC20

add-minter

get-allowance

approve

balance

deposit

mint

ERC721

add-minter

approve

deposit

mint

owner

Utils

hash-list

simulate

Centrifuge

deploy

get-hash

Celo-CLI

Substrate

Contributing

Submiting a PR

Reporting an issue

Local Setup

local

^ this command will run a shell script that contains instructions for running two EVM chains via Docker (docker-compose). Note: this will likely take a few minutes to run.

ChainSafe Security Policy

Reporting a Security Bug

License

About

Resources

License

Stars

Watchers

Forks

Releases 8

Packages 0

Languages

`Installation`

`Modules`

`Metrics`

`OpenTelementry`

`EVM-CLI`

`Accounts`

`generate`

`import`

`transfer`

`Admin`

`add-admin`

`add-relayer`

`get-threshold`

`is-relayer`

`pause`

`remove-admin`

`remove-relayer`

`set-deposit-nonce`

`set-fee`

`set-threshold`

`unpause`

`withdraw`

`Bridge`

`cancel-proposal`

`query-proposal`

`query-resource`

`register-generic-resource`

`register-resource`

`set-burn`

`Deploy`

`ERC20`

`add-minter`

`get-allowance`

`approve`

`balance`

`deposit`

`mint`

`ERC721`

`add-minter`

`approve`

`deposit`

`mint`

`owner`

`Utils`

`hash-list`

`simulate`

`Centrifuge`

`deploy`

`get-hash`

`Celo-CLI`

`Substrate`

`Contributing`

`Local Setup`

`local`

^ this command will run a shell script that contains instructions for running two EVM chains via Docker (`docker-compose`). Note: this will likely take a few minutes to run.

Packages