do my books, make no mistakes
Menu
AccountMy booksAdd receiptsChange country
Get started
DOCS

How Alice proves your books

Every entry Alice books gets a fingerprint in one public tree that settles on Ethereum. Here is how that works, down to the last line of code.

This page is for engineers. It explains the part of Alice that lives on a blockchain: what goes there, how it is computed, and why it can be trusted. You need to know what a hash function and a Merkle tree are; everything else is explained along the way. Every hash in the example below is computed by the same code the site runs, and the code shown is the code that runs.

What problem it solves

Alice records double-entry bookkeeping entries in a set of books that the customer keeps in their own storage. The books are plain JSON files. That makes them easy to read and easy to take elsewhere, but it also means anyone with write access could quietly change an old entry and nobody would notice.

So every entry gets a fingerprint, and the fingerprint goes into a public, append-only record that nobody can edit: a Merkle tree kept by a smart contract on Base. Later, anyone you show your books to can check two things without trusting you or us:

The record reveals nothing about the entry, the company or the books. It holds one number per batch, and each batch mixes entries from many customers.

The idea in one picture

  1. Entrya JSON file in the customer’s storage
  2. 20 numbersthe entry written as field elements
  3. Entry hashPoseidon2 of those numbers, off chain
  4. Batch roota small Merkle tree of every entry booked in the same two seconds
  5. LeafPoseidon2(batch root, block time), computed by the contract
  6. Tree rootone Merkle tree for everyone, on Base
  7. Ethereumwhere Base posts its transaction data and settles

Only the leaf and the tree root are computed on chain, in one transaction per batch; Base later posts that transaction to Ethereum. The entry itself goes on chain only as part of a hash. Our servers handle it while booking it, and it is stored only in the customer’s storage.

The three building blocks

Poseidon2, a hash made for proofs

Ethereum’s own hash is Keccak-256, and most systems use SHA-256. Both work on bits. Poseidon2 works on numbers modulo a prime p (here the scalar field of the BN254 curve, a prime just under 2254), using only additions and multiplications. That makes it cheap to compute inside a zero-knowledge proof, where every bit operation is expensive and field arithmetic is cheap.

The permutation takes a state of four field elements and runs 64 rounds. Each round adds round constants, raises elements to the fifth power (the S-box), and mixes the state with a fixed matrix. The first four and last four rounds apply the S-box to all four elements (full rounds); the 56 rounds in between apply it to the first element only (partial rounds). The constants are Barretenberg’s, the same Noir uses.

To hash a list of numbers, a sponge feeds them in three at a time and puts the list’s length times 264 in the fourth element (the capacity), so lists of different lengths cannot be confused. The hash is the first element of the final state. In the tree, every node is the hash of its two children: node(l, r) = H(l, r).

Security: Poseidon2 on BN254 aims at about 128 bits. Its output is a 254-bit field element, so finding a collision takes about 2127 work. It is newer than SHA-256 and still being studied.

Noir: why the hash is shaped this way

Noir is a language for writing zero-knowledge circuits: programs whose execution can be proven without revealing their inputs. Because the entry hash and the tree use Poseidon2 and field elements throughout, a Noir circuit can recompute them cheaply. That makes it possible, in principle, to prove a statement such as “the books contain an entry like this, stamped before that date” while showing only the tree’s root.

Base, with Ethereum underneath

Base is an Ethereum layer 2 built on the OP Stack. It orders transactions and produces a block every two seconds, then posts its transaction data to Ethereum in batches and settles there. Anyone can re-derive Base’s state from what is on Ethereum, and a state root that does not follow from that data can be challenged with a fault proof. So once a batch has been posted to Ethereum and that Ethereum block is final, usually within about a quarter of an hour, rewriting it would mean rewriting Ethereum, or Base changing its own rules through its upgrade keys.

Two consequences matter here. Block time on Base follows from the block number (one block every two seconds since genesis), so the sequencer cannot backdate a leaf. And until the batch is final on Ethereum, the sequencer could in principle reorder or drop very recent blocks. In normal operation Base posts batches within minutes, well inside the 12 hours an entry stays pending, and Alice confirms a stamp on chain again before booking anything onto it.

The worked example

A small Swedish company buys an office chair for 2 500.00 SEK including 25% VAT, paid from the business account. It is the first entry in its books. The company, amounts and IDs are made up, but every hash is computed by the published code; only the transaction hash is a placeholder.

1. The entry file

