@zkproofport-app/sdk 0.5.0-beta.0 → 0.5.0-beta.2

package/README.md

@@ -81,7 +81,7 @@ const qrDataUrl = await sdk.generateQRCode(relay.deepLink);
 const result = await sdk.waitForProof(relay.requestId);
 
 if (result.status === 'completed') {
-  // 6. Verify on-chain — the relay result carries the verifier to call
+  // 6. Verify on-chain — against the SDK's own verifier for this circuit
   const response: ProofResponse = {
     requestId: result.requestId,
     circuit: result.circuit as CircuitType,
@@ -296,9 +296,8 @@ One more difference worth knowing if you count people: its nullifier is
 a constant compiled into the circuit, so one wallet in one scope has exactly
 one nullifier and there is no input a prover can vary.
 
-**Testnet only.** The verifier lives on GIWA Sepolia (chain `91342`) and
-nowhere else, so the mobile app keeps it behind Developer Mode. A mainnet
-deployment is planned; until it exists, do not ship on this.
+The verifier is deployed on GIWA Sepolia (chain `91342`). The mobile app shows
+this circuit in its Laboratory, which the user turns on in More.
 
 ### `dojang_playground`
 
@@ -350,7 +349,7 @@ something the circuit never saw.
 
 ## 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`.
+ZKProofport is registered with the Ministry of the Interior and Safety as a Korea Mobile ID integration service (모바일 신분증 연계서비스). The three circuits below are in beta: `CIRCUIT_SUPPORT_STATUS` reports each of them as `planned`, and their input shape and public-input layout can change without a major version bump.
 
 ### `mdl_kr_ownership`
 
@@ -677,8 +676,8 @@ When you are done, `sdk.disconnect()` closes any open socket.
   circuit: 'coinbase_attestation',
   proof: '0x1f8b0a…',                       // proof bytes, opaque
   publicInputs: ['0x00…2f', '0x00…a1', …],  // ordered — 128 entries for this circuit
-  verifierAddress: '0x…',                   // contract that can check this proof
-  chainId: …,                               // network that contract lives on
+  verifierAddress: '0x…',                   // the verifier the app reports (checked, not trusted)
+  chainId: …,                               // the network the app reports (checked, not trusted)
   deepLink: 'zkproofport://proof-request?data=…',
   createdAt: '2026-02-07T09:14:02.101Z',
   updatedAt: '2026-02-07T09:14:48.902Z',
@@ -692,8 +691,8 @@ When you are done, `sdk.disconnect()` closes any open socket.
 | `circuit` | `string` | terminal results | Which circuit produced the proof, as reported by the mobile app. You need it to read `publicInputs`, because the layout is per circuit. Undefined while the request is still pending. |
 | `proof` | `string` | `'completed'` | The proof bytes as a `0x` hex string. Opaque: the only thing to do with it is hand it to a verifier. |
 | `publicInputs` | `string[]` | `'completed'` | The circuit's public inputs **in circuit order**. This is the part that carries meaning — what each index holds is in [Public Input Layout Constants](#public-input-layout-constants). |
-| `verifierAddress` | `string` | `'completed'` | Address of the Solidity verifier contract that can check this exact proof. It comes from the mobile app — forward it, do not hardcode one. |
-| `chainId` | `number` | `'completed'` | The chain that `verifierAddress` lives on. Same rule: forward it. |
+| `verifierAddress` | `string` | `'completed'` | The verifier contract the mobile app reports. Forward it: the SDK compares it with the verifier it ships with and refuses the proof if they differ. It never verifies against this address. |
+| `chainId` | `number` | `'completed'` | The network the mobile app reports. Same rule: compared, never trusted. |
 | `error` | `string` | `'error'`, `'failed'`, `'expired'` | Human-readable reason from the mobile app or the relay. |
 | `errorCode` | `string` | some `'error'` results | The app's error code, `E` + four digits (e.g. `'E2007'`). Absent when the app did not send one. |
 | `deepLink` | `string` | polling path only | The deep link the request was created with. |
@@ -771,8 +770,8 @@ The relay answers `'expired'` before the SDK's default `timeoutMs` (300 000 ms)
 | `status` | `'pending' \| 'completed' \| 'error' \| 'cancelled'` | Yes | `'completed'`. Anything else and verification returns `{ valid: false, error: 'Invalid or incomplete response' }` without touching the chain. Note the relay says `'failed'` where this type says `'error'` |
 | `proof` | `string` | When completed | `result.proof` |
 | `publicInputs` | `string[]` | When completed | `result.publicInputs` |
-| `verifierAddress` | `string` | When completed | `result.verifierAddress`. Without it there is no contract to call and verification fails with `No verifier address provided…` |
-| `chainId` | `number` | When completed | `result.chainId`. Used to pick a network when you pass no provider of your own |
+| `verifierAddress` | `string` | No | `result.verifierAddress`. Optional. When present it must match the SDK's own verifier for the circuit, or verification is refused |
+| `chainId` | `number` | No | `result.chainId`. Optional. When present it must match the network the SDK verifies the circuit on, or verification is refused |
 | `numPublicInputs` | `number` | No | Never delivered by the relay, and never read during verification — `publicInputs.length` is used instead. Omit it |
 | `timestamp` | `number` | No | Not delivered by the relay. Omit it |
 | `error` | `string` | On failure | `result.error`. Carried for your own logging; verification ignores it |
@@ -783,7 +782,15 @@ There is no `nullifier` field here either.
 
 Verify the proof cryptographically by calling the deployed Solidity verifier contract.
 
-The relay result tells you which contract to call (`verifierAddress`) and on which chain (`chainId`), so verification goes through `verifyResponseOnChain`, which reads both off the response:
+`verifyResponseOnChain` checks the proof against the verifier contract the SDK ships with for that circuit. Which contract judges a proof is never taken from the proof's own response: the SDK carries the deployed verifiers, generated from the circuits' deployment records, and a response whose `verifierAddress` or `chainId` differs from them is refused rather than checked elsewhere. If you configure your own verifier in the SDK's `verifiers` option, that one is used instead.
+
+For OIDC domain proofs the SDK also checks that the proof was made with a signing key Google or Microsoft actually publishes. That key is part of the proof's public inputs, so a proof made with a self-generated key would otherwise pass the contract. The SDK fetches the provider's published keys, caches them as the provider's own cache headers allow, and returns `{ valid: false, error }` when the key is not among them or the keys cannot be fetched. Every verify method does this; there is nothing to call separately.
+
+For Coinbase KYC, Coinbase country and GIWA proofs the SDK checks that the attestation's signer belongs to the published signer set: the proof carries the root of the signer list it was made against, and a proof made against any other list is refused with `{ valid: false, error }`. This too runs in every verify method.
+
+The one limit: a proof made with a key the provider has already withdrawn, which this process never saw while it was published, cannot be checked and is refused. Keys seen while published stay acceptable for 24 hours after they disappear.
+
+
 
 ```typescript
 import type { CircuitType, ProofResponse } from '@zkproofport-app/sdk';
@@ -815,11 +822,11 @@ The SDK connects to the right network on its own. Pass your own ethers `Provider
 const verification = await sdk.verifyResponseOnChain(response, myProvider);
 ```
 
-`verifyResponseOnChain` reports failures instead of throwing them. An incomplete response (`status` other than `'completed'`, or a missing `proof` / `publicInputs`) returns `{ valid: false, error: 'Invalid or incomplete response' }` without making a network call; a missing `verifierAddress` returns `{ valid: false, error: 'No verifier address provided…' }`; and a reverting contract call returns `{ valid: false, error }` carrying the revert message. It does throw in one case: a response carrying a `chainId` the SDK has no built-in endpoint for, when you passed no provider of your own. Pass your own provider if you ever hit that.
+`verifyResponseOnChain` reports failures instead of throwing them. An incomplete response (`status` other than `'completed'`, or a missing `proof` / `publicInputs`) returns `{ valid: false, error: 'Invalid or incomplete response' }` without making a network call; an unknown circuit, a response naming a different verifier, an OIDC signing key the provider does not publish and a reverting contract call each return `{ valid: false, error }` saying which.
 
 `valid: true` means the verifier contract accepted the proof: it is a real proof for that circuit, and its public inputs are the ones it was proved against. It does **not** yet mean the proof answers *your* question — that it was bound to your scope, or that the domain or country in it is the one you asked for. Those live in the public inputs, and reading them is Step 8. `valid: false` is a rejected proof, not an outage: do not retry it, refuse the user.
 
-> **Why not `verifyOnChain`?** `sdk.verifyOnChain(circuit, proof, publicInputs, providerOrSigner?)` takes the same proof in raw pieces. Those pieces carry no verifier address, and it never looks at a response for one — it consults only the `verifiers` map the SDK was constructed with, which `ProofportSDK.create()` leaves empty. Out of the box it therefore returns `{ valid: false, error: 'No verifier address provided. Configure via SDK or ensure proof response includes verifierAddress.' }`. Use `verifyResponseOnChain`.
+> **`verifyOnChain` and `verifyResponseOffChain`.** `sdk.verifyOnChain(circuit, proof, publicInputs, providerOrSigner?)` takes the same proof in raw pieces and checks it against the same built-in verifier, with the same OIDC key check. `sdk.verifyResponseOffChain(response)` checks the proof against the circuit's verification key with no chain involved, and runs the same OIDC key check. Prefer `verifyResponseOnChain` when the answer has to be the one a contract gives.
 
 ### Step 8: Extract Scope, Nullifier, and Domain
 
@@ -1025,7 +1032,7 @@ async function verifyUser() {
 
 ## Configuration
 
-`ProofportSDK.create()` returns a fully configured SDK instance. No manual configuration is needed: the relay endpoint is built in, and the verifier contract and network to check a proof against arrive with the proof itself (`verifierAddress`, `chainId`).
+`ProofportSDK.create()` returns a fully configured SDK instance. No manual configuration is needed: the relay endpoint and the verifier contracts proofs are checked against are built in. The verifier a proof response names is compared with them, never used in their place.
 
 ## Types Reference
 

package/dist/ProofportSDK.d.ts

@@ -44,6 +44,12 @@ export declare class ProofportSDK {
     private signer;
     private relayUrl;
     private socket;
+    /**
+     * Set by {@link ProofportSDK.create} from its environment preset. It decides
+     * which chain a proof is verified on when the dApp configured no verifier
+     * for the circuit; a custom-config SDK has none and must configure one.
+     */
+    private environment;
     /**
      * Creates a new ProofportSDK instance.
      *
@@ -73,13 +79,11 @@ export declare class ProofportSDK {
     constructor(config?: ProofportConfig);
     /**
      * @internal
-     * Creates a Coinbase KYC verification proof request.
+     * Creates a proof request for a circuit whose dapp-side input is a scope
+     * (Coinbase KYC, OIDC domain, GIWA, Dojang), keeping that circuit's id.
      *
-     * Generates a proof request for verifying Coinbase KYC status without revealing
-     * the actual attestation data. The proof confirms the user has passed Coinbase KYC
-     * while maintaining privacy through zero-knowledge proofs.
-     *
-     * @param inputs - Circuit inputs for Coinbase KYC
+     * @param circuit - The circuit requested; it is the request's circuit
+     * @param inputs - Circuit inputs; `scope` is required (and `domain` for OIDC)
      * @param inputs.scope - Application-specific scope (e.g., domain name)
      * @param options - Request configuration options
   
@@ -94,7 +98,7 @@ export declare class ProofportSDK {
      *
      * @example
      * ```typescript
-     * const request = sdk.createCoinbaseKycRequest({
+     * const request = sdk.createScopedRequest('coinbase_attestation', {
      *   scope: 'myapp.com'
      * }, {
      *   dappName: 'My DApp',
@@ -104,7 +108,7 @@ export declare class ProofportSDK {
      * const deepLink = sdk.getDeepLinkUrl(request);
      * ```
      */
-    private createCoinbaseKycRequest;
+    private createScopedRequest;
     /**
      * @internal
      * Creates a Coinbase Country attestation proof request.
@@ -169,6 +173,12 @@ export declare class ProofportSDK {
      * ```
      */
     private createProofRequest;
+    /**
+     * How each circuit's request is built and checked. Keyed by circuit id and
+     * exhaustive over it, so a new circuit is a compile error here instead of
+     * falling through to another circuit's builder.
+     */
+    private static readonly REQUEST_BUILDERS;
     /**
      * @internal
      * Creates a Korea Mobile ID (mDL) proof request for any of the three
@@ -491,6 +501,13 @@ export declare class ProofportSDK {
         valid: boolean;
         error?: string;
     }>;
+    /**
+     * The verifier for a circuit: the one the dApp configured, otherwise the
+     * pinned deployment on the chain this SDK's environment verifies that
+     * circuit on. `undefined` when neither exists, which core reports as an
+     * error. Never anything a proof response said.
+     */
+    private verifierTarget;
     /**
      * Verifies a proof response on-chain using the deployed verifier contract.
      *
@@ -575,6 +592,8 @@ export declare class ProofportSDK {
      * ```
      */
     getVerifierAddress(circuit: CircuitType): string;
+    /** The configured or pinned verifier, or an error saying why there is none. */
+    private requireVerifier;
     /**
      * Gets the blockchain chain ID where the verifier contract is deployed.
      *
@@ -731,6 +750,8 @@ export declare class ProofportSDK {
      * ```
      */
     static create(envOrConfig?: SDKEnvironment | ProofportConfig): ProofportSDK;
+    /** @internal An SDK on an environment preset's relay, verifying on that environment's chains. */
+    private static forEnvironment;
     /**
      * Detects if the code is running on a mobile device.
      *

package/dist/constants.d.ts

@@ -13,6 +13,49 @@ import type { CircuitType, SDKEnvironment } from './types';
  * ```
  */
 export declare const RELAY_URLS: Record<SDKEnvironment, string>;
+/**
+ * The chain each circuit is verified on, per environment. Complete: a circuit
+ * added to the SDK is a compile error here until somebody names its chain.
+ *
+ * Mirrors the mobile app's `CIRCUIT_NETWORKS` (proofport-app
+ * src/config/contracts.ts), because a proof is checked where the app said its
+ * verifier is: Base for the Coinbase and OIDC circuits, GIWA Sepolia for GIWA
+ * and Dojang (testnet-only), Base Sepolia for Korea Mobile ID (testnet-only).
+ * The ADDRESS on that chain always comes from core's pinned table, never from
+ * a proof response.
+ */
+export declare const VERIFICATION_CHAINS: {
+    readonly production: {
+        readonly coinbase_attestation: 8453;
+        readonly coinbase_country_attestation: 8453;
+        readonly oidc_domain_attestation: 8453;
+        readonly giwa_attestation: 91342;
+        readonly dojang_playground: 91342;
+        readonly mdl_kr_ownership: 84532;
+        readonly mdl_kr_age: 84532;
+        readonly mdl_kr_region: 84532;
+    };
+    readonly staging: {
+        readonly coinbase_attestation: 84532;
+        readonly coinbase_country_attestation: 84532;
+        readonly oidc_domain_attestation: 84532;
+        readonly giwa_attestation: 91342;
+        readonly dojang_playground: 91342;
+        readonly mdl_kr_ownership: 84532;
+        readonly mdl_kr_age: 84532;
+        readonly mdl_kr_region: 84532;
+    };
+    readonly local: {
+        readonly coinbase_attestation: 84532;
+        readonly coinbase_country_attestation: 84532;
+        readonly oidc_domain_attestation: 84532;
+        readonly giwa_attestation: 91342;
+        readonly dojang_playground: 91342;
+        readonly mdl_kr_ownership: 84532;
+        readonly mdl_kr_age: 84532;
+        readonly mdl_kr_region: 84532;
+    };
+};
 /**
  * Default deep link URL scheme for ZKProofport mobile app.
  * Used to construct deep link URLs that open the mobile app.

package/dist/index.d.ts

@@ -30,6 +30,8 @@ export { extractScopeFromPublicInputs, extractNullifierFromPublicInputs, extract
 export { CIRCUIT_IDS, CIRCUIT_SUPPORT_STATUS, ALL_CIRCUIT_IDS, SUPPORTED_CIRCUIT_IDS, EXPERIMENTAL_CIRCUIT_IDS, PLANNED_CIRCUIT_IDS, isCircuitId, isSupportedCircuitId, getCircuitSupportStatus, CIRCUIT_VK_PATHS, } from './circuits';
 export { verifyProofOffChain } from './offChainVerifier';
 export type { OffChainVerifyResult, OffChainVerifyOptions, } from './offChainVerifier';
+export { PINNED_VERIFIERS, getPinnedVerifier } from './verifier';
+export type { PinnedVerifier } from './verifier';
 export { COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, MDL_KR_PUBLIC_INPUT_LAYOUT, } from './constants';
 export type { CircuitId, CircuitSupportStatus } from './circuits';
 export { CIRCUIT_ACTION_BINDING, circuitActionBinding, } from './circuits';

package/dist/index.esm.js

@@ -1,5 +1,5 @@
-import { parseProofForOnChain, verifyProofOnChain, getVerifierAddress, getVerifierChainId, extractScopeFromPublicInputs, extractNullifierFromPublicInputs, extractDomainFromPublicInputs } from '@zkproofport-app/core';
-export { COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, MDL_KR_PUBLIC_INPUT_LAYOUT, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, extractDomainFromPublicInputs, extractNullifierFromPublicInputs, extractScopeFromPublicInputs } from '@zkproofport-app/core';
+import { checkProofIssuer, parseProofForOnChain, verifyProofOnChain, getPinnedVerifier, extractScopeFromPublicInputs, extractNullifierFromPublicInputs, extractDomainFromPublicInputs } from '@zkproofport-app/core';
+export { COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, MDL_KR_PUBLIC_INPUT_LAYOUT, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, PINNED_VERIFIERS, extractDomainFromPublicInputs, extractNullifierFromPublicInputs, extractScopeFromPublicInputs, getPinnedVerifier } from '@zkproofport-app/core';
 import { isCircuitId, ALL_CIRCUIT_IDS, circuitActionBinding, CIRCUIT_VK_PATHS, CIRCUIT_NEEDS_WALLET_SIGNATURE } from '@zkproofport-app/core/circuits';
 export { ALL_CIRCUIT_IDS, CIRCUIT_ACTION_BINDING, CIRCUIT_IDS, CIRCUIT_SUPPORT_STATUS, CIRCUIT_VK_PATHS, EXPERIMENTAL_CIRCUIT_IDS, PLANNED_CIRCUIT_IDS, SUPPORTED_CIRCUIT_IDS, circuitActionBinding, getCircuitSupportStatus, isCircuitId, isSupportedCircuitId } from '@zkproofport-app/core/circuits';
 import { validateTypedAction } from '@zkproofport-app/core/typedAction';
@@ -23,6 +23,49 @@ const RELAY_URLS = {
     staging: 'https://stg-relay.zkproofport.app',
     local: 'http://localhost:4001',
 };
+/**
+ * The chain each circuit is verified on, per environment. Complete: a circuit
+ * added to the SDK is a compile error here until somebody names its chain.
+ *
+ * Mirrors the mobile app's `CIRCUIT_NETWORKS` (proofport-app
+ * src/config/contracts.ts), because a proof is checked where the app said its
+ * verifier is: Base for the Coinbase and OIDC circuits, GIWA Sepolia for GIWA
+ * and Dojang (testnet-only), Base Sepolia for Korea Mobile ID (testnet-only).
+ * The ADDRESS on that chain always comes from core's pinned table, never from
+ * a proof response.
+ */
+const VERIFICATION_CHAINS = {
+    production: {
+        coinbase_attestation: 8453,
+        coinbase_country_attestation: 8453,
+        oidc_domain_attestation: 8453,
+        giwa_attestation: 91342,
+        dojang_playground: 91342,
+        mdl_kr_ownership: 84532,
+        mdl_kr_age: 84532,
+        mdl_kr_region: 84532,
+    },
+    staging: {
+        coinbase_attestation: 84532,
+        coinbase_country_attestation: 84532,
+        oidc_domain_attestation: 84532,
+        giwa_attestation: 91342,
+        dojang_playground: 91342,
+        mdl_kr_ownership: 84532,
+        mdl_kr_age: 84532,
+        mdl_kr_region: 84532,
+    },
+    local: {
+        coinbase_attestation: 84532,
+        coinbase_country_attestation: 84532,
+        oidc_domain_attestation: 84532,
+        giwa_attestation: 91342,
+        dojang_playground: 91342,
+        mdl_kr_ownership: 84532,
+        mdl_kr_age: 84532,
+        mdl_kr_region: 84532,
+    },
+};
 /**
  * Default deep link URL scheme for ZKProofport mobile app.
  * Used to construct deep link URLs that open the mobile app.
@@ -3963,6 +4006,10 @@ async function fetchVerificationKey(circuit, timeoutMs) {
  * Needs no setup from the caller: the verifier ships with this SDK and is
  * loaded on first use.
  *
+ * For `oidc_domain_attestation` it first checks the proof's RSA key against the
+ * provider's published JWKS (core's `checkOidcProviderKey`); a key the provider
+ * does not publish, or a JWKS that cannot be fetched, is `{ valid: false }`.
+ *
  * @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
@@ -3981,6 +4028,18 @@ async function fetchVerificationKey(circuit, timeoutMs) {
  */
 async function verifyProofOffChain(circuit, proof, publicInputs, options = {}) {
     const timeoutMs = options.timeoutMs ?? 30000;
+    if (!isCircuitId(circuit)) {
+        return { valid: false, error: `Unknown circuit '${circuit}'. Known: ${ALL_CIRCUIT_IDS.join(', ')}.` };
+    }
+    // Before Barretenberg, and for the same reason as on-chain: a proof can be
+    // mathematically valid and still mean nothing, because some circuits take
+    // their trust anchor as a public input the prover chooses. For OIDC that is
+    // the RSA key -- see core's oidcProviderKeys. Checked here so a dApp that
+    // verifies off-chain gets the same answer as one that verifies on-chain.
+    const issuer = await checkProofIssuer(circuit, publicInputs);
+    if (!issuer.ok) {
+        return { valid: false, error: issuer.error };
+    }
     // A REQUIRED dependency, loaded lazily.
     //
     // It was briefly an optional peer dependency, on the reasoning that the WASM
@@ -4121,22 +4180,32 @@ class ProofportSDK {
         this.pendingRequests = new Map();
         this.signer = null;
         this.socket = null;
+        /**
+         * Set by {@link ProofportSDK.create} from its environment preset. It decides
+         * which chain a proof is verified on when the dApp configured no verifier
+         * for the circuit; a custom-config SDK has none and must configure one.
+         */
+        this.environment = null;
         this.config = {
             scheme: config.scheme || DEFAULT_SCHEME,
             verifiers: config.verifiers || {},
         };
         this.relayUrl = config.relayUrl || '';
+        if (config.environment !== undefined) {
+            if (!Object.prototype.hasOwnProperty.call(VERIFICATION_CHAINS, config.environment)) {
+                throw new Error(`Unknown environment '${config.environment}'. Known: ${Object.keys(VERIFICATION_CHAINS).join(', ')}.`);
+            }
+            this.environment = config.environment;
+        }
     }
     // ============ Request Creation ============
     /**
      * @internal
-     * Creates a Coinbase KYC verification proof request.
-     *
-     * Generates a proof request for verifying Coinbase KYC status without revealing
-     * the actual attestation data. The proof confirms the user has passed Coinbase KYC
-     * while maintaining privacy through zero-knowledge proofs.
+     * Creates a proof request for a circuit whose dapp-side input is a scope
+     * (Coinbase KYC, OIDC domain, GIWA, Dojang), keeping that circuit's id.
      *
-     * @param inputs - Circuit inputs for Coinbase KYC
+     * @param circuit - The circuit requested; it is the request's circuit
+     * @param inputs - Circuit inputs; `scope` is required (and `domain` for OIDC)
      * @param inputs.scope - Application-specific scope (e.g., domain name)
      * @param options - Request configuration options
   
@@ -4151,7 +4220,7 @@ class ProofportSDK {
      *
      * @example
      * ```typescript
-     * const request = sdk.createCoinbaseKycRequest({
+     * const request = sdk.createScopedRequest('coinbase_attestation', {
      *   scope: 'myapp.com'
      * }, {
      *   dappName: 'My DApp',
@@ -4161,13 +4230,34 @@ class ProofportSDK {
      * const deepLink = sdk.getDeepLinkUrl(request);
      * ```
      */
-    createCoinbaseKycRequest(inputs, options = {}) {
-        if (!inputs.scope) {
-            throw new Error('scope is required for coinbase_attestation circuit');
+    createScopedRequest(circuit, inputs, options = {}) {
+        const scope = inputs.scope;
+        if (typeof scope !== 'string' || scope.trim() === '') {
+            throw new Error(`scope is required for ${circuit} circuit`);
+        }
+        if (circuit === 'oidc_domain_attestation') {
+            const domain = inputs.domain;
+            if (typeof domain !== 'string' || domain.trim() === '') {
+                throw new Error('domain is required for oidc_domain_attestation circuit');
+            }
+        }
+        const action = inputs.action;
+        const binding = circuitActionBinding(circuit);
+        if (binding === 'none' && action !== undefined) {
+            throw new Error(`${circuit} has no action inputs, so an action sent with it would not be proved.`);
+        }
+        if (binding === 'required' || (binding === 'optional' && action !== undefined)) {
+            const actionError = validateTypedAction(action);
+            if (actionError)
+                throw new Error(`${actionError} (circuit: ${circuit})`);
         }
         const request = {
             requestId: generateRequestId(),
-            circuit: 'coinbase_attestation',
+            // The circuit asked for, always. This used to be the literal
+            // 'coinbase_attestation', and every circuit that was not country or mDL
+            // was routed here -- a GIWA, Dojang or OIDC request silently became a
+            // Coinbase KYC request.
+            circuit,
             inputs,
             message: options.message,
             dappName: options.dappName,
@@ -4264,16 +4354,17 @@ class ProofportSDK {
      * ```
      */
     createProofRequest(circuit, inputs, options = {}) {
-        if (circuit === 'coinbase_country_attestation') {
-            return this.createCoinbaseCountryRequest(inputs, options);
-        }
-        else if (circuit === 'mdl_kr_ownership' ||
-            circuit === 'mdl_kr_age' ||
-            circuit === 'mdl_kr_region') {
-            return this.createMdlKrRequest(circuit, inputs, options);
+        if (!isCircuitId(circuit)) {
+            throw new Error(`Unknown circuit '${circuit}'. Known: ${ALL_CIRCUIT_IDS.join(', ')}.`);
         }
-        else {
-            return this.createCoinbaseKycRequest(inputs, options);
+        const builder = ProofportSDK.REQUEST_BUILDERS[circuit];
+        switch (builder) {
+            case 'country':
+                return this.createCoinbaseCountryRequest(inputs, options);
+            case 'mdl':
+                return this.createMdlKrRequest(circuit, inputs, options);
+            case 'scoped':
+                return this.createScopedRequest(circuit, inputs, options);
         }
     }
     /**
@@ -4650,8 +4741,24 @@ class ProofportSDK {
      */
     async verifyOnChain(circuit, proof, publicInputs, providerOrSigner) {
         const parsedProof = parseProofForOnChain(proof, publicInputs, publicInputs.length);
-        const customVerifier = this.config.verifiers[circuit];
-        return verifyProofOnChain(circuit, parsedProof, providerOrSigner, customVerifier);
+        return verifyProofOnChain(circuit, parsedProof, providerOrSigner, this.verifierTarget(circuit));
+    }
+    /**
+     * The verifier for a circuit: the one the dApp configured, otherwise the
+     * pinned deployment on the chain this SDK's environment verifies that
+     * circuit on. `undefined` when neither exists, which core reports as an
+     * error. Never anything a proof response said.
+     */
+    verifierTarget(circuit) {
+        const configured = this.config.verifiers[circuit];
+        if (configured)
+            return configured;
+        if (this.environment === null)
+            return undefined;
+        const chains = VERIFICATION_CHAINS[this.environment];
+        if (!Object.prototype.hasOwnProperty.call(chains, circuit))
+            return undefined;
+        return { chainId: chains[circuit] };
     }
     /**
      * Verifies a proof response on-chain using the deployed verifier contract.
@@ -4692,12 +4799,14 @@ class ProofportSDK {
             return { valid: false, error: 'Invalid or incomplete response' };
         }
         const parsedProof = parseProofForOnChain(response.proof, response.publicInputs, response.publicInputs.length);
-        const customVerifier = this.config.verifiers[response.circuit];
-        const responseVerifier = {
+        // The response's verifierAddress and chainId are a claim to check, never
+        // the contract to call: whoever wrote the response would otherwise pick
+        // the judge. A claim that differs from the pinned or configured verifier
+        // is refused.
+        return verifyProofOnChain(response.circuit, parsedProof, providerOrSigner, this.verifierTarget(response.circuit), {
             verifierAddress: response.verifierAddress,
             chainId: response.chainId,
-        };
-        return verifyProofOnChain(response.circuit, parsedProof, providerOrSigner, customVerifier, responseVerifier);
+        });
     }
     /**
      * Verifies a proof response off-chain, against the circuit's verification key.
@@ -4748,8 +4857,17 @@ class ProofportSDK {
      * ```
      */
     getVerifierAddress(circuit) {
-        const customVerifier = this.config.verifiers[circuit];
-        return getVerifierAddress(circuit, customVerifier);
+        return this.requireVerifier(circuit).address;
+    }
+    /** The configured or pinned verifier, or an error saying why there is none. */
+    requireVerifier(circuit) {
+        const target = this.verifierTarget(circuit);
+        if (!target) {
+            throw new Error(`No verifier configured for circuit '${circuit}'. Configure one in the SDK's verifiers option, or create the SDK with ProofportSDK.create() to use the pinned deployment.`);
+        }
+        if ('address' in target)
+            return { address: target.address, chainId: target.chainId };
+        return { address: getPinnedVerifier(circuit, target.chainId).address, chainId: target.chainId };
     }
     /**
      * Gets the blockchain chain ID where the verifier contract is deployed.
@@ -4769,8 +4887,7 @@ class ProofportSDK {
      * ```
      */
     getVerifierChainId(circuit) {
-        const customVerifier = this.config.verifiers[circuit];
-        return getVerifierChainId(circuit, customVerifier);
+        return this.requireVerifier(circuit).chainId;
     }
     /**
      * Gets metadata for a specific circuit type.
@@ -4917,17 +5034,20 @@ class ProofportSDK {
      */
     static create(envOrConfig) {
         if (typeof envOrConfig === 'undefined') {
-            return new ProofportSDK({ relayUrl: RELAY_URLS.production });
+            return ProofportSDK.forEnvironment('production');
         }
         if (typeof envOrConfig === 'string') {
-            const relayUrl = RELAY_URLS[envOrConfig];
-            if (!relayUrl) {
-                throw new Error(`Unknown environment: ${envOrConfig}. Use 'production', 'staging', or 'local'.`);
-            }
-            return new ProofportSDK({ relayUrl });
+            return ProofportSDK.forEnvironment(envOrConfig);
         }
         return new ProofportSDK(envOrConfig);
     }
+    /** @internal An SDK on an environment preset's relay, verifying on that environment's chains. */
+    static forEnvironment(env) {
+        if (!Object.prototype.hasOwnProperty.call(RELAY_URLS, env)) {
+            throw new Error(`Unknown environment: ${env}. Use 'production', 'staging', or 'local'.`);
+        }
+        return new ProofportSDK({ relayUrl: RELAY_URLS[env], environment: env });
+    }
     /**
      * Detects if the code is running on a mobile device.
      *
@@ -5061,7 +5181,10 @@ class ProofportSDK {
     // calling createRelayRequest() for it with no signer got no local error and
     // a relay 401 two round trips later.
     static needsWalletSignature(circuit) {
-        return CIRCUIT_NEEDS_WALLET_SIGNATURE[circuit] === true;
+        if (!isCircuitId(circuit)) {
+            throw new Error(`Unknown circuit '${circuit}'. Expected: ${ALL_CIRCUIT_IDS.join(', ')}`);
+        }
+        return CIRCUIT_NEEDS_WALLET_SIGNATURE[circuit];
     }
     async createRelayRequest(circuit, inputs, options = {}) {
         if (!this.relayUrl) {
@@ -5435,6 +5558,21 @@ class ProofportSDK {
         return extractDomainFromPublicInputs(publicInputs, circuit);
     }
 }
+/**
+ * How each circuit's request is built and checked. Keyed by circuit id and
+ * exhaustive over it, so a new circuit is a compile error here instead of
+ * falling through to another circuit's builder.
+ */
+ProofportSDK.REQUEST_BUILDERS = {
+    coinbase_attestation: 'scoped',
+    coinbase_country_attestation: 'country',
+    oidc_domain_attestation: 'scoped',
+    giwa_attestation: 'scoped',
+    dojang_playground: 'scoped',
+    mdl_kr_ownership: 'mdl',
+    mdl_kr_age: 'mdl',
+    mdl_kr_region: 'mdl',
+};
 
 export { ProofportSDK, RELAY_TERMINAL_STATUSES, ProofportSDK as default, isTerminalRelayStatus, verifyProofOffChain };
 //# sourceMappingURL=index.esm.js.map