@coordination-network/issuer-set 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ethereum Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# @coordination-network/issuer-set
+
+The approved-issuer set in TypeScript: a [LeanIMT](https://github.com/zk-kit/zk-kit) accumulator over the credential signing keys of approved network members, mirroring `ApprovedIssuerSet.sol`.
+
+A verifier needs to know that whoever signed a credential was an approved issuer at the time. The set answers that with a single Merkle proof against a root everyone agrees on, and that proof is the witness a zero-knowledge circuit consumes to show the same thing without revealing which issuer signed.
+
+Keys are Baby Jubjub public keys in affine form, `[x, y]`. Leaves and internal nodes are Poseidon hashes over the BN254 scalar field, domain-separated by `ISSUER_LEAF_DOMAIN`, which is what keeps this implementation, the Solidity one and the circuit in agreement.
+
+## Install
+
+```bash
+yarn add @coordination-network/issuer-set
+```
+
+## Usage
+
+### Building the set and proving membership
+
+```ts
+import { ApprovedIssuerSet } from "@coordination-network/issuer-set"
+
+const set = new ApprovedIssuerSet(publicKeys)
+
+if (!set.isApproved(issuerKey)) throw new Error("issuer is not approved")
+
+const witness = set.generateProof(issuerKey)
+
+// witness.root is what a verifier pins against the authority
+```
+
+Order matters. The tree is position-addressable, so the same keys inserted in a different order produce a different root. When rebuilding a set that already exists, supply the keys in the order that set published them.
+
+### Rebuilding from the authority
+
+The on-chain set is the authoritative copy.
+
+```ts
+const set = await ApprovedIssuerSet.fromContract({
+    getLeafCount: () => contract.read.getLeafCount(),
+    getLeaves: (start, end) => contract.read.getLeaves([start, end])
+})
+```
+
+### Publishing and retiring keys
+
+```ts
+const leaf = set.publish(issuerKey) // curve-validated, unlike the constructor
+set.publishMany(issuerKeys)
+set.retire(issuerKey) // tombstones the slot; leafCount never shrinks
+```
+
+### Verifying a proof
+
+```ts
+set.verifyProof(witness) // against this set's current root
+ApprovedIssuerSet.verifyProof(witness) // against the root the witness carries
+```
+
+## Notes
+
+- The set must not be empty, and it is capped at `2 ** ISSUER_SET_MAX_DEPTH` (depth 20) because that is the circuit's `binary_merkle_root` capacity. The tree's actual depth is dynamic and tracks `ceil(log2(leafCount))`.

package/dist/index.cjs

@@ -0,0 +1,287 @@
+'use strict';
+
+var leanImt = require('@zk-kit/lean-imt');
+var poseidon2 = require('poseidon-lite/poseidon2');
+var poseidon3 = require('poseidon-lite/poseidon3');
+var babyJubjub = require('@zk-kit/baby-jubjub');
+
+/**
+ * The BN254 (alt_bn128) scalar field order. Every leaf and internal-node hash,
+ * and every signing-key coordinate, is an element of this field.
+ */
+const SNARK_SCALAR_FIELD = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+/**
+ * Baby Jubjub's cofactor. A point has low order exactly when multiplying it by
+ * this gives the identity, which is what disqualifies a signing key: see
+ * `toPublicKey`.
+ */
+const COFACTOR = 8n;
+/**
+ * The tree's capacity bound: spec 03's construction and the circuit's
+ * `binary_merkle_root`. The tree's actual depth is dynamic; see
+ * `ApprovedIssuerSet.depth`.
+ */
+const ISSUER_SET_MAX_DEPTH = 20;
+/**
+ * Domain separator mixed into every leaf commitment, matching
+ * `IssuerSetHashes.ISSUER_LEAF_DOMAIN` in Solidity and `LEAF_DOMAIN` in the
+ * circuit.
+ */
+const ISSUER_LEAF_DOMAIN = 185404551131306766954100762329350135288498146007932686448214248919067924295n;
+
+/**
+ * Commits a Baby Jubjub public key to the leaf value the tree stores for it.
+ * Matches `IssuerSetHashes.issuerKeyLeaf` in Solidity (`PoseidonT4`) and the
+ * leaf hash in `packages/circuits/src/issuer.nr`; all three must agree or a
+ * proof built against one never verifies against a root from another.
+ */
+function issuerKeyLeaf(publicKey) {
+    return poseidon3.poseidon3([ISSUER_LEAF_DOMAIN, publicKey[0], publicKey[1]]);
+}
+/** Alias for the name `packages/credential`'s re-export carries forward. */
+const issuerLeaf = issuerKeyLeaf;
+/** Combines two child nodes into their parent. Matches `IssuerSetHashes.internalNode` (`PoseidonT3`). */
+function internalNode(left, right) {
+    return poseidon2.poseidon2([left, right]);
+}
+
+/**
+ * Coerces a value to a BN254 field element, rejecting anything outside the
+ * field.
+ *
+ * Every leaf and every hash the set produces must be a field element: outside
+ * that range two distinct values reduce to the same element, so one key's
+ * membership proof would open against another's leaf.
+ *
+ * Zero is accepted, because a tombstoned or never-written slot holds it.
+ *
+ * @param value The value, as a bigint, number or decimal string.
+ * @returns The value as a bigint.
+ */
+function toFieldElement(value) {
+    const element = BigInt(value);
+    if (element < 0n) {
+        throw new Error("ApprovedIssuerSet: a field element must not be negative");
+    }
+    if (element >= SNARK_SCALAR_FIELD) {
+        throw new Error("ApprovedIssuerSet: a field element must be less than the SNARK scalar field order");
+    }
+    return element;
+}
+/**
+ * Coerces a pair to a Baby Jubjub public key of full order, rejecting a point
+ * that is not on the curve or that lies in the small-order subgroup.
+ *
+ * The set would happily commit to any two field elements, so without the curve
+ * check a caller could publish a commitment to a point that does not exist.
+ *
+ * The order check matters more. Under a low-order public key `A` the term `h·A`
+ * in EdDSA verification takes at most eight values whatever the message, so
+ * anyone can solve `S·B = R + h·A` for a signature over a claim tree they chose;
+ * at the identity it is immediate. Publishing such a key would hand every
+ * stranger the member's issuing power. Mirrors the same rejection in
+ * `ApprovedIssuerSet.sol`.
+ *
+ * @param publicKey The signing key as `[x, y]`.
+ * @returns The key with both coordinates as bigints.
+ */
+function toPublicKey(publicKey) {
+    const point = [toFieldElement(publicKey[0]), toFieldElement(publicKey[1])];
+    if (!babyJubjub.inCurve(point)) {
+        throw new Error("ApprovedIssuerSet: the public key is not a point on Baby Jubjub");
+    }
+    // A point has low order exactly when eight times it is the identity, the curve's cofactor being
+    // eight. That is the same set of eight points the contract rejects by x coordinate.
+    const [x, y] = babyJubjub.mulPointEscalar(point, COFACTOR);
+    if (x === 0n && y === 1n) {
+        throw new Error("ApprovedIssuerSet: the public key has low order");
+    }
+    return point;
+}
+
+/** How many leaves {@link ApprovedIssuerSet.fromContract} requests per `getLeaves` call. */
+const FROM_CONTRACT_PAGE_SIZE = 1000;
+/**
+ * The approved-issuer set: a LeanIMT accumulator, capped at depth
+ * {@link ISSUER_SET_MAX_DEPTH}, over network members' credential signing keys
+ * spec 03 defines, mirroring `ApprovedIssuerSet.sol`.
+ *
+ * A retired key's slot is tombstoned to `0` rather than removed, the same
+ * dense, append-only storage the contract keeps: `leafCount` never shrinks, so
+ * a slot's Merkle position never changes once assigned. A node with no right
+ * sibling is promoted unchanged rather than hashed against a zero, so the
+ * tree's depth tracks `ceil(log2(leafCount))` instead of staying fixed.
+ */
+class ApprovedIssuerSet {
+    /**
+     * @param publicKeys The set's current signing keys, in order. Not
+     * curve-validated: this bulk-load path mirrors an already-validated
+     * on-chain state, unlike {@link publish}.
+     */
+    constructor(publicKeys) {
+        if (publicKeys.length === 0)
+            throw new Error("approved issuer set must not be empty");
+        if (publicKeys.length > 2 ** ISSUER_SET_MAX_DEPTH) {
+            throw new Error("approved issuer set exceeds circuit capacity");
+        }
+        const leaves = publicKeys.map(issuerKeyLeaf);
+        // Compared as leaves, not as coordinate pairs, so this agrees with `publish`'s own check.
+        if (new Set(leaves).size !== leaves.length) {
+            throw new Error("approved issuer set contains a duplicate key");
+        }
+        this.tree = new leanImt.LeanIMT(internalNode, leaves);
+    }
+    /** The current root. Never `undefined`: both constructors require at least one slot. */
+    get root() {
+        return this.tree.root;
+    }
+    /** The number of physical leaf slots, including tombstoned ones. Never decreases. */
+    get leafCount() {
+        return this.tree.size;
+    }
+    /** The number of currently approved (non-tombstoned) keys. */
+    get size() {
+        return this.tree.leaves.filter((leaf) => leaf !== 0n).length;
+    }
+    /** `ceil(log2(leafCount))`, 0 for a one-slot set. Grows as slots are added; never shrinks. */
+    get depth() {
+        return this.tree.depth;
+    }
+    /** Every physical slot, in order, `0` for a tombstone. A copy: mutate through {@link publish}/{@link retire}. */
+    get leafSlots() {
+        return this.tree.leaves;
+    }
+    /** The leaf a key would occupy, without publishing it. */
+    static leafOf(publicKey) {
+        return issuerKeyLeaf(toPublicKey(publicKey));
+    }
+    /**
+     * Rebuilds a set from the physical slot table a holder reads with
+     * `ApprovedIssuerSet.getLeaves` — the private path that never asks the
+     * chain which leaf it holds a witness for (see the contract's
+     * `siblingsOf` natspec).
+     *
+     * @param leaves Every slot, in physical order, `0` for a tombstone.
+     * @throws if `leaves` is empty. A drained set (every slot tombstoned) is
+     * a valid, nonzero-length input; the on-chain analogue is `leafCount`
+     * being monotonic, so a set that has ever published a key is never truly
+     * empty again.
+     */
+    static fromLeaves(leaves) {
+        if (leaves.length === 0)
+            throw new Error("approved issuer set must not be empty");
+        // Bypasses the public constructor, which validates a list of public keys: these are already
+        // leaf hashes, not keys, mirroring a state the caller trusts (the contract's own storage).
+        const set = Object.create(ApprovedIssuerSet.prototype);
+        set.tree = new leanImt.LeanIMT(internalNode, leaves.map(toFieldElement));
+        return set;
+    }
+    /**
+     * Rebuilds a set from a deployed `ApprovedIssuerSet.sol`, paging through
+     * `getLeaves` so a large set never needs one unbounded call. Pages are
+     * fetched concurrently — the reader isn't block-pinned, so this is no
+     * weaker a read than the sequential form.
+     */
+    static async fromContract(reader) {
+        const leafCount = Number(await reader.getLeafCount());
+        const ranges = [];
+        for (let start = 0; start < leafCount; start += FROM_CONTRACT_PAGE_SIZE) {
+            ranges.push([start, Math.min(start + FROM_CONTRACT_PAGE_SIZE, leafCount)]);
+        }
+        const pages = await Promise.all(ranges.map(([start, end]) => reader.getLeaves(start, end)));
+        return ApprovedIssuerSet.fromLeaves(pages.flat());
+    }
+    /** Whether a witness is internally consistent with the root it carries, independent of any set. */
+    static verifyProof(proof) {
+        if (proof.indices.length !== proof.siblings.length)
+            return false;
+        let packed = 0;
+        for (let level = 0; level < proof.indices.length; level += 1) {
+            if (proof.indices[level])
+                packed |= 1 << level;
+        }
+        if (packed !== proof.pathIndex)
+            return false;
+        return leanImt.LeanIMT.verifyProof({ root: proof.root, leaf: proof.leaf, index: proof.pathIndex, siblings: proof.siblings }, internalNode);
+    }
+    /** Whether a signing key is currently approved. */
+    isApproved(publicKey) {
+        return this.indexOf(publicKey) >= 0;
+    }
+    /** The physical index of a currently approved key, or `-1`. */
+    indexOf(publicKey) {
+        return this.tree.indexOf(issuerKeyLeaf(publicKey));
+    }
+    /**
+     * Publishes a signing key, appended at the next free slot.
+     * @returns The leaf commitment inserted.
+     * @throws if the key is off-curve, low-order, or already approved.
+     */
+    publish(publicKey) {
+        const leaf = issuerKeyLeaf(toPublicKey(publicKey));
+        if (this.tree.has(leaf)) {
+            throw new Error("approved issuer set contains a duplicate key");
+        }
+        this.tree.insert(leaf);
+        return leaf;
+    }
+    /**
+     * {@link publish}, for several keys in order. Each is checked against the
+     * ones already in this batch too, and the set is rebuilt once at the end
+     * rather than after every key.
+     * @throws if any key is invalid or a duplicate, leaving the set unchanged.
+     */
+    publishMany(publicKeys) {
+        if (publicKeys.length === 0)
+            return [];
+        const leaves = [];
+        for (const publicKey of publicKeys) {
+            const leaf = issuerKeyLeaf(toPublicKey(publicKey));
+            if (this.tree.has(leaf) || leaves.includes(leaf)) {
+                throw new Error("approved issuer set contains a duplicate key");
+            }
+            leaves.push(leaf);
+        }
+        this.tree.insertMany(leaves);
+        return leaves;
+    }
+    /**
+     * Tombstones a key's slot to `0`, ending its ability to verify. The slot
+     * stays allocated; a republished key gets a new one.
+     * @throws if the key is off-curve, low-order, or not currently approved.
+     */
+    retire(publicKey) {
+        const index = this.indexOf(toPublicKey(publicKey));
+        if (index < 0)
+            throw new Error("credential issuer is not in the approved set");
+        this.tree.update(index, 0n);
+    }
+    /**
+     * Generates the membership witness the credential circuit consumes.
+     * @throws if the key is off-curve, low-order, or not currently approved.
+     */
+    generateProof(publicKey) {
+        const leaf = issuerKeyLeaf(toPublicKey(publicKey));
+        const leafIndex = this.tree.indexOf(leaf);
+        if (leafIndex < 0)
+            throw new Error("credential issuer is not in the approved set");
+        const proof = this.tree.generateProof(leafIndex);
+        const indices = Array.from({ length: proof.siblings.length }, (_, level) => ((proof.index >> level) & 1) === 1);
+        return { root: this.root, leafIndex, pathIndex: proof.index, siblings: proof.siblings, indices, leaf };
+    }
+    /** Instance form of {@link ApprovedIssuerSet.verifyProof}, additionally bound to this set's current root. */
+    verifyProof(proof) {
+        return proof.root === this.root && ApprovedIssuerSet.verifyProof(proof);
+    }
+}
+
+exports.ApprovedIssuerSet = ApprovedIssuerSet;
+exports.COFACTOR = COFACTOR;
+exports.ISSUER_LEAF_DOMAIN = ISSUER_LEAF_DOMAIN;
+exports.ISSUER_SET_MAX_DEPTH = ISSUER_SET_MAX_DEPTH;
+exports.SNARK_SCALAR_FIELD = SNARK_SCALAR_FIELD;
+exports.internalNode = internalNode;
+exports.issuerKeyLeaf = issuerKeyLeaf;
+exports.issuerLeaf = issuerLeaf;
+exports.toFieldElement = toFieldElement;
+exports.toPublicKey = toPublicKey;

package/dist/index.js

@@ -0,0 +1,276 @@
+import { LeanIMT } from '@zk-kit/lean-imt';
+import { poseidon2 } from 'poseidon-lite/poseidon2';
+import { poseidon3 } from 'poseidon-lite/poseidon3';
+import { inCurve, mulPointEscalar } from '@zk-kit/baby-jubjub';
+
+/**
+ * The BN254 (alt_bn128) scalar field order. Every leaf and internal-node hash,
+ * and every signing-key coordinate, is an element of this field.
+ */
+const SNARK_SCALAR_FIELD = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+/**
+ * Baby Jubjub's cofactor. A point has low order exactly when multiplying it by
+ * this gives the identity, which is what disqualifies a signing key: see
+ * `toPublicKey`.
+ */
+const COFACTOR = 8n;
+/**
+ * The tree's capacity bound: spec 03's construction and the circuit's
+ * `binary_merkle_root`. The tree's actual depth is dynamic; see
+ * `ApprovedIssuerSet.depth`.
+ */
+const ISSUER_SET_MAX_DEPTH = 20;
+/**
+ * Domain separator mixed into every leaf commitment, matching
+ * `IssuerSetHashes.ISSUER_LEAF_DOMAIN` in Solidity and `LEAF_DOMAIN` in the
+ * circuit.
+ */
+const ISSUER_LEAF_DOMAIN = 185404551131306766954100762329350135288498146007932686448214248919067924295n;
+
+/**
+ * Commits a Baby Jubjub public key to the leaf value the tree stores for it.
+ * Matches `IssuerSetHashes.issuerKeyLeaf` in Solidity (`PoseidonT4`) and the
+ * leaf hash in `packages/circuits/src/issuer.nr`; all three must agree or a
+ * proof built against one never verifies against a root from another.
+ */
+function issuerKeyLeaf(publicKey) {
+    return poseidon3([ISSUER_LEAF_DOMAIN, publicKey[0], publicKey[1]]);
+}
+/** Alias for the name `packages/credential`'s re-export carries forward. */
+const issuerLeaf = issuerKeyLeaf;
+/** Combines two child nodes into their parent. Matches `IssuerSetHashes.internalNode` (`PoseidonT3`). */
+function internalNode(left, right) {
+    return poseidon2([left, right]);
+}
+
+/**
+ * Coerces a value to a BN254 field element, rejecting anything outside the
+ * field.
+ *
+ * Every leaf and every hash the set produces must be a field element: outside
+ * that range two distinct values reduce to the same element, so one key's
+ * membership proof would open against another's leaf.
+ *
+ * Zero is accepted, because a tombstoned or never-written slot holds it.
+ *
+ * @param value The value, as a bigint, number or decimal string.
+ * @returns The value as a bigint.
+ */
+function toFieldElement(value) {
+    const element = BigInt(value);
+    if (element < 0n) {
+        throw new Error("ApprovedIssuerSet: a field element must not be negative");
+    }
+    if (element >= SNARK_SCALAR_FIELD) {
+        throw new Error("ApprovedIssuerSet: a field element must be less than the SNARK scalar field order");
+    }
+    return element;
+}
+/**
+ * Coerces a pair to a Baby Jubjub public key of full order, rejecting a point
+ * that is not on the curve or that lies in the small-order subgroup.
+ *
+ * The set would happily commit to any two field elements, so without the curve
+ * check a caller could publish a commitment to a point that does not exist.
+ *
+ * The order check matters more. Under a low-order public key `A` the term `h·A`
+ * in EdDSA verification takes at most eight values whatever the message, so
+ * anyone can solve `S·B = R + h·A` for a signature over a claim tree they chose;
+ * at the identity it is immediate. Publishing such a key would hand every
+ * stranger the member's issuing power. Mirrors the same rejection in
+ * `ApprovedIssuerSet.sol`.
+ *
+ * @param publicKey The signing key as `[x, y]`.
+ * @returns The key with both coordinates as bigints.
+ */
+function toPublicKey(publicKey) {
+    const point = [toFieldElement(publicKey[0]), toFieldElement(publicKey[1])];
+    if (!inCurve(point)) {
+        throw new Error("ApprovedIssuerSet: the public key is not a point on Baby Jubjub");
+    }
+    // A point has low order exactly when eight times it is the identity, the curve's cofactor being
+    // eight. That is the same set of eight points the contract rejects by x coordinate.
+    const [x, y] = mulPointEscalar(point, COFACTOR);
+    if (x === 0n && y === 1n) {
+        throw new Error("ApprovedIssuerSet: the public key has low order");
+    }
+    return point;
+}
+
+/** How many leaves {@link ApprovedIssuerSet.fromContract} requests per `getLeaves` call. */
+const FROM_CONTRACT_PAGE_SIZE = 1000;
+/**
+ * The approved-issuer set: a LeanIMT accumulator, capped at depth
+ * {@link ISSUER_SET_MAX_DEPTH}, over network members' credential signing keys
+ * spec 03 defines, mirroring `ApprovedIssuerSet.sol`.
+ *
+ * A retired key's slot is tombstoned to `0` rather than removed, the same
+ * dense, append-only storage the contract keeps: `leafCount` never shrinks, so
+ * a slot's Merkle position never changes once assigned. A node with no right
+ * sibling is promoted unchanged rather than hashed against a zero, so the
+ * tree's depth tracks `ceil(log2(leafCount))` instead of staying fixed.
+ */
+class ApprovedIssuerSet {
+    /**
+     * @param publicKeys The set's current signing keys, in order. Not
+     * curve-validated: this bulk-load path mirrors an already-validated
+     * on-chain state, unlike {@link publish}.
+     */
+    constructor(publicKeys) {
+        if (publicKeys.length === 0)
+            throw new Error("approved issuer set must not be empty");
+        if (publicKeys.length > 2 ** ISSUER_SET_MAX_DEPTH) {
+            throw new Error("approved issuer set exceeds circuit capacity");
+        }
+        const leaves = publicKeys.map(issuerKeyLeaf);
+        // Compared as leaves, not as coordinate pairs, so this agrees with `publish`'s own check.
+        if (new Set(leaves).size !== leaves.length) {
+            throw new Error("approved issuer set contains a duplicate key");
+        }
+        this.tree = new LeanIMT(internalNode, leaves);
+    }
+    /** The current root. Never `undefined`: both constructors require at least one slot. */
+    get root() {
+        return this.tree.root;
+    }
+    /** The number of physical leaf slots, including tombstoned ones. Never decreases. */
+    get leafCount() {
+        return this.tree.size;
+    }
+    /** The number of currently approved (non-tombstoned) keys. */
+    get size() {
+        return this.tree.leaves.filter((leaf) => leaf !== 0n).length;
+    }
+    /** `ceil(log2(leafCount))`, 0 for a one-slot set. Grows as slots are added; never shrinks. */
+    get depth() {
+        return this.tree.depth;
+    }
+    /** Every physical slot, in order, `0` for a tombstone. A copy: mutate through {@link publish}/{@link retire}. */
+    get leafSlots() {
+        return this.tree.leaves;
+    }
+    /** The leaf a key would occupy, without publishing it. */
+    static leafOf(publicKey) {
+        return issuerKeyLeaf(toPublicKey(publicKey));
+    }
+    /**
+     * Rebuilds a set from the physical slot table a holder reads with
+     * `ApprovedIssuerSet.getLeaves` — the private path that never asks the
+     * chain which leaf it holds a witness for (see the contract's
+     * `siblingsOf` natspec).
+     *
+     * @param leaves Every slot, in physical order, `0` for a tombstone.
+     * @throws if `leaves` is empty. A drained set (every slot tombstoned) is
+     * a valid, nonzero-length input; the on-chain analogue is `leafCount`
+     * being monotonic, so a set that has ever published a key is never truly
+     * empty again.
+     */
+    static fromLeaves(leaves) {
+        if (leaves.length === 0)
+            throw new Error("approved issuer set must not be empty");
+        // Bypasses the public constructor, which validates a list of public keys: these are already
+        // leaf hashes, not keys, mirroring a state the caller trusts (the contract's own storage).
+        const set = Object.create(ApprovedIssuerSet.prototype);
+        set.tree = new LeanIMT(internalNode, leaves.map(toFieldElement));
+        return set;
+    }
+    /**
+     * Rebuilds a set from a deployed `ApprovedIssuerSet.sol`, paging through
+     * `getLeaves` so a large set never needs one unbounded call. Pages are
+     * fetched concurrently — the reader isn't block-pinned, so this is no
+     * weaker a read than the sequential form.
+     */
+    static async fromContract(reader) {
+        const leafCount = Number(await reader.getLeafCount());
+        const ranges = [];
+        for (let start = 0; start < leafCount; start += FROM_CONTRACT_PAGE_SIZE) {
+            ranges.push([start, Math.min(start + FROM_CONTRACT_PAGE_SIZE, leafCount)]);
+        }
+        const pages = await Promise.all(ranges.map(([start, end]) => reader.getLeaves(start, end)));
+        return ApprovedIssuerSet.fromLeaves(pages.flat());
+    }
+    /** Whether a witness is internally consistent with the root it carries, independent of any set. */
+    static verifyProof(proof) {
+        if (proof.indices.length !== proof.siblings.length)
+            return false;
+        let packed = 0;
+        for (let level = 0; level < proof.indices.length; level += 1) {
+            if (proof.indices[level])
+                packed |= 1 << level;
+        }
+        if (packed !== proof.pathIndex)
+            return false;
+        return LeanIMT.verifyProof({ root: proof.root, leaf: proof.leaf, index: proof.pathIndex, siblings: proof.siblings }, internalNode);
+    }
+    /** Whether a signing key is currently approved. */
+    isApproved(publicKey) {
+        return this.indexOf(publicKey) >= 0;
+    }
+    /** The physical index of a currently approved key, or `-1`. */
+    indexOf(publicKey) {
+        return this.tree.indexOf(issuerKeyLeaf(publicKey));
+    }
+    /**
+     * Publishes a signing key, appended at the next free slot.
+     * @returns The leaf commitment inserted.
+     * @throws if the key is off-curve, low-order, or already approved.
+     */
+    publish(publicKey) {
+        const leaf = issuerKeyLeaf(toPublicKey(publicKey));
+        if (this.tree.has(leaf)) {
+            throw new Error("approved issuer set contains a duplicate key");
+        }
+        this.tree.insert(leaf);
+        return leaf;
+    }
+    /**
+     * {@link publish}, for several keys in order. Each is checked against the
+     * ones already in this batch too, and the set is rebuilt once at the end
+     * rather than after every key.
+     * @throws if any key is invalid or a duplicate, leaving the set unchanged.
+     */
+    publishMany(publicKeys) {
+        if (publicKeys.length === 0)
+            return [];
+        const leaves = [];
+        for (const publicKey of publicKeys) {
+            const leaf = issuerKeyLeaf(toPublicKey(publicKey));
+            if (this.tree.has(leaf) || leaves.includes(leaf)) {
+                throw new Error("approved issuer set contains a duplicate key");
+            }
+            leaves.push(leaf);
+        }
+        this.tree.insertMany(leaves);
+        return leaves;
+    }
+    /**
+     * Tombstones a key's slot to `0`, ending its ability to verify. The slot
+     * stays allocated; a republished key gets a new one.
+     * @throws if the key is off-curve, low-order, or not currently approved.
+     */
+    retire(publicKey) {
+        const index = this.indexOf(toPublicKey(publicKey));
+        if (index < 0)
+            throw new Error("credential issuer is not in the approved set");
+        this.tree.update(index, 0n);
+    }
+    /**
+     * Generates the membership witness the credential circuit consumes.
+     * @throws if the key is off-curve, low-order, or not currently approved.
+     */
+    generateProof(publicKey) {
+        const leaf = issuerKeyLeaf(toPublicKey(publicKey));
+        const leafIndex = this.tree.indexOf(leaf);
+        if (leafIndex < 0)
+            throw new Error("credential issuer is not in the approved set");
+        const proof = this.tree.generateProof(leafIndex);
+        const indices = Array.from({ length: proof.siblings.length }, (_, level) => ((proof.index >> level) & 1) === 1);
+        return { root: this.root, leafIndex, pathIndex: proof.index, siblings: proof.siblings, indices, leaf };
+    }
+    /** Instance form of {@link ApprovedIssuerSet.verifyProof}, additionally bound to this set's current root. */
+    verifyProof(proof) {
+        return proof.root === this.root && ApprovedIssuerSet.verifyProof(proof);
+    }
+}
+
+export { ApprovedIssuerSet, COFACTOR, ISSUER_LEAF_DOMAIN, ISSUER_SET_MAX_DEPTH, SNARK_SCALAR_FIELD, internalNode, issuerKeyLeaf, issuerLeaf, toFieldElement, toPublicKey };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@coordination-network/issuer-set",
+  "version": "0.0.1",
+  "description": "Approved-issuer set in TypeScript: publish network members' credential signing keys into the LeanIMT accumulator (dynamic depth, capacity 2^20) spec 03 defines, and generate the membership proofs a credential circuit consumes, as the set itself or as a mirror of one held on chain.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zk-kit/coordination-network.git",
+    "directory": "packages/issuer-set"
+  },
+  "homepage": "https://github.com/zk-kit/coordination-network/tree/main/packages/issuer-set",
+  "bugs": "https://github.com/zk-kit/coordination-network/issues",
+  "sideEffects": false,
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "types/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist types && rollup -c rollup.config.mjs"
+  },
+  "dependencies": {
+    "@zk-kit/baby-jubjub": "1.0.3",
+    "@zk-kit/lean-imt": "2.2.5",
+    "poseidon-lite": "0.3.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^12.3.0",
+    "rimraf": "^6.1.3",
+    "rollup": "^4.62.2",
+    "rollup-plugin-cleanup": "^3.2.1",
+    "rollup-plugin-dts": "^6.4.1",
+    "tslib": "^2.8.0",
+    "typescript": "^6.0.3"
+  }
+}

