Build a Token

Step-by-step guide to creating a fungible token on Alkanes

In this tutorial, you'll build a complete fungible token contract with minting, burning, and supply tracking. We'll cover the essential patterns used in production tokens like DIESEL and FROST.

Prerequisites

  • Rust and wasm32-unknown-unknown target installed
  • Basic understanding of Rust
  • alkanes-cli installed
  • Local regtest environment running

Token Overview

Our token will have the following features:

Initialize- Set up the token with name, symbol, and initial supply
Mint- Create new tokens (admin only)
Burn- Destroy tokens to reduce supply
Total Supply- Query the current total supply
Name/Symbol- Return token metadata

Step 1: Project Setup

Create a new Rust project for your token:

# Create project directory
mkdir my-token && cd my-token

# Initialize Rust project
cargo init --lib

# Add WASM target
rustup target add wasm32-unknown-unknown

Step 2: Cargo.toml

Configure your dependencies:

Cargo.toml
[package]
name = "my-token"
version = "0.1.0"
edition = "2021"

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

[dependencies]
# Core Alkanes runtime
alkanes-runtime = { git = "https://github.com/kungfuflex/alkanes-rs" }
alkanes-support = { git = "https://github.com/kungfuflex/alkanes-rs" }
alkanes-macros = { git = "https://github.com/kungfuflex/alkanes-rs" }

# Storage utilities
metashrew-support = { git = "https://github.com/kungfuflex/alkanes-rs" }

# Factory support for MintableToken trait
alkanes-std-factory-support = { git = "https://github.com/kungfuflex/alkanes-rs" }

# Error handling
anyhow = "1.0"

[profile.release]
opt-level = "z"
lto = true
codegen-units = 1
panic = "abort"

Step 3: Token Structure

Define your token struct and message enum:

src/lib.rs
use alkanes_runtime::{
    declare_alkane,
    message::MessageDispatch,
    runtime::AlkaneResponder,
    auth::AuthenticatedResponder,
    storage::StoragePointer,
};
use alkanes_std_factory_support::MintableToken;
use alkanes_support::{
    context::Context,
    id::AlkaneId,
    parcel::{AlkaneTransfer, AlkaneTransferParcel},
    response::CallResponse,
};
use anyhow::{anyhow, Result};
use metashrew_support::index_pointer::KeyValuePointer;
use std::sync::Arc;

/// Our token contract struct
#[derive(Default)]
pub struct MyToken(());

// Implement required traits
impl AlkaneResponder for MyToken {}
impl AuthenticatedResponder for MyToken {}
impl MintableToken for MyToken {}

/// Message dispatch enum - defines our contract's opcodes
#[derive(MessageDispatch)]
pub enum MyTokenMessage {
    /// Opcode 0: Initialize the token
    #[opcode(0)]
    Initialize {
        name: String,
        symbol: String,
        initial_supply: u128,
        auth_units: u128,
    },

    /// Opcode 77: Mint new tokens (admin only)
    #[opcode(77)]
    Mint { amount: u128 },

    /// Opcode 88: Burn tokens
    #[opcode(88)]
    Burn,

    /// Opcode 99: Get token name
    #[opcode(99)]
    #[returns(String)]
    GetName,

    /// Opcode 100: Get token symbol
    #[opcode(100)]
    #[returns(String)]
    GetSymbol,

    /// Opcode 101: Get total supply
    #[opcode(101)]
    #[returns(u128)]
    GetTotalSupply,
}

Step 4: Storage Helpers

Add helper methods for storage access:

impl MyToken {
    // ============================================
    // Storage Pointers
    // ============================================

    fn name_pointer(&self) -> StoragePointer {
        StoragePointer::from_keyword("/name")
    }

    fn symbol_pointer(&self) -> StoragePointer {
        StoragePointer::from_keyword("/symbol")
    }

    fn total_supply_pointer(&self) -> StoragePointer {
        StoragePointer::from_keyword("/totalsupply")
    }

    // ============================================
    // Storage Getters/Setters
    // ============================================

    fn get_name(&self) -> String {
        let bytes = self.name_pointer().get();
        String::from_utf8(bytes.as_ref().clone())
            .unwrap_or_else(|_| String::from("Unknown"))
    }

