Willow Curriculum
Phase 1 of a video curriculum on the Willow protocol as of Willow'25: the data model, Meadowcap capabilities, private sync, encryption, drops, and the chosen parameters. Idea map, one unit card and script per idea.

Willow Curriculum

Phase 1 output under the Video Curriculum Guide. Every unit is one video plus one post and carries exactly one idea.

What the series is. Willow is a family of peer-to-peer protocols by worm-blossom (Aljoscha Meyer and Sam Gwilym) for running independent digital spaces: a data model where data has a name rather than a hash and can be deleted; Meadowcap, a capability system; a sync protocol, Confidential Sync, that reveals nothing to peers who do not share your interests, and a simpler transfer protocol that does not try; end-to-end encryption that keeps the data's shape; and a drop format for sync without a connection. Willow'25 is the recommended set of parameters (Ed25519, WILLIAM3, 4096-byte limits, ChaCha20-Poly1305, a Noise XX handshake) released on 26 October 2025. The series teaches the model as it stands on 2026-10-21, for people who build local-first and peer-to-peer software.

Recorded source statements. Every claim in the scripts rests on one of these, quoted from willowprotocol.org (read 2026-10-21).

    Home page: "Peer-to-peer protocols which scale up, down, and sideways." "A set of protocols for running your own digital spaces. All spaces are completely independent from each other." "Synchronisable data storage with destructive editing."

    Why Willow: "A protocol which enables a plurality of small, private networks alongside big, public ones"; "It must be resilient in the times we're forced to scale down, whether that's due to a temporary loss of signal, natural disaster, or war"; "able to run on low-spec hardware and on low-bandwidth networks"; "to be private, so that it's possible to find people with common interests without broadcasting those interests to the world"; "to let others distribute data on your behalf without letting them know what that data is"; "Wrangling the complexity of distributed systems shouldn't mean we trade away basic features like deletion."

    Comparison page: versus IPFS and content-addressed storage, "Willow employs explicit naming of data"; versus Secure Scuttlebutt and Hypercore, Willow "can achieve efficient data synchronisation without the need to restrict updates to a linear sequence"; "Traceless data removal when the need arises"; "Willow started out as a reimagining of Earthstar."

    Data model: "A namespace is the join over all stores in existence of a given NamespaceId." "A subspace is the set of all Entries of a given SubspaceId in a given namespace." "A Path is a sequence of at most maxcomponentcount many bytestrings, each of at most maxcomponentlength bytes, and whose total number of bytes is at most maxpathlength." An Entry has namespaceid, subspaceid, path, timestamp ("The claimed creation time of the Entry"), payloadlength, payloaddigest. "Willow can store arbitrary bytestrings of at most 2⁶⁴−1 bytes. We call such a bytestring a Payload." Newer: e1 is newer than e2 if its timestamp is greater, or timestamps are equal and its payloaddigest is greater, or both are equal and its payloadlength is greater. Prefix pruning: no store contains two entries of the same subspace where "new.path is a prefix of old.path, and new is newer than old." "A store is a set of AuthorisedEntries such that all its Entries have the same namespaceid." "Stores form a join semi-lattice (also known as a state-based CRDT) under the join operation." "An AuthorisedEntry is a PossiblyAuthorisedEntry for which isauthorisedwrite returns true." Parameters: NamespaceId, SubspaceId, the three path limits, PayloadDigest (totally ordered), hashpayload, AuthorisationToken, isauthorisedwrite.

    Timestamps, really?: "tracking the happened-before relation accurately requires space proportional to the greatest number of concurrent events, a number we cannot bound in a peer-to-peer system." "If you do not allow anyone else to write to your subspace, it does not matter how devilishly clever they choose their timestamps — your data remains unaffected." Backdating hides entries; future-dating blocks newer legitimate entries "until real time catches up"; mitigations: reject entries too far ahead of local time, and capabilities with time windows. Meadowcap capabilities restrict claimed timestamps; refusing to issue new capabilities means old entries eventually lose to newer overwrites. Apps can aggregate subspaces "through CRDTs, operational transformations, or abstract nonsense."

    Meadowcap: "an unforgeable token that bestows read or write access for some data." Communal namespaces: "Subspace IDs are public keys of a digital signature scheme," ownership proven by signature. Owned namespaces: "The person who created the namespace is the owner of all its data," namespace ids are public keys, "peers reject all requests unless they involve a signature from the namespace keypair." A capability specifies access mode, namespace, area (subspace, path prefix, time range) and recipient. Delegation is "a chain of successive authorisations," each "a signature from the prior holder's keypair"; the granted area of the previous capability must include the new area. Writing requires a MeadowcapAuthorisationToken: the capability plus "a signature over the entry by the receiver of the capability." McCapability unifies CommunalCapability and OwnedCapability; iscommunal decides which applies. Status: page header "Final (as of 21.11.2025)"; changelog 26 Oct 2025 "Meadowcap is now Final!".

    Grouping entries: a range includes values "greater than or equal to its start value and strictly less than its end value (if it has one)." An area has a subspace (one or any), a path prefix and a time range, and "includes every Entry whose subspaceid, path, and timestamp are all included." An area of interest adds maxcount (the newest entries) and maxsize (total payload length). Areas rather than ranges because encrypted paths and subspace ids "do not preserve their meaning under encryption."

    Region-based set reconciliation: fingerprints cover LengthyAuthorisedEntries, so changing an entry's number of available payload bytes changes the fingerprint; fingerprintsingleton, fingerprintcombine (associative, commutative, with a neutral element), fingerprintfinalise; the loop: compare a region's fingerprints, if equal done, else split into sub-regions or send the entries; "drill down to the differences between their two sets in a logarithmic number of communication rounds, spending only little bandwidth on those regions of the original sets where they hold the same items."

    Private interest overlap detection: "peers cannot learn about the existence of any NamespaceId, SubspaceId, or Path which they did not know about already." The example: transmitting a capability for the path "gemmastinks" discloses an opinion. Each peer sends "hashes salted with its own salt" and "compares the hashes it receives against hashes that it computes locally with the other peer's salt"; "the peer who has the more specific PrivateInterest is the one to detect the overlap"; read capabilities are then exchanged for matches only.

    Confidential Sync: "peers only hand out data if the request authorises its access"; peers "discover common interests without disclosing any non-shared information to each other"; phases: overlap detection, read capability exchange, three-dimensional range-based set reconciliation, payload transmission (eager or on request); payload digests must come from "a Merkle-tree-based hash function" (Bab), peers exchange chunks and verify partial transmissions. Status: Proposal; "Design on this specification are paused, we are focussing on the Willow Transport Protocol first."

    Willow Transfer Protocol: "Metadata, such as capabilities themselves, or requests for specific groupings of Entries are transmitted naively, however; peers must be mindful of possibly leaking information this way." Message based, over a reliable ordered bidirectional channel; RequestEntries (areas, with region-based reconciliation), RequestPayloadSlice, SendEntry, SendPayloadSlice, CancelOwnRequest, UpdatePayloadLazyness; "Requests for Entries must be accompanied by read capabilities, peers should never send data to peers who are not authorised to access that data"; capabilities are checked against the authenticated receiver from the handshake. Status: Proposal (as of 16.10.2026); the changelog has no WTP entry.

    Handshake and transport encryption: "essentially the XX handshake of the noise protocol framework"; mutual authentication of static keypairs; two symmetric keys derived; names start with "Nose" instead of "Noise"; read capabilities are bound to the authenticated receiver's public key. The home page claims protection against man in the middle, eavesdropping and tampering; the PIO page gives the reasoning: peers who know each other's long-term keys exclude an active attacker in the handshake, and strangers are protected because an attacker who swaps keys "will later have to produce read capabilities for those public keys" and cannot; "An active eavesdropper can access everything at L2" (public keys and signatures inside transmitted capabilities).

    Encrypting entries: payloads are encrypted by users (nonce and padding first); path components are encrypted one at a time with hierarchical key derivation, so encrypting "blog/ideas/game.txt" yields ciphertexts whose first component always matches, whose second matches when the originals share "blog/ideas", and so on; timestamps stay plaintext ("Computing joins of stores necessitates comparing Timestamps numerically ... we begrudgingly accept that Willow deals in plaintext Timestamps only"); payload length and digest are exposed; NamespaceIds and SubspaceIds are not encrypted (hash their meaningful parts instead); relays can replicate and join without reading payloads or path semantics.

    Drop format: a static bytestring of entries and payload slices for "completely user-improvised channels" (USB keys, email, messaging); contains PossiblyAuthorisedEntries, authorisation tokens, "non-overlapping slices of payload chunks with strictly increasing start offsets"; entries may have no available payload (changelog, 26 Oct 2025); "We highly recommend encrypting drops for transport." Status: the page header says Proposal; the changelog of 26 Oct 2025 says promoted to Candidate.

    Willow'25: "Willow'25 is a set of recommended parameters that should work in a variety of settings." Ed25519 as the signature scheme; "We use WILLIAM3 as the go-to hash function, which is defined as part of the Bab specification"; NamespaceId and SubspaceId are Ed25519 public keys; maxcomponentlength, maxcomponentcount and maxpathlength are 4096; hashpayload is WILLIAM3; iscommunal maps a key to true "if and only if its least significant bit is 0"; encryption AEADCHACHA20POLY1305; dh is Ed25519 scalar multiplication; protocol name NoseXXED25519ChaChaPolyWILLIAM3; "We intend to not release another set of recommended parameters until one of the cryptographic primitives of Willow'25 is broken." Status: Proposal.

    Willow URIs: entry URIs willow://namespace.subspace/path/components, optionally with a digest or a payload subslice; area URIs add ?area with maxcount, maxsize, a start timestamp and an optional end; optional resolution hints (URLs suggesting where to obtain data); examples willow://family.alfie/blog/ideas, willow://family.alfie/blog?digest=b287afb0, willow://family.alfie/blog?area&count=12.

    Changelog, 26 Oct 2025: Confidential Sync made man-in-the-middle resistant, with handshake and transport encryption and streaming verification of payloads; LCMUX split out; drops may omit payloads; "We've added Willow'25"; Confidential Sync demoted to Proposal pending the Rust implementation; Drop Format promoted to Candidate; Meadowcap promoted to Final. Changelog 17 Jan 2024: site released.

    About: designed by Aljoscha Meyer and Sam Gwilym as worm-blossom; "The path / author / timestamp model at the heart of Willow was designed by our dear departed friend Cinnamon"; "Willow started as a minimalistic reimagining of Earthstar"; funded through the NGI Assure Fund (NLnet, European Commission).