package/src/approved-issuer-set.ts

@@ -0,0 +1,217 @@
+import { LeanIMT } from "@zk-kit/lean-imt"
+import { ISSUER_SET_MAX_DEPTH } from "./constants"
+import { internalNode, issuerKeyLeaf } from "./hashes"
+import type { BigNumberish, ContractLeafReader, IssuerMembershipWitness, IssuerPublicKey, IssuerSet } from "./types"
+import { toFieldElement, toPublicKey } from "./utils"
+
+/** How many leaves {@link ApprovedIssuerSet.fromContract} requests per `getLeaves` call. */
+const FROM_CONTRACT_PAGE_SIZE = 1000
+
+/**
+ * The approved-issuer set: a LeanIMT accumulator, capped at depth
+ * {@link ISSUER_SET_MAX_DEPTH}, over network members' credential signing keys
+ * spec 03 defines, mirroring `ApprovedIssuerSet.sol`.
+ *
+ * A retired key's slot is tombstoned to `0` rather than removed, the same
+ * dense, append-only storage the contract keeps: `leafCount` never shrinks, so
+ * a slot's Merkle position never changes once assigned. A node with no right
+ * sibling is promoted unchanged rather than hashed against a zero, so the
+ * tree's depth tracks `ceil(log2(leafCount))` instead of staying fixed.
+ */
+export class ApprovedIssuerSet implements IssuerSet {
+    private tree: LeanIMT<bigint>
+
+    /**
+     * @param publicKeys The set's current signing keys, in order. Not
+     * curve-validated: this bulk-load path mirrors an already-validated
+     * on-chain state, unlike {@link publish}.
+     */
+    constructor(publicKeys: IssuerPublicKey[]) {
+        if (publicKeys.length === 0) throw new Error("approved issuer set must not be empty")
+        if (publicKeys.length > 2 ** ISSUER_SET_MAX_DEPTH) {
+            throw new Error("approved issuer set exceeds circuit capacity")
+        }
+
+        const leaves = publicKeys.map(issuerKeyLeaf)
+        // Compared as leaves, not as coordinate pairs, so this agrees with `publish`'s own check.
+        if (new Set(leaves).size !== leaves.length) {
+            throw new Error("approved issuer set contains a duplicate key")
+        }
+
+        this.tree = new LeanIMT<bigint>(internalNode, leaves)
+    }
+
+    /** The current root. Never `undefined`: both constructors require at least one slot. */
+    get root(): bigint {
+        return this.tree.root
+    }
+
+    /** The number of physical leaf slots, including tombstoned ones. Never decreases. */
+    get leafCount(): number {
+        return this.tree.size
+    }
+
+    /** The number of currently approved (non-tombstoned) keys. */
+    get size(): number {
+        return this.tree.leaves.filter((leaf) => leaf !== 0n).length
+    }
+
+    /** `ceil(log2(leafCount))`, 0 for a one-slot set. Grows as slots are added; never shrinks. */
+    get depth(): number {
+        return this.tree.depth
+    }
+
+    /** Every physical slot, in order, `0` for a tombstone. A copy: mutate through {@link publish}/{@link retire}. */
+    get leafSlots(): bigint[] {
+        return this.tree.leaves
+    }
+
+    /** The leaf a key would occupy, without publishing it. */
+    static leafOf(publicKey: IssuerPublicKey): bigint {
+        return issuerKeyLeaf(toPublicKey(publicKey))
+    }
+
+    /**
+     * Rebuilds a set from the physical slot table a holder reads with
+     * `ApprovedIssuerSet.getLeaves` — the private path that never asks the
+     * chain which leaf it holds a witness for (see the contract's
+     * `siblingsOf` natspec).
+     *
+     * @param leaves Every slot, in physical order, `0` for a tombstone.
+     * @throws if `leaves` is empty. A drained set (every slot tombstoned) is
+     * a valid, nonzero-length input; the on-chain analogue is `leafCount`
+     * being monotonic, so a set that has ever published a key is never truly
+     * empty again.
+     */
+    static fromLeaves(leaves: BigNumberish[]): ApprovedIssuerSet {
+        if (leaves.length === 0) throw new Error("approved issuer set must not be empty")
+
+        // Bypasses the public constructor, which validates a list of public keys: these are already
+        // leaf hashes, not keys, mirroring a state the caller trusts (the contract's own storage).
+        const set = Object.create(ApprovedIssuerSet.prototype) as ApprovedIssuerSet
+
+        set.tree = new LeanIMT<bigint>(internalNode, leaves.map(toFieldElement))
+
+        return set
+    }
+
+    /**
+     * Rebuilds a set from a deployed `ApprovedIssuerSet.sol`, paging through
+     * `getLeaves` so a large set never needs one unbounded call. Pages are
+     * fetched concurrently — the reader isn't block-pinned, so this is no
+     * weaker a read than the sequential form.
+     */
+    static async fromContract(reader: ContractLeafReader): Promise<ApprovedIssuerSet> {
+        const leafCount = Number(await reader.getLeafCount())
+
+        const ranges: [number, number][] = []
+        for (let start = 0; start < leafCount; start += FROM_CONTRACT_PAGE_SIZE) {
+            ranges.push([start, Math.min(start + FROM_CONTRACT_PAGE_SIZE, leafCount)])
+        }
+
+        const pages = await Promise.all(ranges.map(([start, end]) => reader.getLeaves(start, end)))
+
+        return ApprovedIssuerSet.fromLeaves(pages.flat())
+    }
+
+    /** Whether a witness is internally consistent with the root it carries, independent of any set. */
+    static verifyProof(proof: IssuerMembershipWitness): boolean {
+        if (proof.indices.length !== proof.siblings.length) return false
+
+        let packed = 0
+        for (let level = 0; level < proof.indices.length; level += 1) {
+            if (proof.indices[level]) packed |= 1 << level
+        }
+        if (packed !== proof.pathIndex) return false
+
+        return LeanIMT.verifyProof(
+            { root: proof.root, leaf: proof.leaf, index: proof.pathIndex, siblings: proof.siblings },
+            internalNode
+        )
+    }
+
+    /** Whether a signing key is currently approved. */
+    isApproved(publicKey: IssuerPublicKey): boolean {
+        return this.indexOf(publicKey) >= 0
+    }
+
+    /** The physical index of a currently approved key, or `-1`. */
+    indexOf(publicKey: IssuerPublicKey): number {
+        return this.tree.indexOf(issuerKeyLeaf(publicKey))
+    }
+
+    /**
+     * Publishes a signing key, appended at the next free slot.
+     * @returns The leaf commitment inserted.
+     * @throws if the key is off-curve, low-order, or already approved.
+     */
+    publish(publicKey: IssuerPublicKey): bigint {
+        const leaf = issuerKeyLeaf(toPublicKey(publicKey))
+
+        if (this.tree.has(leaf)) {
+            throw new Error("approved issuer set contains a duplicate key")
+        }
+
+        this.tree.insert(leaf)
+
+        return leaf
+    }
+
+    /**
+     * {@link publish}, for several keys in order. Each is checked against the
+     * ones already in this batch too, and the set is rebuilt once at the end
+     * rather than after every key.
+     * @throws if any key is invalid or a duplicate, leaving the set unchanged.
+     */
+    publishMany(publicKeys: IssuerPublicKey[]): bigint[] {
+        if (publicKeys.length === 0) return []
+
+        const leaves: bigint[] = []
+
+        for (const publicKey of publicKeys) {
+            const leaf = issuerKeyLeaf(toPublicKey(publicKey))
+
+            if (this.tree.has(leaf) || leaves.includes(leaf)) {
+                throw new Error("approved issuer set contains a duplicate key")
+            }
+
+            leaves.push(leaf)
+        }
+
+        this.tree.insertMany(leaves)
+
+        return leaves
+    }
+
+    /**
+     * Tombstones a key's slot to `0`, ending its ability to verify. The slot
+     * stays allocated; a republished key gets a new one.
+     * @throws if the key is off-curve, low-order, or not currently approved.
+     */
+    retire(publicKey: IssuerPublicKey): void {
+        const index = this.indexOf(toPublicKey(publicKey))
+        if (index < 0) throw new Error("credential issuer is not in the approved set")
+
+        this.tree.update(index, 0n)
+    }
+
+    /**
+     * Generates the membership witness the credential circuit consumes.
+     * @throws if the key is off-curve, low-order, or not currently approved.
+     */
+    generateProof(publicKey: IssuerPublicKey): IssuerMembershipWitness {
+        const leaf = issuerKeyLeaf(toPublicKey(publicKey))
+        const leafIndex = this.tree.indexOf(leaf)
+        if (leafIndex < 0) throw new Error("credential issuer is not in the approved set")
+
+        const proof = this.tree.generateProof(leafIndex)
+        const indices = Array.from({ length: proof.siblings.length }, (_, level) => ((proof.index >> level) & 1) === 1)
+
+        return { root: this.root, leafIndex, pathIndex: proof.index, siblings: proof.siblings, indices, leaf }
+    }
+
+    /** Instance form of {@link ApprovedIssuerSet.verifyProof}, additionally bound to this set's current root. */
+    verifyProof(proof: IssuerMembershipWitness): boolean {
+        return proof.root === this.root && ApprovedIssuerSet.verifyProof(proof)
+    }
+}

