Skip to content

Latest commit

 

History

History

basic_bitcoin

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Basic Bitcoin

Open in ICP Ninja

🥷 Try it live — no local setup. ICP Ninja is a web-based IDE that builds and deploys this project to the mainnet for free, right in your browser. Click the badge above, or hit Deploy if you're already in Ninja. To build and run it locally instead, follow the steps below.

This example demonstrates how a canister can send and receive Bitcoin on the Internet Computer using threshold ECDSA and Schnorr signatures. It covers three address types (P2PKH, P2TR key-path, P2TR script-path), querying balances and UTXOs, reading chain state, and sending transactions.

For a deeper understanding of the ICP ↔ Bitcoin integration, see the Bitcoin integration concepts.

Architecture

The canister uses three ICP management canister APIs:

Address types

The example covers three Bitcoin address types, each backed by a different signing key:

  • P2PKH — Pay-to-Public-Key-Hash. Derived from a threshold ECDSA key. The classic Bitcoin address format.
  • P2TR key-only — Pay-to-Taproot, key-path spend only. Derived from a threshold Schnorr key with an unspendable script tree. Simpler Taproot: only the internal key can spend.
  • P2TR (key + script path) — Pay-to-Taproot with a Merkleized Alternative Script Tree (MAST). Funds can be spent either via the internal key (key path) or via a script that authorizes a second Schnorr public key (script path). Demonstrates BIP341 script-path spending.

Build and deploy from the command line

Prerequisites

  • Node.js v18+
  • icp-cli: npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm
  • ic-mops: npm install -g ic-mops
  • Docker (required for local testing — bundles the IC network launcher + bitcoind)

Install

git clone https://github.com/dfinity/examples
cd examples/motoko/basic_bitcoin

Local deployment

The local environment uses a self-contained Docker image (icp-cli-network-launcher-bitcoin) that runs bitcoind in regtest mode alongside the IC network. Build it once:

./build-image.sh

Then deploy and run tests:

icp network start -d
icp deploy --cycles 30t
make test
icp network stop

If tests fail with an out-of-cycles error, top up the canister and retry:

icp canister top-up --amount 30t backend

Deploy to the IC network

The ic environment deploys to IC mainnet connected to Bitcoin testnet4, using test_key_1:

icp deploy -e ic --cycles 30t

To deploy to Bitcoin mainnet, change the init_args for the ic environment in icp.yaml from testnet to mainnet. The canister automatically selects key_1 (the production threshold signing key) when initialized with the mainnet variant.

Environments

Environment IC network Bitcoin network Key
local local (PocketIC) regtest test_key_1
ic IC mainnet testnet4 test_key_1

Available functions

Address generation

icp canister call backend get_p2pkh_address '()'
icp canister call backend get_p2tr_key_only_address '()'
icp canister call backend get_p2tr_address '()'

Chain queries

icp canister call backend get_balance '("YOUR_ADDRESS")'
icp canister call backend get_utxos '("YOUR_ADDRESS")'
icp canister call backend get_current_fee_percentiles '()'
icp canister call backend get_block_headers '(0 : nat32, null)'
icp canister call backend get_blockchain_info '()'

Sending Bitcoin

icp canister call backend send_from_p2pkh_address \
  '(record { destination_address = "DEST"; amount_in_satoshi = 4321 })'
icp canister call backend send_from_p2tr_key_only_address \
  '(record { destination_address = "DEST"; amount_in_satoshi = 4321 })'
icp canister call backend send_from_p2tr_address_key_path \
  '(record { destination_address = "DEST"; amount_in_satoshi = 4321 })'
icp canister call backend send_from_p2tr_address_script_path \
  '(record { destination_address = "DEST"; amount_in_satoshi = 4321 })'

Local testing: mine blocks and fund an address

# Get a P2PKH address
ADDR=$(icp canister call backend get_p2pkh_address '()' | grep -o '"[^"]*"' | tr -d '"')

# Mine 101 blocks to that address via the bundled bitcoind
CONTAINER=$(docker ps --filter "ancestor=icp-cli-network-launcher-bitcoin" --format "{{.ID}}" | head -1)
docker exec "$CONTAINER" bitcoin-cli -regtest \
  -rpcuser=ic-btc-integration -rpcpassword=ic-btc-integration \
  generatetoaddress 101 "$ADDR"

# Wait for the IC to sync, then check balance
sleep 5
icp canister call backend get_balance "(\"$ADDR\")"

Security considerations and best practices

Refer to the security best practices for information on security and best practices for your ICP app.