Force Bridge

https://github.com/nervosnetwork/force-bridge
Admin
Force Bridge is a general-purpose bridge designed to connect chains supporting multi-signature...
Tokens:10,421
Snippets:58
Trust Score:9.6
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Set up Force Bridge Devnet with Docker

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/use-docker.md

Commands to build CKB contracts, start CKB and Ethereum dev chains, install dependencies, deploy contracts, generate configurations, and start off-chain modules for local development. Includes instructions for UI setup and MetaMask configuration for testing.

```bash
make build-ckb-contracts

cd offchain-modules
# start CKB dev chain and Ethereum dev chain
yarn startDevDockerDeps
# install dependencies and build via docker
yarn dev-docker:install
# deploy the contracts and generate all configs for you via docker
yarn dev-docker:generate
# generate the ui configs and build via docker
# if you don't need ui or start it yourself, skip it 
yarn dev-docker:generate-ui
# start off chain modules
yarn startDevDockers
# you can use 'yarn startDevDockersWithUi' instead of 'yarn startDevDockers' to run the whole bridge with ui
# open 'http://localhost:3003' in browser
# add a network named 'local' with rpc 'http://localhost:3000' and chainId '1234' to MetaMask
# import account with private key '0x6e51216cbb2fe170368da49e82b22f02b999204730c858482d0e84a9083005ac' to MetaMask for test
```

--------------------------------

### Install Force Bridge CLI (forcecli)

Source: https://github.com/nervosnetwork/force-bridge/blob/main/offchain-modules/forcecli-guide.md

Instructions to clone the Force Bridge repository, install dependencies using Yarn, build the project, configure the CLI, and link it globally for command-line access. This sets up the necessary environment to use `forcecli`.

```bash
git clone https://github.com/nervosnetwork/force-bridge.git

cd offchain-modules
yarn install
yarn build

cp config-cli.json.example config-cli.json
# edit the config file on your demands
npm link
```

--------------------------------

### Start Services with Docker Compose

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docker/README.md

Starts all services defined in the `docker-compose.yml` file. Navigate to the `docker` directory before executing this command.

```shell script
cd docker
docker-compose up
```

--------------------------------

### Install and Verify Force Bridge CLI

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/verifiers-guide/deployment.md

This snippet demonstrates how to install the Force Bridge command-line interface globally using npm. It then verifies the successful installation by executing the `forcecli -h` command to display its usage and available commands.

```Bash
$ npm install -g @force-bridge/cli@latest

$ forcecli -h
Usage: forcecli [options] [command]

forcecli is command line tool to lock & unlock asset to force bridge

Options:
  -V, --version        output the version number
  -h, --help           display help for command

Commands:
  eth
  collector [options]
  fee                  query and withdraw bridge fee
  rpc [options]
  verifier [options]
  config
  keystore
  help [command]       display help for command
```

--------------------------------

### Start Force Bridge Verifier Service

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/verifiers-guide/deployment.md

Initiate the Force Bridge verifier service using the `forcecli` command-line tool. This command requires a path to a `config.json` file, which specifies database, keystore, RPC endpoints, and other critical settings for the service operation.

```bash
# start verifier service
$ forcecli verifier --config /path/to/your/config.json
```

--------------------------------

### Example: Query Ethereum Balance on CKB Network

Source: https://github.com/nervosnetwork/force-bridge/blob/main/offchain-modules/forcecli-guide.md

Demonstrates querying the balance of an Ethereum asset on the CKB network for a given CKB address using `forcecli eth balanceOf`. This allows users to verify their wrapped asset holdings on the CKB side of the bridge.

```bash
forcecli eth balanceOf -addr ckt1qyqyph8v9mclls35p6snlaxajeca97tc062sa5gahk
```

--------------------------------

### Configure and Deploy Force Bridge on Testnet with Docker

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/use-docker.md

Instructions for setting up the Testnet environment, including creating a work directory, configuring essential environment variables (RPC URLs, private keys), installing dependencies, generating configurations, and starting the Force Bridge services using docker-compose. Emphasizes the need for funded private keys for contract deployment.

```bash
mkdir -p workdir/testnet-docker
```

```env
ETH_RPC_URL = 'https://rinkeby.infura.io/v3/xxx'
CKB_RPC_URL = 'https://testnet.ckb.dev/rpc'
CKB_INDEXER_URL = 'https://testnet.ckb.dev/indexer'
CKB_PRIVATE_KEY = 'xxx'
ETH_PRIVATE_KEY = 'xxx'
```

```bash
cd offchain-modules
# install node modules
yarn testnet-docker:install
# generate all configs
yarn testnet-docker:generate

cd workdir/testnet-docker
docker-compose up -d
```

--------------------------------

### Run Force Bridge UI Locally for Testnet Interaction

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/use-docker.md

Steps to clone the Force Bridge UI repository, configure its development environment variables (API and CKB RPC URLs), install dependencies, build common libraries, and start the UI for local interaction with a deployed Testnet bridge.

```bash
git clone https://github.com/nervosnetwork/force-bridge-ui.git
cd force-bridge-ui
```

```env
REACT_APP_BRIDGE_RPC_URL=/api/force-bridge/api/v1
REACT_APP_BRIDGE_RPC_URL=http://127.0.0.1:4199/force-bridge/api/v1
REACT_APP_CKB_RPC_URL=https://testnet.ckb.dev/rpc
```

