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

package/README.md

@@ -370,6 +370,70 @@ Secrets are encrypted into per-node envelopes. The gateway coordinates the round
 
 Private API access is still an active security-sensitive surface. Do not treat encrypted secret delivery as production-ready until gateway/node-side test vectors and validation are complete.
 
+## Paywalled API sources
+
+Some API sources answer an unpaid request with HTTP 402 instead of data. You pay such a
+source directly, from your own wallet on the source's network. Molpha never holds, signs
+for, or converts those funds, and the Molpha side of the round is unchanged: a paid
+source still costs exactly one round of subscription quota.
+
+```ts
+import { createEvmSignerFromPrivateKey } from "@molpha/sdk";
+
+const result = await sdk.gateway.requestSignedData({
+  apiConfig,
+  signaturesRequired,
+  sourcePayment: {
+    signer: createEvmSignerFromPrivateKey(process.env.EVM_PRIVATE_KEY!),
+  },
+});
+```
+
+The SDK fetches the source unpaid to read its terms, signs one EIP-3009 transfer
+authorization per node in the round's eligible set, and sends them as `sourcePayments`.
+Beta signs `exact` payments in USDC on Base and Base Sepolia only; any other network or
+asset is rejected before you sign anything. Private keys stay in your process — pass your
+own `EvmSigner` to keep them in a wallet or KMS instead.
+
+**You pay per node fetch, not per datum.** Independent fetching is the point of the
+protocol, so one round costs up to
+`min(signaturesRequired + redundancyBuffer, nodeCount)` source calls — the same eligible
+set the selection bitmap is drawn from. Only authorizations a node actually spends ever
+settle, so unused ones cost nothing. Sign the whole set anyway: a short set starves buffer
+nodes and makes the round more likely to fail.
+
+Each retry signs fresh authorizations with new nonces, because a dispatched round cannot
+be replayed and a retry is therefore a new round. Authorizations the source already
+settled stay spent if the round then fails; unsettled ones expire worthless. There is no
+refund path and none is needed.
+
+Source payment is per-round access material, like a credential. It never enters
+`sourceId`, so a paid and an unpaid fetch of the same API config share one source
+identity.
+
+### Without a source wallet
+
+A paywalled source with no `sourcePayment` throws `UpstreamPaymentRequiredError`, whose
+`quote` carries the resource, the eligible set size, and the source's own rejection
+detail. This is terminal — the round is never retried blindly.
+
+```ts
+import { UpstreamPaymentRequiredError } from "@molpha/sdk";
+
+try {
+  await sdk.gateway.requestSignedData({ apiConfig, signaturesRequired });
+} catch (err) {
+  if (err instanceof UpstreamPaymentRequiredError) {
+    console.log(`${err.quote.resource} needs ${err.quote.eligibleSetSize} paid fetches`);
+  }
+}
+```
+
+To drive the payment yourself, `probeSource`, `signSourcePayments` and `eligibleSetSize`
+are exported for x402-native agents calling `/v1/x402/execute` with their own client.
+`gateway.getNodesInfo()` reports the gateway's advisory view of the registry policy that
+sizes the eligible set, for callers with no Solana connection.
+
 ## EVM verification
 
 After a gateway round, the same signed result can be verified on EVM chains.
