@armory-sh/base 0.2.28 → 0.2.29

package/src/types/hooks.ts

@@ -0,0 +1,85 @@
+/**
+ * Extension Hook System Types
+ *
+ * Provides a generic hook system for x402 clients to register
+ * extension handlers that can modify payment payloads or respond
+ * to payment requirements.
+ *
+ * Hooks allow extensibility without custom code in each client package.
+ */
+
+import type {
+  Address,
+  Extensions,
+  PaymentPayloadV2,
+  PaymentRequirementsV2,
+} from "./v2";
+
+export interface PaymentRequiredContext {
+  url: RequestInfo | URL;
+  requestInit: RequestInit | undefined;
+  accepts: PaymentRequirementsV2[];
+  requirements: PaymentRequirementsV2;
+  selectedRequirement?: PaymentRequirementsV2;
+  serverExtensions: Extensions | undefined;
+  fromAddress: Address;
+  nonce: `0x${string}`;
+  validBefore: number;
+}
+
+export interface PaymentPayloadContext<TWallet = unknown> {
+  payload: PaymentPayloadV2;
+  requirements: PaymentRequirementsV2;
+  wallet: TWallet;
+  paymentContext: PaymentRequiredContext;
+}
+
+export type HookResult = void | Promise<void>;
+
+export type OnPaymentRequiredHook<TWallet = unknown> = (
+  context: PaymentRequiredContext,
+) => HookResult;
+
+export type BeforePaymentHook<TWallet = unknown> = (
+  context: PaymentPayloadContext<TWallet>,
+) => HookResult;
+
+export type ExtensionHook<TWallet = unknown> =
+  | OnPaymentRequiredHook<TWallet>
+  | BeforePaymentHook<TWallet>;
+
+export interface HookConfig<TWallet = unknown> {
+  hook: ExtensionHook<TWallet>;
+  priority?: number;
+  name?: string;
+}
+
+export type HookRegistry<TWallet = unknown> = Record<
+  string,
+  HookConfig<TWallet>
+>;
+
+export interface ClientHookErrorContext {
+  error: unknown;
+  phase:
+    | "onPaymentRequired"
+    | "selectRequirement"
+    | "beforeSignPayment"
+    | "afterPaymentResponse";
+}
+
+export interface ClientHook<TWallet = unknown> {
+  name?: string;
+  onPaymentRequired?: (context: PaymentRequiredContext) => HookResult;
+  selectRequirement?: (
+    context: PaymentRequiredContext,
+  ) =>
+    | PaymentRequirementsV2
+    | undefined
+    | Promise<PaymentRequirementsV2 | undefined>;
+  beforeSignPayment?: (context: PaymentPayloadContext<TWallet>) => HookResult;
+  afterPaymentResponse?: (
+    context: PaymentPayloadContext<TWallet> & { response: Response },
+  ) => HookResult;
+  onError?: (context: ClientHookErrorContext) => HookResult;
+}

package/src/types/networks.ts

