@zkproofport-app/sdk 0.4.1 → 0.4.3

package/README.md

@@ -477,6 +477,8 @@ const relay = await sdk.createRelayRequest('coinbase_attestation', {
 
 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.
 
+The relay never reads your circuit inputs. So that ZKProofport can count requests per app, the SDK also sends `scope` alongside them, unchanged. The proof itself uses the scope in your inputs.
+
 #### Switching back: `returnScheme`
 
 When ZKProofport finishes a proof, the user is sitting in the ZKProofport app. `returnScheme` answers one question: **which app should come back to the foreground?**
@@ -692,7 +694,8 @@ When you are done, `sdk.disconnect()` closes any open socket.
 | `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. |
+| `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. |
 | `createdAt`, `updatedAt` | `string` | polling path only | ISO timestamps of creation and last update. |
 
@@ -703,37 +706,40 @@ The last three come from the relay's polling endpoint. `waitForProof()` normally
 | `status` | Terminal | What happened | What you do |
 |----------|----------|---------------|-------------|
 | `'pending'` | no | The request exists; no proof yet | Keep waiting — `waitForProof()` does that for you |
+| `'generating'` | no | The app is producing the proof | Keep waiting |
 | `'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 |
+| `'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. `errorCode` (e.g. `'E2007'`) names the cause when the app sent one |
+| `'failed'` | yes | Same meaning and same handling as `'error'`; older app versions send it | Handle it with `'error'` |
+| `'cancelled'` | yes | The user declined the request in the ZKProofport app | Reset your UI |
+| `'expired'` | yes | The app did not answer in time, so the relay answered for it (a little under five minutes after the request) | Offer to start a new request |
 
-`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:
+Every terminal status ends the wait: `waitForProof()`, `waitForResult()` and `subscribe()`'s `onResult` all settle on each of the five, so branch on `result.status` rather than assuming success:
 
 ```typescript
-const status: string = result.status;
+import { isTerminalRelayStatus } from '@zkproofport-app/sdk';
+
+const result = await sdk.waitForProof(relay.requestId);
 
-if (status === 'completed') {
-  // verify it
-} else if (status === 'error' || status === 'failed') {
-  showError(result.error ?? 'Proof generation failed');
+switch (result.status) {
+  case 'completed':
+    // verify it (Step 7)
+    break;
+  case 'error':
+  case 'failed':
+    showError(result.error ?? 'Proof generation failed', result.errorCode);
+    break;
+  case 'cancelled':
+    hideQrDialog();
+    break;
+  case 'expired':
+    offerRetry();
+    break;
 }
 ```
 
-`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();
-    }
-  },
-});
-```
+`isTerminalRelayStatus(status)` and `RELAY_TERMINAL_STATUSES` are exported for code that drives `pollResult()` in a loop of its own.
 
-`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.
+The relay answers `'expired'` before the SDK's default `timeoutMs` (300 000 ms) runs out, so with the defaults you get a result to branch on rather than a thrown timeout. If you pass a much shorter `timeoutMs`, the SDK's own timeout can still fire first and the promise rejects.
 
 #### What is not on the result
 
