@4mica/x402 0.1.0

package/src/server/scheme.ts

@@ -0,0 +1,223 @@
+import {
+  AssetAmount,
+  Network,
+  PaymentRequirements,
+  Price,
+  SchemeNetworkServer,
+  MoneyParser,
+} from '@x402/core/types'
+
+export const SUPPORTED_NETWORKS: Network[] = ['eip155:11155111', 'eip155:80002']
+
+/**
+ * EVM server implementation for the 4mica payment scheme.
+ */
+export class FourMicaEvmScheme implements SchemeNetworkServer {
+  readonly scheme = '4mica-credit'
+  private moneyParsers: MoneyParser[] = []
+
+  constructor(readonly advertisedTabEndpoint: string) {}
+
+  /**
+   * Register a custom money parser in the parser chain.
+   * Multiple parsers can be registered - they will be tried in registration order.
+   * Each parser receives a decimal amount (e.g., 1.50 for $1.50).
+   * If a parser returns null, the next parser in the chain will be tried.
+   * The default parser is always the final fallback.
+   *
+   * @param parser - Custom function to convert amount to AssetAmount (or null to skip)
+   * @returns The server instance for chaining
+   *
+   * @example
+   * evmServer.registerMoneyParser(async (amount, network) => {
+   *   // Custom conversion logic
+   *   if (amount > 100) {
+   *     // Use different token for large amounts
+   *     return { amount: (amount * 1e18).toString(), asset: "0xCustomToken" };
+   *   }
+   *   return null; // Use next parser
+   * });
+   */
+  registerMoneyParser(parser: MoneyParser): FourMicaEvmScheme {
+    this.moneyParsers.push(parser)
+    return this
+  }
+
+  /**
+   * Parses a price into an asset amount.
+   * If price is already an AssetAmount, returns it directly.
+   * If price is Money (string | number), parses to decimal and tries custom parsers.
+   * Falls back to default conversion if all custom parsers return null.
+   *
+   * @param price - The price to parse
+   * @param network - The network to use
+   * @returns Promise that resolves to the parsed asset amount
+   */
+  async parsePrice(price: Price, network: Network): Promise<AssetAmount> {
+    // If already an AssetAmount, return it directly
+    if (typeof price === 'object' && price !== null && 'amount' in price) {
+      if (!price.asset) {
+        throw new Error(`Asset address must be specified for AssetAmount on network ${network}`)
+      }
+      return {
+        amount: price.amount,
+        asset: price.asset,
+        extra: price.extra || {},
+      }
+    }
+
+    // Parse Money to decimal number
+    const amount = this.parseMoneyToDecimal(price)
+
+    // Try each custom money parser in order
+    for (const parser of this.moneyParsers) {
+      const result = await parser(amount, network)
+      if (result !== null) {
+        return result
+      }
+    }
+
+    // All custom parsers returned null, use default conversion
+    return this.defaultMoneyConversion(amount, network)
+  }
+
+  /**
+   * Build payment requirements for this scheme/network combination
+   *
+   * @param paymentRequirements - The base payment requirements
+   * @param supportedKind - The supported kind from facilitator (unused)
+   * @param supportedKind.x402Version - The x402 version
+   * @param supportedKind.scheme - The logical payment scheme
+   * @param supportedKind.network - The network identifier in CAIP-2 format
+   * @param supportedKind.extra - Optional extra metadata regarding scheme/network implementation details
+   * @param extensionKeys - Extension keys supported by the facilitator (unused)
+   * @returns Payment requirements ready to be sent to clients
+   */
+  enhancePaymentRequirements(
+    paymentRequirements: PaymentRequirements,
+    supportedKind: {
+      x402Version: number
+      scheme: string
+      network: Network
+      extra?: Record<string, unknown>
+    },
+    extensionKeys: string[]
+  ): Promise<PaymentRequirements> {
+    // Mark unused parameters to satisfy linter
+    void supportedKind
+    void extensionKeys
+
+    if (!paymentRequirements.extra) {
+      paymentRequirements.extra = {}
+    }
+    paymentRequirements.extra.tabEndpoint = this.advertisedTabEndpoint
+
+    return Promise.resolve(paymentRequirements)
+  }
+
+  /**
+   * Parse Money (string | number) to a decimal number.
+   * Handles formats like "$1.50", "1.50", 1.50, etc.
+   *
+   * @param money - The money value to parse
+   * @returns Decimal number
+   */
+  private parseMoneyToDecimal(money: string | number): number {
+    if (typeof money === 'number') {
+      return money
+    }
+
+    // Remove $ sign and whitespace, then parse
+    const cleanMoney = money.replace(/^\$/, '').trim()
+    const amount = parseFloat(cleanMoney)
+
+    if (isNaN(amount)) {
+      throw new Error(`Invalid money format: ${money}`)
+    }
+
+    return amount
+  }
+
+  /**
+   * Default money conversion implementation.
+   * Converts decimal amount to the default stablecoin on the specified network.
+   *
+   * @param amount - The decimal amount (e.g., 1.50)
+   * @param network - The network to use
+   * @returns The parsed asset amount in the default stablecoin
+   */
+  private defaultMoneyConversion(amount: number, network: Network): AssetAmount {
+    const assetInfo = this.getDefaultAsset(network)
+    const tokenAmount = this.convertToTokenAmount(amount.toString(), assetInfo.decimals)
+
+    return {
+      amount: tokenAmount,
+      asset: assetInfo.address,
+      extra: {
+        name: assetInfo.name,
+        version: assetInfo.version,
+      },
+    }
+  }
+
+  /**
+   * Convert decimal amount to token units (e.g., 0.10 -> 100000 for 6-decimal tokens)
+   *
+   * @param decimalAmount - The decimal amount to convert
+   * @param decimals - The number of decimals for the token
+   * @returns The token amount as a string
+   */
+  private convertToTokenAmount(decimalAmount: string, decimals: number): string {
+    const amount = parseFloat(decimalAmount)
+    if (isNaN(amount)) {
+      throw new Error(`Invalid amount: ${decimalAmount}`)
+    }
+    // Convert to smallest unit (e.g., for USDC with 6 decimals: 0.10 * 10^6 = 100000)
+    const [intPart, decPart = ''] = String(amount).split('.')
+    const paddedDec = decPart.padEnd(decimals, '0').slice(0, decimals)
+    const tokenAmount = (intPart + paddedDec).replace(/^0+/, '') || '0'
+    return tokenAmount
+  }
+
+  /**
+   * Get the default asset info for a network (typically USDC)
+   *
+   * @param network - The network to get asset info for
+   * @returns The asset information including address, name, version, and decimals
+   */
+  private getDefaultAsset(network: Network): {
+    address: string
+    name: string
+    version: string
+    decimals: number
+  } {
+    // Map of network to USDC info including EIP-712 domain parameters
+    // Each network has the right to determine its own default stablecoin that can be expressed as a USD string by calling servers
+    // NOTE: Currently only EIP-3009 supporting stablecoins can be used with this scheme
+    // Generic ERC20 support via EIP-2612/permit2 is planned, but not yet implemented.
+    const stablecoins: Record<
+      string,
+      { address: string; name: string; version: string; decimals: number }
+    > = {
+      'eip155:11155111': {
+        address: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
+        name: 'USDC',
+        version: '2',
+        decimals: 6,
+      }, // Ethereum Sepolia USDC
+      'eip155:80002': {
+        address: '0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582',
+        name: 'USDC',
+        version: '2',
+        decimals: 6,
+      }, // Polygon PoS Amoy USDC
+    }
+
+    const assetInfo = stablecoins[network]
+    if (!assetInfo) {
+      throw new Error(`No default asset configured for network ${network}`)
+    }
+
+    return assetInfo
+  }
+}

package/tsconfig.build.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["src/**/*"],
+  "exclude": ["tests", "dist", "node_modules"]
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "Node16",
+    "lib": [
+      "ES2020"
+    ],
+    "moduleResolution": "node16",
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+  },
+  "include": ["src/**/*", "tests/**/*", "vitest.config.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+    exclude: [
+      'dist/**',
+      'node_modules/**',
+      ...(process.env.CI ? ['tests/**/*.integration.test.ts'] : []),
+    ],
+  },
+});