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

package/README.md

@@ -578,40 +578,100 @@ const sepoliaDirect = MOLPHA_VERIFIER_STARKNET_SEPOLIA;
 
 ### Build verifier arguments
 
+The verifier's entrypoint is `verify(attestation: Attestation, max_age: u64) -> (bool, u8)`.
+
 ```ts
 import { buildStarknetVerifierArgs } from "@molpha/sdk";
 
 const result = await sdk.gateway.requestSignedData({ apiConfig, signaturesRequired });
 
-const { dataUpdate, signature } = buildStarknetVerifierArgs(result);
+const { attestation, maxAge } = buildStarknetVerifierArgs(result, { maxAge: 300 });
 ```
 
-The generated objects match the Molpha Starknet verifier interface (the Cairo struct still names the first field `feed_id`; positional calldata is unchanged):
+`maxAge` is required. It is the freshness window in seconds: the verifier reports an older
+attestation as `STALE`. `0` disables the check entirely — pass it only when your contract
+enforces freshness or ordering itself, because a stateless verifier otherwise accepts a
+correctly signed attestation forever.
+
+The generated object matches the Cairo `Attestation` struct. Member order is Cairo `Serde`
+order (and the signed message's order), so it differs from `DataUpdateResult`:
 
 ```ts
-// dataUpdate:
-// {
-//   source_id: u256,
-//   registry_version: u32,
-//   signatures_required: u32,
-//   value: u256,
-//   canonical_timestamp: u64,
-// }
+attestation:
+{
+  payload: {
+    value: u256,
+    source_id: u256,
+    registry_version: u32,
+    signatures_required: u8,
+    canonical_timestamp: u64,
+  },
+  signature: {
+    signature: u256,
+    commitment: felt252, // 20-byte address as felt
+    signers_bitmap: u256,
+  },
+}
+```
 
-// signature:
-// {
-//   signature: u256,
-//   commitment: felt252, // EVM-style 20-byte address as felt
-//   signers_bitmap: u256,
-// }
+The builder range-checks every integer against its Cairo type. Out-of-range calldata never
+reaches `verify`: Cairo `Serde` fails while decoding the arguments and the call reverts
+instead of returning a result code.
+
+### Call `verify` and read the result
+
+`encodeStarknetVerifyCalldata` flattens the arguments into the 13 felts a raw `starknet_call`
+takes, and `parseStarknetVerifyResult` decodes the `(bool, u8)` it returns. Any Starknet
+client works; with `starknet.js`:
+
+```ts
+import { RpcProvider } from "starknet";
+import {
+  buildStarknetVerifierArgs,
+  encodeStarknetVerifyCalldata,
+  parseStarknetVerifyResult,
+} from "@molpha/sdk";
+
+const provider = new RpcProvider({ nodeUrl: STARKNET_RPC_URL });
+const args = buildStarknetVerifierArgs(result, { maxAge: 300 });
+
+const response = await provider.callContract({
+  contractAddress: verifierAddress,
+  entrypoint: "verify",
+  calldata: encodeStarknetVerifyCalldata(args),
+});
+
+const { success, code, reason } = parseStarknetVerifyResult(response);
+// { success: true, code: 0, reason: "OK" }
+// { success: false, code: 10, reason: "STALE" }
 ```
 
+`verify` never reverts on well-formed calldata; a rejection is a result code. The codes are
+shared with the EVM verifier contract and exported as `VERIFY_CODES`:
+
+| Code | Name | Meaning |
+|---|---|---|
+| 0 | `OK` | Verified |
+| 2 | `BAD_REGISTRY_VERSION` | `registryVersion` does not exist on this verifier |
+| 3 | `MALFORMED` | Structurally invalid input, or dated in the future when `maxAge != 0` |
+| 4 | `NOT_YET_ACTIVE` | `canonicalTimestamp` predates the registry version's activation |
+| 5 | `VERSION_EXPIRED` | Registry version superseded more than the grace window earlier |
+| 7 | `BAD_QUORUM` | Signers are not within the round's derived selection group |
+| 8 | `BAD_AGGREGATE` | The signers' aggregate key is the point at infinity |
+| 9 | `BAD_SIGNATURE` | The aggregate Schnorr signature does not verify |
+| 10 | `STALE` | Older than `maxAge` |
+
+Codes 1 and 6 are reserved and never returned. Codes are append-only, so
+`parseStarknetVerifyResult` reports a code newer than your SDK as `reason: "UNKNOWN"` rather
+than throwing.
+
 Lower-level helpers are also exported:
 
 ```ts
 import {
   commitmentAddressToStarknetFelt,
   signersBitmapToStarknetUint256,
+  verifyCodeName,
 } from "@molpha/sdk";
 ```
 
@@ -686,7 +746,7 @@ Current scope:
 - Solana attestation submission and feed/registry reads;
 - private API encryption helpers (pre-production);
 - caller-funded x402 payments for paywalled API sources (Base USDC, pre-production);
-- EVM and Starknet verifier argument building;
+- EVM and Starknet verifier argument building, Starknet `verify` calldata encoding and result decoding;
 - deployed testnet verifier address helpers.
 
 Known limitations:
@@ -716,6 +776,9 @@ Solana paths such as selection bitmap and `submit_attestation` remaining-account
 | `result.feedId` / `NodeKeyVerifierArgs.feedId` | `.sourceId` |
 | EVM tuple `feedId`, ABI `jobId` | `sourceId` |
 | Starknet `feed_id` | `source_id` |
+| `buildStarknetVerifierArgs(result)` → `{ dataUpdate, signature }` | `buildStarknetVerifierArgs(result, { maxAge })` → `{ attestation, maxAge }` for `verify(attestation, max_age)` |
+| `StarknetDataUpdate` (`signatures_required: u32`) | `StarknetAttestationPayload` (`signatures_required: u8`, `value` first), nested in `StarknetAttestation` |
+| Starknet `verify` returns `bool` | returns `(bool, u8)` — decode with `parseStarknetVerifyResult` |
 | `resolveRegistryIndexForVersion`, `VIRTUAL_INDEX`, `nodePda(index)` | removed — signer accounts are `registry.nodes[bit]`; `nodePda(owner)` |
 
 ## Develop

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Address } from '@solana/kit';
 import { Wallet, Idl, AnchorProvider } from '@anchor-lang/core';