Scope. The model and what the protocols promise, as of Willow'25. Not covered: encodings and relative encodings, LCMUX, three-dimensional storage structures, subspace capabilities, the Bab hash internals, nonce and padding schemes, the Rust and TypeScript implementations, Earthstar history, Keyhive or Hypermedia comparisons.

Status. Revision 2, 2026-10-21, after the independent text review. Thirty-three accuracy findings and nine structural findings were resolved: three wrong claims fixed, key pairs taught before first use, the protocol named wherever private overlap detection is described, two beats added, one cut, four metaphors now spoken. See "Review notes".

Idea map


    Willow: networks that scale down. Independent spaces, small beside big, built to keep working when scaled down, keeping deletion and privacy. needs: nothing

    Data has a name, not a hash. Addressing by name makes overwriting and deletion possible; the hash is inside the record, not the address. needs: 1

    Three coordinates: namespace, subspace, path. Building, room, shelf label; every piece of data has all three. needs: 2

    An entry is a name, a time, and a fingerprint. The record carries the name, a timestamp, payload digest and length; the payload is separate and can move later. needs: 3

    Newer wins. Same subspace and path: later timestamp, then greater digest, then longer payload; the loser is dropped. needs: 4

    A shorter path deletes everything under it. Within one subspace, a newer entry at a prefix prunes all longer paths beneath it; whole folders go in one write. needs: 5

    Stores join like sets, and forget. A store is a set under two rules; joins are order-independent; no history is kept. needs: 6

    Timestamps are claims. Author-claimed; a wrong clock harms only its own subspace; future-dating blocks your own writes; peers may refuse far-future entries. needs: 5

    Two kinds of namespace. Key pairs and signatures defined; communal (each subspace is a key) and owned (the namespace is a key), no list; Willow'25 decides by the key's lowest bit. needs: 3

    A capability is a ticket, not an account. Access mode, namespace, area, holder key; checked by any peer alone. needs: 9

    Delegation only narrows. A chain of signatures, each area inside the previous; no one asks the issuer. needs: 10

    A write is an entry plus a proof. Token = a genuine write capability covering the entry + holder's signature over it; three checks; stores hold only authorised entries. needs: 10

    Tickets expire; they are not revoked. No revocation; time ranges bound claimed timestamps; renew the trusted; newer entries win over a stale writer. needs: 12, 8

    An area: a room, a shelf prefix, a time range. The block of the three-dimensional space that tickets grant and sync asks for. needs: 10

    You sync an area, not a namespace. Areas of interest with count and size limits; peers sync the overlap. needs: 14

    Fingerprints find the differences. Compare one fingerprint per region; split on mismatch; send entries when small; cost follows the differences. needs: 15

    Finding shared interests without naming them. In Confidential Sync, salted hashes of interests compared both ways; only matches lead to capability exchange. needs: 15

    A peer sends only what you can prove you may read. Handshake binds a key; read tickets must be for that key; nothing outside their areas is sent; a key-swapping middle box has no ticket. needs: 17

    Payloads verify as they stream. A tree hash lets each chunk be checked on arrival; partial payloads are verified partials. needs: 4

    Encryption keeps the shape. Payloads sealed; paths sealed one part at a time so prefixes survive; timestamps plain; relays merge what they cannot read. needs: 6, 14

    A drop is sync on a USB stick. One file of entries, tokens and payload slices; payloads may be missing; joined like any store; encrypt before handing over. needs: 12

    Willow'25 is the chosen parameters. Ed25519, WILLIAM3, 4096 limits, ChaCha20-Poly1305, a Noise-style XX handshake; no new set until something breaks. needs: 9, 18

    A Willow URI names a shelf or an area. willow://namespace.subspace/path; digest for an exact payload; ?area with limits; hints for where to look. needs: 14

    What is final and what is moving. Data model and Meadowcap final; drops and Willow'25 proposals; Confidential Sync paused; the transfer protocol is the live proposal and is not private. needs: 1, 17

