@zkproofport-app/sdk 0.2.11 → 0.2.13

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@zkproofport-app/sdk)](https://www.npmjs.com/package/@zkproofport-app/sdk)
 [![license](https://img.shields.io/npm/l/@zkproofport-app/sdk)](./LICENSE)
 
-TypeScript SDK for requesting zero-knowledge proofs from the [ZKProofport](https://zkproofport.com) mobile app and verifying them on-chain. Six circuits are supported: Coinbase KYC and country attestations, OIDC email-domain attestations (Google, Microsoft 365), and the three Korean mobile ID (mDL) circuits.
+TypeScript SDK for requesting zero-knowledge proofs from the [ZKProofport](https://zkproofport.com) mobile app and verifying them on-chain. Three circuits are officially supported today — Coinbase KYC, Coinbase country attestation, and OIDC email-domain attestation (Google, Microsoft 365). Four more identifiers are reserved and planned: GIWA attestation and the three Korean mobile ID (mDL) circuits. [Circuit Identifiers](#circuit-identifiers) has the full list and what each status means.
 
 ## How It Works
 
@@ -97,9 +97,73 @@ if (result.status === 'completed') {
 }
 ```
 
+## Circuit Identifiers
+
+Circuit IDs are canonical, lowercase and case-sensitive: each one is the `name` field of that circuit's `Nargo.toml`, verbatim. Hyphenated spellings such as `coinbase-kyc` or `mdl-kr-age` are route and directory names from elsewhere — they are not circuit IDs, and passing one does not fail with a clear error. It produces a nullifier mismatch or a verifier lookup that finds nothing.
+
+This SDK is the single source of truth for that list. Import the constants rather than typing the strings, and a rename becomes a compile error instead of a runtime surprise:
+
+```typescript
+import { CIRCUIT_IDS } from '@zkproofport-app/sdk';
+
+const relay = await sdk.createRelayRequest(CIRCUIT_IDS.COINBASE_ATTESTATION, {
+  scope: 'myapp.com',
+});
+```
+
+The same names are also published on their own subpath, which holds nothing but the list — no `ethers`, no `socket.io-client`, no SDK code. A server, a worker or a build script can read it without pulling the SDK in:
+
+```typescript
+import { CIRCUIT_IDS, CIRCUIT_SUPPORT_STATUS } from '@zkproofport-app/sdk/circuits';
+```
+
+### Status
+
+| Constant | Circuit ID | Status |
+|----------|-----------|--------|
+| `CIRCUIT_IDS.COINBASE_ATTESTATION` | `coinbase_attestation` | **Supported** |
+| `CIRCUIT_IDS.COINBASE_COUNTRY_ATTESTATION` | `coinbase_country_attestation` | **Supported** |
+| `CIRCUIT_IDS.OIDC_DOMAIN_ATTESTATION` | `oidc_domain_attestation` | **Supported** |
+| `CIRCUIT_IDS.GIWA_ATTESTATION` | `giwa_attestation` | Planned |
+| `CIRCUIT_IDS.MDL_KR_OWNERSHIP` | `mdl_kr_ownership` | Planned |
+| `CIRCUIT_IDS.MDL_KR_AGE` | `mdl_kr_age` | Planned |
+| `CIRCUIT_IDS.MDL_KR_REGION` | `mdl_kr_region` | Planned |
+
+**Supported** means generally available — build a product on it. **Planned** means the identifier is reserved and the circuit exists, but it is not officially supported yet: availability, inputs and public-input layout can change without a major version bump.
+
+Every ID appears in `CircuitType` and in `sdk.getSupportedCircuits()`, planned ones included, so being assignable is not a support guarantee. Gate on the status, not on the type:
+
+```typescript
+import { CIRCUIT_SUPPORT_STATUS, isSupportedCircuitId } from '@zkproofport-app/sdk';
+
+CIRCUIT_SUPPORT_STATUS.coinbase_attestation; // 'supported'
+CIRCUIT_SUPPORT_STATUS.mdl_kr_age;           // 'planned'
+
+isSupportedCircuitId('oidc_domain_attestation'); // true
+isSupportedCircuitId('mdl_kr_age');              // false
+isSupportedCircuitId('coinbase-kyc');            // false — not an ID at all
+```
+
+### Exports
+
+| Export | Type | What it is |
+|--------|------|------------|
+| `CIRCUIT_IDS` | object | Every canonical ID, keyed by a stable constant name |
+| `ALL_CIRCUIT_IDS` | `readonly CircuitId[]` | Every ID, in the order of the table above |
+| `SUPPORTED_CIRCUIT_IDS` | `readonly CircuitId[]` | Only the officially supported ones |
+| `PLANNED_CIRCUIT_IDS` | `readonly CircuitId[]` | Only the planned ones |
+| `CIRCUIT_SUPPORT_STATUS` | `Readonly<Record<CircuitId, CircuitSupportStatus>>` | The status of each circuit |
+| `isCircuitId(value)` | `value is CircuitId` | Narrows an unknown value; `false` for hyphenated names |
+| `isSupportedCircuitId(value)` | `value is CircuitId` | The same, and additionally requires `supported` |
+| `getCircuitSupportStatus(id)` | `CircuitSupportStatus` | Status of one ID; throws on an unknown one |
+| `CircuitId` | type | Union of the seven IDs. `CircuitType` is an alias of it |
+| `CircuitSupportStatus` | type | `'supported' \| 'planned'` |
+
+Both objects and all three arrays are frozen. `ALL_CIRCUIT_IDS`, `SUPPORTED_CIRCUIT_IDS` and `PLANNED_CIRCUIT_IDS` are derived from `CIRCUIT_SUPPORT_STATUS` at load time, so they cannot disagree with it.
+
 ## Supported Circuits
 
-Circuit IDs are canonical and case-sensitive — pass them exactly as written here. `sdk.getSupportedCircuits()` returns the same list at runtime.
+The circuits below are officially supported. Pass their IDs exactly as written, or use the `CIRCUIT_IDS` constants. `sdk.getSupportedCircuits()` returns every known ID at runtime, planned ones included — see [Circuit Identifiers](#circuit-identifiers).
 
 ### `coinbase_attestation`
 
@@ -178,6 +242,14 @@ const relay = await sdk.createRelayRequest('oidc_domain_attestation', {
 
 > When `provider` is set, the mobile app verifies the user's account is managed by the specified workspace provider (e.g., Google Workspace `hd` claim, Microsoft 365 `tid` claim). Without `provider`, only the email domain is verified.
 
+## Planned Circuits
+
+The identifiers below are reserved and exported, and the circuits exist — but they are **not officially supported yet**. Availability, input shape and public-input layout can change without a major version bump, so treat anything here as provisional. `CIRCUIT_SUPPORT_STATUS` reports each of them as `planned`.
+
+### `giwa_attestation`
+
+Reserved identifier for GIWA attestation. It is a fork of `coinbase_attestation` and carries the same four public inputs, but there is no dedicated input type for it and no supported request flow. The ID is exported so that every layer spells it the same way; do not build on it yet.
+
 ### `mdl_kr_ownership`
 
 Proves the user holds a valid Korean mobile driver's license (모바일 신분증). The license data stays on-device; only the attributes selected by `discloseFlags` are revealed. No wallet signer is required.
@@ -852,6 +924,8 @@ Types you can import:
 
 ```typescript
 import type {
+  CircuitId,
+  CircuitSupportStatus,
   CircuitType,
   ProofRequestStatus,
   CoinbaseKycInputs,
@@ -875,7 +949,9 @@ import type {
 
 | Type | Description |
 |------|-------------|
-| `CircuitType` | `'coinbase_attestation' \| 'coinbase_country_attestation' \| 'oidc_domain_attestation' \| 'mdl_kr_ownership' \| 'mdl_kr_age' \| 'mdl_kr_region'` |
+| `CircuitId` | Union of the seven canonical circuit IDs — `'coinbase_attestation' \| 'coinbase_country_attestation' \| 'oidc_domain_attestation' \| 'giwa_attestation' \| 'mdl_kr_ownership' \| 'mdl_kr_age' \| 'mdl_kr_region'`. Also exported from `@zkproofport-app/sdk/circuits` |
+| `CircuitSupportStatus` | `'supported' \| 'planned'` — see [Circuit Identifiers](#circuit-identifiers) |
+| `CircuitType` | Alias of `CircuitId`. Kept as the name used throughout `ProofRequest`, `ProofResponse` and the SDK methods |
 | `ProofRequestStatus` | `'pending' \| 'completed' \| 'error' \| 'cancelled'` — the status on a `ProofResponse` |
 | `CoinbaseKycInputs` | Inputs for `coinbase_attestation`: `{ scope, userAddress?, rawTransaction? }` |
 | `CoinbaseCountryInputs` | Inputs for `coinbase_country_attestation`: `{ scope, countryList, isIncluded, userAddress?, rawTransaction? }` |

package/dist/ProofportSDK.d.ts

@@ -2,6 +2,7 @@
  * Proofport SDK - Main class
  */
 import type { ProofRequest, ProofResponse, CircuitType, CircuitInputs, ProofportConfig, QRCodeOptions, ChallengeResponse, WalletSigner, RelayProofRequest, RelayProofResult } from './types';
+import { type OffChainVerifyOptions } from './offChainVerifier';
 import type { SDKEnvironment } from './types';
 /**
  * Main SDK class for interacting with the ZKProofport mobile app.
@@ -528,6 +529,36 @@ export declare class ProofportSDK {
         valid: boolean;
         error?: string;
     }>;
+    /**
+     * 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');
+     * }
+     * ```
+     */
+    verifyResponseOffChain(response: ProofResponse, options?: OffChainVerifyOptions): Promise<{
+        valid: boolean;
+        error?: string;
+    }>;
     /**
      * Gets the deployed verifier contract address for a circuit.
      *

package/dist/circuits.d.ts

@@ -0,0 +1,158 @@
+/**
+ * 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.
+ */
+/**
+ * Whether a circuit is officially supported today or still on the roadmap.
+ *
+ * - `supported` — generally available. Safe to build a product on.
+ * - `planned` — the identifier is reserved and the circuit exists, but it is
+ *   not officially supported yet. Availability, inputs and public-input layout
+ *   may change without a major version bump.
+ */
+export type CircuitSupportStatus = 'supported' | 'planned';
+/**
+ * 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',
+ * });
+ * ```
+ */
+export declare const CIRCUIT_IDS: Readonly<{
+    /** Coinbase KYC attestation. Officially supported. */
+    readonly COINBASE_ATTESTATION: "coinbase_attestation";
+    /** Coinbase country attestation (inclusion / exclusion). Officially supported. */
+    readonly COINBASE_COUNTRY_ATTESTATION: "coinbase_country_attestation";
+    /** OIDC email-domain attestation. Officially supported. */
+    readonly OIDC_DOMAIN_ATTESTATION: "oidc_domain_attestation";
+    /** GIWA attestation. Planned — not officially supported yet. */
+    readonly GIWA_ATTESTATION: "giwa_attestation";
+    /** Korea Mobile ID ownership. Planned — not officially supported yet. */
+    readonly MDL_KR_OWNERSHIP: "mdl_kr_ownership";
+    /** Korea Mobile ID age threshold. Planned — not officially supported yet. */
+    readonly MDL_KR_AGE: "mdl_kr_age";
+    /** Korea Mobile ID si/do region. Planned — not officially supported yet. */
+    readonly MDL_KR_REGION: "mdl_kr_region";
+}>;
+/**
+ * Union of every canonical circuit identifier.
+ *
+ * `CircuitType` (exported from the package root) is an alias of this type — the
+ * two names refer to the same union, and this module is where it is defined.
+ */
+export type CircuitId = (typeof CIRCUIT_IDS)[keyof typeof CIRCUIT_IDS];
+/**
+ * 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'
+ * ```
+ */
+export declare const CIRCUIT_SUPPORT_STATUS: Readonly<Record<CircuitId, CircuitSupportStatus>>;
+/**
+ * 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.
+ */
+export declare const CIRCUIT_VK_PATHS: Readonly<Record<CircuitId, string>>;
+/**
+ * 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.
+ */
+export declare const ALL_CIRCUIT_IDS: readonly CircuitId[];
+/**
+ * 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.
+ */
+export declare const SUPPORTED_CIRCUIT_IDS: readonly CircuitId[];
+/**
+ * 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.
+ */
+export declare const PLANNED_CIRCUIT_IDS: readonly CircuitId[];
+/**
+ * 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
+ * ```
+ */
+export declare function isCircuitId(value: unknown): value is CircuitId;
+/**
+ * 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
+ * ```
+ */
+export declare function isSupportedCircuitId(value: unknown): value is CircuitId;
+/**
+ * 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'
+ * ```
+ */
+export declare function getCircuitSupportStatus(circuit: CircuitId): CircuitSupportStatus;

package/dist/circuits.esm.js

@@ -0,0 +1,170 @@
+/**
+ * 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];
+}
+
+export { ALL_CIRCUIT_IDS, CIRCUIT_IDS, CIRCUIT_SUPPORT_STATUS, CIRCUIT_VK_PATHS, PLANNED_CIRCUIT_IDS, SUPPORTED_CIRCUIT_IDS, getCircuitSupportStatus, isCircuitId, isSupportedCircuitId };
+//# sourceMappingURL=circuits.esm.js.map

package/dist/circuits.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuits.esm.js","sources":["../src/circuits.ts"],"sourcesContent":["/**\n * Canonical ZKProofport circuit identifiers.\n *\n * This module is the single source of truth for circuit IDs. Every other layer\n * — the mobile app, the demo, the relay, server-side provers — reads its list\n * from here instead of keeping a private copy that silently drifts.\n *\n * It has **no imports and no dependencies**, so it can be pulled in on its own:\n *\n * ```typescript\n * import { CIRCUIT_IDS, isCircuitId } from '@zkproofport-app/sdk/circuits';\n * ```\n *\n * The same names are also re-exported from the package root\n * (`@zkproofport-app/sdk`) for callers that already import the SDK.\n *\n * ## Identifiers are canonical and case-sensitive\n *\n * Each ID is the circuit's `name` in its `Nargo.toml`, verbatim. The format is\n * lowercase with underscores. Hyphenated spellings (`coinbase-kyc`,\n * `mdl-kr-age`) are directory or UI route names in other repositories — they\n * are **not** circuit IDs, and passing one produces a nullifier mismatch or a\n * failed on-chain lookup rather than a clear error.\n */\n\n/**\n * Whether a circuit is officially supported today or still on the roadmap.\n *\n * - `supported` — generally available. Safe to build a product on.\n * - `planned` — the identifier is reserved and the circuit exists, but it is\n *   not officially supported yet. Availability, inputs and public-input layout\n *   may change without a major version bump.\n */\nexport type CircuitSupportStatus = 'supported' | 'planned';\n\n/**\n * Canonical circuit identifiers, keyed by a stable constant name.\n *\n * Prefer these constants over string literals so a rename is a compile error\n * rather than a runtime surprise.\n *\n * @example\n * ```typescript\n * import { CIRCUIT_IDS } from '@zkproofport-app/sdk/circuits';\n *\n * const relay = await sdk.createRelayRequest(CIRCUIT_IDS.COINBASE_ATTESTATION, {\n *   scope: 'myapp.com',\n * });\n * ```\n */\nexport const CIRCUIT_IDS = Object.freeze({\n  /** Coinbase KYC attestation. Officially supported. */\n  COINBASE_ATTESTATION: 'coinbase_attestation',\n  /** Coinbase country attestation (inclusion / exclusion). Officially supported. */\n  COINBASE_COUNTRY_ATTESTATION: 'coinbase_country_attestation',\n  /** OIDC email-domain attestation. Officially supported. */\n  OIDC_DOMAIN_ATTESTATION: 'oidc_domain_attestation',\n  /** GIWA attestation. Planned — not officially supported yet. */\n  GIWA_ATTESTATION: 'giwa_attestation',\n  /** Korea Mobile ID ownership. Planned — not officially supported yet. */\n  MDL_KR_OWNERSHIP: 'mdl_kr_ownership',\n  /** Korea Mobile ID age threshold. Planned — not officially supported yet. */\n  MDL_KR_AGE: 'mdl_kr_age',\n  /** Korea Mobile ID si/do region. Planned — not officially supported yet. */\n  MDL_KR_REGION: 'mdl_kr_region',\n} as const);\n\n/**\n * Union of every canonical circuit identifier.\n *\n * `CircuitType` (exported from the package root) is an alias of this type — the\n * two names refer to the same union, and this module is where it is defined.\n */\nexport type CircuitId = (typeof CIRCUIT_IDS)[keyof typeof CIRCUIT_IDS];\n\n/**\n * Support status for every circuit.\n *\n * The record is exhaustive over {@link CircuitId}: adding an identifier without\n * giving it a status is a compile error, so this list cannot drift from\n * {@link CIRCUIT_IDS}.\n *\n * @example\n * ```typescript\n * import { CIRCUIT_SUPPORT_STATUS } from '@zkproofport-app/sdk/circuits';\n *\n * CIRCUIT_SUPPORT_STATUS.coinbase_attestation; // 'supported'\n * CIRCUIT_SUPPORT_STATUS.mdl_kr_age;           // 'planned'\n * ```\n */\nexport const CIRCUIT_SUPPORT_STATUS: Readonly<Record<CircuitId, CircuitSupportStatus>> =\n  Object.freeze({\n    coinbase_attestation: 'supported',\n    coinbase_country_attestation: 'supported',\n    oidc_domain_attestation: 'supported',\n    giwa_attestation: 'planned',\n    mdl_kr_ownership: 'planned',\n    mdl_kr_age: 'planned',\n    mdl_kr_region: 'planned',\n  } as const);\n\n/**\n * Where each circuit's verification key lives inside the `zkproofport/circuits`\n * repository, relative to its root.\n *\n * Off-chain verification needs the verification key and nothing else — no\n * circuit bytecode, no witness. The key is public by nature: it is what anyone\n * checking a proof must already have, and the Solidity verifiers deployed\n * on-chain embed the same key.\n *\n * Exhaustive over {@link CircuitId} on purpose. A new circuit whose key path is\n * not listed here fails to compile rather than failing at verification time,\n * where the only symptom would be a proof that cannot be checked.\n */\nexport const CIRCUIT_VK_PATHS: Readonly<Record<CircuitId, string>> = Object.freeze({\n  coinbase_attestation: 'coinbase-attestation/target/vk',\n  coinbase_country_attestation: 'coinbase-country-attestation/target/vk',\n  oidc_domain_attestation: 'oidc-domain-attestation/target/vk',\n  giwa_attestation: 'giwa-attestation/target/vk',\n  mdl_kr_ownership: 'mdl/kr-ownership/target/vk',\n  mdl_kr_age: 'mdl/kr-age/target/vk',\n  mdl_kr_region: 'mdl/kr-region/target/vk',\n} as const);\n\n/**\n * Every canonical circuit identifier, in declaration order.\n *\n * Includes circuits that are still `planned`. Use {@link SUPPORTED_CIRCUIT_IDS}\n * when you only want the ones that are officially supported today.\n */\nexport const ALL_CIRCUIT_IDS: readonly CircuitId[] = Object.freeze(\n  Object.values(CIRCUIT_IDS) as CircuitId[]\n);\n\n/**\n * Circuits that are officially supported today: the two Coinbase circuits and\n * OIDC domain attestation.\n *\n * Derived from {@link CIRCUIT_SUPPORT_STATUS}, so it cannot fall out of sync.\n */\nexport const SUPPORTED_CIRCUIT_IDS: readonly CircuitId[] = Object.freeze(\n  ALL_CIRCUIT_IDS.filter((id) => CIRCUIT_SUPPORT_STATUS[id] === 'supported')\n);\n\n/**\n * Circuits whose identifiers are reserved but which are not officially\n * supported yet: GIWA attestation and the three Korea Mobile ID circuits.\n *\n * Derived from {@link CIRCUIT_SUPPORT_STATUS}, so it cannot fall out of sync.\n */\nexport const PLANNED_CIRCUIT_IDS: readonly CircuitId[] = Object.freeze(\n  ALL_CIRCUIT_IDS.filter((id) => CIRCUIT_SUPPORT_STATUS[id] === 'planned')\n);\n\n/**\n * Narrows an unknown value to a canonical circuit identifier.\n *\n * Returns `false` for hyphenated route names such as `'coinbase-kyc'`, which\n * are not circuit IDs.\n *\n * @example\n * ```typescript\n * isCircuitId('coinbase_attestation'); // true\n * isCircuitId('coinbase-kyc');         // false\n * ```\n */\nexport function isCircuitId(value: unknown): value is CircuitId {\n  return typeof value === 'string' && (ALL_CIRCUIT_IDS as readonly string[]).includes(value);\n}\n\n/**\n * Narrows an unknown value to a circuit identifier that is officially supported\n * today. Planned circuits return `false`.\n *\n * @example\n * ```typescript\n * isSupportedCircuitId('oidc_domain_attestation'); // true\n * isSupportedCircuitId('mdl_kr_age');              // false — planned\n * ```\n */\nexport function isSupportedCircuitId(value: unknown): value is CircuitId {\n  return isCircuitId(value) && CIRCUIT_SUPPORT_STATUS[value] === 'supported';\n}\n\n/**\n * Returns the support status of a circuit.\n *\n * @param circuit - A canonical circuit identifier.\n * @throws Error when the value is not a canonical circuit identifier.\n *\n * @example\n * ```typescript\n * getCircuitSupportStatus('giwa_attestation'); // 'planned'\n * ```\n */\nexport function getCircuitSupportStatus(circuit: CircuitId): CircuitSupportStatus {\n  if (!isCircuitId(circuit)) {\n    throw new Error(\n      `Unknown circuit '${String(circuit)}'. Expected one of: ${ALL_CIRCUIT_IDS.join(', ')}`\n    );\n  }\n  return CIRCUIT_SUPPORT_STATUS[circuit];\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;AAuBG;AAYH;;;;;;;;;;;;;;AAcG;AACI,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC;;AAEvC,IAAA,oBAAoB,EAAE,sBAAsB;;AAE5C,IAAA,4BAA4B,EAAE,8BAA8B;;AAE5D,IAAA,uBAAuB,EAAE,yBAAyB;;AAElD,IAAA,gBAAgB,EAAE,kBAAkB;;AAEpC,IAAA,gBAAgB,EAAE,kBAAkB;;AAEpC,IAAA,UAAU,EAAE,YAAY;;AAExB,IAAA,aAAa,EAAE,eAAe;AACtB,CAAA;AAUV;;;;;;;;;;;;;;AAcG;AACI,MAAM,sBAAsB,GACjC,MAAM,CAAC,MAAM,CAAC;AACZ,IAAA,oBAAoB,EAAE,WAAW;AACjC,IAAA,4BAA4B,EAAE,WAAW;AACzC,IAAA,uBAAuB,EAAE,WAAW;AACpC,IAAA,gBAAgB,EAAE,SAAS;AAC3B,IAAA,gBAAgB,EAAE,SAAS;AAC3B,IAAA,UAAU,EAAE,SAAS;AACrB,IAAA,aAAa,EAAE,SAAS;AAChB,CAAA;AAEZ;;;;;;;;;;;;AAYG;AACI,MAAM,gBAAgB,GAAwC,MAAM,CAAC,MAAM,CAAC;AACjF,IAAA,oBAAoB,EAAE,gCAAgC;AACtD,IAAA,4BAA4B,EAAE,wCAAwC;AACtE,IAAA,uBAAuB,EAAE,mCAAmC;AAC5D,IAAA,gBAAgB,EAAE,4BAA4B;AAC9C,IAAA,gBAAgB,EAAE,4BAA4B;AAC9C,IAAA,UAAU,EAAE,sBAAsB;AAClC,IAAA,aAAa,EAAE,yBAAyB;AAChC,CAAA;AAEV;;;;;AAKG;AACI,MAAM,eAAe,GAAyB,MAAM,CAAC,MAAM,CAChE,MAAM,CAAC,MAAM,CAAC,WAAW,CAAgB;AAG3C;;;;;AAKG;AACI,MAAM,qBAAqB,GAAyB,MAAM,CAAC,MAAM,CACtE,eAAe,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,sBAAsB,CAAC,EAAE,CAAC,KAAK,WAAW,CAAC;AAG5E;;;;;AAKG;AACI,MAAM,mBAAmB,GAAyB,MAAM,CAAC,MAAM,CACpE,eAAe,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,sBAAsB,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC;AAG1E;;;;;;;;;;;AAWG;AACG,SAAU,WAAW,CAAC,KAAc,EAAA;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,eAAqC,CAAC,QAAQ,CAAC,KAAK,CAAC;AAC5F;AAEA;;;;;;;;;AASG;AACG,SAAU,oBAAoB,CAAC,KAAc,EAAA;IACjD,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,sBAAsB,CAAC,KAAK,CAAC,KAAK,WAAW;AAC5E;AAEA;;;;;;;;;;AAUG;AACG,SAAU,uBAAuB,CAAC,OAAkB,EAAA;AACxD,IAAA,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE;AACzB,QAAA,MAAM,IAAI,KAAK,CACb,CAAA,iBAAA,EAAoB,MAAM,CAAC,OAAO,CAAC,CAAA,oBAAA,EAAuB,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA,CAAE,CACvF;IACH;AACA,IAAA,OAAO,sBAAsB,CAAC,OAAO,CAAC;AACxC;;;;"}