@armory-sh/base 0.2.0 → 0.2.1

package/dist/encoding/x402.d.ts

@@ -0,0 +1,85 @@
+/**
+ * X402 Protocol Encoding - Coinbase Compatible
+ *
+ * All payment payloads are Base64 encoded for transport in HTTP headers.
+ * This matches the Coinbase x402 SDK format.
+ */
+import type { PaymentPayload, SettlementResponse, X402Response, LegacyPaymentPayload, PaymentPayloadV1, PaymentPayloadV2, PaymentRequirements } from "../types/x402";
+/**
+ * Safe Base64 encode (URL-safe, no padding)
+ */
+export declare function safeBase64Encode(str: string): string;
+/**
+ * Safe Base64 decode (handles URL-safe format)
+ */
+export declare function safeBase64Decode(str: string): string;
+/**
+ * Encode payment payload to Base64 string
+ * All versions use Base64 encoding for compatibility
+ */
+export declare function encodePayment(payload: PaymentPayload | LegacyPaymentPayload): string;
+/**
+ * Decode payment payload from Base64 string
+ */
+export declare function decodePayment(encoded: string): PaymentPayload;
+/**
+ * Encode settlement response to Base64 string
+ */
+export declare function encodeSettlementResponse(response: SettlementResponse): string;
+/**
+ * Decode settlement response from Base64 string
+ */
+export declare function decodeSettlementResponse(encoded: string): SettlementResponse;
+/**
+ * Encode X402 error response
+ */
+export declare function encodeX402Response(response: X402Response): string;
+/**
+ * Decode X402 error response
+ */
+export declare function decodeX402Response(encoded: string): X402Response;
+/**
+ * Unified X402 headers - Coinbase compatible
+ */
+export declare const X402_HEADERS: {
+    readonly PAYMENT: "X-PAYMENT";
+    readonly PAYMENT_RESPONSE: "X-PAYMENT-RESPONSE";
+    readonly PAYMENT_REQUIRED: "X-PAYMENT-REQUIRED";
+};
+/**
+ * Detect payment version from headers
+ * Returns null if no payment header found
+ *
+ * Supports both x402 format (X-PAYMENT header with x402Version)
+ * and legacy format (X-PAYMENT for v1, PAYMENT-SIGNATURE for v2)
+ */
+export declare function detectPaymentVersion(headers: Headers): number | null;
+/**
+ * Extract payment from headers
+ */
+export declare function extractPaymentFromHeaders(headers: Headers): PaymentPayload | null;
+/**
+ * Create payment required headers
+ */
+export declare function createPaymentRequiredHeaders(requirements: PaymentRequirements | PaymentRequirements[]): Record<string, string>;
+/**
+ * Create settlement response headers
+ */
+export declare function createSettlementHeaders(settlement: SettlementResponse): Record<string, string>;
+export declare const encodePaymentV1: typeof encodePayment;
+export declare const decodePaymentV1: typeof decodePayment;
+export declare const encodePaymentV2: typeof encodePayment;
+export declare const decodePaymentV2: typeof decodePayment;
+export declare const encodeSettlementV1: typeof encodeSettlementResponse;
+export declare const decodeSettlementV1: typeof decodeSettlementResponse;
+export declare const encodeSettlementV2: typeof encodeSettlementResponse;
+export declare const decodeSettlementV2: typeof decodeSettlementResponse;
+/**
+ * Type guards for legacy compatibility
+ */
+export declare function isLegacyV1(payload: unknown): payload is PaymentPayloadV1;
+export declare function isLegacyV2(payload: unknown): payload is PaymentPayloadV2;
+/**
+ * Decode settlement from headers (legacy compatibility)
+ */
+export declare function decodeSettlement(headers: Headers): SettlementResponse;

package/dist/index.d.ts

