README
¶
ZetaChain
ZetaChain is an EVM-compatible L1 blockchain that enables omnichain, generic smart contracts and messaging between any blockchain.
Prerequisites
- Go 1.23
- Docker and Docker Compose (optional, for running tests locally)
- buf (optional, for processing protocol buffer files)
- jq (optional, for running scripts)
Components of ZetaChain
ZetaChain is built with Cosmos SDK, a modular framework for building blockchain and Cosmos EVM, a module that implements EVM-compatibility.
This repository contains the core components:
- Blockchain Modules (ZetaCore): This section contains the core logic of the ZetaChain blockchain, built using Cosmos SDK modules. These modules are responsible for managing the state, state transitions, and overall functionality of the ZetaChain network.
- ZetaClient: The ZetaClient is a specialized client designed to act as an observer and signer for the ZetaChain network. It is responsible for communicating with the blockchain, relaying messages, and performing signature tasks to ensure the network operates cross-chain transactions.
Protocol Contracts
In addition to the blockchain codebase, ZetaChain’s architecture includes a set of protocol contracts that serve as an interface for developers to interact with the blockchain. These smart contracts are deployed across various blockchain networks. The smart contract source code is maintained in separate repositories, depending on the network they are deployed on:
- ZetaChain EVM and EVM connected chains
- Solana connected chains (SVM)
- TON connected chains (TVM)
- Sui connected chains (Sui's MVM)
These repositories contain the necessary code and tools to deploy, interact with, and extend the functionality of ZetaChain’s cross-chain protocol on each respective blockchain network.
Versions
For a complete compatibility matrix showing which protocol contract versions are compatible with specific ZetaCore and ZetaClient versions, see VERSIONS.md.
Building the zetacored/zetaclientd binaries
Clone this repository, checkout the latest release tag, and type the following command to build the binaries:
make install
to build.
This command will install the zetacored and zetaclientd binaries in your
$GOPATH/bin directory.
Verify that the version of the binaries match the release tag.
zetacored version
zetaclientd version
Making changes to the source code
After making changes to any of the protocol buffer files, run the following command to run generated files generation (ProtoBuf, OpenAPI and docs):
make generate
This command will use buf to generate the Go files from the protocol buffer
files and move them to the correct directories inside x/. It will also
generate an OpenAPI spec.
This command will run a script to update the modules' documentation. The script
uses static code analysis to read the protocol buffer files and identify all
Cosmos SDK messages. It then searches the source code for the corresponding
message handler functions and retrieves the documentation for those functions.
Finally, it creates a messages.md file for each module, which contains the
documentation for all the messages in that module.
Further Reading
Find below further documentation for development and running your own ZetaChain node:
- Get familiar with our release lifecycle
- Run the E2E tests and interact with the localnet
- Make a new ZetaChain release
- Build test release binaries
- Deploy your own ZetaChain or Bitcoin node
- Run the simulation tests
- Learn about gas and fees in ZetaChain
Community
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
zetaclientd
command
|
|
|
zetaclientd-supervisor
command
|
|
|
zetacore_utils
command
|
|
|
zetacored
command
|
|
|
zetae2e
command
|
|
|
zetatool
command
|
|
|
contrib
|
|
|
rpctest
command
|
|
|
e2e
|
|
|
contracts/istaking
Package istaking contains the bindings for the staking precompile interface It is used for E2E testing with the staking precompiles Note: for simplicity and to only validate that the precompile is enable, only the staking function is defined in the interface
|
Package istaking contains the bindings for the staking precompile interface It is used for E2E testing with the staking precompiles Note: for simplicity and to only validate that the precompile is enable, only the staking function is defined in the interface |
|
pkg
|
|
|
bg
Package bg provides primitives for the background tasks
|
Package bg provides primitives for the background tasks |
|
contracts/solana
Package solana provides structures and constants that are used when interacting with the gateway program on Solana chain.
|
Package solana provides structures and constants that are used when interacting with the gateway program on Solana chain. |
|
contracts/ton
Package ton provider bindings for TON blockchain including Gateway contract wrapper.
|
Package ton provider bindings for TON blockchain including Gateway contract wrapper. |
|
errgroup
Package errgroup provides synchronization, error propagation, and Context cancellation for groups of goroutines working on subtasks of a common task.
|
Package errgroup provides synchronization, error propagation, and Context cancellation for groups of goroutines working on subtasks of a common task. |
|
fanout
Package fanout provides a fan-out pattern implementation.
|
Package fanout provides a fan-out pattern implementation. |
|
graceful
Package graceful contains tools for graceful shutdown.
|
Package graceful contains tools for graceful shutdown. |
|
ptr
Package ptr provides helper functions for working with pointers.
|
Package ptr provides helper functions for working with pointers. |
|
retry
Package retry provides a generic retry mechanism with exponential backoff.
|
Package retry provides a generic retry mechanism with exponential backoff. |
|
scheduler
Package scheduler provides a background task scheduler that allows for the registration, execution, and management of periodic tasks.
|
Package scheduler provides a background task scheduler that allows for the registration, execution, and management of periodic tasks. |
|
sdkconfig/default
Set the global default cosmos sdk config on import
|
Set the global default cosmos sdk config on import |
|
ticker
Package ticker provides a dynamic ticker that can change its interval at runtime.
|
Package ticker provides a dynamic ticker that can change its interval at runtime. |
|
nullify
Package nullify provides methods to init nil values structs for test assertion.
|
Package nullify provides methods to init nil values structs for test assertion. |
|
x
|
|
|
authority/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
crosschain/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
emissions/types
NOTE: Usage of x/params to manage parameters is deprecated in favor of x/gov controlled execution of MsgUpdateParams messages.
|
NOTE: Usage of x/params to manage parameters is deprecated in favor of x/gov controlled execution of MsgUpdateParams messages. |
|
fungible/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
lightclient/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
observer/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
zetaclient
|
|
|
authz
Package authz provides a signer object for transactions using grants grants are used to allow a hotkey to sign transactions on behalf of the observers
|
Package authz provides a signer object for transactions using grants grants are used to allow a hotkey to sign transactions on behalf of the observers |
|
chains/bitcoin/client
Package client implements a Bitcoin RPC with support for context, logging, and metrics.
|
Package client implements a Bitcoin RPC with support for context, logging, and metrics. |
|
chains/bitcoin/observer
Package observer implements the Bitcoin chain observer
|
Package observer implements the Bitcoin chain observer |
|
chains/bitcoin/signer
Package signer implements the ChainSigner interface for BTC
|
Package signer implements the ChainSigner interface for BTC |
|
chains/evm/observer
Package observer implements the EVM chain observer
|
Package observer implements the EVM chain observer |
|
chains/evm/signer
Package signer implements the ChainSigner interface for EVM chains
|
Package signer implements the ChainSigner interface for EVM chains |
|
chains/interfaces
Package interfaces provides interfaces for clients and signers for the chain to interact with
|
Package interfaces provides interfaces for clients and signers for the chain to interact with |
|
chains/solana/repo
Package repo implements the Repository pattern to provide an abstraction layer over interactions with the Solana client.
|
Package repo implements the Repository pattern to provide an abstraction layer over interactions with the Solana client. |
|
chains/ton/encoder
Package encoder contains functions that encode/decode transactions' logical time and hash ("lt:hash").
|
Package encoder contains functions that encode/decode transactions' logical time and hash ("lt:hash"). |
|
chains/ton/rpc
Package rpc implements a client for HTTP-RPC using toncenter API V2 spec See: https://toncenter.com/api/v2 See: https://github.com/toncenter/ton-http-api See: https://docs.ton.org/v3/guidelines/dapps/apis-sdks/ton-http-apis
|
Package rpc implements a client for HTTP-RPC using toncenter API V2 spec See: https://toncenter.com/api/v2 See: https://github.com/toncenter/ton-http-api See: https://docs.ton.org/v3/guidelines/dapps/apis-sdks/ton-http-apis |
|
chains/tssrepo
Package tssrepo provides an abstraction layer for interactions with the TSS signer client.
|
Package tssrepo provides an abstraction layer for interactions with the TSS signer client. |
|
chains/zrepo
Package zrepo provides an abstraction layer for interactions with the zetacore client.
|
Package zrepo provides an abstraction layer for interactions with the zetacore client. |
|
compliance
Package compliance provides functions to check for compliance of cross-chain transactions
|
Package compliance provides functions to check for compliance of cross-chain transactions |
|
config
Package config provides functions to load and save ZetaClient config
|
Package config provides functions to load and save ZetaClient config |
|
context
Package context provides global app context for ZetaClient
|
Package context provides global app context for ZetaClient |
|
db
Package db represents API for database operations.
|
Package db represents API for database operations. |
|
dry
Package dry provides a dry client for TSS, and dry-wrappers for the zetacore client and for the standard clients of the connected chains.
|
Package dry provides a dry client for TSS, and dry-wrappers for the zetacore client and for the standard clients of the connected chains. |
|
maintenance
Package maintenance provides maintenance functionalities for the zetaclient.
|
Package maintenance provides maintenance functionalities for the zetaclient. |
|
metrics
Package metrics provides metrics functionalities for the zetaclient
|
Package metrics provides metrics functionalities for the zetaclient |
|
mode
Package mode lists the execution modes for the ZetaClient.
|
Package mode lists the execution modes for the ZetaClient. |
|
mode/chaos
Package chaos provides chaos-wrappers for the TSS signer, for the zetacore client, and for the standard clients of the connected chains.
|
Package chaos provides chaos-wrappers for the TSS signer, for the zetacore client, and for the standard clients of the connected chains. |
|
mode/chaos/generate
command
This program generates chaos-wrappers for client interfaces using reflection.
|
This program generates chaos-wrappers for client interfaces using reflection. |
|
orchestrator
Package orchestrator is responsible for (de)provisioning, running, and monitoring various observer-signer instances.
|
Package orchestrator is responsible for (de)provisioning, running, and monitoring various observer-signer instances. |
|
ratelimiter
Package ratelimiter provides functionalities for rate limiting the cross-chain transactions
|
Package ratelimiter provides functionalities for rate limiting the cross-chain transactions |
|
zetacore
Package zetacore provides the client to interact with zetacore node via GRPC.
|
Package zetacore provides the client to interact with zetacore node via GRPC. |
Click to show internal directories.
Click to hide internal directories.