Zig Guide

Overview

Ashen contracts can be written in Zig and compiled to the Ashen VM’s RV64 freestanding target. This guide walks through the canonical contract layout, entrypoint patterns, and build flow using the Ashen Zig SDK.

Prerequisites

• Use the pinned toolchain. Build with the exact Zig toolchain provided by devenv (or the Docker image built from it). Validators validate the ELF output from the canonical compilers; mismatched toolchains are rejected.
• Ashen SDK: Contracts must use contracts/ashen-sdk. Do not reimplement storage, dispatch, or syscall helpers.
• IDL file: Every contract has a *.idl file that defines its interface.

Project Layout

A typical Zig contract lives under contracts/<name>/:

contracts/my_contract/
├── build.zig
├── linker.ld
├── my_contract.idl
└── src/
    ├── main.zig
    ├── abi.zig
    └── my_contract.manifest.v1.json

• build.zig targets RV64 freestanding and wires in ashen-sdk.
• linker.ld keeps code/data at low addresses for the VM.
• abi.zig + *.manifest.v1.json are generated from IDL.

Contract Skeleton

The recommended pattern is to use the SDK dispatch helper with IDL-generated stubs:

const sdk = @import("ashen-sdk");
const abi = @import("abi.zig");

const Counter = struct {
    pub fn get(self: *Counter, args: abi.GetArgs) abi.ContractResult(abi.GetResult) {
        _ = self;
        _ = args;
        const value: u128 = sdk.storage.readU128OrDefault("count", 0);
        return .{ .Ok = .{ .value = value } };
    }

    pub fn inc(self: *Counter, args: abi.IncArgs) abi.ContractResult(abi.IncResult) {
        _ = self;
        _ = args;
        const value: u128 = sdk.storage.readU128OrDefault("count", 0) + 1;
        _ = sdk.storage.writeU128("count", value);
        return .{ .Ok = .{ .value = value } };
    }
};

export fn _start(calldata_ptr: [*]const u8, calldata_len: usize) sdk.ByteSlice {
    return sdk.dispatch.run(Counter, abi.dispatch, calldata_ptr, calldata_len);
}

pub const panic = sdk.panic;

Notes:

• sdk.dispatch.run handles heap reset, calldata slicing, and error encoding.
• The entrypoint must be named _start.
• Always export pub const panic = sdk.panic;.

Concrete Walkthrough: Counter Contract

This is a minimal end-to-end example you can copy into a new contract.

1) Create the contract folder + IDL

mkdir -p contracts/counter/src

contracts/counter/counter.idl:

namespace counter;

interface Counter {
    fn get() -> u128;
    fn inc() -> u128;
}

2) Generate Zig stubs from IDL

cargo run -p idl-abi-gen -- \
  --idl contracts/counter/counter.idl \
  --out-dir contracts/counter/src \
  --zig-stubs

3) Implement the contract

contracts/counter/src/main.zig:

const sdk = @import("ashen-sdk");
const abi = @import("abi.zig");

const Counter = struct {
    pub fn get(self: *Counter, args: abi.GetArgs) abi.ContractResult(abi.GetResult) {
        _ = self;
        _ = args;
        const value: u128 = sdk.storage.readU128OrDefault("count", 0);
        return .{ .Ok = .{ .value = value } };
    }

    pub fn inc(self: *Counter, args: abi.IncArgs) abi.ContractResult(abi.IncResult) {
        _ = self;
        _ = args;
        const value: u128 = sdk.storage.readU128OrDefault("count", 0) + 1;
        _ = sdk.storage.writeU128("count", value);
        return .{ .Ok = .{ .value = value } };
    }
};

export fn _start(calldata_ptr: [*]const u8, calldata_len: usize) sdk.ByteSlice {
    return sdk.dispatch.run(Counter, abi.dispatch, calldata_ptr, calldata_len);
}

pub const panic = sdk.panic;

4) Build

cd contracts/counter
zig build -Doptimize=ReleaseSmall

Output: zig-out/bin/counter

5) Bundle + deploy

node contract bundle \
  --elf contracts/counter/zig-out/bin/counter \
  --idl contracts/counter/counter.idl \
  --out ./counter.bundle

node contract deploy --bundle ./counter.bundle --key $ASHEN_PRIVATE_KEY --wait

6) Call it

ashen call 0xCONTRACT get '[]' --key $ASHEN_PRIVATE_KEY --wait
ashen call 0xCONTRACT inc '[]' --key $ASHEN_PRIVATE_KEY --wait

IDL + Zig Stubs

Generate Zig ABI stubs from the contract IDL:

cargo run -p idl-abi-gen -- \
  --idl contracts/my_contract/my_contract.idl \
  --out-dir contracts/my_contract/src \
  --zig-stubs

This produces:

• src/abi.zig (selectors, args/results, dispatch)
• src/my_contract.manifest.v1.json (deploy manifest metadata)

Regenerate these files whenever you change the IDL.

Build

cd contracts/my_contract
zig build -Doptimize=ReleaseSmall

Output: zig-out/bin/my_contract

Bundle + Deploy

Use the deployment workflow in the CLI guide:

• Build the Zig ELF (zig build -Doptimize=ReleaseSmall)
• Bundle with IDL (node contract bundle)
• Deploy (node contract deploy)

See: /guides/deploying-contracts/

Common Patterns

Storage helpers

const balance = sdk.storage.readU128("balance") orelse 0;
_ = sdk.storage.writeU128("balance", balance + 1);

Events

const events = sdk.events;
const Transfer = events.define("Transfer(address,address,uint256)");
Transfer.emit2(from, to, events.toTopicU128(amount), &[_]u8{});

Reentrancy guard

try sdk.guards.enterNonReentrant();
defer sdk.guards.exitNonReentrant();

Next Steps

• /contracts/ashen-sdk/ for the SDK API surface
• /contracts/idl-and-abi/ for interface definitions
• /contracts/examples/ for production-grade Zig contracts