@@ -1,16 +1,19 @@
+export type { Address as X402Address, Hex, X402Version, Scheme, Network as X402Network, ExactEvmAuthorization, ExactEvmPayload, PaymentPayload as X402PaymentPayload, UnsignedPaymentPayload as X402UnsignedPaymentPayload, PaymentRequirements as X402PaymentRequirements, SettlementResponse as X402SettlementResponse, VerifyResponse, X402Response, PaymentPayloadV1 as X402PayloadV1, PaymentPayloadV2 as X402PayloadV2, LegacyPaymentPayload as X402LegacyPayload, } from "./types/x402";
+export { X402_VERSION, SCHEMES, isPaymentPayload, isExactEvmPayload, legacyToPaymentPayload, } from "./types/x402";
+export { safeBase64Encode, safeBase64Decode, encodePayment, decodePayment, encodeSettlementResponse, decodeSettlementResponse, encodeX402Response, decodeX402Response, X402_HEADERS, detectPaymentVersion, extractPaymentFromHeaders, createPaymentRequiredHeaders, createSettlementHeaders, isLegacyV1, isLegacyV2, } from "./encoding/x402";
+export { createNonce, toAtomicUnits, fromAtomicUnits, parseSignature, combineSignature, caip2ToNetwork, networkToCaip2, getCurrentTimestamp, isValidAddress, normalizeAddress, } from "./utils/x402";
 export type { PaymentPayloadV1, PaymentRequirementsV1, SettlementResponseV1, } from "./types/v1";
-export { V1_HEADERS, encodePaymentPayload, decodePaymentPayload, encodeSettlementResponse, decodeSettlementResponse, } from "./types/v1";
+export { V1_HEADERS, encodePaymentPayload, decodePaymentPayload, encodeSettlementResponse as encodeSettlementResponseV1, decodeSettlementResponse as decodeSettlementResponseV1, } from "./types/v1";
 export type { CAIP2ChainId, CAIPAssetId, Address, Signature, PayToV2, Extensions, PaymentPayloadV2, PaymentRequirementsV2, SettlementResponseV2, } from "./types/v2";
 export { V2_HEADERS, isCAIP2ChainId, isCAIPAssetId, isAddress, } from "./types/v2";
 export type { PaymentPayload, PaymentRequirements, SettlementResponse, } from "./types/protocol";
-export { isV1, isV2, getPaymentVersion as getPaymentVersionFromPayload, getRequirementsVersion, getSettlementVersion, getPaymentHeaderName, getPaymentResponseHeaderName, getPaymentRequiredHeaderName, isSettlementSuccessful, getTxHash, } from "./types/protocol";
+export { isV1, isV2, getPaymentVersion, getRequirementsVersion, getSettlementVersion, getPaymentHeaderName, getPaymentResponseHeaderName, getPaymentRequiredHeaderName, isSettlementSuccessful, getTxHash, } from "./types/protocol";
 export type { NetworkConfig, CustomToken } from "./types/networks";
 export { NETWORKS, getNetworkConfig, getNetworkByChainId, getMainnets, getTestnets, registerToken, getCustomToken, getAllCustomTokens, unregisterToken, isCustomToken, } from "./types/networks";
 export type { TransferWithAuthorizationParams, ReceiveWithAuthorizationParams, BalanceOfParams, BalanceOfReturnType, NameReturnType, SymbolReturnType, ERC20Abi, } from "./abi/erc20";
 export { ERC20_ABI } from "./abi/erc20";
-export type { PaymentPayload as EncodingPaymentPayload, SettlementResponse as EncodingSettlementResponse, } from "./encoding";
-export { encodePaymentV1, decodePaymentV1, encodeSettlementV1, decodeSettlementV1, encodePaymentV2, decodePaymentV2, encodeSettlementV2, decodeSettlementV2, detectPaymentVersion, decodePayment, decodeSettlement, isPaymentV1, isPaymentV2, isSettlementV1, isSettlementV2, } from "./encoding";
 export type { TypedDataDomain, EIP712Domain, TransferWithAuthorization, TypedDataField, EIP712Types, } from "./eip712";
 export { EIP712_TYPES, USDC_DOMAIN, createEIP712Domain, createTransferWithAuthorization, validateTransferWithAuthorization, } from "./eip712";
 export { resolveNetwork, resolveToken, resolveFacilitator, checkFacilitatorSupport, validatePaymentConfig, validateAcceptConfig, getAvailableNetworks, getAvailableTokens, isValidationError, isResolvedNetwork, isResolvedToken, createError, } from "./validation";
