@armory-sh/base 0.2.28 → 0.2.30

package/src/types/v2.ts

@@ -0,0 +1,282 @@
+/**
+ * Armory V2 Types - x402 Protocol V2 Compatible
+ *
+ * These types match the Coinbase x402 V2 specification for full interoperability.
+ * No conversion needed - this is the native format.
+ *
+ * Specification: https://github.com/coinbase/x402
+ */
+
+// ============================================================================
+// Base Types
+// ============================================================================
+
+export type CAIP2Network = `eip155:${string}`;
+
+export type CAIPAssetId = `eip155:${string}/erc20:${string}`;
+
+export type Address = `0x${string}`;
+
+export interface Signature {
+  v: number;
+  r: string;
+  s: string;
+}
+
+export type PayToV2 =
+  | Address
+  | {
+      role?: string;
+      callback?: string;
+    };
+
+export type PayToAddress = Address | PayToV2;
+
+export interface Extensions {
+  [key: string]: unknown;
+}
+
+// ============================================================================
+// Resource Info
+// ============================================================================
+
+/**
+ * Resource information describing the protected resource
+ */
+export interface ResourceInfo {
+  /** URL of the protected resource */
+  url: string;
+  /** Human-readable description of the resource */
+  description?: string;
+  /** MIME type of the expected response */
+  mimeType?: string;
+}
+
+// ============================================================================
+// Payment Requirements (Server → Client in accepts[] array)
+// ============================================================================
+
+/**
+ * Payment requirements for a specific payment method
+ * Matches x402 V2 PaymentRequirements spec
+ */
+export interface PaymentRequirementsV2 {
+  /** Payment scheme identifier (e.g., "exact") */
+  scheme: "exact";
+  /** Blockchain network identifier in CAIP-2 format */
+  network: CAIP2Network;
+  /** Required payment amount in atomic token units */
+  amount: string;
+  /** Token contract address (extracted from CAIP asset ID) */
+  asset: Address;
+  /** Recipient wallet address or role constant */
+  payTo: Address;
+  /** Maximum time allowed for payment completion */
+  maxTimeoutSeconds: number;
+  /** EIP-712 domain parameter: token name */
+  name?: string;
+  /** EIP-712 domain parameter: token version */
+  version?: string;
+  /** Scheme-specific additional information */
+  extra?: Extensions;
+}
+
+// ============================================================================
+// Payment Required Response (Server → Client, 402 status)
+// ============================================================================
+
+/**
+ * Payment required response (PAYMENT-REQUIRED header)
+ * Matches x402 V2 PaymentRequired spec
+ */
+export interface PaymentRequiredV2 {
+  /** Protocol version identifier (must be 2) */
+  x402Version: 2;
+  /** Human-readable error message */
+  error?: string;
+  /** Resource being accessed */
+  resource: ResourceInfo;
+  /** Array of acceptable payment methods */
+  accepts: PaymentRequirementsV2[];
+  /** Protocol extensions data */
+  extensions?: Extensions;
+}
+
+// ============================================================================
+// EIP-3009 Authorization (for exact scheme on EVM)
+// ============================================================================
+
+/**
+ * EIP-3009 TransferWithAuthorization authorization data
+ * Matches x402 V2 spec for exact scheme
+ */
+export interface EIP3009Authorization {
+  /** Payer's wallet address */
+  from: Address;
+  /** Recipient's wallet address */
+  to: Address;
+  /** Payment amount in atomic units */
+  value: string;
+  /** Unix timestamp when authorization becomes valid */
+  validAfter: string;
+  /** Unix timestamp when authorization expires */
+  validBefore: string;
+  /** 32-byte random nonce (bytes32 hex string) */
+  nonce: `0x${string}`;
+}
+
+/**
+ * Scheme-specific payment payload data
+ */
+export interface SchemePayloadV2 {
+  /** Signature for the authorization (0x-prefixed 65-byte hex) */
+  signature: `0x${string}`;
+  /** EIP-3009 authorization */
+  authorization: EIP3009Authorization;
+}
+
+// ============================================================================
+// Payment Payload (Client → Server, PAYMENT-SIGNATURE header)
+// ============================================================================
+
+/**
+ * Payment payload sent by client
+ * Matches x402 V2 PaymentPayload spec (Coinbase format)
+ *
+ * The 'accepted' field echoes the server's requirements being accepted.
+ */
+export interface PaymentPayloadV2 {
+  /** Protocol version identifier */
+  x402Version: 2;
+  /** The payment requirements being accepted (echoed from server) */
+  accepted: PaymentRequirementsV2;
+  /** Scheme-specific payment data */
+  payload: SchemePayloadV2;
+  /** Resource being accessed (optional) */
+  resource?: ResourceInfo;
+  /** Protocol extensions data */
+  extensions?: Extensions;
+}
+
+// ============================================================================
+// Settlement Response (Server → Client, PAYMENT-RESPONSE header)
+// ============================================================================
+
+/**
+ * Settlement response after payment settlement
+ * Matches x402 V2 SettlementResponse spec
+ */
+export interface SettlementResponseV2 {
+  /** Whether settlement was successful */
+  success: boolean;
+  /** Error reason if settlement failed */
+  errorReason?: string;
+  /** Address of the payer's wallet */
+  payer?: Address;
+  /** Blockchain transaction hash (empty if failed) */
+  transaction: string;
+  /** Blockchain network identifier in CAIP-2 format */
+  network: CAIP2Network;
+  /** Protocol extensions data */
+  extensions?: Extensions;
+}
+
+// ============================================================================
+// Headers
+// ============================================================================
+
+export const V2_HEADERS = {
+  PAYMENT_SIGNATURE: "PAYMENT-SIGNATURE",
+  PAYMENT_REQUIRED: "PAYMENT-REQUIRED",
+  PAYMENT_RESPONSE: "PAYMENT-RESPONSE",
+} as const;
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export function isCAIP2ChainId(value: string): value is CAIP2Network {
+  return /^eip155:\d+$/.test(value);
+}
+
+export function isCAIPAssetId(value: string): value is CAIPAssetId {
+  return /^eip155:\d+\/erc20:0x[a-fA-F0-9]+$/.test(value);
+}
+
+export function isAddress(value: string): value is Address {
+  return /^0x[a-fA-F0-9]{40}$/.test(value);
+}
+
+export function isPaymentRequiredV2(obj: unknown): obj is PaymentRequiredV2 {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    "x402Version" in obj &&
+    (obj as PaymentRequiredV2).x402Version === 2 &&
+    "resource" in obj &&
+    "accepts" in obj &&
+    Array.isArray((obj as PaymentRequiredV2).accepts)
+  );
+}
+
+export function isPaymentPayloadV2(obj: unknown): obj is PaymentPayloadV2 {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    "x402Version" in obj &&
+    (obj as PaymentPayloadV2).x402Version === 2 &&
+    "accepted" in obj &&
+    "payload" in obj
+  );
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Extract token address from CAIP asset ID
+ */
+export function assetIdToAddress(assetId: CAIPAssetId): Address {
+  const match = assetId.match(/\/erc20:(0x[a-fA-F0-9]{40})$/);
+  if (!match) throw new Error(`Invalid CAIP asset ID: ${assetId}`);
+  return match[1] as Address;
+}
+
+/**
+ * Create CAIP asset ID from token address and chain ID
+ */
+export function addressToAssetId(
+  address: Address,
+  chainId: string | number,
+): CAIPAssetId {
+  const chain = typeof chainId === "number" ? `eip155:${chainId}` : chainId;
+  if (!isCAIP2ChainId(chain)) throw new Error(`Invalid chain ID: ${chain}`);
+  return `${chain}/erc20:${address}` as CAIPAssetId;
+}
+
+/**
+ * Parse combined signature (0x + r + s + v) into components
+ */
+export function parseSignature(signature: `0x${string}`): Signature {
+  const sig = signature.slice(2);
+  return {
+    r: `0x${sig.slice(0, 64)}`,
+    s: `0x${sig.slice(64, 128)}`,
+    v: parseInt(sig.slice(128, 130), 16),
+  };
+}
+
+/**
+ * Combine signature components into 65-byte hex string
+ */
+export function combineSignature(
+  v: number,
+  r: string,
+  s: string,
+): `0x${string}` {
+  const rClean = r.startsWith("0x") ? r.slice(2) : r;
+  const sClean = s.startsWith("0x") ? s.slice(2) : s;
+  const vHex = v.toString(16).padStart(2, "0");
+  return `0x${rClean}${sClean}${vHex}` as `0x${string}`;
+}