    fn set_name(&self, name: &str) {
        self.name_pointer().set(Arc::new(name.as_bytes().to_vec()));
    }

    fn get_symbol(&self) -> String {
        let bytes = self.symbol_pointer().get();
        String::from_utf8(bytes.as_ref().clone())
            .unwrap_or_else(|_| String::from("???"))
    }

    fn set_symbol(&self, symbol: &str) {
        self.symbol_pointer().set(Arc::new(symbol.as_bytes().to_vec()));
    }

    fn get_total_supply(&self) -> u128 {
        self.total_supply_pointer().get_value::<u128>()
    }

    fn set_total_supply(&self, supply: u128) {
        self.total_supply_pointer().set_value::<u128>(supply);
    }

    fn increase_supply(&self, amount: u128) -> Result<()> {
        let current = self.get_total_supply();
        let new_supply = current.checked_add(amount)
            .ok_or_else(|| anyhow!("supply overflow"))?;
        self.set_total_supply(new_supply);
        Ok(())
    }

    fn decrease_supply(&self, amount: u128) -> Result<()> {
        let current = self.get_total_supply();
        let new_supply = current.checked_sub(amount)
            .ok_or_else(|| anyhow!("supply underflow"))?;
        self.set_total_supply(new_supply);
        Ok(())
    }
}

Step 5: Initialize

Implement the initialization logic:

impl MyToken {
    fn initialize(
        &self,
        name: String,
        symbol: String,
        initial_supply: u128,
        auth_units: u128,
    ) -> Result<CallResponse> {
        // Prevent re-initialization
        self.observe_initialization()?;

        let context = self.context()?;

        // Set token metadata
        self.set_name(&name);
        self.set_symbol(&symbol);

        // Set initial supply
        self.set_total_supply(initial_supply);

        // Build response
        let mut response = CallResponse::forward(&context.incoming_alkanes);

        // Deploy auth token for admin access
        // Auth token holder can call mint()
        let auth_transfer = self.deploy_auth_token(auth_units)?;
        response.alkanes.0.push(auth_transfer);

        // Mint initial supply to deployer
        if initial_supply > 0 {
            response.alkanes.0.push(AlkaneTransfer {
                id: context.myself.clone(),
                value: initial_supply,
            });
        }

        Ok(response)
    }
}

Step 6: Minting

Add admin-only minting with auth token protection:

impl MyToken {
    fn mint(&self, amount: u128) -> Result<CallResponse> {
        // Verify caller has auth token
        // This will fail if auth token not in incoming_alkanes
        self.only_owner()?;

        let context = self.context()?;

        // Increase total supply
        self.increase_supply(amount)?;

        // Build response - return auth token + newly minted tokens
        let mut response = CallResponse::forward(&context.incoming_alkanes);
        response.alkanes.0.push(AlkaneTransfer {
            id: context.myself.clone(),
            value: amount,
        });

        Ok(response)
    }
}

Step 7: Burning

Implement token burning from incoming transfers:

impl MyToken {
    fn burn(&self) -> Result<CallResponse> {
        let context = self.context()?;
        let myself = context.myself.clone();

        // Calculate how much of our token was sent
        let burn_amount: u128 = context.incoming_alkanes.0
            .iter()
            .filter(|t| t.id == myself)
            .map(|t| t.value)
            .sum();

        if burn_amount == 0 {
            return Err(anyhow!("no tokens to burn"));
        }

        // Decrease total supply
        self.decrease_supply(burn_amount)?;

        // Return any OTHER tokens (not our burned tokens)
        let mut response = CallResponse::default();
        for transfer in &context.incoming_alkanes.0 {
            if transfer.id != myself {
                response.alkanes.0.push(transfer.clone());
            }
        }

        Ok(response)
    }
}

Step 8: Query Methods

Add read-only methods for token metadata:

impl MyToken {
    fn get_name_call(&self) -> Result<CallResponse> {
        let context = self.context()?;
        let mut response = CallResponse::forward(&context.incoming_alkanes);

        // Set response data to token name bytes
        response.data = self.get_name().into_bytes();

        Ok(response)
    }

    fn get_symbol_call(&self) -> Result<CallResponse> {
        let context = self.context()?;
        let mut response = CallResponse::forward(&context.incoming_alkanes);

        // Set response data to token symbol bytes
        response.data = self.get_symbol().into_bytes();

        Ok(response)
    }

