> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kontor.network/llms.txt
> Use this file to discover all available pages before exploring further.

# 1. Hello World

<Note>
  **Full working code**: The complete source code for this example is available in [`example-contracts/hello-world/`](https://github.com/KontorProtocol/Documentation/tree/main/example-contracts/hello-world)
</Note>

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`:**

```toml theme={null}
[workspace]
members = ["contract", "test"]
resolver = "2"

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

<Note>
  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](/docs/sigil/quickstart#working-with-example-contracts) for setup details.
</Note>

## Step 2: Contract Configuration

**`contract/Cargo.toml`:**

```toml theme={null}
[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`:

```wit theme={null}
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`:

```rust contract/src/lib.rs theme={null}
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:

```bash theme={null}
cd test
cargo test
```

The `build.rs` automatically:

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

**To build manually without running tests:**

```bash theme={null}
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`:

```rust test/src/lib.rs theme={null}
#[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:**

```bash theme={null}
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`