@armory-sh/base 0.2.27-alpha.23.76 → 0.2.27-alpha.23.78

package/src/payment-client.ts

@@ -0,0 +1,201 @@
+import type {
+  PaymentPayload,
+  PaymentRequirements,
+  SettlementResponse,
+  VerifyResponse,
+} from "./types/x402";
+import { isExactEvmPayload, isPaymentPayload } from "./types/x402";
+import { decodeBase64ToUtf8 } from "./utils/base64";
+
+export interface FacilitatorClientConfig {
+  url: string;
+  createHeaders?: () =>
+    | Record<string, string>
+    | Promise<Record<string, string>>;
+}
+
+const DEFAULT_FACILITATOR_URL = "https://facilitator.payai.network";
+
+function toJsonSafe(data: object): object {
+  function convert(value: unknown): unknown {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      return Object.fromEntries(
+        Object.entries(value).map(([key, val]) => [key, convert(val)]),
+      );
+    }
+    if (Array.isArray(value)) {
+      return value.map(convert);
+    }
+    if (typeof value === "bigint") {
+      return value.toString();
+    }
+    return value;
+  }
+  return convert(data) as object;
+}
+
+function resolveUrl(config?: FacilitatorClientConfig): string {
+  return config?.url ?? DEFAULT_FACILITATOR_URL;
+}
+
+async function resolveHeaders(
+  config?: FacilitatorClientConfig,
+): Promise<Record<string, string>> {
+  const base: Record<string, string> = { "Content-Type": "application/json" };
+  if (!config?.createHeaders) return base;
+  const extra = await config.createHeaders();
+  return { ...base, ...extra };
+}
+
+export async function verifyPayment(
+  payload: PaymentPayload,
+  requirements: PaymentRequirements,
+  config?: FacilitatorClientConfig,
+): Promise<VerifyResponse> {
+  const url = resolveUrl(config);
+  const headers = await resolveHeaders(config);
+
+  const response = await fetch(`${url}/verify`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      paymentPayload: toJsonSafe(payload),
+      paymentRequirements: toJsonSafe(requirements),
+    }),
+  });
+
+  if (response.status !== 200) {
+    const text = await response.text().catch(() => response.statusText);
+    throw new Error(`Facilitator verify failed: ${response.status} ${text}`);
+  }
+
+  return (await response.json()) as VerifyResponse;
+}
+
+export async function settlePayment(
+  payload: PaymentPayload,
+  requirements: PaymentRequirements,
+  config?: FacilitatorClientConfig,
+): Promise<SettlementResponse> {
+  const url = resolveUrl(config);
+  const headers = await resolveHeaders(config);
+
+  const response = await fetch(`${url}/settle`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      paymentPayload: toJsonSafe(payload),
+      paymentRequirements: toJsonSafe(requirements),
+    }),
+  });
+
+  if (response.status !== 200) {
+    const text = await response.text().catch(() => response.statusText);
+    throw new Error(`Facilitator settle failed: ${response.status} ${text}`);
+  }
+
+  return (await response.json()) as SettlementResponse;
+}
+
+export interface SupportedKind {
+  x402Version: number;
+  scheme: string;
+  network: string;
+  extra?: Record<string, unknown>;
+}
+
+export interface SupportedResponse {
+  kinds: SupportedKind[];
+}
+
+interface DecodePayloadDefaults {
+  accepted?: PaymentRequirements;
+}
+
+export async function getSupported(
+  config?: FacilitatorClientConfig,
+): Promise<SupportedResponse> {
+  const url = resolveUrl(config);
+  const headers = await resolveHeaders(config);
+
+  const response = await fetch(`${url}/supported`, {
+    method: "GET",
+    headers,
+  });
+
+  if (response.status !== 200) {
+    throw new Error(`Facilitator supported failed: ${response.statusText}`);
+  }
+
+  return (await response.json()) as SupportedResponse;
+}
+
+function isCompactV2Payload(
+  payload: unknown,
+): payload is { x402Version: number; payload: unknown } {
+  if (typeof payload !== "object" || payload === null) return false;
+  const record = payload as Record<string, unknown>;
+  return (
+    typeof record.x402Version === "number" &&
+    "payload" in record &&
+    !("accepted" in record)
+  );
+}
+
+export function decodePayloadHeader(
+  headerValue: string,
+  defaults?: DecodePayloadDefaults,
+): PaymentPayload {
+  if (headerValue.startsWith("{")) {
+    const parsed = JSON.parse(headerValue);
+    if (isPaymentPayload(parsed)) return parsed;
+    if (isCompactV2Payload(parsed)) {
+      const compact = parsed as { payload: PaymentPayload["payload"] };
+      if (!defaults?.accepted) {
+        throw new Error(
+          "Invalid payment payload: missing 'accepted' field and no defaults provided",
+        );
+      }
+      return {
+        x402Version: 2,
+        accepted: defaults.accepted,
+        payload: compact.payload,
+      };
+    }
+    throw new Error("Invalid payment payload: unrecognized format");
+  }
+
+  const normalized = headerValue
+    .replace(/-/g, "+")
+    .replace(/_/g, "/")
+    .padEnd(Math.ceil(headerValue.length / 4) * 4, "=");
+
+  try {
+    const decoded = JSON.parse(decodeBase64ToUtf8(normalized));
+    if (isPaymentPayload(decoded)) return decoded;
+    if (isCompactV2Payload(decoded)) {
+      const compact = decoded as { payload: PaymentPayload["payload"] };
+      if (!defaults?.accepted) {
+        throw new Error(
+          "Invalid payment payload: missing 'accepted' field and no defaults provided",
+        );
+      }
+      return {
+        x402Version: 2,
+        accepted: defaults.accepted,
+        payload: compact.payload,
+      };
+    }
+    throw new Error("Invalid payment payload: unrecognized format");
+  } catch {
+    throw new Error("Invalid payment payload: failed to decode");
+  }
+}
+
+export function extractPayerAddress(payload: PaymentPayload): string {
+  if (isExactEvmPayload(payload.payload)) {
+    return payload.payload.authorization.from;
+  }
+
+  throw new Error("Unable to extract payer address from payload");
+}