Parts: 1 to 8 the data model; 9 to 13 Meadowcap; 14 to 19 sync; 20 and 21 carrying data you cannot read; 22 to 24 parameters, names and status.

Parking list. Encodings and relative encodings; LCMUX channels and guarantees; three-dimensional index structures; subspace capabilities; Bab internals; nonces and padding for payload encryption; hashing of namespace and subspace ids under encryption; eager versus lazy payload transmission thresholds; the Rust and TypeScript implementations; sneakerweb; Earthstar history.

Shared visual language


    A namespace is a building with its id over the door. A subspace is a room; its key hangs by the room. A path is a shelf label with parts.

    An entry is an index card: the name as one block, timestamp, digest, length. A payload is a parcel beside the card. A store is a box of cards.

    A capability is a ticket with four fields: read or write, namespace, area, holder. A delegated ticket hangs below its parent in a chain.

    An area is a highlighted block in a grid: rooms across, shelf prefixes down, a time dial beside it.

    A peer is a laptop or phone; a relay is a server box in the middle. A fingerprint is a seal on a region.

    Sealed things are drawn hatched: a sealed parcel, a sealed path part.

    A drop is a file icon on a USB stick.

Breaks, each said once in the script: a shelf holds one book, and a new book replaces the old (unit 2); the ticket's holder is a key, not a person (unit 10).

Units

Unit 1: Willow: networks that scale down


    Idea. Willow is a set of protocols for independent digital spaces that keep working when scaled down and keep deletion and privacy.

    Why it matters. It sets the frame: what the protocol is for, and which trade-offs it refuses to make.

    Context assumed. Nothing.

    Metaphor. None; a framing unit.

    Misconception. Willow is a single app or network. Addressed at beat 1.

    Visual language. Networks big and small, laptops, a card with a delete mark, a sealed envelope, four blocks.

    Target length. 55 to 65 seconds.

    Check question. Name two things Willow keeps that peer-to-peer systems usually give up.

Script:

    Willow is a set of protocols for running your own digital spaces. Small private networks, next to big public ones. (Screen: one big network beside three small ones.)

    It is built to scale down. A lost signal. A disaster. Two laptops and a cable should still work. (Screen: the big network shrinks to two laptops and a cable.)

    It keeps the things peer to peer systems usually give up. Deletion, most of all. (Screen: a card with a delete mark.)

    Others can carry your data without reading it. And you can find people who share your interests without telling the world what they are. (Screen: a closed envelope passing through a server.)

    Four parts. A data model. A capability system called Meadowcap. Sync. And drops. This series takes them one idea at a time. (Screen: four blocks: data model, Meadowcap, sync, drops.)

Unit 2: Data has a name, not a hash


    Idea. Willow addresses data by name, so a name can get new contents or none; the hash is inside the record, not the address.

    Why it matters. It is the root of overwriting and deletion, and the main difference from content-addressed systems.

    Context assumed. Unit 1.

    Metaphor. A shelf label in a library. Break, spoken: a shelf holds one book, and a new book replaces the old; deletion is putting an empty book there, not taking one away.

    Misconception. Willow is content addressed like IPFS. Addressed at beat 2.

    Visual language. A file with a hash, a shelf label, a book.

    Target length. 50 to 60 seconds.

    Check question. Where does the hash of the contents live, and what is the address?