This is the whole file Alice writes to the customer’s storage, in plain text:

{
 "bobalice": "ledger/3",
 "entry": {
  "format": "entry/4",
  "book": "7c1e4a9b2f0d63e58a14c7b90e2f6d3a1b8c5e7f40a9d2c6e1b3f8a5d7c0e9",
  "parent": null,
  "number": 1,
  "date": "2026-10-14",
  "currency": "SEK",
  "decimals": 2,
  "financial_year": "2026-12-31",
  "salt": "e3b07a4c19d2f58b6a0c3e7d91f24b8a5c6d0e3f7a2b9c4d18e5f6a0b7c3d2",
  "lines": [
   {
    "account": "5410",
    "debit": 200000,
    "credit": 0
   },
   {
    "account": "2641",
    "debit": 50000,
    "credit": 0
   },
   {
    "account": "1930",
    "debit": 0,
    "credit": 250000
   }
  ],
  "text": "Office chair, Kontorsbolaget invoice 1043",
  "reason": "Furniture below the inventory threshold is an expense (5410). 25% input VAT on 2641. Paid from the business account (1930).",
  "documents": [
   {
    "id": "invoice-1043",
    "sha256": "cdc026448c88e9d4e5a3a7c17db0db47ea59126f76ffa9c41425a2c924eb2dca"
   }
  ]
 },
 "hash": "0x12d3c7532c80d6282739e695f99d00c99101875f4e40a54b97205009c706d7d6",
 "parent_key": null,
 "booked_by": "3f9d2b7a-4c1e-4e8b-9a6d-0c5f8e2b1d47",
 "stamp": {
  "batch_root": "0x04ff97d75f19688b43d73866ac5a1f34fd38362dc284c05d65e470f3bbffa15d",
  "batch_index": 1,
  "batch_path": [
   "0x2cd0f29a426f1326357eb8dad59f2fb0aba2c2593346d38611c48219ad422de4",
   "0x2986a459a2945187ac1021d41730f4346851731b7262ed761d012e6befb66326",
   "0x0e34ac2c09f45a503d2908bcb12f1cbae5fa4065759c88d501c097506a8b2290",
   "0x21f9172d72fdcdafc312eee05cf5092980dda821da5b760a9fb8dbdf607c8a20",
   "0x2373ea368857ec7af97e7b470d705848e2bf93ed7bef142a490f2119bcf82d8e",
   "0x120157cfaaa49ce3da30f8b47879114977c24b266d58b0ac18b325d878aafddf",
   "0x01c28fe1059ae0237b72334700697bdf465e03df03986fe05200cadeda66bd76",
   "0x2d78ed82f93b61ba718b17c2dfe5b52375b4d37cbbed6f1fc98b47614b0cf21b",
   "0x067243231eddf4222f3911defbba7705aff06ed45960b27f6f91319196ef97e1",
   "0x1849b85f3c693693e732dfc4577217acc18295193bede09ce8b97ad910310972"
  ],
  "time": 1791970213,
  "leaf_index": 41,
  "path": [
   "0x1f2fb439af4f756267cfcaff0ecbbb77cbc4bc95b1d0b1909fc6ce95f9ac0a3d",
   "0x0b63a53787021a4a962a452c2921b3663aff1ffd8d5510540f8e659e782956f1",
   "0x0e34ac2c09f45a503d2908bcb12f1cbae5fa4065759c88d501c097506a8b2290",
   "0x259cf9b83e1b5455b1eaf630f6377873ded1d859a43102ea7ed7b510a4b5f983",
   "0x2373ea368857ec7af97e7b470d705848e2bf93ed7bef142a490f2119bcf82d8e",
   "0x2b949e8cd705ddc340b203a97d7390e126ba817c67b38bcd6768775b32a7adfb",
   "0x01c28fe1059ae0237b72334700697bdf465e03df03986fe05200cadeda66bd76",
   "0x2d78ed82f93b61ba718b17c2dfe5b52375b4d37cbbed6f1fc98b47614b0cf21b",
   "0x067243231eddf4222f3911defbba7705aff06ed45960b27f6f91319196ef97e1",
   "0x1849b85f3c693693e732dfc4577217acc18295193bede09ce8b97ad910310972",
   "0x2a775ea761d20435b31fa2c33ff07663e24542ffb9e7b293dfce3042eb104686",
   "0x0f320b0703439a8114f81593de99cd0b8f3b9bf854601abb5b2ea0e8a3dda4a7",
   "0x0d07f6e7a8a0e9199d6d92801fff867002ff5b4808962f9da2ba5ce1bdd26a73",
   "0x1c4954081e324939350febc2b918a293ebcdaead01be95ec02fcbe8d2c1635d1",
   "0x0197f2171ef99c2d053ee1fb5ff5ab288d56b9b41b4716c9214a4d97facc4c4a",
   "0x2b9cdd484c5ba1e4d6efcc3f18734b5ac4c4a0b9102e2aeb48521a661d3feee9",
   "0x14f44d672eb357739e42463497f9fdac46623af863eea4d947ca00a497dcdeb3",
   "0x071d7627ae3b2eabda8a810227bf04206370ac78dbf6c372380182dbd3711fe3",
   "0x2fdc08d9fe075ac58cb8c00f98697861a13b3ab6f9d41a4e768f75e477475bf5",
   "0x20165fe405652104dceaeeca92950aa5adc571b8cafe192878cba58ff1be49c5",
   "0x1c8c3ca0b3a3d75850fcd4dc7bf1e3445cd0cfff3ca510630fd90b47e8a24755",
   "0x1f0c1a8fb16b0d2ac9a146d7ae20d8d179695a92a79ed66fc45d9da4532459b3",
   "0x038146ec5a2573e1c30d2fb32c66c8440f426fbd108082df41c7bebd1d521c30",
   "0x17d3d12b17fe762de4b835b2180b012e808816a7f2ff69ecb9d65188235d8fd4",
   "0x0e1a6b7d63a6e5a9e54e8f391dd4e9d49cdfedcbc87f02cd34d4641d2eb30491",
   "0x09244eec34977ff795fc41036996ce974136377f521ac8eb9e04642d204783d2",
   "0x1646d6f544ec36df9dc41f778a7ef1690a53c730b501471b6acd202194a7e8e9",
   "0x064769603ba3f6c41f664d266ecb9a3a0f6567cd3e48b40f34d4894ee4c361b3",
   "0x1595bb3cd19f84619dc2e368175a88d8627a7439eda9397202cdb1167531fd3f",
   "0x2a529be462b81ca30265b558763b1498289c9d88277ab14f0838cb1fce4b472c",
   "0x0c08da612363088ad0bbc78abd233e8ace4c05a56fdabdd5e5e9b05e428bdaee",
   "0x14748d0241710ef47f54b931ac5a58082b1d56b0f0c30d55fb71a6e8c9a6be14"
  ],
  "root": "0x0e1626c1a4a9bc1d3b8409d79f77074df9a3bf69fbe05ab2afa17436009da35a",
  "tx": "0x4f6d2c9a8b7e1f3d5c0a2e4b6d8f1a3c5e7b9d0f2a4c6e8b1d3f5a7c9e0b2d4f",
  "block": 52590433
 }
}

