Deployment Guide
Deploy and interact with Alkanes smart contracts on regtest and mainnet
This guide covers deploying Alkanes contracts using alkanes-cli. You'll learn the deployment patterns, CLI commands, and how to interact with deployed contracts.
Deployment Patterns
Alkanes uses specific cellpack patterns for different deployment operations:
| Pattern | Description |
|---|---|
| [3, tx] | Deploy WASM to factory slot [4, tx] - use for templates and factories |
| [6, tx] | Clone from template [4, tx] to next available [2, n] |
| [1, 0] | Deploy via CREATE to next available [2, n] |
AlkaneId Ranges
Different block prefixes indicate different contract types:
| Range | Description |
|---|---|
| [2, n] | Regular deployed contracts (CREATE or CLONE) |
| [4, n] | Factory templates - deployed via [3, n] |
| [6, n] | Clone operations (specifies template to clone) |
| [32, n] | Genesis contracts (frBTC, etc.) |
| [31, n] | System contracts (ftrBTC, etc.) |
CLI Setup
First, set up alkanes-cli and create a wallet:
# Build alkanes-cli from source
cd alkanes-rs
cargo build --release -p alkanes-cli
# Add to PATH
export PATH="$PATH:$(pwd)/target/release"
# Verify installation
alkanes-cli --helpRegtest Environment
Start a local regtest environment for testing:
# Clone alkanes-rs if you haven't
git clone https://github.com/kungfuflex/alkanes-rs.git
cd alkanes-rs
# Start regtest node with Docker
docker-compose up -d
# Wait for services to start
sleep 10
# Check if node is running
curl -s http://127.0.0.1:18888 | head -c 100
# Check metashrew indexer height
curl -X POST http://127.0.0.1:18888 \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"metashrew_height","params":[],"id":1}'Wallet Setup
Create and fund a wallet for deployment:
# Create a new wallet
alkanes-cli -p regtest \
--wallet-file ~/.alkanes/wallet.json \
--passphrase "your-secure-passphrase" \
wallet create
# Mine 400 blocks to fund wallet (regtest only)
alkanes-cli -p regtest \
--wallet-file ~/.alkanes/wallet.json \
--passphrase "your-secure-passphrase" \
bitcoind generatetoaddress 400 "p2tr:0"
# Check balance
alkanes-cli -p regtest \
--wallet-file ~/.alkanes/wallet.json \
--passphrase "your-secure-passphrase" \
wallet balance
# List UTXOs
alkanes-cli -p regtest \
--wallet-file ~/.alkanes/wallet.json \
--passphrase "your-secure-passphrase" \
wallet utxos p2tr:0Protostone Format
The protostone format is: [block,tx,opcode,...args]:output0:output1
| Example | Description |
|---|---|
| [3,1000,0]:v0:v0 | Deploy WASM to [4, 1000], call opcode 0 (initialize) |
| [6,1000,0,arg1,arg2]:v0:v0 | Clone from [4, 1000], pass args to opcode 0 |
| [2,0,77]:v0:v0 | Call opcode 77 (mint) on DIESEL [2,0] |
| [4,65522,0]:v0:v0 | Call opcode 0 on factory at [4, 65522] |
Protostone Format: [block,tx,opcode,...args]:output0:output1
Components:
- block,tx: Target AlkaneId (3 for deploy, 6 for clone, 4 for call)
- opcode: The function to call (0 = initialize, etc.)
- ...args: Additional arguments as u128 values
- :output0:output1: Where to send outputs (v0 = vout 0, etc.)Deploying a Template
Deploy a contract as a factory template at [4, tx]:
# Deploy WASM to [4, 1000] as a template
# Use [3, target_tx] to specify the slot
alkanes-cli -p regtest \
--wallet-file ~/.alkanes/wallet.json \
--passphrase "your-secure-passphrase" \
alkanes execute "[3,1000,0]:v0:v0" \
--envelope ./target/wasm32-unknown-unknown/release/my_token.wasm \
--from p2tr:0 \
--fee-rate 1 \
--mine \
-y
# Verify deployment
alkanes-cli -p regtest alkanes getbytecode "4:1000"
# The bytecode should return non-empty if deployment succeededCloning from Templates
Create instances from templates using [6, template_tx]:
# Clone from template [4, 1000] with initialization args
# This creates a new instance at the next available [2, n]
alkanes-cli -p regtest \
--wallet-file ~/.alkanes/wallet.json \
--passphrase "your-secure-passphrase" \
alkanes execute "[6,1000,0,1000000000]:v0:v0" \
--from p2tr:0 \
--fee-rate 1 \
--mine \
-y
# Parameters:
# - 6: Clone operation
# - 1000: Template at [4, 1000]
# - 0: Opcode (initialize)
# - 1000000000: Initial supply argument
# The new instance will be at [2, sequence]
# Check logs or use alkanes list to find the new IDContract Initialization
Most contracts need initialization after deployment:
# Initialize a contract at [4, 65522] (e.g., AMM Factory)
# Call opcode 0 with initialization parameters
alkanes-cli -p regtest \
--wallet-file ~/.alkanes/wallet.json \
--passphrase "your-secure-passphrase" \
alkanes execute "[4,65522,0,780993,4,65523]:v0:v0" \
--from p2tr:0 \
--inputs 2:1:1 \
--fee-rate 1 \
--mine \
-y
# Parameters:
# - 4,65522: Target contract (factory proxy)
# - 0: Initialize opcode
# - 780993: Pool beacon proxy tx
# - 4,65523: Pool upgradeable beacon ID
# --inputs 2:1:1: Include 1 unit of auth token [2:1]Minting DIESEL
Mine DIESEL tokens by calling opcode 77 on [2,0]:
# Mint DIESEL by calling opcode 77 on [2,0]
alkanes-cli -p regtest \
--wallet-file ~/.alkanes/wallet.json \
--passphrase "your-secure-passphrase" \
alkanes execute "[2,0,77]:v0:v0" \
--to p2tr:0 \
--from p2tr:0 \
--mine \
--change p2tr:0 \
-y
# DIESEL minting follows Bitcoin's emission schedule
# Rewards decrease over time similar to BTC halvingWrapping BTC to frBTC
Convert BTC to frBTC using the wrap-btc command:
# Wrap 1 BTC (100000000 sats) to frBTC
alkanes-cli -p regtest \
--wallet-file ~/.alkanes/wallet.json \
--passphrase "your-secure-passphrase" \
alkanes wrap-btc \
100000000 \
--to p2tr:0 \
--from p2tr:0 \
--mine \
--change p2tr:0 \
-y
# frBTC will be credited at [32, 0]
# The wrapped BTC is held in the protocolCreating AMM Pools
Create liquidity pools using init-pool:
# Create a DIESEL/frBTC liquidity pool
alkanes-cli -p regtest \
--wallet-file ~/.alkanes/wallet.json \
--passphrase "your-secure-passphrase" \
alkanes init-pool \
--pair "2:0,32:0" \
--liquidity "300000000:50000" \
--to p2tr:0 \
--from p2tr:0 \
--mine \
--change p2tr:0 \
--factory "4:65522" \
-y
# Parameters:
# --pair: Token pair (DIESEL [2:0], frBTC [32:0])
# --liquidity: Initial liquidity amounts
# --factory: AMM factory contract IDPerforming Swaps
Swap tokens through AMM pools:
# Swap DIESEL for frBTC through a pool
alkanes-cli -p regtest \
--wallet-file ~/.alkanes/wallet.json \
--passphrase "your-secure-passphrase" \
alkanes swap \
--pool "2:12345" \
--amount-in "1000000" \
--token-in "2:0" \
--min-out "900" \
--to p2tr:0 \
--from p2tr:0 \
--mine \
-y
# Parameters:
# --pool: Pool contract ID
# --amount-in: Amount of input token
# --token-in: Input token ID (DIESEL)
# --min-out: Minimum output (slippage protection)Simulating Calls
Test calls without broadcasting using simulate:
# Simulate a call to get contract state
alkanes-cli -p regtest \
alkanes simulate "2:0:101"
# This calls opcode 101 (GetTotalSupply) on DIESEL
# Returns the total supply without making a transaction
# Simulate pool reserves query
alkanes-cli -p regtest \
alkanes simulate "2:12345:97"
# Returns reserve0 and reserve1 as bytes
# Simulate with trace for debugging
alkanes-cli -p regtest \
alkanes simulate "4:1000:99" --traceVerifying Deployments
Check that contracts deployed correctly:
# Check bytecode exists
alkanes-cli -p regtest alkanes getbytecode "4:1000"
# Get contract name (opcode 99)
alkanes-cli -p regtest alkanes simulate "4:1000:99"
# Get total supply (opcode 101)
alkanes-cli -p regtest alkanes simulate "4:1000:101"
# List all alkanes for an address
alkanes-cli -p regtest \
--wallet-file ~/.alkanes/wallet.json \
--passphrase "your-secure-passphrase" \
alkanes getbalanceMainnet Deployment
For mainnet deployment, change the network flag:
Mainnet Warnings
- Test thoroughly on regtest first
- Use higher fee rates for faster confirmation
- Keep wallet passphrase secure
- Verify contract bytecode before deploying
- Consider using multisig for admin operations
# Deploy to mainnet
alkanes-cli -p mainnet \
--jsonrpc-url "https://mainnet.subfrost.io/v4/jsonrpc" \
--wallet-file ~/.alkanes/mainnet-wallet.json \
--passphrase "your-secure-passphrase" \
alkanes execute "[3,1000,0]:v0:v0" \
--envelope ./my_contract.wasm \
--from p2tr:0 \
--fee-rate 10 \
-y
# Key differences from regtest:
# - Use -p mainnet
# - Set proper --jsonrpc-url for mainnet
# - Use appropriate fee rates (check mempool.space)
# - No --mine flag (wait for real confirmations)
# - Ensure wallet has real BTCTroubleshooting
UTXO not found
Wait for indexer to sync or mine more blocks
Bytecode not found
Check deployment tx confirmed, wait for indexer
Already initialized
Contract already initialized - this is expected
Insufficient funds
Mine more blocks to your wallet address
Auth token required
Include auth token with --inputs flag
Complete Deployment Script
Here's a complete script for deploying a token contract:
#!/bin/bash
# Configuration
WALLET_FILE="$HOME/.alkanes/wallet.json"
PASSPHRASE="your-secure-passphrase"
WASM_FILE="./target/wasm32-unknown-unknown/release/my_token.wasm"
TARGET_TX=1000 # Will deploy to [4, 1000]
# Common CLI options
CLI_OPTS="-p regtest --wallet-file $WALLET_FILE --passphrase $PASSPHRASE"
echo "Building contract..."
cargo build --release --target wasm32-unknown-unknown
echo "Deploying to [4, $TARGET_TX]..."
alkanes-cli $CLI_OPTS \
alkanes execute "[3,$TARGET_TX,0]:v0:v0" \
--envelope "$WASM_FILE" \
--from p2tr:0 \
--fee-rate 1 \
--mine \
-y
echo "Waiting for indexer..."
sleep 5
echo "Verifying deployment..."
BYTECODE=$(alkanes-cli -p regtest alkanes getbytecode "4:$TARGET_TX")
if [ -n "$BYTECODE" ] && [ "$BYTECODE" != "null" ]; then
echo "Success! Contract deployed to [4, $TARGET_TX]"
# Get contract name
echo "Contract name:"
alkanes-cli -p regtest alkanes simulate "4:$TARGET_TX:99"
else
echo "Error: Deployment failed"
exit 1
fi