Rust SDK

The Rust SDK is the reference implementation. The chio-binding-helpers crate holds the pure invariants (canonical JSON, SHA-256, Ed25519, receipt and capability and manifest verification) that every other SDK mirrors byte for byte.

chio is the CLI, not a library crate

On the Rust side, chio is the name of the CLI binary produced by the chio-cli crate. There is no Rust library crate called chio. The invariants you depend on as a library live in chio-binding-helpers; kernel types live in chio-core.

High-level Rust client is planned

A high-level Rust client equivalent to @chio-protocol/sdk, chio-sdk (Python), or chio-go is not yet shipped. The Rust surface available today is the invariants layer plus kernel types. Treat the sections below on client, session, DPoP signing, and receipt-query clients as planned surfaces: use the TypeScript, Python, or Go SDK if you need those today.

Installation

bash

$ cargo add chio-binding-helpers

Or in Cargo.toml:

toml

[dependencies]
chio-binding-helpers = { path = "../../crates/chio-binding-helpers" }

The library name (used in use statements) is chio_binding_helpers.

Crate Layout

Crate	Purpose
`chio-binding-helpers`	Invariants: canonical JSON, SHA-256, Ed25519, receipt/capability/manifest parsing and verification. The stable contract every other SDK conforms to.
`chio-core`	Kernel types (`ChioReceipt`, `CapabilityToken`, `ChioScope`, …), delegation-chain validation, and the signing primitives the invariants layer wraps.
`chio-manifest`	Signed tool manifest types. Re-exported by `chio-binding-helpers` where needed.
`chio-cli`	Produces the `chio` binary. Not a library dependency target.

Invariants (chio-binding-helpers)

Every invariant the protocol depends on lives in this crate. It owns: RFC 8785 canonical JSON, SHA-256 hashing, Ed25519 sign and verify, receipt parsing and verification, capability parsing and verification (including delegation-chain walking via chio-core), and signed manifest parsing and verification. No transport, no auth, no orchestration: those layers live in language-native SDKs.

Receipt Verification

verify_receipt.rs

use chio_binding_helpers::{
    parse_receipt_json,
    verify_receipt,
    ReceiptVerification,
};

fn main() -> anyhow::Result<()> {
    let json = std::fs::read_to_string("receipt.json")?;
    let receipt = parse_receipt_json(&json)?;

    let result: ReceiptVerification = verify_receipt(&receipt)?;
    assert!(result.signature_valid);
    assert!(result.parameter_hash_valid);
    Ok(())
}

Capability Verification

verify_capability takes three arguments: the parsed token, the current Unix timestamp, and an optional maximum delegation depth. The returned CapabilityVerification carries signature_valid, delegation_chain_valid, time_valid, and a time_status enum.

rust

use std::time::{SystemTime, UNIX_EPOCH};

use chio_binding_helpers::{
    parse_capability_json,
    verify_capability,
    CapabilityTimeStatus,
};

let cap = parse_capability_json(&json)?;

let now: u64 = SystemTime::now()
    .duration_since(UNIX_EPOCH)?
    .as_secs();
let max_delegation_depth: Option<u32> = Some(8);

let status = verify_capability(&cap, now, max_delegation_depth)?;
assert!(status.signature_valid);
assert!(status.delegation_chain_valid);
match status.time_status {
    CapabilityTimeStatus::Valid => {}
    CapabilityTimeStatus::NotYetValid => return Err(anyhow::anyhow!("nbf")),
    CapabilityTimeStatus::Expired => return Err(anyhow::anyhow!("expired")),
}

Manifest Verification

rust

use chio_binding_helpers::{
    parse_signed_manifest_json,
    verify_signed_manifest,
};

let manifest = parse_signed_manifest_json(&json)?;
let result = verify_signed_manifest(&manifest)?;
assert!(result.signature_valid);

Delegation Chains

Delegation-chain validity is rolled into verify_capability: the returned CapabilityVerification exposes delegation_chain_valid. Under the hood this calls chio_core::validate_delegation_chain with the max_delegation_depth you passed in. If you need finer-grained control (for example, to inspect a single link), reach directly into chio-core.

Merkle proof helpers are planned

chio-binding-helpers does not currently expose a Merkle inclusion-proof function. Receipt-store inclusion proofs will land as merkle_proof_verify in a future release once the wire shape stabilises.

Ed25519 and Canonical JSON

rust

use chio_binding_helpers::{
    canonicalize_json_str,
    sha256_hex_bytes,
    sha256_hex_utf8,
    sign_json_str_ed25519,
    verify_json_str_signature_ed25519,
    sign_utf8_message_ed25519,
    verify_utf8_message_ed25519,
};

let canonical = canonicalize_json_str(r#"{"b":2,"a":1}"#)?;
assert_eq!(canonical, r#"{"a":1,"b":2}"#);

let digest = sha256_hex_utf8("hello world");

let sig = sign_json_str_ed25519(&canonical, &seed_hex)?;
let ok = verify_json_str_signature_ed25519(&canonical, &sig.signature, &public_key_hex)?;
assert!(ok);

High-Level Client (Planned)

Not yet shipped

A high-level Rust client with session, transport, authentication, DPoP signing, capability-chain minting, and a receipt-query client is planned but not yet released. The examples in this section sketch the intended shape, not a working API. Track the roadmap entry or reach for the TypeScript, Python, or Go SDK in the meantime.

Today, the shipping Rust surface is chio-binding-helpers for invariants and chio-core for kernel types (ChioReceipt, CapabilityToken, ChioScope, …). Constructing a remote session, signing a DPoP proof, minting a capability chain, or paginating a receipt query all require wiring higher-level Rust code yourself, or using a non-Rust SDK.

Error Model

chio_binding_helpers::Error wraps an ErrorCode enum with the stable codes listed in the Bindings API contract (invalid_public_key, capability_expired, delegation_chain_broken, and the rest).

rust

use chio_binding_helpers::{Error, ErrorCode, Result};

fn must_be_valid(json: &str, now: u64) -> Result<()> {
    let cap = chio_binding_helpers::parse_capability_json(json)?;
    let status = chio_binding_helpers::verify_capability(&cap, now, Some(8))?;
    if !status.signature_valid {
        return Err(Error::new(ErrorCode::SignatureVerificationFailed, "bad sig"));
    }
    Ok(())
}

Conformance

Rust is the reference. Every other SDK produces byte-identical output against the Rust test vectors stored in the conformance harness.

bash

$ cargo test -p chio-binding-helpers
$ cargo test -p chio-core
$ cargo test -p chio-conformance

PreviousGo SDK NextBindings API