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.
Pre-V1: the storage plane is field-proven; the trust plane now runs real mechanisms (a space-time storage bond, objective on-chain-bond fork-choice, unlinkable publishing, per-operator takedowns), hardened through independent adversarial review and covered at the unit, simulation, and real-daemon end-to-end tiers, but not yet externally re-verified, so treat it as unaudited. Build from source; see the roadmap for the 0.x → 0.9.0 (RC) → 1.0.0 (V1) track.
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>:<key> # care link — repair and audit rights, but CANNOT decrypt siltcare:v1:<root>:<layout-key>
Each of the two values is a 32-byte hash in compact base64url (43 characters); older 64-character hex links still parse.
By default the key is random, so publishing the same bytes twice yields different links and their existence can't be probed; in opt-in convergent mode the key is content-derived, so identical files dedup up to the handle you share (at the cost of a confirmation-of-file attack). 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 durable — finite but renewable: funded for a horizon, auto-skim-extended, and re-endowed before expiry (perpetual only if the balance grows) — 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.
The default untrusted posture makes fork-choice objective: a validator's weight is its on-chain proof-of-space-time bond — challenged storage that costs real, identity-bound disk — recomputed identically by every replica, so divergent replicas agree and forks heal. Quorums must intersect over the phase's real validator set: in the mature phase a block's supporters must carry more than ⅔ of the frozen epoch's committed bonded weight (weight, never head-count — free identities can't vote their way in), and during the launch window commits additionally require sign-off from the named anchor validators — explicit, time-boxed training wheels that shed on measured decentralization. Standing is not free reputation: the target pricing is the non-substitutable composition C_honest = disk × address-diversity × time × served-demand, so forging a fraction q of it costs roughly q of honest provision (C1, no discount), and a concentration metric over bond-distinct operators keeps a quiet cartel from capturing the quorum (C2, no quiet capture). Honest status: today the shipped subset gates standing on the disk (bond) axis alone — the served-demand and address-diversity axes are designed but not yet wired into the standing number. This is Silt's mission — held as a composition in tension, not a single primitive — with the full honest accounting in docs/design/m0.md.
This is deliberately not proof-of-work. It's cheap, and a block is final once an intersecting quorum stands behind it — from then on the chain prefers a visible stall to a silent rewrite (finalized history is never reorged). 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.
Curious how it got built, and why? The build log tells the story and the reasoning behind the design — the forks taken, the dead ends, the decisions — distinct from the changelog (what shipped) and the roadmap (what's next).