package/src/constants.ts

@@ -0,0 +1,26 @@
+/**
+ * The BN254 (alt_bn128) scalar field order. Every leaf and internal-node hash,
+ * and every signing-key coordinate, is an element of this field.
+ */
+export const SNARK_SCALAR_FIELD = 21888242871839275222246405745257275088548364400416034343698204186575808495617n
+
+/**
+ * Baby Jubjub's cofactor. A point has low order exactly when multiplying it by
+ * this gives the identity, which is what disqualifies a signing key: see
+ * `toPublicKey`.
+ */
+export const COFACTOR = 8n
+
+/**
+ * The tree's capacity bound: spec 03's construction and the circuit's
+ * `binary_merkle_root`. The tree's actual depth is dynamic; see
+ * `ApprovedIssuerSet.depth`.
+ */
+export const ISSUER_SET_MAX_DEPTH = 20
+
+/**
+ * Domain separator mixed into every leaf commitment, matching
+ * `IssuerSetHashes.ISSUER_LEAF_DOMAIN` in Solidity and `LEAF_DOMAIN` in the
+ * circuit.
+ */
+export const ISSUER_LEAF_DOMAIN = 185404551131306766954100762329350135288498146007932686448214248919067924295n

package/src/hashes.ts

@@ -0,0 +1,22 @@
+import { poseidon2 } from "poseidon-lite/poseidon2"
+import { poseidon3 } from "poseidon-lite/poseidon3"
+import { ISSUER_LEAF_DOMAIN } from "./constants"
+import type { IssuerPublicKey } from "./types"
+
+/**
+ * Commits a Baby Jubjub public key to the leaf value the tree stores for it.
+ * Matches `IssuerSetHashes.issuerKeyLeaf` in Solidity (`PoseidonT4`) and the
+ * leaf hash in `packages/circuits/src/issuer.nr`; all three must agree or a
+ * proof built against one never verifies against a root from another.
+ */
+export function issuerKeyLeaf(publicKey: IssuerPublicKey): bigint {
+    return poseidon3([ISSUER_LEAF_DOMAIN, publicKey[0], publicKey[1]])
+}
+
+/** Alias for the name `packages/credential`'s re-export carries forward. */
+export const issuerLeaf = issuerKeyLeaf
+
+/** Combines two child nodes into their parent. Matches `IssuerSetHashes.internalNode` (`PoseidonT3`). */
+export function internalNode(left: bigint, right: bigint): bigint {
+    return poseidon2([left, right])
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { ApprovedIssuerSet } from "./approved-issuer-set"
+export { COFACTOR, ISSUER_LEAF_DOMAIN, ISSUER_SET_MAX_DEPTH, SNARK_SCALAR_FIELD } from "./constants"
+export { internalNode, issuerKeyLeaf, issuerLeaf } from "./hashes"
+export type {
+    BigNumberish,
+    ContractLeafReader,
+    IssuerMembershipProof,
+    IssuerMembershipWitness,
+    IssuerPublicKey,
+    IssuerSet
+} from "./types"
+export { toFieldElement, toPublicKey } from "./utils"

package/src/types.ts

@@ -0,0 +1,52 @@
+/** Anything that can be coerced to a field element with `BigInt()`. */
+export type BigNumberish = bigint | number | string
+
+/** A Baby Jubjub public key in affine form, `[x, y]`. */
+export type IssuerPublicKey = [bigint, bigint]
+
+/**
+ * A membership proof for one signing key: a Merkle proof of a single leaf.
+ * Structurally identical to `packages/credential`'s type of the same name, so
+ * a re-export from there type-checks unchanged. `leafIndex` is the leaf's
+ * physical slot; `pathIndex` packs the direction bits of the levels actually
+ * present in `siblings` (promoted levels have no sibling and are absent), and
+ * is what the proof opens against `root` with.
+ */
+export interface IssuerMembershipProof {
+    root: bigint
+    leafIndex: number
+    pathIndex: number
+    siblings: bigint[]
+}
+
+/**
+ * `ApprovedIssuerSet.generateProof`'s actual return shape: a membership proof
+ * plus the per-level direction bits and the leaf itself, together enough to
+ * fold to `root` with no other context. `indices` covers only the levels
+ * `siblings` includes — `indices[i]` is bit `i` of `pathIndex` — the circuit's
+ * `binary_merkle_root` witness.
+ */
+export interface IssuerMembershipWitness extends IssuerMembershipProof {
+    indices: boolean[]
+    leaf: bigint
+}
+
+/**
+ * The structural interface `packages/credential` consumes: a root and a way
+ * to prove membership against it. `ApprovedIssuerSet` widens `generateProof`'s
+ * return type to {@link IssuerMembershipWitness}, which still satisfies this.
+ */
+export interface IssuerSet {
+    root: bigint
+    generateProof(publicKey: IssuerPublicKey): IssuerMembershipProof
+}
+
+/**
+ * The minimal read surface {@link ApprovedIssuerSet.fromContract} needs from
+ * a deployed `ApprovedIssuerSet.sol`. Structural, not a viem `Contract`
+ * instance, so this package carries no on-chain dependency.
+ */
+export interface ContractLeafReader {
+    getLeafCount(): Promise<bigint | number>
+    getLeaves(start: number, end: number): Promise<(bigint | string | number)[]>
+}

package/src/utils.ts

@@ -0,0 +1,65 @@
+import { inCurve, mulPointEscalar } from "@zk-kit/baby-jubjub"
+import { COFACTOR, SNARK_SCALAR_FIELD } from "./constants"
+import type { BigNumberish, IssuerPublicKey } from "./types"
+
+/**
+ * Coerces a value to a BN254 field element, rejecting anything outside the
+ * field.
+ *
+ * Every leaf and every hash the set produces must be a field element: outside
+ * that range two distinct values reduce to the same element, so one key's
+ * membership proof would open against another's leaf.
+ *
+ * Zero is accepted, because a tombstoned or never-written slot holds it.
+ *
+ * @param value The value, as a bigint, number or decimal string.
+ * @returns The value as a bigint.
+ */
+export function toFieldElement(value: BigNumberish): bigint {
+    const element = BigInt(value)
+
+    if (element < 0n) {
+        throw new Error("ApprovedIssuerSet: a field element must not be negative")
+    }
+
+    if (element >= SNARK_SCALAR_FIELD) {
+        throw new Error("ApprovedIssuerSet: a field element must be less than the SNARK scalar field order")
+    }
+
+    return element
+}
+
+/**
+ * Coerces a pair to a Baby Jubjub public key of full order, rejecting a point
+ * that is not on the curve or that lies in the small-order subgroup.
+ *
+ * The set would happily commit to any two field elements, so without the curve
+ * check a caller could publish a commitment to a point that does not exist.
+ *
+ * The order check matters more. Under a low-order public key `A` the term `h·A`
+ * in EdDSA verification takes at most eight values whatever the message, so
+ * anyone can solve `S·B = R + h·A` for a signature over a claim tree they chose;
+ * at the identity it is immediate. Publishing such a key would hand every
+ * stranger the member's issuing power. Mirrors the same rejection in
+ * `ApprovedIssuerSet.sol`.
+ *
+ * @param publicKey The signing key as `[x, y]`.
+ * @returns The key with both coordinates as bigints.
+ */
+export function toPublicKey(publicKey: IssuerPublicKey): [bigint, bigint] {
+    const point: [bigint, bigint] = [toFieldElement(publicKey[0]), toFieldElement(publicKey[1])]
+
+    if (!inCurve(point)) {
+        throw new Error("ApprovedIssuerSet: the public key is not a point on Baby Jubjub")
+    }
+
+    // A point has low order exactly when eight times it is the identity, the curve's cofactor being
+    // eight. That is the same set of eight points the contract rejects by x coordinate.
+    const [x, y] = mulPointEscalar(point, COFACTOR)
+
+    if (x === 0n && y === 1n) {
+        throw new Error("ApprovedIssuerSet: the public key has low order")
+    }
+
+    return point
+}

package/types/index.d.ts

@@ -0,0 +1,204 @@
+/** Anything that can be coerced to a field element with `BigInt()`. */
+type BigNumberish = bigint | number | string;
+/** A Baby Jubjub public key in affine form, `[x, y]`. */
+type IssuerPublicKey = [bigint, bigint];
+/**
+ * A membership proof for one signing key: a Merkle proof of a single leaf.
+ * Structurally identical to `packages/credential`'s type of the same name, so
+ * a re-export from there type-checks unchanged. `leafIndex` is the leaf's
+ * physical slot; `pathIndex` packs the direction bits of the levels actually
+ * present in `siblings` (promoted levels have no sibling and are absent), and
+ * is what the proof opens against `root` with.
+ */
+interface IssuerMembershipProof {
+    root: bigint;
+    leafIndex: number;
+    pathIndex: number;
+    siblings: bigint[];
+}
+/**
+ * `ApprovedIssuerSet.generateProof`'s actual return shape: a membership proof
+ * plus the per-level direction bits and the leaf itself, together enough to
+ * fold to `root` with no other context. `indices` covers only the levels
+ * `siblings` includes — `indices[i]` is bit `i` of `pathIndex` — the circuit's
+ * `binary_merkle_root` witness.
+ */
+interface IssuerMembershipWitness extends IssuerMembershipProof {
+    indices: boolean[];
+    leaf: bigint;
+}
+/**
+ * The structural interface `packages/credential` consumes: a root and a way
+ * to prove membership against it. `ApprovedIssuerSet` widens `generateProof`'s
+ * return type to {@link IssuerMembershipWitness}, which still satisfies this.
+ */
+interface IssuerSet {
+    root: bigint;
+    generateProof(publicKey: IssuerPublicKey): IssuerMembershipProof;
+}
+/**
+ * The minimal read surface {@link ApprovedIssuerSet.fromContract} needs from
+ * a deployed `ApprovedIssuerSet.sol`. Structural, not a viem `Contract`
+ * instance, so this package carries no on-chain dependency.
+ */
+interface ContractLeafReader {
+    getLeafCount(): Promise<bigint | number>;
+    getLeaves(start: number, end: number): Promise<(bigint | string | number)[]>;
+}
+
+/**
+ * The approved-issuer set: a LeanIMT accumulator, capped at depth
+ * {@link ISSUER_SET_MAX_DEPTH}, over network members' credential signing keys
+ * spec 03 defines, mirroring `ApprovedIssuerSet.sol`.
+ *
+ * A retired key's slot is tombstoned to `0` rather than removed, the same
+ * dense, append-only storage the contract keeps: `leafCount` never shrinks, so
+ * a slot's Merkle position never changes once assigned. A node with no right
+ * sibling is promoted unchanged rather than hashed against a zero, so the
+ * tree's depth tracks `ceil(log2(leafCount))` instead of staying fixed.
+ */
+declare class ApprovedIssuerSet implements IssuerSet {
+    private tree;
+    /**
+     * @param publicKeys The set's current signing keys, in order. Not
+     * curve-validated: this bulk-load path mirrors an already-validated
+     * on-chain state, unlike {@link publish}.
+     */
+    constructor(publicKeys: IssuerPublicKey[]);
+    /** The current root. Never `undefined`: both constructors require at least one slot. */
+    get root(): bigint;
+    /** The number of physical leaf slots, including tombstoned ones. Never decreases. */
+    get leafCount(): number;
+    /** The number of currently approved (non-tombstoned) keys. */
+    get size(): number;
+    /** `ceil(log2(leafCount))`, 0 for a one-slot set. Grows as slots are added; never shrinks. */
+    get depth(): number;
+    /** Every physical slot, in order, `0` for a tombstone. A copy: mutate through {@link publish}/{@link retire}. */
+    get leafSlots(): bigint[];
+    /** The leaf a key would occupy, without publishing it. */
+    static leafOf(publicKey: IssuerPublicKey): bigint;
+    /**
+     * Rebuilds a set from the physical slot table a holder reads with
+     * `ApprovedIssuerSet.getLeaves` — the private path that never asks the
+     * chain which leaf it holds a witness for (see the contract's
+     * `siblingsOf` natspec).
+     *
+     * @param leaves Every slot, in physical order, `0` for a tombstone.
+     * @throws if `leaves` is empty. A drained set (every slot tombstoned) is
+     * a valid, nonzero-length input; the on-chain analogue is `leafCount`
+     * being monotonic, so a set that has ever published a key is never truly
+     * empty again.
+     */
+    static fromLeaves(leaves: BigNumberish[]): ApprovedIssuerSet;
+    /**
+     * Rebuilds a set from a deployed `ApprovedIssuerSet.sol`, paging through
+     * `getLeaves` so a large set never needs one unbounded call. Pages are
+     * fetched concurrently — the reader isn't block-pinned, so this is no
+     * weaker a read than the sequential form.
+     */
+    static fromContract(reader: ContractLeafReader): Promise<ApprovedIssuerSet>;
+    /** Whether a witness is internally consistent with the root it carries, independent of any set. */
+    static verifyProof(proof: IssuerMembershipWitness): boolean;
+    /** Whether a signing key is currently approved. */
+    isApproved(publicKey: IssuerPublicKey): boolean;
+    /** The physical index of a currently approved key, or `-1`. */
+    indexOf(publicKey: IssuerPublicKey): number;
+    /**
+     * Publishes a signing key, appended at the next free slot.
+     * @returns The leaf commitment inserted.
+     * @throws if the key is off-curve, low-order, or already approved.
+     */
+    publish(publicKey: IssuerPublicKey): bigint;
+    /**
+     * {@link publish}, for several keys in order. Each is checked against the
+     * ones already in this batch too, and the set is rebuilt once at the end
+     * rather than after every key.
+     * @throws if any key is invalid or a duplicate, leaving the set unchanged.
+     */
+    publishMany(publicKeys: IssuerPublicKey[]): bigint[];
+    /**
+     * Tombstones a key's slot to `0`, ending its ability to verify. The slot
+     * stays allocated; a republished key gets a new one.
+     * @throws if the key is off-curve, low-order, or not currently approved.
+     */
+    retire(publicKey: IssuerPublicKey): void;
+    /**
+     * Generates the membership witness the credential circuit consumes.
+     * @throws if the key is off-curve, low-order, or not currently approved.
+     */
+    generateProof(publicKey: IssuerPublicKey): IssuerMembershipWitness;
+    /** Instance form of {@link ApprovedIssuerSet.verifyProof}, additionally bound to this set's current root. */
+    verifyProof(proof: IssuerMembershipWitness): boolean;
+}
+
+/**
+ * The BN254 (alt_bn128) scalar field order. Every leaf and internal-node hash,
+ * and every signing-key coordinate, is an element of this field.
+ */
+declare const SNARK_SCALAR_FIELD = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+/**
+ * Baby Jubjub's cofactor. A point has low order exactly when multiplying it by
+ * this gives the identity, which is what disqualifies a signing key: see
+ * `toPublicKey`.
+ */
+declare const COFACTOR = 8n;
+/**
+ * The tree's capacity bound: spec 03's construction and the circuit's
+ * `binary_merkle_root`. The tree's actual depth is dynamic; see
+ * `ApprovedIssuerSet.depth`.
+ */
+declare const ISSUER_SET_MAX_DEPTH = 20;
+/**
+ * Domain separator mixed into every leaf commitment, matching
+ * `IssuerSetHashes.ISSUER_LEAF_DOMAIN` in Solidity and `LEAF_DOMAIN` in the
+ * circuit.
+ */
+declare const ISSUER_LEAF_DOMAIN = 185404551131306766954100762329350135288498146007932686448214248919067924295n;
+
+/**
+ * Commits a Baby Jubjub public key to the leaf value the tree stores for it.
+ * Matches `IssuerSetHashes.issuerKeyLeaf` in Solidity (`PoseidonT4`) and the
+ * leaf hash in `packages/circuits/src/issuer.nr`; all three must agree or a
+ * proof built against one never verifies against a root from another.
+ */
+declare function issuerKeyLeaf(publicKey: IssuerPublicKey): bigint;
+/** Alias for the name `packages/credential`'s re-export carries forward. */
+declare const issuerLeaf: typeof issuerKeyLeaf;
+/** Combines two child nodes into their parent. Matches `IssuerSetHashes.internalNode` (`PoseidonT3`). */
+declare function internalNode(left: bigint, right: bigint): bigint;
+
+/**
+ * Coerces a value to a BN254 field element, rejecting anything outside the
+ * field.
+ *
+ * Every leaf and every hash the set produces must be a field element: outside
+ * that range two distinct values reduce to the same element, so one key's
+ * membership proof would open against another's leaf.
+ *
+ * Zero is accepted, because a tombstoned or never-written slot holds it.
+ *
+ * @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 pair to a Baby Jubjub public key of full order, rejecting a point
+ * that is not on the curve or that lies in the small-order subgroup.
+ *
+ * The set would happily commit to any two field elements, so without the curve
+ * check a caller could publish a commitment to a point that does not exist.
+ *
+ * The order check matters more. Under a low-order public key `A` the term `h·A`
+ * in EdDSA verification takes at most eight values whatever the message, so
+ * anyone can solve `S·B = R + h·A` for a signature over a claim tree they chose;
+ * at the identity it is immediate. Publishing such a key would hand every
+ * stranger the member's issuing power. Mirrors the same rejection in
+ * `ApprovedIssuerSet.sol`.
+ *
+ * @param publicKey The signing key as `[x, y]`.
+ * @returns The key with both coordinates as bigints.
+ */
+declare function toPublicKey(publicKey: IssuerPublicKey): [bigint, bigint];
+
+export { ApprovedIssuerSet, COFACTOR, ISSUER_LEAF_DOMAIN, ISSUER_SET_MAX_DEPTH, SNARK_SCALAR_FIELD, internalNode, issuerKeyLeaf, issuerLeaf, toFieldElement, toPublicKey };
+export type { BigNumberish, ContractLeafReader, IssuerMembershipProof, IssuerMembershipWitness, IssuerPublicKey, IssuerSet };