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

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.
@@ -621,12 +685,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);
+- caller-funded x402 payments for paywalled API sources (Base USDC, pre-production);
 - EVM and Starknet verifier argument building;
 - 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.

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-B3mYmC2b.js';
+export { j as EncKeyBundle, k as RegistryInfo, l as SchnorrSignature, m as gatewaySignerFromWallet, s as signerFromKeypair } from './wallet-B3mYmC2b.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;
@@ -601,6 +675,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}`,
@@ -748,4 +856,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, 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 };