    fn get_total_supply_call(&self) -> Result<CallResponse> {
        let context = self.context()?;
        let mut response = CallResponse::forward(&context.incoming_alkanes);

        // Set response data to supply as little-endian bytes
        response.data = self.get_total_supply().to_le_bytes().to_vec();

        Ok(response)
    }
}

Step 9: Complete Contract

Here's the complete token contract:

src/lib.rs (complete)
use alkanes_runtime::{
    declare_alkane,
    message::MessageDispatch,
    runtime::AlkaneResponder,
    auth::AuthenticatedResponder,
    storage::StoragePointer,
};
use alkanes_std_factory_support::MintableToken;
use alkanes_support::{
    context::Context,
    id::AlkaneId,
    parcel::{AlkaneTransfer, AlkaneTransferParcel},
    response::CallResponse,
};
use anyhow::{anyhow, Result};
use metashrew_support::index_pointer::KeyValuePointer;
use std::sync::Arc;

#[derive(Default)]
pub struct MyToken(());

impl AlkaneResponder for MyToken {}
impl AuthenticatedResponder for MyToken {}
impl MintableToken for MyToken {}

#[derive(MessageDispatch)]
pub enum MyTokenMessage {
    #[opcode(0)]
    Initialize {
        name: String,
        symbol: String,
        initial_supply: u128,
        auth_units: u128,
    },

    #[opcode(77)]
    Mint { amount: u128 },

    #[opcode(88)]
    Burn,

    #[opcode(99)]
    #[returns(String)]
    GetName,

    #[opcode(100)]
    #[returns(String)]
    GetSymbol,

    #[opcode(101)]
    #[returns(u128)]
    GetTotalSupply,
}

impl MyToken {
    // Storage pointers
    fn name_pointer(&self) -> StoragePointer {
        StoragePointer::from_keyword("/name")
    }

    fn symbol_pointer(&self) -> StoragePointer {
        StoragePointer::from_keyword("/symbol")
    }

    fn total_supply_pointer(&self) -> StoragePointer {
        StoragePointer::from_keyword("/totalsupply")
    }

    // Getters/setters
    fn get_name(&self) -> String {
        let bytes = self.name_pointer().get();
        String::from_utf8(bytes.as_ref().clone())
            .unwrap_or_else(|_| String::from("Unknown"))
    }

    fn set_name(&self, name: &str) {
        self.name_pointer().set(Arc::new(name.as_bytes().to_vec()));
    }

    fn get_symbol(&self) -> String {
        let bytes = self.symbol_pointer().get();
        String::from_utf8(bytes.as_ref().clone())
            .unwrap_or_else(|_| String::from("???"))
    }

    fn set_symbol(&self, symbol: &str) {
        self.symbol_pointer().set(Arc::new(symbol.as_bytes().to_vec()));
    }

    fn get_total_supply(&self) -> u128 {
        self.total_supply_pointer().get_value::<u128>()
    }

    fn set_total_supply(&self, supply: u128) {
        self.total_supply_pointer().set_value::<u128>(supply);
    }

    fn increase_supply(&self, amount: u128) -> Result<()> {
        let current = self.get_total_supply();
        let new_supply = current.checked_add(amount)
            .ok_or_else(|| anyhow!("supply overflow"))?;
        self.set_total_supply(new_supply);
        Ok(())
    }

    fn decrease_supply(&self, amount: u128) -> Result<()> {
        let current = self.get_total_supply();
        let new_supply = current.checked_sub(amount)
            .ok_or_else(|| anyhow!("supply underflow"))?;
        self.set_total_supply(new_supply);
        Ok(())
    }

    // Opcode handlers
    fn initialize(
        &self,
        name: String,
        symbol: String,
        initial_supply: u128,
        auth_units: u128,
    ) -> Result<CallResponse> {
        self.observe_initialization()?;
        let context = self.context()?;

        self.set_name(&name);
        self.set_symbol(&symbol);
        self.set_total_supply(initial_supply);

        let mut response = CallResponse::forward(&context.incoming_alkanes);
        response.alkanes.0.push(self.deploy_auth_token(auth_units)?);

        if initial_supply > 0 {
            response.alkanes.0.push(AlkaneTransfer {
                id: context.myself.clone(),
                value: initial_supply,
            });
        }

        Ok(response)
    }

