1. Hello World

Full working code: The complete source code for this example is shown on this page. More complete example contracts are available in test-contracts/

This example walks you through creating your first Sigil contract—a simple “Hello World” that demonstrates the fundamental structure and workflow.

Project Structure

hello-world/
├── Cargo.toml          # Workspace configuration
├── contract/
│   ├── Cargo.toml      # Contract dependencies
│   ├── wit/
│   │   └── contract.wit
│   └── src/
│       └── lib.rs
└── test/
    ├── Cargo.toml      # Test dependencies
    └── src/
        └── lib.rs

Step 1: Workspace Configuration

Root Cargo.toml:

[workspace]
members = ["contract", "test"]
resolver = "2"

[workspace.dependencies]
stdlib = { path = "../../Kontor/core/stdlib" }
testlib = { path = "../../Kontor/core/testlib" }

The paths shown assume the Documentation and Kontor repos are siblings. If you cloned them to different locations, adjust these paths to point to your Kontor installation. See Getting Started for setup details.

Step 2: Contract Configuration

contract/Cargo.toml:

[package]
name = "hello-world"
version = "0.1.0"
edition = "2024"

[dependencies]
stdlib = { workspace = true }

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

Key points:

crate-type = ["cdylib"] - Builds a dynamic library for WASM
stdlib provides the contract! macro and runtime primitives

Step 3: Define the Contract Interface (WIT)

Create contract/wit/contract.wit:

package root:component;

world root {
    include kontor:built-in/built-in;
    use kontor:built-in/context.{view-context, proc-context};

    export init: func(ctx: borrow<proc-context>);

    export hello-world: func(ctx: borrow<view-context>) -> string;
}

What this defines:

init - Called once when contract is deployed
hello-world - Returns a greeting string (read-only)

The kontor:built-in types are available via a symlink at wit/deps/built-in.wit.

Step 4: Implement the Contract

Create contract/src/lib.rs:

contract/src/lib.rs

use stdlib::*;

contract!(name = "hello-world");

impl Guest for HelloWorld {
    fn init(_ctx: &ProcContext) {}

    fn hello_world(_ctx: &ViewContext) -> String {
        "Hello, World!".to_string()
    }
}

How it works:

contract!(name = "hello-world") - Generates the Guest trait and WASM bindings
impl Guest for HelloWorld - The contract name is converted to PascalCase
init() - Empty because we don’t need storage
hello_world() - Returns a static string

Step 5: Build and Test

The contract is automatically built when you run tests. The test directory’s build.rs handles compilation, optimization, and compression:

cd test
cargo test

The build.rs automatically:

Compiles the contract to WASM
Optimizes with wasm-opt -Oz --enable-bulk-memory --enable-sign-ext
Compresses with brotli to create .wasm.br

To build manually without running tests:

cd contract
cargo build --release --target wasm32-unknown-unknown
wasm-opt -Oz --enable-bulk-memory --enable-sign-ext \
  target/wasm32-unknown-unknown/release/hello_world.wasm \
  -o hello_world_opt.wasm
brotli -Zf hello_world_opt.wasm -o hello_world.wasm.br

Step 6: Write Tests

Create test/src/lib.rs:

test/src/lib.rs

#[cfg(test)]
mod tests {
    use testlib::*;

    interface!(name = "hello-world");

    #[testlib::test]
    async fn test_contract() -> Result<()> {
        let alice = runtime.identity().await?;
        let hello_world = runtime.publish(&alice, "hello-world").await?;
        let result = hello_world::hello_world(runtime, &hello_world).await?;
        assert_eq!(result, "Hello, World!");
        Ok(())
    }
}

What this does:

interface! - Generates type-safe bindings from the WIT file
#[testlib::test] - Auto-injects the runtime variable
runtime.identity() - Creates a test user with gas funding
runtime.publish() - Deploys the contract and returns its address
hello_world::hello_world() - Calls the contract function

Run tests:

cd test
cargo test

Common First-Time Issues

contract! macro not found

error: cannot find macro `contract` in this scope

Solution: Add use stdlib::*; at the top of your file Missing Guest trait implementation

error: not all trait items implemented, missing: `hello_world`

Solution: Ensure you’ve implemented all functions listed in your WIT file. Function names with hyphens in WIT become underscores in Rust. WIT file parse error

error: expected `include`, `use`, `import`, `export`, or `type`

Solution: Ensure you have include kontor:built-in/built-in; in your WIT world Build target not installed

error: can't find crate for `core`

Solution: Install the WASM target: rustup target add wasm32-unknown-unknown

Basics

Reference

Examples

SDK

Project Structure

Step 1: Workspace Configuration

Step 2: Contract Configuration

Step 3: Define the Contract Interface (WIT)

Step 4: Implement the Contract

Step 5: Build and Test

Step 6: Write Tests

Common First-Time Issues

​Project Structure

​Step 1: Workspace Configuration

​Step 2: Contract Configuration

​Step 3: Define the Contract Interface (WIT)

​Step 4: Implement the Contract

​Step 5: Build and Test

​Step 6: Write Tests

​Common First-Time Issues

Project Structure

Step 1: Workspace Configuration

Step 2: Contract Configuration

Step 3: Define the Contract Interface (WIT)

Step 4: Implement the Contract

Step 5: Build and Test

Step 6: Write Tests

Common First-Time Issues