Broker API

The Broker API is a standalone client that exposes Broker functionality via a JSON API interface. It can be obtained from the same location as the chainflip-node, i.e. you can install it via apt, use the provided docker image or compile it yourself from the sources on Github.

Brokers need to run the client for the API themselves, as the Broker holds keys used to sign extrinsics and collect any fees set for Deposit Channels. The API client works by pointing it to an RPC node — also run by the same Broker, ideally.

1. Running Broker API locally

Before you do anything, you need to generate a valid signing_key and fund the associated account. If you are planning to use our Docker setup, instructions on how to generate new keys and fund your account are provided in the github repo.

Option A: Using the pre-compiled binaries

Download the chainflip-broker-api software and the chainflip-node:

apt-get install chainflip-broker-api
apt-get install chainflip-node

For a full list of command line arguments, see chainflip-broker-api --help and chainflip-node --help.

To use the default configuration, run:

Testnet

chainflip-node --chain /etc/chainflip/perseverance.chainspec.json --rpc-methods=unsafe
 
chainflip-broker-api --state_chain.signing_key_file /etc/chainflip/keys/signing_key_file

Mainnet

chainflip-node --chain /etc/chainflip/berghain.chainspec.json --rpc-methods=unsafe
 
chainflip-broker-api --state_chain.signing_key_file /etc/chainflip/keys/signing_key_file

Avoid exposing the chainflip-node publicly with these settings, as anyone could redeem your earned fees!

Option B: Running the Broker API with Docker Compose

Alternatively, for a quick start with the Broker API, we have provided a docker-compose setup that runs the Broker API and a State Chain node (required).

2. Registering the account

After being funded, before you can fully interact with the Broker API, your account needs to be registered as a Broker account.

Command line arguments and defaults

The state_chain.ws_endpoint should point at a synced Chainflip State Chain RPC node. The default is ws://localhost:9944 — assuming it is run locally.
The state_chain.signing_key_file should be a path to a file containing the hex-encoded private key for the on-chain Broker account. The default file path is /etc/chainflip/keys/signing_key_file. The account should be funded and the account role should be set to Broker.
The port is the port on which the Broker API will listen for connections. Use 0 to assign a random port. The default is 80.
New functionality available from version 1.7+: The health_check.hostname and health_check.port describe the hostname and port where the Broker API will listen for health check requests. Both arguments have to be specified for the health check server to start.

chainflip-broker-api --help

chainflip-broker-api
 
USAGE:
    chainflip-broker-api [OPTIONS]
 
OPTIONS:
    -h, --help
            Print help information
 
        --health_check.hostname <HEALTH_CHECK_HOSTNAME>
            Hostname for this server's healthcheck. Requires the <HEALTH_CHECK_PORT> parameter to be
            given as well.
 
        --health_check.port <HEALTH_CHECK_PORT>
            Port for this server's healthcheck. Requires the <HEALTH_CHECK_HOSTNAME> parameter to be
            given as well.
 
        --max_connections <MAX_CONNECTIONS>
            The maximum number of concurrent websocket connections to accept. [default: 100]
 
        --port <PORT>
            The port number on which the broker will listen for connections. Use 0 to assign a
            random port. [default: 80]
 
        --state_chain.signing_key_file <SIGNING_KEY_FILE>
            A path to a file that contains the broker's secret key for signing extrinsics.
            [default: /etc/chainflip/keys/signing_key_file]
 
        --state_chain.ws_endpoint <WS_ENDPOINT>
            The state chain node's RPC endpoint. [default: ws://localhost:9944]
 
    -v, --version
            Print version information

3. Using the Broker: RPC Methods

`broker_request_swap_deposit_address`

Parameters:

source_asset: Source asset.
destination_asset: Egress asset.
destination_address: Egress Address.
broker_commission: Broker Commission in basis points (100th of a percent or 0.01%). Broker operators can choose to charge a fee for the use of their endpoint, and can be set at any value from 1 basis point to 1000 basis points (0.01% - 10%).
channel_metadata: (Optional) Cross-chain message metadata as a JSON object: {"gas_budget": <hex_string>, "message":<hex_string>, "cf_parameters": <hex_string>}. Where gas_budget, message and cf_parameters are hex encoded strings.
boost_fee: (Optional) Maximum accepted boost fee in basis points (100th of a percent).
affiliate_fees: (Optional) Array of affiliate brokers (up to 5).
refund_parameters: (Optional) Minimum accepted price for swaps through the channel as JSON object: {"retry_duration": <number>, "refund_address": <address>, "min_price": <hex_string>}. Where retry_duration is a number of blocks, refund_address is an address, and min_price is a price.
dca_parameters: (Optional) DCA parameters for swaps through the channel as JSON object: {"number_of_chunks": <number>, "chunk_interval": <number>}. Where number_of_chunks is the number of "sub-swaps" to perform, and chunk_interval is the delay between them in number of blocks.