@@ -514,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";
 ```
 
@@ -621,12 +745,15 @@ Current scope:
 - gateway signed-data requests (failover, retries, per-gateway request auth, context cache);
 - Solana attestation submission and feed/registry reads;
 - private API encryption helpers (pre-production);
-- EVM and Starknet verifier argument building;
+- caller-funded x402 payments for paywalled API sources (Base USDC, pre-production);
+- EVM and Starknet verifier argument building, Starknet `verify` calldata encoding and result decoding;
 - deployed testnet verifier address helpers.
 
 Known limitations:
 
 - private API envelope encryption still needs gateway/node-side test-vector validation;
+- paid-source payments sign `exact` USDC on Base and Base Sepolia only, and are pending
+  end-to-end validation against a live paywalled source;
 - verifier-node registration and admin tooling are intentionally outside this package;
 - production deployments should use authenticated gateway requests;
 - testnet verifier addresses may change between protocol releases.
@@ -649,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 { R as RegistrySelectionConfig, S as Signer, N as NodeKeyVerifier, a as Node, A as APIConfig, D as DataUpdateResult, b as SolanaAccountMeta, c as SolanaConnection, d as SolanaAddress, e as NodeKeyVerifierArgs, M as MolphaWallet } from './wallet-udLZ5Iy0.js';
-export { E as EncKeyBundle, f as SchnorrSignature, g as gatewaySignerFromWallet, s as signerFromKeypair } from './wallet-udLZ5Iy0.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';
 
 /**
@@ -56,6 +56,48 @@ declare function encodeRequestAuth(fields: RequestAuthFields): Uint8Array;
 /** `keccak256(REQUEST_AUTH_DOMAIN || encodeRequestAuth(fields))` — the message the consumer signs. */
 declare function hashRequestAuth(fields: RequestAuthFields): Uint8Array;
 
+/** Raised when a round needs source payment the caller cannot or did not make. */
+declare class UpstreamPaymentRequiredError extends Error {
+    readonly quote: UpstreamQuote;
+    constructor(quote: UpstreamQuote, message?: string);
+}
+/**
+ * Number of source fetches this round may perform, and so authorizations to
+ * sign: `min(signaturesRequired + redundancyBuffer, nodeCount)`. Identical to
+ * the round's selection size — the eligible set *is* the set that fetches.
+ */
+declare function eligibleSetSize(signaturesRequired: number, registry: {
+    nodeCount: number;
+    redundancyBuffer: number;
+}): number;
+/** Reads a gateway 402 body and returns the relayed upstream quote, if any. */
+declare function parseUpstreamQuote(envelope: unknown): UpstreamQuote | null;
+/**
+ * Validates caller-supplied terms with the same allowlist and structural checks
+ * as {@link probeSource}. Returns canonical {@link UpstreamTerms} derived from
+ * `terms.requirements`, not the caller's top-level fields.
+ */
+declare function validateSuppliedTerms(terms: UpstreamTerms, resource: string, assetDomain?: AssetDomain): UpstreamTerms;
+/**
+ * Fetch the source unpaid to read its own x402 terms. This is a price fetch,
+ * not a data fetch: nodes remain the only fetchers of the value itself.
+ * Returns `null` when the source is not paywalled.
+ */
+declare function probeSource(apiConfig: APIConfig, options?: {
+    secrets?: Record<string, string>;
+    assetDomain?: AssetDomain;
+    timeoutMs?: number;
+}): Promise<UpstreamTerms | null>;
+/**
+ * Sign one x402 payment authorization per eligible node.
+ *
+ * Sign the whole eligible set. Only authorizations a node actually spends ever
+ * settle, so unused ones cost nothing, while signing fewer starves buffer nodes
+ * and raises the round's failure probability. Every authorization carries a
+ * unique nonce, which is what prevents one from settling twice.
+ */
+declare function signSourcePayments(terms: UpstreamTerms, signer: EvmSigner, count: number): Promise<string[]>;
+
 interface RequestSignedDataOptions {
     /**
      * The API definition to resolve. Its canonical form determines the round's
@@ -85,6 +127,17 @@ interface RequestSignedDataOptions {
     encrypt?: {
         secrets: Record<string, string>;
     };
+    /**
+     * Pays an API source that is itself x402-paywalled. The SDK reads the source's
+     * own 402, signs one authorization per node in the round's eligible set, and
+     * sends them with the round as `sourcePayments`.
+     *
+     * Payment goes to the source, never to Molpha: the round still costs exactly
+     * one round of subscription quota. Only authorizations a node actually spends
+     * ever settle, so the redundancy buffer costs nothing when it goes unused.
+     * Without this, a paywalled source throws {@link UpstreamPaymentRequiredError}.
+     */
+    sourcePayment?: SourcePaymentOptions;
     /** Max accepted value age in seconds. Default 60. */
     maxAge?: number;
     /** Each retry re-rolls the timestamp. Default 15. */
@@ -171,6 +224,16 @@ declare class MolphaGateway {
     defaultSubscriptionOwnerOrOptions?: string | MolphaGatewayOptions, defaultConsumerAuthority?: string);
     /** Tries endpoints in order; returns the first node list it can fetch. */
     getNodes(): Promise<Node[]>;
+    /**
+     * `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.
+     */
+    getNodesInfo(): Promise<NodesInfo>;
     isHealthy(): Promise<boolean>;
     /**
      * `GET {url}/v1/info` — the gateway's on-chain identity. Throws when the gateway
@@ -202,6 +265,10 @@ declare class MolphaGateway {
      * 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.
      */
     requestSignedData(opts: RequestSignedDataOptions): Promise<DataUpdateResult>;
     /**
@@ -483,6 +550,13 @@ declare function bigIntFromBytesBe(bytes: Uint8Array): bigint;
 declare function ensureLength(bytes: Uint8Array, len: number, label: string): Uint8Array;
 /** Coerce hex string or bytes to a fixed-length byte array. */
 declare function toFixedBytes(value: string | Uint8Array, len: number, label: string): Uint8Array;
