@armory-sh/base 0.2.28 → 0.2.29

package/dist/payment-client.d.ts

@@ -1,4 +1,4 @@
-import type { PaymentPayload, PaymentRequirements, VerifyResponse, SettlementResponse } from "./types/x402";
+import type { PaymentPayload, PaymentRequirements, SettlementResponse, VerifyResponse } from "./types/x402";
 export interface FacilitatorClientConfig {
     url: string;
     createHeaders?: () => Record<string, string> | Promise<Record<string, string>>;

package/dist/payment-requirements.d.ts

@@ -0,0 +1,29 @@
+import type { NetworkId, TokenId, ValidationError } from "./types/api";
+import type { Address, PaymentRequirementsV2 } from "./types/v2";
+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 declare function createPaymentRequirements(config: PaymentConfig): ResolvedRequirementsConfig;
+export declare function findRequirementByNetwork(requirements: PaymentRequirementsV2[], network: string): PaymentRequirementsV2 | undefined;
+export declare function findRequirementByAccepted(requirements: PaymentRequirementsV2[], accepted: {
+    scheme: string;
+    network: string;
+    amount: string;
+    asset: string;
+    payTo: string;
+}): PaymentRequirementsV2 | undefined;

package/dist/protocol.d.ts

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

package/dist/types/api.d.ts

@@ -2,8 +2,8 @@
  * 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";
-import type { NetworkConfig, CustomToken } from "./networks";
 /**
  * Network identifier - flexible input that resolves to a chain
  * - Network name: "base", "ethereum", "skale-base"

package/dist/types/hooks.d.ts

@@ -7,11 +7,13 @@
  *
  * Hooks allow extensibility without custom code in each client package.
  */
-import type { PaymentPayloadV2, PaymentRequirementsV2, Extensions, Address } from "./v2";
+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}`;
@@ -33,3 +35,17 @@ export interface HookConfig<TWallet = unknown> {
     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/dist/types/protocol.d.ts

@@ -3,7 +3,7 @@
  *
  * Simplified to support only x402 V2 format (Coinbase compatible)
  */
-import type { PaymentPayloadV2, PaymentRequirementsV2, SettlementResponseV2, PaymentRequiredV2, Address } from "./v2";
+import type { Address, PaymentPayloadV2, PaymentRequiredV2, PaymentRequirementsV2, SettlementResponseV2 } from "./v2";
 export type PaymentPayload = PaymentPayloadV2;
 export type PaymentRequirements = PaymentRequirementsV2;
 export type SettlementResponse = SettlementResponseV2;

package/dist/types/wallet.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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/dist/utils/base64.d.ts

@@ -0,0 +1,4 @@
+export declare function encodeUtf8ToBase64(value: string): string;
+export declare function decodeBase64ToUtf8(value: string): string;
+export declare function toBase64Url(base64: string): string;
+export declare function normalizeBase64Url(value: string): string;

package/dist/utils/x402.d.ts

@@ -3,7 +3,7 @@
  *
  * Helper functions for nonce generation, amount conversion, and other utilities.
  */
-import type { Hex, Address } from "../types/x402";
+import type { Address, Hex } from "../types/x402";
 /**
  * Generate a random 32-byte nonce as hex string
  * Matches Coinbase SDK format: "0x" + 64 hex characters

package/dist/validation.d.ts

@@ -2,7 +2,7 @@
  * Comprehensive validation for Armory configurations
  * Ensures networks, tokens, and facilitators are compatible
  */
-import type { NetworkId, TokenId, FacilitatorConfig, ResolvedNetwork, ResolvedToken, ResolvedFacilitator, ResolvedPaymentConfig, ValidationError, PaymentErrorCode } from "./types/api";
+import type { FacilitatorConfig, NetworkId, PaymentErrorCode, ResolvedFacilitator, ResolvedNetwork, ResolvedPaymentConfig, ResolvedToken, TokenId, ValidationError } from "./types/api";
 export declare const createError: (code: PaymentErrorCode, message: string, details?: Partial<ValidationError>) => ValidationError;
 export declare const normalizeNetworkName: (name: string) => string;
 export declare const resolveNetwork: (input: unknown) => ResolvedNetwork | ValidationError;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armory-sh/base",
-  "version": "0.2.28",
+  "version": "0.2.29",
   "license": "MIT",
   "author": "Sawyer Cutler <sawyer@dirtroad.dev>",
   "keywords": [
@@ -28,10 +28,21 @@
       "bun": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./types/hooks": {
+      "types": "./src/types/hooks.ts",
+      "bun": "./src/types/hooks.ts",
+      "default": "./src/types/hooks.ts"
+    },
+    "./client-hooks-runtime": {
+      "types": "./src/client-hooks-runtime.ts",
+      "bun": "./src/client-hooks-runtime.ts",
+      "default": "./src/client-hooks-runtime.ts"
+    },
     "./dist/*": "./dist/*.js"
   },
   "files": [
     "dist",
+    "src",
     "README.md"
   ],
   "publishConfig": {
@@ -50,7 +61,9 @@
   },
   "scripts": {
     "build": "rm -rf dist && tsup && tsc --emitDeclarationOnly",
+    "lint": "bun run build",
+    "format": "bun run lint",
     "test": "bun test",
     "typecheck": "tsc --noEmit"
   }
-}
+}

package/src/abi/erc20.ts

@@ -0,0 +1,84 @@
+export type TransferWithAuthorizationParams = readonly [
+  from: `0x${string}`,
+  to: `0x${string}`,
+  amount: bigint,
+  validAfter: bigint,
+  expiry: bigint,
+  v: number,
+  r: `0x${string}`,
+  s: `0x${string}`,
+];
+
+export type ReceiveWithAuthorizationParams = readonly [
+  from: `0x${string}`,
+  to: `0x${string}`,
+  amount: bigint,
+  validAfter: bigint,
+  expiry: bigint,
+  v: number,
+  r: `0x${string}`,
+  s: `0x${string}`,
+];
+
+export type BalanceOfParams = readonly [account: `0x${string}`];
+export type BalanceOfReturnType = bigint;
+export type NameReturnType = string;
+export type SymbolReturnType = string;
+
+export const ERC20_ABI = [
+  {
+    type: "function",
+    name: "transferWithAuthorization",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "from", type: "address" },
+      { name: "to", type: "address" },
+      { name: "amount", type: "uint256" },
+      { name: "validAfter", type: "uint256" },
+      { name: "expiry", type: "uint256" },
+      { name: "v", type: "uint8" },
+      { name: "r", type: "bytes32" },
+      { name: "s", type: "bytes32" },
+    ],
+    outputs: [],
+  },
+  {
+    type: "function",
+    name: "receiveWithAuthorization",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "from", type: "address" },
+      { name: "to", type: "address" },
+      { name: "amount", type: "uint256" },
+      { name: "validAfter", type: "uint256" },
+      { name: "expiry", type: "uint256" },
+      { name: "v", type: "uint8" },
+      { name: "r", type: "bytes32" },
+      { name: "s", type: "bytes32" },
+    ],
+    outputs: [],
+  },
+  {
+    type: "function",
+    name: "balanceOf",
+    stateMutability: "view",
+    inputs: [{ name: "account", type: "address" }],
+    outputs: [{ name: "balance", type: "uint256" }],
+  },
+  {
+    type: "function",
+    name: "name",
+    stateMutability: "view",
+    inputs: [],
+    outputs: [{ name: "", type: "string" }],
+  },
+  {
+    type: "function",
+    name: "symbol",
+    stateMutability: "view",
+    inputs: [],
+    outputs: [{ name: "", type: "string" }],
+  },
+] as const;
+
+export type ERC20Abi = typeof ERC20_ABI;

package/src/client-hooks-runtime.ts

@@ -0,0 +1,153 @@
+import type {
+  ClientHook,
+  ClientHookErrorContext,
+  PaymentPayloadContext,
+  PaymentRequiredContext,
+} from "./types/hooks";
+import type { PaymentRequirementsV2 } from "./types/v2";
+
+const notifyError = async <TWallet>(
+  hooks: ClientHook<TWallet>[] | undefined,
+  context: ClientHookErrorContext,
+): Promise<void> => {
+  if (!hooks?.length) {
+    return;
+  }
+
+  for (const hook of hooks) {
+    if (!hook.onError) {
+      continue;
+    }
+    await hook.onError(context);
+  }
+};
+
+export const runOnPaymentRequiredHooks = async <TWallet>(
+  hooks: ClientHook<TWallet>[] | undefined,
+  context: PaymentRequiredContext,
+): Promise<void> => {
+  if (!hooks?.length) {
+    return;
+  }
+
+  for (const hook of hooks) {
+    if (!hook.onPaymentRequired) {
+      continue;
+    }
+    try {
+      await hook.onPaymentRequired(context);
+    } catch (error) {
+      await notifyError(hooks, { error, phase: "onPaymentRequired" });
+      throw error;
+    }
+  }
+};
+
+export const selectRequirementWithHooks = async <TWallet>(
+  hooks: ClientHook<TWallet>[] | undefined,
+  context: PaymentRequiredContext,
+): Promise<PaymentRequirementsV2> => {
+  if (!context.accepts.length) {
+    throw new Error("No payment requirements found in accepts array");
+  }
+
+  let selected = context.accepts[0];
+
+  if (!hooks?.length) {
+    context.selectedRequirement = selected;
+    context.requirements = selected;
+    return selected;
+  }
+
+  for (const hook of hooks) {
+    if (!hook.selectRequirement) {
+      continue;
+    }
+    try {
+      const override = await hook.selectRequirement({
+        ...context,
+        selectedRequirement: selected,
+        requirements: selected,
+      });
+      if (!override) {
+        continue;
+      }
+      const isValid = context.accepts.some((accept) => accept === override);
+      if (!isValid) {
+        throw new Error(
+          "Hook selectRequirement must return an item from accepts",
+        );
+      }
+      selected = override;
+    } catch (error) {
+      await notifyError(hooks, { error, phase: "selectRequirement" });
+      throw error;
+    }
+  }
+
+  context.selectedRequirement = selected;
+  context.requirements = selected;
+  return selected;
+};
+
+export const getRequirementAttemptOrderWithHooks = async <TWallet>(
+  hooks: ClientHook<TWallet>[] | undefined,
+  context: PaymentRequiredContext,
+): Promise<PaymentRequirementsV2[]> => {
+  if (!context.accepts.length) {
+    throw new Error("No payment requirements found in accepts array");
+  }
+
+  const hasSelectorHook = Boolean(hooks?.some((hook) => hook.selectRequirement));
+  if (!hasSelectorHook) {
+    const first = context.accepts[0];
+    context.selectedRequirement = first;
+    context.requirements = first;
+    return context.accepts;
+  }
+
+  const selected = await selectRequirementWithHooks(hooks, context);
+  return [selected];
+};
+
+export const runBeforeSignPaymentHooks = async <TWallet>(
+  hooks: ClientHook<TWallet>[] | undefined,
+  context: PaymentPayloadContext<TWallet>,
+): Promise<void> => {
+  if (!hooks?.length) {
+    return;
+  }
+
+  for (const hook of hooks) {
+    if (!hook.beforeSignPayment) {
+      continue;
+    }
+    try {
+      await hook.beforeSignPayment(context);
+    } catch (error) {
+      await notifyError(hooks, { error, phase: "beforeSignPayment" });
+      throw error;
+    }
+  }
+};
+
+export const runAfterPaymentResponseHooks = async <TWallet>(
+  hooks: ClientHook<TWallet>[] | undefined,
+  context: PaymentPayloadContext<TWallet> & { response: Response },
+): Promise<void> => {
+  if (!hooks?.length) {
+    return;
+  }
+
+  for (const hook of hooks) {
+    if (!hook.afterPaymentResponse) {
+      continue;
+    }
+    try {
+      await hook.afterPaymentResponse(context);
+    } catch (error) {
+      await notifyError(hooks, { error, phase: "afterPaymentResponse" });
+      throw error;
+    }
+  }
+};

package/src/data/tokens.ts

@@ -0,0 +1,199 @@
+import type { CustomToken } from "../types/networks";
+
+export const USDC_BASE: CustomToken = {
+  symbol: "USDC",
+  name: "USDC",
+  version: "2",
+  contractAddress:
+    "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" as `0x${string}`,
+  chainId: 8453,
+  decimals: 6,
+};
+
+export const EURC_BASE: CustomToken = {
+  symbol: "EURC",
+  name: "EURC",
+  version: "2",
+  contractAddress:
+    "0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42" as `0x${string}`,
+  chainId: 8453,
+  decimals: 6,
+};
+
+export const USDC_BASE_SEPOLIA: CustomToken = {
+  symbol: "USDC",
+  name: "USDC",
+  version: "2",
+  contractAddress:
+    "0x036CbD53842c5426634e7929541eC2318f3dCF7e" as `0x${string}`,
+  chainId: 84532,
+  decimals: 6,
+};
+
+export const USDC_SKALE_BASE: CustomToken = {
+  symbol: "USDC",
+  name: "Bridged USDC (SKALE Bridge)",
+  version: "2",
+  contractAddress:
+    "0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20" as `0x${string}`,
+  chainId: 1187947933,
+  decimals: 6,
+};
+
+export const SKL_SKALE_BASE: CustomToken = {
+  symbol: "SKL",
+  name: "SKALE",
+  version: "1",
+  contractAddress:
+    "0xE0595a049d02b7674572b0d59cd4880Db60EDC50" as `0x${string}`,
+  chainId: 1187947933,
+  decimals: 18,
+};
+
+export const USDT_SKALE_BASE: CustomToken = {
+  symbol: "USDT",
+  name: "Tether USD",
+  version: "1",
+  contractAddress:
+    "0x2bF5bF154b515EaA82C31a65ec11554fF5aF7fCA" as `0x${string}`,
+  chainId: 1187947933,
+  decimals: 6,
+};
+
+export const WBTC_SKALE_BASE: CustomToken = {
+  symbol: "WBTC",
+  name: "Wrapped BTC",
+  version: "1",
+  contractAddress:
+    "0x1aeeCFE5454c83B42D8A316246CAc9739E7f690e" as `0x${string}`,
+  chainId: 1187947933,
+  decimals: 8,
+};
+
+export const WETH_SKALE_BASE: CustomToken = {
+  symbol: "WETH",
+  name: "Wrapped Ether",
+  version: "1",
+  contractAddress:
+    "0x7bD39ABBd0Dd13103542cAe3276C7fA332bCA486" as `0x${string}`,
+  chainId: 1187947933,
+  decimals: 18,
+};
+
+export const SKL_SKALE_BASE_SEPOLIA: CustomToken = {
+  symbol: "SKL",
+  name: "SKALE",
+  version: "1",
+  contractAddress:
+    "0xaf2e0ff5b5f51553fdb34ce7f04a6c3201cee57b" as `0x${string}`,
+  chainId: 324705682,
+  decimals: 18,
+};
+
+export const USDC_SKALE_BASE_SEPOLIA: CustomToken = {
+  symbol: "USDC",
+  name: "Bridged USDC (SKALE Bridge)",
+  version: "2",
+  contractAddress:
+    "0x2e08028E3C4c2356572E096d8EF835cD5C6030bD" as `0x${string}`,
+  chainId: 324705682,
+  decimals: 6,
+};
+
+export const USDT_SKALE_BASE_SEPOLIA: CustomToken = {
+  symbol: "USDT",
+  name: "Tether USD",
+  version: "1",
+  contractAddress:
+    "0x3ca0a49f511c2c89c4dcbbf1731120d8919050bf" as `0x${string}`,
+  chainId: 324705682,
+  decimals: 6,
+};
+
+export const WBTC_SKALE_BASE_SEPOLIA: CustomToken = {
+  symbol: "WBTC",
+  name: "Wrapped BTC",
+  version: "1",
+  contractAddress:
+    "0x4512eacd4186b025186e1cf6cc0d89497c530e87" as `0x${string}`,
+  chainId: 324705682,
+  decimals: 8,
+};
+
+export const WETH_SKALE_BASE_SEPOLIA: CustomToken = {
+  symbol: "WETH",
+  name: "Wrapped Ether",
+  version: "1",
+  contractAddress:
+    "0xf94056bd7f6965db3757e1b145f200b7346b4fc0" as `0x${string}`,
+  chainId: 324705682,
+  decimals: 18,
+};
+
+export const TOKENS = {
+  USDC_BASE,
+  USDC_BASE_SEPOLIA,
+  EURC_BASE,
+  USDC_SKALE_BASE,
+  USDT_SKALE_BASE,
+  WBTC_SKALE_BASE,
+  WETH_SKALE_BASE,
+  SKL_SKALE_BASE,
+  SKL_SKALE_BASE_SEPOLIA,
+  USDC_SKALE_BASE_SEPOLIA,
+  USDT_SKALE_BASE_SEPOLIA,
+  WBTC_SKALE_BASE_SEPOLIA,
+  WETH_SKALE_BASE_SEPOLIA,
+} as const;
+
+function getToken(
+  chainId: number,
+  contractAddress: string,
+): CustomToken | undefined {
+  const tokens = Object.values(TOKENS);
+  return tokens.find(
+    (t) =>
+      t.chainId === chainId &&
+      t.contractAddress.toLowerCase() === contractAddress.toLowerCase(),
+  );
+}
+
+function getAllTokens(): CustomToken[] {
+  return Object.values(TOKENS);
+}
+
+function getTokensBySymbol(symbol: string): CustomToken[] {
+  return getAllTokens().filter(
+    (t) => t.symbol.toUpperCase() === symbol.toUpperCase(),
+  );
+}
+
+function getTokensByChain(chainId: number): CustomToken[] {
+  return getAllTokens().filter((t) => t.chainId === chainId);
+}
+
+export function getUSDCTokens(): CustomToken[] {
+  return getTokensBySymbol("USDC");
+}
+
+export function getEURCTokens(): CustomToken[] {
+  return getTokensBySymbol("EURC");
+}
+
+export function getSKLTokens(): CustomToken[] {
+  return getTokensBySymbol("SKL");
+}
+
+export function getUSDTTokens(): CustomToken[] {
+  return getTokensBySymbol("USDT");
+}
+
+export function getWBTCTokens(): CustomToken[] {
+  return getTokensBySymbol("WBTC");
+}
+
+export function getWETHTokens(): CustomToken[] {
+  return getTokensBySymbol("WETH");
+}
+
+export { getToken, getAllTokens, getTokensBySymbol, getTokensByChain };