```bash
yarn install
# build commons libraries
yarn build:lib
yarn workspace @force-bridge/ui run start
```

--------------------------------

### Example: Query Ethereum Balance on Ethereum Network

Source: https://github.com/nervosnetwork/force-bridge/blob/main/offchain-modules/forcecli-guide.md

Demonstrates querying the balance of a specific Ethereum address on the Ethereum network using `forcecli eth balanceOf` with the `-o` flag. This is useful for checking native ETH or ERC20 token balances on the origin chain.

```bash
forcecli eth balanceOf -addr 0x8951a3DdEf2bB36fF3846C3B6968812C269f4561 -o
```

--------------------------------

### Run CKB Full Node and Indexer with Docker

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/verifiers-guide/deployment.md

This command initiates a CKB full node and indexer within a Docker container. It configures port mapping (8117:9115), sets the CKB network to 'testnet', and mounts a specified local directory for persistent data storage. This setup is crucial for verifiers to interact with the CKB chain.

```Bash
$ docker run -d -it -p 8117:9115  --name=ckb-testnet-indexer  -e "CKB_NETWORK=testnet" -v /path/to/ckb/data:/data nervos/perkins-tent:v0.43.0
```

--------------------------------

### Example: Unlock Ethereum Asset from CKB

Source: https://github.com/nervosnetwork/force-bridge/blob/main/offchain-modules/forcecli-guide.md

Demonstrates unlocking a specified amount of Ethereum asset from a CKB account back to an Ethereum recipient address using `forcecli eth unlock`. This operation requires the private key of the CKB account holding the asset.

```bash
forcecli eth unlock -p 0xa800c82df5461756ae99b5c6677d019c98cc98c7786b80d7b2e77256e46ea1fe -r 0x8951a3DdEf2bB36fF3846C3B6968812C269f4561 -a 0.1
```

--------------------------------

### Example: Lock Ethereum Asset to CKB

Source: https://github.com/nervosnetwork/force-bridge/blob/main/offchain-modules/forcecli-guide.md

Demonstrates locking a specified amount of Ethereum asset from an Ethereum account to a CKB recipient address using `forcecli eth lock`. This operation requires the private key of the Ethereum account initiating the lock.

```bash
forcecli eth lock -p 0x719e94ec5d2ecef67b5878503ffd6e1e0e2fe7a52ddd55c436878cb4d52d376d -r ckt1qyqyph8v9mclls35p6snlaxajeca97tc062sa5gahk -a 0.1
```

--------------------------------

### Display Forcecli Help and Usage

Source: https://github.com/nervosnetwork/force-bridge/blob/main/offchain-modules/forcecli-guide.md

Execute `forcecli --help` to display the tool's general usage, available options, and supported blockchain commands (eth, eos, tron, btc). This provides an overview of the CLI's capabilities and structure.

```bash
forcecli --help
```

```APIDOC
Usage: forcecli [options] [command]

forcecli is command line tool to lock & unlock asset to force bridge

Options:
  -V, --version   output the version number
  -h, --help      display help for command

Commands:
  eth
  eos
  tron
  btc
  help [command]  display help for command
```

--------------------------------

### Install Capsule and Run Project Tests

Source: https://github.com/nervosnetwork/force-bridge/blob/main/ckb-contracts/README.md

Instructions to install the 'capsule' tool (version 0.2.3) using cargo or by direct download, followed by commands to execute the project's test suite.

```bash
# install capsule 0.2.3
# or download the binary directly: https://github.com/nervosnetwork/capsule/releases/tag/v0.2.3
cargo install capsule --git https://github.com/nervosnetwork/capsule.git --tag v0.2.3

# test
make
```

--------------------------------

### Manually Run Force Bridge Off-chain Modules CLI

Source: https://github.com/nervosnetwork/force-bridge/blob/main/README.md

Provides steps to manually start the Force Bridge off-chain modules. This involves navigating to the directory, installing Node.js dependencies with Yarn, configuring the application, and launching it.

```bash
cd offchain-modules
yarn install
cp config.json.example config.json
# edit the config file on your demands
yarn start
```

--------------------------------

### Build CKB Indexer Docker Image

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docker/README.md

Builds the Docker image for the CKB indexer. Navigate to the `docker/ckb-indexer` directory before executing this command.

```shell script
cd docker/ckb-indexer
docker build -t ckb-indexer .
```

--------------------------------

### Create and Encrypt Keystore from Key Pairs in TypeScript

Source: https://github.com/nervosnetwork/force-bridge/blob/main/offchain-modules/packages/keystore/README.md

Demonstrates how to initialize a KeyStore from a set of key-value pairs, encrypt it with a password, and retrieve the encrypted data for storage. This snippet shows the initial setup of the keystore.

```TypeScript
import { KeyStore } from '@force-bridge/keystore';

const password = '123456';
const store = KeyStore.createFromPairs(
  {
    Alice: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
    Bob: '0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
  },
  password,
);

const encrypted = store.getEncryptedData();
saveToFile(JSON.stringify(encrypted));
```

--------------------------------

### Build CKB Dev Chain Docker Image

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docker/README.md

Builds the Docker image for the CKB development chain. Navigate to the `docker/ckb` directory before executing this command.

```shell script
cd docker/ckb
docker build -t ckb-dev:v0.36.0 .
```

--------------------------------