Script:

    Many peer to peer systems find data by its hash. Change one byte, and it is a different thing with a different address. (Screen: a file; its hash underneath.)

    Willow names data instead. Like a shelf label in a library. The label stays. The book on it can change. (Screen: a shelf label; a book on the shelf.)

    Put a new book on the shelf, and the old one is gone. Same name, new contents. (Screen: the book replaced; the label unchanged.)

    Put an empty book there, and the old one is gone. That is deletion. (Screen: an empty book put on the shelf; the old one gone.)

    The hash is still there, inside the record, to check the contents. But the address is the name. (Screen: shelf label on the left, hash on the right, crossed.)

Unit 3: Three coordinates: namespace, subspace, path


    Idea. A name is a namespace, a subspace, and a path; every entry has all three.

    Why it matters. Every later unit speaks in these three words.

    Context assumed. Unit 2.

    Metaphor. Building, room, shelf label.

    Misconception. A subspace is a folder. It is a writer's room. Addressed at beat 3.

    Visual language. Building, rooms with keys, shelf label.

    Target length. 45 to 55 seconds.

    Check question. Which of the three coordinates usually belongs to one author?

Script:

    A name in Willow has three parts. Picture a building. (Screen: a building.)

    The namespace is the building. Each one is completely independent of every other. (Screen: the building with its namespace id over the door.)

    A subspace is a room inside it. In most buildings, each person writes in their own room. (Screen: rooms inside, each belonging to one person.)

    A path is the shelf label inside the room. A sequence of parts, like folders. Blog. Ideas. Game. (Screen: a shelf label: blog, ideas, game.)

    Building, room, shelf. Namespace, subspace, path. Every piece of data has all three. (Screen: the three parts stacked: namespace, subspace, path.)

Unit 4: An entry is a name, a time, and a digest


    Idea. An entry is the name plus a claimed timestamp, a payload digest and length; the payload is separate and can move later.

    Why it matters. Separating the card from the parcel is what lets peers agree on what exists before moving bytes.

    Context assumed. Unit 3.

    Metaphor. An index card and a parcel.

    Misconception. An entry contains the data. Addressed at beat 4.

    Visual language. Index card with the name as one block, parcel.

    Target length. 45 to 55 seconds.

    Check question. Can two peers know they hold the same entry without exchanging its payload?

Script:

    The record Willow stores is called an entry. Think of an index card. The name is on it. Namespace, subspace, path. (Screen: an index card with the name as one block.)

    A timestamp. When the author says it was written. (Screen: a timestamp added to the card.)

    And a hash of the contents: the payload digest. Plus the payload length. (Screen: a digest and a length added.)

    The contents themselves, the payload, are a separate parcel. Large or small. (Screen: the card beside a separate parcel: the payload.)

    So the card can travel without the parcel. Peers can agree on which entries exist before any payload moves. (Screen: cards travel; the parcel stays behind.)

Unit 5: Newer wins


    Idea. For one subspace and path only one entry survives: later timestamp, then greater digest, then longer payload; the loser is dropped.

    Why it matters. This is the entire conflict rule, and it needs no coordination.

    Context assumed. Unit 4.

    Metaphor. The newest card replaces the old one on the shelf.

    Misconception. Conflicts need a merge step. Addressed at beat 5.

    Visual language. Two cards, lit fields, fading card.

    Target length. 40 to 50 seconds.

    Check question. Two entries have the same timestamp. What decides?

Script:

    Two entries, same room, same shelf. Only one can stay. (Screen: two cards with the same name.)

    The one with the later timestamp wins. (Screen: the later timestamp lit.)

    Same timestamp? The greater fingerprint wins. Same fingerprint? The longer payload wins. (Screen: equal timestamps; the greater digest lit.)

    The loser is dropped. Not kept in a history. Dropped. Willow calls this destructive editing. (Screen: the losing card fades.)

    The rule needs no server and no conversation. Any two machines with the same two cards pick the same one. (Screen: the same two cards on two machines; the same winner.)

Unit 6: A shorter path deletes everything under it


    Idea. Within one subspace, a newer entry at a prefix removes every older entry with a longer path beneath it, so a folder is deleted in one write, leaving only the new entry.

    Why it matters. It is how Willow delivers deletion without tombstones.

    Context assumed. Unit 5.

    Metaphor. A new card at a shelf label sweeps every card beneath it.

    Misconception. Deleting needs a tombstone per item. Addressed at beat 5.

    Visual language. Shelf label with cards under it, new card, fading cards.

    Target length. 45 to 55 seconds.

    Check question. How many writes does it take to delete a folder with a thousand files?

