feat(x402): USDC UserOp sponsorship quote and precharge paymaster (#14)

Add POST /api/sponsor-userop at $0.10 USDC. Worker never signs or broadcasts; EntryPoint deposit cap defaults to 0.05 ETH. WQFLOPPaymaster precharges in validation to close the approve-then-revoke drain.

Author: igor-holt

gc-workers/x402-paid-service/bazaar-listing.json

@@ -1,6 +1,6 @@
 {
   "name": "Yennefer x402 Paid Service — Tiered (Genesis Conductor)",
-  "description": "Tiered x402 paid API on Base + Polygon mainnet. Six tiers from $0.01 discovery calls to $9,999 agent-to-agent source-exclusive checkout. USDC settlement via the Coinbase CDP facilitator (production-grade, EIP-3009). Agent-native: pay-per-call, no accounts or API keys. Covers generic execution, premium API access, AI inference, specialized data, licensing, and plugin fulfillment.",
+  "description": "Tiered x402 paid API on Base + Polygon mainnet. Seven tiers from $0.01 discovery calls to $9,999 agent-to-agent source-exclusive checkout, plus $0.10 ERC-4337 UserOp sponsorship quotes. USDC settlement via the Coinbase CDP facilitator (production-grade, EIP-3009). Agent-native: pay-per-call, no accounts or API keys. Covers generic execution, premium API access, AI inference, specialized data, licensing, plugin fulfillment, and gas sponsorship quotes.",
   "version": "2.1",
   "url": "https://x402-paid-service.iholt.workers.dev",
   "provider": "Genesis Conductor / Yennefer",
@@ -80,6 +80,35 @@
         "tier": "discovery"
       }
     },