### Build Geth Private Chain Docker Image

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docker/README.md

Builds the Docker image for the Geth private chain. Navigate to the `docker/geth` directory before executing this command.

```shell script
cd docker/geth
docker build -t geth-priv:v1.9.23 .
```

--------------------------------

### Generate and Encrypt Verifier Keystore

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/verifiers-guide/deployment.md

This snippet outlines the critical steps for securing a verifier's private key. It involves creating a temporary `keys.json` file with the private key and then encrypting it into a secure `keystore.json` file using a password. The instructions emphasize the importance of deleting the unencrypted `keys.json` and clearing shell history to maintain security.

```Bash
$ echo "{\"verifier\":\"${PRIVKEY}\"}" > keys.json
$ forcecli keystore encrypt -s ./keys.json -d ./keystore.json -p my-custom-password
```

--------------------------------

### Generate Verifier MultiConfig from Private Key

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/verifiers-guide/deployment.md

This snippet demonstrates how to generate the `multiConfig` for a verifier using a provided private key. The output includes the derived Ethereum address, CKB public key hash, and CKB address, which are essential for the deployment of on-chain contracts.

```Bash
$ export PRIVKEY=0x1000000000000000000000000000000000000000000000000000000000000000
$ forcecli config generate -k $PRIVKEY -p ckb
multiConfig:
{
  "ethAddress": "0x7B2419E0Ee0BD034F7Bf24874C12512AcAC6e21C",
  "ckbPubkeyHash": "0x42a34b11710e40b97180f8edae2760c0ab69bcf3",
  "ckbAddress": "ckt1qyqy9g6tz9csus9ewxq03mdwyasvp2mfhnesju9rhz"
}
```

--------------------------------

### Install Force Bridge Global CLI via npm

Source: https://github.com/nervosnetwork/force-bridge/blob/main/README.md

Installs the Force Bridge command-line interface globally using npm. This allows users to execute Force Bridge commands directly from their terminal.

```bash
npm i -g @force-bridge/cli
```

--------------------------------

### Run CKB Indexer Docker Container

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docker/README.md

Runs the CKB indexer container, exposing port 8116. The container is removed automatically upon exit.

```shell script
docker run --rm -it -p 8116:8116 ckb-indexer
```

--------------------------------

### Check Force Bridge Service Status via API

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/verifiers-guide/upgrade-ckb-node.md

This command demonstrates how to query the Force Bridge sign server API to check the current status of the service. It sends a JSON-RPC request to the `/force-bridge/sign-server/api/v1` endpoint and expects a JSON response containing `addressConfig` and `latestChainStatus` for CKB and ETH, including `latestCkbHeight`. The example output shows a successful response.

```bash
# check if it works
$ echo '{ "id": 0, "jsonrpc": "2.0", "method": "status" }' \
| curl -H 'content-type: application/json' -d @- \
http://127.0.0.1:80/force-bridge/sign-server/api/v1
{
    "id": 0,
    "jsonrpc": "2.0",
    "result": {
        "addressConfig": {
            "ckbAddress": "ckt1qyqx9424gr3p237a36lt8veh50gaavc27jpqmhrdum",
            "ckbPubkeyHash": "0x62d55540e21547dd8ebeb3b337a3d1deb30af482",
            "ethAddress": "0x994B430359BEDCfeb73EB90Fb39416A7dE1F1640"
        },
        "latestChainStatus": {
            "ckb": {
                "latestCkbBlockHash": "0x95e1f7331c7a5a41ef24a8fbecc2ff10d2319fa678479d2345c8b8ebc04f9868",
                "latestCkbHeight": "1417"
            },
            "eth": {
                "latestEthBlockHash": "0xea3470c3ba5f26c4d049e9796940bb973258992d149e0f708774bac1b3182b7b",
                "latestEthHeight": "1180"
            }
        }
    }
}
```

--------------------------------

### Forcecli Ethereum Balance Query Command Reference

Source: https://github.com/nervosnetwork/force-bridge/blob/main/offchain-modules/forcecli-guide.md

Detailed reference for the `forcecli eth balanceOf` command, used to query asset balances on either the Ethereum or CKB network. Parameters include the address, asset contract, and an optional flag to specify the origin network.

```APIDOC
forcecli eth balanceOf:
  -addr, --address: address on eth or ckb
  -s, --asset: contract address of asset (default: "0x0000000000000000000000000000000000000000")
  -o, --origin: whether query balance on eth
```

--------------------------------

### Stop and Remove Services with Docker Compose

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docker/README.md

Stops and removes containers, networks, and volumes defined by Docker Compose. Navigate to the `docker` directory before executing this command.

```shell script
cd docker
docker-compose down
```

--------------------------------

### Upgrade CKB Node and Force Bridge CLI in Docker Compose

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/verifiers-guide/upgrade-ckb-node.md

This snippet shows the necessary changes to a `docker-compose.yml` file to upgrade the CKB node image to `v0.101.0` and the `forcecli` version to `0.0.12` within a Dockerized verifier setup. It updates the CKB image and the `yarn global add` command for `forcecli`.

