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:

PatternDescription
[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:

RangeDescription
[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 --help

Regtest 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:0

Protostone Format

The protostone format is: [block,tx,opcode,...args]:output0:output1

ExampleDescription
[3,1000,0]:v0:v0Deploy WASM to [4, 1000], call opcode 0 (initialize)
[6,1000,0,arg1,arg2]:v0:v0Clone from [4, 1000], pass args to opcode 0
[2,0,77]:v0:v0Call opcode 77 (mint) on DIESEL [2,0]
[4,65522,0]:v0:v0Call 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 succeeded

Cloning 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 ID

Contract 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 halving

Wrapping 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 protocol

Creating 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 ID

Performing 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" --trace

Verifying 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 getbalance

Mainnet 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 BTC

Troubleshooting

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:

deploy-token.sh
#!/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