Skip to main content

Glossary

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

Agent case​

An expiring, read-capped URL that serves the owner's memories as Markdown. Token prefix toda_case_. The default is 15 minutes and one read. 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. The API transmits them as decimal strings.

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​

A random 32-byte AES key used to encrypt one user's memory content. It is never stored unwrapped.

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 that appends a leaf in O(log n) by recomputing the rightmost path. Its root must equal computeRoot() for the same leaves.

Ingest​

Passes conversation text to a memory provider and stores the extracted memories.

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. Partial withdrawals consume the youngest lots first.

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​

An expiring, write-capped URL for adding memory. Token prefix toda_drop_. The default is 15 minutes and one write. 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​

The response from getProof(): an inclusion proof, batchRoot, txSignature, and onchainRoot. Independent verification reads the root from a separate RPC.

Recall​

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

Rolling root​

A root covering the full log rather than only the latest batch.

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. Withdrawal requires the owner to sign.

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) in users.wrapped_data_key.