+/**
+ * Standard base64 (padded, no line breaks). Isomorphic: `btoa` is available in
+ * Node 20+ and every browser, so no `Buffer` is pulled into browser bundles.
+ */
+declare function bytesToBase64(bytes: Uint8Array): string;
+/** Accepts padded or unpadded standard base64. */
+declare function base64ToBytes(value: string): Uint8Array;
 
 /** `keccak256("MOLPHA_MESSAGE_V1")` domain separator. */
 declare const MESSAGE_PREFIX: Uint8Array;
@@ -534,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
@@ -601,6 +714,40 @@ type MolphaEvmNetwork = "evm-sepolia" | "arbitrum-sepolia" | "avalanche-fuji" |
 /** CREATE2 Molpha verifier address — identical on all supported EVM chains. */
 declare const MOLPHA_VERIFIER_ADDRESS: "0xE1fd792b7E54e0C8F0Cd1c8055E446ff36d233eB";
 
+/** EIP-712 domain of the token contract that will settle the authorization. */
+interface Eip712Domain {
+    name: string;
+    version: string;
+    chainId: number;
+    /** Token contract address, 0x-prefixed. */
+    verifyingContract: string;
+}
+/** EIP-3009 transfer authorization. Amounts are decimal strings of base units. */
+interface TransferAuthorization {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    /** 0x-prefixed 32-byte nonce. */
+    nonce: string;
+}
+declare const EIP712_DOMAIN_TYPEHASH: Uint8Array<ArrayBufferLike>;
+declare const TRANSFER_WITH_AUTHORIZATION_TYPEHASH: Uint8Array<ArrayBufferLike>;
+declare function domainSeparator(domain: Eip712Domain): Uint8Array;
+declare function transferWithAuthorizationHash(auth: TransferAuthorization): Uint8Array;
+/** The 32-byte digest a wallet signs: `keccak256(0x1901 || domain || struct)`. */
+declare function transferWithAuthorizationDigest(domain: Eip712Domain, auth: TransferAuthorization): Uint8Array;
+/** EIP-55 checksum form. Some facilitators reject non-checksummed addresses. */
+declare function toChecksumAddress(address: string): string;
+/** The EIP-55 address of a raw secp256k1 private key. */
+declare function evmAddressFromPrivateKey(privateKey: string | Uint8Array): string;
+/**
+ * Build an {@link EvmSigner} from a raw secp256k1 private key. The key stays in
+ * the caller's process: neither Molpha nor the gateway ever sees one.
+ */
+declare function createEvmSignerFromPrivateKey(privateKey: string | Uint8Array): EvmSigner;
+
 /** `(bytes32 sourceId, uint32 registryVersion, uint32 signaturesRequired, bytes32 valuePacked, uint64 timestamp)` */
 type EvmDataUpdateTuple = readonly [
     sourceId: `0x${string}`,
@@ -643,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
@@ -748,4 +964,4 @@ declare class MolphaSDK {
     }>;
 }
 
-export { APIConfig, type AttestationMessageFields, DEFAULT_GATEWAY_ENDPOINT, DataUpdateResult, type EvmDataUpdateTuple, type EvmSchnorrSignatureTuple, 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, type PlanId, type PlanInfo, PlanType, REQUEST_AUTH_DOMAIN, RegistrySelectionConfig, type RegistryStateView, type RegistryView, type RequestAuthFields, type RequestSignedDataOptions, type RoundContext, Signer, type StarknetDataUpdate, type StarknetSchnorrSignature, type StarknetVerifierArgs, type SubmitAttestationArgs, type SubmitResult, type SubscribeResult, type SubscriptionInfo, 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 { 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 };