Project Setup
Set up your development environment for building Alkanes smart contracts
Alkanes smart contracts are written in Rust and compiled to WebAssembly (WASM). This guide walks you through setting up a complete development environment.
Prerequisites
- Rust toolchain (rustup, cargo)
- wasm32-unknown-unknown target
- Docker (for local regtest environment)
- alkanes-cli (for deployment and interaction)
1. Install Rust & WASM Target
Install Rust using rustup and add the WebAssembly target:
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Add WASM target
rustup target add wasm32-unknown-unknown
# Verify installation
rustc --version
cargo --version2. Project Structure
A typical Alkanes contract project has this structure:
my-alkane/
├── Cargo.toml # Dependencies and build config
├── src/
│ └── lib.rs # Contract entry point
└── target/
└── wasm32-unknown-unknown/
└── release/
└── my_alkane.wasm # Compiled contract3. Cargo.toml Configuration
Configure your contract's dependencies:
Cargo.toml
[package]
name = "my-alkane"
version = "0.1.0"
edition = "2021"
[lib]
crate-type = ["cdylib", "rlib"]
[dependencies]
# Core runtime - required for all contracts
alkanes-runtime = { git = "https://github.com/kungfuflex/alkanes-rs" }
alkanes-support = { git = "https://github.com/kungfuflex/alkanes-rs" }
# Procedural macros for message dispatch
alkanes-macros = { git = "https://github.com/kungfuflex/alkanes-rs" }
# Storage utilities
metashrew-support = { git = "https://github.com/kungfuflex/alkanes-rs" }
# Error handling
anyhow = "1.0"
[profile.release]
opt-level = "z" # Optimize for size
lto = true # Link-time optimization
codegen-units = 1 # Better optimization
panic = "abort" # Smaller binary4. Basic Contract Template
Create your contract entry point in src/lib.rs:
src/lib.rs
use alkanes_runtime::runtime::AlkaneResponder;
use alkanes_support::response::CallResponse;
use alkanes_macros::{declare_alkane, MessageDispatch};
use anyhow::Result;
/// Your contract struct - holds no state (state is in storage)
#[derive(Default)]
pub struct MyAlkane(());
/// Message enum - defines your contract's opcodes
#[derive(MessageDispatch)]
pub enum MyAlkaneMessage {
/// Opcode 0: Initialize the contract
#[opcode(0)]
Initialize,
/// Opcode 99: Get the contract name
#[opcode(99)]
#[returns(String)]
GetName,
}
impl MyAlkane {
/// Called when opcode 0 is received
pub fn initialize(&self) -> Result<CallResponse> {
// Prevent re-initialization
self.observe_initialization()?;
let context = self.context()?;
let response = CallResponse::forward(&context.incoming_alkanes);
Ok(response)
}
/// Called when opcode 99 is received
pub fn get_name(&self) -> Result<CallResponse> {
let context = self.context()?;
let mut response = CallResponse::forward(&context.incoming_alkanes);
response.data = b"MyAlkane".to_vec();
Ok(response)
}
}
// Implement the responder trait
impl AlkaneResponder for MyAlkane {}
// Register the contract entry point
declare_alkane! {
impl AlkaneResponder for MyAlkane {
type Message = MyAlkaneMessage;
}
}5. Build Your Contract
Compile to WebAssembly:
# Build for WebAssembly
cargo build --release --target wasm32-unknown-unknown
# Find your compiled contract
ls -la target/wasm32-unknown-unknown/release/*.wasm
# Optional: Optimize with wasm-opt (from binaryen)
wasm-opt -Oz target/wasm32-unknown-unknown/release/my_alkane.wasm \
-o my_alkane_optimized.wasm6. Local Development Environment
Set up a local regtest environment for testing:
# Clone alkanes-rs repository
git clone https://github.com/kungfuflex/alkanes-rs.git
cd alkanes-rs
# Start regtest environment with Docker
docker-compose up -d
# Wait for services to start
sleep 10
# Verify the node is running
curl -s http://127.0.0.1:18888 | head -c 100
# Check metashrew indexer
curl -X POST http://127.0.0.1:18888 \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"metashrew_height","params":[],"id":1}'7. Install alkanes-cli
Build and install the CLI for deployment:
# 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 --help8. Create a Wallet
Create a wallet for regtest deployment:
# Create a new wallet
alkanes-cli -p regtest \
--wallet-file ~/.alkanes/wallet.json \
--passphrase "your-secure-passphrase" \
wallet create
# Fund the wallet (mine 400 blocks)
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