@4mica/x402 1.2.4 → 2.0.0-alpha.2

package/dist/server/scheme.js

@@ -1,12 +1,43 @@
-export const SUPPORTED_NETWORKS = ['eip155:11155111', 'eip155:84532', 'eip155:80002'];
+import { RpcProxy, resolveNetworkRpcUrl, } from '@4mica/sdk';
+import { SDK_DEFAULT_ASSET_TRANSFER_METHOD } from '@x402/core/server';
+import { chainIdOf, DOMAIN_EXTRA_KEYS } from '../domain.js';
+export const SUPPORTED_NETWORKS = ['eip155:11155111', 'eip155:84532', 'eip155:8453'];
 /**
  * EVM server implementation for the 4mica payment scheme.
+ *
+ * A `Money` price resolves to the stablecoin core lists for the network
+ * (`GET /core/tokens`), so the advertised `asset` is always one core accepts a
+ * guarantee against. Every requirement also carries core's EIP-712 domain in
+ * `extra` (`name`, `version`, `verifyingContract`, from
+ * `GET /core/public-params`), so a payer can sign without calling core. Both
+ * are fetched once per network and cached for the life of the instance.
  */
 export class FourMicaEvmScheme {
-    constructor(advertisedTabEndpoint) {
-        this.advertisedTabEndpoint = advertisedTabEndpoint;
+    constructor(options = {}) {
         this.scheme = '4mica-credit';
+        // No on-wire assetTransferMethod: a claim is a claim. The signed payment is
+        // verified before the handler runs and settled (guarantee issued) after it
+        // — the library's authorization flow.
+        this.defaultAssetTransferMethod = SDK_DEFAULT_ASSET_TRANSFER_METHOD;
+        this.paymentFlows = {
+            [SDK_DEFAULT_ASSET_TRANSFER_METHOD]: {
+                supported: ['authorization'],
+                default: 'authorization',
+            },
+        };
         this.moneyParsers = [];
+        this.defaultAssets = new Map();
+        this.domains = new Map();
+        this.coreUrls = options.coreUrls ?? {};
+        this.stablecoinSymbol = options.stablecoinSymbol ?? 'USDC';
+    }
+    /** Core's token list. Private static so tests can stub the network call. */
+    static loadSupportedTokens(coreUrl) {
+        return new RpcProxy(coreUrl).getSupportedTokens();
+    }
+    /** Core's public parameters. Private static so tests can stub the network call. */
+    static loadPublicParams(coreUrl) {
+        return new RpcProxy(coreUrl).getPublicParams();
     }
     /**
      * Register a custom money parser in the parser chain.
@@ -36,7 +67,7 @@ export class FourMicaEvmScheme {
      * 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.
+     * Falls back to the stablecoin core lists for the network if all custom parsers return null.
      *
      * @param price - The price to parse
      * @param network - The network to use
@@ -67,7 +98,12 @@ export class FourMicaEvmScheme {
         return this.defaultMoneyConversion(amount, network);
     }
     /**
-     * Build payment requirements for this scheme/network combination
+     * Build payment requirements for this scheme/network combination.
+     *
+     * Adds core's EIP-712 domain to `extra` so the payer can sign without a
+     * round trip to core. A domain the resource server set itself is kept; only
+     * the missing keys are filled in. The chain id is not added: a client takes
+     * it from `network`.
      *
      * @param paymentRequirements - The base payment requirements
      * @param supportedKind - The supported kind from facilitator (unused)
@@ -78,15 +114,17 @@ export class FourMicaEvmScheme {
      * @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
+    async enhancePaymentRequirements(paymentRequirements, supportedKind, extensionKeys) {
         void supportedKind;
         void extensionKeys;
-        if (!paymentRequirements.extra) {
-            paymentRequirements.extra = {};
-        }
-        paymentRequirements.extra.tabEndpoint = this.advertisedTabEndpoint;
-        return Promise.resolve(paymentRequirements);
+        const extra = { ...(paymentRequirements.extra ?? {}) };
+        const missing = DOMAIN_EXTRA_KEYS.filter((key) => typeof extra[key] !== 'string');
+        if (missing.length === 0)
+            return paymentRequirements;
+        const domain = await this.getDomain(paymentRequirements.network);
+        for (const key of missing)
+            extra[key] = domain[key];
+        return { ...paymentRequirements, extra };
     }
     /**
      * Parse Money (string | number) to a decimal number.
@@ -102,29 +140,28 @@ export class FourMicaEvmScheme {
         // Remove $ sign and whitespace, then parse
         const cleanMoney = money.replace(/^\$/, '').trim();
         const amount = parseFloat(cleanMoney);
-        if (isNaN(amount)) {
+        if (Number.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.
+     * Converts a decimal amount to the stablecoin core lists for the 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);
+    async defaultMoneyConversion(amount, network) {
+        const asset = await this.getDefaultAsset(network);
         return {
-            amount: tokenAmount,
-            asset: assetInfo.address,
-            extra: {
-                name: assetInfo.name,
-                version: assetInfo.version,
-            },
+            amount: this.convertToTokenAmount(amount.toString(), asset.decimals),
+            asset: asset.address,
+            // No EIP-3009 domain hints: a 4mica-credit payer signs against core's
+            // guarantee domain, never the token's. `enhancePaymentRequirements` adds
+            // that domain for every kind of price.
+            extra: {},
         };
     }
     /**
@@ -136,7 +173,7 @@ export class FourMicaEvmScheme {
      */
     convertToTokenAmount(decimalAmount, decimals) {
         const amount = parseFloat(decimalAmount);
-        if (isNaN(amount)) {
+        if (Number.isNaN(amount)) {
             throw new Error(`Invalid amount: ${decimalAmount}`);
         }
         // Convert to smallest unit (e.g., for USDC with 6 decimals: 0.10 * 10^6 = 100000)
@@ -145,41 +182,66 @@ export class FourMicaEvmScheme {
         const tokenAmount = (intPart + paddedDec).replace(/^0+/, '') || '0';
         return tokenAmount;
     }
+    coreUrlFor(network) {
+        const coreUrl = this.coreUrls[network] ?? resolveNetworkRpcUrl(network);
+        if (!coreUrl) {
+            throw new Error(`No core API URL known for network ${network}; pass one in coreUrls`);
+        }
+        return coreUrl;
+    }
     /**
-     * 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
+     * The stablecoin core lists for `network`, fetched once and cached. A failed
+     * lookup is not cached, so the next price parse retries.
      */
     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:84532': {
-                address: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
-                name: 'USDC',
-                version: '2',
-                decimals: 6,
-            }, // Base 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 cachedLookup(this.defaultAssets, network, () => this.resolveDefaultAsset(network));
+    }
+    async resolveDefaultAsset(network) {
+        const coreUrl = this.coreUrlFor(network);
+        const { tokens } = await FourMicaEvmScheme.loadSupportedTokens(coreUrl);
+        const wanted = this.stablecoinSymbol.toLowerCase();
+        const token = tokens.find((entry) => entry.symbol.toLowerCase() === wanted);
+        if (!token) {
+            const listed = tokens.map((entry) => entry.symbol).join(', ') || 'none';
+            throw new Error(`Core at ${coreUrl} lists no ${this.stablecoinSymbol} for network ${network} (listed: ${listed})`);
+        }
+        if (token.decimals === undefined) {
+            throw new Error(`Core at ${coreUrl} reports no decimals for ${token.symbol} on network ${network}`);
         }
-        return assetInfo;
+        return { address: token.address, decimals: token.decimals };
+    }
+    /**
+     * Core's EIP-712 domain for `network`, fetched once and cached. A failed
+     * lookup is not cached, so the next 402 retries.
+     */
+    getDomain(network) {
+        return cachedLookup(this.domains, network, () => this.resolveDomain(network));
+    }
+    async resolveDomain(network) {
+        const coreUrl = this.coreUrlFor(network);
+        const params = await FourMicaEvmScheme.loadPublicParams(coreUrl);
+        // The client derives the chain id from `network`, so a core that serves a
+        // different chain would hand out a domain no signature can satisfy.
+        const expectedChainId = chainIdOf(network);
+        if (expectedChainId !== undefined && params.chainId !== expectedChainId) {
+            throw new Error(`Core at ${coreUrl} serves chain ${params.chainId}, not ${network}; check coreUrls`);
+        }
+        return {
+            name: params.eip712Name,
+            version: params.eip712Version,
+            verifyingContract: params.contractAddress,
+        };
+    }
+}
+/** Memoise a per-network lookup, dropping a rejected entry so the next call retries. */
+function cachedLookup(cache, network, resolve) {
+    let pending = cache.get(network);
+    if (!pending) {
+        pending = resolve().catch((err) => {
+            cache.delete(network);
+            throw err;
+        });
+        cache.set(network, pending);
     }
+    return pending;
 }

package/dist/types.d.ts

@@ -1,15 +1,39 @@
-import { PaymentRequirements } from '@x402/core/types';
+import type { PaymentRequirements } from '@x402/core/types';
 /**
- * Extra fields required by the 4mica V2 validation policy.
+ * The `extra.validation` object a resource server advertises to gate a
+ * payment on an external validator. Present ⇒ the payer signs the same
+ * requirement into their claims, and the guarantee only becomes payable once
+ * the validator approves it.
  */
-export type FourMicaV2RequirementsExtra = {
-    validationRegistryAddress: string;
-    validatorAddress: string;
-    validatorAgentId: string | number;
-    minValidationScore: number;
-    jobHash: string;
-    requiredValidationTag?: string;
-    tabEndpoint?: string;
+export type FourMicaValidationExtra = {
+    /** Validator identifier; must be on core's allowlist. */
+    validator: string;
+    /** 0x-prefixed bytes32 the validator must approve. */
+    subject: string;
+    /** Unix seconds; core tightens this to the cycle's resolution cutoff. */
+    deadline?: number;
+    /** 0x-prefixed validator-specific policy bytes. */
+    params?: string;
+};
+/**
+ * The EIP-712 domain of the core a payer signs against, as
+ * `GET /core/public-params` reports it (`eip712_name`, `eip712_version`,
+ * `contract_address`). The chain id is not carried: it is the CAIP-2
+ * reference in `network`, so the two can never disagree.
+ */
+export type FourMicaDomainExtra = {
+    name: string;
+    version: string;
+    verifyingContract: string;
+};
+/**
+ * Extra fields the 4mica-credit scheme understands on `paymentRequirements`.
+ * There is no tab endpoint any more: clients sign their claim straight from
+ * the requirements, minting a random `reqId` locally.
+ */
+export type FourMicaRequirementsExtra = Partial<FourMicaDomainExtra> & {
+    validation?: FourMicaValidationExtra;
+    /** Override the 4Mica core API URL the client signs against. */
     rpcUrl?: string;
     resource?: {
         url?: string;
@@ -17,6 +41,6 @@ export type FourMicaV2RequirementsExtra = {
         mimeType?: string;
     };
 };
-export type FourMicaPaymentRequirementsV2 = PaymentRequirements & {
-    extra: FourMicaV2RequirementsExtra;
+export type FourMicaPaymentRequirements = PaymentRequirements & {
+    extra?: FourMicaRequirementsExtra;
 };

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@4mica/x402",
-  "version": "1.2.4",
+  "version": "2.0.0-alpha.2",
   "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"
+    "url": "https://github.com/4mica-Network/4mica.git",
+    "directory": "apps/facilitator/packages/typescript/x402"
   },
-  "homepage": "https://github.com/4mica-Network/x402-4mica#readme",
+  "homepage": "https://github.com/4mica-Network/4mica/tree/main/apps/facilitator/packages/typescript/x402#readme",
   "bugs": {
-    "url": "https://github.com/4mica-Network/x402-4mica/issues"
+    "url": "https://github.com/4mica-Network/4mica/issues"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -32,37 +33,25 @@
       "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"
-  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
   "dependencies": {
-    "@x402/core": "^2.9.0",
-    "@x402/extensions": "^2.9.0",
-    "@4mica/sdk": "^1.2.3",
-    "viem": "^2.45.1"
+    "@x402/core": "2.23.0",
+    "@x402/extensions": "2.23.0",
+    "viem": "2.x",
+    "@4mica/sdk": "^2.0.0-alpha.0"
   },
   "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"
+    "@biomejs/biome": "^2.4.16",
+    "@types/express": "^5.0.0",
+    "@types/node": "^26.1.1",
+    "express": "^5.1.0",
+    "publint": "^0.3.14",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.8"
   },
   "peerDependencies": {
     "@x402/paywall": "^2.2.0",
@@ -75,5 +64,17 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check:exports": "attw --pack . --profile esm-only && publint --strict",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "lint:write": "biome check --write --diagnostic-level=error .",
+    "fmt": "biome format .",
+    "fmt:write": "biome format --write .",
+    "demo:server": "pnpm --filter @4mica/x402-demo run server",
+    "demo:client": "pnpm --filter @4mica/x402-demo run client",
+    "demo:dev": "pnpm --filter @4mica/x402-demo run dev"
   }
-}
+}

package/.eslintrc.cjs

@@ -1,29 +0,0 @@
-module.exports = {
-  root: true,
-  env: {
-    es2020: true,
-    node: true,
-  },
-  parser: "@typescript-eslint/parser",
-  parserOptions: {
-    sourceType: "module",
-    ecmaVersion: 2020,
-    project: "./tsconfig.json",
-  },
-  plugins: ["@typescript-eslint"],
-  extends: [
-    "eslint:recommended",
-    "plugin:@typescript-eslint/recommended",
-    "eslint-config-prettier",
-  ],
-  rules: {
-    "@typescript-eslint/no-explicit-any": "off",
-    "@typescript-eslint/explicit-module-boundary-types": "off",
-    "@typescript-eslint/no-unused-vars": [
-      "error",
-      { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
-    ],
-    "@typescript-eslint/no-var-requires": "off",
-  },
-  ignorePatterns: ["dist", "node_modules"],
-};

package/.prettierignore

@@ -1,3 +0,0 @@
-dist
-node_modules
-coverage

package/.prettierrc

@@ -1,6 +0,0 @@
-{
-  "singleQuote": true,
-  "trailingComma": "es5",
-  "printWidth": 100,
-  "semi": false
-}

package/demo/.env.example

@@ -1,8 +0,0 @@
-# Server Configuration
-PORT=3000
-PAY_TO_ADDRESS=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
-ADVERTISED_ENDPOINT=http://localhost:3000/payment/tab
-
-# Client Configuration
-PRIVATE_KEY=0xYourPrivateKeyHere
-API_URL=http://localhost:3000

package/demo/README.md

@@ -1,125 +0,0 @@
-# @4mica/x402 Demo
-
-This demo shows how to use `@4mica/x402` to protect an API endpoint with 4mica payments.
-
-## Setup
-
-1. **Install dependencies**:
-
-First, build the parent package:
-
-```bash
-cd ..
-yarn install
-yarn build
-```
-
-Then install demo dependencies:
-
-```bash
-cd demo
-yarn install
-```
-
-2. **Configure environment variables**:
-
-Copy the example file and edit it:
-
-```bash
-cp .env.example .env
-# Edit .env with your private key and settings
-```
-
-Required variables:
-- `PRIVATE_KEY`: Your Ethereum private key (with 0x prefix) for Sepolia testnet
-- `PAY_TO_ADDRESS`: Address that will receive payments
-
-## Running the Demo
-
-### Terminal 1: Start the server
-
-From the demo directory:
-
-```bash
-yarn server
-```
-
-Or from the package root:
-
-```bash
-yarn demo:server
-```
-
-You should see:
-```
-x402 Demo Server running on http://localhost:3000
-Protected endpoint: http://localhost:3000/api/premium-data
-Payment required: $0.01 (4mica credit on Sepolia)
-```
-
-### Terminal 2: Run the client
-
-The client will automatically load environment variables from `.env`:
-
-From the demo directory:
-
-```bash
-yarn client
-```
-
-Or from the package root:
-
-```bash
-yarn demo:client
-```
-
-You can also set PRIVATE_KEY inline:
-
-```bash
-PRIVATE_KEY=0xYourPrivateKey yarn client
-```
-
-## What Happens
-
-1. **Server** starts with one protected endpoint: `GET /api/premium-data`
-   - Requires a payment of $0.01 in 4mica credits on Sepolia
-   - Uses x402 payment protocol
-
-2. **Client** makes a request to the protected endpoint:
-   - First receives `402 Payment Required` response
-   - Automatically opens a payment tab via the 4mica facilitator
-   - Signs and submits the payment
-   - Retries the request with payment proof
-   - Receives the protected data
-
-3. **Payment Flow**:
-   ```
-   Client → GET /api/premium-data
-          ← 402 Payment Required (with payment requirements)
-   
-   Client → POST /payment/tab (open payment tab)
-          ← 200 OK (tab details)
-   
-   Client → Signs payment guarantee (via 4mica SDK)
-   
-   Client → GET /api/premium-data (with payment proof)
-          ← 200 OK (protected data)
-   ```
-
-## Testing Without Running the Client
-
-You can also test the server manually using curl:
-
-```bash
-# Check server status
-curl http://localhost:3000/
-
-# Try to access protected endpoint (will return 402)
-curl -v http://localhost:3000/api/premium-data
-```
-
-## Notes
-
-- Make sure your account has sufficient balance on Sepolia testnet
-- The demo uses the default 4mica facilitator configuration
-- Tab TTL is set to 1 hour (3600 seconds)

package/demo/package.json

@@ -1,26 +0,0 @@
-{
-  "name": "@4mica/x402-demo",
-  "version": "0.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "server": "tsx src/server.ts",
-    "client": "tsx src/client.ts",
-    "deposit": "tsx src/deposit.ts",
-    "dev": "tsx watch src/server.ts"
-  },
-  "dependencies": {
-    "@4mica/sdk": "^0.5.3",
-    "@4mica/x402": "file:..",
-    "@x402/fetch": "^2.2.0",
-    "dotenv": "^16.4.7",
-    "express": "^5.2.1",
-    "viem": "^2.21.54"
-  },
-  "devDependencies": {
-    "@types/express": "^5.0.6",
-    "@types/node": "^25.0.7",
-    "tsx": "^4.19.2",
-    "typescript": "^5.3.3"
-  }
-}

package/demo/src/client.ts

@@ -1,54 +0,0 @@
-import 'dotenv/config'
-import { wrapFetchWithPaymentFromConfig } from '@x402/fetch'
-import { FourMicaEvmScheme } from '@4mica/x402/client'
-import { privateKeyToAccount } from 'viem/accounts'
-
-async function main() {
-  const privateKey = process.env.PRIVATE_KEY
-  if (!privateKey || !privateKey.startsWith('0x')) {
-    console.error('Error: PRIVATE_KEY environment variable must be set and start with 0x')
-    console.error('Example: PRIVATE_KEY=0x1234... yarn client')
-    process.exit(1)
-  }
-
-  const apiUrl = process.env.API_URL || 'http://localhost:3000'
-  const endpoint = `${apiUrl}/api/premium-data`
-
-  console.log('Initializing x402 client...')
-  console.log(`Target endpoint: ${endpoint}`)
-
-  const account = privateKeyToAccount(privateKey as `0x${string}`)
-  console.log(`Using account: ${account.address}`)
-
-  const scheme = await FourMicaEvmScheme.create(account)
-
-  const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
-    schemes: [
-      {
-        network: 'eip155:11155111', // Ethereum Sepolia
-        client: scheme,
-      },
-    ],
-  })
-
-  console.log('\nMaking request to protected endpoint...')
-
-  try {
-    const response = await fetchWithPayment(endpoint)
-    const data = await response.json()
-
-    console.log('Request successful!')
-    console.log('Response:', JSON.stringify(data, null, 2))
-  } catch (error) {
-    console.error('Request failed:', error)
-    if (error instanceof Error) {
-      console.error('Message:', error.message)
-    }
-    process.exit(1)
-  }
-}
-
-main().catch((error) => {
-  console.error('Unhandled error:', error)
-  process.exit(1)
-})