```diff
  ckb:
-    image: nervos/perkins-tent
+    image: nervos/perkins-tent:v0.101.0
    restart: always
    environment:
      CKB_NETWORK: testnet
    volumes:
      - ./ckb-data:/data
    ports:
      - 3091:9115
  verifier:
    image: node:14
    restart: always
    environment:
      FORCE_BRIDGE_KEYSTORE_PASSWORD: 123456
    volumes:
      - ./force-bridge:/data
    ports:
      - 3092:80
    command: |
      sh -c '
-      yarn global add @force-bridge/cli@latest
+      yarn global add @force-bridge/cli@0.0.12
      forcecli verifier -cfg /data/force_bridge.json
      '
    depends_on:
      - db
      - ckb
```

--------------------------------

### Open Dapp with Parameterized URL

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/dapp-user-guide.md

This section describes how to open the Force Bridge Dapp with pre-filled parameters via a URL, allowing for direct linking to specific bridge operations. It details the available path and query parameters for configuring the bridge direction, asset, amount, and recipient.

```APIDOC
Parameterized URL Structure:
  https://testnet.forcebridge.com/bridge/:from-network/:to-network?xchain-asset=<asset_address>&amount=<bridge_amount>&recipient=<recipient_address>

URL Path Parameters:
  from-network: string
    Description: The source blockchain network.
    Example: Ethereum

  to-network: string
    Description: The destination blockchain network.
    Example: Nervos

URL Query Parameters:
  xchain-asset: string (hex address)
    Description: The address of the original asset to be bridged.
    Example: 0x0000000000000000000000000000000000000000 (represents ETH asset)

  amount: number
    Description: The amount of the asset to bridge.
    Example: 0.05

  recipient: string (CKB address)
    Description: The address of the recipient on the destination chain.
    Example: ckt1q3vvtay34wndv9nckl8hah6fzzcltcqwcrx79apwp2a5lkd07fdx8xrv9tkdrcff8nwev8q9zzvf40xvdhsmck9seps
```

--------------------------------

### Install Capsule Development Tool with Cargo

Source: https://github.com/nervosnetwork/force-bridge/blob/main/README.md

Installs the Capsule tool using Cargo, Rust's package manager, from its Git repository at a specific version tag. This command is essential for setting up the development environment.

```bash
cargo install capsule --git https://github.com/nervosnetwork/capsule.git --tag v0.2.3
```

--------------------------------

### Force Bridge Committee Multisig Configuration

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/deployment.md

Example JSON configuration for a 2-of-3 multisig committee for Force Bridge, detailing Ethereum addresses and CKB multisig script parameters (R, M, publicKeyHashes). This configuration is essential for initiating the contracts.

```JSON
{
  "forceBridge": {
    "eth": {
      "multiSignAddresses": [
        "0xB026351cD0c62aC89e488A840b7205730E8476bd",
        "0x27EE444d5D96094EACecC00194b7026Eb4fD979c",
        "0x0C2207536768EcFFeB11744AdbCC90428a0EE83B"
      ],
      "multiSignThreshold": 2
    },
    "ckb": {
      "multisigScript": {
        "R": 0,
        "M": 2,
        "publicKeyHashes": [
          "0x40dcec2ef1ffc2340ea13ff4dd9671d2f9787e95",
          "0xc8328aabcd9b9e8e64fbc566c4385c3bdeb219d7",
          "0xebf9befcd8396e88cab8fcb920ab149231658f4b"
        ]
      }
    }
  }
}
```

--------------------------------

### Run Force Bridge Relayer Collector Service

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/deployment.md

Bash commands to set up and run the Force Bridge relayer collector service. This involves cloning the repository, installing dependencies, building scripts, and executing the collector with a specified configuration path. This service is run by committee members to watch for cross-chain transactions.

```Bash
# Right now it still needs to clone the repo, build the scripts and run the service, we will publish the cli tool soon
git clone https://github.com/nervosnetwork/force-bridge.git
cd offchain-modules && yarn install && yarn build

# run collector service example
CONFIG_PATH=./packages/scripts/src/integration-test/config/collector.json npx ts-node ./packages/app-relayer/src/index.ts
```

--------------------------------

### Run CKB Dev Chain Docker Container

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docker/README.md

Runs the CKB development chain container, exposing port 8114. The container is removed automatically upon exit.

```shell script
docker run --rm -it -p 8114:8114 ckb-dev:v0.36.0
```

--------------------------------

### Verify CKB RPC and Indexer Endpoints

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/verifiers-guide/deployment.md

These cURL commands are used to verify the operational status and connectivity of the CKB RPC and Indexer endpoints. The first command queries general blockchain information, while the second retrieves specific cells, ensuring the local CKB node is functioning correctly and accessible.

```Bash
echo '{
    "id": 2,
    "jsonrpc": "2.0",
    "method": "get_blockchain_info",
    "params": []
}' \
| tr -d '\n' \
| curl -H 'content-type: application/json' -d @- \
http://localhost:8117/rpc

echo '{
    "id": 2,
    "jsonrpc": "2.0",
    "method": "get_cells",
    "params": [
        {
            "script": {
                "code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8",
                "hash_type": "type",
                "args": "0x8211f1b938a107cd53b6302cc752a6fc3965638d"
            },
            "script_type": "lock"
        },
        "asc",
        "0x64"
    ]
}' \
| tr -d '\n' \
| curl -H 'content-type: application/json' -d @- \
http://localhost:8117/indexer
```

--------------------------------

### Run Geth Private Chain Docker Container with DAG Volume

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docker/README.md