-import { U as UpstreamQuote, A as APIConfig, a as AssetDomain, b as UpstreamTerms, E as EvmSigner, R as RegistrySelectionConfig, S as Signer, N as NodeKeyVerifier, c as Node, d as NodesInfo, e as SourcePaymentOptions, D as DataUpdateResult, f as SolanaAccountMeta, g as SolanaConnection, h as SolanaAddress, i as NodeKeyVerifierArgs, M as MolphaWallet } from './wallet-B3mYmC2b.js';
-export { j as EncKeyBundle, k as RegistryInfo, l as SchnorrSignature, m as gatewaySignerFromWallet, s as signerFromKeypair } from './wallet-B3mYmC2b.js';
+import { U as UpstreamQuote, A as APIConfig, a as AssetDomain, b as UpstreamTerms, E as EvmSigner, R as RegistrySelectionConfig, S as Signer, N as NodeKeyVerifier, c as Node, d as NodesInfo, e as SourcePaymentOptions, D as DataUpdateResult, f as SolanaAccountMeta, g as SolanaConnection, h as SolanaAddress, i as NodeKeyVerifierArgs, M as MolphaWallet } from './wallet-DwdBZgl1.js';
+export { j as EncKeyBundle, k as RegistryInfo, l as SchnorrSignature, m as gatewaySignerFromWallet, s as signerFromKeypair } from './wallet-DwdBZgl1.js';
 import BN from 'bn.js';
 
 /**
@@ -608,6 +608,45 @@ declare function deriveGroupBitmap(seed: Uint8Array, nodeCount: number, groupSiz
  */
 declare function deriveSelectionBitmap(sourceId: Uint8Array, registryVersion: number, nodeCount: number, signaturesRequired: number, redundancy?: number, ts?: number | bigint): Uint8Array;
 
