# How Zaryn works, step by step > A guided tour of Zaryn's design, from one idea (name data by its content) to the whole system: the pieces, a commit's journey, chunked large files, proofs of storage, provenance and the transparency log, pinning and replication, and what is and isn't built. Pictures first, every step explained. Source: https://zaryn.xyz/docs/en/get-started-architecture How Zaryn is built, for anyone curious and for architects or security reviewers deciding whether to trust it. No code to run: just follow one commit through the system. ## 1. One idea: name data by its content ```diagram type: graph title: Same bytes, same name; new bytes, new name alt: A file's bytes are hashed into its name; an identical file gets the same name and is stored once; an edited file gets a new name height: 36 --- node a | logo.png | 10 8 | file | | Some bytes node b | copy of logo.png | 10 28 | file | | The same bytes, elsewhere node h | 9f2cโ€ฆ | 50 8 | hash | accent | The hash of the bytes is the name: stored once node e | edited logo.png | 90 28 | file | warn | One byte changed node h2 | 41abโ€ฆ | 90 8 | hash | good | A new name for new bytes link a h | | path link b h | same name | path link e h2 | | new ``` Everything (a file, a folder, a commit) is named by a **hash** of its own bytes: a short fingerprint that changes completely if a single byte does. Three things follow for free: - **Identical data is stored once**, wherever it appears in history. - **Nothing can change quietly**: changed bytes have a different name, so the old name still means the old bytes. - **Anyone can check** they got the right thing: hash what you received and compare. ## 2. The pieces ```diagram type: graph title: Four pieces, one store of named objects alt: zev on your computer pushes and pulls with zev-api; zev-api triggers zev-ci on each push; the website shows the same objects; zev can publish snapshots to IPFS legend: path=Push and pull; path2=CI on each push height: 44 --- box Your computer | 2 2 26 40 | dim node cli | zev | 14 14 | laptop | accent | The command line, one native binary in Zig. Commits, branches and history work offline node ipfs | IPFS | 14 34 | storage | | Published snapshots, openable by any IPFS node node api | zev-api | 52 20 | server | | The server, in Zig: objects on disk, metadata in PostgreSQL, the JSON API, sign-in and access node web | Zaryn website | 88 8 | cloud | good | Reads the same objects by the same names node ci | zev-ci | 88 34 | ci | | Runs pipelines in locked-down containers on each push link cli api | push, pull | path link cli ipfs | | ghost link api web | | dim link api ci | | path2 ``` ## 3. What lives where ```diagram type: cards --- ๐Ÿ’ป | On your computer | `.zev/objects/`: every object, compressed, named by its SHA-256. Everything works offline | accent ๐Ÿ—„ | On the server | Objects on disk named by their BLAKE3; users, repositories, refs and access in PostgreSQL | ๐ŸŒ | On IPFS | Pinned snapshots and files: a CID anyone can resolve, not only Zaryn | good ๐Ÿ” | In the transparency log | An append-only, signed record of pins, receipts and certificates | ``` ## 4. A commit, made offline ```diagram type: graph title: A commit is a chain of names alt: Files are hashed into blobs, folders into trees that list them, and a commit names its tree and its parent, so the commit's name covers everything below it height: 46 --- node c2 | commit | 50 6 | commit | accent | Names its tree, its parent commit, the author and the message node c1 | parent | 88 6 | commit | dim | The commit before node t | tree / | 50 22 | folder | | Lists each file and folder by name and hash node s | src/ | 30 38 | folder | node r | README.md | 70 38 | file | node m | main.zig | 12 38 | file | link c2 c1 | parent | dim link c2 t | | path link t s | | path link t r | | path link s m | | path ``` `zev commit` hashes each changed file, then each folder (a list of names and hashes), then the commit, which names its folder and the commit before it. So a commit's name covers **every byte below it and all of history before it**. Change anything anywhere and every name above it changes. No network is involved. ## 5. Push: two names, written down ```diagram type: graph title: One object, two names, recorded at every push alt: The client names an object by SHA-256, the server stores it under BLAKE3, and the push manifest records both height: 30 --- node local | your computer | 12 14 | laptop | | SHA-256 names node man | manifest/main | 50 14 | log | accent | For every object of the push: its local and its server name node server | the server | 88 14 | storage | good | BLAKE3 names, sharded on disk link local man | local_hash | path link man server | server_hash | path2 ``` `zev push` sends only objects the server doesn't have yet, plus a **manifest** that records both names of each, so the server can always say which of its objects a push brought and how they correspond to yours. ## 6. Big files: only what changed ```diagram type: stats title: A 93-byte edit near the start of a 1.7 MB file --- 96.5% | of the bytes untouched | by chunk, byte for byte | 96 | good ~1% | of the chunks sent again | the rest already on both sides | 1 | accent 100% | with whole-file storage | what a one-line edit would cost without chunks | 100 | bad ``` Large files are cut into **chunks** where the bytes themselves say so (a rolling hash, the same family as restic and borg use), not every N bytes. An insert only changes the chunks around it, so push and pull move only those. [How chunking works](/docs/en/chunking). ## 7. Pull and clone: checked on arrival ```diagram type: flow title: Nothing is used before it's checked --- Ask | What you don't have yet, in batches, four at a time for big repositories | | โ‡ฃ ~ as each arrives Check | Hash it and compare with its name | accent | # ~ only then Use | Stored, and your files updated | good | โœ“ ``` Because every object is named by its hash, a corrupted or substituted object is caught the moment it arrives, wherever it came from: Zaryn, a mirror or a teammate on your [private network](/docs/en/private-networks). ## 8. What can't be changed quietly ```diagram type: cards --- ๐Ÿ“œ | History | A commit's name covers its tree and its parent: rewriting one commit changes every name after it | accent ๐Ÿ”— | Links to files | A CID opens exactly those bytes, on any IPFS node | good ๐Ÿ“ฆ | Published packages | Stored by hash; a version is never replaced | โœ | Signed commits | `zev sign` adds your identity's signature; `zev verify` checks it (signing is a step you choose) | ``` Content addressing makes change **detectable**. Signatures, receipts and the transparency log (next chapters) make **who** did something, and **when**, checkable too. ## 9. Proof that your data is really kept ```diagram type: sequence title: zev verify-storage lanes: zev | Zaryn | Transparency log alt: Zaryn re-reads its objects and signs a receipt; zev checks the push is in it, checks the signature, and checks the receipt is in the log --- note Zaryn : re-reads every object against its hash, signs a receipt | good zev -> Zaryn : the latest receipt note zev : my last push all there? the signature Zaryn's? zev -> Transparency log : is the receipt recorded? Transparency log --> zev : yes, and it can't be changed later ``` Math, not a promise: `zev verify-storage`, or the same code in your browser. [Verified storage](/docs/en/verified-storage). ## 10. From an artifact back to its commit ```diagram type: graph title: Provenance, hash by hash alt: A commit has an IPLD CID; an artifact such as a model file is pinned to its own CID; a provenance record ties the two together and is added to the transparency log legend: path=Tied by hash height: 40 --- node c | commit | 10 10 | commit | accent | Mirrored into an IPLD block with its own CID node a | model.safetensors | 10 32 | file | | A build output, pinned to its own CID node rec | provenance record | 50 21 | log | | This artifact came from this commit, of this repository and branch node log | transparency log | 88 21 | storage | good | Append-only: the record can't be quietly removed link c rec | | path link a rec | | path link rec log | added | path ``` Given a file, you can trace it to the exact commit that produced it, and the link itself is tied by hashes, not by a filename someone could change. [IPLD and provenance](/docs/en/ipld-provenance). ## 11. The transparency log ```diagram type: flow title: A log that can only grow --- Append | Pins, storage receipts, advisories, change certificates | | โž• ~ every entry hashed into Tree head | One root hash for the whole log, signed by Zaryn's key | accent | โœ ~ anyone can Rebuild | Fetch the entries, recompute the root, compare | good | โœ“ ``` The same kind of guarantee certificate transparency gives for TLS certificates: an entry once added can't be removed or edited without the root changing, which anyone watching would see. ## 12. Pinning and replication ```diagram type: graph title: One copy on Free, every peer on Premium alt: A free pin sits on one IPFS Cluster peer; a premium pin is replicated to every available peer, including ones that join later height: 44 --- node free | Free pin | 14 8 | file | | Replication factor 1 node prem | Premium pin | 14 32 | file | accent | Replication -1: every available peer node p1 | peer 1 | 64 8 | storage | good | node p2 | peer 2 | 64 22 | storage | good | node p3 | peer 3 | 64 36 | storage | good | A peer that joins later gets it too link free p1 | | path link prem p1 | | path2 link prem p2 | | path2 link prem p3 | | path2 ``` Files are added and pinned across an IPFS Cluster in one step, each pin with a signed attestation (which CID, how big, when). [Pinning and IPFS Cluster](/docs/en/pinning-and-cluster). ## 13. Copies that repair themselves ```diagram type: cards --- โง‰ | Two copies | Every object kept twice | accent ๐Ÿงน | A daily scrub | Each copy re-read against its hash; a damaged one repaired from the other | good ๐Ÿงฑ | Erasure coding | The resilient policy spreads big files over several servers, surviving the loss of some | ๐Ÿ”’ | Encryption when you need it | Encrypted repositories store only what your devices can read | ``` ## 14. Honest limits ```diagram type: cards title: What's built, and what isn't --- โœ… | Built and running | Content-addressed objects, chunked sync, manifests, IPLD CIDs for commits, provenance pins, the transparency log, storage receipts | good โœ | Signing is a choice | Commits are content-addressed always, signed when you run `zev sign` | warn ๐Ÿงญ | Not a peer-to-peer store | Zaryn's servers hold the history; IPFS is for published snapshots and pinned files, not the whole object store | ๐Ÿ“ถ | Chunks mean requests | A big chunked push is many small requests; chunk endpoints have their own, higher rate limits so they don't starve the API | ``` Every guide in this section says what it can't do, not just what it can. For the full picture, start with [System overview](/docs/en/system-overview).