README.md

Mercury

About Mercury

Mercury is a tool that handles application development on CKB. In the Nervos ecosystem, analogically speaking, while CKB is the Linux kernel, Mercury is Ubuntu. Mercury is the service layer providing interfaces for CKB. The support for CKB core interfaces and other practical functionalities of Mercury can significantly reduce the workload for developers. For developing wallet applications, Mercury offers the interfaces to get balance of an address and to assemble transactions for transferring CKBytes, sUDT or xUDT. For exchanges, Mercury provides functions such as aggregating digital assets and fetching blocks.

Mercury is the bridge between CKB and applications. It provides useful RPC services for DApps that are built upon Lumos and applications that are built upon ckb-sdk (java /go), such as wallets and exchanges. Furthermore, Mercury fetches data from CKB, processes the data, and implements efficient functions based on the core interfaces of CKB.

So far, Mercury has implemented a series of practical interfaces for wallet and exchange applications. More features are in development.

Long-term Support(LTS)

The v0.2 release has been designated as the LTS release. We suggest using the 0.2 version. The migration instructions for upgrading from other versions to the latest version are here.

Usage

There are three ways to use Mercury.

1. Quick Experience

The Mercury official provides public servers for a quick experience of Mercury.

For version 0.2, The request url for mainnet is https://Mercury-mainnet.ckbapp.dev/0.2 , for testnet is https://Mercury-testnet.ckbapp.dev/0.2 .

For version 0.3, the request url for mainnet is https://Mercury-mainnet.ckbapp.dev/0.3 , for testnet is https://Mercury-testnet.ckbapp.dev/0.3 .

For version 0.4, the request url for mainnet is https://Mercury-mainnet.ckbapp.dev/0.4 , for testnet is https://Mercury-testnet.ckbapp.dev/0.4 .

For example, you can use the following command to call a Mercury API method to view the version.

echo '{
    "id": 1234,
    "jsonrpc": "2.0",
    "method": "get_mercury_info",
    "params": []
}' \
| tr -d '\n' \
| curl -H 'content-type: application/json' -d @- https://Mercury-testnet.ckbapp.dev

Attention
Public servers do not guarantee high availability and high performance. If you want to use Mercury in a production project, please deploy and run Mercury on yourself.

2. Run Mercury Locally

• Step 1. Run a CKB node. If you already have a running node, skip this step.

  • run a mainnet node
  • run a testnet node

• Step 2. Edit mainnet_config.toml or testnet_config.toml according to mainnet or testnet. These config files are located in ./devtools/config/. The instrcution of config file is here.

• Step 3. Download the latest version of Mercury from the release page.

• Step 4. Create mercury tables if not exists.

$ psql mercury -U mercury -f ~/path/to/mercury/devtools/create_table/create_table.sql

• Step 5. Run Mercury.

# mainnet
$ Mercury -c ~/path/to/mercury/devtools/config/mainnet_config.toml run

# testnet
$ Mercury -c ~/path/to/mercury/devtools/config/testnet_config.toml run

Recommended Hardware

4 Cores - 8G Memory - 500G Disk and above.

If you use a standalone server to run the Postgres server, a 50G Disk is enough.

Expected Synchronization Duration

If Mercury connects with a synced CKB node, it takes 5-7 hours to catch up the mainnet tip or 10-14 hours to catch up the testnet tip.

3. Run Mercury via Docker

• Step 1. Edit docker_compose_config.toml according to your set. This config file is located in ./devtools/config/.

• Step 2. Edit ./docker-compose.yml to modify the runtime environment of CKB.

environment:
    CKB_NETWORK: mainnet

or

environment:
    CKB_NETWORK: testnet

• Step 3. Build Mercury images from the Dockerfile.

$ docker build -t Mercury .

• Step 4. Run Mercury via docker.

$ docker-compose up -d

or

$ docker run -d -p 8116:8116 -v {user_config_path}:/app/devtools/config Mercury:latest

Recommended Hardware

4 Cores - 8G Memory - 500G Disk and above.

Expected Synchronization Duration

The docker environment runs CKB node and Mercury from the genesis block. It takes 12-15 hours to catch up mainnet tip or 24-30 hours for testnet tip.

SDK Support

For now, two SDKs have supported Mercury: ckb-sdk-java and ckb-sdk-go.

License

Mercury is released under the terms of the MIT license. See COPYING for more information or see https://opensource.org/licenses/MIT.

Development Process

The main branch is built and tested regularly, considered as production-ready; The dev branch is the work branch to merge new features, and it is not stable. The CHANGELOG is available in Releases in the main branch.

Minimum Supported Rust Version policy (MSRV)

The Mercury crate's minimum supported rust version is 1.56.1.

---

Documentation

• Mercury API Documentation
• Mercury Config Documentation
• Mercury Layout Documentation
• Mercury Setup Instructions