+/**
+ * Result codes returned by Molpha's stateless verifier contracts (`verify` on EVM and
+ * Starknet). Shared across VMs: the same attestation yields the same code on every chain.
+ *
+ * Append-only — never renumber. Mirrors `VerifyCodes.sol` in `molpha-core-contracts` and
+ * `verify_codes.cairo` in `molpha-starknet`. Two codes belong to mechanisms the verifiers
+ * do not implement; they are kept so the numbering can never shift under them.
+ */
+declare const VERIFY_CODES: {
+    readonly OK: 0;
+    /** Reserved. Never returned. */
+    readonly FEED_WITNESS: 1;
+    /** The payload's `registryVersion` does not exist on this verifier. */
+    readonly BAD_REGISTRY_VERSION: 2;
+    /** Structurally invalid input, or a `canonicalTimestamp` in the future when `maxAge != 0`. */
+    readonly MALFORMED: 3;
+    /** `canonicalTimestamp` predates the registry version's activation. */
+    readonly NOT_YET_ACTIVE: 4;
+    /** The registry version was superseded more than the grace window before `canonicalTimestamp`. */
+    readonly VERSION_EXPIRED: 5;
+    /** Reserved. Never returned. */
+    readonly COMPROMISED_QUORUM: 6;
+    /** The signer set is not within the round's derived selection group. */
+    readonly BAD_QUORUM: 7;
+    /** The signers' aggregate public key is the point at infinity. */
+    readonly BAD_AGGREGATE: 8;
+    /** The aggregate Schnorr signature does not verify. */
+    readonly BAD_SIGNATURE: 9;
+    /** Older than the caller's `maxAge`. */
+    readonly STALE: 10;
+};
+type VerifyCodeName = keyof typeof VERIFY_CODES;
+type VerifyCode = (typeof VERIFY_CODES)[VerifyCodeName];
+/**
+ * Name of a verifier result code, or `undefined` for a code this SDK version does not know.
+ * Codes are append-only, so an unknown code is a newer verifier, not a malformed response.
+ */
+declare function verifyCodeName(code: number): VerifyCodeName | undefined;
+
 /**
  * Minimal Molpha verifier ABI for `verify` and registry reads.
  * Matches the deployed `verify(DataUpdate, SchnorrSignature)` verifier. The first tuple
@@ -751,31 +790,100 @@ declare const MOLPHA_VERIFIER_STARKNET_ADDRESSES: Record<MolphaStarknetNetwork,
 /** Resolve the deployed verifier address for a supported Starknet network. */
 declare function getMolphaStarknetVerifierAddress(network: MolphaStarknetNetwork): `0x${string}`;
 