+export { encodePaymentV1, decodePaymentV1, encodeSettlementV1, decodeSettlementV1, encodePaymentV2, decodePaymentV2, encodeSettlementV2, decodeSettlementV2, detectPaymentVersion as detectPaymentVersionLegacy, decodePayment as decodePaymentLegacy, decodeSettlement as decodeSettlementLegacy, isPaymentV1, isPaymentV2, isSettlementV1, isSettlementV2, } from "./encoding";
 export type { NetworkId, TokenId, FacilitatorConfig, AcceptPaymentOptions, PaymentResult, PaymentError, PaymentErrorCode, ArmoryPaymentResult, ResolvedNetwork, ResolvedToken, ResolvedFacilitator, ResolvedPaymentConfig, ValidationError, } from "./types/simple";

package/dist/index.js

@@ -1,3 +1,307 @@
+// src/types/x402.ts
+var X402_VERSION = 1;
+var SCHEMES = ["exact"];
+var CHAIN_ID_TO_NETWORK = {
+  1: "ethereum",
+  8453: "base",
+  84532: "base-sepolia",
+  137: "polygon",
+  42161: "arbitrum",
+  421614: "arbitrum-sepolia",
+  10: "optimism",
+  11155420: "optimism-sepolia",
+  11155111: "ethereum-sepolia"
+};
+function isPaymentPayload(obj) {
+  return typeof obj === "object" && obj !== null && "x402Version" in obj && "scheme" in obj && "network" in obj && "payload" in obj;
+}
+function isExactEvmPayload(obj) {
+  return typeof obj === "object" && obj !== null && "signature" in obj && "authorization" in obj;
+}
+function extractNetworkFromLegacy(legacy) {
+  if ("network" in legacy && typeof legacy.network === "string") {
+    return legacy.network;
+  }
+  if ("chainId" in legacy && typeof legacy.chainId === "string") {
+    const match = legacy.chainId.match(/^eip155:(\d+)$/);
+    if (match) {
+      const chainId = parseInt(match[1], 10);
+      return CHAIN_ID_TO_NETWORK[chainId] || `eip155:${chainId}`;
+    }
+  }
+  if ("chainId" in legacy && typeof legacy.chainId === "number") {
+    return CHAIN_ID_TO_NETWORK[legacy.chainId] || `eip155:${legacy.chainId}`;
+  }
+  return "base";
+}
+function extractSignatureFromLegacy(legacy) {
+  if ("v" in legacy && "r" in legacy && "s" in legacy) {
+    const v = legacy.v.toString(16).padStart(2, "0");
+    const r = legacy.r.startsWith("0x") ? legacy.r.slice(2) : legacy.r;
+    const s = legacy.s.startsWith("0x") ? legacy.s.slice(2) : legacy.s;
+    return `0x${r}${s}${v}`;
+  }
+  if ("signature" in legacy && typeof legacy.signature === "object" && legacy.signature !== null) {
+    const sig = legacy.signature;
+    const v = sig.v.toString(16).padStart(2, "0");
+    const r = sig.r.startsWith("0x") ? sig.r.slice(2) : sig.r;
+    const s = sig.s.startsWith("0x") ? sig.s.slice(2) : sig.s;
+    return `0x${r}${s}${v}`;
+  }
+  return "0x";
+}
+function convertAmountToAtomic(amount) {
+  if (amount.includes(".")) {
+    const parts = amount.split(".");
+    const whole = parts[0];
+    const fractional = parts[1] || "";
+    const paddedFractional = fractional.padEnd(6, "0").slice(0, 6);
+    return `${whole}${paddedFractional}`;
+  }
+  return amount;
+}
+function convertNonceToHex(nonce) {
+  if (nonce.startsWith("0x") && nonce.length === 66) {
+    return nonce;
+  }
+  const hex = BigInt(nonce).toString(16).padStart(64, "0");
+  return `0x${hex}`;
+}
+function extractFromAddress(legacy) {
+  return legacy.from;
+}
+function extractToAddress(legacy) {
+  if ("to" in legacy && typeof legacy.to === "string") {
+    return legacy.to;
+  }
+  return legacy.from;
+}
+function legacyToPaymentPayload(legacy) {
+  if (isPaymentPayload(legacy)) {
+    return legacy;
+  }
+  const network = extractNetworkFromLegacy(legacy);
+  const signature = extractSignatureFromLegacy(legacy);
+  const value = convertAmountToAtomic(legacy.amount);
+  const nonce = convertNonceToHex(legacy.nonce);
+  const from = extractFromAddress(legacy);
+  const to = extractToAddress(legacy);
+  return {
+    x402Version: X402_VERSION,
+    scheme: "exact",
+    network,
+    payload: {
+      signature,
+      authorization: {
+        from,
+        to,
+        value,
+        validAfter: "0",
+        validBefore: legacy.expiry.toString(),
+        nonce
+      }
+    }
+  };
+}
+
+// src/encoding/x402.ts
+function safeBase64Encode(str) {
+  return Buffer.from(str).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+function safeBase64Decode(str) {
+  const padding = 4 - str.length % 4;
+  if (padding !== 4) {
+    str += "=".repeat(padding);
+  }
+  str = str.replace(/-/g, "+").replace(/_/g, "/");
+  return Buffer.from(str, "base64").toString("utf-8");
+}
+function encodePayment(payload) {
+  let normalizedPayload;
+  if (isPaymentPayload(payload)) {
+    normalizedPayload = payload;
+  } else {
+    normalizedPayload = legacyToPaymentPayload(payload);
+  }
+  const safePayload = JSON.parse(JSON.stringify(normalizedPayload, (_, value) => {
+    if (typeof value === "bigint") {
+      return value.toString();
+    }
+    return value;
+  }));
+  return safeBase64Encode(JSON.stringify(safePayload));
+}
+function decodePayment(encoded) {
+  const decoded = safeBase64Decode(encoded);
+  const parsed = JSON.parse(decoded);
+  if (!isPaymentPayload(parsed)) {
+    return legacyToPaymentPayload(parsed);
+  }
+  return parsed;
+}
+function encodeSettlementResponse(response) {
+  const safeResponse = JSON.parse(JSON.stringify(response, (_, value) => {
+    if (typeof value === "bigint") {
+      return value.toString();
+    }
+    return value;
+  }));
+  return safeBase64Encode(JSON.stringify(safeResponse));
+}
+function decodeSettlementResponse(encoded) {
+  const decoded = safeBase64Decode(encoded);
+  return JSON.parse(decoded);
+}
+function encodeX402Response(response) {
+  return safeBase64Encode(JSON.stringify(response));
+}
+function decodeX402Response(encoded) {
+  const decoded = safeBase64Decode(encoded);
+  return JSON.parse(decoded);
+}
+var X402_HEADERS = {
+  PAYMENT: "X-PAYMENT",
+  PAYMENT_RESPONSE: "X-PAYMENT-RESPONSE",
+  PAYMENT_REQUIRED: "X-PAYMENT-REQUIRED"
+};
+function detectPaymentVersion(headers) {
+  if (headers.has("PAYMENT-SIGNATURE")) {
+    return 2;
+  }
+  if (headers.has(X402_HEADERS.PAYMENT)) {
+    const encoded = headers.get(X402_HEADERS.PAYMENT);
+    if (encoded) {
+      try {
+        const decoded = decodePayment(encoded);
+        if (isPaymentPayload(decoded) && "x402Version" in decoded) {
+          return decoded.x402Version;
+        }
+        return 1;
+      } catch {
+        return 1;
+      }
+    }
+    return 1;
+  }
+  return null;
+}
+function extractPaymentFromHeaders(headers) {
+  const encoded = headers.get(X402_HEADERS.PAYMENT);
+  if (!encoded) return null;
+  try {
+    return decodePayment(encoded);
+  } catch {
+    return null;
+  }
+}
+function createPaymentRequiredHeaders(requirements) {
+  const accepts = Array.isArray(requirements) ? requirements : [requirements];
+  const response = {
+    x402Version: 1,
+    accepts
+  };
+  return {
+    [X402_HEADERS.PAYMENT_REQUIRED]: safeBase64Encode(JSON.stringify(response))
+  };
+}
+function createSettlementHeaders(settlement) {
+  return {
+    [X402_HEADERS.PAYMENT_RESPONSE]: encodeSettlementResponse(settlement)
+  };
+}
+function isLegacyV1(payload) {
+  return typeof payload === "object" && payload !== null && "v" in payload && typeof payload.v === "number";
+}
+function isLegacyV2(payload) {
+  return typeof payload === "object" && payload !== null && "signature" in payload && typeof payload.signature === "object";
+}
+
+// src/utils/x402.ts
+import { randomBytes } from "crypto";
+function createNonce() {
+  const bytes = randomBytes(32);
+  return `0x${bytes.toString("hex")}`;
+}
+function toAtomicUnits(amount, decimals = 6) {
+  const parts = amount.split(".");
+  const whole = parts[0];
+  const fractional = parts[1] || "";
+  const paddedFractional = fractional.padEnd(decimals, "0").slice(0, decimals);
+  return `${whole}${paddedFractional}`;
+}
+function fromAtomicUnits(amount, decimals = 6) {
+  const value = BigInt(amount);
+  const divisor = BigInt(10 ** decimals);
+  const whole = (value / divisor).toString();
+  const fractional = (value % divisor).toString().padStart(decimals, "0").replace(/0+$/, "");
+  if (fractional.length === 0) {
+    return whole;
+  }
+  return `${whole}.${fractional}`;
+}
+function parseSignature(signature) {
+  const hex = signature.startsWith("0x") ? signature.slice(2) : signature;
+  const r = `0x${hex.slice(0, 64)}`;
+  const s = `0x${hex.slice(64, 128)}`;
+  const v = parseInt(hex.slice(128, 130) || "1c", 16);
+  return { r, s, v };
+}
+function combineSignature(r, s, v) {
+  const rHex = r.startsWith("0x") ? r.slice(2) : r;
+  const sHex = s.startsWith("0x") ? s.slice(2) : s;
+  const vHex = v.toString(16).padStart(2, "0");
+  return `0x${rHex}${sHex}${vHex}`;
+}
+function caip2ToNetwork(caip2Id) {
+  const match = caip2Id.match(/^eip155:(\d+)$/);
+  if (!match) {
+    return caip2Id;
+  }
+  const chainId = parseInt(match[1], 10);
+  const chainIdToNetwork = {
+    1: "ethereum",
+    8453: "base",
+    84532: "base-sepolia",
+    137: "polygon",
+    42161: "arbitrum",
+    421614: "arbitrum-sepolia",
+    10: "optimism",
+    11155420: "optimism-sepolia",
+    11155111: "ethereum-sepolia"
+  };
+  return chainIdToNetwork[chainId] || caip2Id;
+}
+function networkToCaip2(network) {
+  const networkToChainId = {
+    ethereum: 1,
+    base: 8453,
+    "base-sepolia": 84532,
+    polygon: 137,
+    arbitrum: 42161,
+    "arbitrum-sepolia": 421614,
+    optimism: 10,
+    "optimism-sepolia": 11155420,
+    "ethereum-sepolia": 11155111
+  };
+  const chainId = networkToChainId[network];
+  if (chainId) {
+    return `eip155:${chainId}`;
+  }
+  if (network.startsWith("eip155:")) {
+    return network;
+  }
+  return `eip155:0`;
+}
+function getCurrentTimestamp() {
+  return Math.floor(Date.now() / 1e3);
+}
+function isValidAddress(address) {
+  return /^0x[a-fA-F0-9]{40}$/.test(address);
+}
+function normalizeAddress(address) {
+  return address.toLowerCase();
+}
+
 // src/types/v1.ts
 var V1_HEADERS = {
   PAYMENT: "X-PAYMENT",
@@ -9,10 +313,10 @@ function encodePaymentPayload(payload) {
 function decodePaymentPayload(encoded) {
   return JSON.parse(Buffer.from(encoded, "base64").toString("utf-8"));
 }
-function encodeSettlementResponse(response) {
+function encodeSettlementResponse2(response) {
   return Buffer.from(JSON.stringify(response)).toString("base64");
 }
-function decodeSettlementResponse(encoded) {
+function decodeSettlementResponse2(encoded) {
   return JSON.parse(Buffer.from(encoded, "base64").toString("utf-8"));
 }
 
@@ -167,46 +471,6 @@ var ERC20_ABI = [
   }
 ];
 
-// src/encoding.ts
-var base64Encode = (data) => Buffer.from(JSON.stringify(data)).toString("base64");
-var base64Decode = (encoded) => JSON.parse(Buffer.from(encoded, "base64").toString("utf-8"));
-var jsonEncode = (data) => JSON.stringify(data);
-var jsonDecode = (encoded) => JSON.parse(encoded);
-var encodePaymentV1 = (payload) => base64Encode(payload);
-var decodePaymentV1 = (encoded) => base64Decode(encoded);
-var encodeSettlementV1 = (response) => base64Encode(response);
-var decodeSettlementV1 = (encoded) => base64Decode(encoded);
-var encodePaymentV2 = (payload) => jsonEncode(payload);
-var decodePaymentV2 = (encoded) => jsonDecode(encoded);
-var encodeSettlementV2 = (response) => jsonEncode(response);
-var decodeSettlementV2 = (encoded) => jsonDecode(encoded);
-var detectPaymentVersion = (headers) => {
-  if (headers.has(V1_HEADERS.PAYMENT)) return 1;
-  if (headers.has(V2_HEADERS.PAYMENT_SIGNATURE)) return 2;
-  return null;
-};
-var decodePayment = (headers) => {
-  const version = detectPaymentVersion(headers);
-  if (version === null) {
-    throw new Error("No valid payment headers found. Expected X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2)");
-  }
-  const headerName = version === 1 ? V1_HEADERS.PAYMENT : V2_HEADERS.PAYMENT_SIGNATURE;
-  const encoded = headers.get(headerName);
-  if (!encoded) throw new Error(`Header ${headerName} is empty`);
-  return version === 1 ? decodePaymentV1(encoded) : decodePaymentV2(encoded);
-};
-var decodeSettlement = (headers) => {
-  const v1Response = headers.get(V1_HEADERS.PAYMENT_RESPONSE);
-  if (v1Response) return decodeSettlementV1(v1Response);
-  const v2Response = headers.get(V2_HEADERS.PAYMENT_RESPONSE);
-  if (v2Response) return decodeSettlementV2(v2Response);
-  throw new Error("No valid settlement response headers found. Expected X-PAYMENT-RESPONSE (v1) or PAYMENT-RESPONSE (v2)");
-};
-var isPaymentV1 = (payload) => "v" in payload && typeof payload.v === "number";
-var isPaymentV2 = (payload) => "signature" in payload && typeof payload.signature === "object";
-var isSettlementV1 = (response) => "success" in response;
-var isSettlementV2 = (response) => "status" in response;
-
 // src/eip712.ts
 var EIP712_TYPES = {
   TransferWithAuthorization: [
@@ -664,35 +928,93 @@ var isResolvedNetwork = (value) => {
 var isResolvedToken = (value) => {
   return typeof value === "object" && value !== null && "config" in value && "caipAsset" in value;
 };
+
+// src/encoding.ts
+var base64Encode = (data) => Buffer.from(JSON.stringify(data)).toString("base64");
+var base64Decode = (encoded) => JSON.parse(Buffer.from(encoded, "base64").toString("utf-8"));
+var jsonEncode = (data) => JSON.stringify(data);
+var jsonDecode = (encoded) => JSON.parse(encoded);
+var encodePaymentV1 = (payload) => base64Encode(payload);
+var decodePaymentV1 = (encoded) => base64Decode(encoded);
+var encodeSettlementV1 = (response) => base64Encode(response);
+var decodeSettlementV1 = (encoded) => base64Decode(encoded);
+var encodePaymentV2 = (payload) => jsonEncode(payload);
+var decodePaymentV2 = (encoded) => jsonDecode(encoded);
+var encodeSettlementV2 = (response) => jsonEncode(response);
+var decodeSettlementV2 = (encoded) => jsonDecode(encoded);
+var detectPaymentVersion2 = (headers) => {
+  if (headers.has(V1_HEADERS.PAYMENT)) return 1;
+  if (headers.has(V2_HEADERS.PAYMENT_SIGNATURE)) return 2;
+  return null;
+};
+var decodePayment2 = (headers) => {
+  const version = detectPaymentVersion2(headers);
+  if (version === null) {
+    throw new Error("No valid payment headers found. Expected X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2)");
+  }
+  const headerName = version === 1 ? V1_HEADERS.PAYMENT : V2_HEADERS.PAYMENT_SIGNATURE;
+  const encoded = headers.get(headerName);
+  if (!encoded) throw new Error(`Header ${headerName} is empty`);
+  return version === 1 ? decodePaymentV1(encoded) : decodePaymentV2(encoded);
+};
+var decodeSettlement = (headers) => {
+  const v1Response = headers.get(V1_HEADERS.PAYMENT_RESPONSE);
+  if (v1Response) return decodeSettlementV1(v1Response);
+  const v2Response = headers.get(V2_HEADERS.PAYMENT_RESPONSE);
+  if (v2Response) return decodeSettlementV2(v2Response);
+  throw new Error("No valid settlement response headers found. Expected X-PAYMENT-RESPONSE (v1) or PAYMENT-RESPONSE (v2)");
+};
+var isPaymentV1 = (payload) => "v" in payload && typeof payload.v === "number";
+var isPaymentV2 = (payload) => "signature" in payload && typeof payload.signature === "object";
+var isSettlementV1 = (response) => "success" in response;
+var isSettlementV2 = (response) => "status" in response;
 export {
   EIP712_TYPES,
   ERC20_ABI,
   NETWORKS,
+  SCHEMES,
   USDC_DOMAIN,
   V1_HEADERS,
   V2_HEADERS,
+  X402_HEADERS,
+  X402_VERSION,
+  caip2ToNetwork,
   checkFacilitatorSupport,
+  combineSignature,
   createEIP712Domain,
   createError,
+  createNonce,
+  createPaymentRequiredHeaders,
+  createSettlementHeaders,
   createTransferWithAuthorization,
   decodePayment,
+  decodePayment2 as decodePaymentLegacy,
   decodePaymentPayload,
   decodePaymentV1,
   decodePaymentV2,
-  decodeSettlement,
+  decodeSettlement as decodeSettlementLegacy,
   decodeSettlementResponse,
+  decodeSettlementResponse2 as decodeSettlementResponseV1,
   decodeSettlementV1,
   decodeSettlementV2,
+  decodeX402Response,
   detectPaymentVersion,
+  detectPaymentVersion2 as detectPaymentVersionLegacy,
+  encodePayment,
   encodePaymentPayload,
   encodePaymentV1,
   encodePaymentV2,
   encodeSettlementResponse,
+  encodeSettlementResponse2 as encodeSettlementResponseV1,
   encodeSettlementV1,
   encodeSettlementV2,
+  encodeX402Response,
+  extractPaymentFromHeaders,
+  fromAtomicUnits,
   getAllCustomTokens,
   getAvailableNetworks,
   getAvailableTokens,
+  getCurrentTimestamp,
   getCustomToken,
   getMainnets,
   getNetworkByChainId,
@@ -700,7 +1022,7 @@ export {
   getPaymentHeaderName,
   getPaymentRequiredHeaderName,
   getPaymentResponseHeaderName,
-  getPaymentVersion as getPaymentVersionFromPayload,
+  getPaymentVersion,
   getRequirementsVersion,
   getSettlementVersion,
   getTestnets,
@@ -709,6 +1031,10 @@ export {
   isCAIP2ChainId,
   isCAIPAssetId,
   isCustomToken,
+  isExactEvmPayload,
+  isLegacyV1,
+  isLegacyV2,
+  isPaymentPayload,
   isPaymentV1,
   isPaymentV2,
   isResolvedNetwork,
@@ -718,11 +1044,19 @@ export {
   isSettlementV2,
   isV1,
   isV2,
+  isValidAddress,
   isValidationError,
+  legacyToPaymentPayload,
+  networkToCaip2,
+  normalizeAddress,
+  parseSignature,
   registerToken,
   resolveFacilitator,
   resolveNetwork,
   resolveToken,
+  safeBase64Decode,
+  safeBase64Encode,
+  toAtomicUnits,
   unregisterToken,
   validateAcceptConfig,
   validatePaymentConfig,

package/dist/types/x402.d.ts

@@ -0,0 +1,136 @@
+/**
+ * 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}`;
+export declare const X402_VERSION: 1;
+export type X402Version = typeof X402_VERSION;
+export declare const SCHEMES: readonly ["exact"];
+export type Scheme = (typeof SCHEMES)[number];
+export type Network = "base" | "base-sepolia" | "ethereum" | "ethereum-sepolia" | "polygon" | "polygon-amoy" | "arbitrum" | "arbitrum-sepolia" | "optimism" | "optimism-sepolia" | string;
+/**
+ * EIP-3009 TransferWithAuthorization authorization data
+ */
+export interface ExactEvmAuthorization {
+    from: Address;
+    to: Address;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: Hex;
+}
+/**
+ * Exact EVM payment payload structure
+ */
+export interface ExactEvmPayload {
+    signature: Hex;
+    authorization: ExactEvmAuthorization;
+}
+/**
+ * Payment payload - Coinbase compatible format
+ * This is the unified format that works with both v1 and v2
+ */
+export interface PaymentPayload {
+    x402Version: X402Version;
+    scheme: Scheme;
+    network: Network;
+    payload: ExactEvmPayload;
+}
+/**
+ * Unsigned payment payload (before signing)
+ */
+export interface UnsignedPaymentPayload {
+    x402Version: X402Version;
+    scheme: Scheme;
+    network: Network;
+    payload: Omit<ExactEvmPayload, "signature"> & {
+        signature: undefined;
+    };
+}
+/**
+ * Payment requirements for 402 response
+ */
+export interface PaymentRequirements {
+    scheme: Scheme;
+    network: Network;
+    maxAmountRequired: string;
+    resource: string;
+    description: string;
+    mimeType: string;
+    outputSchema?: Record<string, unknown>;
+    payTo: Address;
+    maxTimeoutSeconds: number;
+    asset: Address;
+    extra?: Record<string, unknown>;
+}
+/**
+ * Settlement response
+ */
+export interface SettlementResponse {
+    success: boolean;
+    errorReason?: string;
+    payer?: Address;
+    transaction: string;
+    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;
+}
+export interface PaymentPayloadV1 {
+    from: string;
+    to: string;
+    amount: string;
+    nonce: string;
+    expiry: number;
+    v: number;
+    r: string;
+    s: string;
+    chainId: number;
+    contractAddress: string;
+    network: string;
+}
+export interface PaymentPayloadV2 {
+    from: Address;
+    to: Address | {
+        role?: string;
+        callback?: string;
+    };
+    amount: string;
+    nonce: string;
+    expiry: number;
+    signature: {
+        v: number;
+        r: string;
+        s: string;
+    };
+    chainId: `eip155:${string}`;
+    assetId: `eip155:${string}/erc20:${string}`;
+    extensions?: Record<string, unknown>;
+}
+export type LegacyPaymentPayload = PaymentPayloadV1 | PaymentPayloadV2;
+/**
+ * Type guards
+ */
+export declare function isPaymentPayload(obj: unknown): obj is PaymentPayload;
+export declare function isExactEvmPayload(obj: unknown): obj is ExactEvmPayload;
+/**
+ * Convert legacy payload to new format
+ */
+export declare function legacyToPaymentPayload(legacy: LegacyPaymentPayload | PaymentPayload): PaymentPayload;

package/dist/utils/x402.d.ts

@@ -0,0 +1,56 @@
+/**
+ * X402 Protocol Utilities - Coinbase Compatible
+ *
+ * Helper functions for nonce generation, amount conversion, and other utilities.
+ */
+import type { Hex, Address } from "../types/x402";
+/**
+ * Generate a random 32-byte nonce as hex string
+ * Matches Coinbase SDK format: "0x" + 64 hex characters
+ */
+export declare function createNonce(): Hex;
+/**
+ * Convert human-readable amount to atomic units
+ * e.g., "1.5" USDC -> "1500000" (6 decimals)
+ */
+export declare function toAtomicUnits(amount: string, decimals?: number): string;
+/**
+ * Convert atomic units to human-readable amount
+ * e.g., "1500000" -> "1.5" USDC (6 decimals)
+ */
+export declare function fromAtomicUnits(amount: string, decimals?: number): string;
+/**
+ * Parse signature from hex string to components
+ * Returns { r, s, v } where v is 27 or 28
+ */
+export declare function parseSignature(signature: Hex): {
+    r: Hex;
+    s: Hex;
+    v: number;
+};
+/**
+ * Combine signature components into hex string
+ */
+export declare function combineSignature(r: Hex, s: Hex, v: number): Hex;
+/**
+ * Convert CAIP-2 chain ID to network name
+ * e.g., "eip155:8453" -> "base"
+ */
+export declare function caip2ToNetwork(caip2Id: string): string;
+/**
+ * Convert network name to CAIP-2 chain ID
+ * e.g., "base" -> "eip155:8453"
+ */
+export declare function networkToCaip2(network: string): string;
+/**
+ * Get current Unix timestamp in seconds
+ */
+export declare function getCurrentTimestamp(): number;
+/**
+ * Validate Ethereum address
+ */
+export declare function isValidAddress(address: string): address is Address;
+/**
+ * Normalize address to checksum format (basic lowercase)
+ */
+export declare function normalizeAddress(address: string): Address;

package/dist/validation.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Comprehensive unit tests for validation layer
+ * Tests all input formats, cross-checks, and error messages
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armory-sh/base",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "MIT",
   "author": "Sawyer Cutler <sawyer@dirtroad.dev>",
   "type": "module",