Runs the Geth private chain container, mapping port 8545. It mounts the current directory for configuration and uses a Docker volume `geth-dag` to persist DAG data, significantly speeding up subsequent runs after the initial DAG generation (which can take 5-10 minutes).

```shell script
docker run --rm -it --mount type=bind,source="$(pwd)",target=/config --mount source=geth-dag,target=/root/.ethash -p 8545:8545 geth-priv:v1.9.23
```

--------------------------------

### Verify Force Bridge Verifier Service Status

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/verifiers-guide/deployment.md

Confirm the operational status of the Force Bridge verifier service by sending a JSON-RPC request to its `/status` endpoint. This curl command demonstrates how to query the service and displays the expected JSON response, including address configurations and latest chain synchronization heights for CKB and Ethereum.

```bash
$ echo '{ "id": 0, "jsonrpc": "2.0", "method": "status" }' \
| curl -H 'content-type: application/json' -d @- \
http://127.0.0.1:80/force-bridge/sign-server/api/v1
{
    "id": 0,
    "jsonrpc": "2.0",
    "result": {
        "addressConfig": {
            "ckbAddress": "ckt1qyqx9424gr3p237a36lt8veh50gaavc27jpqmhrdum",
            "ckbPubkeyHash": "0x62d55540e21547dd8ebeb3b337a3d1deb30af482",
            "ethAddress": "0x994B430359BEDCfeb73EB90Fb39416A7dE1F1640"
        },
        "latestChainStatus": {
            "ckb": {
                "latestCkbBlockHash": "0x95e1f7331c7a5a41ef24a8fbecc2ff10d2319fa678479d2345c8b8ebc04f9868",
                "latestCkbHeight": "1417"
            },
            "eth": {
                "latestEthBlockHash": "0xea3470c3ba5f26c4d049e9796940bb973258992d149e0f708774bac1b3182b7b",
                "latestEthHeight": "1180"
            }
        }
    }
}
```

--------------------------------

### Force Bridge Verifier Configuration Example

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/deployment.md

This JSON configuration defines the settings for a Force Bridge verifier, including common network and database parameters, Ethereum (ETH) chain-specific configurations like RPC URL, multi-signature addresses, contract addresses, and asset whitelists, as well as CKB chain-specific settings such as RPC URLs, multisig scripts, and cell dependencies. It specifies logging levels, network type, database connection details, and various chain-specific parameters for bridging assets.

```JSON
{
  "forceBridge": {
    "common": {
      "log": {
        "level": "info"
      },
      "network": "testnet",
      "role": "watcher",
      "orm": {
        "type": "mysql",
        "host": "localhost",
        "port": 3307,
        "username": "root",
        "password": "root",
        "database": "forcebridge",
        "timezone": "Z",
        "synchronize": true,
        "logging": false
      }
    },
    "eth": {
      "rpcUrl": "http://127.0.0.1:8545",
      "multiSignAddresses": [
        "0xB026351cD0c62aC89e488A840b7205730E8476bd",
        "0x27EE444d5D96094EACecC00194b7026Eb4fD979c",
        "0x0C2207536768EcFFeB11744AdbCC90428a0EE83B"
      ],
      "multiSignKeys": [
        {
          "address": "0xB026351cD0c62aC89e488A840b7205730E8476bd",
          "privKey": "privkeys/eth-multisig-1"
        }
      ],
      "contractAddress": "0x8326e1d621Cd32752920ed2A44B49bB1a96c7391",
      "confirmNumber": 1,
      "startBlockHeight": 5,
      "batchUnlock": {
        "batchNumber": 100,
        "maxWaitTime": 86400000
      },
      "assetWhiteList": [
        {
          "address": "0x0000000000000000000000000000000000000000",
          "name": "ETH",
          "symbol": "ETH",
          "decimal": 18,
          "logoURI": "https://cryptologos.cc/logos/ethereum-eth-logo.svg?v=002",
          "minimalBridgeAmount": "1000000000000000",
          "bridgeFee": {
            "in": "1000000000000",
            "out": "2000000000000"
          }
        },
        {
          "address": "0x265566D4365d80152515E800ca39424300374A83",
          "name": "USDC",
          "symbol": "USDC",
          "decimal": 6,
          "logoURI": "https://cryptologos.cc/logos/usd-coin-usdc-logo.svg?v=002",
          "minimalBridgeAmount": "1000",
          "bridgeFee": {
            "in": "10",
            "out": "20"
          }
        }
      ]
    },
    "ckb": {
      "ckbRpcUrl": "http://127.0.0.1:8114",
      "ckbIndexerUrl": "http://127.0.0.1:8116",
      "multisigScript": {
        "R": 0,
        "M": 2,
        "publicKeyHashes": [
          "0x40dcec2ef1ffc2340ea13ff4dd9671d2f9787e95",
          "0xc8328aabcd9b9e8e64fbc566c4385c3bdeb219d7",
          "0x470dcdc5e44064909650113a274b3b36aecb6dc7",
          "0xd9a188cc1985a7d4a31f141f4ebb61f241aec182",
          "0xebf9befcd8396e88cab8fcb920ab149231658f4b"
        ]
      },
      "multiSignKeys": [
        {
          "address": "ckt1qyqvsv5240xeh85wvnau2eky8pwrhh4jr8ts8vyj37",
          "privKey": "privkeys/ckb-multisig-1"
        }
      ],
      "ownerLockHash": "0x49beb8c4c29d06e05452b5d9ea8e86ffd4ea2b614498ba1a0c47890a0ad4f550",
      "deps": {
        "bridgeLock": {
          "cellDep": {
            "depType": "code",
            "outPoint": {
              "txHash": "0x8b42fd0e607dc70cf15f72782a44154197b2beb6c581e24e9888081e66506ad4",
              "index": "0x0"
            }
          },
          "script": {
            "codeHash": "0x098fc87ba45ca95d7904f04c9921e4315e074537294c4cd794dd5237721bf640",
            "hashType": "data"
          }
        },
        "sudtType": {
          "cellDep": {
            "depType": "code",
            "outPoint": {
              "txHash": "0x8b42fd0e607dc70cf15f72782a44154197b2beb6c581e24e9888081e66506ad4",
              "index": "0x2"
            }
          },
          "script": {
            "codeHash": "0xe1e354d6d643ad42724d40967e334984534e0367405c5ae42a9d7d63d77df419",
            "hashType": "data"
          }
        },
        "recipientType": {
          "cellDep": {
            "depType": "code",
            "outPoint": {
              "txHash": "0x8b42fd0e607dc70cf15f72782a44154197b2beb6c581e24e9888081e66506ad4",
              "index": "0x3"
            }
          },
          "script": {
            "codeHash": "0xcfa8deb97db22fe777413c88f6682ad13292af1087f48c41d8f801bf7ad61d58",
            "hashType": "data"
          }
        }
      },
      "startBlockHeight": 0,
      "confirmNumber": 1,
      "ownerCellTypescript": {
        "code_hash": "0x00000000000000000000000000000000000000000000000000545950455f4944",
        "hash_type": "type",
        "args": "0x50726c38a50f3c39d7fa02debf6bcad8f04db5fb2a54e52974c8e260f640a20
```