-/** Starknet calldata shape for `DataUpdate`. */
-interface StarknetDataUpdate {
-    /** 32-byte source id as u256 (the Cairo struct still names this field `feed_id`). */
+/**
+ * Starknet calldata shape for `AttestationPayload`.
+ *
+ * Member order is the order of the signed message preimage and of Cairo `Serde`, so it is
+ * load bearing — it is not the order of `DataUpdateResult`.
+ */
+interface StarknetAttestationPayload {
+    /** 32-byte packed value as `u256`. */
+    value: bigint;
+    /** 32-byte source id as `u256`. */
     source_id: bigint;
+    /** `u32`. */
     registry_version: number;
+    /** `u8`. */
     signatures_required: number;
-    value: bigint;
+    /** `u64`, unix seconds. */
     canonical_timestamp: number;
 }
 /** Starknet calldata shape for `SchnorrSignature`. */
 interface StarknetSchnorrSignature {
+    /** Schnorr scalar `s` as `u256`. */
     signature: bigint;
+    /** Ethereum-style 20-byte address of the nonce point `R`, as a `felt252`. */
     commitment: bigint;
+    /** Big-endian signers bitmap as `u256`; bit `i` is node `i` of the registry version. */
     signers_bitmap: bigint;
 }
-interface StarknetVerifierArgs {
-    dataUpdate: StarknetDataUpdate;
+/** Starknet calldata shape for `Attestation`. */
+interface StarknetAttestation {
+    payload: StarknetAttestationPayload;
     signature: StarknetSchnorrSignature;
 }
-/** Convert a 20-byte EVM-style address hex to a Starknet felt-compatible bigint. */
+/** Positional arguments for `verify(attestation, max_age)`. */
+interface StarknetVerifierArgs {
+    attestation: StarknetAttestation;
+    /** Freshness window in seconds (`u64`). `0` disables the check. */
+    maxAge: number;
+}
+interface BuildStarknetVerifierArgsOptions {
+    /**
+     * Freshness window in seconds. The verifier rejects the attestation with `STALE` when it
+     * is older than this, and as `MALFORMED` when it is dated in the future.
+     *
+     * Required on purpose. `0` disables the check entirely, and that is not a neutral
+     * default: the verifier is stateless, so without a window it accepts a correctly signed
+     * attestation forever. Pass `0` only when the consuming contract enforces freshness or
+     * ordering itself.
+     */
+    maxAge: number;
+}
+/** Decoded `verify` return value. */
+interface StarknetVerifyResult {
+    success: boolean;
+    /** Raw result code — see `VERIFY_CODES`. */
+    code: number;
+    /** Name of `code`, or `"UNKNOWN"` for a code newer than this SDK. */
+    reason: VerifyCodeName | "UNKNOWN";
+}
+/** A felt as returned by `starknet_call` (hex or decimal string) or by an ABI-aware client. */
+type StarknetFeltLike = string | number | bigint | boolean;
+/** Convert a 20-byte commitment address hex to a Starknet felt-compatible bigint. */
 declare function commitmentAddressToStarknetFelt(value: string): bigint;
 /** Convert a 32-byte bitmap hex to a Starknet/Cairo `u256` bigint. */
 declare function signersBitmapToStarknetUint256(value: string): bigint;
-/** Build verifier `DataUpdate` and `SchnorrSignature` structs from a gateway result. */
-declare function buildStarknetVerifierArgs(result: DataUpdateResult): StarknetVerifierArgs;
+/**
+ * Build the `verify(attestation, max_age)` arguments from a gateway result.
+ *
+ * ```ts
+ * const { attestation, maxAge } = buildStarknetVerifierArgs(result, { maxAge: 300 });
+ * ```
+ */
+declare function buildStarknetVerifierArgs(result: DataUpdateResult, options: BuildStarknetVerifierArgsOptions): StarknetVerifierArgs;
+/**
+ * Flat felt calldata for `verify(attestation, max_age)`, in Cairo `Serde` order — 13 felts:
+ *
+ * `value.low, value.high, source_id.low, source_id.high, registry_version,
+ *  signatures_required, canonical_timestamp, signature.low, signature.high, commitment,
+ *  signers_bitmap.low, signers_bitmap.high, max_age`
+ *
+ * For a raw `starknet_call` with `entry_point_selector = selector("verify")`.
+ */
+declare function encodeStarknetVerifyCalldata(args: StarknetVerifierArgs): `0x${string}`[];
+/**
+ * Decode the `(bool, u8)` returned by `verify`.
+ *
+ * Accepts the raw two-felt array from `starknet_call` (e.g. `["0x1", "0x0"]`) or the tuple
+ * an ABI-aware client decodes (e.g. `{ 0: true, 1: 0n }`). Throws when the two halves
+ * disagree (`success` with a non-zero code, or failure with `OK`), which means the call did
+ * not reach a Molpha verifier of this interface.
+ */
+declare function parseStarknetVerifyResult(result: readonly StarknetFeltLike[] | {
+    readonly 0: StarknetFeltLike;
+    readonly 1: StarknetFeltLike;
+}): StarknetVerifyResult;
 
 /**
  * Consumer PDA derivations. Seed byte strings are cross-checked against the IDL const
@@ -856,4 +964,4 @@ declare class MolphaSDK {
     }>;
 }
 
-export { APIConfig, AssetDomain, type AttestationMessageFields, DEFAULT_GATEWAY_ENDPOINT, DataUpdateResult, EIP712_DOMAIN_TYPEHASH, type Eip712Domain, type EvmDataUpdateTuple, type EvmSchnorrSignatureTuple, EvmSigner, type EvmVerifierArgs, type FeedAccount, type GatewayEndpoint, type GatewayEndpointInput, GatewayError, type GatewayInfo, MESSAGE_PREFIX, MOLPHA_IDL, MOLPHA_PROGRAM_ADDRESS, MOLPHA_PROGRAM_ID, MOLPHA_VERIFIER_ABI, MOLPHA_VERIFIER_ADDRESS, MOLPHA_VERIFIER_STARKNET_ADDRESSES, MOLPHA_VERIFIER_STARKNET_SEPOLIA, type MolphaEvmNetwork, MolphaGateway, type MolphaGatewayOptions, MolphaSDK, type MolphaSDKOptions, MolphaSolanaClient, type MolphaStarknetNetwork, MolphaWallet, Node, NodeKeyVerifier, NodeKeyVerifierArgs, NodesInfo, type PlanId, type PlanInfo, PlanType, REQUEST_AUTH_DOMAIN, RegistrySelectionConfig, type RegistryStateView, type RegistryView, type RequestAuthFields, type RequestSignedDataOptions, type RoundContext, Signer, SourcePaymentOptions, type StarknetDataUpdate, type StarknetSchnorrSignature, type StarknetVerifierArgs, type SubmitAttestationArgs, type SubmitResult, type SubscribeResult, type SubscriptionInfo, TRANSFER_WITH_AUTHORIZATION_TYPEHASH, type TransferAuthorization, UpstreamPaymentRequiredError, UpstreamQuote, UpstreamTerms, 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, ensureLength, evmAddressFromPrivateKey, feedPda, gatewayPda, getMolphaStarknetVerifierAddress, hashRequestAuth, hexToBytes, nodePda, normalizeEndpoint, normalizeSecp256k1PublicKeyHex, parseGatewayInfo, 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 };
+export { APIConfig, AssetDomain, type AttestationMessageFields, type BuildStarknetVerifierArgsOptions, DEFAULT_GATEWAY_ENDPOINT, DataUpdateResult, EIP712_DOMAIN_TYPEHASH, type Eip712Domain, type EvmDataUpdateTuple, type EvmSchnorrSignatureTuple, EvmSigner, type EvmVerifierArgs, type FeedAccount, type GatewayEndpoint, type GatewayEndpointInput, GatewayError, type GatewayInfo, MESSAGE_PREFIX, MOLPHA_IDL, MOLPHA_PROGRAM_ADDRESS, MOLPHA_PROGRAM_ID, MOLPHA_VERIFIER_ABI, MOLPHA_VERIFIER_ADDRESS, MOLPHA_VERIFIER_STARKNET_ADDRESSES, MOLPHA_VERIFIER_STARKNET_SEPOLIA, type MolphaEvmNetwork, MolphaGateway, type MolphaGatewayOptions, MolphaSDK, type MolphaSDKOptions, MolphaSolanaClient, type MolphaStarknetNetwork, MolphaWallet, Node, NodeKeyVerifier, NodeKeyVerifierArgs, NodesInfo, type PlanId, type PlanInfo, PlanType, REQUEST_AUTH_DOMAIN, RegistrySelectionConfig, type RegistryStateView, type RegistryView, type RequestAuthFields, type RequestSignedDataOptions, type RoundContext, Signer, SourcePaymentOptions, type StarknetAttestation, type StarknetAttestationPayload, type StarknetFeltLike, type StarknetSchnorrSignature, type StarknetVerifierArgs, type StarknetVerifyResult, type SubmitAttestationArgs, type SubmitResult, type SubscribeResult, type SubscriptionInfo, TRANSFER_WITH_AUTHORIZATION_TYPEHASH, type TransferAuthorization, UpstreamPaymentRequiredError, UpstreamQuote, UpstreamTerms, VERIFY_CODES, type VerifyCode, type VerifyCodeName, 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 };

package/dist/index.js

@@ -11559,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 = [
   {
@@ -11654,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;
 }
@@ -11678,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
@@ -11735,6 +11848,6 @@ var MolphaSDK = class {
   }
 };
 
-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, 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, ensureLength, evmAddressFromPrivateKey, feedPda, gatewayPda, getMolphaStarknetVerifierAddress, hashRequestAuth, hexToBytes, nodePda, normalizeEndpoint, normalizeSecp256k1PublicKeyHex, parseGatewayInfo, 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 };
+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