Knowledge Base

Browse the concepts behind Truestamp. Follow the links between concepts, or search across everything.

Item Lifecycle

The states a Truestamp item moves through from created to committed, plus the terminal redacted and deletion states, what each means to a user, how an item advances to committed, and how ownership governs who can act at each stage.

Overview

An item is a single unit of data submitted to Truestamp for timestamping. Every item moves through a small, well-defined set of states. It begins as created, becomes processing once its hash is a leaf of a finalized block, and reaches committed when its commitment into that block, which holds its inclusion proof, exists. committed is the normal resting state: from there, once its block is committed to a public chain, the item can be proved. Beyond that a committed item can be redacted (its content removed while its proof survives) or scheduled for deletion, ending in one of two deletion states depending on why it is being removed. Throughout, ownership (not authorship) decides who is allowed to act on the item at each stage.

The three main states

An item advances through three states on the way to being verifiable. The names are exact and are the same everywhere the item’s status is reported.

  • created: the initial state, set the moment the item is submitted. Its hashes and its item code have been computed, and its record’s witness hashes already name its witnesses, so which public records the submitted-after edge of its submission window can rest on is fixed before the item goes anywhere. It has not yet been placed in a block. Nothing further is needed from the user; the item simply waits to be picked up.
  • processing: the item is in a block. That block has already been finalized with the item’s hash among the leaves of its Merkle tree, and the item is waiting for its commitment, which holds its inclusion proof, to be written. This is a brief, automatic stage. The user does not trigger it and does not need to act on it.
  • committed: the item’s commitment into its finalized block exists, holding the inclusion proof that walks the item’s hash to the block’s Merkle root. This is Item Commitment: on Truestamp’s own ledger, the item was submitted before that block was finalized. committed is the normal end state. A proof can be generated once the block also has a final commitment on a public chain.

The forward path is created -> processing -> committed. An item whose commitment could not be written can be returned to created and placed in a later block; this is an internal recovery step, not a state the user drives. Its hash stays a leaf of the earlier block, which never gives it a proof; the later block does.

How an item advances to committed

Advancing to committed is fully automatic. A user submits an item and then waits; no further user action is required.

  1. At submission the item’s record names, in its witness hashes, a hash for each record it is being submitted after: the block then at the head of Truestamp’s internal ledger, which is always present, plus the newest observation captured from each external entropy source that had one. A source with nothing captured is simply left out and never holds up a submission.
  2. Newly submitted items sit in created until the block-building process collects the current batch of unassigned items.
  3. The collected items’ hashes become the leaves of a new block’s Merkle tree. The block is finalized, and in the same step each of its items moves to processing.
  4. When the item’s commitment into that block, with its inclusion proof, has been written, the item moves to committed in the same transaction.

At committed the item has an inclusion proof against a finalized block. That places it on Truestamp’s own ledger, but it does not yet give a submission window a stranger can confirm. Separately, the block’s hash is batched into an epoch whose hash is written to Stellar or Bitcoin (Block Commitment), and once that write is final a proof of the item can be generated. A verifier then draws the submitted-before edge from its own read of that chain, and the submitted-after edge from the sources of the entropy witnesses the item’s record names. Block Commitment is about the block, not the individual item’s state, and neither edge says anything about when the underlying data was created. For the guarantee the two edges add up to, see the submission window.

Redacted items

A committed item can be redacted. Redaction removes the item’s content (its claims data) while keeping every hash intact, so the item’s inclusion proof remains valid. This supports privacy and “right to be forgotten” needs without breaking the cryptographic record: the proof still shows that something was submitted in that window, even though the original content is no longer stored.

  • Only a committed item can be redacted, moving it to the redacted state.
  • Redaction removes the item’s claims and its tags. Every hash, the item code and the item’s commitment stay exactly as they were, so the item’s place in its block still verifies.
  • Truestamp records who redacted the item and under which right: as its owner, as an admin or owner of the team that owns it, or for compliance, which is the right a Truestamp system administrator always redacts under. If the account of whoever redacted an item is deleted, the record of who it was is cleared and the right stays.
  • No proof can be generated for a redacted item until it is restored. The redaction steps on the item’s page have you download its proof first, and that file is then the only proof of the item there is.
  • A redacted item can be restored to committed only with its exact original claims, nonce included: their claims hash must equal the one the item kept. This makes restoring verifiable rather than a blind overwrite. Any formatting of the same claims restores, and no claims rule or plan limit is checked again, so a later change to either never blocks a restore. Restoring brings back the claims, not the tags. A compliance redaction can be undone only by a Truestamp system administrator; the owner’s and a team admin’s redactions can be undone by whoever holds that right over the item.
  • On the item’s page, a redacted item is restored by uploading the proof file downloaded before the redaction (a JSON file of at most 256 KB, pretty-printed or not), or by pasting the original claims as JSON. The page checks that the file is JSON, that it is a proof of an item, that its item id is this item’s, and that its claims hash matches; it lists each check passed, and a block, entropy or beacon proof, a proof of another item, or claims that do not match are refused with a message saying why. No signature or chain check is needed, since the claims hash alone decides.
  • Restoring is also on the APIs, with the claims as a JSON text of at most 65,536 octets: PATCH /api/json/items/:id/unredact on JSON:API, the unredactItem mutation on GraphQL, and items.item.restore on the MCP server. Each needs its surface’s write scope and the same right to restore as the page. Redacting stays on the item’s page alone, since its steps have you download the item’s last proof first.
  • Redaction does not delete the item. A redacted item still exists and can still be verified; it has simply had its human-readable content withheld. A public redacted item stays public, shown as “Redacted Item” with no claims and no tags.