--------------------------------

### Forcecli Ethereum Asset Lock Command Reference

Source: https://github.com/nervosnetwork/force-bridge/blob/main/offchain-modules/forcecli-guide.md

Detailed reference for the `forcecli eth lock` command, used to lock assets from Ethereum to CKB. Parameters include the private key of the locking account, the amount to lock, the recipient CKB address, and optional asset contract and transaction wait flags.

```APIDOC
forcecli eth lock:
  -p, --privateKey: private key of locked account
  -a, --amount: amount to lock
  -r, --recipient: recipient address on ckb
  -s, --asset: contract address of asset (default: "0x0000000000000000000000000000000000000000")
  -w, --wait: whether wait for transaction confirmed
  -e, --extra: extra data of sudt
```

--------------------------------

### Restart Docker Services After Configuration Changes

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/verifiers-guide/upgrade-ckb-node.md

After modifying the `docker-compose.yml` file, this command rebuilds and restarts the Docker services in detached mode, applying the new configurations for the CKB node and force bridge verifier.

```bash
cd /path/to/docker/compose
docker-compose up -d
```

--------------------------------

### Start Force Bridge Verifier Service

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/deployment.md

Executes the Force Bridge verifier service using `ts-node` with a specific configuration file. The service will listen on port 8090. Verifiers must ensure their `verifier1.json` configuration is correctly set up, especially dynamic parts like endpoints and MySQL settings, before running this command.

```Shell
CONFIG_PATH=./packages/scripts/src/integration-test/config/verifier1.json npx ts-node ./packages/app-multisign-server/src/index.ts --port 8090
```

--------------------------------

### Manually Upgrade Force Bridge CLI

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/verifiers-guide/upgrade-ckb-node.md

This command upgrades the `forcecli` tool globally to version `0.0.12` using Yarn. This is part of the manual upgrade process for the Force Bridge verifier service after stopping it and the CKB node.

```bash
yarn global add @force-bridge/cli@0.0.12
```

--------------------------------

### Claiming ERC20 Test Tokens with Hardhat

Source: https://github.com/nervosnetwork/force-bridge/blob/main/eth-contracts/README.md

This snippet provides a step-by-step guide to claim test ERC20 tokens on a specified network (e.g., BSC testnet) using Hardhat. It involves setting up environment variables, verifying your account address, ensuring it's funded, and then executing the claim command.

```bash
cp .env.example .env

# change your private key and RPC_URL

# check your address in specific network
npx hardhat accounts --network bsc_testnet

# fund the address with associated faucet

# claim test token for your account
npx hardhat claimERC20TestToken --account 0x17c4b5CE0605F63732bfd175feCe7aC6b4620FD2 --network bsc_testnet
```

--------------------------------

### Implementing a Custom Reconciler for Force Bridge

Source: https://github.com/nervosnetwork/force-bridge/blob/main/offchain-modules/packages/reconc/README.md

This TypeScript example demonstrates how to implement the `Reconciler` interface from the `@force-bridge/reconc` module. The `EthLockReconciler` class fetches 'from' records from an on-chain state and 'to' records from a local database, then combines them to create a `Reconciliation` object, ensuring balance between bridge transactions.

```TypeScript
import { Reconciler, Reconciliation } from '@force-bridge/reconc';

class EthLockReconciler implements Reconciler {
  async getFromRecordsByOnChainState(): Promise<FromRecord[]> {
    return contractHelper.getFromRecords();
  }

  async getToRecordsByLocalState(): Promise<ToRecord[]> {
    return db.getMintRecords();
  }

  async fetchReconciliation(): Promise<Reconciliation> {
    const [from, to] = await Promise.all([this.getFromRecordsByOnChainState(), this.getToRecordsByLocalState()]);
    return new Reconciliation(from, to);
  }
}
```

