quickstart-zig.md

Zig Quickstart

A comprehensive guide to using the Autonomi network with the Zig SDK.

Setup

# Prerequisites
# - Zig 0.13+: https://ziglang.org/download/
# - antd daemon running (ant dev start)

Add the dependency to your build.zig.zon:

.dependencies = .{
    .antd = .{
        .url = "https://github.com/WithAutonomi/ant-sdk/archive/refs/heads/main.tar.gz",
        .hash = "...",  // zig build will tell you the correct hash
    },
},

Then in your build.zig:

const antd = b.dependency("antd", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("antd", antd.module("antd"));

Or scaffold a new project:

ant dev init zig --name my-project

Connecting

const antd = @import("antd");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // REST transport (default)
    var client = try antd.Client.init(allocator, .{});
    defer client.deinit();

    // Custom endpoint
    var client2 = try antd.Client.init(allocator, .{
        .transport = .rest,
        .base_url = "http://localhost:8082",
    });
    defer client2.deinit();

    // gRPC transport
    var client3 = try antd.Client.init(allocator, .{
        .transport = .grpc,
        .target = "localhost:50051",
    });
    defer client3.deinit();
}

Memory ownership: All returned slices and structs containing allocated memory are owned by the caller. You must free them when done, or use defer as shown in the examples.

Health Check

const status = try client.health();
defer status.deinit(allocator);

std.debug.print("Healthy: {}\n", .{status.ok});
std.debug.print("Network: {s}\n", .{status.network}); // "local", "default", "alpha"

Public Data

// Store
const result = try client.dataPutPublic("Hello, Autonomi!");
defer result.deinit(allocator);
std.debug.print("Address: {s}\n", .{result.address});
std.debug.print("Cost: {d} atto tokens\n", .{result.cost});

// Retrieve
const data = try client.dataGetPublic(result.address);
defer allocator.free(data);
std.debug.print("{s}\n", .{data}); // "Hello, Autonomi!"

// Cost estimation — returns UploadCostEstimate with size, chunks, gas, payment mode
const est = try client.dataCost("some data");
defer est.deinit(allocator);
std.debug.print("Estimate: {d} bytes in {d} chunks, {s} atto, gas {s} wei, mode {s}\n",
    .{ est.file_size, est.chunk_count, est.cost, est.estimated_gas_cost_wei, est.payment_mode });

Private Data

// Store (self-encrypting)
const result = try client.dataPutPrivate("secret message");
defer result.deinit(allocator);
const data_map = result.address; // Keep this secret!

// Retrieve (decrypt)
const data = try client.dataGetPrivate(data_map);
defer allocator.free(data);
std.debug.print("{s}\n", .{data});

Files

// Upload a file
const result = try client.fileUploadPublic("/path/to/file.txt");
defer result.deinit(allocator);
std.debug.print("File address: {s}\n", .{result.address});

// Download a file
try client.fileDownloadPublic(result.address, "/path/to/output.txt");

// Upload a directory
const dir_result = try client.dirUploadPublic("/path/to/directory");
defer dir_result.deinit(allocator);

// Download a directory
try client.dirDownloadPublic(dir_result.address, "/path/to/output_dir");

// Cost estimation — returns UploadCostEstimate with size, chunks, gas, payment mode
const est = try client.fileCost("/path/to/file.txt", true);
defer est.deinit(allocator);

Error Handling

const result = client.dataGetPublic("nonexistent") catch |err| switch (err) {
    error.NotFound => {
        std.debug.print("Not found\n", .{});
        return;
    },
    error.PaymentRequired => {
        std.debug.print("Payment issue\n", .{});
        return;
    },
    error.NetworkUnreachable => {
        std.debug.print("Network unreachable\n", .{});
        return;
    },
    else => {
        std.debug.print("Error: {}\n", .{err});
        return err;
    },
};
defer allocator.free(result);

Error union variants:

Error	HTTP Code	When
error.BadRequest	400	Invalid parameters
error.PaymentRequired	402	Insufficient funds
error.NotFound	404	Resource not found
error.AlreadyExists	409	Duplicate creation
error.Fork	409	Version conflict
error.TooLarge	413	Payload too large
error.Internal	500	Server error
error.NetworkUnreachable	502	Network unreachable

Examples

cd antd-zig/examples

zig build run -- 1      # Connect
zig build run -- 2      # Public data
zig build run -- 3      # Chunks
zig build run -- 4      # Files
zig build run -- 6      # Private data
zig build run -- all    # Run all examples

Or use the dev CLI:

ant dev example data -l zig
ant dev example all -l zig