@4mica/x402 0.1.0 → 1.0.0

package/README.md

@@ -277,6 +277,20 @@ const client = new x402Client()
 const fetchWithPayment = wrapFetchWithPayment(fetch, client);
 ```
 
+## V2 Validation Policy Notes
+
+For x402 V2 requests, include validation policy metadata in `paymentRequirements.extra`:
+
+- `validationRegistryAddress`
+- `validatorAddress`
+- `validatorAgentId`
+- `minValidationScore`
+- optional `requiredValidationTag`
+
+`validationChainId` is optional. When omitted, the underlying 4mica SDK derives the
+`validation_chain_id` from the CAIP-2 `network` value (for example, `eip155:1`).
+If `validationChainId` is provided, it must match that network chain id.
+
 ## Complete Example
 
 ### Server

package/demo/README.md

@@ -32,7 +32,7 @@ cp .env.example .env
 
 Required variables:
 - `PRIVATE_KEY`: Your Ethereum private key (with 0x prefix) for Sepolia testnet
-- `PAY_TO_ADDRESS`: Address that will receive payments (optional, defaults to a test address)
+- `PAY_TO_ADDRESS`: Address that will receive payments
 
 ## Running the Demo
 
@@ -54,7 +54,7 @@ You should see:
 ```
 x402 Demo Server running on http://localhost:3000
 Protected endpoint: http://localhost:3000/api/premium-data