--------------------------------

### Forcecli Ethereum Asset Unlock Command Reference

Source: https://github.com/nervosnetwork/force-bridge/blob/main/offchain-modules/forcecli-guide.md

Detailed reference for the `forcecli eth unlock` command, used to unlock assets from CKB back to Ethereum. Parameters include the recipient Ethereum address, the private key of the CKB unlock address, the amount to unlock, and optional asset contract and transaction wait flags.

```APIDOC
forcecli eth unlock:
  -r, --recipient: recipient address on eth
  -p, --privateKey: private key of unlock address on ckb
  -a, --amount: amount of unlock
  -s, --asset: contract address of asset (default: "0x0000000000000000000000000000000000000000")
  -w, --wait: whether wait for transaction confirmed
```

--------------------------------

### Start Force Bridge Verifier Node with Docker Compose

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/verifiers-guide/deploy-with-docker.md

This command initiates the Force Bridge verifier node and its associated services using Docker Compose. The `-d` flag ensures that the services run in detached mode, allowing the terminal to be used for other tasks. This step assumes that `docker-compose.yml` and `force_bridge.json` have been properly configured.

```bash
docker-compose up -d
```

--------------------------------

### Download and Prepare Force Bridge Configuration Files

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/verifiers-guide/deploy-with-docker.md

This snippet outlines the initial steps to prepare the environment for the Force Bridge verifier node. It includes creating a dedicated directory, copying the `keystore.json` file, and downloading the `docker-compose.yml` and `force_bridge.json` configuration templates from the official GitHub repository. These files are essential for defining the Docker services and the bridge's operational parameters.

```bash
cd /path/to/your/node
mkdir force-bridge
cp /path/to/your/keystore.json force-bridge

# you can also visit the URL below and paste the content to the file
wget https://github.com/nervosnetwork/force-bridge/blob/main/devops/verifier-testnet-docker/docker-compose.yml
wget https://github.com/nervosnetwork/force-bridge/blob/main/devops/verifier-testnet-docker/force-bridge/force_bridge.json -O force-bridge/force_bridge.json
```

--------------------------------

### Run Force Bridge Integration Tests via Docker CI

Source: https://github.com/nervosnetwork/force-bridge/blob/main/README.md

Executes the `make local-ci` command to set up the Force Bridge and run integration tests within a Docker environment. This automates the testing process for local development.

```bash
make local-ci
```

--------------------------------

### Verify Force Bridge Verifier Node Status via API

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/verifiers-guide/deploy-with-docker.md

This command demonstrates how to check the operational status of the Force Bridge verifier node by making a JSON-RPC call to its local API endpoint using `curl`. The request queries for the node's configured addresses and the latest synchronized block heights on both CKB and Ethereum chains. The provided output illustrates a successful response, indicating the node is running and syncing.

```bash
$ echo '{ "id": 0, "jsonrpc": "2.0", "method": "status" }' \
| curl -H 'content-type: application/json' -d @- \
http://127.0.0.1:80/force-bridge/sign-server/api/v1
{
    "id": 0,
    "jsonrpc": "2.0",
    "result": {
        "addressConfig": {
            "ckbAddress": "ckt1qyqx9424gr3p237a36lt8veh50gaavc27jpqmhrdum",
            "ckbPubkeyHash": "0x62d55540e21547dd8ebeb3b337a3d1deb30af482",
            "ethAddress": "0x994B430359BEDCfeb73EB90Fb39416A7dE1F1640"
        },
        "latestChainStatus": {
            "ckb": {
                "latestCkbBlockHash": "0x95e1f7331c7a5a41ef24a8fbecc2ff10d2319fa678479d2345c8b8ebc04f9868",
                "latestCkbHeight": "1417"
            },
            "eth": {
                "latestEthBlockHash": "0xea3470c3ba5f26c4d049e9796940bb973258992d149e0f708774bac1b3182b7b",
                "latestEthHeight": "1180"
            }
        }
    }
}
```

--------------------------------

### Initial Force Bridge Operational Parameters

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/deployment.md

These parameters define the initial operational behavior and dependencies of the Nervos Force Bridge, primarily related to Ethereum transaction confirmations, CKB contract dependencies, and asset handling. They are crucial for the bridge's core functionality.

```APIDOC
eth.confirmNumber: only after the lock transaction is confirmed with this number of blocks, the mapped token will be minted on CKB chain
eth.startBlockHeight: the height force bridge start to watch, usually the height we deploy the bridge contract
eth.batchUnlock: since the Ethereum transaction fee is high, we will unlock asset on Ethereum on batch. We will batch unlock `batchNumber` transactions. To avoid it takes too long to reach the batch size, there is an additional `maxWaitTime`, which will batch the transactions after this time even if the number does not reach the `batchNumber`
eth.assetWhiteList: The asset whitelist of force bridge. We will ignore all crosschain assets not int the list.
ckb.deps: ckb contracts deps
ckb.ownerCellTypescript: The owner cell typescript is used to identify the owner cell. The lockscript of the cell will be the committee multisig lockscript.
ckb.multisigLockscript: The committee multisig lockscript.
```

