CommitmentRegistry

Registry-chain contract that records FHE computation commitments. Teecryptor verifies ciphertext integrity against it before decrypting.

Aspect	Description
Type	UUPS-upgradeable Solidity contract deployed on a dedicated registry chain.
Function	Records (version, handle) → commitHash entries for every ciphertext the coprocessor produces or verifies, computed results and encrypted inputs alike.
Responsibilities	• Provide an authoritative source of ciphertext integrity that Teecryptor checks before decrypting. • Group commitments by an opaque version tag so a future tfhe-rs / FHE-parameter upgrade can roll out without invalidating earlier ciphertexts. • Enforce write-once semantics per (version, handle) to prevent commitment replacement. • Expose paginated enumeration so offchain tooling can audit what has been posted.
Deployment	One deployment per registry chain, behind an ERC-1967 proxy.

What a commitment is

A commitment is the keccak256 hash of a ciphertext’s canonical stored bytes. The compute pipeline produces one for every result it computes, and anchors one for every encrypted input the ZK Verifier approves. It batches them and writes them to this registry.

Who writes and who reads

One component writes commitments, and one component reads them. The write happens when a ciphertext is produced; the read happens later, whenever someone asks to decrypt it.

The compute pipeline and Teecryptor run offchain inside CoFHE; the registry itself is onchain. Hover any component or message in the explorable version.

Why commitments?

The commitment is a safety check in the decryption flow. Before decrypting anything, Teecryptor confirms that the ciphertext bytes it fetched hash to the commitment anchored onchain. It only ever decrypts a ciphertext the coprocessor actually produced, never a tampered or substituted one.

The registry also makes the coprocessor accountable. Every result it has ever produced is committed publicly, permanently, and write-once, so its computation history is tamper-evident and open to independent audit. Commitments for every host chain land on one dedicated registry chain, which gives the decryption path a single place to verify against.

Storage shape

mapping(bytes32 version => mapping(bytes32 handle => bytes32 commitHash)) commitments;
mapping(bytes32 version => bytes32[])                                     handlesByVersion;
mapping(bytes32 version => VersionStatus)                                 versionStatus;
mapping(address => bool)                                                  posters;

commitments is the source-of-truth lookup. handlesByVersion is an array kept in parallel so paginated enumeration is O(limit) instead of O(total). Storage lives at the ERC-7201 slot derived from cofhe.storage.CommitmentRegistry, so the contract is upgrade-safe.

Version lifecycle

version is an opaque bytes32 tag chosen by the coprocessor when FHE parameters change. The current tag is the number 2 encoded as bytes32. Every version moves through a small state machine:

Only an Active version accepts new commitments. Revoked is terminal.

State	Meaning	Allowed transitions
Unset	Default. No commitments have been posted under this version.	to Active
Active	Posters may write commitments under this version. Teecryptor honors lookups.	to Deprecated or Revoked
Deprecated	New commitments rejected. Existing lookups still resolve. Used during a parameter rollover.	to Revoked
Revoked	Hard kill. No further transitions; the version is dead.	none (terminal)

The admin-only setVersionStatus(version, newStatus) enforces these transitions and reverts with InvalidVersionTransition otherwise. The transition emits VersionStatusChanged(version, oldStatus, newStatus).

Write surface

Only accounts holding the poster role can write commitments (postCommitments, postCommitmentsSafe); posts from anyone else revert with OnlyPosterAllowed(caller). Poster management and version transitions are admin-only. In production, the poster role is held by the coprocessor’s relayer signer (OpenZeppelin Relayer).

Writing commitments

function postCommitments(
    bytes32 version,
    bytes32[] calldata handles,
    bytes32[] calldata commitHashes
) external onlyPoster;

function postCommitmentsSafe(
    bytes32 version,
    bytes32[] calldata handles,
    bytes32[] calldata commitHashes
) external onlyPoster;

Both functions batch-write (version, handle) → commitHash rows and require:

• version is in Active state, otherwise the call reverts with VersionNotActive(version).
• handles.length == commitHashes.length and > 0, otherwise LengthMismatch / EmptyBatch.
• Each commitHash != bytes32(0), otherwise ZeroCommitHash(handle).

The difference is in how duplicates are handled:

Function	Duplicate handle under same version	Use case
postCommitments	Reverts the whole batch with CommitmentAlreadyExists(version, handle).	Strict integrity: the caller knows it is posting unique data.
postCommitmentsSafe	Silently skips the handle; emits CommitmentsPostedSafe(version, newlyPosted, skipped).	Idempotent re-flushes (e.g. when the coprocessor’s message broker redelivers a commitment batch).

postCommitments emits CommitmentsPosted(version, batchSize). postCommitmentsSafe emits CommitmentsPostedSafe(version, newlyPosted, skipped) so the offchain caller can tell whether the round did real work.

Both enforce write-once per (version, handle): a commitment can never be overwritten, only superseded by writing the same handle under a new version.

Reading commitments

Function	Returns	Notes
getCommitment(version, handle)	bytes32	bytes32(0) means “not posted”.
getVersionStatus(version)	VersionStatus	Unset if never registered.
getSize(version)	uint256	Number of handles ever committed under version.
getHandleByIndex(version, index)	bytes32	Direct array lookup. Reverts on out-of-range.
getHandles(version, offset, limit)	bytes32[]	Paginated. Returns an empty array if offset >= total; clamps offset + limit at total.
isPoster(address)	bool	Useful for offchain ops dashboards.

The paginated getHandles is the recommended way to enumerate a version: getSize first to compute pages, then getHandles(version, offset, pageSize) in a loop.

Events

Event	Emitted by	Use
CommitmentsPosted	postCommitments	Confirm a strict batch landed. Carries the version and batch size.
CommitmentsPostedSafe	postCommitmentsSafe	Reconcile “how many were new” in an idempotent flow. Carries newlyPosted and skipped counts.
VersionStatusChanged	setVersionStatus	Watch for the Active to Deprecated transition to know when to stop posting under a version.
PosterAdded / PosterRemoved	addPoster / removePoster	Audit role changes.

Source

• Solidity: contracts/internal/registry-chain/contracts/commitment-registry/CommitmentRegistry.sol.
• Offchain: the compute pipeline’s blockchain poster batches the commitments and posts them to this registry.
• The pipeline sets the commitment version, and bumps it when the FHE parameters change.