@@ -750,7 +756,8 @@ const result = await sdk.waitForProof(relay.requestId, {
 | `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 |
+| `status: 'expired'` | Only if the user asks for it | Yes: the app never answered — the QR was not scanned, or the app was closed |
+| `waitForProof()` timeout (only with a `timeoutMs` shorter than the default) | 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
@@ -1076,7 +1083,8 @@ import type {
 | `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) |
+| `RelayProofResult` | Result of `waitForProof()` / `waitForResult()` / `pollResult()`: `{ requestId, status, deepLink?, createdAt?, updatedAt?, proof?, publicInputs?, verifierAddress?, chainId?, circuit?, error?, errorCode? }`. `status` is a `RelayProofStatus` — [Step 6](#step-6-read-the-result) |
+| `RelayProofStatus` / `RelayTerminalStatus` | `'pending' \| 'generating'` plus the terminal `'completed' \| 'error' \| 'failed' \| 'cancelled' \| 'expired'` |
 
 The `OidcDomainInputs` interface:
 

package/dist/ProofportSDK.d.ts

@@ -868,7 +868,9 @@ export declare class ProofportSDK {
      */
     pollResult(requestId: string): Promise<RelayProofResult>;
     /**
-     * Polls the relay until proof is completed or failed, with configurable interval and timeout.
+     * Polls the relay until the request reaches a terminal status
+     * (`completed`, `error`, `failed`, `cancelled` or `expired`), with
+     * configurable interval and timeout. Branch on `result.status`.
      *
      * @param requestId - The relay-issued request ID
      * @param options - Polling options
@@ -894,7 +896,7 @@ export declare class ProofportSDK {
      * @param requestId - The relay-issued request ID to subscribe to
      * @param callbacks - Event callbacks for status changes and results
      * @param callbacks.onStatus - Called on status updates (pending, generating)
-     * @param callbacks.onResult - Called when proof is completed or failed
+     * @param callbacks.onResult - Called once with the terminal result: completed, error, failed, cancelled or expired
      * @param callbacks.onError - Called on errors
      * @returns Unsubscribe function to clean up the connection
      * @throws Error if relayUrl not set or socket.io-client not installed

package/dist/index.d.ts

@@ -34,5 +34,6 @@ export { COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT
 export type { CircuitId, CircuitSupportStatus } from './circuits';
 export { CIRCUIT_ACTION_BINDING, circuitActionBinding, } from './circuits';
 export type { CircuitActionBinding } from './circuits';
-export type { CircuitType, ProofRequestStatus, CoinbaseKycInputs, ActionBoundInputs, GiwaAttestationInputs, DojangPlaygroundInputs, TypedAction, CoinbaseCountryInputs, OidcDomainInputs, MdlKrOwnershipInputs, MdlKrAgeInputs, MdlKrRegionInputs, CircuitInputs, ProofRequest, ProofResponse, QRCodeOptions, VerifierContract, ProofportConfig, ChallengeResponse, WalletSigner, RelayProofRequest, RelayProofResult, SDKEnvironment, } from './types';
+export type { CircuitType, ProofRequestStatus, CoinbaseKycInputs, ActionBoundInputs, GiwaAttestationInputs, DojangPlaygroundInputs, TypedAction, CoinbaseCountryInputs, OidcDomainInputs, MdlKrOwnershipInputs, MdlKrAgeInputs, MdlKrRegionInputs, CircuitInputs, ProofRequest, ProofResponse, QRCodeOptions, VerifierContract, ProofportConfig, ChallengeResponse, WalletSigner, RelayProofRequest, RelayProofResult, RelayProofStatus, RelayTerminalStatus, SDKEnvironment, } from './types';
+export { RELAY_TERMINAL_STATUSES, isTerminalRelayStatus } from './relayStatus';
 export { validateTypedAction, parseTypedAction } from './typedAction';

package/dist/index.esm.js

@@ -4916,6 +4916,17 @@ async function verifyProofOffChain(circuit, proof, publicInputs, options = {}) {
     }
 }
 
+/**
+ * The statuses a relay request ends in, as a runtime list. `satisfies` keeps it
+ * in step with the `RelayTerminalStatus` type in both directions: a status
+ * added to the type and not here, or here and not in the type, fails to compile.
+ */
+const RELAY_TERMINAL_STATUSES = ['completed', 'error', 'failed', 'cancelled', 'expired'];
+/** True when `status` is one a relay request ends in. */
+function isTerminalRelayStatus(status) {
+    return RELAY_TERMINAL_STATUSES.includes(status);
+}
+
 /**
  * Proofport SDK - Main class
  */
@@ -5978,6 +5989,13 @@ class ProofportSDK {
             inputs,
             challenge,
         };
+        // The relay never reads `inputs`, so the scope is also sent on the envelope,
+        // where the relay counts requests per scope. The app proves the scope inside
+        // `inputs` and uses the envelope copy only when `inputs` has none; both are
+        // the same string here.
+        const scope = inputs.scope;
+        if (typeof scope === 'string' && scope.length > 0)
+            body.scope = scope;
         // Sign challenge for circuits that require wallet signature
         if (needsSignature && this.signer) {
             body.signature = await this.signer.signMessage(challenge);
@@ -6041,7 +6059,9 @@ class ProofportSDK {
         return await response.json();
     }
     /**
-     * Polls the relay until proof is completed or failed, with configurable interval and timeout.
+     * Polls the relay until the request reaches a terminal status
+     * (`completed`, `error`, `failed`, `cancelled` or `expired`), with
+     * configurable interval and timeout. Branch on `result.status`.
      *
      * @param requestId - The relay-issued request ID
      * @param options - Polling options
@@ -6062,7 +6082,10 @@ class ProofportSDK {
                 lastStatus = result.status;
                 options.onStatusChange?.(result);
             }
-            if (result.status === 'completed' || result.status === 'failed') {
+            // Every terminal status ends the wait, not only success: an app error,
+            // a cancellation and a relay-side timeout are answers too, and polling
+            // past them would only end in this method's own timeout.
+            if (isTerminalRelayStatus(result.status)) {
                 return result;
             }
             await new Promise(resolve => setTimeout(resolve, interval));
@@ -6080,7 +6103,7 @@ class ProofportSDK {
      * @param requestId - The relay-issued request ID to subscribe to
      * @param callbacks - Event callbacks for status changes and results
      * @param callbacks.onStatus - Called on status updates (pending, generating)
-     * @param callbacks.onResult - Called when proof is completed or failed
+     * @param callbacks.onResult - Called once with the terminal result: completed, error, failed, cancelled or expired
      * @param callbacks.onError - Called on errors
      * @returns Unsubscribe function to clean up the connection
      * @throws Error if relayUrl not set or socket.io-client not installed
@@ -6287,5 +6310,5 @@ class ProofportSDK {
     }
 }
 
-export { ALL_CIRCUIT_IDS, CIRCUIT_ACTION_BINDING, CIRCUIT_IDS, CIRCUIT_SUPPORT_STATUS, CIRCUIT_VK_PATHS, COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, EXPERIMENTAL_CIRCUIT_IDS, MDL_KR_PUBLIC_INPUT_LAYOUT, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, PLANNED_CIRCUIT_IDS, ProofportSDK, SUPPORTED_CIRCUIT_IDS, circuitActionBinding, ProofportSDK as default, extractDomainFromPublicInputs, extractNullifierFromPublicInputs, extractScopeFromPublicInputs, getCircuitSupportStatus, isCircuitId, isSupportedCircuitId, parseTypedAction, validateTypedAction, verifyProofOffChain };
+export { ALL_CIRCUIT_IDS, CIRCUIT_ACTION_BINDING, CIRCUIT_IDS, CIRCUIT_SUPPORT_STATUS, CIRCUIT_VK_PATHS, COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, EXPERIMENTAL_CIRCUIT_IDS, MDL_KR_PUBLIC_INPUT_LAYOUT, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, PLANNED_CIRCUIT_IDS, ProofportSDK, RELAY_TERMINAL_STATUSES, SUPPORTED_CIRCUIT_IDS, circuitActionBinding, ProofportSDK as default, extractDomainFromPublicInputs, extractNullifierFromPublicInputs, extractScopeFromPublicInputs, getCircuitSupportStatus, isCircuitId, isSupportedCircuitId, isTerminalRelayStatus, parseTypedAction, validateTypedAction, verifyProofOffChain };
 //# sourceMappingURL=index.esm.js.map