# Swarm API examples These programs construct, sign, and verify Chio objects through the public Rust APIs. Each executable focuses on one mechanism and checks its result. The `runtime-host` executable installs the admission hook on a real `ChioKernel`, registers a tool handler, and verifies the signed allow and denial receipts. ## Build Install Rust through rustup, plus a C compiler and the platform build prerequisites for Chio. The included rust-toolchain.toml selects Rust 1.94.1. Git and curl are needed for the source checkout and download; unzip extracts the project. ```sh curl -fLO https://www.chio.computer/examples/swarm-authority.zip unzip swarm-authority.zip cd swarm-authority cargo run --locked --bin authority ``` Cargo fetches the public revision pinned in Cargo.toml. No sibling checkout is needed. Optional features keep the small authority examples from building every transport and cryptography dependency. ## Run a mechanism ```sh cargo run --locked --bin task-graph -- 2 cargo run --locked --bin budget -- 100 cargo run --locked --bin witness cargo run --locked --bin continuation cargo run --locked --bin route -- mcp://analysis-provider cargo run --locked --bin revocation cargo run --locked --bin terminal cargo run --locked --features runtime --bin admission cargo run --locked --features runtime --bin runtime-host cargo run --locked --features federation --bin bilateral cargo run --locked --features federation --bin ladder cargo run --locked --features frost --bin frost cargo run --locked --features disclosure --bin disclosure cargo run --locked --features lineage --bin lineage cargo run --locked --features reputation --bin hygiene cargo run --locked --features pheromone --bin pheromone cargo run --locked --features relay --bin relay cargo run --locked --features workflow --bin three-vendor cargo run --locked --bin scarcity -- 3 4 ``` Expected-refusal checks inside successful programs use assertions and exit zero when the refusal occurs. Invalid command input exits nonzero: ```sh cargo run --locked --bin task-graph -- 1 cargo run --locked --bin budget -- 79 cargo run --locked --bin scarcity -- 3 0 ``` `authority` writes bundle.json and prints its public verification key and evaluation time. To verify your own saved bundle, pass those two values explicitly: ```sh cargo run --locked --bin authority -- verify bundle.json TRUSTED_KEY_HEX NOW_UNIX_MS ``` Choose trust from your own configuration and evaluation time from your clock. Do not adopt a submitted bundle's clock or embedded signer as a trust decision. The generated authority bundle expires after one minute. ## What each example establishes - `src/lib.rs` contains the complete graph, witness, route, continuation, join, revocation, budget and terminal constructors. It generates a fresh local key and clock per process. Signed join/terminal declarations do not prove tasks ran. - `budget` shows the host-owned transition from Reserved to Active, a recorded charge, and fan-in release. It is an in-memory ledger example, not a payment rail or production pool lifecycle service. - `admission` isolates reservation, pre-dispatch abort release, revalidation and replay in the admission library. `runtime-host` runs the installed hook through the actual kernel; it records one result in a local tool handler. The capability quota is ten so the repeated request reaches the continuation replay guard. - `bilateral` signs one strict DSSE invocation at two local signing boundaries. The example supplies lease and policy declarations. Remote policy execution and transport are application responsibilities. Direct DualSignedReceipt is a separate signature profile. - `frost` runs DKG and threshold signing using separate participant secret objects in one process. Secret custody, authenticated transport between machines, durable nonce burning, active-roster trust and live slot anchors must be provided by a deployed host. Aggregation does not execute the declared settlement. - `disclosure` generates a real BBS proof and checks the outstanding challenge. Its in-memory issuer registry is local; production context checks also need revocation, holder, audience and nonce-consumption state. - `lineage` constructs signed policy/provenance declarations with a two-node frontier and checks their bindings. Its declared crypto-context report is not a new execution of the BBS/context verifier. Run `disclosure` for proof generation. - `hygiene` scores two populated lineage corpora. Scoring does not issue or verify capabilities; it assumes the host authenticated its persisted records. - `relay` starts an origin/receiver pair over actual loopback HTTP. Separate peer keys and directories establish local trust. SQLite retains outbox/inbox records; the receiver validates and stores one passport-signed observation in memory. The receiver accepts only one origin frame and forbids forwarding. Its injected clock advances past retry backoff; machine time is unchanged. This local host does not implement production proof-package admission, crash-safe observation storage or peer-directory rotation. The ordinary CLI `chio pheromone relay serve` additionally requires transit-policy, proof-package, trust-bundle and context files. - `three-vendor` produces and verifies the public artifact scenario. It uses that scenario's fixed verification context; it does not contact three vendor services. All output files are written in the working directory. Run in a fresh directory when you need to retain a previous run. Private keys remain in process memory except during the explicit relay setup below. The public pages show source and captured output from these exact files. ## Operate the relay with the CLI In a fresh project working directory, create local keys, directory pins and one queued observation. Setup refuses an existing relay-state directory. Key files are created with owner-only permissions on Unix systems. ```sh cargo run --locked --features relay --bin relay -- setup cargo run --locked --features relay --bin relay-serve -- relay-state ``` Leave the receiver running. In a second terminal in the same working directory: ```sh curl --fail http://127.0.0.1:18080/v1/chio/pheromone/ready chio pheromone relay tick \ --store relay-state/sender.sqlite \ --peer-directory relay-state/sender-directory.json \ --signing-key relay-state/sender-key.json \ --profile local-dev \ --max-batches 1 \ --report relay-state/tick.json cat relay-state/tick.json ``` The report should have accepted=true, delivered=1, retried=0 and no failures. A second tick has no due work. Receiver reports are in relay-state/reports. Stop the receiver with Ctrl-C. Keep the private key files inside the local operator boundary. This local receiver implements the bounded admission contract described above; it is not the CLI's proof-package receiver. ## Mechanism evidence and application effects `budget` explicitly updates accounting fields to demonstrate the authority contract. It is a data-model exercise. `packet`-style envelopes and opaque digests are validation fixtures, not evidence that a document was published or a payment settled. `runtime-host` additionally enters a real registered handler and checks its invocation count and receipts; that counter is process-local. For a persistent shared allowance, contention, cancellation and restart, follow the complete worker fleet or report-service projects. For a retained release artifact, use the reviewed publication example. The Rust systems tour connects these applications and their distinct failure/recovery tests.