package/src/payment-requirements.ts

@@ -0,0 +1,256 @@
+import type {
+  NetworkId,
+  ResolvedNetwork,
+  ResolvedToken,
+  TokenId,
+  ValidationError,
+} from "./types/api";
+import { getNetworkConfig } from "./types/networks";
+import type { Address, PaymentRequirementsV2 } from "./types/v2";
+import { toAtomicUnits } from "./utils/x402";
+import {
+  normalizeNetworkName,
+  resolveNetwork,
+  resolveToken,
+} from "./validation";
+
+export interface PaymentConfig {
+  payTo: Address | string;
+  chains?: NetworkId[];
+  chain?: NetworkId;
+  tokens?: TokenId[];
+  token?: TokenId;
+  amount?: string;
+  maxTimeoutSeconds?: number;
+
+  payToByChain?: Record<string, Address | string>;
+  payToByToken?: Record<string, Record<string, Address | string>>;
+
+  facilitatorUrl?: string;
+  facilitatorUrlByChain?: Record<string, string>;
+  facilitatorUrlByToken?: Record<string, Record<string, string>>;
+}
+
+export interface ResolvedRequirementsConfig {
+  requirements: PaymentRequirementsV2[];
+  error?: ValidationError;
+}
+
+const DEFAULT_NETWORKS: NetworkId[] = [
+  "ethereum",
+  "base",
+  "base-sepolia",
+  "skale-base",
+  "skale-base-sepolia",
+  "ethereum-sepolia",
+];
+
+const DEFAULT_TOKENS: TokenId[] = ["usdc"];
+
+const isValidationError = (value: unknown): value is ValidationError => {
+  return typeof value === "object" && value !== null && "code" in value;
+};
+
+function resolvePayTo(
+  config: PaymentConfig,
+  network: ResolvedNetwork,
+  token: ResolvedToken,
+): Address | string {
+  const chainId = network.config.chainId;
+
+  if (config.payToByToken) {
+    for (const [chainKey, tokenMap] of Object.entries(config.payToByToken)) {
+      const resolvedChain = resolveNetwork(chainKey);
+      if (
+        !isValidationError(resolvedChain) &&
+        resolvedChain.config.chainId === chainId
+      ) {
+        for (const [tokenKey, address] of Object.entries(tokenMap)) {
+          const resolvedToken = resolveToken(tokenKey, network);
+          if (
+            !isValidationError(resolvedToken) &&
+            resolvedToken.config.contractAddress.toLowerCase() ===
+              token.config.contractAddress.toLowerCase()
+          ) {
+            return address;
+          }
+        }
+      }
+    }
+  }
+
+  if (config.payToByChain) {
+    for (const [chainKey, address] of Object.entries(config.payToByChain)) {
+      const resolvedChain = resolveNetwork(chainKey);
+      if (
+        !isValidationError(resolvedChain) &&
+        resolvedChain.config.chainId === chainId
+      ) {
+        return address;
+      }
+    }
+  }
+
+  return config.payTo;
+}
+
+function resolveFacilitatorUrl(
+  config: PaymentConfig,
+  network: ResolvedNetwork,
+  token: ResolvedToken,
+): string | undefined {
+  const chainId = network.config.chainId;
+
+  if (config.facilitatorUrlByToken) {
+    for (const [chainKey, tokenMap] of Object.entries(
+      config.facilitatorUrlByToken,
+    )) {
+      const resolvedChain = resolveNetwork(chainKey);
+      if (
+        !isValidationError(resolvedChain) &&
+        resolvedChain.config.chainId === chainId
+      ) {
+        for (const [tokenKey, url] of Object.entries(tokenMap)) {
+          const resolvedToken = resolveToken(tokenKey, network);
+          if (
+            !isValidationError(resolvedToken) &&
+            resolvedToken.config.contractAddress.toLowerCase() ===
+              token.config.contractAddress.toLowerCase()
+          ) {
+            return url;
+          }
+        }
+      }
+    }
+  }
+
+  if (config.facilitatorUrlByChain) {
+    for (const [chainKey, url] of Object.entries(
+      config.facilitatorUrlByChain,
+    )) {
+      const resolvedChain = resolveNetwork(chainKey);
+      if (
+        !isValidationError(resolvedChain) &&
+        resolvedChain.config.chainId === chainId
+      ) {
+        return url;
+      }
+    }
+  }
+
+  return config.facilitatorUrl;
+}
+
+function resolveNetworks(chainInputs: NetworkId[] | undefined): {
+  networks: ResolvedNetwork[];
+  error?: ValidationError;
+} {
+  const resolvedNetworks: ResolvedNetwork[] = [];
+  const errors: string[] = [];
+
+  const networks = chainInputs?.length ? chainInputs : DEFAULT_NETWORKS;
+
+  for (const networkId of networks) {
+    const resolved = resolveNetwork(networkId);
+    if (isValidationError(resolved)) {
+      errors.push(`Network "${networkId}": ${resolved.message}`);
+    } else {
+      resolvedNetworks.push(resolved);
+    }
+  }
+
+  if (errors.length > 0) {
+    return {
+      networks: resolvedNetworks,
+      error: {
+        code: "VALIDATION_FAILED",
+        message: errors.join("; "),
+      },
+    };
+  }
+
+  return { networks: resolvedNetworks };
+}
+
+export function createPaymentRequirements(
+  config: PaymentConfig,
+): ResolvedRequirementsConfig {
+  const {
+    payTo,
+    chains,
+    chain,
+    tokens,
+    token,
+    amount = "1.0",
+    maxTimeoutSeconds = 300,
+  } = config;
+
+  const chainInputs = chain ? [chain] : chains;
+  const tokenInputs = token ? [token] : tokens;
+
+  const { networks, error: networksError } = resolveNetworks(chainInputs);
+  if (networksError) {
+    return { requirements: [], error: networksError };
+  }
+
+  const requirements: PaymentRequirementsV2[] = [];
+
+  for (const network of networks) {
+    const tokensToResolve = tokenInputs?.length ? tokenInputs : DEFAULT_TOKENS;
+
+    for (const tokenId of tokensToResolve) {
+      const resolvedToken = resolveToken(tokenId, network);
+      if (isValidationError(resolvedToken)) {
+        continue;
+      }
+
+      const atomicAmount = toAtomicUnits(amount);
+      const tokenConfig = resolvedToken.config;
+
+      const resolvedPayTo = resolvePayTo(config, network, resolvedToken);
+      const resolvedFacilitatorUrl = resolveFacilitatorUrl(
+        config,
+        network,
+        resolvedToken,
+      );
+
+      const requirement: PaymentRequirementsV2 = {
+        scheme: "exact",
+        network: network.caip2,
+        amount: atomicAmount,
+        asset: tokenConfig.contractAddress,
+        payTo: resolvedPayTo as `0x${string}`,
+        maxTimeoutSeconds,
+        extra: {
+          name: tokenConfig.name,
+          version: tokenConfig.version,
+        },
+      };
+
+      requirements.push(requirement);
+    }
+  }
+
+  if (requirements.length === 0) {
+    return {
+      requirements: [],
+      error: {
+        code: "VALIDATION_FAILED",
+        message: "No valid network/token combinations found",
+      },
+    };
+  }
+
+  return { requirements };
+}
+
+export function findRequirementByNetwork(
+  requirements: PaymentRequirementsV2[],
+  network: string,
+): PaymentRequirementsV2 | undefined {
+  const normalized = normalizeNetworkName(network);
+  const netConfig = getNetworkConfig(normalized);
+  if (!netConfig) return undefined;
+
+  return requirements.find((r) => r.network === netConfig.caip2Id);
+}

