Quick Start

This guide will help you build and deploy your first Alkane smart contract on Bitcoin.

Prerequisites

Before you begin, make sure you have:

  • Rust (1.70 or later) – Install from rustup.rs
  • wasm-pack – cargo install wasm-pack
  • Node.js (18 or later) – For the CLI and tooling

Step 1: Install the CLI

Clone and build from source (develop branch):

# Clone alkanes-rs (develop branch)
git clone https://github.com/kungfuflex/alkanes-rs.git -b develop
cd alkanes-rs

# Build the CLI
cargo build --release -p alkanes-cli

# Add to PATH (optional)
export PATH="$PWD/target/release:$PATH"

Note: The CLI is not published to npm. Build from source is the only installation method.

Step 2: Create a Wallet

# Create a new wallet
alkanes-cli wallet create

# Or import an existing mnemonic
alkanes-cli wallet import

# Fund your wallet (testnet/signet)
alkanes-cli wallet receive  # Shows your address

Step 3: Create Your Contract

Create a new Rust project:

cargo new --lib my-alkane
cd my-alkane

Update Cargo.toml:

[package]
name = "my-alkane"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
alkanes-std = { git = "https://github.com/kungfuflex/alkanes-rs" }
alkanes-support = { git = "https://github.com/kungfuflex/alkanes-rs" }

[profile.release]
opt-level = "z"
lto = true

Write your contract in src/lib.rs:

use alkanes_std::prelude::*;
use alkanes_support::context::Context;

#[derive(Default)]
pub struct MyAlkane {
    counter: u64,
}

impl MyAlkane {
    // Initialize the contract
    pub fn new() -> Self {
        Self { counter: 0 }
    }

    // Increment the counter
    pub fn increment(&mut self) {
        self.counter += 1;
    }

    // Get the current count
    pub fn get_count(&self) -> u64 {
        self.counter
    }
}

// Export the contract
alkane!(MyAlkane);

Step 4: Build the Contract

# Build to WASM
wasm-pack build --target web --release

# The output will be in pkg/my_alkane_bg.wasm

Step 5: Deploy to Bitcoin

# Deploy to signet (testnet)
alkanes-cli -p signet alkanes execute "[3,0,0]" \
  --envelope "./pkg/my_alkane_bg.wasm" \
  --fee-rate 10 \
  -y

# The output will show your contract's Alkane ID
# e.g., [2, 1] means block 2, tx index 1

Step 6: Interact with Your Contract

# Call the increment function (opcode 1)
alkanes-cli -p signet alkanes execute "[2,1,1]" \
  --fee-rate 10 \
  -y

# Query the count (opcode 2)
alkanes-cli -p signet alkanes view "[2,1]" "2"

Example Contracts

Check out these example contracts in the alkanes-rs repository:

  • DIESEL token – Fungible token implementation
  • frBTC – Wrapped BTC with futures support
  • AMM Pool – Automated market maker