@armory-sh/base 0.2.28 → 0.2.30

package/src/payment-requirements.ts

@@ -0,0 +1,354 @@
+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;
+}
+
+export interface FacilitatorRoutingConfig {
+  facilitatorUrl?: string;
+  facilitatorUrlByChain?: Record<string, string>;
+  facilitatorUrlByToken?: Record<string, Record<string, string>>;
+}
+
+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;
+}
+
+export function resolveFacilitatorUrlFromRequirement(
+  config: FacilitatorRoutingConfig,
+  requirement: Pick<PaymentRequirementsV2, "network" | "asset">,
+): string | undefined {
+  const chainId = parseInt(requirement.network.split(":")[1] || "0", 10);
+  const assetAddress = requirement.asset.toLowerCase();
+
+  if (config.facilitatorUrlByToken) {
+    for (const [chainKey, tokenMap] of Object.entries(
+      config.facilitatorUrlByToken,
+    )) {
+      const resolvedChain = resolveNetwork(chainKey);
+      if (
+        isValidationError(resolvedChain) ||
+        resolvedChain.config.chainId !== chainId
+      ) {
+        continue;
+      }
+
+      for (const [tokenKey, url] of Object.entries(tokenMap)) {
+        const resolvedToken = resolveToken(tokenKey, resolvedChain);
+        if (
+          !isValidationError(resolvedToken) &&
+          resolvedToken.config.contractAddress.toLowerCase() === assetAddress
+        ) {
+          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);
+}
+
+export function findRequirementByAccepted(
+  requirements: PaymentRequirementsV2[],
+  accepted: {
+    scheme: string;
+    network: string;
+    amount: string;
+    asset: string;
+    payTo: string;
+  },
+): PaymentRequirementsV2 | undefined {
+  const acceptedPayTo =
+    typeof accepted.payTo === "string" ? accepted.payTo.toLowerCase() : "";
+  const exactMatch = requirements.find(
+    (requirement) =>
+      requirement.scheme === accepted.scheme &&
+      requirement.network === accepted.network &&
+      requirement.amount === accepted.amount &&
+      requirement.asset.toLowerCase() === accepted.asset.toLowerCase() &&
+      typeof requirement.payTo === "string" &&
+      requirement.payTo.toLowerCase() === acceptedPayTo,
+  );
+  if (exactMatch) {
+    return exactMatch;
+  }
+
+  const payToAwareMatch = requirements.find(
+    (requirement) =>
+      requirement.scheme === accepted.scheme &&
+      requirement.network === accepted.network &&
+      acceptedPayTo.length > 0 &&
+      typeof requirement.payTo === "string" &&
+      requirement.payTo.toLowerCase() === acceptedPayTo,
+  );
+  if (payToAwareMatch) {
+    return payToAwareMatch;
+  }
+
+  return requirements.find(
+    (requirement) =>
+      requirement.scheme === accepted.scheme &&
+      requirement.network === accepted.network,
+  );
+}

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;
+}

package/src/types/api.ts

@@ -0,0 +1,304 @@
+/**
+ * Simple, developer-friendly API types for Armory
+ * Focuses on DX/UX - "everything just magically works"
+ */
+
+import type { CustomToken, NetworkConfig } from "./networks";
+import type { Address, CAIPAssetId } from "./v2";
+
+// ═══════════════════════════════════════════════════════════════
+// Simple API Types
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Network identifier - flexible input that resolves to a chain
+ * - Network name: "base", "ethereum", "skale-base"
+ * - CAIP-2: "eip155:8453"
+ * - Chain ID: 8453
+ */
+export type NetworkId = string | number;
+
+/**
+ * Token identifier - flexible input that resolves to a token
+ * - Symbol: "usdc", "eurc", "usdt" (case-insensitive)
+ * - CAIP Asset ID: "eip155:8453/erc20:0x..."
+ * - Full token config object
+ */
+export type TokenId = string | CustomToken;
+
+/**
+ * Facilitator configuration
+ */
+export interface FacilitatorConfig {
+  /** Facilitator URL for verification/settlement */
+  url: string;
+  /** Optional authentication headers */
+  headers?: () => Record<string, string>;
+  /** Networks this facilitator supports (auto-detected if not provided) */
+  networks?: NetworkId[];
+  /** Tokens this facilitator supports (optional) */
+  tokens?: TokenId[];
+}
+
+/**
+ * Result from facilitator verification
+ */
+export interface FacilitatorVerifyResult {
+  success: boolean;
+  payerAddress?: string;
+  balance?: string;
+  requiredAmount?: string;
+  error?: string;
+}
+
+/**
+ * Result from facilitator settlement
+ */
+export interface FacilitatorSettleResult {
+  success: boolean;
+  txHash?: string;
+  error?: string;
+}
+
+/**
+ * Settlement mode - verify only, settle only, or both
+ */
+export type SettlementMode = "verify" | "settle" | "async";
+
+/**
+ * CAIP-2 chain ID type (e.g., eip155:8453)
+ */
+export type CAIP2ChainId = `eip155:${string}`;
+
+/**
+ * CAIP-2 asset ID type (e.g., eip155:8453/erc20:0xa0b8691...)
+ */
+export type CAIP2AssetId = `eip155:${string}/erc20:${string}`;
+
+/**
+ * Payment destination - address, CAIP-2 chain ID, or CAIP asset ID
+ */
+export type PayToAddress = `0x${string}` | CAIP2ChainId | CAIP2AssetId;
+
+/**
+ * Pricing configuration for a specific network/token/facilitator combination
+ */
+export interface PricingConfig {
+  /** Network for this pricing */
+  network?: NetworkId;
+  /** Token for this pricing */
+  token?: TokenId;
+  /** Facilitator URL for this pricing (optional - applies to all facilitators if not specified) */
+  facilitator?: string;
+  /** Amount to charge */
+  amount: string;
+}
+
+/**
+ * Payment accept options for merchants (v2 multi-support)
+ */
+export interface AcceptPaymentOptions {
+  /** Networks to accept payments on */
+  networks?: NetworkId[];
+  /** Tokens to accept (defaults to ["usdc"]) */
+  tokens?: TokenId[];
+  /** Facilitator(s) for payment verification/settlement */
+  facilitators?: FacilitatorConfig | FacilitatorConfig[];
+  /** Protocol version (V2 only) */
+  version?: 2;
+  /** Pricing configurations - if not provided, uses amount from top-level config */
+  pricing?: PricingConfig[];
+}
+
+/**
+ * Result of a payment attempt
+ */
+export interface PaymentResult<T = unknown> {
+  /** Payment successful */
+  success: true;
+  /** Response data */
+  data: T;
+  /** Transaction hash (if settled) */
+  txHash?: string;
+}
+
+/**
+ * Payment error result
+ */
+export interface PaymentError {
+  /** Payment failed */
+  success: false;
+  /** Error code */
+  code: PaymentErrorCode;
+  /** Human-readable error message */
+  message: string;
+  /** Underlying error details */
+  details?: unknown;
+}
+
+/**
+ * Payment error codes
+ */
+export type PaymentErrorCode =
+  | "UNKNOWN_NETWORK"
+  | "UNKNOWN_TOKEN"
+  | "TOKEN_NOT_ON_NETWORK"
+  | "FACILITATOR_UNSUPPORTED"
+  | "FACILITATOR_NO_NETWORK_SUPPORT"
+  | "FACILITATOR_NO_TOKEN_SUPPORT"
+  | "INVALID_CAIP_FORMAT"
+  | "CHAIN_MISMATCH"
+  | "PAYMENT_REQUIRED"
+  | "PAYMENT_DECLINED"
+  | "SIGNING_FAILED"
+  | "NETWORK_ERROR"
+  | "VALIDATION_FAILED";
+
+/**
+ * Combined payment result type
+ */
+export type ArmoryPaymentResult<T = unknown> = PaymentResult<T> | PaymentError;
+
+// ═══════════════════════════════════════════════════════════════
+// Resolved Configuration (internal use)
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Fully resolved network configuration
+ */
+export interface ResolvedNetwork {
+  /** Original input */
+  input: NetworkId;
+  /** Network config */
+  config: NetworkConfig;
+  /** CAIP-2 ID */
+  caip2: `eip155:${string}`;
+}
+
+/**
+ * Fully resolved token configuration
+ */
+export interface ResolvedToken {
+  /** Original input */
+  input: TokenId;
+  /** Token config */
+  config: CustomToken;
+  /** CAIP Asset ID */
+  caipAsset: CAIPAssetId;
+  /** Network this token is on */
+  network: ResolvedNetwork;
+}
+
+/**
+ * Fully resolved facilitator configuration
+ */
+export interface ResolvedFacilitator {
+  /** Original input */
+  input: FacilitatorConfig;
+  /** URL */
+  url: string;
+  /** Supported networks (resolved) */
+  networks: ResolvedNetwork[];
+  /** Supported tokens (resolved) */
+  tokens: ResolvedToken[];
+}
+
+/**
+ * Fully resolved payment configuration
+ */
+export interface ResolvedPaymentConfig {
+  /** Network to use */
+  network: ResolvedNetwork;
+  /** Token to use */
+  token: ResolvedToken;
+  /** Facilitator(s) to use */
+  facilitators: ResolvedFacilitator[];
+  /** Protocol version (V2 only) */
+  version: 2;
+  /** Recipient address */
+  payTo: Address;
+  /** Amount to charge */
+  amount: string;
+}
+
+/**
+ * Validation error details
+ */
+export interface ValidationError {
+  /** Error code */
+  code: PaymentErrorCode;
+  /** Error message */
+  message: string;
+  /** Path to the invalid value */
+  path?: string;
+  /** Invalid value */
+  value?: unknown;
+  /** Valid options */
+  validOptions?: string[];
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Route Configuration Types
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Route pattern type for matching paths
+ */
+export type RoutePattern = string;
+
+/**
+ * Route matcher function type
+ */
+export type RouteMatcher = (path: string) => boolean;
+
+/**
+ * Route configuration with associated config data
+ */
+export interface RouteConfig<T = unknown> {
+  /** Route pattern (e.g., "/api/users", "/api/*", "/api/users/:id") */
+  pattern: RoutePattern;
+  /** Configuration associated with this route */
+  config: T;
+}
+
+/**
+ * Parsed route pattern information
+ */
+export interface ParsedPattern {
+  /** Route segments split by "/" */
+  segments: string[];
+  /** Whether this pattern contains a wildcard */
+  isWildcard: boolean;
+  /** Whether this pattern contains parameters (e.g., :id) */
+  isParametrized: boolean;
+  /** Parameter names extracted from the pattern */
+  paramNames: string[];
+  /** Match priority (higher = more specific) */
+  priority: number;
+}
+
+/**
+ * Route input configuration for middleware
+ */
+export interface RouteInputConfig {
+  /** Single exact route (no wildcards allowed) */
+  route?: string;
+  /** Multiple routes (allows wildcards) */
+  routes?: string[];
+}
+
+/**
+ * Route-specific validation error details
+ */
+export interface RouteValidationError {
+  /** Error code (custom string, not PaymentErrorCode) */
+  code: string;
+  /** Error message */
+  message: string;
+  /** Path to the invalid value */
+  path?: string;
+  /** Invalid value */
+  value?: unknown;
+  /** Valid options */
+  validOptions?: string[];
+}