The part under entry is what is hashed. hash is the result, and stamp says where that hash sits in the public tree. parent_key (the previous entry’s file name) and booked_by (who requested the booking) sit outside the hash, so nothing proves them.

Amounts are integers in the smallest unit: with decimals: 2, 200000 means 2 000.00 SEK. The lines balance: debits 200000 + 50000 equal the credit 250000. Accounts 5410, 2641 and 1930 are from the Swedish BAS chart: low-value equipment expensed directly (förbrukningsinventarier), input VAT, and the business bank account.

2. From JSON to numbers

Poseidon2 hashes field elements, so the entry is first written as a fixed sequence of numbers, each below p. Ten come first, then three per line. With three lines that makes 19.

#FieldFrom the entryAs a number
0tag
the format, so no two formats share a hash
"entry/4" as ASCII bytes0x656e7472792f34
1book
which book
the 31 random bytes of the book id0x7c1e4a9b2f0d63e58a14c7b90e2f6d3a1b8c5e7f40a9d2c6e1b3f8a5d7c0e9
2parent
chains the book
the previous entry’s hash, or 0 for the first0x0
3number
position in the book
10x1
4date
booking date
2026-10-14 → 202610140x1352896
5currency"SEK" as ASCII bytes0x53454b
6decimals
amounts are in öre (1/100)
20x2
7notes, high half
text, reason, documents
first 128 bits of SHA-256(notes)0x7eaae2fa5121302e921138d0d4d743d3
8notes, low halflast 128 bits of SHA-256(notes)0xf94b3c5fb0072dd8568ec7f6ba1f26a7
9salt
hides the entry
31 random bytes0xe3b07a4c19d2f58b6a0c3e7d91f24b8a5c6d0e3f7a2b9c4d18e5f6a0b7c3d2
10financial year
the last day of the year it is booked in
2026-12-31 → 202612310x135296f
11line 1 account54100x1522
12line 1 debit200000 (2 000.00 SEK)0x30d40
13line 1 credit0 (0.00 SEK)0x0
14line 2 account26410xa51
15line 2 debit50000 (500.00 SEK)0xc350
16line 2 credit0 (0.00 SEK)0x0
17line 3 account19300x78a
18line 3 debit0 (0.00 SEK)0x0
19line 3 credit250000 (2 500.00 SEK)0x3d090

