Skip to main content

Glossary

Terms are defined in toda fundamentals and used with these meanings throughout.

Agent case​

A read capability: a one-time, expiring URL that serves the owner's memories as markdown to whoever fetches it. Token prefix toda_case_. Default 15-minute expiry, one read. Minting one revokes all others for that owner. See agent cases.

Anchor​

The Solana transaction that writes a commitment into a user's commitment account. A memory is anchored once a commitment covering its leaf is confirmed on-chain.

Anchor service​

The single process that seals batches and submits commit_root. Sole holder of the anchoring authority keypair. Runs one sweep every ANCHOR_INTERVAL_MS.

Authority​

The key named in a commitment account's authority field, permitted to call commit_root on the owner's behalf. It can write a root and stall anchoring. It cannot decrypt a memory and cannot regress the memory count.

Base units​

Token amounts as integers, before applying the mint's decimals. Always transmitted as decimal strings in toda's API - a u64 exceeds Number.MAX_SAFE_INTEGER.

Batch​

The unit of anchoring: the set of leaves pending when the seal policy fired, sealed under one commitment and one transaction. States: pending → submitted → confirmed, or failed.

Canonical preimage​

The deterministic byte string a memory is serialized to before hashing: "toda:leaf:v1" ‖ 0x00 ‖ utf8(canonicalJson), where canonicalJson has fixed field order and recursively sorted metadata keys. See leaf encoding.

Ciphertext​

The AES-256-GCM encryption of a memory's content under the owner's data key. Stored with a fresh 96-bit IV. The GCM authentication tag is carried inside it.

Commitment​

The Merkle root over a log's leaves 0..n-1. 32 bytes. toda's commitments are rolling - each covers the entire log, not a delta.

Commitment account​

The on-chain PDA holding a user's tip, at seeds ["user", owner_pubkey]. Fixed 129 bytes; does not grow with the log. Ownership is address-derived, not assigned.

Data key​

An independent, randomly generated 32-byte AES key, one per user, used to encrypt their memory bodies. Never stored unwrapped - see KEK and wrapped data key.

Direction bit​

One boolean per level of an inclusion proof. true means the sibling at that level is on the right, so the accumulator is hashed first: H(acc, sibling).

Domain separator​

A constant prefixed to a hash preimage so that structurally different inputs cannot collide. toda has two: DOMAIN_SEP_LEAF = "toda:leaf:v1" and DOMAIN_SEP_NODE = "toda:node:v1". The v1 is the version of the entire commitment specification.

Envelope encryption​

Encrypting a memory under a per-user data key, and that data key under a KEK derived from the master key. Yields a stored key blob that is inert without the master key.

Incremental Merkle tree​

A persisted tree, stored as node levels, that appends a leaf in O(log n) by recomputing only the rightmost path. Its root() is byte-identical to a full computeRoot() at every size - the invariant that keeps every on-chain root and every issued proof simultaneously valid.

Ingest​

The capture half of the memory loop. Hands a conversation slice to a memory provider, which distills durable facts, and stores each one. Returning zero memories is the common, correct case.

Inclusion proof​

The sibling path from a leaf to a root: sibling hashes bottom-up, plus a direction bit per level. A log of a million memories yields a 20-sibling proof.

IV​

Initialization vector. 96 bits, random, fresh per encryption. IV reuse under AES-GCM leaks the XOR of plaintexts and permits tag forgery.

KEK​

Key-encryption key. Derived per user as HKDF-SHA256(master, salt = userId, info = "toda:kek:v1"). Never stored. Binding it to userId means a wrapped blob moved between users fails to unwrap.

Leaf​

The 32-byte SHA-256 hash of a memory's canonical preimage. The only representation of a memory that a commitment ever sees.

Leaf index​

A memory's position in its owner's log, assigned at write time, never changed.

Log​

One user's ordered, append-only sequence of leaves, keyed by wallet public key. Exactly one log per wallet.

Lot​

One deposit into a stake vault, aging on its own maturity clock. Consumed youngest-first on withdrawal (LIFO). See staking.

LIFO​

Last-in, first-out. An unstake burns the youngest lots first, so aged stake keeps aging. The alternative would destroy your most valuable maturity on a partial withdrawal.

Master encryption key​

MASTER_ENCRYPTION_KEY. The root of the encryption hierarchy, held in the API's environment. Unwraps every user's data key. No rotation path exists.

Maturity window​

How long a stake lot must age before it counts. STAKE_MATURITY_MS, default 24 hours. Exists to prevent snipe-staking.

Memory​

An atomic, self-contained, immutable fact: a content string plus optional metadata. There is no update operation; correction means writing a new memory.

Memory count​

The u64 on a commitment account recording how many leaves the current root covers. Monotonic - enforced on-chain. The rule that makes deletion detectable.

Memory drop​

A write capability: a one-time, expiring URL an agent can POST a memory to, on the owner's behalf. Token prefix toda_drop_. Default 15-minute expiry, one write. Write-only - the holder cannot read anything. See memory drops.

Memory provider​

An LLM that extracts durable facts from a conversation. One method: extract({ conversation, existing }). ClaudeMemoryProvider ships in @toda/llm; bring your own key.

Metadata​

Free-form JSON attached to a memory. Stored in plaintext and hashed into the leaf. Visible to anyone with database access. Never put secrets here.

Nonce (commitment)​

A monotonic u64 on a commitment account, incremented per successful commit. Callers pass the value they expect; a mismatch aborts. Optimistic concurrency control for anchoring.

Nonce (SIWS)​

A single-use, DB-persisted 128-bit value bound to a public key and a message. Consumed atomically on verification, so a replayed signature finds no row.

Odd-node rule​

When a Merkle level has an odd node count, the lone rightmost node is promoted by pairing with itself: H(x, x). Not carried up unchanged, not paired with zero.

PDA​

Program-derived address. A Solana address derived deterministically from seeds and a program id, with no private key. toda's commitment accounts and stake authorities are PDAs, so ownership is computable rather than assigned.

Proof bundle​

What getProof() returns: an inclusion proof, the batchRoot it validates against, the txSignature that anchored that root, and the live onchainRoot. Everything but the proof itself is toda telling you something - verify the root yourself.

Recall​

Substring matching over the caller's decrypted memory bodies, performed in the API process after decryption. Encryption forecloses index-time search.

Rolling root​

toda's commitment discipline: each anchor commits to the whole log, not the newly added leaves. There is never a chain of per-batch roots to walk, and a lost anchor is never a data-loss event - the next one subsumes it.

Seal policy​

When a user's pending leaves become a batch: 64 or more pending leaves, or the oldest pending leaf older than 5 minutes. A pure function of the pending set and the clock.

SIWS​

Sign-In With Solana. An EIP-4361-style structured message signed by a wallet with ed25519. The message binds domain, URI, chain id, nonce, and expiry - all part of the signed bytes.

Stake authority​

The PDA at ["stake", owner_pubkey] whose associated token account is the owner's vault. Derived from a signing owner on withdrawal, which is the entire self-custody guarantee.

Tip​

The commitment currently in a user's commitment account: the latest root, its memory count, and the nonce the next commit must present.

Vault​

A user's on-chain stake account: the associated token account owned by their stake authority. Anyone may deposit into it; only the owner's signature can withdraw.

Wrapped data key​

A user's data key encrypted under their KEK, stored as iv(12) ‖ ciphertext(32) ‖ tag(16) = 60 bytes in users.wrapped_data_key. Inert without the master key. A blob shorter than that is a legacy row using the deprecated derived-key path.