Deletion states

Deletion is a separate lifecycle from redaction. Both committed and redacted items can be scheduled for deletion, which moves the item into one of two terminal states that record why it is being removed. In both cases the item is not erased instantly: it is marked for a later permanent sweep, and until that sweep runs the item can be recovered.

  • deleted_user: a user chose to delete the item. It is scheduled for permanent deletion after a grace period (currently 7 days), during which the user can cancel and restore the item.
  • deleted_expired: the item was scheduled for removal because it exceeded a free-plan retention window. It also carries a grace period (currently 7 days) and can be cancelled and restored. Moving back onto a paid plan before the grace period runs out restores the items still waiting in this state automatically; items a user deleted deliberately are never restored that way.

Cancelling a pending deleted_user or deleted_expired deletion returns the item to whatever state it held before (either committed or redacted) and clears the pending-deletion marker. A user who wants a scheduled deletion to happen sooner can instead expedite it, which gives up the rest of the grace period and hands the item to the next sweep. Once the scheduled time passes, a background sweep permanently removes the item’s row.

An item that has not reached committed never enters either deletion state. An item in created has no proof and is not waiting on any block, so there is nothing to preserve and no reason to keep the row around: it is destroyed outright, with no grace period. That is true both when a user destroys it and when it passes a free-plan retention window while still in created.

An item in processing cannot be destroyed that way. Its hash is already a leaf of a finalized block and its proof is moments away, so it waits until it reaches committed and is then deleted like any committed item, with the grace period. A free-plan retention window that passes while it is in processing is applied once it is committed.

One case is an exception to created meaning “in no block”: an item returned to created by the recovery step above. Its hash is still a leaf of the earlier block. Destroying it removes the item and leaves that leaf, which never had a proof against it.

Deleting the owning account is a separate path from these deletion states, and it does not treat every item the same way. An item the account personally owns is permanently removed immediately, with no deletion state and no grace period, so that removal is not recoverable. Team-owned items go the same way when the departing account created the team and that team leaves ownership with the person who submitted the work; if instead the team is one that keeps ownership of its items, account deletion is refused outright until those items or the team itself are dealt with. An item the account merely authored, and that somebody else owns, is not deleted this way: it survives under its owner, with the authorship record replaced by a generic placeholder so it no longer identifies the departed account. See the life of a Truestamp account for the full account-deletion process.

Ownership governs who can act at each stage

Every rights decision at every stage keys off ownership, never authorship. Authorship (who first submitted the item) is a permanent, audit-only record and is never consulted to decide who may act. Ownership is transferable and is what determines who can read, update, redact, or delete an item. This distinction is covered in depth in item ownership versus authorship.

In practice this means:

  • Reading an item depends on its visibility and the reader’s relationship to the owning team, not on who submitted it.
  • Redacting or restoring an item, scheduling, cancelling or expediting its deletion, and destroying it while it is still in created are all gated the same way, by who owns the item. On an item a user owns, only that user holds these rights. On an item the team owns, the team’s admins and owners hold them. A team admin or owner has none of these rights over an item a member owns personally, even though they can read it and change its settings. Each of these rights also needs write access to the item’s team, so a team viewer holds none of them, even over an item they own. The one exception is redacting and restoring: the right to do both extends to a Truestamp system administrator in any team, whether or not they belong to it. A system administrator reaches an item outside their own teams only if it is public, or through an internal call that reads the item as the system rather than as a user.
  • These controls are on the item’s page, and the page shows each one only to someone who holds that right for the item in its current state, so a team admin looking at a member’s personal item sees none of them, and a system administrator sees redact or restore. The item’s page opens only items of the team you are working in, so it offers a system administrator no way to redact an item in a team they do not belong to. Restoring is also on the APIs, under the same rights.
  • Reassigning an item’s ownership is more restricted: it is limited to team admins and owners only. A user who merely owns an item cannot reassign it.
  • When a member leaves a team, items follow their owner, not their original author. An item the departing member owns moves with them to their personal team; an item the team owns stays with the team, and the departing member simply loses access.
  • When a team is dismantled altogether there is nothing left to stay with, so every item goes to a personal team: user-owned items to their owners, and team-owned items to the personal team of whoever created the team.

Because ownership can change while an item keeps the same hashes, transfers and reassignments never invalidate an item’s proof: a committed item stays verifiable across any ownership change.

Limitations

  • The lifecycle states are the authoritative product facts, but the exact timing of automatic transitions (how quickly a created item becomes processing and then committed) depends on the block-building cadence and is not a fixed guarantee.
  • Deletion grace periods are configured values (currently 7 days for user-initiated and expiration deletions) and can change. Two paths are defined as having no grace period at all: account deletion, and destroying an item that is still in created.
  • Reaching committed gives no submission window on its own. A verifier draws both edges from public sources it reads: the submitted-before edge from the chain that holds the block’s epoch hash, and the submitted-after edge from the sources of the item’s entropy witnesses. Neither says when the underlying data was created.