Three details are worth noticing. The free text, the reason and the document list go in as one SHA-256 hash, split into two 128-bit halves because a 256-bit value does not fit in a 254-bit field. Before hashing, they are written as canonical JSON (keys sorted, no spaces):

{"documents":[{"id":"invoice-1043","sha256":"cdc026448c88e9d4e5a3a7c17db0db47ea59126f76ffa9c41425a2c924eb2dca"}],"reason":"Furniture below the inventory threshold is an expense (5410). 25% input VAT on 2641. Paid from the business account (1930).","text":"Office chair, Kontorsbolaget invoice 1043"}

which hashes (SHA-256) to 7eaae2fa5121302e921138d0d4d743d3f94b3c5fb0072dd8568ec7f6ba1f26a7. Each document is referenced only by the SHA-256 of the original file, so the receipt itself stays in storage. An account number made of plain digits (no leading zero, below 264) is that number; any other account name is SHA-256 of its text cut to 31 bytes. And the 31-byte random salt means the hash cannot be guessed by trying likely amounts, dates and accounts: there are 2248 salts to try for every guess.

3. The entry hash

The sponge starts with 20 · 264 in the capacity element and absorbs the 20 numbers three at a time: six permutations take the first 18, and a seventh runs after the last two are added. The first element of that final state is the entry hash:

0x12d3c7532c80d6282739e695f99d00c99101875f4e40a54b97205009c706d7d6

The next entry in this book will carry this value in its parent field. So the newest entry’s hash depends on every entry before it, and checking it against the files checks the whole chain.

4. The batch

Alice does not send a transaction per entry. Entries from all customers that arrive within about two seconds are collected into one batch: a Merkle tree 10 levels deep (room for 1024 hashes), with empty places filled by the hashes of empty subtrees. In the example, two other books booked at the same moment, and our entry landed at position 1 (counting from 0):

batch leaves:  [0x2cd0f29a42…, 0x12d3c7532c…, 0x12225192c9…, empty, …]
batch root:    0x04ff97d75f19688b43d73866ac5a1f34fd38362dc284c05d65e470f3bbffa15d

Our entry’s path to the batch root is 10 siblings: the entry to its left at level 0, at level 1 the hash of the third entry paired with an empty slot, and empty subtrees above. The other books’ hashes appear in it, but they are salted hashes and reveal nothing.

5. The leaf and the tree

The stamping wallet sends one transaction: add(batchRoot). The contract reads the block’s time, 1791970213 (2026-10-14T09:30:13Z), and makes the leaf

leaf = H(batchRoot, time) = 0x06788ede30e646bce7ee6c6adea84da45fcb14fb5755cf8ef857d52026dc91a0

The tree is append-only: leaves are added left to right, 32 levels, room for 232 − 1 leaves (about 4 billion). In the example 41 leaves were already there, so ours is leaf 41 (indices start at 0), binary 101001. Read from the lowest bit up, each bit says whether our node at that level is a left (0) or right (1) child:

LevelOur node isSo its sibling isSibling
0righta finished subtree to its left (from filled)0x1f2fb439af4f…
1leftempty (a zero subtree)0x0b63a5378702…
2leftempty (a zero subtree)0x0e34ac2c09f4…
3righta finished subtree to its left (from filled)0x259cf9b83e1b…
4leftempty (a zero subtree)0x2373ea368857…
5righta finished subtree to its left (from filled)0x2b949e8cd705…
6leftempty (a zero subtree)0x01c28fe1059a…
7leftempty (a zero subtree)0x2d78ed82f93b…

Above level 5 every sibling is an empty subtree. The new root becomes

0x0e1626c1a4a9bc1d3b8409d79f77074df9a3bf69fbe05ab2afa17436009da35a