Where every affiliate broker is defined as follow:

{
	account: AccountId,
	bps: BasisPoints,
}

The total broker fee is the sum of the broker_commission + all the affiliate_fees.

Return:

deposit address.

`broker_register_account`

Parameters:

None

Return:

null if successful, otherwise an error.

curl 'http://localhost/' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "broker_register_account"}' | jq

`broker_withdraw_fees`

Withdraw all accumulated fees for a given asset.

Parameters:

asset: The asset to withdraw.
destination_address: The destination address to which the assets should be withdrawn.

Return:

tx_hash: Hash,
egress_id: [ForeignChain, Number],
egress_amount: Amount,
egress_fee: Amount,
destination_address: Address,

Example input:

curl 'http://localhost/' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "broker_withdraw_fees", "params": {"asset": {"chain": "Ethereum", "asset": "ETH"}, "destination_address": "0xabababababababababababababababababababab"}}' | jq

Example output:

{
  "jsonrpc": "2.0",
  "result": {
    "tx_hash": "0x736c159fec96ea84b8eceb49258019625a17e68ab981a3a674261e1df00a0482",
    "egress_id": [
      "Ethereum",
      103
    ],
    "egress_amount": 99998499999503000,
    "egress_fee": 490000,
    "destination_address": "0xabababababababababababababababababababab"
  },
  "id": 1
}

Working Example

This example assumes the node that is exposing the Statechain RPC's is funded.

Open a terminal and run:

RUST_LOG=info chainflip-broker-api \
    --state_chain.ws_endpoint=ws://localhost:9944 \
    --state_chain.signing_key_file /etc/chainflip/keys/signing_key_file \
    --port 62378 # or whatever port you want to use

It will print 🎙 Server is listening on 0.0.0.0:62378. and continue to run.

Open another terminal and run:

curl 'http://localhost:62378/' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "broker_register_account"}'

Request a swap deposit address:

curl 'http://localhost:62378/' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "broker_request_swap_deposit_address", "params": ["ETH", "FLIP","0xabababababababababababababababababababab", 0]}'

The result is the hex encoded deposit address, channel id, expiry block, and the issued block:

{
    "jsonrpc":"2.0",
    "result":{
        "address":"0xe720e23f62efc931d465a9d16ca303d72ad6c0bc",
        "issued_block":5418,
        "channel_id":6,
        "source_chain_expiry_block":2954
    },
    "id":1
}

Limitations

The current API architecture supports only ws and not wss.

Reference

Assets

Assets are specified as a { chain, asset } object, where the chain is as described below, and the asset is an upper-case string.

Where the chain is unambiguous (for example for the native currencies), the asset can be submitted simply as the upper-case string.

For example, for BTC, "BTC" and { chain: "Bitcoin", asset: "BTC" } are both valid and resolve to the same asset.

Assets returned from the RPCs will always take the explicit form, for example { chain: "Ethereum", asset: "ETH" }

Chains

Chains are specified as the full name of the chain, capitalised, for example "Ethereum", "Bitcoin", "Polkadot".

Addresses

Addresses should be encoded according to their host chains:

Ethereum addresses should be encoded as Hex strings, for example "0xfa36e03defc6e4d140cc61fcaab9d1fbef18642f".
Polkadot addresses can be encoded using SS58 or Hex strings, for example: "13zyEWmmLDx63Y99TL9SkxBe1DqPVCrcjXytxM3ZHGRyEJV5" or "0x84aec0876dbb3cb7391eeded2eef5fbcf0d1a34f7c9f86f9af205f944b461761"
Bitcoin addresses should be encoded using the appropriate bitcoin standard for the address type. For example "tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx" is a valid bech32 address on Bitcoin testnet.

Price

A 256 bit unsigned fixed point number, with 128 fractional bits, representing a price as the amount of quote asset a single unit of the base asset is valued at. Note the amounts are in the smallest units of both assets.

Introduction to Brokers Working Example