@t402/evm-core 2.3.0

package/README.md

@@ -0,0 +1,128 @@
+# @t402/evm-core
+
+T402 EVM Core Types and Utilities - Zero external dependencies.
+
+## Overview
+
+This package provides EVM types, constants, and utilities for the T402 payment protocol without requiring viem as a dependency. Use this package when you want to work with T402 EVM types without bundling the full viem library.
+
+For full EVM functionality with viem integration, use `@t402/evm` instead.
+
+## Installation
+
+```bash
+npm install @t402/evm-core
+# or
+pnpm add @t402/evm-core
+```
+
+## Usage
+
+```typescript
+import {
+  // Primitive types
+  type Address,
+  type Hex,
+  bytesToHex,
+  hexToBytes,
+
+  // Payment types
+  type ExactEIP3009Payload,
+  type UptoEIP2612Payload,
+
+  // Constants
+  authorizationTypes,
+  eip3009ABI,
+
+  // Signer interfaces
+  type ClientEvmSigner,
+  type FacilitatorEvmSigner,
+
+  // Token registry
+  TOKEN_REGISTRY,
+  getTokenConfig,
+  getNetworkTokens,
+
+  // Utilities
+  createNonce,
+  getEvmChainId,
+} from "@t402/evm-core";
+
+// Use types without viem
+const payload: ExactEIP3009Payload = {
+  authorization: {
+    from: "0x...",
+    to: "0x...",
+    value: "1000000",
+    validAfter: "0",
+    validBefore: "1893456000",
+    nonce: createNonce(),
+  },
+};
+```
+
+## When to Use This Package
+
+Use `@t402/evm-core` when:
+
+- You only need types and don't need viem functionality
+- You're building a type-only package that depends on T402 types
+- You want to reduce bundle size by avoiding viem
+- You're using a different EVM library (ethers.js, web3.js, etc.)
+
+Use `@t402/evm` when:
+
+- You need full EVM signing and verification
+- You're using viem in your project
+- You need the client or facilitator scheme implementations
+
+## Exports
+
+### Primitive Types
+
+- `Address` - Ethereum address type (`` `0x${string}` ``)
+- `Hex` - Hexadecimal string type
+- `Bytes32` - 32-byte hex value
+- `bytesToHex()` - Convert Uint8Array to hex
+- `hexToBytes()` - Convert hex to Uint8Array
+
+### Payment Types
+
+- `ExactEIP3009Payload` - EIP-3009 TransferWithAuthorization payload
+- `ExactLegacyPayload` - Legacy approve+transferFrom payload
+- `UptoEIP2612Payload` - EIP-2612 Permit payload for metered payments
+- `PermitSignature` - EIP-2612 signature components
+- `PermitAuthorization` - EIP-2612 permit parameters
+
+### Constants
+
+- `authorizationTypes` - EIP-712 type definitions for EIP-3009
+- `legacyAuthorizationTypes` - EIP-712 type definitions for legacy flow
+- `eip3009ABI` - ABI for EIP-3009 token contracts
+- `erc20LegacyABI` - ABI for standard ERC-20 operations
+
+### Signer Interfaces
+
+- `ClientEvmSigner` - Interface for client-side signing
+- `FacilitatorEvmSigner` - Interface for facilitator operations
+- `toClientEvmSigner()` - Convert to ClientEvmSigner
+- `toFacilitatorEvmSigner()` - Convert to FacilitatorEvmSigner
+
+### Token Registry
+
+- `TOKEN_REGISTRY` - Complete token configuration by network
+- `USDT0_ADDRESSES` - USDT0 contract addresses
+- `USDC_ADDRESSES` - USDC contract addresses
+- `getTokenConfig()` - Get token config by network/symbol
+- `getNetworkTokens()` - Get all tokens for a network
+- `getTokenByAddress()` - Find token by contract address
+- `getEIP712Domain()` - Get EIP-712 domain for token
+
+### Utilities
+
+- `createNonce()` - Generate random 32-byte nonce
+- `getEvmChainId()` - Get chain ID from network name
+
+## License
+
+Apache-2.0

package/dist/cjs/index.d.ts

