README
¶
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.
Table of Contents
Installation
Refer to installation guide for assistance in installing.
Modules
The chainbridge-core-example currently supports two modules:
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.
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.
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
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
Directories
¶
| Path | Synopsis |
|---|---|
|
chains
|
|
|
evm/calls/evmgaspricer/mock
Package mock_evmgaspricer is a generated GoMock package.
|
Package mock_evmgaspricer is a generated GoMock package. |
|
evm/calls/mock
Package mock_calls is a generated GoMock package.
|
Package mock_calls is a generated GoMock package. |
|
evm/calls/transactor/itx/mock
Package mock_itx is a generated GoMock package.
|
Package mock_itx is a generated GoMock package. |
|
evm/calls/transactor/mock
Package mock_transactor is a generated GoMock package.
|
Package mock_transactor is a generated GoMock package. |
|
evm/cli/bridge/mock
Package mock_bridge is a generated GoMock package.
|
Package mock_bridge is a generated GoMock package. |
|
evm/listener/mock
Package mock_listener is a generated GoMock package.
|
Package mock_listener is a generated GoMock package. |
|
evm/voter/mock
Package mock_voter is a generated GoMock package.
|
Package mock_voter is a generated GoMock package. |
|
The crypto package is used to provide functionality to several keypair types.
|
The crypto package is used to provide functionality to several keypair types. |
|
e2e
|
|
|
The keystore package is used to load keys from keystore files, both for live use and for testing.
|
The keystore package is used to load keys from keystore files, both for live use and for testing. |
|
mock
Package mock_relayer is a generated GoMock package.
|
Package mock_relayer is a generated GoMock package. |
|
mock
Package mock_blockstore is a generated GoMock package.
|
Package mock_blockstore is a generated GoMock package. |