@4mica/x402 0.1.0

package/dist/server/scheme.js

@@ -0,0 +1,179 @@
+export const SUPPORTED_NETWORKS = ['eip155:11155111', 'eip155:80002'];
+/**
+ * EVM server implementation for the 4mica payment scheme.
+ */
+export class FourMicaEvmScheme {
+    constructor(advertisedTabEndpoint) {
+        this.advertisedTabEndpoint = advertisedTabEndpoint;
+        this.scheme = '4mica-credit';
+        this.moneyParsers = [];
+    }
+    /**
+     * 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) {
+        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, network) {
+        // 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, supportedKind, extensionKeys) {
+        // 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
+     */
+    parseMoneyToDecimal(money) {
+        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
+     */
+    defaultMoneyConversion(amount, network) {
+        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
+     */
+    convertToTokenAmount(decimalAmount, decimals) {
+        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
+     */
+    getDefaultAsset(network) {
+        // 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 = {
+            '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/eslint.config.mjs

@@ -0,0 +1,22 @@
+import js from "@eslint/js";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+import pluginReact from "eslint-plugin-react";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+  {
+    ignores: ["dist/**", "coverage/**", "node_modules/**", "*.cjs"],
+  },
+  {
+    files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"],
+    plugins: { js },
+    extends: ["js/recommended"],
+    languageOptions: { globals: globals.browser },
+  },
+  tseslint.configs.recommended,
+  pluginReact.configs.flat.recommended,
+  {
+    settings: { react: { version: "detect" } },
+  },
+]);

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@4mica/x402",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "TypeScript x402 utilities for interacting with the 4Mica payment network",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/4mica-Network/x402-4mica.git"
+  },
+  "homepage": "https://github.com/4mica-Network/x402-4mica#readme",
+  "bugs": {
+    "url": "https://github.com/4mica-Network/x402-4mica/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./server/express": {
+      "types": "./dist/server/express/index.d.ts",
+      "import": "./dist/server/express/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "lint": "eslint . --ext .ts",
+    "fmt": "prettier --check \"{src,tests}/**/*.{ts,js,json}\"",
+    "demo:server": "cd demo && yarn server",
+    "demo:client": "cd demo && yarn client",
+    "demo:dev": "cd demo && yarn dev"
+  },
+  "dependencies": {
+    "@x402/core": "^2.2.0",
+    "@x402/extensions": "^2.2.0",
+    "@4mica/sdk": "^0.5.3",
+    "viem": "^2.45.1"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@eslint/js": "^9.39.2",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.7",
+    "@typescript-eslint/eslint-plugin": "^8.48.1",
+    "@typescript-eslint/parser": "^8.48.1",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-react": "^7.37.5",
+    "express": "^5.2.1",
+    "globals": "^17.0.0",
+    "prettier": "^3.7.4",
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.48.1",
+    "vitest": "^4.0.17"
+  },
+  "peerDependencies": {
+    "@x402/paywall": "^2.2.0",
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@x402/paywall": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/client/index.ts

@@ -0,0 +1 @@
+export * from './scheme.js'

package/src/client/scheme.ts

@@ -0,0 +1,95 @@
+import { SchemeNetworkClient, PaymentRequirements, PaymentPayload, Network } from '@x402/core/types'
+import {
+  Client,
+  ConfigBuilder,
+  PaymentRequirementsV1,
+  X402Flow,
+  X402PaymentRequired,
+} from '@4mica/sdk'
+import { Account } from 'viem/accounts'
+import { SUPPORTED_NETWORKS } from '../server/scheme.js'
+
+const NETWORK_RPC_URLS: Record<Network, string> = {
+  'eip155:11155111': 'https://ethereum.sepolia.api.4mica.xyz',
+  'eip155:80002': 'https://api.4mica.xyz',
+}
+
+export class FourMicaEvmScheme implements SchemeNetworkClient {
+  readonly scheme = '4mica-credit'
+
+  private constructor(
+    private readonly signer: Account,
+    // rpcUrl -> x402Flow
+    private readonly x402Flows: Map<string, X402Flow>
+  ) {}
+
+  private static async createX402Flow(signer: Account, rpcUrl: string): Promise<X402Flow> {
+    const cfg = new ConfigBuilder().rpcUrl(rpcUrl).signer(signer).build()
+    const client = await Client.new(cfg)
+
+    return X402Flow.fromClient(client)
+  }
+
+  static async create(signer: Account): Promise<FourMicaEvmScheme> {
+    const x402Flows = new Map<string, X402Flow>()
+
+    for (const network of SUPPORTED_NETWORKS) {
+      const rpcUrl = NETWORK_RPC_URLS[network]
+      if (!rpcUrl) continue
+
+      x402Flows.set(rpcUrl, await FourMicaEvmScheme.createX402Flow(signer, rpcUrl))
+    }
+
+    return new FourMicaEvmScheme(signer, x402Flows)
+  }
+
+  async createPaymentPayload(
+    x402Version: number,
+    paymentRequirements: PaymentRequirements
+  ): Promise<Pick<PaymentPayload, 'x402Version' | 'payload'>> {
+    const network = paymentRequirements.network as Network
+    if (!network) {
+      throw new Error('Network is required in PaymentRequirements')
+    }
+
+    const rpcUrl = (paymentRequirements.extra?.rpcUrl as string) ?? NETWORK_RPC_URLS[network]
+    if (!rpcUrl) {
+      throw new Error(`No RPC URL configured for network ${network}`)
+    }
+
+    let x402Flow = this.x402Flows.get(rpcUrl)
+    if (!x402Flow) {
+      x402Flow = await FourMicaEvmScheme.createX402Flow(this.signer, rpcUrl)
+      this.x402Flows.set(rpcUrl, x402Flow)
+    }
+
+    if (x402Version === 1) {
+      const signed = await x402Flow.signPayment(
+        paymentRequirements as unknown as PaymentRequirementsV1,
+        this.signer.address
+      )
+      return {
+        x402Version: 1,
+        payload: signed.payload as unknown as Record<string, unknown>,
+      }
+    } else if (x402Version === 2) {
+      const paymentRequired: X402PaymentRequired = {
+        x402Version: 2,
+        resource: { url: '', description: '', mimeType: '' },
+        accepts: [paymentRequirements],
+      }
+      const signed = await x402Flow.signPaymentV2(
+        paymentRequired,
+        paymentRequirements,
+        this.signer.address
+      )
+
+      return {
+        x402Version: 2,
+        payload: signed.payload as unknown as Record<string, unknown>,
+      }
+    }
+
+    throw new Error(`Unsupported x402Version: ${x402Version}`)
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export type {
+  PaymentRequired,
+  PaymentRequirements,
+  PaymentPayload,
+  Network,
+  SchemeNetworkServer,
+} from '@x402/core/types'

package/src/server/express/adapter.ts

@@ -0,0 +1,100 @@
+import { HTTPAdapter } from '@x402/core/server'
+import { Request } from 'express'
+
+/**
+ * Express adapter implementation
+ */
+export class ExpressAdapter implements HTTPAdapter {
+  /**
+   * Creates a new ExpressAdapter instance.
+   *
+   * @param req - The Express request object
+   */
+  constructor(private req: Request) {}
+
+  /**
+   * Gets a header value from the request.
+   *
+   * @param name - The header name
+   * @returns The header value or undefined
+   */
+  getHeader(name: string): string | undefined {
+    const value = this.req.header(name)
+    return Array.isArray(value) ? value[0] : value
+  }
+
+  /**
+   * Gets the HTTP method of the request.
+   *
+   * @returns The HTTP method
+   */
+  getMethod(): string {
+    return this.req.method
+  }
+
+  /**
+   * Gets the path of the request.
+   *
+   * @returns The request path
+   */
+  getPath(): string {
+    return this.req.path
+  }
+
+  /**
+   * Gets the full URL of the request.
+   *
+   * @returns The full request URL
+   */
+  getUrl(): string {
+    return `${this.req.protocol}://${this.req.headers.host}${this.req.originalUrl}`
+  }
+
+  /**
+   * Gets the Accept header from the request.
+   *
+   * @returns The Accept header value or empty string
+   */
+  getAcceptHeader(): string {
+    return this.req.header('Accept') || ''
+  }
+
+  /**
+   * Gets the User-Agent header from the request.
+   *
+   * @returns The User-Agent header value or empty string
+   */
+  getUserAgent(): string {
+    return this.req.header('User-Agent') || ''
+  }
+
+  /**
+   * Gets all query parameters from the request URL.
+   *
+   * @returns Record of query parameter key-value pairs
+   */
+  getQueryParams(): Record<string, string | string[]> {
+    return this.req.query as Record<string, string | string[]>
+  }
+
+  /**
+   * Gets a specific query parameter by name.
+   *
+   * @param name - The query parameter name
+   * @returns The query parameter value(s) or undefined
+   */
+  getQueryParam(name: string): string | string[] | undefined {
+    const value = this.req.query[name]
+    return value as string | string[] | undefined
+  }
+
+  /**
+   * Gets the parsed request body.
+   * Requires express.json() or express.urlencoded() middleware.
+   *
+   * @returns The parsed request body
+   */
+  getBody(): unknown {
+    return this.req.body
+  }
+}