@zkproofport-app/sdk 0.2.8 → 0.2.10

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. Supports Coinbase KYC/Country attestations and OIDC domain attestations (Google, Microsoft 365).
+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.
 
 ## How It Works
 
@@ -21,23 +21,23 @@ TypeScript SDK for requesting zero-knowledge proofs from the [ZKProofport](https
        │  │                                    relay callback
        │  v
        │  ┌──────────────────────────────────────────────────┐
-       │  │  SDK receives result (WebSocket / polling)       │
+       │  │  SDK receives result (WebSocket / polling)        │
        │  │  (proof, publicInputs, status)                    │
        │  └─────────────────────┬────────────────────────────┘
        │                        │
        v                        v
 ┌──────────────┐     ┌──────────────────┐     ┌───────────────────┐
 │  Verify      │────>│  On-chain verify  │────>│  Access granted   │
-│  on-chain    │     │  (Base Mainnet)   │     │  or denied        │
+│  on-chain    │     │  (Base)           │     │  or denied        │
 └──────────────┘     └──────────────────┘     └───────────────────┘
 ```
 
-1. Your app sets a wallet signer and creates a proof request via the SDK
-2. The SDK authenticates with the relay using challenge-signature (EIP-191) and gets a tracked request ID
-3. The SDK displays a QR code (desktop) or opens the deep link (mobile)
-4. The user opens the ZKProofport app, which generates the ZK proof
-5. The proof result flows back through the relay to your app via WebSocket (or polling)
-6. Your app verifies the proof on-chain
+1. Your app creates a proof request through the SDK
+2. The SDK asks the relay for a one-time challenge and a tracked request ID. For the Coinbase circuits it also signs that challenge with your wallet signer (EIP-191); the OIDC and mDL circuits need no signature
+3. Your app shows the returned deep link as a QR code (desktop) or navigates to it (mobile)
+4. The user opens the ZKProofport app, which generates the ZK proof on-device
+5. The proof result flows back through the relay to your app over WebSocket (HTTP polling as fallback)
+6. Your app verifies the proof on-chain, then reads its public inputs to confirm it answers the question that was asked
 
 ## Installation
 
@@ -51,16 +51,19 @@ npm install @zkproofport-app/sdk
 npm install ethers
 ```
 
+`ethers` v6 is recommended; v5 also works. Real-time delivery uses `socket.io-client`, which ships as a dependency of this package — nothing extra to install.
+
 ## Quick Start
 
 ```typescript
 import { ProofportSDK } from '@zkproofport-app/sdk';
+import type { CircuitType, ProofResponse } from '@zkproofport-app/sdk';
 import { BrowserProvider } from 'ethers';
 
 // 1. Initialize
 const sdk = ProofportSDK.create();
 
-// 2. Set wallet signer (ethers v6 Signer)
+// 2. Set wallet signer (ethers v6 Signer) — required for the Coinbase circuits
 const provider = new BrowserProvider(window.ethereum);
 const signer = await provider.getSigner();
 sdk.setSigner(signer);
@@ -72,31 +75,41 @@ const relay = await sdk.createRelayRequest('coinbase_attestation', {
 
 // 4. Show QR code to user
 const qrDataUrl = await sdk.generateQRCode(relay.deepLink);
-document.getElementById('qr').src = qrDataUrl;
+(document.getElementById('qr') as HTMLImageElement).src = qrDataUrl;
 
 // 5. Wait for proof (WebSocket primary, HTTP polling fallback)
 const result = await sdk.waitForProof(relay.requestId);
 
 if (result.status === 'completed') {
-  // 6. Verify on-chain
-  const verification = await sdk.verifyOnChain(
-    result.circuit,
-    result.proof,
-    result.publicInputs
-  );
+  // 6. Verify on-chain — the relay result carries the verifier to call
+  const response: ProofResponse = {
+    requestId: result.requestId,
+    circuit: result.circuit as CircuitType,
+    status: 'completed',
+    proof: result.proof,
+    publicInputs: result.publicInputs,
+    verifierAddress: result.verifierAddress,
+    chainId: result.chainId,
+  };
+
+  const verification = await sdk.verifyResponseOnChain(response);
   console.log('Valid:', verification.valid);
 }
 ```
 
 ## Supported Circuits
 
+Circuit IDs are canonical and case-sensitive — pass them exactly as written here. `sdk.getSupportedCircuits()` returns the same list at runtime.
+
 ### `coinbase_attestation`
 
-Proves that a user has completed Coinbase KYC identity verification without revealing any personal information.
+Proves that a user has completed Coinbase KYC identity verification without revealing any personal information. Requires a wallet signer.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `scope` | `string` | Yes | Application-specific identifier (e.g., your domain). Ensures proof uniqueness per app. |
+| `userAddress` | `string` | No | Address to prove the attestation for. Omit it and the mobile app asks the user to connect a wallet. |
+| `rawTransaction` | `string` | No | Pre-fetched attestation transaction data. Omit it and the app fetches the attestation itself. |
 
 ```typescript
 const relay = await sdk.createRelayRequest('coinbase_attestation', {
@@ -106,13 +119,15 @@ const relay = await sdk.createRelayRequest('coinbase_attestation', {
 
 ### `coinbase_country_attestation`
 
-Proves a user's country based on Coinbase verification, supporting inclusion and exclusion checks, without revealing the actual country.
+Proves a user's country based on Coinbase verification, supporting inclusion and exclusion checks, without revealing the actual country. Requires a wallet signer.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `scope` | `string` | Yes | Application-specific identifier |
 | `countryList` | `string[]` | Yes | ISO 3166-1 alpha-2 country codes (e.g., `['US', 'KR']`) |
 | `isIncluded` | `boolean` | Yes | `true` = prove user IS from listed countries; `false` = prove user is NOT |
+| `userAddress` | `string` | No | Address to prove the attestation for (optional, as above) |
+| `rawTransaction` | `string` | No | Pre-fetched attestation transaction data (optional, as above) |
 
 ```typescript
 const relay = await sdk.createRelayRequest('coinbase_country_attestation', {
@@ -124,7 +139,7 @@ const relay = await sdk.createRelayRequest('coinbase_country_attestation', {
 
 ### `oidc_domain_attestation`
 
-Prove email domain affiliation via OIDC Sign-In. The mobile app handles authentication and proof generation entirely on-device — the user's email is never revealed.
+Prove email domain affiliation via OIDC Sign-In. The mobile app handles authentication and proof generation entirely on-device — the user's email is never revealed. No wallet signer is required.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -165,12 +180,12 @@ const relay = await sdk.createRelayRequest('oidc_domain_attestation', {
 
 ### `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 signature is required.
+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.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `scope` | `string` | Yes | Application-specific identifier for proof uniqueness |
-| `discloseFlags` | `number` | No | Attribute disclosure bitmask `0x00`–`0x0F` (`0x01` name, `0x02` birth, `0x04` sex, `0x08` phone). Omit or `0` for a fully anonymous ownership proof. |
+| `scope` | `string` | Yes | Application-specific identifier for proof uniqueness. Non-empty, 256 characters or fewer, no control characters. |
+| `discloseFlags` | `number` | No | Attribute disclosure bitmask, integer 0–15 (`0x01` name, `0x02` birth, `0x04` sex, `0x08` phone). Omit or `0` for a fully anonymous ownership proof. |
 
 ```typescript
 // Anonymous "holds a valid Korean mobile ID" proof
@@ -181,12 +196,12 @@ const relay = await sdk.createRelayRequest('mdl_kr_ownership', {
 
 ### `mdl_kr_age`
 
-Proves the user is at least `ageThreshold` years old according to their Korean mobile driver's license, without revealing the birth date.
+Proves the user is at least `ageThreshold` years old according to their Korean mobile driver's license, without revealing the birth date. No wallet signer is required.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `scope` | `string` | Yes | Application-specific identifier |
-| `ageThreshold` | `number` | Yes | Minimum age to prove (integer 1–150, e.g. `19` for Korean adult verification) |
+| `scope` | `string` | Yes | Application-specific identifier (same rules as above) |
+| `ageThreshold` | `number` | Yes | Minimum age to prove — integer between 1 and 150 (e.g. `19` for Korean adult verification) |
 
 ```typescript
 const relay = await sdk.createRelayRequest('mdl_kr_age', {
@@ -197,12 +212,12 @@ const relay = await sdk.createRelayRequest('mdl_kr_age', {
 
 ### `mdl_kr_region`
 
-Proves the user's registered address is in the specified si/do region without revealing the full address.
+Proves the user's registered address is in the specified si/do region without revealing the full address. No wallet signer is required.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `scope` | `string` | Yes | Application-specific identifier |
-| `targetRegion` | `string` | Yes | Region (si/do) to prove residency in, in Korean (e.g. `'경기도'`, `'서울특별시'`) |
+| `scope` | `string` | Yes | Application-specific identifier (same rules as above) |
+| `targetRegion` | `string` | Yes | Region (si/do) to prove residency in, in Korean (e.g. `'경기도'`, `'서울특별시'`). Non-empty, 256 characters or fewer, no control characters. |
 
 ```typescript
 const relay = await sdk.createRelayRequest('mdl_kr_region', {
@@ -211,7 +226,9 @@ const relay = await sdk.createRelayRequest('mdl_kr_region', {
 });
 ```
 
-> The mDL circuits do not require `setSigner()` — the proof is bound to the license via an on-device nullifier (`nullifier_value` public input), not a wallet address. Use `sdk.extractNullifier(result.publicInputs, result.circuit)` for sybil-resistant user identification.
+> mDL inputs are checked before the request leaves your process: a missing `scope`, an out-of-range `discloseFlags`, a non-integer `ageThreshold` or an empty `targetRegion` throws locally instead of coming back as a relay error.
+
+> The mDL circuits do not require `setSigner()` — the proof is bound to the license via an on-device nullifier (`nullifier_value` public input), not a wallet address. Use `sdk.extractNullifier(publicInputs, circuit)` for sybil-resistant user identification.
 
 ## Integration Guide
 
@@ -223,11 +240,11 @@ import { ProofportSDK } from '@zkproofport-app/sdk';
 const sdk = ProofportSDK.create();
 ```
 
-`ProofportSDK.create()` returns an SDK instance pre-configured with the relay server and verifier contracts. No configuration needed.
+`ProofportSDK.create()` returns an SDK instance pre-configured with the relay server. No configuration needed.
 
 ### Step 2: Set Wallet Signer
 
-The SDK uses challenge-signature authentication (EIP-191). Set a wallet signer that can sign messages:
+The Coinbase circuits (`coinbase_attestation`, `coinbase_country_attestation`) authenticate with a signed challenge (EIP-191). Set a wallet signer that can sign messages:
 
 ```typescript
 import { BrowserProvider } from 'ethers';
@@ -241,20 +258,20 @@ The `WalletSigner` interface requires two methods:
 
 ```typescript
 interface WalletSigner {
-  signMessage(message: string): Promise<string>;
+  signMessage(message: string | Uint8Array): Promise<string>;
   getAddress(): Promise<string>;
 }
 ```
 
 Any ethers v5/v6 `Signer` is compatible.
 
-> **OIDC Domain note:** Wallet signer is not required for OIDC Domain proofs. See Step 3 for OIDC-specific usage.
+> **When you can skip this step:** the OIDC Domain and the three mDL circuits never sign a challenge. Calling `createRelayRequest` for those circuits without a signer works. Calling it for a Coinbase circuit without one throws `Signer not set. Call setSigner() first. Wallet signature is required for this circuit.`
 
 #### About challenge-signature
 
-The challenge-signature mechanism was developed **for relay nonce replay prevention**. Each challenge is one-time use and consumed immediately. The signer's recovered address is recorded as `clientId` in relay server logs, which helps the relay operator track requests.
+The challenge-signature mechanism exists **for replay prevention**. Each challenge is one-time use and is consumed immediately. The relay recovers the signer's address from the signature and logs it; the address is not fed into the circuit, and it does not have to be the address that holds the attestation — the mobile app decides that, from `userAddress` or from the wallet the user connects.
 
-For server-side or headless environments, using an ephemeral random wallet is fine. A persistent wallet (fixed private key) is **not recommended** as it adds unnecessary key management overhead with no functional benefit.
+So for server-side or headless environments an ephemeral random wallet is fine. A persistent wallet (fixed private key) is **not recommended**: it adds key management for no functional benefit.
 
 ```typescript
 import { Wallet } from 'ethers';
@@ -265,7 +282,7 @@ sdk.setSigner(Wallet.createRandom());
 
 ### Step 3: Create Request (via Relay)
 
-`createRelayRequest` authenticates with the relay (challenge-signature), creates a tracked proof request, and returns a deep link.
+`createRelayRequest` fetches a challenge and request ID from the relay, signs the challenge when the circuit needs it, creates a tracked proof request, and returns a deep link.
 
 ```typescript
 const relay = await sdk.createRelayRequest('coinbase_attestation', {
@@ -275,6 +292,7 @@ const relay = await sdk.createRelayRequest('coinbase_attestation', {
   dappIcon: 'https://myapp.com/icon.png',
   message: 'Verify your identity to continue',
   nonce: 'unique-nonce-123',  // Optional: replay prevention
+  returnScheme: 'mydapp://',  // Optional: mobile-only, see below
 });
 
 // relay.requestId  — Relay-issued UUID
@@ -283,11 +301,56 @@ const relay = await sdk.createRelayRequest('coinbase_attestation', {
 // relay.pollUrl    — Relative URL for HTTP polling
 ```
 
+Every field of the third argument is optional: `message`, `dappName` and `dappIcon` are shown to the user in the ZKProofport app, `nonce` is a value of your own choosing that the relay refuses to accept twice, and `returnScheme` is described next.
+
+#### Switching back to your app: `returnScheme`
+
+By default the user stays in the ZKProofport app after generating a proof and switches back to your app themselves. Pass `returnScheme` and the ZKProofport app brings your app to the foreground once the proof has been delivered — the same handoff a wallet performs after a signature.
+
+```typescript
+// Native app: your own registered scheme
+await sdk.createRelayRequest('coinbase_attestation', { scope: 'myapp.com' }, {
+  returnScheme: 'mydapp://',
+});
+
+// Web app: your own origin
+await sdk.createRelayRequest('coinbase_attestation', { scope: 'myapp.com' }, {
+  returnScheme: 'https://myapp.com',
+});
+```
+
+**Only set it in the mobile deep-link flow.** The switch happens on the phone that generated the proof, so it makes sense only when that phone is also where the user started — i.e. when you navigated the browser to `relay.deepLink` on the same device. In the desktop QR flow the user is watching the desktop screen while the proof happens on their phone; opening a page or an app on the phone at that moment surfaces something nobody asked for. Gate it:
+
+```typescript
+const relay = await sdk.createRelayRequest('coinbase_attestation', { scope: 'myapp.com' },
+  ProofportSDK.isMobile() ? { returnScheme: 'https://myapp.com' } : {});
+```
+
+`returnScheme` is **not** a return address. It says which app to open, nothing more — the proof still reaches you the usual way, through `waitForProof()` / `waitForResult()`, and the ZKProofport app never posts anything to it.
+
+Two shapes are accepted, and nothing else:
+
+| Form | Example | Notes |
+|------|---------|-------|
+| Bare custom scheme | `'mydapp://'` | An RFC 3986 scheme followed by exactly `://` |
+| https origin | `'https://myapp.com'`, `'https://myapp.com:8443'` | Host (and optional port) only |
+
+Anything else throws before the SDK makes a single network call — no challenge is consumed, so nothing is wasted on a typo:
+
+- a path, query string or fragment (`'mydapp://transfer?to=0x...'`, `'https://myapp.com/done'`), which is what keeps a request from driving your app to a specific action
+- an empty or whitespace-containing value, or one longer than 128 characters
+- userinfo (`'https://user:pass@myapp.com'`) and non-ASCII hosts (use punycode)
+- `http://` and other schemes the OS treats specially: `about`, `blob`, `content`, `data`, `facetime`, `facetime-audio`, `file`, `ftp`, `intent`, `javascript`, `jar`, `mailto`, `sms`, `tel`, `vbscript`
+
+The value is matched case-insensitively and stored lowercased by the relay.
+
+Omit `returnScheme` and nothing changes: the request is created without it and the user stays in the ZKProofport app when the proof is done. There is no auto-switch when proof generation fails either — the error has to be read in the ZKProofport app first.
+
 **OIDC Domain Attestation:**
 
 ```typescript
 // Email domain verification
-const relay = await sdk.createRelayRequest('oidc_domain_attestation', {
+const relayDomain = await sdk.createRelayRequest('oidc_domain_attestation', {
   domain: 'company.com',
   scope: 'myapp.com',
 }, {
@@ -297,24 +360,22 @@ const relay = await sdk.createRelayRequest('oidc_domain_attestation', {
 });
 
 // Organization membership verification (Google Workspace)
-const relay = await sdk.createRelayRequest('oidc_domain_attestation', {
+const relayGoogle = await sdk.createRelayRequest('oidc_domain_attestation', {
   domain: 'company.com',
   scope: 'myapp.com',
   provider: 'google',
 }, {
   dappName: 'My DApp',
-  dappIcon: 'https://myapp.com/icon.png',
   message: 'Verify your organization membership',
 });
 
 // Organization membership verification (Microsoft 365)
-const relay = await sdk.createRelayRequest('oidc_domain_attestation', {
+const relayMicrosoft = await sdk.createRelayRequest('oidc_domain_attestation', {
   domain: 'company.com',
   scope: 'myapp.com',
   provider: 'microsoft',
 }, {
   dappName: 'My DApp',
-  dappIcon: 'https://myapp.com/icon.png',
   message: 'Verify your organization membership',
 });
 ```
@@ -327,13 +388,15 @@ Generate a QR code from the relay deep link for the user to scan with the ZKProo
 
 ```typescript
 const qrDataUrl = await sdk.generateQRCode(relay.deepLink, {
-  width: 400,
+  width: 400,          // pixels (default: 300)
   darkColor: '#1a1a1a',
-  margin: 4,
+  margin: 4,           // quiet zone in modules (default: 2)
 });
-document.getElementById('qr').src = qrDataUrl;
+(document.getElementById('qr') as HTMLImageElement).src = qrDataUrl;
 ```
 
+`QRCodeOptions` accepts `width` (default `300`), `margin` (default `2`), `darkColor` (default `'#000000'`), `lightColor` (default `'#ffffff'`) and `errorCorrectionLevel` (`'L' | 'M' | 'Q' | 'H'`, default `'M'`).
+
 **Other QR formats:**
 
 ```typescript
@@ -343,10 +406,12 @@ const svg = await sdk.generateQRCodeSVG(relay.deepLink);
 // Render to canvas
 await sdk.renderQRCodeToCanvas(canvasElement, relay.deepLink, { width: 400 });
 
-// Check if data fits QR limits
+// Check if data fits QR limits (2953 bytes)
 const { size, withinLimit } = sdk.checkQRCodeSize(relay.deepLink);
 ```
 
+All three generators throw `QR code data too large (… bytes). Maximum is 2953 bytes.` rather than emitting an unscannable image. Relay deep links are far below that; the check matters if you build your own link.
+
 **Mobile:** On mobile browsers, redirect directly to the deep link instead of showing a QR code:
 
 ```typescript
@@ -357,7 +422,7 @@ if (ProofportSDK.isMobile()) {
 
 ### Step 5: Wait for Proof
 
-**`waitForProof` (recommended)** — Uses WebSocket (Socket.IO) for instant delivery, with automatic HTTP polling fallback if `socket.io-client` is not installed or connection fails.
+**`waitForProof` (recommended)** — Uses WebSocket (Socket.IO) for instant delivery and falls back to HTTP polling automatically if the socket connection fails.
 
 ```typescript
 const result = await sdk.waitForProof(relay.requestId, {
@@ -368,6 +433,8 @@ const result = await sdk.waitForProof(relay.requestId, {
 });
 ```
 
+`waitForProof` settles once the request reaches a terminal state. Step 6 walks through the object it hands back, field by field, and through the states that are not terminal.
+
 **Alternative: Subscribe to real-time updates directly:**
 
 ```typescript
@@ -387,7 +454,7 @@ const unsubscribe = await sdk.subscribe(relay.requestId, {
 
 ```typescript
 // Single poll
-const result = await sdk.pollResult(relay.requestId);
+const once = await sdk.pollResult(relay.requestId);
 
 // Poll until terminal state
 const result = await sdk.waitForResult(relay.requestId, {
@@ -397,17 +464,137 @@ const result = await sdk.waitForResult(relay.requestId, {
 });
 ```
 
-### Step 6: Verify On-Chain
+When you are done, `sdk.disconnect()` closes any open socket.
+
+### Step 6: Read the Result
+
+`waitForProof()`, `waitForResult()` and `pollResult()` all hand back the same object, a `RelayProofResult`. A completed one looks like this (long values elided):
+
+```typescript
+{
+  requestId: '9f1c8a02-4e2b-4f0a-9c3e-1d5a7b0e2f44',
+  status: 'completed',
+  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
+  deepLink: 'zkproofport://proof-request?data=…',
+  createdAt: '2026-02-07T09:14:02.101Z',
+  updatedAt: '2026-02-07T09:14:48.902Z',
+}
+```
+
+| Field | Type | Present when | What it is |
+|-------|------|--------------|------------|
+| `requestId` | `string` | always | The relay-issued id you waited on. Echoed back so one handler can serve many requests. |
+| `status` | `string` | always | Lifecycle state — see below. |
+| `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. |
+| `error` | `string` | failures | Human-readable reason from the mobile app or the relay. |
+| `deepLink` | `string` | polling path only | The deep link the request was created with. |
+| `createdAt`, `updatedAt` | `string` | polling path only | ISO timestamps of creation and last update. |
+
+The last three come from the relay's polling endpoint. `waitForProof()` normally resolves over the WebSocket, whose payload does not carry them, so do not build logic on their presence.
+
+#### What `status` can be
+
+| `status` | Terminal | What happened | What you do |
+|----------|----------|---------------|-------------|
+| `'pending'` | no | The request exists; no proof yet | Keep waiting — `waitForProof()` does that for you |
+| `'completed'` | yes | A proof came back | `proof`, `publicInputs`, `verifierAddress` and `chainId` are set. Verify it (Step 7) before trusting anything in it |
+| `'error'` | yes | The app could not produce a proof — no attestation on that address, sign-in refused, generation failed | Read `error`, show it, let the user start over |
+| `'failed'` | yes | Same meaning and same handling as `'error'` | Handle the pair; the type declares `'failed'`, the app sends `'error'` |
+| `'cancelled'` | see below | The user declined the request in the ZKProofport app | Reset your UI |
+
+`RelayProofResult` declares `status` as `'pending' | 'completed' | 'failed'`, which is narrower than what the relay can deliver, so TypeScript rejects a direct comparison against `'error'`. Widen it once and branch on the string:
+
+```typescript
+const status: string = result.status;
+
+if (status === 'completed') {
+  // verify it
+} else if (status === 'error' || status === 'failed') {
+  showError(result.error ?? 'Proof generation failed');
+}
+```
+
+`waitForProof()` settles on `'completed'`, `'error'` and `'failed'`. It does **not** settle on `'cancelled'` — a cancellation arrives as a status update, and if you ignore it the call sits there until `timeoutMs` expires. Watch for it if you want to drop the QR dialog the moment the user says no:
+
+```typescript
+const result = await sdk.waitForProof(relay.requestId, {
+  onStatusChange: (update) => {
+    if (update.status === 'cancelled') {
+      // The user declined in the app. This promise will not settle on its own.
+      hideQrDialog();
+    }
+  },
+});
+```
+
+`waitForResult()`, the polling path, is narrower still: it returns only on `'completed'` and `'failed'`, and keeps polling through `'error'` and `'cancelled'` until `timeoutMs`. Prefer `waitForProof()`, or drive `pollResult()` in a loop of your own if you want to decide what counts as terminal.
+
+#### What is not on the result
+
+- **No `nullifier` field.** The nullifier is inside `publicInputs`. Read it with `sdk.extractNullifier()` — Step 8.
+- **No `numPublicInputs` field.** It is `publicInputs.length`.
+- **A `'completed'` result can arrive with `proof` and `publicInputs` missing.** That means the relay's buffered copy of the result has expired — results are kept for a short window only. There is nothing left to fetch for that `requestId`; the user has to make a new request.
+
+#### Retry, or show the user?
+
+| Situation | Retry automatically | Show the user |
+|-----------|--------------------|----------------|
+| `createRelayRequest()` throws `Too many requests. Please try again later.` | Yes, with backoff | No |
+| Network failure reaching the relay | Yes | No |
+| `pollResult()` throws `Request not found or expired` | No — that id is gone | Yes, ask them to start again |
+| `status: 'error'` / `'failed'` | No — a retry re-runs the same failing thing | Yes: `error` says what went wrong, and it is usually the user's move (connect the right wallet, sign in, use the device holding the licence) |
+| `status: 'cancelled'` | No | Nothing to say — they just declined |
+| `waitForProof()` timeout | Only if the user asks for it | Yes |
+| `verifyResponseOnChain()` returns `{ valid: false }` | No | Treat it as a rejected proof, not an outage — Step 7 |
+
+#### `ProofResponse` — the shape on-chain verification takes
+
+`verifyResponseOnChain()` does not take the relay result directly. It takes a `ProofResponse`, which you build from it:
+
+| `ProofResponse` field | Type | Required | Where it comes from |
+|-----------------------|------|----------|---------------------|
+| `requestId` | `string` | Yes | `result.requestId` |
+| `circuit` | `CircuitType` | Yes | `result.circuit`, narrowed — the relay types it as a plain `string` |
+| `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 |
+| `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 |
+
+There is no `nullifier` field here either.
+
+### Step 7: Verify On-Chain
 
 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:
+
 ```typescript
+import type { CircuitType, ProofResponse } from '@zkproofport-app/sdk';
+
 if (result.status === 'completed') {
-  const verification = await sdk.verifyOnChain(
-    result.circuit,
-    result.proof,
-    result.publicInputs
-  );
+  const response: ProofResponse = {
+    requestId: result.requestId,
+    circuit: result.circuit as CircuitType,
+    status: 'completed',
+    proof: result.proof,
+    publicInputs: result.publicInputs,
+    verifierAddress: result.verifierAddress,
+    chainId: result.chainId,
+  };
+
+  const verification = await sdk.verifyResponseOnChain(response);
 
   if (verification.valid) {
     console.log('Proof verified on-chain!');
@@ -417,47 +604,107 @@ if (result.status === 'completed') {
 }
 ```
 
-**Or verify from a `ProofResponse` object:**
+The SDK connects to the right network on its own. Pass your own ethers `Provider` or `Signer` as the second argument if you would rather use your existing connection:
 
 ```typescript
-const verification = await sdk.verifyResponseOnChain(response);
+const verification = await sdk.verifyResponseOnChain(response, myProvider);
 ```
 
-### Step 7: Extract Scope, Nullifier, and Domain
+`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.
+
+`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.
 
-After verification, extract data from the public inputs:
+> **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`.
+
+### Step 8: Extract Scope, Nullifier, and Domain
+
+A verified proof tells you the public inputs are genuine. It does not tell you what they say. Reading them is a separate step, and it is the step that decides whether the proof answers the question you asked.
+
+Do it **after** `verifyResponseOnChain()` returns `valid: true`. These helpers are plain parsers — they will happily decode an array that no verifier has ever seen.
 
 ```typescript
-if (result.status === 'completed') {
-  // Extract scope — the keccak256 hash of the scope string you provided
-  const scope = sdk.extractScope(result.publicInputs, result.circuit);
+import type { CircuitType } from '@zkproofport-app/sdk';
+
+if (result.status === 'completed' && result.publicInputs && result.circuit) {
+  const circuit = result.circuit as CircuitType;
+
+  // Extract scope — the bytes32 scope value carried in the public inputs
+  const scope = sdk.extractScope(result.publicInputs, circuit);
 
   // Extract nullifier — a unique, deterministic hash per user + scope
   // Same user with the same scope always produces the same nullifier
-  const nullifier = sdk.extractNullifier(result.publicInputs, result.circuit);
+  const nullifier = sdk.extractNullifier(result.publicInputs, circuit);
 
-  console.log('Scope:', scope);       // '0x7a6b70726f...'
+  console.log('Scope:', scope);         // '0x7a6b70726f...'
   console.log('Nullifier:', nullifier); // '0xabc123...'
 
   // Extract domain — only for OIDC Domain Attestation
-  if (result.circuit === 'oidc_domain_attestation') {
-    const domain = sdk.extractDomain(result.publicInputs, result.circuit);
+  if (circuit === 'oidc_domain_attestation') {
+    const domain = sdk.extractDomain(result.publicInputs, circuit);
     console.log('Domain:', domain); // 'example.com'
   }
 }
 ```
 
-The **nullifier** serves as a privacy-preserving user identifier:
-- Deterministic: same user + same scope = same nullifier (enables duplicate detection)
-- Privacy-preserving: the wallet address (Coinbase) or email (OIDC) is never revealed
-- Scope-bound: different scopes produce different nullifiers for the same user
+All three return `null` rather than throwing when the public inputs are too short for the circuit's layout. Pass the wrong circuit id and you get no error at all, just the wrong 32 entries decoded into a plausible-looking value — always pass the `circuit` the result came with.
+
+#### Check the scope
+
+Every circuit publishes `scope` as `keccak256` of the scope string you sent. Comparing it is how you find out that the proof was made for *your* request and not replayed from someone else's app:
+
+```typescript
+import { keccak256, toUtf8Bytes } from 'ethers';
+
+const expectedScope = keccak256(toUtf8Bytes('myapp.com'));
+
+if (sdk.extractScope(publicInputs, circuit) !== expectedScope) {
+  throw new Error('Proof was generated for a different scope');
+}
+```
+
+#### Use the nullifier
+
+The nullifier is a deterministic hash over the user's credential and the scope:
+
+- **Deterministic** — same user, same scope, same nullifier, every time. That is what makes duplicate detection possible.
+- **Privacy-preserving** — the wallet address (Coinbase), the email (OIDC) and the licence (mDL) stay hidden. There is no way back from the nullifier to the person.
+- **Scope-bound** — the same user proving to a different scope produces an unrelated nullifier, so your users cannot be correlated across apps.
+
+On your side, it is the primary key of a verified user. Store it once verification succeeds, with a unique constraint, and check it before granting anything:
+
+```typescript
+const nullifier = sdk.extractNullifier(publicInputs, circuit);
+if (!nullifier) throw new Error('Public inputs too short for this circuit');
+
+// One claim per user, forever: the insert is the double-proof check.
+const inserted = await db.verifiedUsers.insertIfAbsent({
+  nullifier,          // '0xabc123…'
+  circuit,
+  claimedAt: new Date(),
+});
+
+if (!inserted) {
+  // This credential has already been used for this scope.
+  throw new Error('Already claimed');
+}
+```
+
+Keep the scope you used fixed for the lifetime of that record. Change the scope string and every returning user looks brand new, because every nullifier changes with it.
 
 > **OIDC Domain:** The nullifier is a hash of the user's email and scope. The same email + scope always produces the same nullifier, enabling Sybil resistance without revealing the email address.
 
-The **domain** (OIDC Domain Attestation only) is the email domain the user proved:
-- Extracted from the circuit's public inputs
-- Matches the domain parameter provided during proof request
-- Available only for `oidc_domain_attestation` circuits
+#### Check the domain
+
+`extractDomain()` (OIDC Domain Attestation only) returns the email domain the proof was made for, decoded from the public inputs — up to 64 ASCII characters. It returns `null` for every other circuit.
+
+The circuit binds it to the signed token: the part of the email after `@` has to equal this domain, exactly, to the end of the address. What the circuit does not decide is *which* domain — the prover picks it. So compare it with what you asked for:
+
+```typescript
+const domain = sdk.extractDomain(publicInputs, 'oidc_domain_attestation');
+if (domain !== 'company.com') {
+  throw new Error(`Proof is for ${domain}, not company.com`);
+}
+```
 
 **Standalone utility functions** are also available for use outside the SDK class:
 
@@ -468,7 +715,8 @@ import {
   extractDomainFromPublicInputs,
 } from '@zkproofport-app/sdk';
 
-// Works with all circuits: coinbase_attestation, coinbase_country_attestation, oidc_domain_attestation, mdl_kr_ownership, mdl_kr_age, mdl_kr_region
+// Scope and nullifier work for all six circuits — the layout is picked from the
+// circuit id, so always pass it:
 const scope = extractScopeFromPublicInputs(publicInputs, 'coinbase_attestation');
 const nullifier = extractNullifierFromPublicInputs(publicInputs, 'coinbase_attestation');
 
@@ -476,18 +724,26 @@ const nullifier = extractNullifierFromPublicInputs(publicInputs, 'coinbase_attes
 const oidcScope = extractScopeFromPublicInputs(publicInputs, 'oidc_domain_attestation');
 const oidcNullifier = extractNullifierFromPublicInputs(publicInputs, 'oidc_domain_attestation');
 
+// The three mDL circuits share one layout
+const mdlNullifier = extractNullifierFromPublicInputs(publicInputs, 'mdl_kr_age');
+
 // Extract domain from OIDC Domain Attestation
 const domain = extractDomainFromPublicInputs(publicInputs, 'oidc_domain_attestation');
-// domain: 'example.com' or null if circuit doesn't match or inputs insufficient
+// domain: 'example.com', or null if the circuit doesn't match or inputs are insufficient
 ```
 
+Omitting the circuit argument falls back to the `coinbase_attestation` layout, which is why the examples above always pass it explicitly.
+
 ## Complete Example
 
 End-to-end integration using the relay flow:
 
 ```typescript
 import { ProofportSDK } from '@zkproofport-app/sdk';
-import { BrowserProvider } from 'ethers';
+import type { CircuitType, ProofResponse } from '@zkproofport-app/sdk';
+import { BrowserProvider, keccak256, toUtf8Bytes } from 'ethers';
+
+const SCOPE = 'myapp.com';
 
 async function verifyUser() {
   // Initialize
@@ -500,7 +756,7 @@ async function verifyUser() {
 
   // Create proof request via relay
   const relay = await sdk.createRelayRequest('coinbase_attestation', {
-    scope: 'myapp.com',
+    scope: SCOPE,
   }, {
     dappName: 'My DApp',
     message: 'Verify your identity',
@@ -508,30 +764,53 @@ async function verifyUser() {
 
   // Display QR code
   const qrDataUrl = await sdk.generateQRCode(relay.deepLink, { width: 400 });
-  document.getElementById('qr-image').src = qrDataUrl;
-  document.getElementById('status').textContent = 'Scan the QR code with ZKProofport';
+  (document.getElementById('qr-image') as HTMLImageElement).src = qrDataUrl;
+  document.getElementById('status')!.textContent = 'Scan the QR code with ZKProofport';
 
   // Wait for proof result
   const result = await sdk.waitForProof(relay.requestId, {
     onStatusChange: (update) => {
-      document.getElementById('status').textContent = `Status: ${update.status}`;
+      document.getElementById('status')!.textContent = `Status: ${update.status}`;
     },
   });
 
   if (result.status === 'completed') {
+    const circuit = result.circuit as CircuitType;
+    const publicInputs = result.publicInputs ?? [];
+
     // Verify on-chain
-    const verification = await sdk.verifyOnChain(
-      result.circuit,
-      result.proof,
-      result.publicInputs
-    );
-
-    if (verification.valid) {
-      document.getElementById('status').textContent = 'Identity verified!';
-      // Grant access to your application
+    const response: ProofResponse = {
+      requestId: result.requestId,
+      circuit,
+      status: 'completed',
+      proof: result.proof,
+      publicInputs,
+      verifierAddress: result.verifierAddress,
+      chainId: result.chainId,
+    };
+
+    const verification = await sdk.verifyResponseOnChain(response);
+
+    if (!verification.valid) {
+      document.getElementById('status')!.textContent = `Invalid proof: ${verification.error}`;
+      sdk.disconnect();
+      return;
+    }
+
+    // A real proof is not yet a proof of what you asked: check the scope.
+    if (sdk.extractScope(publicInputs, circuit) !== keccak256(toUtf8Bytes(SCOPE))) {
+      document.getElementById('status')!.textContent = 'Proof was made for another scope';
+      sdk.disconnect();
+      return;
     }
+
+    // Key the user on the nullifier — same person + same scope, same value
+    const nullifier = sdk.extractNullifier(publicInputs, circuit);
+    document.getElementById('status')!.textContent = 'Identity verified!';
+    console.log('Verified user:', nullifier);
+    // Grant access to your application
   } else {
-    document.getElementById('status').textContent = `Failed: ${result.error}`;
+    document.getElementById('status')!.textContent = `Failed: ${result.error}`;
   }
 
   // Cleanup
@@ -541,11 +820,11 @@ async function verifyUser() {
 
 ## Configuration
 
-`ProofportSDK.create()` returns a fully configured SDK instance. No manual configuration is needed — relay URLs, verifier contracts, and chain settings are all built-in.
+`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`).
 
 ## Types Reference
 
-All 15 exported types:
+Types you can import:
 
 ```typescript
 import type {
@@ -554,6 +833,9 @@ import type {
   CoinbaseKycInputs,
   CoinbaseCountryInputs,
   OidcDomainInputs,
+  MdlKrOwnershipInputs,
+  MdlKrAgeInputs,
+  MdlKrRegionInputs,
   CircuitInputs,
   ProofRequest,
   ProofResponse,
@@ -569,21 +851,24 @@ import type {
 
 | Type | Description |
 |------|-------------|
-| `CircuitType` | `'coinbase_attestation' \| 'coinbase_country_attestation' \| 'oidc_domain_attestation'` |
-| `ProofRequestStatus` | `'pending' \| 'completed' \| 'error' \| 'cancelled'` |
-| `CoinbaseKycInputs` | Inputs for `coinbase_attestation` (`{ scope, userAddress?, rawTransaction? }`) |
-| `CoinbaseCountryInputs` | Inputs for `coinbase_country_attestation` (`{ scope, countryList, isIncluded, ... }`) |
-| `OidcDomainInputs` | Inputs for `oidc_domain_attestation` (`{ domain, scope, provider? }`) |
-| `CircuitInputs` | Union: `CoinbaseKycInputs \| CoinbaseCountryInputs \| OidcDomainInputs` |
-| `ProofRequest` | Proof request object with `requestId`, `circuit`, `inputs`, metadata, and expiry |
-| `ProofResponse` | Proof response with `status`, `proof`, `publicInputs`, `verifierAddress`, `chainId` |
+| `CircuitType` | `'coinbase_attestation' \| 'coinbase_country_attestation' \| 'oidc_domain_attestation' \| 'mdl_kr_ownership' \| 'mdl_kr_age' \| 'mdl_kr_region'` |
+| `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? }` |
+| `OidcDomainInputs` | Inputs for `oidc_domain_attestation`: `{ domain, scope, provider? }` |
+| `MdlKrOwnershipInputs` | Inputs for `mdl_kr_ownership`: `{ scope, discloseFlags? }` |
+| `MdlKrAgeInputs` | Inputs for `mdl_kr_age`: `{ scope, ageThreshold }` |
+| `MdlKrRegionInputs` | Inputs for `mdl_kr_region`: `{ scope, targetRegion }` |
+| `CircuitInputs` | Union of every input type above (plus an empty-input form for circuits that need nothing from the dApp) |
+| `ProofRequest` | Request object: `requestId`, `circuit`, `inputs`, `createdAt`, plus optional `message`, `dappName`, `dappIcon`, `returnScheme`, `expiresAt` |
+| `ProofResponse` | What `verifyResponseOnChain()` takes: `requestId`, `circuit`, `status`, and — when completed — `proof`, `publicInputs`, `verifierAddress`, `chainId`; `error` when it failed. `numPublicInputs` and `timestamp` also exist but the relay never fills them, so omit them. Field by field in [Step 6](#step-6-read-the-result) |
 | `QRCodeOptions` | QR customization: `width`, `margin`, `darkColor`, `lightColor`, `errorCorrectionLevel` |
 | `VerifierContract` | Verifier contract info: `{ address, chainId, abi }` |
-| `ProofportConfig` | SDK configuration (internal use — `ProofportSDK.create()` handles defaults) |
-| `ChallengeResponse` | Challenge from relay: `{ challenge, expiresAt }` |
-| `WalletSigner` | Signer interface: `{ signMessage(msg), getAddress() }` |
-| `RelayProofRequest` | Relay response: `{ requestId, deepLink, status, pollUrl }` |
-| `RelayProofResult` | Relay result: `{ requestId, status, proof?, publicInputs?, circuit?, error? }` |
+| `ProofportConfig` | Constructor configuration — `ProofportSDK.create()` fills it in for you |
+| `ChallengeResponse` | Challenge from the relay: `{ requestId, challenge, expiresAt }` |
+| `WalletSigner` | Signer interface: `{ signMessage(message), getAddress() }` |
+| `RelayProofRequest` | Result of `createRelayRequest()`: `{ requestId, deepLink, status, pollUrl }` |
+| `RelayProofResult` | Result of `waitForProof()` / `waitForResult()` / `pollResult()`: `{ requestId, status, deepLink?, createdAt?, updatedAt?, proof?, publicInputs?, verifierAddress?, chainId?, circuit?, error? }`. `status` is declared as `'pending' \| 'completed' \| 'failed'` but the relay also delivers `'error'` and `'cancelled'` — [Step 6](#step-6-read-the-result) |
 
 The `OidcDomainInputs` interface:
 
@@ -595,81 +880,128 @@ interface OidcDomainInputs {
 }
 ```
 
+Note that `RelayProofResult` (what you get back from the relay) and `ProofResponse` (what `verifyResponseOnChain` takes) are different types: the relay result's `status` uses `'failed'`, and its `circuit` is a plain `string`. Step 6 shows both shapes side by side and Step 7 does the conversion.
+
 ## Public Input Layout Constants
 
-The SDK exports constants defining the field positions in each circuit's public inputs array. These are useful when working with standalone extraction functions or building custom verification logic.
+`publicInputs` is an **ordered array whose layout is fixed by the circuit**. Index 64 in one circuit has nothing to do with index 64 in another. Reading it with the wrong layout does not fail loudly — it returns a well-formed value that means something else, which is how a proof ends up verifying a claim nobody asked for. Prefer `sdk.extractScope()` / `extractNullifier()` / `extractDomain()`, and reach for these constants only for the fields those do not cover.
 
 ```typescript
 import {
   COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT,
   COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT,
   OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT,
+  MDL_KR_PUBLIC_INPUT_LAYOUT,
 } from '@zkproofport-app/sdk';
 ```
 
-**Coinbase KYC Attestation** (128 fields total):
+Two rules hold for every table below:
+
+- **Every number is an index into `publicInputs`, and `_END` is inclusive.** Slice with `slice(START, END + 1)`.
+- **One entry is one field element, not one 32-byte value.** A `bytes32` such as a scope or a nullifier is spread over 32 consecutive entries, each holding a single byte in its low byte: `publicInputs[64] === '0x00…2f'` is the byte `0x2f`. Rebuild it by concatenating those 32 low bytes. The one exception is the OIDC RSA modulus, whose 18 entries each hold a 128-bit limb.
+
 ```typescript
-COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT = {
-  SIGNAL_HASH_START: 0,      // RSA modulus limbs (Coinbase signer)
-  SIGNAL_HASH_END: 31,
-  MERKLE_ROOT_START: 32,     // Merkle root of signers
-  MERKLE_ROOT_END: 63,
-  SCOPE_START: 64,           // keccak256 hash of scope string
-  SCOPE_END: 95,
-  NULLIFIER_START: 96,       // Unique identifier per user+scope
-  NULLIFIER_END: 127,
-}
-```
+const L = COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT;
 
-**Coinbase Country Attestation** (150 fields total):
-```typescript
-COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT = {
-  SIGNAL_HASH_START: 0,
-  SIGNAL_HASH_END: 31,
-  MERKLE_ROOT_START: 32,
-  MERKLE_ROOT_END: 63,
-  COUNTRY_LIST_START: 64,    // Packed country codes
-  COUNTRY_LIST_END: 83,
-  COUNTRY_LIST_LENGTH: 84,   // Number of countries
-  IS_INCLUDED: 85,           // Boolean: user in list or not
-  SCOPE_START: 86,
-  SCOPE_END: 117,
-  NULLIFIER_START: 118,
-  NULLIFIER_END: 149,
-}
+// Rebuild a bytes32 value from 32 single-byte entries.
+const toBytes32 = (fields: string[]): string =>
+  '0x' + fields.map((f) => (BigInt(f) & 0xffn).toString(16).padStart(2, '0')).join('');
+
+const signalHash = toBytes32(publicInputs.slice(L.SIGNAL_HASH_START, L.SIGNAL_HASH_END + 1));
 ```
 
-**OIDC Domain Attestation** (148 fields total):
+### `coinbase_attestation` — 128 entries
+
+| Index | Constants | Circuit field | What it is |
+|-------|-----------|---------------|------------|
+| 0–31 | `SIGNAL_HASH_START` / `_END` | `signal_hash` | `bytes32` anti-replay challenge for the request |
+| 32–63 | `MERKLE_ROOT_START` / `_END` | `signer_list_merkle_root` | `bytes32` root of the Coinbase attestation-signer list the proof was checked against |
+| 64–95 | `SCOPE_START` / `_END` | `scope` | `bytes32` — `keccak256` of your scope string. Compare it (Step 8) |
+| 96–127 | `NULLIFIER_START` / `_END` | `nullifier` | `bytes32`, unique per user and scope |
+
+### `coinbase_country_attestation` — 150 entries
+
+| Index | Constants | Circuit field | What it is |
+|-------|-----------|---------------|------------|
+| 0–31 | `SIGNAL_HASH_START` / `_END` | `signal_hash` | `bytes32` anti-replay challenge |
+| 32–63 | `MERKLE_ROOT_START` / `_END` | `signer_list_merkle_root` | `bytes32` signer-list root |
+| 64–83 | `COUNTRY_LIST_START` / `_END` | `country_list` | 10 slots of 2 ASCII bytes, one byte per entry — entries 64–65 are the first code, 66–67 the second, and so on, in the order you sent them. Only the first `country_list_length` slots are meaningful; the rest are zero |
+| 84 | `COUNTRY_LIST_LENGTH` | `country_list_length` | How many of those 10 slots count |
+| 85 | `IS_INCLUDED` | `is_included` | `1` = the user **is** in the list, `0` = the user is **not** |
+| 86–117 | `SCOPE_START` / `_END` | `scope` | `bytes32` scope hash |
+| 118–149 | `NULLIFIER_START` / `_END` | `nullifier` | `bytes32`, unique per user and scope |
+
+The country list and the `is_included` flag are public inputs, which means the proof is only as strong as the list it was proved against. Read indices 64–85 back and confirm they are the list and the direction you asked for; a valid proof against a different list is still a valid proof.
+
+### `oidc_domain_attestation` — 148 entries
+
+| Index | Constants | Circuit field | What it is |
+|-------|-----------|---------------|------------|
+| 0–17 | `PUBKEY_MODULUS_START` / `_END` | `pubkey_modulus_limbs` | The RSA modulus of the OIDC issuer's signing key, as 18 × 128-bit limbs. Not single bytes |
+| 18–81 | `DOMAIN_STORAGE_START` / `_END` | `domain` storage | The domain as ASCII, one byte per entry. Entries past the length at index 82 are zero |
+| 82 | `DOMAIN_LEN` | `domain` length | How many of those 64 bytes are the domain. `extractDomain()` does this decoding for you |
+| 83–114 | `SCOPE_START` / `_END` | `scope` | `bytes32` scope hash |
+| 115–146 | `NULLIFIER_START` / `_END` | `nullifier` | `bytes32` over the user's email and the scope |
+| 147 | `PROVIDER` | `provider` | `0` = Google, `1` = Microsoft. The circuit accepts no other value |
+
+`DOMAIN_START` and `DOMAIN_END` are kept as deprecated aliases of `DOMAIN_STORAGE_START` and `DOMAIN_LEN`. Use the current names — the old pair reads as a range and is not one.
+
+Index 147 tells you which issuer signed the token, not whether the account belongs to an organisation. Workspace and Microsoft 365 membership is checked on-device only when you set `provider` in the request; if you did not set it, do not read a membership guarantee out of this field.
+
+### Korea Mobile ID (mDL) — one layout, three circuits
+
+All three mDL circuits share the same first 64 entries and differ after that. Entries are single bytes, except `age_threshold` and `current_year`, which each hold their whole value in one entry.
+
+| Index | Constants | Circuit field | Applies to |
+|-------|-----------|---------------|------------|
+| 0–31 | `SCOPE_START` / `_END` | `scope` | all three |
+| 32–63 | `NULLIFIER_START` / `_END` | `nullifier_value` | all three |
+| 64 | `OWNERSHIP_DISCLOSE_FLAGS` | `disclose_flags` | `mdl_kr_ownership` (97 entries) — the bitmask that was actually proved (`0x01` name, `0x02` birth, `0x04` sex, `0x08` phone) |
+| 65–96 | `OWNERSHIP_OWNER_COMMIT_START` / `_END` | `owner_commit` | `mdl_kr_ownership` — `bytes32` commitment to the disclosed attributes. All zero when `disclose_flags` is `0`, which is the anonymous case |
+| 64 | `AGE_THRESHOLD` | `age_threshold` | `mdl_kr_age` (66 entries) — the age the proof actually clears. Read it back; it is a public input, so confirm it is the threshold you asked for |
+| 65 | `AGE_CURRENT_YEAR` | `current_year` | `mdl_kr_age` — the year the comparison was made in |
+| 64–95 | `REGION_CODE_START` / `_END` | `region_code` | `mdl_kr_region` (96 entries) — `bytes32`, not a readable region name. See below |
+
+`region_code` is `keccak256` over the region name, UTF-8 and zero-padded to 64 bytes. The circuit proves that the region on the licence hashes to this value, but the value itself is a public input — so recompute it from the region you asked for and compare, exactly as you do with the scope:
+
 ```typescript
-OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT = {
-  PUBKEY_MODULUS_START: 0,   // RSA modulus limbs (JWT issuer key)
-  PUBKEY_MODULUS_END: 17,
-  DOMAIN_STORAGE_START: 18,  // Domain bytes (up to 64 ASCII characters)
-  DOMAIN_STORAGE_END: 81,
-  DOMAIN_LEN: 82,            // Domain string length
-  SCOPE_START: 83,           // keccak256 hash of scope string
-  SCOPE_END: 114,
-  NULLIFIER_START: 115,      // Unique identifier per user+scope
-  NULLIFIER_END: 146,
-  PROVIDER: 147,             // OIDC provider code (0=none, 1=Google, 2=Microsoft)
+import { keccak256 } from 'ethers';
 
-  // Deprecated aliases (use new names above)
-  DOMAIN_START: 18,          // @deprecated Use DOMAIN_STORAGE_START
-  DOMAIN_END: 82,            // @deprecated Use DOMAIN_LEN
-}
-```
+const regionCodeFor = (region: string): string => {
+  const padded = new Uint8Array(64);
+  padded.set(new TextEncoder().encode(region));
+  return keccak256(padded);
+};
 
-> **Note on field positions:** Each position in the public inputs array corresponds to a field element in the circuit. For bytes32 values (scope, nullifier, signal hash), 32 consecutive fields are concatenated to form the final value.
+// regionCodeFor('경기도') — compare against indices 64–95, rebuilt with toBytes32()
+```
 
 ## Error Handling
 
-All async SDK methods throw standard `Error` objects:
+Async SDK methods throw standard `Error` objects. The messages are stable enough to log, not to switch on:
 
 ```typescript
 try {
+  // Coinbase circuit without a signer
   await sdk.createRelayRequest('coinbase_attestation', { scope: 'app.com' });
 } catch (err) {
-  // "Signer not set. Call setSigner() first."
+  // "Signer not set. Call setSigner() first. Wallet signature is required for this circuit."
+}
+
+try {
+  await sdk.createRelayRequest('mdl_kr_age', { scope: 'app.com', ageThreshold: 0 });
+} catch (err) {
+  // "ageThreshold is required and must be an integer between 1 and 150 (circuit: mdl_kr_age)"
+}
+
+try {
+  await sdk.createRelayRequest('coinbase_attestation', { scope: 'app.com' }, {
+    returnScheme: 'https://myapp.com/done',
+  });
+} catch (err) {
+  // "returnScheme must be a bare custom scheme such as "mydapp://" or an https
+  //  origin such as "https://myapp.com" — paths, query strings and fragments are
+  //  not accepted"  (thrown before any network call)
 }
 
 try {
@@ -679,6 +1011,12 @@ try {
 }
 ```
 
+A relay rejection surfaces as its message, e.g. `Duplicate nonce (replay detected)` for a reused `nonce`, or `Request not found or expired` from `pollResult()`.
+
+Verification is the exception: `verifyResponseOnChain` and `verifyOnChain` report failures as `{ valid: false, error }` instead of throwing.
+
+A proof that fails on the phone is not an exception either — it comes back as a result with `status: 'error'` and an `error` string. Step 6 covers those, and which of them are worth retrying.
+
 ## Networks
 
 Proofs are verified on **Base** (Ethereum L2). The SDK handles network configuration automatically — no manual setup required.