@@ -0,0 +1,175 @@
+const isEvmAddress = (value: string): boolean =>
+  /^0x[a-fA-F0-9]{40}$/.test(value);
+
+export interface NetworkConfig {
+  name: string;
+  chainId: number;
+  usdcAddress: `0x${string}`;
+  rpcUrl: string;
+  caip2Id: string;
+  caipAssetId: string;
+}
+
+export interface CustomToken {
+  symbol: string;
+  name: string;
+  version: string;
+  contractAddress: `0x${string}`;
+  chainId: number;
+  decimals?: number;
+}
+
+const tokenRegistry = new Map<string, CustomToken>();
+const tokenKey = (chainId: number, contractAddress: string): string =>
+  `${chainId}:${contractAddress.toLowerCase()}`;
+
+export const NETWORKS: Record<string, NetworkConfig> = {
+  ethereum: {
+    name: "Ethereum Mainnet",
+    chainId: 1,
+    usdcAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" as const,
+    rpcUrl: "https://eth.llamarpc.com",
+    caip2Id: "eip155:1",
+    caipAssetId: "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  },
+  base: {
+    name: "Base Mainnet",
+    chainId: 8453,
+    usdcAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" as const,
+    rpcUrl: "https://mainnet.base.org",
+    caip2Id: "eip155:8453",
+    caipAssetId: "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  },
+  "base-sepolia": {
+    name: "Base Sepolia",
+    chainId: 84532,
+    usdcAddress: "0x036CbD53842c5426634e7929541eC2318f3dCF7e" as const,
+    rpcUrl: "https://sepolia.base.org",
+    caip2Id: "eip155:84532",
+    caipAssetId:
+      "eip155:84532/erc20:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+  },
+  "skale-base": {
+    name: "SKALE Base",
+    chainId: 1187947933,
+    usdcAddress: "0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20" as const,
+    rpcUrl: "https://skale-base.skalenodes.com/v1/base",
+    caip2Id: "eip155:1187947933",
+    caipAssetId:
+      "eip155:1187947933/erc20:0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20",
+  },
+  "skale-base-sepolia": {
+    name: "SKALE Base Sepolia",
+    chainId: 324705682,
+    usdcAddress: "0x2e08028E3C4c2356572E096d8EF835cD5C6030bD" as const,
+    rpcUrl:
+      "https://base-sepolia-testnet.skalenodes.com/v1/jubilant-horrible-ancha",
+    caip2Id: "eip155:324705682",
+    caipAssetId:
+      "eip155:324705682/erc20:0x2e08028E3C4c2356572E096d8EF835cD5C6030bD",
+  },
+  "ethereum-sepolia": {
+    name: "Ethereum Sepolia",
+    chainId: 11155111,
+    usdcAddress: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238" as const,
+    rpcUrl: "https://rpc.sepolia.org",
+    caip2Id: "eip155:11155111",
+    caipAssetId:
+      "eip155:11155111/erc20:0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
+  },
+};
+
+export const getNetworkConfig = (name: string): NetworkConfig | undefined =>
+  NETWORKS[name];
+export const getNetworkByChainId = (
+  chainId: number,
+): NetworkConfig | undefined =>
+  Object.values(NETWORKS).find((c) => c.chainId === chainId);
+export const getMainnets = (): NetworkConfig[] =>
+  Object.values(NETWORKS).filter(
+    (c) => !c.name.toLowerCase().includes("sepolia"),
+  );
+export const getTestnets = (): NetworkConfig[] =>
+  Object.values(NETWORKS).filter((c) =>
+    c.name.toLowerCase().includes("sepolia"),
+  );
+
+export const registerToken = (token: unknown): CustomToken => {
+  if (typeof token !== "object" || token === null) {
+    throw new Error("Invalid token: must be an object");
+  }
+
+  const t = token as Record<string, unknown>;
+
+  if (typeof t.symbol !== "string") {
+    throw new Error("Invalid token: symbol must be a string");
+  }
+
+  if (typeof t.name !== "string") {
+    throw new Error("Invalid token: name must be a string");
+  }
+
+  if (typeof t.version !== "string") {
+    throw new Error("Invalid token: version must be a string");
+  }
+
+  if (
+    typeof t.contractAddress !== "string" ||
+    !isEvmAddress(t.contractAddress)
+  ) {
+    throw new Error(
+      "Invalid token: contractAddress must be a valid EVM address",
+    );
+  }
+
+  if (
+    typeof t.chainId !== "number" ||
+    !Number.isInteger(t.chainId) ||
+    t.chainId <= 0
+  ) {
+    throw new Error("Invalid token: chainId must be a positive integer");
+  }
+
+  if (
+    t.decimals !== undefined &&
+    (typeof t.decimals !== "number" ||
+      !Number.isInteger(t.decimals) ||
+      t.decimals < 0)
+  ) {
+    throw new Error("Invalid token: decimals must be a non-negative integer");
+  }
+
+  const validated: CustomToken = {
+    symbol: t.symbol,
+    name: t.name,
+    version: t.version,
+    contractAddress: t.contractAddress as `0x${string}`,
+    chainId: t.chainId,
+    decimals: t.decimals,
+  };
+
+  tokenRegistry.set(
+    tokenKey(validated.chainId, validated.contractAddress),
+    validated,
+  );
+  return validated;
+};
+
+export const getCustomToken = (
+  chainId: number,
+  contractAddress: string,
+): CustomToken | undefined =>
+  tokenRegistry.get(tokenKey(chainId, contractAddress));
+
+export const getAllCustomTokens = (): CustomToken[] =>
+  Array.from(tokenRegistry.values());
+
+export const unregisterToken = (
+  chainId: number,
+  contractAddress: string,
+): boolean => tokenRegistry.delete(tokenKey(chainId, contractAddress));
+
+export const isCustomToken = (
+  chainId: number,
+  contractAddress: string,
+): boolean => tokenRegistry.has(tokenKey(chainId, contractAddress));

package/src/types/protocol.ts

@@ -0,0 +1,182 @@
+/**
+ * Protocol Types - x402 V2 Only
+ *
+ * Simplified to support only x402 V2 format (Coinbase compatible)
+ */
+
+import type {
+  Address,
+  PaymentPayloadV2,
+  PaymentRequiredV2,
+  PaymentRequirementsV2,
+  SettlementResponseV2,
+} from "./v2";
+
+// ============================================================================
+// Type Aliases for V2 Only
+// ============================================================================
+
+export type PaymentPayload = PaymentPayloadV2;
+export type PaymentRequirements = PaymentRequirementsV2;
+export type SettlementResponse = SettlementResponseV2;
+export type PaymentRequired = PaymentRequiredV2;
+
+// ============================================================================
+// Facilitator Communication Types (shared across middleware packages)
+// ============================================================================
+
+/**
+ * Configuration for connecting to a facilitator service
+ */
+export interface FacilitatorConfig {
+  url: string;
+  createHeaders?: () => Record<string, string>;
+}
+
+/**
+ * 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";
+
+/**
+ * Payment destination - address, CAIP-2 chain ID, or CAIP asset ID
+ */
+export type PayToAddress = Address | CAIP2ChainId | CAIPAssetId;
+
+/**
+ * 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 CAIPAssetId = `eip155:${string}/erc20:${string}`;
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+/**
+ * Check if payload is x402 V2 format (Coinbase format)
+ */
+export function isX402V2Payload(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
+  );
+}
+
+/**
+ * Check if requirements is x402 V2 format
+ */
+export function isX402V2Requirements(
+  obj: unknown,
+): obj is PaymentRequirementsV2 {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    "scheme" in obj &&
+    (obj as PaymentRequirementsV2).scheme === "exact" &&
+    "network" in obj &&
+    typeof (obj as PaymentRequirementsV2).network === "string" &&
+    (obj as PaymentRequirementsV2).network.startsWith("eip155:") && // CAIP-2 format
+    "amount" in obj &&
+    "asset" in obj &&
+    "payTo" in obj &&
+    "maxTimeoutSeconds" in obj
+  );
+}
+
+/**
+ * Check if settlement response is x402 V2 format
+ */
+export function isX402V2Settlement(obj: unknown): obj is SettlementResponseV2 {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    "success" in obj &&
+    typeof (obj as SettlementResponseV2).success === "boolean" &&
+    "network" in obj &&
+    typeof (obj as SettlementResponseV2).network === "string" &&
+    (obj as SettlementResponseV2).network.startsWith("eip155:") // CAIP-2 format
+  );
+}
+
+/**
+ * Check if payment required is x402 V2 format
+ */
+export function isX402V2PaymentRequired(
+  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
+  );
+}
+
+// ============================================================================
+// Header Names (V2 Hardcoded)
+// ============================================================================
+
+/**
+ * x402 V2 payment header name
+ */
+export const PAYMENT_SIGNATURE_HEADER = "PAYMENT-SIGNATURE" as const;
+
+/**
+ * x402 V2 payment response header name
+ */
+export const PAYMENT_RESPONSE_HEADER = "PAYMENT-RESPONSE" as const;
+
+/**
+ * x402 V2 payment required header name
+ */
+export const PAYMENT_REQUIRED_HEADER = "PAYMENT-REQUIRED" as const;
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Check if settlement was successful
+ */
+export function isSettlementSuccessful(response: SettlementResponse): boolean {
+  return "success" in response ? response.success : false;
+}
+
+/**
+ * Get transaction hash from settlement response (V2 only)
+ */
+export function getTxHash(response: SettlementResponse): string | undefined {
+  if ("transaction" in response) return response.transaction;
+  return undefined;
+}