Build on the ledger.
Everything runs on your machine: a devnet whose validators sign with two post-quantum signature families, the sion command line, a JSON HTTP API, a Model Context Protocol server, and agents your programs reach over HTTP, OpenAI’s chat API and A2A. The reference documentation lives at siontology.org/docs.
Quick start
You need Rust 1.80 or later. One command starts an in-process devnet and drives real transactions through the whole protocol: lane certificates, consensus, Pulse execution, signed headers, data availability and proving. Each demo narrates what the ledger established.
The devnet is for building and learning. Its validators run in one process, its proofs are checked by replay, and its validator keys are derived from the chain name, so it secures nothing of value.
To run an agent of your own instead, sion setup makes a chain, two wallets, the agent and its memory on your computer: see Your agent.
git clone https://github.com/shayansal/Siontology
cd siontology
cargo build --release
alias sion=./target/release/sion
# Run every scripted demo against an in-process devnet
sion demo all --localThe demos
Fourteen scripted demos, each run against a node you started or, with --local, against an in-process devnet of its own. The light demo needs a devnet that has already proven a Pulse, so it runs against a node, or inside sion demo all --local. Their recorded output is in the book.
| Command | What it shows |
|---|---|
sion demo invoice --local | Trade finance on insured knowledge: a bonded invoice claim is priced with the Assurance Algebra, relied on within its backing, and the financier is compensated from slashed bonds when the claim proves false. |
sion demo agents --local | An AI agent with a budget the ledger enforces: a payment to an unlisted payee and an over-limit payment are refused; revoking the charter stops the agent and its sub-agent. |
sion demo swarm --local | An orchestrator and fifteen subagents, each with an identity of its own, made in three transactions: a payment over a subagent’s limit is refused, suspending the orchestrator stops a subagent two levels down, and an unspent budget is reclaimed. |
sion demo batch --local | Sixty-four keyless subagents each pay, all authorized by one signature over the batch’s Merkle root; a batch signed by anyone but their nearest keyed ancestor is not certified. |
sion demo tasks --local | Work paid only when its result passes a rule fixed when the task was posted: a result without enough backing is refused, a task pays once, and a reward hack found later slashes the environment’s vendor and repays the lab. |
sion demo robots --local | Two robots share a memory the ledger keeps append-only: complete answers with proofs, a rewrite refused, and an index that hides a scan convicted with a fraud proof. |
sion demo storage --local | A robot’s memory kept by a laptop and a phone it pays per proven round: the phone drops data, misses its rounds and forfeits its collateral; the laptop is paid. |
sion demo market --local | A sealed-bid GPU-hour market that clears at one price with an optimality certificate. |
sion demo receipts --local | Verifiable AI inference receipts: each consumer prices the same receipt under its own assumptions. |
sion demo x402 --local | An agent pays an HTTP API per request; a replayed payment and an over-limit payment are refused. |
sion demo streams --local | An agent pays an API 2,000 times from one payment stream: one hash per call at the server, a few settlements on the ledger, a call’s receipt audited against the ledger. |
sion demo censorship --local | Forced inclusion: a censored user gets through by posting straight to consensus. When more than a third of a committee censors too, the shard misses its deadline, its committee is replaced, and certified headers count the overdue intent. |
sion demo staking --local | A standby validator stakes and joins the active set at the next epoch boundary, and a light client follows the committee change from genesis. Rewards are claimed; the newcomer signs two headers for one round, is slashed and loses its seat. |
sion demo light | A light client pins the chain identity, verifies the latest Pulse end to end and catches a node that serves substituted validator keys. |
Run a devnet
# Terminal 1: 4 validators, 2 shards, API on port 8730
sion devnet
# Terminal 2
sion status
sion keys new dana # dual post-quantum keys
sion faucet dana 100
sion send dana alice 12.5
sion balance dana
sion verify --chain <identity from sion devnet>sion devnet prints the chain identity: a digest of the genesis specification, the validators with their stake and keys, and the shard layout. Pin it with --chain or SION_CHAIN, and every light-client check is made against it; without a pin, the node vouches for itself.
The client talks to the node at SION_NODE, by default http://127.0.0.1:8730. The demos also run against a live node. The staking demo needs a standby validator and epochs that end: with --local it starts such a devnet itself; for your own, run sion devnet --standby 1 --epoch-length 24.
With --idle-round-ms, a chain with nothing to order waits between rounds instead of running them back to back, as the chain sion setup makes does.
The command line
Every command, with its options, is in the reference.
| Command | What it does |
|---|---|
sion devnet, sion genesis, sion node, sion gateway | Runs a devnet in one process; or collects validators into a network’s genesis and runs each validator and gateway in a process of its own |
sion status, sion pulse, sion events | Chain status; a Pulse’s header, certificate and summary; recent events |
sion keys new, sion keys show | Wallets with ML-DSA-44 and SLH-DSA keys |
sion balance, sion faucet, sion send | Balances, the devnet faucet and transfers; send --forced posts straight to consensus |
sion forced, sion censor | Forced-inclusion obligations; adversary simulation on a devnet, censoring accounts at the gateway or at validators |
sion bond, sion claim issue, show, decide | Bonds, claims, their cost of corruption and the decision rule |
sion accept, sion challenge, sion rule | Rely on a claim and reserve its backing; challenge a bonded atom; rule as the adjudicator |
sion charter create, pay, revoke | Agent Charters |
sion agent register, spawn, show, suspend, resume, revoke, reclaim, narrow | Agent identities on the ledger, their subagents and their limits |
sion setup, sion update, sion doctor | Sets up a chain, wallets and an agent on this machine; installs a release whose signature checks; says what the machine has |
sion, sion -c, sion agent talk | Talks with the agent setup made, in a new conversation or the last; by voice with --voice |
sion agent profile, run, continue, sessions, trace, kill-switch | The agent runtime: profiles (model, autonomy level, tools, memory), runs and their approvals, sessions, and a switch that stops every agent on the machine |
sion agent serve, bridge, telegram, gateway, host, pairing | Channels: HTTP, OpenAI’s chat API and A2A; the messengers; a gateway for profiles served from other machines; pairing codes for strangers |
sion agent mcp, graph, schedule | MCP servers the agent may use, reviewed and pinned; graphs of agents; scheduled runs |
sion agent work, waiting, project | Work the agent takes on by itself from GitHub and chats, under mandates on the ledger; what waits for you; projects that run for weeks, their payments held to a budget, with check-ins |
sion agent improve, routes | Changes to the agent kept only when they are better beyond chance on a set of tasks and fail no held-out task; a model for each kind of task |
sion agent improve run, seal, improver, code | The agent improving itself from its own sessions: changes it writes, kept only when confirmed on tasks sealed on the ledger before they were written; the improver improving itself; changes to its own code built and scored in a sandbox, released, attested by others and installed by you |
sion agent rent, find | Renting an agent out by the token from an attested enclave; finding the best agent for a task by its offer and its record |
sion agent sell, buy, commerce | Selling and buying through ACP’s checkout under AP2 mandates, paid on the ledger or by a card (the card network simulated) |
sion agent meeting | Meeting notes by phone, on this machine or as a guest by the link, which can answer what it is asked by name |
sion skill | Skills: pack, audit, publish, install, evaluate, improve and vouch for them; post a bounty for a better version |
sion task | Task Charters: post work, attest, submit and settle a result, cancel |
sion memory | Memory logs: open, remember, commit, recall with proofs, consolidate, dream, archive and restore; vouch for and revoke a shared fact |
sion storage | Storage deals: post, accept, prove each round, settle, retrieve, close; serve runs a provider |
sion market create, order, clear, show | Markets that clear with a certificate |
sion tx, sion receipt, sion verify | A transaction’s effects; its receipt, verified as a light client would; a Pulse, verified as a light client |
sion mcp | Serves the Model Context Protocol on stdio |
sion x402 serve, sion x402 fetch | Sells or buys HTTP resources per request, by transaction or from a payment stream |
sion stream open, pay, check, settle, top-up, close, show | Payment streams by hand: pay with chain elements, check them, settle by walk or by checkpoint |
sion demo, sion bench | The scripted demos; measurements of signatures, hashing, data availability, clearing, the Assurance Algebra, execution, proving, payment streams and a live devnet |
The HTTP API
JSON over HTTP on the node, by default 127.0.0.1:8730. Amounts are in micro-units.
| Method | Path | What it returns or does |
|---|---|---|
| GET | /v1/status | Chain status |
| GET | /v1/validators | The chain identity, the validator set and the current committees |
| GET | /v1/epochs/{e} | The proof linking epoch e − 1 to epoch e, so a light client can follow the committee |
| GET | /v1/genesis | The genesis specification and its digest |
| GET | /v1/accounts/{id} | Coins, balances, allotments and a provider’s custody records |
| GET | /v1/objects/{id} | An object with its state proof |
| GET | /v1/agents/{id} | An agent identity or a charter: its standing, lineage and limits, each with a state proof |
| GET | /v1/claims/{id} | A claim, its status, cost of corruption and inclusion proof |
| POST | /v1/claims/{id}/decide | The decision rule for {value, policy?} |
| POST | /v1/transactions | Submits {tx}: a signed transaction, hex of its canonical encoding |
| POST | /v1/batches | Submits a batch of transactions under one authorization |
| GET | /v1/transactions/{digest} | Status, effects and receipt proof |
| POST | /v1/faucet | The devnet faucet: {account, amount, asset?} |
| GET | /v1/pulses/latest, /v1/pulses/{n} | A Pulse’s header, certificate and summary |
| GET | /v1/pulses/{n}/data | The data-availability header |
| GET | /v1/pulses/{n}/data/{row}/{column} | One data share with its proof |
| GET | /v1/pulses/{n}/world | The World Proof |
| GET | /v1/events?from=&limit= | Events |
| GET | /v1/deals | Storage deals and their state; with ?open=1, those open for a provider to accept |
| POST | /v1/forced | Posts a forced intent {tx}, bypassing the gateway |
| GET | /v1/forced | Forced-inclusion obligations: pending, overdue, resolved |
| POST | /v1/devnet/censor | Adversary simulation, devnet only |
curl http://127.0.0.1:8730/v1/status
curl http://127.0.0.1:8730/v1/pulses/latest
curl http://127.0.0.1:8730/v1/claims/<claim id>
# the decision rule for 25,000 USD at risk (amounts in micro-units)
curl -X POST http://127.0.0.1:8730/v1/claims/<claim id>/decide \
-d '{"value": 25000000000}'Your agent, from a program
sion agent serve lets programs talk to the agents on a machine, each conversation a session, with the same commands and approvals as in a chat. Every request carries a token: the machine’s, or one made for a single profile, which only approves or declines if it was made to.
The same server answers OpenAI’s chat API, so an app made for it can talk to a profile as if it were a model, and, with --a2a, other agents in A2A, versions 0.3 and 1.0. Another agent’s message counts as content from outside, so what it asks for that reaches outside or spends waits for a person. An agent gateway takes messages for profiles served from other machines, which connect out to it and prove the agent’s key.
Tested with curl and test clients, against a local devnet and a scripted model; not with those apps or with other makers’ agents. Channels, in the book
# A token that reaches one profile; it is shown once
sion agent profile token add assistant
# Serve this machine’s profiles to programs
sion agent serve --listen 127.0.0.1:8794
curl http://127.0.0.1:8794/v1/chat/completions \
-H "Authorization: Bearer $TOKEN" \
-d '{"model": "assistant", "messages":
[{"role": "user", "content": "How much budget is left?"}]}'| Method | Path | What it returns or does |
|---|---|---|
| POST | /v1/profiles/{name}/messages | A message in a conversation, {text, conversation?, stream?}: the answer, or Server-Sent Events while the agent works |
| GET | /v1/sessions/{id} | A session and where it stands |
| POST | /v1/chat/completions | OpenAI’s chat API, the profile as the model; each conversation goes on in its session |
| GET | /v1/models | The profiles the token reaches |
| GET | /.well-known/agent-card.json | The A2A agent card of the profile served with --a2a |
| POST | /v1/profiles/{name}/a2a | A2A’s JSON-RPC: messages, streamed messages, tasks and their webhooks |
Tools for AI agents
sion mcp serves the Model Context Protocol over stdio, so an agent built anywhere can pay, issue claims, price a claim before relying on it, pay within an Agent Charter, post and settle work, keep a memory log and verify the chain. Every transaction and receipt also comes back as a sentence. The charter’s limits are enforced by the ledger, whatever the agent was told.
{
"mcpServers": {
"siontology": {
"command": "sion",
"args": ["mcp"],
"env": { "SION_NODE": "http://127.0.0.1:8730" }
}
}
}| Tool | What it does |
|---|---|
sion_status, sion_balance, sion_events | Chain status, balances and recent events |
sion_pay | Pays from a wallet the server holds keys for; final once the lane certificate forms |
sion_issue_claim | Issues a claim with a trust formula, optionally resting on the issuer’s bond |
sion_assess_claim | Before relying on a claim: computes its cost of corruption under a policy and applies the decision rule |
sion_agent_pay | Pays from an Agent Charter allotment, within the charter’s payees and limits |
sion_submit_intent | Submits a transaction the agent built and signed itself |
sion_fetch_receipt, sion_verify_pulse | Fetches a receipt or a Pulse and verifies it as a light client, against a pinned chain identity |
sion_fetch_paid | Fetches an HTTP resource that charges through x402, paying at most a cap the agent sets |
sion_task_post, attest, submit, settle, show | Task Charters: work paid only when its result passes the rule fixed when it was posted |
sion_memory_open, remember, commit, recall | A memory log the agent alone appends to, its head on the ledger, recalled with proofs |
sion_storage_post, deals, close | Storage deals for the agent’s data, proven every round |
x402: pay per request
x402 lets an HTTP server ask for payment with status 402 Payment Required, and lets a client, typically an agent, pay and retry without accounts, API keys or checkout pages. The adapter speaks version 2 of the protocol with an exact payment scheme on Siontology. The server answers only after verifying the payment’s receipt as a light client would, and an agent paying under a charter cannot exceed its limits.
With --streams, the server also accepts the stream scheme: a client that opened a payment stream to it pays each request with the next element of its hash chain, which the server checks with one hash, and the server settles many requests in one transaction. See the guide.
x402: paying per request
From the x402 demo. The agent asks carol's API for a forecast and gets 402 Payment Required with a quote: 0.25 USD to carol, scheme exact, a fresh nonce. The agent signs a payment under its charter whose purpose names the quote, and retries with it. carol's facilitator submits the payment, waits for it to execute and verifies the receipt the way a light client would: committee certificate, certified order, inclusion proof. Only then does the API answer 200 OK. Replaying the same payment is refused, because each quote pays for one request.
sion x402 serve carol --price 0.25
# serves http://127.0.0.1:8402/v1/resource for 0.25 USD a request
sion x402 fetch http://127.0.0.1:8402/v1/resource --wallet dana --max 1sion x402 serve carol --price 0.001 --streams
sion stream open dana carol --unit 0.001 --deposit 5
# prints the stream's ID; each call below is paid with one hash
sion x402 fetch http://127.0.0.1:8402/v1/resource --stream <ID> --count 1000
sion bench --only streams # what a payment costs the API and the ledgerVerify as a light client
A light client pins one value, the chain identity, and checks everything else against it: the committee certificate of a Pulse, the certified order of its transactions, receipts and state proofs, random samples of its data and its World Proof. It follows committees from epoch to epoch through boundary proofs. Here is a real run of the check.
chain: 6345655c matches the pinned identity; 4 validators, keys derive their identifiers ✓
Pulse 14 header d42357fe (state root aafa7aec, knowledge root b3950ae7, 0 claims)
certificate: 300000 of 400000 stake signed (quorum 266667), each signature ML-DSA-44 + SLH-DSA-SHA2-128f ✓
forced inclusion: no overdue intents (0 pending within their deadline) ✓
receipts: 1 of 1 transactions proven against the receipts root, in the certified order ✓
state: an account object proven against the state root ✓
availability: 16 of 16 random shares of the 32×32 square verified; a withholding would go unnoticed with probability < 4.7e-3 ✓
world proof: 2 leaves re-verified by stack ["A", "B"]; the published data is what executed and encodes to the certified data root (113 KB; replay proofs simulate succinct ones) ✓
lane certificates: all 1 executed transactions locked their inputs with a quorum of their shard's committee, taken from the proven validator set ✓sion bench # signatures, hashing, data availability, clearing,
# assurance, execution, proving and a live devnet
sion bench --quick --only signatures,data