Contract Structure

​

Anatomy of a Contract

// 1. Import the standard library
use stdlib::*;

// 2. Declare the contract
contract!(name = "token");

// 3. Import other contract interfaces (optional)
interface!(name = "other_contract", path = "other/wit");

// 4. Define storage structure(s)
#[derive(Clone, Default, StorageRoot)]
struct TokenStorage {
    pub ledger: Map<String, Integer>,
}

// 5. Implement the Guest trait (contract logic)
impl Guest for Token {
    fn init(ctx: &ProcContext) {
        TokenStorage::default().init(ctx);
    }

    fn mint(ctx: &ProcContext, n: Integer) {
        let ledger = ctx.model().ledger();
        let account = ctx.signer().to_string();
        let balance = ledger.get(&account).unwrap_or_default();
        ledger.set(account, balance + n);
    }

    fn balance(ctx: &ViewContext, acc: String) -> Option<Integer> {
        ctx.model().ledger().get(&acc)
    }
}

​

The contract! Macro

contract!(name = "my_contract");

• Generates wit-bindgen glue code
• Creates the Guest trait you implement
• Sets up WASM component exports
• The name must match your WIT package

• Must appear after use stdlib::*;
• Name must match the contract name in your WIT file

​

Context Types

​

ViewContext - Read-Only Queries

fn balance(ctx: &ViewContext, acc: String) -> Option<Integer> {
    ctx.model().ledger().get(acc)
}

• ctx.storage() - Access low-level storage
• ctx.model() - Get generated storage model (read-only)

​

ProcContext - State-Modifying Transactions

fn transfer(ctx: &ProcContext, to: String, n: Integer) -> Result<(), Error> {
    let from = ctx.signer().to_string();
    // ... modify storage
}

• ctx.signer() - Transaction signer
• ctx.contract_signer() - Contract’s own address (for receiving tokens)
• ctx.storage() - Access storage
• ctx.model() - Get generated storage model (read-write)
• ctx.generate_id() - Generate unique IDs
• ctx.view_context() - Get read-only view

​

FallContext - Fallback Handler

fn fallback(ctx: &FallContext, expr: String) -> String {
    // Proxy to another contract
    if let Some(addr) = ctx.view_context().model().contract_address() {
        foreign::call(ctx.signer(), &addr, &expr)
    } else {
        "".to_string()
    }
}

• ctx.signer() - Returns Option<Signer> (may be None for view calls)
• ctx.proc_context() - Returns Option<ProcContext> (Some if called with signer)
• ctx.view_context() - Always available

​

WIT Files

​

Relationship to Rust Code

• WIT files are hand-written by you
• They define the public API of your contract
• Every exported function in WIT must be implemented in Rust
• The contract! macro generates Rust types from your WIT

​

Example WIT File

package root:component;

world root {
  // Include built-in types and interfaces
  include kontor:built-in/built-in;

  // Import specific types you'll use
  use kontor:built-in/context.{view-context, proc-context};
  use kontor:built-in/numbers.{integer};
  use kontor:built-in/error.{error};

  // Export functions (your contract's API)
  export init: func(ctx: borrow<proc-context>);
  export mint: func(ctx: borrow<proc-context>, n: integer);
  export transfer: func(ctx: borrow<proc-context>, to: string, n: integer) -> result<_, error>;
  export balance: func(ctx: borrow<view-context>, acc: string) -> option<integer>;
}

​

Built-in WIT Interfaces

• context - Storage and execution context (ViewContext, ProcContext, FallContext)
• numbers - Arbitrary precision Integer and Decimal types
• error - Error type with variants (Message, Overflow, DivByZero, SyntaxError)
• crypto - Hash functions
• foreign - Cross-contract calls

​

Module Organization

​

Workspace Structure

[workspace]
members = ["token", "amm", "pool"]
resolver = "2"

[workspace.dependencies]
wit-bindgen = "=0.47.0"
stdlib = { path = "../core/stdlib" }

​

One Contract Per Crate

• Cargo.toml - Dependencies and build config
• src/lib.rs - Contract implementation
• wit/contract.wit - Interface definition
• wit/deps/ - Symlink to built-in types

​

Build Configuration

[lib]
crate-type = ["cdylib"]  # Required for WASM

[dependencies]
wit-bindgen = "=0.47.0"  # Must be exact version
stdlib = { path = "../core/stdlib" }

[build]
target = "wasm32-unknown-unknown"

[target.wasm32-unknown-unknown]
rustflags = ["-C", "target-feature=-simd128"]

​

Hooks

​

init Hook

fn init(ctx: &ProcContext) {
    MyStorage::default().init(ctx);
}

• Contract is first deployed (publish transaction)
• Automatically by the runtime

• Setting initial storage values
• Contract initialization logic
• Data migrations for upgrades

​

fallback Hook

fn fallback(ctx: &FallContext, expr: String) -> String {
    // Handle calls to non-existent functions
}

• A function is called that doesn’t exist
• Primarily for proxy contracts

• Implementing proxy patterns
• Version upgrades
• Generic delegation

​

Quick Reference

​

Context Types

• Enables state-modifying operations, such as balance transfers
• Provides write access to storage and signer access via ctx.signer()
• Used in functions like mint or transfer to update blockchain state

• Supports read-only queries for inspecting contract state
• Restricts access to read-only storage operations, no signer or mutations allowed
• Used in functions like balance for retrieving data without modifying the blockchain

• Manages unmatched calls via the fallback hook, enabling proxy patterns
• Converts to ViewContext or Option<ProcContext> for storage reads
• Exclusive to the fallback function for dynamic routing

​

Context Traits (for helper functions)

• For mutation logic (e.g., internal updates)
• Implemented only by ProcContext

• For read-only logic (e.g., internal queries)
• Implemented by both ViewContext and ProcContext, enabling shared read operations

​

Storage

• Marks the root struct or enum for contract storage

• Key-value store for collections (e.g., account balances)
• Supports get, set, and keys methods

• ctx.model() - Returns the typed storage model
• Field accessors (e.g., ctx.model().ledger()) - Provide structured access
• Get/set methods - No ctx parameter needed (e.g., ledger.get(&key), ledger.set(key, value))

​

Signer Access

• ctx.signer() - Retrieves the transaction signer (ProcContext only)
• ctx.contract_signer() - Returns the contract’s own address (for receiving tokens)

​

Cross-Contract Calls

import!(name = "token", height = 12345, tx_index = 0, path = "path/to/wit");
// Direct calls: token::transfer(...)

interface!(name = "token_dyn", path = "path/to/wit");
// Dynamic calls with address: token_dyn::transfer(&address, ...)

​

Utilities

• Generates unique IDs for entities (e.g., account IDs)

• Applies sha256 hash and returns hex encoded string and raw bytes

• Applies sha256 hash to string concatenated with salt

​

Error Type

enum Error {
    Message(String),      // Custom error messages
    Overflow(String),     // Arithmetic overflow
    DivByZero(String),    // Division by zero
    SyntaxError(String),  // Syntax errors
}

​

Macros

• Defines contract name and generates boilerplate code from WIT file

• Statically imports another contract’s WIT for cross-contract calls

• Defines dynamic interface for runtime contract calls with dynamic addresses