and the contract emits Added(41, batchRoot, 1791970213, root, completed), where completed holds the 2 subtree roots this leaf finishes: 41 in binary ends in a single 1, so it completes itself (level 0) and the pair 40–41 (level 1).

6. The stamp

Alice writes the result into the file as stamp. It holds everything needed to climb from the entry hash to the tree root:

batch_index, batch_pathwhere the entry sits in its batch, and the 10 siblings up to batch_root
timethe block time the contract hashed into the leaf
leaf_index, pathwhere the leaf sits in the tree, and the 32 siblings up to root
tx, blockthe transaction that added it and its block, to look up the event (the transaction hash is a placeholder here)

7. Checking it

Anyone with the file can check it in two steps. Offline, with no chain at all: recompute the entry hash from the entry, climb batch_path to batch_root, hash it with time into the leaf, and climb path to root. Then one read of the chain: fetch the receipt of tx and check that it holds an Added event from the Tree contract with the same leaf index, batch root, time and root. If both checks pass, the entry existed exactly as written no later than time.

Anyone can make a stamp that holds together offline; only the event on chain makes it real. Note that the root in the stamp is the root just after this leaf was added. Later leaves change the root, but the contract’s events and one call to edge() give what is needed to bring an old path up to today’s root.

8. Checking it in ten years

The check above needs a Base node that still has the stamp’s transaction. Ten years from now that may be hard to find. So once Ethereum has accepted a Base state that includes the stamp, at least five days later, the next booking in the same books makes Alice write a second file next to the entry: the same name ending in .l1.json instead of .json.

That file ties the entry to Ethereum’s own state. About every 20 minutes, Base posts its state to Ethereum as a dispute game: a contract, made by Base’s dispute game factory, that claims the output root of one Base block. The claim can be challenged for several days; once it has been defended, the contract stays in Ethereum’s state for good. The anchor file holds everything between that root and the entry: the Base block’s hash, state root and message-passer storage root (which hash together into the output root), a Merkle-Patricia proof of the Tree contract and of its stored root at that block, and the entry’s path to that root. A reader then needs the two files and any Ethereum node, and checks five things (verify.mjs prints them as ten separate checks):

  1. Hashing the entry gives the hash in its file; that climbs the batch path to the batch root, and with the time it makes the leaf.

  2. The leaf climbs the anchor’s path to the Tree’s root at that block.

  3. That root is in the Tree’s storage (slot 2), and the Tree, with its known code hash, is in Base’s state at that block.

  4. That state, hashed as an OP Stack output root, gives the root the game claims for that block.

  5. On Ethereum, today: Base’s dispute game factory made the game, of the type the file says; the game claims that root for that block; it was defended; and, if Base’s registry (found through Base’s portal) still answers, the Security Council has not blacklisted it.

Only the last step reads a chain, and it reads Ethereum’s current state with ordinary calls: no archive and no Base node. If it all holds, the entry existed exactly as written no later than its stamp’s time. The checker is verify.mjs. It needs four more files (l1.js, entry.js, tree.js, poseidon.js) and a package.json for its one dependency, an audited keccak library. Save them in one folder and run:

npm install
node verify.mjs 20261014T093013Z-0000000041-0001-12d3c7532c80.json \
                20261014T093013Z-0000000041-0001-12d3c7532c80.l1.json

It prints each check with ✓, ✗, or ? for one it could not ask. What it still assumes after ten years: that Ethereum’s state can be read, that Poseidon2, SHA-256 and keccak have not been broken, and that the four values it trusts from outside the files (the Tree’s address and code hash, and the addresses of Base’s game factory and portal, written at the top of verify.mjs) are the ones on this page.

The contract, part by part

The whole contract is about a hundred lines. It is deployed at 0x669591a11987b08016250217b8e18e9176e05590 on Base, cannot be upgraded, and its source is Tree.sol.

State