--------------------------------

### Ethereum ForceBridge Contract Constructor Signature

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/deployment.md

Signature for the ForceBridge.sol smart contract constructor on Ethereum, requiring an array of validator addresses and a multisig threshold. This defines the parameters needed to deploy the bridge contract.

```Solidity
constructor(address[] memory validators, uint256 multisigThreshold)
```

--------------------------------

### Decrypt and Access Keys from Encrypted Keystore File in TypeScript

Source: https://github.com/nervosnetwork/force-bridge/blob/main/offchain-modules/packages/keystore/README.md

Illustrates how to load an encrypted KeyStore from a file, decrypt it using a password, and then access specific private keys by their IDs. This is crucial for using previously saved keystores.

```TypeScript
const store = new KeyStore(fs.readFileSync(filePath).toString());

// decrypt before using the keystore
store.decrypt(process.env.KEYSTORE_PASSWORD);

store.getDecryptedByKeyID('Alice');
store.getDecryptedByKeyID('Bob');
```

--------------------------------

### Modifiable Force Bridge Configuration Settings

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/deployment.md

These parameters are typically user-configurable settings that can be adjusted to customize the Force Bridge's behavior, including logging levels, operational roles, database connections, and RPC endpoints. They allow for adaptation to specific deployment environments and operational needs.

```APIDOC
common.log.level: it can be `info`, `debug` and `error`, change it on your demand
common.role: it can be `collector`, `verifier` and `watcher`
common.orm: change it to your own database configuration
eth.rpcUrl: change it to your own endpoint
eth.multiSighKeys: change it to your own address and privKey path
ckb.ckbRpcUrl: change it to your own endpoint
ckb.ckbIndexerUrl: change it to your own indexer URL
ckb.multiSignKeys: change it to your own ckb private Key
```

--------------------------------

### Define Function with Type-Safe KeyStore Access in TypeScript

Source: https://github.com/nervosnetwork/force-bridge/blob/main/offchain-modules/packages/keystore/README.md

Shows how to define a TypeScript function that explicitly types the KeyStore to only allow access to specific, pre-defined key IDs. This enhances type safety and prevents accidental access to unknown keys, demonstrating secure key usage within a function.

```TypeScript
function AliceTransferToBob(store: KeyStore<'Alice' | 'AliceSecondary'>) {
  const privateKey = store.getDecryptedByKeyID('Alice');
  const privateKey1 = store.getDecryptedByKeyID('AliceSecondary');

  // typescript would marks error if getting with an unknown key
  // const privateKeyUnknown = store.getDecryptedByKeyID('unknown-key');

  signTransaction(tx, privateKey);
  signTransaction(tx1, privateKey1);
}
```

--------------------------------

### CKB Bridge Lockscript Configuration

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/deployment.md

JSON configuration for the CKB bridge lockscript, including its cell dependency (outPoint) and script details (codeHash, hashType) required for deployment. This information is crucial for later interactions with the deployed contract.

```JSON
"bridgeLock": {
  "cellDep": {
    "depType": "code",
    "outPoint": {
      "txHash": "0xa971faeabb549897a0292552127442ab2957e339dfbd38fa05a32a62380bd9f4",
      "index": "0x0"
    }
  },
  "script": {
    "codeHash": "0xdf37272de30a650a360b7a0db8c417b14246416008c9d15b964b69050a3fa23e",
    "hashType": "data"
  }
}
```

--------------------------------

### CKB Owner Cell TypeID and Multisig Lockscript Configuration

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/deployment.md

JSON configuration for the CKB owner cell, specifying its TypeID typescript and multisig lockscript details (code_hash, hash_type, args) for later usage. This cell defines the bridge lockscript owner.

```JSON
  "ownerCellTypescript": {
    "code_hash": "0x00000000000000000000000000000000000000000000000000545950455f4944",
    "hash_type": "type",
    "args": "0x9e299206e0924026cbc283a37de3908172dc68fdd6e96c403de11156b92527bd"
  },
  "multisigLockscript": {
    "code_hash": "0x5c5069eb0857efc65e1bca0c07df34c31663b3622fd3876c876320fc9634e2a8",
    "hash_type": "type",
    "args": "0x7ae4ef98cc4c3e46d359f380cd60c50e3412de5d"
  }
```

--------------------------------

### CKB Burn Transaction Structure

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/data-structure.md

This snippet details the structure of a CKB Burn transaction within the Force Bridge. It outlines the necessary cell dependencies (SUDT), inputs (SUDT input cell), and outputs. The outputs include a recipient data cell containing bridge lockscript details, chain/asset types, amount, and an optional memo, along with a SUDT output cell.

```CKB Transaction Structure
- cell_deps
  - sudt
- inputs   
  - sudt input cell
- outputs
  - recipient data cell
    - bridge lockscript code hash
    - bridge lockscript hash type
    - chain type
    - asset type
    - amount
    - memo
  - sudt output cell
- witnesses
```

--------------------------------

### Memo Field for Ethereum Burn Transactions

Source: https://github.com/nervosnetwork/force-bridge/blob/main/docs/data-structure.md

This section specifies the structure of the memo field used in CKB Burn transactions, specifically for Ethereum. For Ethereum, the memo field contains the recipient's address on the Ethereum chain.

```APIDOC
- eth
  - recipient address
```
Tokens:
Raw