@@ -0,0 +1,595 @@
+import { Network } from '@t402/core/types';
+
+/**
+ * EVM Primitive Types
+ *
+ * These type aliases are compatible with viem's types but don't require viem as a dependency.
+ * When used with viem, these types are structurally identical and fully interoperable.
+ */
+/**
+ * Ethereum address (20 bytes, checksummed or lowercase)
+ * Compatible with viem's Address type
+ */
+type Address = `0x${string}`;
+/**
+ * Hexadecimal string
+ * Compatible with viem's Hex type
+ */
+type Hex = `0x${string}`;
+/**
+ * Bytes32 value (32 bytes as hex)
+ */
+type Bytes32 = `0x${string}`;
+/**
+ * Convert a Uint8Array to a hex string
+ * Standalone implementation - no viem dependency
+ */
+declare function bytesToHex(bytes: Uint8Array): Hex;
+/**
+ * Convert a hex string to Uint8Array
+ * Standalone implementation - no viem dependency
+ */
+declare function hexToBytes(hex: Hex): Uint8Array;
+
+/**
+ * EVM Payment Types
+ *
+ * Type definitions for T402 EVM payment schemes.
+ * These types have no external dependencies and can be used independently.
+ */
+
+/**
+ * EIP-3009 TransferWithAuthorization payload
+ */
+type ExactEIP3009Payload = {
+    signature?: Hex;
+    authorization: {
+        from: Address;
+        to: Address;
+        value: string;
+        validAfter: string;
+        validBefore: string;
+        nonce: Hex;
+    };
+};
+type ExactEvmPayloadV1 = ExactEIP3009Payload;
+type ExactEvmPayloadV2 = ExactEIP3009Payload;
+/**
+ * Payload for exact-legacy scheme (approve + transferFrom pattern)
+ * Used for legacy USDT and other tokens without EIP-3009 support
+ */
+type ExactLegacyPayload = {
+    signature?: Hex;
+    authorization: {
+        /** Payer address */
+        from: Address;
+        /** Recipient address */
+        to: Address;
+        /** Payment amount in token units */
+        value: string;
+        /** Unix timestamp after which the authorization is valid */
+        validAfter: string;
+        /** Unix timestamp before which the authorization is valid */
+        validBefore: string;
+        /** Unique nonce to prevent replay attacks */
+        nonce: Hex;
+        /** Facilitator address that will call transferFrom */
+        spender: Address;
+    };
+};
+/**
+ * EIP-2612 Permit signature components
+ */
+type PermitSignature = {
+    v: number;
+    r: Hex;
+    s: Hex;
+};
+/**
+ * EIP-2612 Permit authorization parameters
+ */
+type PermitAuthorization = {
+    /** Token owner address */
+    owner: Address;
+    /** Spender address (router contract or facilitator) */
+    spender: Address;
+    /** Maximum authorized value */
+    value: string;
+    /** Permit deadline (unix timestamp) */
+    deadline: string;
+    /** Permit nonce from token contract */
+    nonce: number;
+};
+/**
+ * Payload for upto scheme using EIP-2612 Permit
+ */
+type UptoEIP2612Payload = {
+    /** EIP-2612 permit signature */
+    signature: PermitSignature;
+    /** Permit authorization parameters */
+    authorization: PermitAuthorization;
+    /** Unique payment nonce (separate from permit nonce) */
+    paymentNonce: Hex;
+};
+/**
+ * Compact payload with combined signature bytes
+ */
+type UptoEIP2612PayloadCompact = {
+    /** Combined permit signature (65 bytes) */
+    signature: Hex;
+    /** Permit authorization parameters */
+    authorization: PermitAuthorization;
+    /** Unique payment nonce */
+    paymentNonce: Hex;
+};
+type UptoEvmPayloadV2 = UptoEIP2612Payload | UptoEIP2612PayloadCompact;
+/**
+ * Extra fields for upto scheme requirements on EVM
+ */
+type UptoEvmExtra = {
+    /** EIP-712 domain name (from token contract) */
+    name: string;
+    /** EIP-712 domain version */
+    version: string;
+    /** Router contract address for settlement */
+    routerAddress?: Address;
+    /** Billing unit */
+    unit?: string;
+    /** Price per unit */
+    unitPrice?: string;
+};
+/**
+ * Settlement data for upto scheme
+ */
+type UptoEvmSettlement = {
+    /** Actual amount to settle (must be <= maxAmount) */
+    settleAmount: string;
+    /** Usage details for auditing */
+    usageDetails?: {
+        unitsConsumed?: number;
+        unitPrice?: string;
+        unitType?: string;
+        startTime?: number;
+        endTime?: number;
+    };
+};
+/**
+ * EIP-712 typed data for EIP-2612 Permit
+ */
+declare const permitTypes: {
+    readonly Permit: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }];
+};
+/**
+ * Type guard for UptoEIP2612Payload
+ */
+declare function isUptoEIP2612Payload(payload: unknown): payload is UptoEIP2612Payload;
+
+/**
+ * EVM Constants
+ *
+ * EIP-712 type definitions and ABI constants for T402 EVM payments.
+ * No external dependencies.
+ */
+declare const authorizationTypes: {
+    readonly TransferWithAuthorization: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+};
+declare const legacyAuthorizationTypes: {
+    readonly LegacyTransferAuthorization: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }];
+};
+declare const eip3009ABI: readonly [{
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "v";
+        readonly type: "uint8";
+    }, {
+        readonly name: "r";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "s";
+        readonly type: "bytes32";
+    }];
+    readonly name: "transferWithAuthorization";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "signature";
+        readonly type: "bytes";
+    }];
+    readonly name: "transferWithAuthorization";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly name: "balanceOf";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "version";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}];
+declare const erc20LegacyABI: readonly [{
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly name: "balanceOf";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }];
+    readonly name: "allowance";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly name: "approve";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly name: "transferFrom";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}];
+
+/**
+ * EVM Signer Types
+ *
+ * Type definitions for T402 EVM signers (clients and facilitators).
+ * These interfaces are compatible with viem but don't require it.
+ */
+
+/**
+ * ClientEvmSigner - Used by T402 clients to sign payment authorizations
+ *
+ * This is typically a LocalAccount or wallet that holds private keys
+ * and can sign EIP-712 typed data for payment authorizations.
+ * Compatible with viem's LocalAccount interface.
+ */
+type ClientEvmSigner = {
+    readonly address: Address;
+    signTypedData(message: {
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<Hex>;
+};
+/**
+ * FacilitatorEvmSigner - Used by T402 facilitators to verify and settle payments
+ *
+ * This is typically a viem PublicClient + WalletClient combination that can
+ * read contract state, verify signatures, write transactions, and wait for receipts.
+ * Compatible with viem's client interface.
+ *
+ * Supports multiple addresses for load balancing, key rotation, and high availability.
+ */
+type FacilitatorEvmSigner = {
+    /**
+     * Get all addresses this facilitator can use for signing
+     * Enables dynamic address selection for load balancing and key rotation
+     */
+    getAddresses(): readonly Address[];
+    readContract(args: {
+        address: Address;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+    }): Promise<unknown>;
+    verifyTypedData(args: {
+        address: Address;
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+        signature: Hex;
+    }): Promise<boolean>;
+    writeContract(args: {
+        address: Address;
+        abi: readonly unknown[];
+        functionName: string;
+        args: readonly unknown[];
+    }): Promise<Hex>;
+    sendTransaction(args: {
+        to: Address;
+        data: Hex;
+    }): Promise<Hex>;
+    waitForTransactionReceipt(args: {
+        hash: Hex;
+    }): Promise<{
+        status: string;
+    }>;
+    getCode(args: {
+        address: Address;
+    }): Promise<Hex | undefined>;
+};
+/**
+ * Converts a signer to a ClientEvmSigner
+ *
+ * @param signer - The signer to convert to a ClientEvmSigner
+ * @returns The converted signer
+ */
+declare function toClientEvmSigner(signer: ClientEvmSigner): ClientEvmSigner;
+/**
+ * Converts a viem client with single address to a FacilitatorEvmSigner
+ * Wraps the single address in a getAddresses() function for compatibility
+ *
+ * @param client - The client to convert (must have 'address' property)
+ * @returns FacilitatorEvmSigner with getAddresses() support
+ */
+declare function toFacilitatorEvmSigner(client: Omit<FacilitatorEvmSigner, "getAddresses"> & {
+    address: Address;
+}): FacilitatorEvmSigner;
+
+/**
+ * Token Configuration for T402 EVM Payments
+ *
+ * This module provides comprehensive token definitions including:
+ * - USDT0 (Tether's new omnichain token with EIP-3009 support)
+ * - USDC (USD Coin with EIP-3009 support)
+ * - Legacy tokens configuration
+ *
+ * No external dependencies - uses local Address type.
+ */
+
+/**
+ * Token type classification for payment scheme selection
+ */
+type TokenType = "eip3009" | "legacy";
+/**
+ * Token configuration with EIP-712 domain parameters
+ */
+interface TokenConfig {
+    /** Token contract address */
+    address: Address;
+    /** Token symbol (e.g., "USDT0", "USDC") */
+    symbol: string;
+    /** EIP-712 domain name for signing */
+    name: string;
+    /** EIP-712 domain version for signing */
+    version: string;
+    /** Number of decimal places */
+    decimals: number;
+    /** Token type for scheme selection */
+    tokenType: TokenType;
+    /** Payment priority (lower = higher priority) */
+    priority: number;
+}
+/**
+ * Network token registry mapping network -> symbol -> config
+ */
+type NetworkTokenRegistry = Record<string, Record<string, TokenConfig>>;
+/**
+ * USDT0 Contract Addresses by Network
+ * Source: https://docs.tether.io/usdt0/integration-guide/deployed-contracts
+ *
+ * USDT0 is Tether's new omnichain token using LayerZero OFT standard.
+ * Key features:
+ * - Supports EIP-3009 transferWithAuthorization (gasless transfers)
+ * - Supports EIP-2612 permit
+ * - Native cross-chain via LayerZero
+ */
+declare const USDT0_ADDRESSES: Record<string, Address>;
+/**
+ * USDC Contract Addresses by Network
+ * Native USDC with EIP-3009 support
+ */
+declare const USDC_ADDRESSES: Record<string, Address>;
+/**
+ * Traditional USDT Addresses (Legacy - no EIP-3009 support)
+ * These require the approve + transferFrom pattern
+ */
+declare const USDT_LEGACY_ADDRESSES: Record<string, Address>;
+/**
+ * Complete token registry with all supported tokens per network
+ */
+declare const TOKEN_REGISTRY: NetworkTokenRegistry;
+/**
+ * Token priority for payment method selection
+ * Lower number = higher priority
+ */
+declare const TOKEN_PRIORITY: Record<string, number>;
+/**
+ * Get token configuration for a specific token on a network
+ */
+declare function getTokenConfig(network: string, symbol: string): TokenConfig | undefined;
+/**
+ * Get all tokens available on a network
+ */
+declare function getNetworkTokens(network: string): TokenConfig[];
+/**
+ * Get the default/preferred token for a network
+ * Prefers USDT0 > USDC > others based on priority
+ */
+declare function getDefaultToken(network: string): TokenConfig | undefined;
+/**
+ * Get token by contract address on a network
+ */
+declare function getTokenByAddress(network: string, address: Address): TokenConfig | undefined;
+/**
+ * Check if a token supports EIP-3009 (gasless transfers)
+ */
+declare function supportsEIP3009(network: string, symbol: string): boolean;
+/**
+ * Get all networks that support a specific token
+ */
+declare function getNetworksForToken(symbol: string): string[];
+/**
+ * Get USDT0 networks (primary T402 token)
+ */
+declare function getUsdt0Networks(): string[];
+/**
+ * EIP-712 domain configuration for a token
+ */
+declare function getEIP712Domain(network: string, tokenAddress: Address, chainId: number): {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: Address;
+} | undefined;
+
+/**
+ * EVM Utilities
+ *
+ * Utility functions for T402 EVM payments.
+ * No external dependencies - uses local implementations.
+ */
+
+/**
+ * Extract chain ID from network string (e.g., "base-sepolia" -> 84532)
+ * Used by v1 implementations
+ *
+ * @param network - The network identifier
+ * @returns The numeric chain ID
+ */
+declare function getEvmChainId(network: Network): number;
+/**
+ * Create a random 32-byte nonce for authorization
+ *
+ * @returns A hex-encoded 32-byte nonce
+ */
+declare function createNonce(): Hex;
+
+export { type Address, type Bytes32, type ClientEvmSigner, type ExactEIP3009Payload, type ExactEvmPayloadV1, type ExactEvmPayloadV2, type ExactLegacyPayload, type FacilitatorEvmSigner, type Hex, type NetworkTokenRegistry, type PermitAuthorization, type PermitSignature, TOKEN_PRIORITY, TOKEN_REGISTRY, type TokenConfig, type TokenType, USDC_ADDRESSES, USDT0_ADDRESSES, USDT_LEGACY_ADDRESSES, type UptoEIP2612Payload, type UptoEIP2612PayloadCompact, type UptoEvmExtra, type UptoEvmPayloadV2, type UptoEvmSettlement, authorizationTypes, bytesToHex, createNonce, eip3009ABI, erc20LegacyABI, getDefaultToken, getEIP712Domain, getEvmChainId, getNetworkTokens, getNetworksForToken, getTokenByAddress, getTokenConfig, getUsdt0Networks, hexToBytes, isUptoEIP2612Payload, legacyAuthorizationTypes, permitTypes, supportsEIP3009, toClientEvmSigner, toFacilitatorEvmSigner };