contract Tree {
    uint256 public constant DEPTH = 32;

    address public owner;
    address public adder;

    uint32 public count;
    bytes32 public root;
    bytes32[32] internal filled;   // at each level, the left node waiting for its right neighbour
    bytes32[32] internal last;     // the newest leaf's path: its node at each level

    event Added(uint32 indexed leafIndex, bytes32 batchRoot, uint64 time, bytes32 root, bytes32[] completed);
    event AdderChanged(address adder);

    error NotAdder();
    error NotOwner();
    error NotInField();
    error Full();

The tree never stores its leaves. It keeps only its right edge: for each level, the left node still waiting for a right neighbour (filled), and the newest leaf’s node at each level (last). That is 64 storage slots, plus the root, the leaf count and two addresses, forever, however many leaves are added. adder is the only address that may add; owner can only replace the adder.

Starting empty

    constructor(address adder_, address owner_) {
        adder = adder_;
        owner = owner_;
        bytes memory z = Zeros.ALL;
        for (uint256 k = 0; k < DEPTH; k++) {
            filled[k] = bytes32(Zeros.at(z, k));
            last[k] = filled[k];
        }
        root = bytes32(Zeros.at(z, DEPTH));
    }

An empty tree is not all zeros: it is zeros hashed together level by level. Zeros.ALL holds those 33 values, Z0 = 0 and Zk+1 = H(Zk, Zk), precomputed so the contract does not spend gas on them. Z32 is the root of the empty tree.

Adding a leaf

    function add(bytes32 batchRoot) external returns (uint32 index, bytes32 newRoot) {
        if (msg.sender != adder) revert NotAdder();
        if (uint256(batchRoot) >= Poseidon2.P) revert NotInField();
        index = count;
        if (index == type(uint32).max) revert Full();

        uint64 time = uint64(block.timestamp);
        bytes memory z = Zeros.ALL;
        bytes memory rcp = Poseidon2.PARTIAL;

        // The parts this leaf completes: level 0 (the leaf) and one more per trailing 1 bit.
        uint256 ones = 0;
        while ((index >> ones) & 1 == 1) ones++;
        bytes32[] memory completed = new bytes32[](ones + 1);

        // Step 0 hashes the leaf, steps 1 to DEPTH climb a level each. One place calls the hash,
        // which keeps the contract under the size limit.
        uint256 left = uint256(batchRoot);
        uint256 right = time;
        uint256 cur;
        for (uint256 step = 0; ; step++) {
            cur = Poseidon2.hash2(left, right, rcp);
            if (step == DEPTH) break;
            uint256 k = step;
            last[k] = bytes32(cur);
            if (k <= ones) completed[k] = bytes32(cur);
            if ((index >> k) & 1 == 0) {
                filled[k] = bytes32(cur);
                (left, right) = (cur, Zeros.at(z, k));
            } else {
                (left, right) = (uint256(filled[k]), cur);
            }
        }

        newRoot = bytes32(cur);
        count = index + 1;
        root = newRoot;
        emit Added(index, batchRoot, time, newRoot, completed);
    }

Read it as climbing the tree once, from the new leaf to the root:

  1. Checks. Only the adder may call it, the batch root must be a field element (below p), and the tree must not be full.

  2. Step 0 makes the leaf by hashing (batchRoot, time). The time comes from the block, not from the caller.

  3. Each further step climbs one level. If bit k of the index is 0, the node is a left child: it is saved in filled[k] for its future right neighbour, and its sibling for now is the empty subtree Zk. If the bit is 1, the node is a right child: its left sibling is the finished subtree waiting in filled[k].

  4. Completed subtrees. A subtree of size 2k is finished by its last leaf, the one whose index ends in k one-bits. Those nodes are emitted in the event, so a reader can later bring an old path up to date from the events plus one call to edge().

  5. The result is the new root, stored and emitted. One add costs 33 Poseidon2 permutations (one for the leaf, one per level), about 1.3 million gas, around a cent on Base.

Reads and the owner

    function edge() external view returns (uint32 count_, bytes32 root_, bytes32[32] memory last_) {
        return (count, root, last);
    }

    function waiting() external view returns (uint32 count_, bytes32[32] memory filled_) {
        return (count, filled);
    }
    function setAdder(address adder_) external {
        if (msg.sender != owner) revert NotOwner();
        adder = adder_;
        emit AdderChanged(adder_);
    }

waiting() is what the stamping service reads to work out the new leaf’s path before it sends the transaction. Only one queue adds leaves, so nothing can land in between. edge() is what a reader needs, with the events, to bring an old path up to today’s root. The owner’s only power is to replace the adder: it cannot remove, change or reorder leaves.

Poseidon2 in Solidity

library Poseidon2 {
    uint256 internal constant P = 0x30644e72e131…;

    function permute(uint256 a, uint256 b, uint256 c, uint256 d, bytes memory rcp) internal pure returns (uint256, uint256, uint256, uint256) {
        assembly {
            let p := 0x30644e72e131…
            let t0, t1, t2, t3, t4, t5, x
            t0 := addmod(a, b, p) t1 := addmod(c, d, p)
            t2 := add(add(b, b), t1) t3 := add(add(d, d), t0)
            t4 := addmod(mul(4, t1), t3, p) t5 := addmod(mul(4, t0), t2, p)
            a := addmod(t3, t5, p) b := t5 c := addmod(t2, t4, p) d := t4
            x := addmod(a, 0x19b849f69450…, p) t0 := mulmod(x, x, p) t0 := mulmod(t0, t0, p) a := mulmod(t0, x, p)
            x := addmod(b, 0x265ddfe127dd…, p) t0 := mulmod(x, x, p) t0 := mulmod(t0, t0, p) b := mulmod(t0, x, p)
            x := addmod(c, 0x199750ec472f…, p) t0 := mulmod(x, x, p) t0 := mulmod(t0, t0, p) c := mulmod(t0, x, p)
            x := addmod(d, 0x157ff3fe65ac…, p) t0 := mulmod(x, x, p) t0 := mulmod(t0, t0, p) d := mulmod(t0, x, p)
            t0 := addmod(a, b, p) t1 := addmod(c, d, p)
            t2 := add(add(b, b), t1) t3 := add(add(d, d), t0)
            t4 := addmod(mul(4, t1), t3, p) t5 := addmod(mul(4, t0), t2, p)
            a := addmod(t3, t5, p) b := t5 c := addmod(t2, t4, p) d := t4
            // … three more full rounds like the one above …
            for { let ptr := add(rcp, 32) let end := add(ptr, 1792) } lt(ptr, end) { ptr := add(ptr, 32) } {
                x := addmod(a, mload(ptr), p) t0 := mulmod(x, x, p) t0 := mulmod(t0, t0, p) a := mulmod(t0, x, p)
                t1 := add(add(a, b), add(c, d))
                a := addmod(mulmod(a, 0x10dc6e9c006e…, p), t1, p) b := addmod(mulmod(b, 0x0c28145b6a44…, p), t1, p)
                c := addmod(mulmod(c, 0x00544b833879…, p), t1, p) d := addmod(mulmod(d, 0x222c01175718…, p), t1, p)
            }
            // … four more full rounds …
        }
        return (a, b, c, d);
    }

    /// @dev Noir's Poseidon2 hash of two field elements: one permutation of (a, b, 0, 2 << 64).
    function hash2(uint256 a, uint256 b, bytes memory rcp) internal pure returns (uint256 out) {
        (out,,,) = permute(a, b, 0, 2 << 64, rcp);
    }
}

The full file (Poseidon2.sol) is generated from the same constants as the JavaScript version, and its tests compare both with values printed by Noir. hash2 is the sponge for exactly two inputs: one permutation of (a, b, 0, 2·264). Everything is addmod and mulmod on 256-bit words; x5 is computed as x² · x² · x.

The empty subtrees

/// @notice The hash of an empty subtree at levels 0 to 32 (level 0 is an empty leaf, 0).
/// Generated by script/zeros.mjs; do not edit.
library Zeros {
    bytes internal constant ALL = hex"000000000000000000000000…";

    function at(bytes memory all, uint256 level) internal pure returns (uint256 z) {
        assembly { z := mload(add(add(all, 32), mul(level, 32))) }
    }
}

The code that runs off chain

Alice on the server, the Books page in the browser and any independent checker run the same JavaScript, unchanged. These are the parts that matter here; each file is public.

The sponge (poseidon.js)

export function hash(inputs) {
  const n = inputs.length;
  const xs = inputs.map((v) => { const b = BigInt(v); if (b < 0n || b >= P) throw new Error('poseidon2: input outside the field'); return b; });
  let s = [0n, 0n, 0n, BigInt(n) << 64n];
  const full = Math.floor(n / 3) * 3;
  for (let i = 0; i < full; i += 3) { s[0] += xs[i]; s[1] += xs[i + 1]; s[2] += xs[i + 2]; s = permute(s); }
  for (let i = full; i < n; i++) s[i - full] += xs[i];
  return permute(s)[0];
}

An entry as numbers (entry.js)

export async function accountField(a) {
  if (/^[1-9][0-9]{0,19}$/.test(a) && BigInt(a) < 2n ** 64n) return BigInt(a);
  return BigInt('0x' + (await sha256Hex(a)).slice(0, 62));
}

export async function entryFields(e) {
  const [hi, lo] = halves(await sha256Hex(canonical({ text: e.text, reason: e.reason, documents: e.documents })));
  const out = [
    FORMATS[e.format], bytes31(e.book), hashField(e.parent), BigInt(e.number),
    dateField(e.date), currencyField(e.currency), BigInt(e.decimals),
    hi, lo, bytes31(e.salt),
  ];
  if (e.format === 'entry/4' || e.format === 'entry/5') out.push(dateField(e.financial_year));
  if (e.format === 'entry/5') out.push(fromHex(e.bank));
  for (const l of e.lines) out.push(await accountField(l.account), BigInt(l.debit), BigInt(l.credit));
  return out;
}

The trees (tree.js)

export const ZEROS = [0n];
for (let i = 1; i <= TREE_DEPTH; i++) ZEROS.push(hash([ZEROS[i - 1], ZEROS[i - 1]]));

export const node = (left, right) => hash([left, right]);
export const leafOf = (batchRoot, time) => hash([batchRoot, BigInt(time)]);

export function climb(leaf, index, path) {
  let cur = leaf, i = index;
  for (const sib of path) {
    cur = i % 2 === 0 ? node(cur, sib) : node(sib, cur);
    i = Math.floor(i / 2);
  }
  return cur;
}

export function batchTree(leaves) {
  if (leaves.length < 1 || leaves.length > 2 ** BATCH_DEPTH) throw new Error('batch size');
  const levels = [leaves.slice()];
  for (let k = 0; k < BATCH_DEPTH; k++) {
    const cur = levels[k], up = [];
    for (let i = 0; i < cur.length; i += 2) up.push(node(cur[i], i + 1 < cur.length ? cur[i + 1] : ZEROS[k]));
    levels.push(up);
  }
  const path = (i) => {
    const out = [];
    for (let k = 0, j = i; k < BATCH_DEPTH; k++, j = Math.floor(j / 2)) {
      const s = j ^ 1;
      out.push(s < levels[k].length ? levels[k][s] : ZEROS[k]);
    }
    return out;
  };
  return { root: levels[BATCH_DEPTH][0], path };
}

Confirming a stamp on chain (chain.js)

export async function confirmStamp(cfg, hash, s) {
  const same = (a, b) => String(a).toLowerCase() === String(b).toLowerCase();
  try {
    if (toHex(climb(fromHex(hash), s.batch_index, s.batch_path.map(fromHex))) !== s.batch_root) return false;
    if (toHex(climb(leafOf(fromHex(s.batch_root), s.time), s.leaf_index, s.path.map(fromHex))) !== s.root) return false;
  } catch { return false; }
  if (!/^0x[0-9a-fA-F]{64}$/.test(String(s.tx))) return false;
  const r = await rpc(cfg, 'eth_getTransactionReceipt', [s.tx]);
  if (!r || r.status !== '0x1' || !Array.isArray(r.logs)) return false;
  for (const log of r.logs) {
    if (!same(log.address, cfg.contract) || !same(log.topics[0], ADDED) || Number(BigInt(log.topics[1])) !== s.leaf_index) continue;
    const w = words(log.data);                       // batchRoot, time, root, …
    return same(w[0], s.batch_root) && Number(BigInt(w[1])) === s.time && same(w[2], s.root);
  }
  return false;
}

What it guarantees, and what it does not

PropertyWhy it holds
An entry cannot be changed after it is stampedA different entry gives a different hash; matching the stamp would need a Poseidon2 collision.
Earlier entries cannot be changed eitherEach entry hashes its parent, so the newest hash covers the whole chain.
It existed no later than timeThe time is the block’s, set by Base, not by us; the block is settled on Ethereum.
Nothing about the books is publicThe chain holds only batch roots; entry hashes are salted with 248 random bits.
Nobody can remove or rewrite a leafThe contract has no function that does it, and cannot be upgraded.

The limits are just as plain. A stamp proves an entry existed, not that it is the only version: a company could stamp two different histories of the same books, and the chain cannot tell, because nothing on it is tied to a book. We could refuse or delay stamping, though we cannot change or backdate anything already stamped. And a reader should check the event through a chain node they trust.

Sources: verify.mjs, l1.js, Tree.sol, Poseidon2.sol, Zeros.sol, poseidon.js, entry.js, tree.js, chain.js. The contract on Basescan.

Ready when you are

Add mcp.bobalice.com to your assistant and you’re set.

Get started