Script:

    In one room, a path is a sequence of parts. Blog. Blog, ideas. Blog, drafts. Blog, game. (Screen: a shelf label blog, with three cards under it: blog ideas, blog drafts, blog game.)

    Write a newer entry at just blog. (Screen: a new, newer card takes the blog label's slot.)

    Every older entry whose path starts with blog is gone. Ideas, drafts, game. All of them. (Screen: the three longer cards fade.)

    This is prefix pruning. A newer entry at a prefix overwrites everything longer beneath it. (Screen: the word prefix; the rule.)

    That is how you delete a whole folder in one write. No tombstones for each file. One card at blog. Nothing else. (Screen: an empty shelf; nothing left behind.)

Unit 7: Stores join like sets, and forget


    Idea. A store is a set of entries under the two rules; joining stores is order-independent; a store holds the present state and no history.

    Why it matters. It explains why sync never needs a server to decide, and why there is no log to replay.

    Context assumed. Unit 6.

    Metaphor. Pouring two boxes of cards together.

    Misconception. Sync replays a log of operations. Addressed at beat 5.

    Visual language. Two boxes, one box, the word CRDT.

    Target length. 45 to 55 seconds.

    Check question. Join store A with B, then with B again. What changes the second time?

Script:

    A store is a set of entries from one namespace. Two rules hold inside it: newer wins, and prefixes prune. (Screen: a box of cards labelled store.)

    To sync, two stores are joined. Pour both sets together. Apply the two rules. (Screen: two boxes poured into one.)

    Join them in either order, any number of times. You get the same store. (Screen: the join done in either order; the same box.)

    Mathematicians call that a join semilattice. Programmers call it a state based CRDT. (Screen: the word CRDT, small.)

    What it does not keep is history. A store is what is true now. Not how it got there. (Screen: a box with no history behind it.)

Unit 8: Timestamps are claims


    Idea. Timestamps are what the author claims and no one can verify; if only you write in your subspace no other clock can touch it; the dangerous case is future-dating your own writes.

    Why it matters. "Wall clocks in a distributed system" is the first objection every engineer raises.

    Context assumed. Unit 5.

    Metaphor. A date stamp held by the author.

    Misconception. Anyone with a fast clock can override your data. Addressed at beat 2.

    Visual language. Card with the author's stamp, wrong clock, far-future card, a refusing peer, a vector clock (named in the script).

    Target length. 55 to 65 seconds.

    Check question. Whose data can a wrong clock damage?

Script:

    The timestamp on an entry is what the author stamps on it. No one can verify it. (Screen: a card; the author's date stamp.)

    So what can a wrong clock do? If only you write in your room, no one else's clock can touch it. (Screen: a wrong clock; only the author's own room affected.)

    The real danger is your own clock running fast. A far future entry blocks your later writes under that path, until time catches up. (Screen: a card dated far in the future, blocking newer ones.)

    So peers may refuse entries too far ahead of their own time. And a write ticket, which comes later, can bound the timestamps a writer may claim. (Screen: a peer refusing a far future card.)

    Why not track causality with a vector clock instead? That needs a slot for every concurrent writer, with no bound in a peer to peer system. (Screen: a vector clock crossed out.)

Unit 9: Two kinds of namespace


    Idea. A key pair is a public key and a secret key that signs; a communal namespace gives each subspace to its key holder, an owned namespace gives everything to the namespace key, with no list anywhere; Willow'25 decides by the key's lowest bit.

    Why it matters. It is the first fork in designing a Willow app.

    Context assumed. Unit 3.

    Metaphor. Rooms with their own keys versus one key over the door.

    Misconception. Namespaces have an admin list. Addressed at beat 3.

    Visual language. Two buildings, keys, a bit. This unit defines key pair and signature for the series.

    Target length. 55 to 65 seconds.

    Check question. In a communal namespace, what proves a room is yours?

Script:

    Meadowcap is Willow's permission system. It knows two kinds of building. (Screen: two buildings: communal, owned.)

    In a communal namespace, every room belongs to whoever holds its key. A key pair is a public key anyone can see, and a secret key only you hold. Only the secret key can make a signature the public key checks. The subspace id is a public key. Your signature proves the room is yours. (Screen: communal building; each room's id is a public key.)

    In an owned namespace, the building itself has a key. Its holder owns every room, and peers reject anything without that signature. There is no list. (Screen: owned building; one key over the door.)

    Which kind is a given namespace? The id says so. In Willow twenty five, the last bit of the key decides. (Screen: a namespace id; its last bit.)

    Rooms with their own keys, for a club where everyone keeps their own notes. One key over the door, for a group where one party decides who writes. (Screen: rooms with their own keys beside one key over a door.)

Unit 10: A capability is a ticket, not an account


    Idea. A Meadowcap capability is an unforgeable ticket naming access mode, namespace, area and holder key, checkable by any peer alone.

    Why it matters. It replaces accounts, access lists and the server that would hold them.

    Context assumed. Unit 9.

    Metaphor. A ticket. Break, spoken: the holder is a key, not a person.

    Misconception. Permissions live on a server. Addressed at beat 5.

    Visual language. Ticket with four fields.

    Target length. 50 to 60 seconds.

    Check question. What four things does a capability say?

Script:

    Meadowcap has no accounts and no access lists. It has tickets. A capability is an unforgeable ticket. (Screen: a ticket.)

    The ticket says four things. Read or write. Which namespace. Which area. And who holds it. (Screen: the ticket's fields: read or write, namespace, area, holder.)

    The area is a room, a shelf prefix, and a time range. Everything inside that is allowed. Nothing outside. (Screen: the area field: room, shelf prefix, time range.)

    The holder is a public key. To use the ticket, you sign with the matching secret key. (Screen: the holder's public key on the ticket.)

    Any peer can check a ticket on its own. There is no server to ask. (Screen: a peer checking a ticket, no list to look up.)

Unit 11: Delegation only narrows


    Idea. A holder can sign a smaller ticket for another key; each step's area must fit inside the previous; the chain travels with the ticket.

    Why it matters. It is how access spreads without an administrator.

    Context assumed. Unit 10.

    Metaphor. Tearing a ticket smaller; spoken at beat 4.

    Misconception. Delegating needs the original issuer. Addressed at beat 5.

    Visual language. Ticket, smaller ticket, chain, crossed widening.

    Target length. 45 to 55 seconds.

    Check question. Can a delegated ticket cover a shelf the parent did not?

Script:

    You hold a ticket for a whole room. A friend needs one shelf. (Screen: a ticket for a whole room.)

    You sign a new ticket for them. Same namespace. A smaller area. Their key as holder. (Screen: a smaller ticket signed below the first.)

    Their ticket carries the whole chain. The original, and every signature after it. (Screen: the chain: original, then each delegation.)

    Each step must fit inside the step before. You can tear a ticket smaller. You can never grow one. (Screen: an attempt to widen the area, crossed.)

    Your friend can pass it on the same way. Smaller again. No one asks you. (Screen: the friend's friend gets a smaller ticket still.)

Unit 12: A write is an entry plus a proof


    Idea. An entry is accepted only with a token: a genuine write capability whose area covers it, and the holder's signature over the entry; three checks.

    Why it matters. It is what makes a store trustworthy without trusting the peer that sent it.

    Context assumed. Unit 10.

    Metaphor. A ticket stapled to the card.

    Misconception. Peers trust each other's writes. Addressed at beat 1.

    Visual language. Card, ticket, signature, checking peer.

    Target length. 45 to 55 seconds.

    Check question. What three checks does a peer make before storing an entry?

Script:

    An entry by itself is just a claim. Anyone could write a card with your room's name on it. (Screen: a card alone.)

    So every entry travels with a token stapled to it. A write ticket whose area covers the entry. (Screen: a write ticket stapled to the card.)

    And a signature over the entry, by the ticket's holder. (Screen: a signature over the card by the ticket holder.)

    A peer checks three things. Is the ticket genuine? Does it cover this entry? Did its holder sign it? (Screen: three check marks on the ticket.)

    A store holds only entries that pass. Willow calls them authorised entries. (Screen: a store holding only checked cards.)

Unit 13: Tickets expire; they are not revoked


    Idea. There is no revocation; a ticket's time range bounds the timestamps it may claim, so short tickets plus renewal plus newer-wins limit a stale writer.

    Why it matters. It is the question every capability system gets asked, and the answer is structural.

    Context assumed. Units 8 and 12.

    Metaphor. A ticket with dates on it.

    Misconception. No revocation means no control. Addressed at beat 4.

    Visual language. Ticket, time range, renewal, overwritten entries.

    Target length. 50 to 60 seconds.

    Check question. What does a ticket's time range bound: the wall clock or the claimed timestamp?

Script:

    There is no way to cancel a ticket you have issued. Nobody keeps a list to cross it off. (Screen: a ticket with no revoke button.)

    What a ticket has is a time range. It covers entries with timestamps inside that range, and no others. (Screen: the ticket's time range.)

    So issue short ones. Renew the people you still trust. (Screen: a short lived ticket; a new one issued.)

    Someone you stopped renewing can still write within their old range. But your newer entries win over anything they can claim. (Screen: an old ticket's entries overwritten by newer ones.)

    The range bounds claimed timestamps, not the wall clock. That is the whole trick. (Screen: the timestamp range on the ticket, lit.)

Unit 14: An area: a room, a shelf prefix, a time range


    Idea. An area is one subspace or any, a path prefix (always with everything beneath it), and a time range: a block of the three-dimensional space that tickets grant, sync asks for and queries ask for.

    Why it matters. Areas are the unit of permission, of sync and of query; everything downstream is phrased in them.

    Context assumed. Unit 10.

    Metaphor. A block in a grid of rooms and shelves with a time dial.

    Misconception. Permissions and sync work on namespaces. Addressed at beat 5.

    Visual language. Grid, highlighted column, highlighted rows, dial, block.

    Target length. 45 to 60 seconds.

    Check question. What are the three parts of an area?

Script:

    Entries live in three dimensions. Subspace, path, time. (Screen: a grid: rooms across, shelves down.)

    An area picks one room. Or any room. One room means one author. Any room means everyone. (Screen: one column highlighted, or all of them.)

    A shelf prefix. Everything under blog. Or only everything under blog, ideas. (Screen: rows under a shelf prefix highlighted.)

    And a time range. From here, to there, or open ended. (Screen: a time range on a dial.)

    Say: Betty's room, everything under blog, this year. Three choices. One block. (Screen: one column, three rows, part of the dial, lit together.)

    That block is an area. Tickets grant areas. Sync asks for areas. Queries ask for areas. (Screen: the area as one block in the grid.)

Unit 15: You sync an area, not a namespace


    Idea. Peers name areas of interest with count and size limits and sync only the overlap; partial sync is the normal case.

    Why it matters. It is why a phone can take part at all.

    Context assumed. Unit 14.

    Metaphor. A small lit block in a huge building.

    Misconception. Sync means replicating the whole namespace. Addressed at beat 1.

    Visual language. Building, lit block, limits, overlap, phone.

    Target length. 45 to 55 seconds.

    Check question. Under a count limit, which entries are kept?

Script:

    A namespace can be enormous. You rarely want all of it. (Screen: a huge building; one small block lit.)

    So you name an area of interest. An area, plus a limit: at most this many entries, at most this many bytes. (Screen: an area with a count and a size limit.)

    Under a limit, the newest entries win the places. (Screen: the newest entries kept under the limit.)

    Two peers each bring their areas of interest. They sync the overlap. Only the overlap. (Screen: two peers' areas; the overlap lit.)

    A phone can follow one shelf of one room. Partial sync is the normal case, not a special one. (Screen: a phone syncing one small block.)

Unit 16: Fingerprints find the differences


    Idea. Peers compare one fingerprint per region, split regions that differ, and send entries only when a region is small; the fingerprint also counts held payload bytes; bytes sent follow the differences, rounds follow the logarithm of the size.

    Why it matters. It is why syncing a large area you already have costs almost nothing.

    Context assumed. Unit 15.

    Metaphor. A seal over a box; spoken at beat 2.

    Misconception. Sync lists every entry. Addressed at beat 5.

    Visual language. Two peers, seals, split area, small region.

    Target length. 50 to 65 seconds.

    Check question. Two peers hold identical areas. How many entries are sent?

Script:

    Two peers share an area. Which entries does one have that the other lacks? (Screen: two peers; the same area on each.)

    Each side computes one fingerprint over all its entries in the area. Think of a seal over the whole box. Same seal, same contents. Done. (Screen: one fingerprint per side, compared.)

    Different? Split the area and compare again. (Screen: the area split in two; fingerprints again.)

    When a region is small enough, just send its entries. (Screen: a tiny region; the entries themselves sent.)

    The fingerprint also counts how much of each payload a peer holds. So a half downloaded parcel shows up as a difference too. (Screen: a half-filled parcel counted into the seal.)

    The bytes sent grow with the differences. The rounds grow only with the logarithm of the size. Willow calls this region based set reconciliation. (Screen: a large area; a few differences found.)

Unit 17: Finding shared interests without naming them


    Idea. In Confidential Sync, peers exchange salted hashes of their interests and compare them with the other's salt, so only shared interests are detected and nothing new is revealed.

    Why it matters. Naming an interest can itself be a leak; this is the privacy promise from unit 1 made concrete.

    Context assumed. Unit 15.

    Metaphor. Two people checking whether they know the same secret by comparing scrambled versions.

    Misconception. Peers send each other their read capabilities first. Addressed at beat 5.

    Visual language. Two peers, a secret label, scrambles, a match, tickets.

    Target length. 50 to 60 seconds.

    Check question. What does a peer learn about an interest it does not share?

Script:

    In Confidential Sync, before syncing, two peers must find what they both care about. But naming an interest can give something away. (Screen: two peers; one holds a secret shelf label.)

    Say one of your shelves is called gemma stinks. Asking the other peer about it tells them what you think of Gemma. (Screen: the label gemma stinks.)

    So neither side names anything. Each scrambles its interests with its own salt, a random string mixed in before hashing. And sends only the scrambles. (Screen: each side scrambles its interests with its own salt.)

    Each side rescrambles what it already knows with the other's salt. A match means a shared interest. No match reveals nothing. (Screen: the scrambles compared with the other's salt.)

    Only for matches do they exchange read tickets. Nothing new leaves either side. (Screen: only the matched area opened; tickets exchanged.)

Unit 18: A peer sends only what you can prove you may read


    Idea. A handshake binds a key to the session and read tickets must be for that key, so a peer sends nothing outside their areas; a middle box that swaps keys has no ticket for its own key and gets nothing.

    Why it matters. It is where capabilities meet the wire.

    Context assumed. Unit 17.

    Metaphor. A doorman who checks the ticket and the face; spoken at beat 2.

    Misconception. Encryption of the link is enough. Addressed at beat 2.

    Visual language. Handshake, read ticket, refused request, a session key pair, middle box. Post note: the link is encrypted only when the channel is not; an active eavesdropper still sees the public keys and signatures inside transmitted capabilities.

    Target length. 50 to 60 seconds.

    Check question. Why must a read ticket's holder match the handshake key?

Script:

    Every sync session starts with a handshake. Each side proves it holds its key, and the link is encrypted. (Screen: two peers; a handshake.)

    To receive entries, you show a read ticket. Its holder must be the key you just proved. Like a doorman who checks the ticket, and the face it was issued to. (Screen: a read ticket shown; its holder matches the handshake key.)

    A peer never sends data outside the areas your tickets cover. Not even to say it exists. (Screen: a request outside the ticket's area, refused.)

    A peer can even make a fresh key pair for one session. It delegates itself a ticket for that key, and throws both away after. (Screen: a fresh key pair for one session; a ticket delegated to it.)

    A box in the middle can swap keys in the handshake. But then it needs a ticket for its own key, and it has none. It gets no entries and no names. (Screen: a middle box swaps keys; it holds no ticket; cross.)

Unit 19: Payloads verify as they stream


    Idea. Willow's sync protocols require a tree hash (Bab), so each chunk is verified on arrival and a partial payload is a verified partial.

    Why it matters. It removes the attack of sending garbage until the end, and it makes relaying partial data safe.

    Context assumed. Unit 4.

    Metaphor. A parcel checked piece by piece.

    Misconception. You can only verify a payload once it is complete. Addressed at beat 2.

    Visual language. Parcel, chunks in a tree, checks.

    Target length. 50 to 60 seconds.

    Check question. At which chunk is garbage detected?

Script:

    A payload can be large. The entry holds its digest, so you can check it when it arrives. (Screen: a large parcel; its digest on the card.)

    With an ordinary hash, you check only at the end. A bad peer could send gigabytes of garbage first. (Screen: waiting for the whole parcel before checking; a cross.)

    Willow's sync protocols require a tree hash, called Bab. The payload is cut into chunks, and the digest covers the tree. (Screen: the parcel cut into chunks in a tree.)

    Each chunk is checked as it arrives, against the digest you already hold. Bad data is caught early, not at the end. (Screen: each chunk checked as it lands.)

    A half received payload is a verified half. You can pass it on, or stop, and lose nothing. (Screen: the first half of a parcel, verified.)

Unit 20: Encryption keeps the shape


    Idea. You seal payloads, paths are sealed one part at a time so prefixes survive, timestamps and ids stay plain, and relays can merge what they cannot read. Post note: capability tokens travel in the clear too.

    Why it matters. It is how a server can carry your data without learning what it is.

    Context assumed. Units 6 and 14.

    Metaphor. An envelope with a scrambled label whose slots are kept.

    Misconception. Encrypting data breaks sync. Addressed at beat 4.

    Visual language. Relay box, sealed parcel, sealed path parts, plain timestamp.

    Target length. 50 to 60 seconds.

    Check question. Why are timestamps left unencrypted?

Script:

    You can let a server carry your data without reading it. (Screen: a relay server holding sealed cards.)

    You encrypt the payload. The server sees a parcel it cannot open. (Screen: the payload sealed.)

    The path is encrypted one part at a time. Blog, ideas, game become three scrambled parts. (Screen: the path: blog, ideas, game, each part sealed separately.)

    Two paths that share a prefix still share it after scrambling. So prefix pruning and areas keep working on data nobody can read. (Screen: two paths sharing scrambled blog; the prefix still matches.)

    Timestamps stay plain, because newer wins has to compare them. The ids stay plain too. The server can relay and merge, and never learn what any of it says. (Screen: timestamp and ids left plain on the card.)

Unit 21: A drop is sync on a USB stick


    Idea. A drop is one file of entries, tokens and payload slices that any channel can carry; payloads may be missing; the receiver verifies and joins it like any store.

    Why it matters. It is the scale-down promise from unit 1: no connection needed.

    Context assumed. Unit 12.

    Metaphor. A USB stick.

    Misconception. Willow needs a live network. Addressed at beat 1.

    Visual language. USB stick, file with cards, missing parcel, locked drop.

    Target length. 45 to 55 seconds.

    Check question. What must the receiver check before joining a drop?

Script:

    Sync needs a live connection. A drop does not. (Screen: a USB stick; an email; a chat message.)

    A drop is one file. Entries, their write tokens, and slices of payloads. (Screen: a file holding cards, tickets, and parcel slices.)

    A payload can be missing or partial. The entry still arrives, and the digest says what to fetch later. (Screen: a card in the drop with no parcel.)

    The receiver checks every token and joins the drop into their store. The same two rules as always. (Screen: the drop joined into a store.)

    Any channel will do: a stick, a message, the post. Encrypt the drop first. (Screen: a locked drop.)

Unit 22: Willow'25 is the chosen parameters


    Idea. The data model leaves the hash and Meadowcap leaves the signatures as parameters; Willow'25 fixes them (Ed25519, WILLIAM3, 4096, ChaCha20-Poly1305, a Noise-style XX handshake the authors call Nose) so implementations interoperate; not a new protocol, and no new set until a primitive breaks.

    Why it matters. "Which Willow" is answered by this unit.

    Context assumed. Units 9 and 18.

    Metaphor. A parts list.

    Misconception. Willow'25 is a new version of the protocol. Addressed at beat 2.

    Visual language. Blank slots, filled slots, the numbers, a stamp.

    Target length. 50 to 60 seconds.

    Check question. Which hash function does Willow'25 use, and where is it defined?

Script:

    The data model does not say which hash to use. Meadowcap does not say which signatures. Those are parameters. Each app could choose its own. (Screen: the data model with blank slots.)

    Willow twenty five fills the slots. Not a new protocol. The same protocol with its blanks filled in. Ed25519 keys and signatures. WILLIAM3 hashes, from the Bab tree hash. (Screen: two slots filled: Ed25519, WILLIAM3.)

    Path limits: four thousand ninety six parts, four thousand ninety six bytes each, four thousand ninety six bytes in all. (Screen: one slot: 4096 three times.)

    ChaCha twenty Poly thirteen oh five for encryption. A Noise style XX handshake, with those same primitives. The authors call it Nose. (Screen: one slot: ChaCha20-Poly1305; the handshake name.)

    One set, so that implementations interoperate. The authors intend no new set until one of these primitives is broken. (Screen: a stamp: until something breaks.)

Unit 23: A Willow URI names a shelf or an area


    Idea. willow://namespace.subspace/path names an entry (the words stand in for keys); a digest pins a payload; ?area with limits names an area; a hint is only where to look first.

    Why it matters. Links are how the model reaches the rest of the web.

    Context assumed. Unit 14.

    Metaphor. An address versus directions; spoken at beat 5.

    Misconception. The URI says where the data is. Addressed at beat 5.

    Visual language. URI strings.

    Target length. 45 to 55 seconds.

    Check question. What does adding ?area to a URI change?

Script:

    A Willow URI starts with willow colon slash slash. Then the namespace, a dot, the subspace, and the path. Family and alfie stand in for keys. (Screen: willow://family.alfie/blog/ideas.)

    Add a digest, and it names one exact payload. (Screen: the same URI with ?digest=.)

    Add the word area, and it names everything under that shelf. (Screen: the same URI with ?area.)

    An area URI can carry a count, a size, and a time range. The same limits sync uses. (Screen: ?area&count=12.)

    It can also carry a hint: a place to look first. The name is the address. The hint is directions. (Screen: a hint URL appended; address versus directions.)

Unit 24: What is final and what is moving


    Idea. The data model and Meadowcap are final; the drop format and Willow'25 are proposals on their pages (the changelog calls drops a candidate); Confidential Sync, home of the private overlap detection, is paused; the Willow Transfer Protocol, dated October 2026, is the live proposal and sends requests and tickets in the clear.

    Why it matters. Builders need to know which parts they can rely on today.

    Context assumed. Units 1 and 17.

    Metaphor. A status board.

    Misconception. The whole protocol is finished. Addressed at beats 4 and 5.

    Visual language. Status rows, one stamped per beat, four blocks. Authorship (Aljoscha Meyer, Sam Gwilym, and Cinnamon for the path/author/timestamp model) is in the series introduction, not a unit.

    Target length. 50 to 60 seconds.

    Check question. Which two specifications are final?

Script:

    Which parts can you build on today? The site stamps every spec with a status. (Screen: a status board with four empty rows.)

    The data model and Meadowcap are final. Meadowcap became final in twenty twenty five. (Screen: data model and Meadowcap stamped final.)

    The drop format and Willow twenty five are still proposals. (Screen: drop format and Willow'25 stamped proposal.)

    Confidential sync, the private protocol of the earlier units, is paused. A simpler Willow transfer protocol is the live proposal, dated October twenty twenty six. It sends requests and tickets in the clear. (Screen: confidential sync paused; transfer protocol proposal.)

    So the model and the tickets are settled. How peers talk, and how privately, is still being decided. (Screen: the four blocks: two solid, two outlined.)

Review notes

Phase 1d text review, 2026-10-21, by an independent reviewer with only the guide, the curriculum and willowprotocol.org. Full report: Willow Curriculum Review. What changed:

    Three wrong claims. Deletion is a newer write, not a removal (unit 2). "Nobody checks the timestamp" became "no one can verify it", since peers may refuse far-future entries (unit 8). The handshake does not rule out a middle box; the tickets do, and the box still sees the keys and signatures inside them (unit 18).

    Series-wide. Key pairs and signatures are now defined in unit 9 before any unit uses them. "Fingerprint" now means only the region hash; the entry's field is "the payload digest". Every unit describing private overlap detection names Confidential Sync, and unit 24 says the live transfer protocol sends requests and tickets in the clear.

    Scope and precision. Prefix pruning is scoped to one subspace; "nothing left behind" became "one card at blog, nothing else"; the "sixteen million terabytes" figure was cut; a prefix area always includes everything beneath it; queries ask for areas; the write check is three checks; bytes versus rounds in reconciliation; the data model has no signature parameter; the drop format and the transfer protocol are described by their page status; the Meadowcap month was dropped; a hint is only where to look first; the URI words stand in for keys.

    Structure. Unit 14 and unit 16 each gained a beat; unit 18's reader-tickets beat became the session-key trick; unit 24's authorship beat was cut and the credit, including Cinnamon, moved to the series introduction. Four metaphors are now spoken. Screens were cut to four things in units 4, 6, 12, 22 and 24, and labels the narration never said were removed or spoken.

    Sources. Two misquotes corrected and the reasoning behind the man-in-the-middle claim recorded.

Kept against the reviewer's suggestion. Unit 1 keeps no metaphor; a framing unit is the one exception the reviewer allowed. Unit 5 stays at 42 seconds; the idea is small and the card's own target allows it.

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime

Collaborators