@coordination-network/revocation-registry 0.0.1

package/types/index.d.ts

@@ -0,0 +1,351 @@
+import { LeanIMTPlusHashFunctions, LeanIMTPlusLeaf, LeanIMTPlusProof, LeanIMTPlus } from '@zk-kit/lean-imt-plus';
+
+/**
+ * The BN254 (alt_bn128) scalar field order. Every commitment stored in a
+ * revocation registry, and every hash the tree produces, is an element of this
+ * field. It matches `SNARK_SCALAR_FIELD` in the LeanIMT+ Solidity library and
+ * the field a BN254 zero-knowledge circuit works over.
+ */
+declare const SNARK_SCALAR_FIELD = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+/**
+ * Domain-separation tag mixed into every leaf commitment as the third input of
+ * the 3-input leaf hash. Kept here so callers can reproduce a leaf commitment
+ * without depending on LeanIMT+ internals.
+ */
+declare const TAG_LEAF = 1n;
+/**
+ * Proof discriminator. `MEMBERSHIP` proves the commitment is in the registry
+ * (the credential is revoked); `NON_MEMBERSHIP` proves it is absent (the
+ * credential is not revoked). A holder proving a valid credential always
+ * produces a `NON_MEMBERSHIP` proof.
+ */
+declare const PROOF_TYPE: {
+    readonly MEMBERSHIP: 0;
+    readonly NON_MEMBERSHIP: 1;
+};
+/**
+ * Version tag of the snapshot format produced by `export` and accepted by
+ * `import`. It must match the version the underlying LeanIMT+ writes, which
+ * enforces it on import.
+ */
+declare const SNAPSHOT_VERSION = 1;
+
+/**
+ * The hash pair every revocation registry uses, in every language.
+ *
+ * - `leaf` is a 3-input Poseidon over `(value, nextValue, TAG_LEAF)`. It matches
+ *   `PoseidonT4` in the LeanIMT+ Solidity library and `poseidon::bn254::hash_3`
+ *   in a BN254 Poseidon circuit.
+ * - `internal` is a 2-input Poseidon for inner nodes. It matches `PoseidonT3`
+ *   and `poseidon::bn254::hash_2`.
+ *
+ * The differing arity is what domain-separates a leaf commitment from an
+ * internal-node hash, which closes the second-preimage attack in which an
+ * attacker repackages an internal node as a leaf. All three implementations
+ * must agree on this pair or their roots will not match.
+ */
+declare const revocationHashes: LeanIMTPlusHashFunctions<bigint>;
+
+/** Anything that can be coerced to a field element with `BigInt()`. */
+type BigNumberish = bigint | number | string;
+/**
+ * A revocation proof. Structurally a LeanIMT+ proof: a Merkle proof of a single
+ * indexed leaf plus a `proofType` that says which extra check the verifier runs.
+ *
+ * - `proofType: 0` (membership): `leaf.value === value`, so the commitment is in
+ *   the registry and the credential is revoked.
+ * - `proofType: 1` (non-membership): `leaf` is the low leaf of `value`, so the
+ *   commitment is absent and the credential is not revoked.
+ *
+ * `root` is the value the verifier must independently accept as one the
+ * authoritative registry currently publishes. The proof proves nothing on its
+ * own: its root is supplied by whoever built it.
+ */
+type RevocationProof = LeanIMTPlusProof<bigint>;
+/** An indexed leaf of the revocation tree: a commitment and its successor. */
+type RevocationLeaf = LeanIMTPlusLeaf<bigint>;
+
+/**
+ * A revocation registry: a
+ * {@link https://pse.dev/blog/lean-imt-plus-efficient-merkle-tree-for-membership-and-non-membership-proofs | LeanIMT+}
+ * whose leaves are the revocation commitments of revoked credentials.
+ *
+ * The class is a self-contained implementation of the structure, not a client
+ * for any particular backend. It can hold a registry outright, which is what a
+ * service that publishes revocations from its own database does, or mirror one
+ * whose authoritative copy lives elsewhere, which is what a holder does before
+ * building a proof. Nothing here reads or writes anything external.
+ *
+ * Two operations serve the two roles:
+ *
+ * - **Issuer.** {@link revoke} inserts a commitment. Where the authoritative
+ *   registry is a separate system that validates a predecessor index rather than
+ *   searching for one, {@link lowLeafIndexOf} computes that index.
+ * - **Holder.** {@link generateProof} produces a proof about a commitment. A
+ *   non-membership proof (`proofType: 1`) is what shows a credential is not
+ *   revoked, and is the witness a zero-knowledge circuit consumes to show it
+ *   without revealing the commitment.
+ *
+ * When this instance is a mirror rather than the authority, it is trusted for
+ * availability only, never for integrity: compare {@link root} against the root
+ * the authority reports before using any proof built from it. Building the tree
+ * locally is also what keeps a holder private, since they read the whole public
+ * registry and never disclose which commitment they care about.
+ *
+ * An empty registry has a root of `0` and cannot produce proofs: nothing has
+ * been revoked yet, so there is nothing to prove against. Verifiers must handle
+ * that case as "no revocations", not as a failure.
+ */
+declare class RevocationRegistry {
+    /** The underlying LeanIMT+ instance. */
+    leanIMTPlus: LeanIMTPlus<bigint>;
+    /**
+     * Creates a registry, optionally pre-loaded with revoked commitments.
+     * Passing the full list is more efficient than revoking them one by one,
+     * because each affected internal node is rehashed at most once.
+     *
+     * The tree is position-addressable, so a different insertion order produces
+     * a different root even for the same set of commitments. When rebuilding a
+     * registry that already exists elsewhere, the commitments must be supplied
+     * in the order that registry inserted them.
+     *
+     * This reconstructs a registry only while nothing has ever been un-revoked.
+     * An un-revocation leaves a tombstoned slot behind, and that slot still
+     * occupies a Merkle position, so replaying the surviving commitments would
+     * produce a different root. Use {@link RevocationRegistry.fromLeaves} or
+     * {@link RevocationRegistry.import} for a registry that may have tombstones.
+     *
+     * @param commitments Revoked commitments, in insertion order.
+     */
+    constructor(commitments?: BigNumberish[]);
+    /** The current revocation root. `0` while the registry is empty. */
+    get root(): bigint;
+    /** The current tree depth. */
+    get depth(): number;
+    /** The number of revoked commitments, excluding the sentinel and tombstones. */
+    get size(): number;
+    /**
+     * The revoked commitments in insertion order. Reading `.value` off each leaf
+     * gives the commitments; `.nextValue` exposes the sorted linked list the
+     * non-membership proof relies on.
+     */
+    get leaves(): RevocationLeaf[];
+    /**
+     * The revoked commitments, in insertion order. Excludes the sentinel and any
+     * tombstones, so this is a lossy view of the tree: it round-trips through the
+     * constructor only while nothing has been un-revoked. See
+     * {@link leafSlots}.
+     */
+    get commitments(): bigint[];
+    /**
+     * Every physical leaf slot in index order, sentinel and tombstones included.
+     *
+     * This is the lossless view of the registry and the counterpart of
+     * {@link RevocationRegistry.fromLeaves}: an authority publishes these slots,
+     * and anyone can rebuild the exact same tree from them. It mirrors what the
+     * on-chain registry exposes through `getLeaf`.
+     *
+     * Prefer {@link commitments} to enumerate what is revoked. This walks the
+     * whole tree, so treat it as a publishing operation rather than a hot path.
+     */
+    get leafSlots(): RevocationLeaf[];
+    /** Returns true if the commitment has been revoked. */
+    isRevoked(commitment: BigNumberish): boolean;
+    /**
+     * Returns the physical leaf index of a revoked commitment, or `-1` if it is
+     * not revoked.
+     *
+     * This is a slot in the tree, never a position in {@link commitments}. The
+     * two always differ by at least one, because slot 0 is the sentinel, and
+     * they drift further apart with every tombstone.
+     */
+    indexOf(commitment: BigNumberish): number;
+    /**
+     * Revokes a credential by inserting its commitment.
+     *
+     * @param commitment The revocation commitment of the credential.
+     */
+    revoke(commitment: BigNumberish): void;
+    /**
+     * Revokes several credentials in one pass. Cheaper than calling
+     * {@link revoke} once per commitment, because each affected internal node is
+     * rehashed at most once.
+     *
+     * Not transactional: if a commitment mid-batch is rejected, the earlier ones
+     * have already been applied. Validate with {@link isRevoked} first when the
+     * input is untrusted.
+     *
+     * @param commitments The revocation commitments, in insertion order.
+     */
+    revokeMany(commitments: BigNumberish[]): void;
+    /**
+     * Un-revokes a credential, tombstoning its slot.
+     *
+     * Revocation is normally permanent, and a registry that never un-revokes is
+     * the simpler thing to reason about: an un-revoked credential becomes valid
+     * again for every verifier that has not yet seen the new root. The operation
+     * is exposed because the underlying tree supports it and some issuers need
+     * to undo a mistaken revocation, but reach for it deliberately.
+     *
+     * It also leaves a tombstoned slot behind, after which the registry can no
+     * longer be rebuilt from {@link commitments} alone. Publish the leaf slots
+     * (see {@link RevocationRegistry.fromLeaves}) or a snapshot instead.
+     *
+     * @param commitment The revocation commitment to un-revoke.
+     */
+    unrevoke(commitment: BigNumberish): void;
+    /**
+     * Replaces a revoked commitment with another one, in place, reusing the old
+     * physical slot. Cheaper than an {@link unrevoke} followed by a
+     * {@link revoke}, which would tombstone a slot and append a new one.
+     *
+     * @param oldCommitment The revoked commitment to replace.
+     * @param newCommitment The commitment to put in its place.
+     */
+    updateCommitment(oldCommitment: BigNumberish, newCommitment: BigNumberish): void;
+    /**
+     * Generates a proof for a commitment: a non-membership proof
+     * (`proofType: 1`) if the credential is not revoked, a membership proof
+     * (`proofType: 0`) if it is.
+     *
+     * The proof carries the root it was built against. It proves nothing until
+     * the verifier independently accepts that root as one the authoritative
+     * registry currently publishes.
+     *
+     * @param commitment The revocation commitment of the credential.
+     * @returns The revocation proof.
+     */
+    generateProof(commitment: BigNumberish): RevocationProof;
+    /**
+     * Verifies a proof against this tree's current root. Use the static
+     * {@link RevocationRegistry.verifyProof} to check a proof without a local tree.
+     */
+    verifyProof(proof: RevocationProof): boolean;
+    /**
+     * Verifies that a proof is internally consistent with the root it carries.
+     *
+     * This does not bind the proof to any registry: the caller supplies
+     * `proof.root`, so on its own this returns true for a proof against an
+     * attacker-chosen root. Always compare `proof.root` against a root you
+     * independently accept.
+     */
+    static verifyProof(proof: RevocationProof): boolean;
+    /**
+     * Returns the physical index of the low leaf of a commitment: the
+     * predecessor a constrained implementation needs supplied rather than
+     * searched for.
+     *
+     * {@link revoke} does not need this, since it finds the predecessor itself.
+     * It exists for registries whose authoritative implementation validates a
+     * caller-supplied index in O(1) instead of searching, which is how a version
+     * that has to bound its own cost per write is built. Such an index is only
+     * valid against the tree state the write applies to, so if another revocation
+     * lands first it must be recomputed against the new state.
+     *
+     * @param commitment The commitment about to be revoked.
+     * @returns The physical index of its predecessor, or `0` for the first
+     * revocation, where the argument is ignored and the sentinel is created.
+     */
+    lowLeafIndexOf(commitment: BigNumberish): number;
+    /**
+     * Returns the low leaf indices for a batch of commitments, as a batched
+     * write expects them: index `i` is computed against the tree state after
+     * commitments `0..i-1` have been inserted.
+     *
+     * Computed on a throwaway copy, so this tree is left untouched.
+     *
+     * @param commitments The commitments about to be revoked, in insertion order.
+     */
+    lowLeafIndicesOf(commitments: BigNumberish[]): number[];
+    /**
+     * Returns the physical index of the leaf whose `nextValue` is this
+     * commitment. The counterpart of {@link lowLeafIndexOf} for un-revoking and
+     * for replacing a commitment.
+     *
+     * Returns `0` when the commitment is the smallest in the registry, because
+     * the sentinel at index 0 is then its predecessor.
+     *
+     * @param commitment A revoked commitment.
+     */
+    predecessorIndexOf(commitment: BigNumberish): number;
+    /**
+     * Serializes the whole tree, hashes included.
+     *
+     * This is the snapshot format: publishing a snapshot lets a holder rebuild a
+     * large registry without replaying every revocation since genesis. A snapshot
+     * is trusted for availability only, so an importing client must still compare
+     * {@link root} against the root the authoritative registry publishes.
+     */
+    export(): string;
+    /**
+     * Rebuilds a tree from {@link export} output.
+     *
+     * @param snapshot The serialized tree.
+     * @param validate Recompute every commitment and check it against the
+     * serialized hashes, rejecting a tampered snapshot. Defaults to `true`; pass
+     * `false` only for data you produced yourself.
+     */
+    static import(snapshot: string, validate?: boolean): RevocationRegistry;
+    /**
+     * Rebuilds a registry from its full physical leaf slots, sentinel and
+     * tombstones included.
+     *
+     * This is the reconstruction path that always works. The constructor takes
+     * only the active commitments, which is enough only while no commitment has
+     * ever been un-revoked: an un-revocation leaves a tombstoned slot behind, and
+     * a slot still occupies a Merkle position, so a registry that has one cannot
+     * be reproduced from its commitments alone.
+     *
+     * The leaf slots are exactly what an authoritative registry can publish
+     * verbatim: {@link leafSlots} here, or `getLeaf(registryId, i)` for `i` in
+     * `0..getRevocationTreeLeafCount(registryId) - 1` on chain.
+     *
+     * Hashes are recomputed here rather than taken on trust, so unlike a snapshot
+     * the input carries no node data to tamper with. The caller must still
+     * compare {@link root} against the root the authority publishes, which is
+     * what detects missing or reordered slots.
+     *
+     * @param leaves The physical leaf slots, in index order starting at the
+     * sentinel.
+     * @returns The reconstructed registry.
+     */
+    static fromLeaves(leaves: {
+        value: BigNumberish;
+        nextValue: BigNumberish;
+    }[]): RevocationRegistry;
+}
+
+/**
+ * Coerces a value to a BN254 field element, rejecting anything outside the
+ * field.
+ *
+ * Every leaf field and every hash the registry produces must be a field element:
+ * outside that range two distinct values reduce to the same element, which would
+ * let one revocation silently cover an unrelated credential and would break the
+ * sorted ordering a non-membership proof relies on.
+ *
+ * Zero is accepted, because the sentinel and tombstone leaf slots hold it. Use
+ * {@link toCommitment} for anything that must be a real commitment.
+ *
+ * @param value The value, as a bigint, number or decimal string.
+ * @returns The value as a bigint.
+ */
+declare function toFieldElement(value: BigNumberish): bigint;
+/**
+ * Coerces a value to a revocation commitment, rejecting anything the registry
+ * cannot hold as one.
+ *
+ * A commitment must be a field element, for the reason given on
+ * {@link toFieldElement}, and must additionally be non-zero, because zero is
+ * reserved for the sentinel leaf and for tombstones.
+ *
+ * These are the rules of the structure itself, so every implementation of a
+ * registry enforces them.
+ *
+ * @param value The commitment, as a bigint, number or decimal string.
+ * @returns The commitment as a bigint.
+ */
+declare function toCommitment(value: BigNumberish): bigint;
+
+export { PROOF_TYPE, RevocationRegistry, SNAPSHOT_VERSION, SNARK_SCALAR_FIELD, TAG_LEAF, revocationHashes, toCommitment, toFieldElement };
+export type { BigNumberish, RevocationLeaf, RevocationProof };