Documentation
Silt is one binary that plays every role — publisher, host, validator, desktop client — depending on how you invoke it. This is the working reference for the command line, the link format, the HTTP API, and consensus.
The core is pure logic — chunking, encryption, erasure coding, manifests, the DHT, the chain — and touches no network, disk, or clock directly. Everything effectful arrives through an interface (a port), and adapters implement those ports: an in-memory network for deterministic simulation, real TCP for production. The same core code runs in both. Retrieval always speaks to the same registry interface, so it never learns whether that registry is a local file or a replicated chain.
Local (single-store) commands:
| command | does |
|---|---|
| silt add <file> | Chunk, encrypt, erasure-code, store; prints the file's link and its care link. |
| silt get <link> -o <out> | Fetch, verify every hash, repair from parity, decrypt, reassemble. |
| silt info <link> | Stripe map — every shard, its stripe, and whether it's present. |
| silt ls | List registered roots. |
| silt genesis | Print the founding block, its link, and the manifesto root. |
Networked commands:
| command | does |
|---|---|
| silt daemon … | Run a long-lived node: TCP listener, disk store, optional validator + registry + web UI. |
| silt client … | Desktop app: consumes and serves in one process, keeps a link-book library, opens a browser UI. |
| silt swarm add <file> | Publish into a running swarm via an ephemeral client; prints the link. |
| silt swarm get <link> | Retrieve from a swarm. |
| silt sim run <scenario> | Deterministic in-process simulations: scatter, churn, economy, audit, capacity, consensus. |
A file's public name is its Merkle root — thirty-two bytes that reveal nothing. To open the file you also need its key. Together they are the link:
# full link — retrieve AND decrypt silt:v1:<root-hex>:<key-hex> # care link — repair and audit rights, but CANNOT decrypt siltcare:v1:<root-hex>:<layout-key-hex>
The key is content-derived, so identical files produce identical links — deduplication reaches all the way up to the handle you share. From the link key the software derives, one-way, a layout key (stripe structure — enough to repair and audit) and a content key (the decryption material). Hand a caretaker the care link and they can keep your file alive forever without ever reading a byte of it.
A validator can host the registry over pinned HTTPS. Reads serve from the local replica; a publish triggers a consensus round.
| endpoint | does |
|---|---|
| GET /lookup?root=… | Resolve a root to its registry entry, or 404. |
| GET /all | Every registered entry. |
| POST /publish | Propose an entry; commits only with quorum. 402 if the publisher can't afford it. |
The registry reference clients use is <host-ID>@https://host:port — self-authenticating: the TLS handshake must present the key that hashes to that ID.
The web UI (-ui) adds read-only JSON at /api/status, /api/roots, /api/registry, and /api/chain, plus /api/publish and /api/fetch. These power the dashboard and the network observatory; they expose only what any participant could already assemble.
The registry is an append-only chain. Each block hashes the previous one, so history can't be edited in the middle without forging everything after it. A block commits only when it satisfies:
reputation(proposer) ≥ MinProposerRep AND ≥ Quorum distinct attesters, each with reputation ≥ MinAttesterRep, none of them the proposer, having signed the block hash
An attestation is an Ed25519 signature over the block hash, which covers the block's height, its parent, and its entries — so a signature endorses exact content in an exact place in history. Every replica re-validates all of it; latecomers re-check the whole chain as they sync. Reputation is each validator's own view — audits it ran, serving it saw — so lying to one validator buys nothing with the others.
This is deliberately not proof-of-work. It's cheap, final immediately, and honest about its trust model: a quorum chain for a network with an honest validator majority. The founding genesis block is the one exception — it needs no quorum, because it is declared identically on every node rather than agreed, exactly as Bitcoin hardcodes its first block.
The repository carries a set of short, friendly notes on the mathematics — Merkle trees, convergent encryption, Reed-Solomon, Kademlia, proof-of-retrieval, network-size estimation, key hierarchies, and quorum chains — written for a smart reader who isn't a mathematician. See docs/math/ in the source.