@molpha/sdk 0.2.0-dev-20260911175245 → 0.2.0-dev-20260913100330

package/dist/index.js

@@ -77,6 +77,20 @@ function assertUint(value, max, label) {
     throw new RangeError(`${label} out of range: ${value}`);
   }
 }
+function bytesToBase64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += 32768) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + 32768));
+  }
+  return btoa(binary);
+}
+function base64ToBytes(value) {
+  const padded = value.length % 4 === 0 ? value : value + "=".repeat(4 - value.length % 4);
+  const binary = atob(padded);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
 
 // src/core/apiconfig.ts
 function compareCodeUnits(a, b) {
@@ -308,6 +322,268 @@ function validateEncryptionRecipients(selectedNodes) {
     return { index: node.index, signingKey };
   });
 }
+var typeHash = (signature) => keccak_256(utf8(signature));
+var EIP712_DOMAIN_TYPEHASH = typeHash(
+  "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"
+);
+var TRANSFER_WITH_AUTHORIZATION_TYPEHASH = typeHash(
+  "TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)"
+);
+function word(bytes) {
+  if (bytes.length > 32) throw new RangeError("ABI word overflow");
+  const out = new Uint8Array(32);
+  out.set(bytes, 32 - bytes.length);
+  return out;
+}
+function addressWord(address3) {
+  const bytes = hexToBytes(address3);
+  if (bytes.length !== 20) throw new RangeError(`Not a 20-byte address: ${address3}`);
+  return word(bytes);
+}
+function uintWord(value) {
+  const n = typeof value === "bigint" ? value : BigInt(value);
+  if (n < 0n) throw new RangeError(`Not an unsigned integer: ${value}`);
+  const hex = n.toString(16);
+  return word(hexToBytes(hex.length % 2 === 0 ? hex : "0" + hex));
+}
+function bytes32Word(value) {
+  const bytes = hexToBytes(value);
+  if (bytes.length !== 32) throw new RangeError(`Not a 32-byte value: ${value}`);
+  return bytes;
+}
+function domainSeparator(domain) {
+  return keccak_256(
+    concatBytes(
+      EIP712_DOMAIN_TYPEHASH,
+      keccak_256(utf8(domain.name)),
+      keccak_256(utf8(domain.version)),
+      uintWord(BigInt(domain.chainId)),
+      addressWord(domain.verifyingContract)
+    )
+  );
+}
+function transferWithAuthorizationHash(auth) {
+  return keccak_256(
+    concatBytes(
+      TRANSFER_WITH_AUTHORIZATION_TYPEHASH,
+      addressWord(auth.from),
+      addressWord(auth.to),
+      uintWord(auth.value),
+      uintWord(auth.validAfter),
+      uintWord(auth.validBefore),
+      bytes32Word(auth.nonce)
+    )
+  );
+}
+function transferWithAuthorizationDigest(domain, auth) {
+  return keccak_256(
+    concatBytes(
+      Uint8Array.from([25, 1]),
+      domainSeparator(domain),
+      transferWithAuthorizationHash(auth)
+    )
+  );
+}
+function toChecksumAddress(address3) {
+  const lower = bytesToHex(hexToBytes(address3));
+  if (lower.length !== 40) throw new RangeError(`Not a 20-byte address: ${address3}`);
+  const digest = bytesToHex(keccak_256(utf8(lower)));
+  let out = "0x";
+  for (let i = 0; i < lower.length; i++) {
+    out += parseInt(digest[i], 16) >= 8 ? lower[i].toUpperCase() : lower[i];
+  }
+  return out;
+}
+function evmAddressFromPrivateKey(privateKey) {
+  const key = typeof privateKey === "string" ? hexToBytes(privateKey) : privateKey;
+  if (key.length !== 32) throw new RangeError("EVM private key must be 32 bytes");
+  const uncompressed = secp256k1.getPublicKey(key, false);
+  return toChecksumAddress(bytesToHex0x(keccak_256(uncompressed.subarray(1)).subarray(12)));
+}
+function createEvmSignerFromPrivateKey(privateKey) {
+  const key = typeof privateKey === "string" ? hexToBytes(privateKey) : privateKey;
+  const address3 = evmAddressFromPrivateKey(key);
+  return {
+    address: address3,
+    async signDigest(digest) {
+      if (digest.length !== 32) throw new RangeError("Digest must be 32 bytes");
+      const signed = secp256k1.sign(digest, key, { prehash: false, format: "recovered" });
+      const out = new Uint8Array(65);
+      out.set(signed.subarray(1), 0);
+      out[64] = 27 + signed[0];
+      return out;
+    }
+  };
+}
+
+// src/gateway/x402.ts
+var NETWORKS = {
+  "eip155:8453": { chainId: 8453, usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
+  "eip155:84532": { chainId: 84532, usdc: "0x036CbD53842c5426634e7929541eC2318f3dCF7e" },
+  // x402 v1 network names.
+  base: { chainId: 8453, usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
+  "base-sepolia": { chainId: 84532, usdc: "0x036CbD53842c5426634e7929541eC2318f3dCF7e" }
+};
+var UpstreamPaymentRequiredError = class extends Error {
+  constructor(quote, message) {
+    super(
+      message ?? `API source requires payment for up to ${quote.eligibleSetSize} fetches: ${quote.resource}`
+    );
+    this.quote = quote;
+    this.name = "UpstreamPaymentRequiredError";
+  }
+  quote;
+};
+function eligibleSetSize(signaturesRequired, registry) {
+  return effectiveSelectionSize(
+    signaturesRequired,
+    registry.redundancyBuffer,
+    registry.nodeCount
+  );
+}
+function parseUpstreamQuote(envelope) {
+  if (!envelope || typeof envelope !== "object") return null;
+  const extensions = envelope.extensions;
+  if (!extensions || typeof extensions !== "object") return null;
+  const quote = extensions.upstream;
+  if (!quote || typeof quote !== "object") return null;
+  return typeof quote.eligibleSetSize === "number" ? quote : null;
+}
+function selectTerms(envelope, resource, assetDomain) {
+  const version = envelope.x402Version === 1 ? 1 : 2;
+  const offers = Array.isArray(envelope.accepts) ? envelope.accepts : [];
+  if (offers.length === 0) {
+    throw new Error(`Source 402 for ${resource} advertised no payment terms`);
+  }
+  const supported = offers.find(
+    (o) => o.scheme === "exact" && NETWORKS[String(o.network)] !== void 0
+  );
+  if (!supported) {
+    const seen = offers.map((o) => `${o.scheme}/${o.network}`).join(", ");
+    throw new Error(
+      `Source ${resource} requires an unsupported payment scheme or network (${seen}); this SDK signs exact payments on Base USDC only`
+    );
+  }
+  const network = NETWORKS[String(supported.network)];
+  const asset = String(supported.asset ?? "");
+  if (asset.toLowerCase() !== network.usdc.toLowerCase()) {
+    throw new Error(
+      `Source ${resource} asks to be paid in ${asset} on ${supported.network}; this SDK signs USDC (${network.usdc}) only`
+    );
+  }
+  const domain = assetDomain ?? (supported.extra?.name && supported.extra?.version ? { name: String(supported.extra.name), version: String(supported.extra.version) } : void 0);
+  if (!domain) {
+    throw new Error(
+      `Source ${resource} omitted extra.name/extra.version for ${asset}; supply sourcePayment.assetDomain to sign against it`
+    );
+  }
+  const amount = String(supported.amount ?? supported.maxAmountRequired ?? "");
+  if (!/^\d+$/.test(amount)) {
+    throw new Error(`Source ${resource} quoted a non-integer price: ${amount}`);
+  }
+  const payTo = String(supported.payTo ?? "");
+  if (!payTo) throw new Error(`Source ${resource} omitted payTo`);
+  return {
+    x402Version: version,
+    // Echoed verbatim in the signed payload, so it must stay the source's own object.
+    requirements: supported,
+    network: String(supported.network),
+    chainId: network.chainId,
+    asset,
+    payTo,
+    amount,
+    maxTimeoutSeconds: Number(supported.maxTimeoutSeconds ?? 60),
+    domain,
+    resource
+  };
+}
+function decodeEnvelope(headerValue, body) {
+  if (headerValue) {
+    try {
+      return JSON.parse(
+        new TextDecoder().decode(base64ToBytes(headerValue))
+      );
+    } catch {
+    }
+  }
+  return JSON.parse(body);
+}
+function validateSuppliedTerms(terms, resource, assetDomain) {
+  return selectTerms(
+    {
+      x402Version: terms.x402Version,
+      accepts: [terms.requirements]
+    },
+    resource,
+    assetDomain
+  );
+}
+async function probeSource(apiConfig, options = {}) {
+  const resolved = options.secrets ? resolveAPIConfig(apiConfig, options.secrets) : apiConfig;
+  const init = {
+    method: resolved.method ?? "GET",
+    headers: resolved.headers ?? {}
+  };
+  let res;
+  if (options.timeoutMs === void 0) {
+    res = await fetch(resolved.url, init);
+  } else {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+    try {
+      res = await fetch(resolved.url, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  if (res.status !== 402) return null;
+  return selectTerms(
+    decodeEnvelope(res.headers.get("PAYMENT-REQUIRED"), await res.text()),
+    apiConfig.url,
+    options.assetDomain
+  );
+}
+async function signSourcePayments(terms, signer, count) {
+  if (!Number.isInteger(count) || count < 1) {
+    throw new RangeError(`Cannot sign ${count} source payments`);
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  const validAfter = String(now - 600);
+  const validBefore = String(now + Math.max(terms.maxTimeoutSeconds, 60));
+  const payments = [];
+  for (let i = 0; i < count; i++) {
+    const authorization = {
+      from: toChecksumAddress(signer.address),
+      to: toChecksumAddress(terms.payTo),
+      value: terms.amount,
+      validAfter,
+      validBefore,
+      nonce: bytesToHex0x(randomBytes(32))
+    };
+    const digest = transferWithAuthorizationDigest(
+      {
+        name: terms.domain.name,
+        version: terms.domain.version,
+        chainId: terms.chainId,
+        verifyingContract: terms.asset
+      },
+      authorization
+    );
+    const signature = bytesToHex0x(await signer.signDigest(digest));
+    const payload = terms.x402Version === 1 ? {
+      x402Version: 1,
+      scheme: "exact",
+      network: terms.network,
+      payload: { signature, authorization }
+    } : {
+      x402Version: 2,
+      accepted: terms.requirements,
+      payload: { signature, authorization }
+    };
+    payments.push(bytesToBase64(utf8(JSON.stringify(payload))));
+  }
+  return payments;
+}
 var SEED_GATEWAY = utf8("molpha_gateway");
 var addressEncoder = getAddressEncoder();
 function normalizeEndpoint(input) {
@@ -392,8 +668,24 @@ var MolphaGateway = class {
   }
   /** Tries endpoints in order; returns the first node list it can fetch. */
   async getNodes() {
+    return (await this.getNodesInfo()).nodes;
+  }
+  /**
+   * `GET /v1/nodes` — the peer set plus the gateway's view of the registry
+   * selection policy, which sizes the eligible set a paid source must fund.
+   *
+   * The `registry` block is advisory: it is whatever the gateway read from the
+   * chain, and is absent on older gateways or when that read failed. Prefer the
+   * on-chain read (`MolphaSolanaClient.getRegistrySelectionConfig`) whenever a
+   * Solana connection is available — `requestSignedData` already does.
+   */
+  async getNodesInfo() {
     const data = await this.firstReachableData("/v1/nodes");
-    return Array.isArray(data) ? data : data.nodes;
+    if (Array.isArray(data)) return { nodes: data };
+    return {
+      nodes: data.nodes,
+      ...data.registry ? { registry: data.registry } : {}
+    };
   }
   async isHealthy() {
     for (const endpoint of this.endpoints) {
@@ -454,12 +746,17 @@ var MolphaGateway = class {
    * read does not report `nodeCount`). Supply `opts.context` (e.g. from
    * {@link prepareContext}) to reuse cached inputs and skip those fetches — a
    * fully-populated context collapses the call to a single POST round.
+   *
+   * When the API source is itself x402-paywalled, pass `opts.sourcePayment` to
+   * fund it; without that, such a source throws
+   * {@link UpstreamPaymentRequiredError} carrying the gateway's quote.
    */
   async requestSignedData(opts) {
     const {
       apiConfig,
       signer,
       encrypt,
+      sourcePayment,
       maxAge = 60,
       maxRetries = 15,
       timeoutMs = 5e3
@@ -494,9 +791,33 @@ var MolphaGateway = class {
     if (nodeCount === void 0) {
       throw new Error("Round context resolved neither nodeCount nor nodes");
     }
+    let terms = null;
+    let authorizations = 0;
+    let requoted = false;
+    if (sourcePayment) {
+      terms = sourcePayment.terms ? validateSuppliedTerms(
+        sourcePayment.terms,
+        requestApiConfig.url,
+        sourcePayment.assetDomain
+      ) : await probeSource(apiConfig, {
+        ...encrypt ? { secrets: encrypt.secrets } : {},
+        ...sourcePayment.assetDomain ? { assetDomain: sourcePayment.assetDomain } : {},
+        timeoutMs
+      });
+      if (terms) {
+        authorizations = effectiveSelectionSize(
+          signaturesRequired,
+          redundancyBuffer,
+          nodeCount
+        );
+      }
+    }
     let lastError;
+    let lastTimestamp = 0;
     for (let attempt = 0; attempt < maxRetries; attempt++) {
-      const timestamp = Math.floor(Date.now() / 1e3);
+      let timestamp = Math.floor(Date.now() / 1e3);
+      if (timestamp <= lastTimestamp) timestamp = lastTimestamp + 1;
+      lastTimestamp = timestamp;
       const seed = deriveSelectionSeed(sourceIdBytes, registryVersion, timestamp);
       const groupSize = effectiveSelectionSize(signaturesRequired, redundancyBuffer, nodeCount);
       const bitmap = deriveGroupBitmap(seed, nodeCount, groupSize);
@@ -515,6 +836,14 @@ var MolphaGateway = class {
         }
         encKeyBundle = encryptForNodes(requestApiConfig, encrypt.secrets, selected);
       }
+      let sourcePayments;
+      if (terms && sourcePayment && authorizations > 0) {
+        sourcePayments = await signSourcePayments(
+          terms,
+          sourcePayment.signer,
+          authorizations
+        );
+      }
       const baseBody = {
         sourceId,
         registryVersion,
@@ -526,6 +855,8 @@ var MolphaGateway = class {
         apiConfig: requestApiConfig
       };
       if (encKeyBundle) baseBody.encKeyBundle = encKeyBundle;
+      if (sourcePayments) baseBody.sourcePayments = sourcePayments;
+      let requote = false;
       for (const endpoint of this.endpoints) {
         try {
           let authSig = ZERO_AUTH_SIG;
@@ -547,6 +878,55 @@ var MolphaGateway = class {
             body,
             timeoutMs
           );
+          if (res.status === 402) {
+            const quote = parseUpstreamQuote(
+              await res.json().catch(() => null)
+            );
+            if (!quote) {
+              throw new GatewayError(
+                "Gateway requires payment but returned no upstream source quote",
+                402
+              );
+            }
+            if (!sourcePayment) throw new UpstreamPaymentRequiredError(quote);
+            if (terms && requoted && authorizations >= quote.eligibleSetSize) {
+              throw new UpstreamPaymentRequiredError(
+                quote,
+                `Source payment was not accepted for ${quote.resource}: ${quote.error ?? "no detail"}`
+              );
+            }
+            requoted = true;
+            if (quote.eligibleSetSize !== groupSize) {
+              throw new GatewayError(
+                `Gateway upstream quote eligibleSetSize ${quote.eligibleSetSize} does not match this round's selection size ${groupSize} (min(signaturesRequired + redundancyBuffer, nodeCount))`,
+                402
+              );
+            }
+            authorizations = groupSize;
+            if (!terms) {
+              try {
+                terms = await probeSource(apiConfig, {
+                  ...encrypt ? { secrets: encrypt.secrets } : {},
+                  ...sourcePayment.assetDomain ? { assetDomain: sourcePayment.assetDomain } : {},
+                  timeoutMs
+                });
+              } catch (err) {
+                throw new UpstreamPaymentRequiredError(
+                  quote,
+                  `Cannot pay ${quote.resource}: ${err instanceof Error ? err.message : String(err)}`
+                );
+              }
+            }
+            if (!terms) {
+              throw new UpstreamPaymentRequiredError(
+                quote,
+                `Gateway reports ${quote.resource} is paywalled but the source returned no payment terms`
+              );
+            }
+            lastError = new UpstreamPaymentRequiredError(quote);
+            requote = true;
+            break;
+          }
           const errorDetail = !res.ok ? await parseGatewayErrorDetail(res) : void 0;
           if (res.status === 400 || res.status === 401) {
             throw new GatewayError(
@@ -581,12 +961,14 @@ var MolphaGateway = class {
           }
           lastError = new Error(`Gateway returned status: ${json.status}`);
         } catch (err) {
-          if (err instanceof GatewayError && (err.status === 400 || err.status === 401)) {
+          if (err instanceof UpstreamPaymentRequiredError) throw err;
+          if (err instanceof GatewayError && (err.status === 400 || err.status === 401 || err.status === 402)) {
             throw err;
           }
           lastError = err;
         }
       }
+      if (requote) continue;
     }
     throw lastError instanceof Error ? lastError : new Error("Gateway round failed after retries");
   }
@@ -11177,6 +11559,40 @@ function attestationMessageHashFromResult(result) {
   });
 }
 
+// src/core/verifyCodes.ts
+var VERIFY_CODES = {
+  OK: 0,
+  /** Reserved. Never returned. */
+  FEED_WITNESS: 1,
+  /** The payload's `registryVersion` does not exist on this verifier. */
+  BAD_REGISTRY_VERSION: 2,
+  /** Structurally invalid input, or a `canonicalTimestamp` in the future when `maxAge != 0`. */
+  MALFORMED: 3,
+  /** `canonicalTimestamp` predates the registry version's activation. */
+  NOT_YET_ACTIVE: 4,
+  /** The registry version was superseded more than the grace window before `canonicalTimestamp`. */
+  VERSION_EXPIRED: 5,
+  /** Reserved. Never returned. */
+  COMPROMISED_QUORUM: 6,
+  /** The signer set is not within the round's derived selection group. */
+  BAD_QUORUM: 7,
+  /** The signers' aggregate public key is the point at infinity. */
+  BAD_AGGREGATE: 8,
+  /** The aggregate Schnorr signature does not verify. */
+  BAD_SIGNATURE: 9,
+  /** Older than the caller's `maxAge`. */
+  STALE: 10
+};
+var NAMES_BY_CODE = new Map(
+  Object.entries(VERIFY_CODES).map(([name, code]) => [
+    code,
+    name
+  ])
+);
+function verifyCodeName(code) {
+  return NAMES_BY_CODE.get(code);
+}
+
 // src/evm/abi.ts
 var MOLPHA_VERIFIER_ABI = [
   {
@@ -11272,6 +11688,12 @@ function getMolphaStarknetVerifierAddress(network) {
 }
 
 // src/starknet/helpers.ts
+var U8_MAX = 0xffn;
+var U32_MAX2 = 0xffffffffn;
+var U64_MAX = 0xffffffffffffffffn;
+var U128_MASK = (1n << 128n) - 1n;
+var U256_MAX = (1n << 256n) - 1n;
+var ADDRESS_MAX = (1n << 160n) - 1n;
 function strip0x2(value) {
   return value.startsWith("0x") || value.startsWith("0X") ? value.slice(2) : value;
 }
@@ -11296,26 +11718,99 @@ function fixedHexToBigInt(value, bytes, label) {
   const raw = toFixedBytes(hex, bytes, label);
   return bigIntFromBytesBe(raw);
 }
+function assertUint2(value, max, label) {
+  if (!Number.isSafeInteger(value) || value < 0 || BigInt(value) > max) {
+    throw new RangeError(`${label}: expected an integer in 0..${max}, got ${value}`);
+  }
+  return value;
+}
+function assertBigUint(value, max, label) {
+  if (value < 0n || value > max) {
+    throw new RangeError(`${label}: expected an integer in 0..${max}, got ${value}`);
+  }
+  return value;
+}
+function toFelt(value) {
+  return `0x${BigInt(value).toString(16)}`;
+}
+function u256Felts(value, label) {
+  assertBigUint(value, U256_MAX, label);
+  return [toFelt(value & U128_MASK), toFelt(value >> 128n)];
+}
+function feltToBigInt(value, label) {
+  if (typeof value === "boolean") return value ? 1n : 0n;
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value)) throw new RangeError(`${label}: not an integer: ${value}`);
+    return BigInt(value);
+  }
+  const text = value.trim();
+  if (!/^(0x[0-9a-fA-F]+|[0-9]+)$/.test(text)) {
+    throw new RangeError(`${label}: not a felt: ${JSON.stringify(value)}`);
+  }
+  return BigInt(text);
+}
 function commitmentAddressToStarknetFelt(value) {
   return fixedHexToBigInt(value, 20, "commitment");
 }
 function signersBitmapToStarknetUint256(value) {
   return fixedHexToBigInt(value, 32, "signersBitmap");
 }
-function buildStarknetVerifierArgs(result) {
-  const dataUpdate = {
-    source_id: fixedHexToBigInt(result.sourceId, 32, "sourceId"),
-    registry_version: result.registryVersion,
-    signatures_required: result.signaturesRequired,
+function buildStarknetVerifierArgs(result, options) {
+  const payload = {
     value: fixedHexToBigInt(result.valuePacked, 32, "valuePacked"),
-    canonical_timestamp: result.timestamp
+    source_id: fixedHexToBigInt(result.sourceId, 32, "sourceId"),
+    registry_version: assertUint2(result.registryVersion, U32_MAX2, "registryVersion"),
+    signatures_required: assertUint2(result.signaturesRequired, U8_MAX, "signaturesRequired"),
+    canonical_timestamp: assertUint2(result.timestamp, U64_MAX, "timestamp")
   };
   const signature = {
     signature: fixedHexToBigInt(result.s, 32, "signature"),
     commitment: commitmentAddressToStarknetFelt(result.commitmentAddr),
     signers_bitmap: signersBitmapToStarknetUint256(result.signersBitmap)
   };
-  return { dataUpdate, signature };
+  return {
+    attestation: { payload, signature },
+    maxAge: assertUint2(options.maxAge, U64_MAX, "maxAge")
+  };
+}
+function encodeStarknetVerifyCalldata(args) {
+  const { payload, signature } = args.attestation;
+  return [
+    ...u256Felts(payload.value, "value"),
+    ...u256Felts(payload.source_id, "source_id"),
+    toFelt(assertUint2(payload.registry_version, U32_MAX2, "registry_version")),
+    toFelt(assertUint2(payload.signatures_required, U8_MAX, "signatures_required")),
+    toFelt(assertUint2(payload.canonical_timestamp, U64_MAX, "canonical_timestamp")),
+    ...u256Felts(signature.signature, "signature"),
+    // An Ethereum-style address, so it must fit 160 bits (the verifier reports a wider one
+    // as `MALFORMED`; one past the field prime would not even deserialize).
+    toFelt(assertBigUint(signature.commitment, ADDRESS_MAX, "commitment")),
+    ...u256Felts(signature.signers_bitmap, "signers_bitmap"),
+    toFelt(assertUint2(args.maxAge, U64_MAX, "maxAge"))
+  ];
+}
+function parseStarknetVerifyResult(result) {
+  if (Array.isArray(result) && result.length !== 2) {
+    throw new RangeError(`verify result: expected 2 felts, got ${result.length}`);
+  }
+  const tuple = result;
+  const successFelt = feltToBigInt(tuple[0], "verify result success");
+  if (successFelt !== 0n && successFelt !== 1n) {
+    throw new RangeError(`verify result: success must be 0 or 1, got ${successFelt}`);
+  }
+  const codeFelt = feltToBigInt(tuple[1], "verify result code");
+  if (codeFelt < 0n || codeFelt > U8_MAX) {
+    throw new RangeError(`verify result: code must fit u8, got ${codeFelt}`);
+  }
+  const success = successFelt === 1n;
+  const code = Number(codeFelt);
+  if (success !== (code === VERIFY_CODES.OK)) {
+    throw new Error(
+      `verify result is inconsistent: success=${success} with code ${code}; the call did not reach a Molpha verifier with this interface`
+    );
+  }
+  return { success, code, reason: verifyCodeName(code) ?? "UNKNOWN" };
 }
 
 // src/index.ts
@@ -11353,6 +11848,6 @@ var MolphaSDK = class {
   }
 };
 
-export { DEFAULT_GATEWAY_ENDPOINT, GatewayError, MESSAGE_PREFIX, MOLPHA_IDL, MOLPHA_PROGRAM_ADDRESS, MOLPHA_PROGRAM_ID, MOLPHA_VERIFIER_ABI, MOLPHA_VERIFIER_ADDRESS, MOLPHA_VERIFIER_STARKNET_ADDRESSES, MOLPHA_VERIFIER_STARKNET_SEPOLIA, MolphaGateway, MolphaSDK, MolphaSolanaClient, PlanType, REQUEST_AUTH_DOMAIN, addressToBytes, attestationMessageHash, attestationMessageHashFromResult, bigIntFromBytesBe, bitmapBitSet, bitmapToIndices, buildEvmVerifierArgs, buildStarknetVerifierArgs, buildSubmitAttestationArgs, bytesToHex, bytesToHex0x, canonicalizeAPIConfig, commitmentAddressToStarknetFelt, concatBytes, deriveApiConfigHash, deriveGatewayPda, deriveGatewayPdaAddress, deriveGroupBitmap, deriveSelectionBitmap, deriveSelectionSeed, deriveSourceId, deriveSourceIdString, effectiveSelectionSize, encodeRequestAuth, ensureLength, feedPda, gatewayPda, getMolphaStarknetVerifierAddress, hashRequestAuth, hexToBytes, nodePda, normalizeEndpoint, normalizeSecp256k1PublicKeyHex, parseGatewayInfo, planIdFromVariant, planPda, planVariant, protocolConfigPda, registryPda, registryStatePda, resolveRemainingAccounts, secp256k1PublicKeyFromCoordinates, selectedIndices, signersBitmapToDecimal, signersBitmapToStarknetUint256, signersBitmapToUint256, subscriptionPda, toFixedBytes, toFixedHex, u256beFromBigInt, u32be, u32le, u64be, u64le, utf8 };
+export { DEFAULT_GATEWAY_ENDPOINT, EIP712_DOMAIN_TYPEHASH, GatewayError, MESSAGE_PREFIX, MOLPHA_IDL, MOLPHA_PROGRAM_ADDRESS, MOLPHA_PROGRAM_ID, MOLPHA_VERIFIER_ABI, MOLPHA_VERIFIER_ADDRESS, MOLPHA_VERIFIER_STARKNET_ADDRESSES, MOLPHA_VERIFIER_STARKNET_SEPOLIA, MolphaGateway, MolphaSDK, MolphaSolanaClient, PlanType, REQUEST_AUTH_DOMAIN, TRANSFER_WITH_AUTHORIZATION_TYPEHASH, UpstreamPaymentRequiredError, VERIFY_CODES, addressToBytes, attestationMessageHash, attestationMessageHashFromResult, base64ToBytes, bigIntFromBytesBe, bitmapBitSet, bitmapToIndices, buildEvmVerifierArgs, buildStarknetVerifierArgs, buildSubmitAttestationArgs, bytesToBase64, bytesToHex, bytesToHex0x, canonicalizeAPIConfig, commitmentAddressToStarknetFelt, concatBytes, createEvmSignerFromPrivateKey, deriveApiConfigHash, deriveGatewayPda, deriveGatewayPdaAddress, deriveGroupBitmap, deriveSelectionBitmap, deriveSelectionSeed, deriveSourceId, deriveSourceIdString, domainSeparator, effectiveSelectionSize, eligibleSetSize, encodeRequestAuth, encodeStarknetVerifyCalldata, ensureLength, evmAddressFromPrivateKey, feedPda, gatewayPda, getMolphaStarknetVerifierAddress, hashRequestAuth, hexToBytes, nodePda, normalizeEndpoint, normalizeSecp256k1PublicKeyHex, parseGatewayInfo, parseStarknetVerifyResult, parseUpstreamQuote, planIdFromVariant, planPda, planVariant, probeSource, protocolConfigPda, registryPda, registryStatePda, resolveRemainingAccounts, secp256k1PublicKeyFromCoordinates, selectedIndices, signSourcePayments, signersBitmapToDecimal, signersBitmapToStarknetUint256, signersBitmapToUint256, subscriptionPda, toChecksumAddress, toFixedBytes, toFixedHex, transferWithAuthorizationDigest, transferWithAuthorizationHash, u256beFromBigInt, u32be, u32le, u64be, u64le, utf8, validateSuppliedTerms, verifyCodeName };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map