package/src/types/wallet.ts

@@ -0,0 +1,30 @@
+/**
+ * Generic Wallet Adapter Interface
+ *
+ * This interface defines the minimum wallet operations required
+ * for x402 payment signing. Each client package implements this
+ * interface for their specific wallet library (viem, ethers, etc.).
+ */
+
+export interface PaymentWallet {
+  /**
+   * Get the wallet address
+   * Can be synchronous or asynchronous depending on the wallet library
+   */
+  getAddress(): string | Promise<string>;
+
+  /**
+   * Sign EIP-712 typed data
+   * Used for EIP-3009 TransferWithAuthorization signatures
+   *
+   * @param domain - EIP-712 domain separator
+   * @param types - EIP-712 type definitions
+   * @param value - Message to sign
+   * @returns Signature as hex string (0x-prefixed)
+   */
+  signTypedData(
+    domain: Record<string, unknown>,
+    types: Record<string, unknown>,
+    value: Record<string, unknown>,
+  ): Promise<string>;
+}

package/src/types/x402.ts

@@ -0,0 +1,151 @@
+/**
+ * X402 Protocol Types - Coinbase Compatible Format
+ *
+ * This module provides types that match the official Coinbase x402 SDK format
+ * for full interoperability with their facilitator and extensions.
+ */
+
+export type Address = `0x${string}`;
+export type Hex = `0x${string}`;
+
+// X402 Protocol Version
+export const X402_VERSION = 2 as const;
+export type X402Version = typeof X402_VERSION;
+
+// Supported schemes
+export const SCHEMES = ["exact"] as const;
+export type Scheme = (typeof SCHEMES)[number];
+
+// Supported networks (CAIP-2 format)
+export type Network =
+  | "base"
+  | "base-sepolia"
+  | "ethereum"
+  | "ethereum-sepolia"
+  | "polygon"
+  | "polygon-amoy"
+  | "arbitrum"
+  | "arbitrum-sepolia"
+  | "optimism"
+  | "optimism-sepolia"
+  | string; // For custom networks
+
+/**
+ * EIP-3009 TransferWithAuthorization authorization data
+ */
+export interface ExactEvmAuthorization {
+  from: Address;
+  to: Address;
+  value: string; // Atomic units (e.g., "1500000" for 1.5 USDC)
+  validAfter: string; // Unix timestamp as string
+  validBefore: string; // Unix timestamp as string (expiry)
+  nonce: Hex; // 32-byte hex string (bytes32)
+}
+
+/**
+ * Exact EVM payment payload structure
+ */
+export interface ExactEvmPayload {
+  signature: Hex; // Full hex signature (0x + r + s + v)
+  authorization: ExactEvmAuthorization;
+}
+
+/**
+ * Resource information for payment payload
+ */
+export interface ResourceInfo {
+  url: string;
+  description?: string;
+  mimeType?: string;
+}
+
+/**
+ * Payment payload - Coinbase compatible format (x402 v2)
+ * Uses 'accepted' field to echo server's requirements
+ */
+export interface PaymentPayload {
+  x402Version: X402Version;
+  accepted: PaymentRequirements;
+  payload: ExactEvmPayload;
+  resource?: ResourceInfo;
+  extensions?: Record<string, unknown>;
+}
+
+/**
+ * Unsigned payment payload (before signing)
+ */
+export interface UnsignedPaymentPayload {
+  x402Version: X402Version;
+  accepted: PaymentRequirements;
+  payload: Omit<ExactEvmPayload, "signature"> & { signature: undefined };
+  resource?: ResourceInfo;
+  extensions?: Record<string, unknown>;
+}
+
+/**
+ * Payment requirements for 402 response
+ * Matches x402 SDK format
+ */
+export interface PaymentRequirements {
+  scheme: Scheme;
+  network: Network;
+  amount: string; // Atomic units (x402 V2 spec)
+  payTo: Address;
+  maxTimeoutSeconds: number;
+  asset: Address; // Token contract address
+  name?: string; // EIP-712 domain parameter
+  version?: string; // EIP-712 domain parameter
+  extra?: Record<string, unknown>; // Additional extensions
+}
+
+/**
+ * Settlement response
+ */
+export interface SettlementResponse {
+  success: boolean;
+  errorReason?: string;
+  payer?: Address;
+  transaction: string; // Transaction hash
+  network: Network;
+}
+
+/**
+ * Verify response
+ */
+export interface VerifyResponse {
+  isValid: boolean;
+  invalidReason?: string;
+  payer?: Address;
+}
+
+/**
+ * X402 response structure for 402 errors
+ */
+export interface X402Response {
+  x402Version: X402Version;
+  error?: string;
+  accepts?: PaymentRequirements[];
+  payer?: Address;
+}
+
+/**
+ * Type guards
+ */
+export function isPaymentPayload(obj: unknown): obj is PaymentPayload {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    "x402Version" in obj &&
+    "accepted" in obj &&
+    "payload" in obj
+  );
+}
+
+export function isExactEvmPayload(obj: unknown): obj is ExactEvmPayload {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    "signature" in obj &&
+    "authorization" in obj
+  );
+}

package/src/utils/base64.ts

@@ -0,0 +1,48 @@
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+function toBase64(bytes: Uint8Array): string {
+  if (typeof btoa === "function") {
+    let binary = "";
+    for (let index = 0; index < bytes.length; index += 1) {
+      binary += String.fromCharCode(bytes[index]);
+    }
+    return btoa(binary);
+  }
+
+  throw new Error("No base64 encoder available in this runtime");
+}
+
+function fromBase64(base64: string): Uint8Array {
+  if (typeof atob === "function") {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+      bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+  }
+
+  throw new Error("No base64 decoder available in this runtime");
+}
+
+export function encodeUtf8ToBase64(value: string): string {
+  const bytes = textEncoder.encode(value);
+  return toBase64(bytes);
+}
+
+export function decodeBase64ToUtf8(value: string): string {
+  const bytes = fromBase64(value);
+  return textDecoder.decode(bytes);
+}
+
+export function toBase64Url(base64: string): string {
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+
+export function normalizeBase64Url(value: string): string {
+  return value
+    .replace(/-/g, "+")
+    .replace(/_/g, "/")
+    .padEnd(Math.ceil(value.length / 4) * 4, "=");
+}