+    {
+      "tier": "sponsor-userop",
+      "path": "/api/sponsor-userop",
+      "method": "POST",
+      "networks": [
+        "eip155:8453"
+      ],
+      "price": {
+        "amount": "100000",
+        "currency": "USDC",
+        "decimals": 6,
+        "displayPrice": "$0.10"
+      },
+      "network": "eip155:8453",
+      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+      "payTo": "0x60C4499870f115664d7FfD8411b023DBEf3377d9",
+      "description": "ERC-4337 v0.6 UserOp sponsorship quote. Worker never signs or broadcasts; EntryPoint deposit cap default 0.05 ETH.",
+      "keywords": [
+        "paymaster",
+        "erc-4337",
+        "userop",
+        "gas sponsorship",
+        "account abstraction"
+      ],
+      "useCases": [
+        "quote UserOp sponsorship after USDC settlement",
+        "agent gas market on Base"
+      ]
+    },
     {
       "tier": "pro",
       "path": "/api/pro",

gc-workers/x402-paid-service/contracts/wQFLOPPaymaster.sol

@@ -0,0 +1,147 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.32;
+
+/// ERC-4337 v0.6 UserOperation. Not PackedUserOperation (v0.7).
+struct UserOperation {
+    address sender;
+    uint256 nonce;
+    bytes initCode;
+    bytes callData;
+    uint256 callGasLimit;
+    uint256 verificationGasLimit;
+    uint256 preVerificationGas;
+    uint256 maxFeePerGas;
+    uint256 maxPriorityFeePerGas;
+    bytes paymasterAndData;
+    bytes signature;
+}
+
+interface IEntryPoint {
+    function depositTo(address) external payable;
+    function balanceOf(address) external view returns (uint256);
+    function withdrawTo(address payable, uint256) external;
+}
+
+interface IWQFLOP {
+    function transferFrom(address, address, uint256) external returns (bool);
+    function transfer(address, uint256) external returns (bool);
+    function balanceOf(address) external view returns (uint256);
+    function allowance(address, address) external view returns (uint256);
+}
+
+/// wQFLOP ERC-4337 v0.6 paymaster.
+/// Tokens are pulled in validation (precharge) and excess is refunded in postOp.
+/// This closes the approve-then-revoke drain: callData cannot un-pull funds
+/// after validatePaymasterUserOp has already transferFrom'd the max.
+///
+/// postOpMode: 0 opSucceeded, 1 opReverted, 2 postOpReverted.
+/// Mode 2 must not revert (EntryPoint would otherwise retry forever).
+contract WQFLOPPaymaster {
+    IEntryPoint public immutable entryPoint;
+    IWQFLOP public immutable wqflop;
+    address public immutable owner;
+
+    uint256 public rate;
+    uint256 public constant SLIPPAGE_BPS = 300;
+    uint256 public constant MIN_RATE = 1e12;
+
+    event Deposit(address indexed from, uint256 amount);
+    event RateUpdated(uint256 oldRate, uint256 newRate);
+    event WQFLOPCollected(address indexed user, uint256 amount, uint256 gasCost);
+    event WQFLOPRefunded(address indexed user, uint256 amount);
+    event WQFLOPWithdrawn(address indexed to, uint256 amount);
+
+    modifier onlyOwner() {
+        require(msg.sender == owner, "WQFP: not owner");
+        _;
+    }
+
+    constructor(IEntryPoint _entryPoint, IWQFLOP _wqflop, uint256 _initialRate) {
+        require(_initialRate >= MIN_RATE, "WQFP: rate too low");
+        entryPoint = _entryPoint;
+        wqflop = _wqflop;
+        owner = msg.sender;
+        rate = _initialRate;
+        emit RateUpdated(0, _initialRate);
+    }
+
+    receive() external payable {
+        entryPoint.depositTo{value: msg.value}(address(this));
+        emit Deposit(msg.sender, msg.value);
+    }
+
+    function deposit() external payable {
+        entryPoint.depositTo{value: msg.value}(address(this));
+        emit Deposit(msg.sender, msg.value);
+    }
+
+    function setRate(uint256 _rate) external onlyOwner {
+        require(_rate >= MIN_RATE, "WQFP: rate too low");
+        emit RateUpdated(rate, _rate);
+        rate = _rate;
+    }
+
+    function withdrawETH(address payable to, uint256 amount) external onlyOwner {
+        entryPoint.withdrawTo(to, amount);
+    }
+
+    function withdrawWQFLOP(address to, uint256 amount) external onlyOwner {
+        uint256 bal = wqflop.balanceOf(address(this));
+        uint256 wAmount = amount == 0 ? bal : amount;
+        require(wqflop.transfer(to, wAmount), "WQFP: transfer failed");
+        emit WQFLOPWithdrawn(to, wAmount);
+    }
+
+    function entryPointBalance() external view returns (uint256) {
+        return entryPoint.balanceOf(address(this));
+    }
+
+    function maxCharge(uint256 maxCost) public view returns (uint256) {
+        return (maxCost * rate * (10000 + SLIPPAGE_BPS)) / 1e18 / 10000 + 1;
+    }
+
+    function validatePaymasterUserOp(
+        UserOperation calldata userOp,
+        bytes32,
+        uint256 maxCost
+    ) external returns (bytes memory context, uint256 validationData) {
+        require(msg.sender == address(entryPoint), "WQFP: only entrypoint");
+        require(rate >= MIN_RATE, "WQFP: rate not set");
+
+        uint256 maxWQFLOP = maxCharge(maxCost);
+        require(wqflop.balanceOf(userOp.sender) >= maxWQFLOP, "WQFP: low balance");
+        require(
+            wqflop.transferFrom(userOp.sender, address(this), maxWQFLOP),
+            "WQFP: pull failed"
+        );
+
+        context = abi.encode(userOp.sender, maxWQFLOP, rate);
+        return (context, 0);
+    }
+
+    function postOp(uint8 mode, bytes calldata context, uint256 actualGasCost) external {
+        require(msg.sender == address(entryPoint), "WQFP: only entrypoint");
+        (address sender, uint256 maxWQFLOP, uint256 rate_) = abi.decode(
+            context, (address, uint256, uint256)
+        );
+
+        uint256 actualWQFLOP = (actualGasCost * rate_) / 1e18;
+        if (actualWQFLOP > maxWQFLOP) actualWQFLOP = maxWQFLOP;
+        uint256 refund = maxWQFLOP - actualWQFLOP;
+
+        if (refund > 0) {
+            bool ok = wqflop.transfer(sender, refund);
+            if (!ok) {
+                if (mode == 2) {
+                    emit WQFLOPRefunded(sender, 0);
+                } else {
+                    revert("WQFP: refund failed");
+                }
+            } else {
+                emit WQFLOPRefunded(sender, refund);
+            }
+        }
+
+        emit WQFLOPCollected(sender, actualWQFLOP, actualGasCost);
+    }
+}

gc-workers/x402-paid-service/src/index.test.ts

@@ -153,7 +153,7 @@ describe('x402 Worker discovery routes', () => {
     expect(health.response.status).toBe(200);
     await expect(responseJson<Record<string, unknown>>(health.response)).resolves.toMatchObject({
       status: 'ok',
-      tiers: 6,
+      tiers: 7,
       vault: VAULT,
       eth_pricing_enabled: true,
     });
@@ -177,8 +177,9 @@ describe('x402 Worker discovery routes', () => {
     const x402Body = await responseJson<{ endpoints: Array<{ path: string; shopify_url?: string }> }>(
       (await dispatch('/.well-known/x402')).response,
     );
-    expect(x402Body.endpoints).toHaveLength(6);
+    expect(x402Body.endpoints).toHaveLength(7);
     expect(x402Body.endpoints.map((endpoint) => endpoint.path)).toContain('/api/founders');
+    expect(x402Body.endpoints.map((endpoint) => endpoint.path)).toContain('/api/sponsor-userop');
     expect(x402Body.endpoints.find((endpoint) => endpoint.path === '/api/founders')).toMatchObject({
       shopify_url: 'https://shop.example/founders',
     });

gc-workers/x402-paid-service/src/index.ts

@@ -16,6 +16,7 @@ import { probeAlchemySurfaces } from './lib/alchemy/client';
 import { buildHotFundHtml } from './lib/hot-fund';
 import { isAllowedAlchemyRpcUrl, isAllowedCdpBaseRpcUrl } from './lib/rpc-allow';
 import { deliverTier } from './lib/tier-delivery';
+import { quoteSponsorship } from './lib/sponsor-userop';
 import type { SecretBindings } from './lib/secrets';
 import type {
   ExecutionContext,
@@ -104,13 +105,19 @@ interface Env {
   TIER_SPECIALIZED_USD6: string;
   TIER_FOUNDERS_USD6: string;
   TIER_SOURCE_EXCLUSIVE_USD6: string;
+  TIER_SPONSOR_USD6: string;
   // ETH pricing tiers (wei)
   TIER_DISCOVERY_ETH_WEI: string;
   TIER_PRO_ETH_WEI: string;
   TIER_INFERENCE_ETH_WEI: string;
   TIER_SPECIALIZED_ETH_WEI: string;
   TIER_FOUNDERS_ETH_WEI: string;
   TIER_SOURCE_EXCLUSIVE_ETH_WEI: string;
+  TIER_SPONSOR_ETH_WEI: string;
+  /** Optional deployed WQFLOPPaymaster on Base. Quote-only if unset. */
+  PAYMASTER_ADDRESS?: string;
+  /** Wei cap for EntryPoint deposit used in sponsorship quotes. Default 0.05 ETH. */
+  PAYMASTER_DEPOSIT_CAP_WEI?: string;
   // Solana config
   SOLANA_USDC_MINT: string;
   SOLANA_RPC_URL: string;
@@ -237,6 +244,16 @@ const TIERS: TierConfig[] = [
     shopifyUrl: (e) => e.SHOPIFY_SOURCE_EXCLUSIVE_URL,
     shopifyVariantId: (e) => e.SHOPIFY_SOURCE_EXCLUSIVE_VARIANT_ID,
   },
+  {
+    path: '/api/sponsor-userop',
+    getAmount: (e) => e.TIER_SPONSOR_USD6 || '100000',
+    getEthAmount: (e) => e.TIER_SPONSOR_ETH_WEI || '50000000000000',
+    description:
+      'ERC-4337 v0.6 UserOp sponsorship quote billed in USDC on Base. Worker never signs and never broadcasts; EntryPoint deposit is capped (default 0.05 ETH). Keywords: paymaster, erc-4337, userop, gas sponsorship, account abstraction, usdc gas.',
+    displayPrice: '$0.10',
+    asset: USDC_BASE,
+    ethAsset: 'native',
+  },
 ];
 
 // ── Solana USDC helpers ─────────────────────────────────────────────────────
@@ -852,7 +869,9 @@ async function handleTier(
   // above, so they skip delivery entirely; every other tier gets a real
   // product rather than its own description echoed back. deliverTier never
   // throws — settlement is already confirmed at this point.
-  const delivery = tier.shopifyUrl
+  const sponsor = tier.path === '/api/sponsor-userop' ? quoteSponsorship(body, env) : undefined;
+
+  const delivery = tier.shopifyUrl || sponsor
     ? null
     : await deliverTier({
         tierPath: tier.path,
@@ -887,13 +906,15 @@ async function handleTier(
         charged_eth_wei: requestedEth ? amount : '0',
         payment_asset: requestedEth ? 'ETH' : 'USDC',
         ...(delivery?.rtptpa ? { rtptpa: delivery.rtptpa } : {}),
+        ...(sponsor ? { sponsor } : {}),
       };
 
   return Response.json({
     ...result,
     payer: payerAddress,
     settlement_tx: settlementTx,
     ...(fulfillment ?? {}),
+    ...(sponsor ? { sponsor } : {}),
   });
 }
 
@@ -1006,7 +1027,7 @@ function buildLlmsTxt(hostname: string) {
 
   return `# Genesis Conductor x402 Tiered Service
 
-> Paid API using the x402 protocol on Base + Polygon. Six tiers from $0.01 to $9,999.
+> Paid API using the x402 protocol on Base + Polygon. ${TIERS.length} tiers from $0.01 to $9,999, including UserOp sponsorship ($0.10).
 
 ## Overview
 - **Networks**: Base mainnet (eip155:8453), Polygon mainnet (eip155:137)
@@ -1149,7 +1170,7 @@ export default {
   <script type="application/ld+json">{"@context":"https://schema.org","@type":"WebAPI","name":"Genesis Conductor x402 Tiered Service","url":"https://${hostname}"}</script>
 </head><body>
   <h1>Genesis Conductor x402 Tiered Service</h1>
-  <p>Six tiers of paid API access — pay <strong>USDC</strong> or <strong>ETH</strong> on Base, or <strong>USDC</strong> on Solana.</p>
+  <p>${TIERS.length} tiers of paid API access — pay <strong>USDC</strong> or <strong>ETH</strong> on Base, or <strong>USDC</strong> on Solana.</p>
   <table border="1" cellpadding="4"><thead><tr><th>Endpoint</th><th>Price</th><th>Description</th></tr></thead>
   <tbody>${tierRows}</tbody></table>
   <p>See <a href="/llms.txt">/llms.txt</a>, <a href="/.well-known/x402">/.well-known/x402</a>, or the <a href="/cashflow">internal cashflow dashboard</a>.</p>
@@ -1378,7 +1399,7 @@ export default {
         name_for_human: 'Genesis Conductor x402',
         name_for_model: 'genesis_conductor_x402',
         description_for_human: 'Six-tier paid API using USDC, ETH, and Solana USDC micropayments on Base',
-        description_for_model: 'Six tiers of paid API access ($0.01–$9,999). Supports USDC, ETH, and Solana USDC. Call /.well-known/x402 first, then retry with PAYMENT-SIGNATURE or X-SOLANA-SIGNATURE header.',
+        description_for_model: `${TIERS.length} tiers of paid API access ($0.01–$9,999, plus $0.10 UserOp sponsorship). Supports USDC, ETH, and Solana USDC. Call /.well-known/x402 first, then retry with PAYMENT-SIGNATURE or X-SOLANA-SIGNATURE header.`,
         auth: { type: 'none' },
         api: { type: 'openapi', url: `https://${hostname}/openapi.json` },
         contact_email: 'api@genesisconductor.io',

gc-workers/x402-paid-service/src/lib/sponsor-userop.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_DEPOSIT_CAP_WEI,
+  ENTRY_POINT_V06,
+  estimateMaxCostWei,
+  parseUserOp,
+  quoteSponsorship,
+} from './sponsor-userop';
+
+const validOp = {
+  sender: '0x1111111111111111111111111111111111111111',
+  nonce: '0x0',
+  initCode: '0x',
+  callData: '0x',
+  callGasLimit: '100000',
+  verificationGasLimit: '100000',
+  preVerificationGas: '50000',
+  maxFeePerGas: '1000',
+  maxPriorityFeePerGas: '100',
+  paymasterAndData: '0x',
+  signature: '0x',
+};
+
+describe('parseUserOp', () => {
+  it('accepts a v0.6 userOp', () => {
+    const r = parseUserOp({ userOp: validOp });
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.userOp.sender).toBe(validOp.sender);
+  });
+
+  it('rejects a missing sender', () => {
+    const r = parseUserOp({ ...validOp, sender: 'nope' });
+    expect(r.ok).toBe(false);
+  });
+});
+
+describe('estimateMaxCostWei', () => {
+  it('is (call+ver+pre)*maxFeePerGas', () => {
+    const r = parseUserOp(validOp);
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(estimateMaxCostWei(r.userOp)).toBe(250000n * 1000n);
+  });
+});
+
+describe('quoteSponsorship', () => {
+  it('quotes within the default 0.05 ETH cap and never signs', () => {
+    const q = quoteSponsorship({ userOp: validOp });
+    expect(q.sponsorship_status).toBe('quoted_not_broadcast');
+    expect(q.broadcast).toBe(false);
+    expect(q.worker_signs).toBe(false);
+    expect(q.network).toBe('eip155:8453');
+    expect(q.entry_point).toBe(ENTRY_POINT_V06);
+    expect(q.deposit_cap_wei).toBe(DEFAULT_DEPOSIT_CAP_WEI.toString());
+    expect(q.within_cap).toBe(true);
+  });
+
+  it('flags maxCost above the cap without broadcasting', () => {
+    const q = quoteSponsorship({
+      userOp: { ...validOp, callGasLimit: '5000000', maxFeePerGas: '100000000000' },
+    });
+    expect(q.sponsorship_status).toBe('quoted_not_broadcast');
+    expect(q.within_cap).toBe(false);
+    expect(q.broadcast).toBe(false);
+  });
+
+  it('returns invalid_userop after a paid call with a bad body (no 5xx)', () => {
+    const q = quoteSponsorship({ hello: 'world' });
+    expect(q.sponsorship_status).toBe('invalid_userop');
+    expect(q.reason).toMatch(/sender/);
+  });
+
+  it('surfaces PAYMASTER_ADDRESS when it is a real address', () => {
+    const q = quoteSponsorship(validOp, {
+      PAYMASTER_ADDRESS: '0x2222222222222222222222222222222222222222',
+    });
+    expect(q.paymaster).toBe('0x2222222222222222222222222222222222222222');
+  });
+});