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

package/dist/index.js

@@ -77,13 +77,39 @@ 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) {
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    const diff = a.charCodeAt(i) - b.charCodeAt(i);
+    if (diff !== 0) return diff;
+  }
+  return a.length - b.length;
+}
+function sortHeaders(headers) {
+  return Object.fromEntries(Object.entries(headers).sort(([a], [b]) => compareCodeUnits(a, b)));
+}
 function canonicalizeAPIConfig(apiConfig) {
+  const headers = apiConfig.headers ?? {};
   return {
     url: apiConfig.url,
     method: apiConfig.method ?? "GET",
-    headers: apiConfig.headers ?? {},
+    headers: Object.keys(headers).length === 0 ? headers : sortHeaders(headers),
     responseParser: apiConfig.responseParser,
     valueTransform: apiConfig.valueTransform ?? ""
   };
@@ -296,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) {
@@ -380,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) {
@@ -442,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
@@ -482,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);
@@ -503,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,
@@ -514,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;
@@ -535,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(
@@ -569,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");
   }
@@ -11341,6 +11735,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, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map