@zkproofport-app/sdk 0.2.11 → 0.2.13

package/dist/index.mjs

@@ -51,20 +51,26 @@ const DEEP_LINK_HOSTS = {
  * ```typescript
  * const metadata = CIRCUIT_METADATA['coinbase_attestation'];
  * console.log(metadata.name); // "Coinbase KYC"
- * console.log(metadata.publicInputsCount); // 2
+ * console.log(metadata.publicInputsCount); // 128
  * ```
  */
 const CIRCUIT_METADATA = {
     coinbase_attestation: {
         name: 'Coinbase KYC',
         description: 'Prove Coinbase identity verification',
-        publicInputsCount: 2,
+        // 4 x `pub [u8; 32]` in coinbase-attestation/src/main.nr, flattened to
+        // bytes: signal_hash, signer_list_merkle_root, scope, nullifier.
+        // Read 2 here until 2026-09-04, which was wrong under any reading —
+        // the circuit has never had two public inputs, logical or flattened.
+        publicInputsCount: 128,
         publicInputNames: ['signal_hash', 'signer_list_merkle_root'],
     },
     coinbase_country_attestation: {
         name: 'Coinbase Country',
         description: 'Prove Coinbase country verification',
-        publicInputsCount: 14,
+        // 32 + 32 + (10 x 2) + 1 + 1 + 32 + 32 = 150, counted off
+        // coinbase-country-attestation/src/main.nr. Read 14 until 2026-09-04.
+        publicInputsCount: 150,
         publicInputNames: ['signal_hash', 'signer_list_merkle_root', 'country_list', 'country_list_length', 'is_included'],
     },
     oidc_domain_attestation: {
@@ -73,8 +79,22 @@ const CIRCUIT_METADATA = {
         publicInputsCount: 148,
         publicInputNames: ['pubkey_modulus_limbs', 'domain', 'scope', 'nullifier', 'provider'],
     },
-    // Korea Mobile ID (mDL) circuits. Counts are byte-flattened field totals
-    // from the compiled circuit ABIs: [u8; 32] arrays contribute 32 inputs each.
+    // Planned circuit — the identifier is reserved and the circuit exists, but it
+    // is not officially supported yet. See CIRCUIT_SUPPORT_STATUS in ./circuits.
+    // Forked from coinbase_attestation and shares its four public inputs, so the
+    // count is the byte-flattened total (4 x [u8; 32] = 128), matching the
+    // COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT indices below. The
+    // coinbase_attestation entry above reports a legacy logical count of 2 and is
+    // left as-is for backwards compatibility.
+    giwa_attestation: {
+        name: 'GIWA Attestation',
+        description: 'Prove GIWA identity verification (planned — not officially supported yet)',
+        publicInputsCount: 128,
+        publicInputNames: ['signal_hash', 'signer_list_merkle_root', 'scope', 'nullifier'],
+    },
+    // Korea Mobile ID (mDL) circuits. Planned — not officially supported yet.
+    // Counts are byte-flattened field totals from the compiled circuit ABIs:
+    // [u8; 32] arrays contribute 32 inputs each.
     mdl_kr_ownership: {
         name: 'Korea Mobile ID — Ownership',
         description: "Prove valid Korean mobile driver's license ownership with selective disclosure",
@@ -118,6 +138,13 @@ const VERIFIER_ABI = [
  * Supported networks:
  * - 84532: Base Sepolia (testnet)
  * - 8453: Base Mainnet (production)
+ * - 91342: GIWA Sepolia (testnet) — where the GIWA account circuit verifies
+ *
+ * A chain missing from this map is not a quiet degradation: `getDefaultProvider`
+ * throws "No RPC endpoint configured for chain N". That is what a caller saw
+ * when verifying a GIWA proof on chain 91342 — the verifier contract had been
+ * deployed and the proof was valid, but the SDK had no way to reach the chain
+ * to ask. Deploying a verifier to a new network means adding it here too.
  *
  * @example
  * ```typescript
@@ -129,6 +156,7 @@ const VERIFIER_ABI = [
 const RPC_ENDPOINTS = {
     84532: 'https://sepolia.base.org', // Base Sepolia
     8453: 'https://mainnet.base.org', // Base Mainnet
+    91342: 'https://sepolia-rpc.giwa.io', // GIWA Sepolia
 };
 /**
  * Default proof request expiration time in milliseconds.
@@ -4234,6 +4262,383 @@ function reconstructBytes32FromFields(fields) {
     return '0x' + bytes;
 }
 
+/**
+ * Canonical ZKProofport circuit identifiers.
+ *
+ * This module is the single source of truth for circuit IDs. Every other layer
+ * — the mobile app, the demo, the relay, server-side provers — reads its list
+ * from here instead of keeping a private copy that silently drifts.
+ *
+ * It has **no imports and no dependencies**, so it can be pulled in on its own:
+ *
+ * ```typescript
+ * import { CIRCUIT_IDS, isCircuitId } from '@zkproofport-app/sdk/circuits';
+ * ```
+ *
+ * The same names are also re-exported from the package root
+ * (`@zkproofport-app/sdk`) for callers that already import the SDK.
+ *
+ * ## Identifiers are canonical and case-sensitive
+ *
+ * Each ID is the circuit's `name` in its `Nargo.toml`, verbatim. The format is
+ * lowercase with underscores. Hyphenated spellings (`coinbase-kyc`,
+ * `mdl-kr-age`) are directory or UI route names in other repositories — they
+ * are **not** circuit IDs, and passing one produces a nullifier mismatch or a
+ * failed on-chain lookup rather than a clear error.
+ */
+/**
+ * Canonical circuit identifiers, keyed by a stable constant name.
+ *
+ * Prefer these constants over string literals so a rename is a compile error
+ * rather than a runtime surprise.
+ *
+ * @example
+ * ```typescript
+ * import { CIRCUIT_IDS } from '@zkproofport-app/sdk/circuits';
+ *
+ * const relay = await sdk.createRelayRequest(CIRCUIT_IDS.COINBASE_ATTESTATION, {
+ *   scope: 'myapp.com',
+ * });
+ * ```
+ */
+const CIRCUIT_IDS = Object.freeze({
+    /** Coinbase KYC attestation. Officially supported. */
+    COINBASE_ATTESTATION: 'coinbase_attestation',
+    /** Coinbase country attestation (inclusion / exclusion). Officially supported. */
+    COINBASE_COUNTRY_ATTESTATION: 'coinbase_country_attestation',
+    /** OIDC email-domain attestation. Officially supported. */
+    OIDC_DOMAIN_ATTESTATION: 'oidc_domain_attestation',
+    /** GIWA attestation. Planned — not officially supported yet. */
+    GIWA_ATTESTATION: 'giwa_attestation',
+    /** Korea Mobile ID ownership. Planned — not officially supported yet. */
+    MDL_KR_OWNERSHIP: 'mdl_kr_ownership',
+    /** Korea Mobile ID age threshold. Planned — not officially supported yet. */
+    MDL_KR_AGE: 'mdl_kr_age',
+    /** Korea Mobile ID si/do region. Planned — not officially supported yet. */
+    MDL_KR_REGION: 'mdl_kr_region',
+});
+/**
+ * Support status for every circuit.
+ *
+ * The record is exhaustive over {@link CircuitId}: adding an identifier without
+ * giving it a status is a compile error, so this list cannot drift from
+ * {@link CIRCUIT_IDS}.
+ *
+ * @example
+ * ```typescript
+ * import { CIRCUIT_SUPPORT_STATUS } from '@zkproofport-app/sdk/circuits';
+ *
+ * CIRCUIT_SUPPORT_STATUS.coinbase_attestation; // 'supported'
+ * CIRCUIT_SUPPORT_STATUS.mdl_kr_age;           // 'planned'
+ * ```
+ */
+const CIRCUIT_SUPPORT_STATUS = Object.freeze({
+    coinbase_attestation: 'supported',
+    coinbase_country_attestation: 'supported',
+    oidc_domain_attestation: 'supported',
+    giwa_attestation: 'planned',
+    mdl_kr_ownership: 'planned',
+    mdl_kr_age: 'planned',
+    mdl_kr_region: 'planned',
+});
+/**
+ * Where each circuit's verification key lives inside the `zkproofport/circuits`
+ * repository, relative to its root.
+ *
+ * Off-chain verification needs the verification key and nothing else — no
+ * circuit bytecode, no witness. The key is public by nature: it is what anyone
+ * checking a proof must already have, and the Solidity verifiers deployed
+ * on-chain embed the same key.
+ *
+ * Exhaustive over {@link CircuitId} on purpose. A new circuit whose key path is
+ * not listed here fails to compile rather than failing at verification time,
+ * where the only symptom would be a proof that cannot be checked.
+ */
+const CIRCUIT_VK_PATHS = Object.freeze({
+    coinbase_attestation: 'coinbase-attestation/target/vk',
+    coinbase_country_attestation: 'coinbase-country-attestation/target/vk',
+    oidc_domain_attestation: 'oidc-domain-attestation/target/vk',
+    giwa_attestation: 'giwa-attestation/target/vk',
+    mdl_kr_ownership: 'mdl/kr-ownership/target/vk',
+    mdl_kr_age: 'mdl/kr-age/target/vk',
+    mdl_kr_region: 'mdl/kr-region/target/vk',
+});
+/**
+ * Every canonical circuit identifier, in declaration order.
+ *
+ * Includes circuits that are still `planned`. Use {@link SUPPORTED_CIRCUIT_IDS}
+ * when you only want the ones that are officially supported today.
+ */
+const ALL_CIRCUIT_IDS = Object.freeze(Object.values(CIRCUIT_IDS));
+/**
+ * Circuits that are officially supported today: the two Coinbase circuits and
+ * OIDC domain attestation.
+ *
+ * Derived from {@link CIRCUIT_SUPPORT_STATUS}, so it cannot fall out of sync.
+ */
+const SUPPORTED_CIRCUIT_IDS = Object.freeze(ALL_CIRCUIT_IDS.filter((id) => CIRCUIT_SUPPORT_STATUS[id] === 'supported'));
+/**
+ * Circuits whose identifiers are reserved but which are not officially
+ * supported yet: GIWA attestation and the three Korea Mobile ID circuits.
+ *
+ * Derived from {@link CIRCUIT_SUPPORT_STATUS}, so it cannot fall out of sync.
+ */
+const PLANNED_CIRCUIT_IDS = Object.freeze(ALL_CIRCUIT_IDS.filter((id) => CIRCUIT_SUPPORT_STATUS[id] === 'planned'));
+/**
+ * Narrows an unknown value to a canonical circuit identifier.
+ *
+ * Returns `false` for hyphenated route names such as `'coinbase-kyc'`, which
+ * are not circuit IDs.
+ *
+ * @example
+ * ```typescript
+ * isCircuitId('coinbase_attestation'); // true
+ * isCircuitId('coinbase-kyc');         // false
+ * ```
+ */
+function isCircuitId(value) {
+    return typeof value === 'string' && ALL_CIRCUIT_IDS.includes(value);
+}
+/**
+ * Narrows an unknown value to a circuit identifier that is officially supported
+ * today. Planned circuits return `false`.
+ *
+ * @example
+ * ```typescript
+ * isSupportedCircuitId('oidc_domain_attestation'); // true
+ * isSupportedCircuitId('mdl_kr_age');              // false — planned
+ * ```
+ */
+function isSupportedCircuitId(value) {
+    return isCircuitId(value) && CIRCUIT_SUPPORT_STATUS[value] === 'supported';
+}
+/**
+ * Returns the support status of a circuit.
+ *
+ * @param circuit - A canonical circuit identifier.
+ * @throws Error when the value is not a canonical circuit identifier.
+ *
+ * @example
+ * ```typescript
+ * getCircuitSupportStatus('giwa_attestation'); // 'planned'
+ * ```
+ */
+function getCircuitSupportStatus(circuit) {
+    if (!isCircuitId(circuit)) {
+        throw new Error(`Unknown circuit '${String(circuit)}'. Expected one of: ${ALL_CIRCUIT_IDS.join(', ')}`);
+    }
+    return CIRCUIT_SUPPORT_STATUS[circuit];
+}
+
+/**
+ * Off-chain proof verification — checking a proof against its verification key,
+ * with no chain, no RPC, and no gas.
+ *
+ * WHY THIS EXISTS. The SDK had only `verifyProofOnChain`, and every caller that
+ * wanted an off-chain check called that instead and relabelled the result. The
+ * demo page did exactly this from its first commit: pressing "Off-Chain Verify"
+ * ran an on-chain verification and printed "Off-Chain Verification Passed!".
+ * The answer was true and the label was a lie, which is the worst combination —
+ * nothing looked broken. The mobile app has always verified off-chain properly
+ * (through mopro's native Barretenberg); it was only the JavaScript side that
+ * had no such thing.
+ *
+ * HOW IT WORKS. `bb` proofs are checked by `acirVerifyUltraKeccakHonk(proof,
+ * vk)` — the keccak variant, matching how these proofs are produced. Two things
+ * have to line up:
+ *
+ *   The version. The verification key format is not stable across bb releases:
+ *   the pinned build emits a 1816-byte key where bb 0.87.0 and 1.2.0 emit 1760.
+ *   `@aztec/bb.js@1.0.0-nightly.20250723` is the WASM build of the same bb the
+ *   circuits were compiled with. A different one will reject valid proofs.
+ *
+ *   The oracle hash. Proofs are generated with `--oracle_hash keccak` so the
+ *   Solidity verifiers can check them, so the poseidon-flavoured verify — which
+ *   is what `BarretenbergVerifier.verifyUltraHonkProof` uses — says false for a
+ *   perfectly good proof.
+ *
+ * THE PROOF ARRIVES IN TWO PIECES. The mobile app splits what Barretenberg
+ * produced into `proof` and `publicInputs` before sending it, because the
+ * Solidity verifier takes them separately. Verifying needs them joined back, in
+ * that order, which is what `reconstructHonkProof` does.
+ */
+/**
+ * Where verification keys are published.
+ *
+ * Not configurable, deliberately: a caller who could point this somewhere else
+ * could point it at a key of their choosing, and "the proof verified" would
+ * then mean nothing. Same repository the mobile app downloads circuit data
+ * from.
+ */
+const CIRCUITS_VK_BASE = 'https://raw.githubusercontent.com/zkproofport/circuits/main';
+/** How long a fetched verification key is reused. Keys change only on a recompile. */
+const VK_CACHE_TTL_MS = 60 * 60 * 1000;
+const vkCache = new Map();
+/** @internal Hex string (with or without 0x) to bytes. */
+function hexToBytes(hex) {
+    const clean = hex.startsWith('0x') || hex.startsWith('0X') ? hex.slice(2) : hex;
+    if (clean.length === 0)
+        return new Uint8Array(0);
+    if (clean.length % 2 !== 0) {
+        throw new Error(`Hex string has an odd length (${clean.length}); it cannot be bytes`);
+    }
+    if (!/^[0-9a-fA-F]*$/.test(clean)) {
+        throw new Error('Hex string contains non-hex characters');
+    }
+    const out = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(clean.substr(i * 2, 2), 16);
+    }
+    return out;
+}
+/**
+ * @internal Public inputs as the flat byte run Barretenberg expects: each one a
+ * 32-byte big-endian field element, concatenated in order.
+ *
+ * The relay carries them as hex strings that are USUALLY already 32 bytes, but
+ * a value that happens to have leading zeros can arrive short (`0x01`). Left-
+ * padding here rather than trusting the sender is the difference between a
+ * verification that works and one that fails on roughly one proof in a hundred,
+ * for no reason the caller can see.
+ */
+function packPublicInputs(publicInputs) {
+    const out = new Uint8Array(publicInputs.length * 32);
+    publicInputs.forEach((input, i) => {
+        const bytes = hexToBytes(input);
+        if (bytes.length > 32) {
+            throw new Error(`Public input ${i} is ${bytes.length} bytes; a field element is at most 32`);
+        }
+        out.set(bytes, i * 32 + (32 - bytes.length));
+    });
+    return out;
+}
+/**
+ * Fetch a circuit's verification key, with a small cache.
+ *
+ * @internal
+ */
+async function fetchVerificationKey(circuit, timeoutMs) {
+    const cached = vkCache.get(circuit);
+    if (cached && Date.now() - cached.at < VK_CACHE_TTL_MS)
+        return cached.vk;
+    const vkPath = CIRCUIT_VK_PATHS[circuit];
+    if (!vkPath) {
+        throw new Error(`No verification key path for circuit '${circuit}'. ` +
+            `Add it to CIRCUIT_VK_PATHS, or pass verificationKey directly.`);
+    }
+    const url = `${CIRCUITS_VK_BASE}/${vkPath}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const resp = await fetch(url, { signal: controller.signal });
+        if (!resp.ok) {
+            throw new Error(`Could not fetch the verification key (HTTP ${resp.status}) from ${url}`);
+        }
+        const vk = new Uint8Array(await resp.arrayBuffer());
+        // A 404 page or an HTML redirect arrives as a successful response full of
+        // text, and would reach Barretenberg as a "verification key" that fails for
+        // reasons no one could guess from the message.
+        if (vk.length < 512) {
+            throw new Error(`The verification key at ${url} is ${vk.length} bytes, far too small to be one. ` +
+                `The path is probably wrong and something else was served.`);
+        }
+        vkCache.set(circuit, { vk, at: Date.now() });
+        return vk;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Verify a proof off-chain, against its verification key.
+ *
+ * Needs `@aztec/bb.js` at the pinned version. It is an optional peer dependency
+ * — the WASM is large and most callers verify on-chain — so the failure to have
+ * it installed says so plainly rather than surfacing as a module-not-found.
+ *
+ * @param circuit - Canonical circuit identifier
+ * @param proof - Proof bytes as hex, WITHOUT public inputs (as the relay sends it)
+ * @param publicInputs - Public inputs as hex strings, in circuit order
+ * @param options - Optional verification key and timeout
+ * @returns `{ valid }`, or `{ valid: false, error }` when the check could not run
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyProofOffChain(
+ *   'coinbase_attestation',
+ *   response.proof,
+ *   response.publicInputs
+ * );
+ * if (result.valid) console.log('Proof is valid, no chain involved');
+ * ```
+ */
+async function verifyProofOffChain(circuit, proof, publicInputs, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 30000;
+    let bb;
+    try {
+        bb = await import('@aztec/bb.js');
+    }
+    catch {
+        return {
+            valid: false,
+            error: 'Off-chain verification needs @aztec/bb.js. Install the pinned version: ' +
+                'npm install @aztec/bb.js@1.0.0-nightly.20250723',
+        };
+    }
+    let api;
+    try {
+        const proofBytes = hexToBytes(proof);
+        if (proofBytes.length === 0) {
+            return { valid: false, error: 'Proof is empty' };
+        }
+        const publicInputBytes = packPublicInputs(publicInputs);
+        const vk = options.verificationKey ?? (await fetchVerificationKey(circuit, timeoutMs));
+        // Public inputs first, then the proof — the order Barretenberg wrote them in
+        // before the mobile app split them apart for the Solidity verifier.
+        const full = bb.reconstructHonkProof(publicInputBytes, proofBytes);
+        api = (await bb.Barretenberg.new({ threads: 1 }));
+        // THE VERIFY MUST MATCH HOW THE PROOF WAS MADE, AND THERE ARE FOUR OF THEM.
+        //
+        // `scripts/build.sh` in the circuits repo proves with `--oracle_hash keccak`
+        // and ZK on — so the only entry point that answers correctly is the one that
+        // is BOTH. Measured against a real proof of the Korea Mobile ID age circuit,
+        // freshly generated against its own key:
+        //
+        //   acirVerifyUltraKeccakZkHonk    true     ← the right one
+        //   acirVerifyUltraKeccakHonk      TRAPS with a bare "unreachable"
+        //   acirVerifyUltraZKHonk          false    (poseidon: wrong oracle hash)
+        //
+        // The middle row is why this took a while: picking keccak-without-ZK does
+        // not return false, it kills the WebAssembly instance with a message that
+        // names nothing. It looks identical to a malformed proof, to a mismatched
+        // key, and to a missing SRS.
+        //
+        // Two more things that produce that same trap, both required:
+        //   initSRSForCircuitSize must be called before the first verify.
+        //   The key must be a RawBuffer — a plain Uint8Array is marshalled as a
+        //   length-prefixed vector, so its length is read as key material.
+        // Both are what bb.js's own BarretenbergVerifier does before verifying.
+        await api.initSRSForCircuitSize(0);
+        const valid = await api.acirVerifyUltraKeccakZkHonk(full, new bb.RawBuffer(vk));
+        return { valid };
+    }
+    catch (error) {
+        return { valid: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        // The WASM instance holds worker threads; leaving them running keeps a Node
+        // process alive after the check is done.
+        if (api) {
+            try {
+                await api.destroy();
+            }
+            catch {
+                /* nothing useful to do if teardown fails */
+            }
+        }
+    }
+}
+
 /**
  * Proofport SDK - Main class
  */
@@ -4880,6 +5285,38 @@ class ProofportSDK {
         };
         return verifyProofOnChain(response.circuit, parsedProof, providerOrSigner, customVerifier, responseVerifier);
     }
+    /**
+     * Verifies a proof response off-chain, against the circuit's verification key.
+     *
+     * No chain, no RPC, no gas, and no verifier contract — so this works for a
+     * circuit whose verifier has not been deployed anywhere, and it does not
+     * depend on a network being reachable. What it does not give you is the
+     * chain's own opinion: use {@link verifyResponseOnChain} when the answer has
+     * to be one a contract will agree with.
+     *
+     * Requires the optional peer dependency:
+     * `npm install @aztec/bb.js@1.0.0-nightly.20250723`. The version is exact —
+     * verification keys are not portable across bb releases, so a different build
+     * rejects valid proofs.
+     *
+     * @param response - Proof response from the relay
+     * @param options - Optional verification key (skips the fetch) and timeout
+     * @returns `{ valid }`, or `{ valid: false, error }` if the check could not run
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.verifyResponseOffChain(response);
+     * if (result.valid) {
+     *   console.log('Valid, and nothing was asked of any chain');
+     * }
+     * ```
+     */
+    async verifyResponseOffChain(response, options) {
+        if (response.status !== 'completed' || !response.proof || !response.publicInputs) {
+            return { valid: false, error: 'Invalid or incomplete response' };
+        }
+        return verifyProofOffChain(response.circuit, response.proof, response.publicInputs, options);
+    }
     // ============ Utility Methods ============
     /**
      * Gets the deployed verifier contract address for a circuit.
@@ -5553,5 +5990,5 @@ ProofportSDK.WALLET_SIGNATURE_CIRCUITS = [
     'coinbase_country_attestation',
 ];
 
-export { COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, MDL_KR_PUBLIC_INPUT_LAYOUT, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, ProofportSDK, ProofportSDK as default, extractDomainFromPublicInputs, extractNullifierFromPublicInputs, extractScopeFromPublicInputs };
+export { ALL_CIRCUIT_IDS, CIRCUIT_IDS, CIRCUIT_SUPPORT_STATUS, CIRCUIT_VK_PATHS, COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, MDL_KR_PUBLIC_INPUT_LAYOUT, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, PLANNED_CIRCUIT_IDS, ProofportSDK, SUPPORTED_CIRCUIT_IDS, ProofportSDK as default, extractDomainFromPublicInputs, extractNullifierFromPublicInputs, extractScopeFromPublicInputs, getCircuitSupportStatus, isCircuitId, isSupportedCircuitId, verifyProofOffChain };
 //# sourceMappingURL=index.mjs.map