Fetching contributors…
Cannot retrieve contributors at this time
263 lines (201 sloc) 10.4 KB

Anchoring btc service deployment


Bitcoind node deployment

First of all install bitcoind via your package manager and ensure that you use the latest stable version. You may visit official bitcoin site for more information about installation.

Then create bitcoind configuration file in according to this tutorial.

For correct work of the service, the bitcoind configuration file should contain the following settings:

# Run on the test network instead of the real bitcoin network.
# If you want to use main network comment line bellow:
# server=1 tells Bitcoin-Qt and bitcoind to accept JSON-RPC commands.
# Maintain a full transaction index, used by the getrawtransaction rpc call.

# Bind to given address to listen for JSON-RPC connections.
# Use [host]:port notation for IPv6.
# This option can be specified multiple times (default: bind to all interfaces)
# You must specify rpcuser and rpcpassword to secure the JSON-RPC API

These rpc settings will be used by the service.

After creating configuration file, launch bitcoind daemon via command:

bitcoind --daemon

Downloading and indexing of the bitcoin blockchain may take a lot of time, especially for the mainnet.


For now we have no quick "testnet" deployment, but for fast anchoring demonstration you can use built-in anchoring example, and regular deployment guide.

cargo install --example anchoring

Create blockchain with anchoring

After installation you need to generate configuration. For this you need:

Generate template config

At the first stage, one of the participants creates a template of blockchain consensus configuration and broadcast it to other members.

anchoring generate-template \
    <Path where save template config> \
    --anchoring-fee <fee in satoshis> \
    --anchoring-network <Network in which anchoring should work (testnet\bitcoin)>

Generate config for each node

Then each of the participants generates own public and secret node config files.

anchoring generate-config \
    <Path to saved template config> \
    <Path where save public node config> \
    <Path where save private node config> \
    --anchoring-host <bitcoind RPC host> \
    [--anchoring-user <bitcoind RPC username>] \
    [--anchoring-password <bitcoind RPC password>] \
    --peer-addr <external node listening address>

Each node should broadcast public config part.

Finalizing configuration

When the administrator collects all public configs, he can create final node configuration.

Participants need to send some bitcoins to the anchoring address in order to enable Bitcoin anchoring. For this:

  • One of the participants generates initial funding_tx by init command:

    anchoring finalize
        <Path to saved private node config> \
        <Path where save finalized node config> \
        [--anchoring-create-funding-tx <Create initial funding tx with given amount in satoshis>] \
        --public-configs <Path to node1 public config>\
        [<Path to node2 public config> ...]

    This command generates configuration of node and returns txid of generated funding_tx:

  • While others should use this funding_tx.

    anchoring finalize
        <Path to saved private node config> \
        <Path where save finalized node config> \
        [--anchoring-funding-txid <Txid of the initial funding tx>] \
        --public-configs <Path to node1 public config>\
        [<Path to node2 public config> ...]

    This is important, because all nodes in the network should start from one state. As result finalize command generates node configuration file, that can be used to launching.

    Which create the configuration of N exonum anchoring nodes in destination directory using given bitcoind by rpc.

    Also in the generated configuration files you may specify public and private API addresses according to this document.

    Warning! Bitcoind node should have some bitcoin amount greater than <initial_funds>, since the initial funding transaction will be created during the testnet generation. For testnet you may use a faucet to get some coins.

Launching node

Launch all exonum nodes in the testnet. To launch node m, execute:

anchoring run --node-config <destdir>/<m>.toml --db-path <destdir>/db/<m>

If you want to see additional information you may specify log level by environment variable RUST_LOG="exonum_btc_anchoring=info".


As maintainer, you can change the anchoring configuration parameters. These actions must be performed by Exonum configuration service. Visit its tutorial for more explanations.

Change configuration parameters

Variables that you can modify:

  • fee - the amount of the fee for the anchoring transaction.
  • frequency - the frequency in exonum blocks with which the generation of a new anchoring transactions occurs.
  • utxo_confirmations - the minimum number of confirmations in bitcoin network to consider the anchoring transaction as fully confirmed. Uses for transition and initial funding transactions.
  • funding_tx - the hex representation of current funding transaction. Node would use it as input if it did not spent.
  • anchoring_keys - the list of hex-encoded compressed bitcoin public keys of exonum validators that collects into the current anchoring address.

For the anchoring example consensus configuration looks like this:


With these variables you can perform the following actions:

Add funds

Send to anchoring wallet some btc and save raw transaction body hex. Wait until transaction got enough confirmations. Then replace funding_tx variable by saved hex.

Note! If the current anchoring chain becomes unusable you may start a new chain by adding corresponding funding transaction.

Change list of validators

Important warning! This procedure changes the anchoring address. Exonum node needs to wait until the last anchored transaction gets enough confirmations. It is caused by impossibility to sign transaction addressed to old anchoring address by keys from the current configuration. If the last anchoring transaction does not get enough confirmations before anchoring address is changed, the following transferring transaction may be lost because of possible bitcoin forks and transaction malleability. See this article for details.

  • Make sure that difference between the activation height (actual_from) and current Exonum blockchain height is enough for get sufficient confirmations for the latest anchored transaction. Usually 6 hours are enough for this. Calculate how many blocks will be taken during this time and add this number to the current_height.
  • If necessary, generate a new key pair for anchoring.
  • Change list of validators via editing anchoring_keys array.
  • Initiate the config update procedure.
  • Make sure that config update procedure is not delayed. That is, do not delay the voting procedure for the new configuration.
  • Look at the new address of the anchoring by the anchoring public API.

Note! If transferring transaction has been lost you need to establish a new anchoring chain by a new funding transaction.

Updating anchoring address in config

Each exonum node stores in the local configuration a map for the anchoring address and its corresponding private key. The address is encoded using base58check encoding and the private key uses WIF format.

address = "2NCJYWui4LGNZguUw41xBANbcHoKxSVxyzr"
private_key = "cRf74adxyQzJs7V8fHoyrMDazxzCmKAan63Cfhf9i4KL69zRkdS2"

Add the line with new address and corresponding private key for it. If node public key is not changed you must use the old key for the new address otherwise use a new key. After modifying the configuration file you need to restart the node for the changes to take effect.