-Payment required: $0.05 (4mica credit on Sepolia)
+Payment required: $0.01 (4mica credit on Sepolia)
 ```
 
 ### Terminal 2: Run the client
@@ -82,7 +82,7 @@ PRIVATE_KEY=0xYourPrivateKey yarn client
 ## What Happens
 
 1. **Server** starts with one protected endpoint: `GET /api/premium-data`
-   - Requires a payment of $0.05 in 4mica credits on Sepolia
+   - Requires a payment of $0.01 in 4mica credits on Sepolia
    - Uses x402 payment protocol
 
 2. **Client** makes a request to the protected endpoint:

package/demo/package.json

@@ -10,7 +10,7 @@
     "dev": "tsx watch src/server.ts"
   },
   "dependencies": {
-    "@4mica/sdk": "file:../../../../../ts-sdk-4mica",
+    "@4mica/sdk": "^0.5.3",
     "@4mica/x402": "file:..",
     "@x402/fetch": "^2.2.0",
     "dotenv": "^16.4.7",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4mica/x402",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "TypeScript x402 utilities for interacting with the 4Mica payment network",
   "license": "MIT",

package/src/client/scheme.ts

@@ -5,6 +5,7 @@ import {
   PaymentRequirementsV1,
   X402Flow,
   X402PaymentRequired,
+  X402ResourceInfo,
 } from '@4mica/sdk'
 import { Account } from 'viem/accounts'
 import { SUPPORTED_NETWORKS } from '../server/scheme.js'
@@ -73,9 +74,23 @@ export class FourMicaEvmScheme implements SchemeNetworkClient {
         payload: signed.payload as unknown as Record<string, unknown>,
       }
     } else if (x402Version === 2) {
+      const resourcePayload =
+        paymentRequirements.extra &&
+        typeof paymentRequirements.extra === 'object' &&
+        'resource' in paymentRequirements.extra &&
+        typeof paymentRequirements.extra.resource === 'object' &&
+        paymentRequirements.extra.resource !== null
+          ? (paymentRequirements.extra.resource as Record<string, unknown>)
+          : {}
+
+      const resource: X402ResourceInfo = {
+        url: String(resourcePayload.url ?? ''),
+        description: String(resourcePayload.description ?? ''),
+        mimeType: String(resourcePayload.mimeType ?? ''),
+      }
       const paymentRequired: X402PaymentRequired = {
         x402Version: 2,
-        resource: { url: '', description: '', mimeType: '' },
+        resource,
         accepts: [paymentRequirements],
       }
       const signed = await x402Flow.signPaymentV2(

package/src/server/facilitator.ts

@@ -1,5 +1,5 @@
 import { FacilitatorConfig, HTTPFacilitatorClient } from '@x402/core/server'
-import { Network, PaymentRequirements } from '@x402/core/types'
+import { Network, PaymentPayload, PaymentRequirements, SettleResponse } from '@x402/core/types'
 
 const DEFAULT_FACILITATOR_URL = 'https://x402.4mica.xyz'
 
@@ -21,6 +21,18 @@ export interface OpenTabResponse {
   nextReqId: string
 }
 
+export interface CertificateResponse {
+  claims: string
+  signature: string
+}
+
+export type FourMicaSettleResponse = SettleResponse & {
+  certificate?: CertificateResponse
+  txHash?: string
+  networkId?: string
+  error?: string
+}
+
 export class OpenTabError extends Error {
   constructor(
     public readonly status: number,
@@ -75,6 +87,41 @@ export class FourMicaFacilitatorClient extends HTTPFacilitatorClient {
     throw new Error(`Facilitator openTab failed (${response.status}): ${JSON.stringify(data)}`)
   }
 
+  async settle(
+    paymentPayload: PaymentPayload,
+    paymentRequirements: PaymentRequirements
+  ): Promise<FourMicaSettleResponse> {
+    let headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    }
+
+    const authHeaders = await this.createAuthHeaders('settle')
+    headers = { ...headers, ...authHeaders.headers }
+
+    const response = await fetch(`${this.url}/settle`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(
+        this.safeJson({
+          x402Version: paymentPayload.x402Version,
+          paymentPayload,
+          paymentRequirements,
+        })
+      ),
+    })
+
+    const data = (await response.json()) as Record<string, unknown>
+    const normalized = normalizeSettleResponse(data, paymentRequirements)
+
+    if (!response.ok || !normalized.success) {
+      throw new Error(
+        `Facilitator settle failed (${response.status}): ${normalized.errorReason ?? normalized.error ?? 'unknown error'}`
+      )
+    }
+
+    return normalized
+  }
+
   /**
    * Helper to convert objects to JSON-safe format.
    * Handles BigInt and other non-JSON types.
@@ -88,3 +135,70 @@ export class FourMicaFacilitatorClient extends HTTPFacilitatorClient {
     )
   }
 }
+
+function normalizeSettleResponse(
+  payload: Record<string, unknown>,
+  requirements: PaymentRequirements
+): FourMicaSettleResponse {
+  const transaction = String(
+    payload.transaction ??
+      payload.transactionHash ??
+      payload.txHash ??
+      payload.tx_hash ??
+      payload.hash ??
+      ''
+  )
+  const network = String(
+    payload.network ?? payload.networkId ?? payload.network_id ?? requirements.network
+  ) as Network
+  const errorReason =
+    typeof payload.errorReason === 'string'
+      ? payload.errorReason
+      : typeof payload.error_reason === 'string'
+        ? payload.error_reason
+        : typeof payload.error === 'string'
+          ? payload.error
+          : typeof payload.message === 'string'
+            ? payload.message
+            : undefined
+
+  const certificate =
+    payload.certificate &&
+    typeof payload.certificate === 'object' &&
+    typeof (payload.certificate as Record<string, unknown>).claims === 'string' &&
+    typeof (payload.certificate as Record<string, unknown>).signature === 'string'
+      ? {
+          claims: (payload.certificate as Record<string, string>).claims,
+          signature: (payload.certificate as Record<string, string>).signature,
+        }
+      : undefined
+
+  return {
+    success: Boolean(payload.success ?? errorReason === undefined),
+    errorReason,
+    payer:
+      typeof payload.payer === 'string'
+        ? payload.payer
+        : typeof payload.userAddress === 'string'
+          ? payload.userAddress
+          : typeof payload.user_address === 'string'
+            ? payload.user_address
+            : undefined,
+    transaction,
+    network,
+    certificate,
+    txHash:
+      typeof payload.txHash === 'string'
+        ? payload.txHash
+        : typeof payload.tx_hash === 'string'
+          ? payload.tx_hash
+          : transaction || undefined,
+    networkId:
+      typeof payload.networkId === 'string'
+        ? payload.networkId
+        : typeof payload.network_id === 'string'
+          ? payload.network_id
+          : network,
+    error: typeof payload.error === 'string' ? payload.error : undefined,
+  }
+}

package/tests/client-scheme.test.ts

@@ -0,0 +1,101 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { privateKeyToAccount } from 'viem/accounts'
+
+import { FourMicaEvmScheme } from '../src/client/scheme.js'
+
+describe('FourMicaEvmScheme', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('passes V2 resource metadata through to the SDK flow', async () => {
+    const signPaymentV2 = vi.fn().mockResolvedValue({
+      payload: {
+        claims: {
+          version: 'v2',
+          validation_request_hash: '0x' + '11'.repeat(32),
+          validation_subject_hash: '0x' + '22'.repeat(32),
+        },
+      },
+    })
+
+    vi.spyOn(FourMicaEvmScheme as never, 'createX402Flow' as never).mockResolvedValue({
+      signPayment: vi.fn(),
+      signPaymentV2,
+    } as never)
+
+    const scheme = await FourMicaEvmScheme.create(
+      privateKeyToAccount(`0x${'11'.repeat(32)}`)
+    )
+
+    const requirements = {
+      scheme: '4mica-credit',
+      network: 'eip155:11155111',
+      asset: '0x2222222222222222222222222222222222222222',
+      amount: '10',
+      payTo: '0x1111111111111111111111111111111111111111',
+      extra: {
+        rpcUrl: 'https://custom.rpc.example',
+        validationRegistryAddress: '0x3333333333333333333333333333333333333333',
+        validatorAddress: '0x4444444444444444444444444444444444444444',
+        validatorAgentId: '7',
+        minValidationScore: 80,
+        requiredValidationTag: 'hard-finality',
+        resource: {
+          url: 'https://api.example.com/premium',
+          description: 'Premium dataset',
+          mimeType: 'application/json',
+        },
+      },
+    }
+
+    const result = await scheme.createPaymentPayload(2, requirements as never)
+
+    expect(result.x402Version).toBe(2)
+    expect(signPaymentV2).toHaveBeenCalledTimes(1)
+
+    const paymentRequired = signPaymentV2.mock.calls[0]?.[0]
+    expect(paymentRequired.resource).toEqual({
+      url: 'https://api.example.com/premium',
+      description: 'Premium dataset',
+      mimeType: 'application/json',
+    })
+
+    const accepted = signPaymentV2.mock.calls[0]?.[1]
+    expect(accepted).toMatchObject({
+      scheme: '4mica-credit',
+      network: 'eip155:11155111',
+      asset: '0x2222222222222222222222222222222222222222',
+      amount: '10',
+      payTo: '0x1111111111111111111111111111111111111111',
+    })
+    expect(accepted.extra).toMatchObject({
+      validationRegistryAddress: '0x3333333333333333333333333333333333333333',
+      validatorAddress: '0x4444444444444444444444444444444444444444',
+      validatorAgentId: '7',
+      minValidationScore: 80,
+      requiredValidationTag: 'hard-finality',
+    })
+  })
+
+  it('rejects unsupported x402 versions', async () => {
+    vi.spyOn(FourMicaEvmScheme as never, 'createX402Flow' as never).mockResolvedValue({
+      signPayment: vi.fn(),
+      signPaymentV2: vi.fn(),
+    } as never)
+
+    const scheme = await FourMicaEvmScheme.create(
+      privateKeyToAccount(`0x${'11'.repeat(32)}`)
+    )
+
+    await expect(
+      scheme.createPaymentPayload(3, {
+        scheme: '4mica-credit',
+        network: 'eip155:11155111',
+        asset: '0x2222222222222222222222222222222222222222',
+        amount: '10',
+        payTo: '0x1111111111111111111111111111111111111111',
+      } as never)
+    ).rejects.toThrow('Unsupported x402Version: 3')
+  })
+})

package/tests/facilitator.test.ts

@@ -0,0 +1,174 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { FourMicaFacilitatorClient } from '../src/server/facilitator.js'
+
+describe('FourMicaFacilitatorClient', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+    vi.unstubAllGlobals()
+  })
+
+  it('normalizes 4mica settle responses and preserves certificate fields', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          success: true,
+          txHash: '0xdeadbeef',
+          networkId: 'eip155:11155111',
+          certificate: {
+            claims: '0x' + '11'.repeat(32),
+            signature: '0x' + '22'.repeat(96),
+          },
+        }),
+        {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }
+      )
+    )
+
+    vi.stubGlobal('fetch', fetchMock)
+
+    const client = new FourMicaFacilitatorClient({ url: 'https://facilitator.example' })
+
+    const result = await client.settle(
+      {
+        x402Version: 2,
+        accepted: {
+          scheme: '4mica-credit',
+          network: 'eip155:11155111',
+          asset: '0x2222222222222222222222222222222222222222',
+          amount: '10',
+          payTo: '0x1111111111111111111111111111111111111111',
+        },
+        payload: {
+          claims: {
+            version: 'v2',
+          },
+          signature: '0x1234',
+          scheme: 'eip712',
+        },
+      } as never,
+      {
+        scheme: '4mica-credit',
+        network: 'eip155:11155111',
+        asset: '0x2222222222222222222222222222222222222222',
+        amount: '10',
+        payTo: '0x1111111111111111111111111111111111111111',
+      } as never
+    )
+
+    expect(result.success).toBe(true)
+    expect(result.transaction).toBe('0xdeadbeef')
+    expect(result.network).toBe('eip155:11155111')
+    expect(result.txHash).toBe('0xdeadbeef')
+    expect(result.networkId).toBe('eip155:11155111')
+    expect(result.certificate).toEqual({
+      claims: '0x' + '11'.repeat(32),
+      signature: '0x' + '22'.repeat(96),
+    })
+
+    const request = fetchMock.mock.calls[0]?.[1]
+    expect(typeof request?.body).toBe('string')
+    expect(String(request?.body)).toContain('"x402Version":2')
+    expect(String(request?.body)).toContain('"version":"v2"')
+  })
+
+  it('normalizes alias fields when the facilitator omits txHash/networkId', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          success: true,
+          transactionHash: '0xabc123',
+          network: 'eip155:80002',
+          user_address: '0x9999999999999999999999999999999999999999',
+        }),
+        {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }
+      )
+    )
+
+    vi.stubGlobal('fetch', fetchMock)
+
+    const client = new FourMicaFacilitatorClient({ url: 'https://facilitator.example' })
+    const result = await client.settle(
+      {
+        x402Version: 2,
+        accepted: {
+          scheme: '4mica-credit',
+          network: 'eip155:80002',
+          asset: '0x2222222222222222222222222222222222222222',
+          amount: '10',
+          payTo: '0x1111111111111111111111111111111111111111',
+        },
+        payload: {
+          claims: { version: 'v2' },
+          signature: '0x1234',
+          scheme: 'eip712',
+        },
+      } as never,
+      {
+        scheme: '4mica-credit',
+        network: 'eip155:80002',
+        asset: '0x2222222222222222222222222222222222222222',
+        amount: '10',
+        payTo: '0x1111111111111111111111111111111111111111',
+      } as never
+    )
+
+    expect(result.success).toBe(true)
+    expect(result.transaction).toBe('0xabc123')
+    expect(result.txHash).toBe('0xabc123')
+    expect(result.network).toBe('eip155:80002')
+    expect(result.networkId).toBe('eip155:80002')
+    expect(result.payer).toBe('0x9999999999999999999999999999999999999999')
+  })
+
+  it('surfaces facilitator errors using normalized reasons', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          success: false,
+          error_reason: 'unsupported x402Version 2',
+        }),
+        {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }
+      )
+    )
+
+    vi.stubGlobal('fetch', fetchMock)
+
+    const client = new FourMicaFacilitatorClient({ url: 'https://facilitator.example' })
+
+    await expect(
+      client.settle(
+        {
+          x402Version: 2,
+          accepted: {
+            scheme: '4mica-credit',
+            network: 'eip155:11155111',
+            asset: '0x2222222222222222222222222222222222222222',
+            amount: '10',
+            payTo: '0x1111111111111111111111111111111111111111',
+          },
+          payload: {
+            claims: { version: 'v2' },
+            signature: '0x1234',
+            scheme: 'eip712',
+          },
+        } as never,
+        {
+          scheme: '4mica-credit',
+          network: 'eip155:11155111',
+          asset: '0x2222222222222222222222222222222222222222',
+          amount: '10',
+          payTo: '0x1111111111111111111111111111111111111111',
+        } as never
+      )
+    ).rejects.toThrow('unsupported x402Version 2')
+  })
+})