package/src/protocol.ts

@@ -0,0 +1,57 @@
+/**
+ * X402 Protocol Utilities (V2 Only)
+ *
+ * Shared protocol utilities for x402 client implementations.
+ * These functions are protocol-level and don't depend on wallet libraries.
+ */
+
+import { V2_HEADERS } from "./types/v2";
+import { decodeBase64ToUtf8, normalizeBase64Url } from "./utils/base64";
+
+/**
+ * Parse JSON or Base64-encoded JSON
+ * Handles both raw JSON and Base64URL-encoded JSON
+ */
+export function parseJsonOrBase64(value: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch {
+    const normalized = normalizeBase64Url(value);
+    return JSON.parse(decodeBase64ToUtf8(normalized));
+  }
+}
+
+/**
+ * Detect x402 protocol version from response
+ * V2-only: Always returns 2
+ */
+export function detectX402Version(_response: Response): 2 {
+  return 2;
+}
+
+/**
+ * Get payment header name for protocol version
+ * V2-only: Returns PAYMENT-SIGNATURE header name
+ */
+export function getPaymentHeaderName(_version: 2): string {
+  return V2_HEADERS.PAYMENT_SIGNATURE;
+}
+
+/**
+ * Generate a timestamp-based nonce as hex string
+ * Matches Coinbase SDK format: "0x" + 64 hex characters
+ * Uses timestamp for reproducibility (vs random)
+ */
+export function generateNonce(): `0x${string}` {
+  const now = Math.floor(Date.now() / 1000);
+  return `0x${(now * 1000).toString(16).padStart(64, "0")}` as `0x${string}`;
+}
+
+/**
+ * Calculate expiry timestamp
+ * @param expirySeconds - Seconds from now (default: 3600 = 1 hour)
+ * @returns Unix timestamp
+ */
+export function calculateValidBefore(expirySeconds: number = 3600): number {
+  return Math.floor(Date.now() / 1000) + expirySeconds;
+}