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:
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-unknownStep 2: Cargo.toml
Configure your dependencies:
[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:
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:
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.wasmDeploying 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 \
-yAdvanced 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