    fn mint(&self, amount: u128) -> Result<CallResponse> {
        self.only_owner()?;
        let context = self.context()?;

        self.increase_supply(amount)?;

        let mut response = CallResponse::forward(&context.incoming_alkanes);
        response.alkanes.0.push(AlkaneTransfer {
            id: context.myself.clone(),
            value: amount,
        });

        Ok(response)
    }

    fn burn(&self) -> Result<CallResponse> {
        let context = self.context()?;
        let myself = context.myself.clone();

        let burn_amount: u128 = context.incoming_alkanes.0
            .iter()
            .filter(|t| t.id == myself)
            .map(|t| t.value)
            .sum();

        if burn_amount == 0 {
            return Err(anyhow!("no tokens to burn"));
        }

        self.decrease_supply(burn_amount)?;

        let mut response = CallResponse::default();
        for transfer in &context.incoming_alkanes.0 {
            if transfer.id != myself {
                response.alkanes.0.push(transfer.clone());
            }
        }

        Ok(response)
    }

    fn get_name_call(&self) -> Result<CallResponse> {
        let context = self.context()?;
        let mut response = CallResponse::forward(&context.incoming_alkanes);
        response.data = self.get_name().into_bytes();
        Ok(response)
    }

    fn get_symbol_call(&self) -> Result<CallResponse> {
        let context = self.context()?;
        let mut response = CallResponse::forward(&context.incoming_alkanes);
        response.data = self.get_symbol().into_bytes();
        Ok(response)
    }

    fn get_total_supply_call(&self) -> Result<CallResponse> {
        let context = self.context()?;
        let mut response = CallResponse::forward(&context.incoming_alkanes);
        response.data = self.get_total_supply().to_le_bytes().to_vec();
        Ok(response)
    }
}

// Register the contract entry point
declare_alkane! {
    impl AlkaneResponder for MyToken {
        type Message = MyTokenMessage;
    }
}

Building the Contract

Compile your token to WebAssembly:

# Build for WebAssembly
cargo build --release --target wasm32-unknown-unknown

# Check the output
ls -la target/wasm32-unknown-unknown/release/my_token.wasm

# Optional: Optimize with wasm-opt
wasm-opt -Oz target/wasm32-unknown-unknown/release/my_token.wasm \
  -o my_token_optimized.wasm

Deploying the Token

Deploy your token to regtest:

# Deploy to [4, 1000] with initialization
# Args: opcode(0), name("MyToken"), symbol("MTK"), initial_supply, auth_units
alkanes-cli -p regtest \
  --wallet-file ~/.alkanes/wallet.json \
  --passphrase "your-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

# Wait for indexer
sleep 5

# Verify deployment
alkanes-cli -p regtest alkanes getbytecode "4:1000"

Testing the Token

Test your token with these commands:

# Get token name (opcode 99)
alkanes-cli -p regtest alkanes simulate "4:1000:99"

# Get token symbol (opcode 100)
alkanes-cli -p regtest alkanes simulate "4:1000:100"

# Get total supply (opcode 101)
alkanes-cli -p regtest alkanes simulate "4:1000:101"

# Mint more tokens (requires auth token)
# Note: You'll need to include your auth token in --inputs
alkanes-cli -p regtest \
  --wallet-file ~/.alkanes/wallet.json \
  --passphrase "your-passphrase" \
  alkanes execute "[4,1000,77,1000000]:v0:v0" \
  --inputs "2:n:1" \
  --from p2tr:0 \
  --fee-rate 1 \
  --mine \
  -y

# Burn tokens (send tokens to contract with opcode 88)
alkanes-cli -p regtest \
  --wallet-file ~/.alkanes/wallet.json \
  --passphrase "your-passphrase" \
  alkanes execute "[4,1000,88]:v0:v0" \
  --inputs "4:1000:500000" \
  --from p2tr:0 \
  --fee-rate 1 \
  --mine \
  -y

Advanced Features

Here are some enhancements you could add:

Allowances

Implement approve/transferFrom for delegated transfers

Pausable

Add ability to pause all transfers in emergencies

Upgradeable

Use proxy pattern for upgradeable logic

Vesting

Implement time-locked token releases

Snapshots

Track balances at specific block heights