Broker API

The Broker API is a standalone client that exposes Broker functionality via a JSON API interface.

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.

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:9944assuming it is run locally.
The state_chain.signing_key_file should be the Broker's private key for their on-chain account. The account should be funded (opens in a new tab). The account type should be set to Broker. The default is /etc/chainflip/keys/signing_key_file.
The port is the port on which the Broker will listen for connections. Use 0 to assign a random port. The default is 80.

./chainflip-broker-api --help

chainflip-broker-api
 
USAGE:
    chainflip-broker-api [OPTIONS]
 
OPTIONS:
    -h, --help
            Print help information
 
        --port <PORT>
            The port number on which the broker will listen for connections. Use 0 to assing 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]

RPC Methods

`broker_request_swap_deposit_address`

Parameters:

Source asset as either a string, e.g. "Eth" or "dot", or as an Asset & Chain JSON object, e.g. {"asset": "Eth", "chain": "Ethereum"}
Egress asset as either a string, e.g. "Eth" or "dot", or as an Asset & Chain JSON object, e.g. {"asset": "dot", "chain": "polkadot"}
Egress Address.
Broker Commission in basis points (100th of a percent). 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.

Return:

deposit address.

`broker_register_account`

Parameters:

None

Return:

null if successful, otherwise an error.

Working Example

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

Open a terminal and run:

./chainflip-broker-api \
    --state_chain.ws_endpoint=ws://localhost:9944 \
    --state_chain.signing_key_file /path/to/my/signing_key \
    --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: Register as a broker if you are not already.

curl -H "Content-Type: application/json" \
    -d '{"id":1, "jsonrpc":"2.0", "method": "broker_register_account"}' \
    http://localhost:62378

Request a swap deposit address:

curl -H "Content-Type: application/json" \
    -d '{"id":1, "jsonrpc":"2.0", "method": "broker_request_swap_deposit_address", "params": ["Eth", "Flip","0xabababababababababababababababababababab", 0]}' \
    http://localhost:62378

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

{"jsonrpc":"2.0","result":{"address":"0x4ef7608893d5a06c2689b8d15b4dc400be0954f2",expiry_block:12345},"id":1}

The broker_request_swap_deposit_address request also accepts cross-chain message metadata as an optional fifth parameter:

{"gas_budget":"0x1000", message:[0,1,2,3,4], cf_parameters: [], source_address: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", source_chain: "Bitcoin"}

Limitations

It doesn't seem to work with wss, so make sure the address is specified with ws. It should be ok since we're not going to expose this externally.

Reference

Foreign Chain Addresses

When specifying an address on a foreign chain, the format of the address depends on the chain.

Ethereum: Hex encoded address (With or without 0x prefix), e.g. 0x71C7656EC7ab88b098defB751B7401B5f6d8976F
Polkadot: SS58 encoded address, e.g. 5EYCAe1J1tZx5VX1d6hYt1JqjvY5qoUWQ7Q7Q7Q7Q7Q7Q7Q7
Bitcoin: Base58 encoded address, e.g. 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa

Running a Broker Broker Working Example