在 Wagmi 项目中集成 Base Paymaster，实现“零 gas”交易的完整指南

关键词：Base Paymaster、无 gas 交易、Wagmi、以太坊 Layer2、NFT 铸造、前端 Web3、CDP 控制台

还在为每次交互都必须支付 gas 费头疼？借助 Base Paymaster 与 Wagmi，你的 dApp 可以把 gas 费用转嫁给赞助方，让用户真正实现无 gas 铸造、无 gas 转账。本文将从零开始，手把手演示如何把这套“零成本”交易框架嵌入现有 React + Wagmi 项目，覆盖环境配置、合约白名单、代码落地与常见问题答疑。

一、前期准备：开通 CDP 并获取 Paymaster 端点

访问 Coinbase Developer Platform，注册或登录。
进入控制台 → Onchain Tools → Paymaster，切换至 Configuration 标签。
选择链：
- Base（主网，正式用户）
- Base Sepolia（测试网，开发调试）。
复制 Paymaster & Bundler endpoint，形如 https://api.developer.coinbase.com/rpc/v1/base/...，写入 .env：

NEXT_PUBLIC_CDP_PAYMASTER=https://api.developer.coinbase.com/rpc/v1/base/xxxxxxxx

⚠️ 生产环境务必通过自建代理隐藏真实 URL，以免被滥用。

下滑至 Contract allowlist，填写：
- 合约地址 – 你的 NFT、Token 或 DeFi 合约
- 函数名称/选择器 – 如 mint(address,uint256)
- 备注（方便自己识别）

保存后即完成白名单设置，任何未列出的函数都将拒绝赞助 gas。

二、为 Wagmi 引入 Base 网络

在项目的 wagmi.ts（或 wagmi.config.ts）中添加：

import { http, cookieStorage, createConfig, createStorage } from 'wagmi';
import { base } from 'wagmi/chains';
import { coinbaseWallet, injected, walletConnect } from 'wagmi/connectors';

export function getConfig() {
  return createConfig({
    chains: [base],
    connectors: [
      injected(),
      coinbaseWallet(),
      walletConnect({ projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID! }),
    ],
    storage: createStorage({ storage: cookieStorage }),
    ssr: true,
    transports: {
      [base.id]: http(),
    },
  });
}

declare module 'wagmi' {
  interface Register {
    config: ReturnType<typeof getConfig>;
  }
}

此时，钱包将直连 Base 主网，无需用户手动切换网络。

三、使用 Wagmi 的实验性 Hooks：无 gas 交易核心

Wagmi 提供了 两条关键的实验性 Hooks：

钩子名称	作用说明
useCapabilities	查询当前账户是否支持 paymasterService
useWriteContracts	发起无 gas 调用（batch 或 single）

3.1 组件结构示例：`mint/page.tsx`

'use client';
import { useState, useMemo } from 'react';
import { useAccount, useConnect, useDisconnect } from 'wagmi';
import { useCapabilities, useWriteContracts } from 'wagmi/experimental';
import { coinbaseWallet } from 'wagmi/connectors';
import { abi, contractAddress } from '../utils';

export default function MintPage() {
  const { address, isConnected } = useAccount();
  const { connect } = useConnect();
  const { disconnect } = useDisconnect();
  const [isMinting, setIsMinting] = useState(false);

  // 查询钱包能力
  const { data: caps } = useCapabilities({ account: address });

  // 计算可用 Paymaster URL
  const capabilities = useMemo(() => {
    if (!caps || !address) return {};
    const chainCaps = caps[address.chainId];
    if (chainCaps?.paymasterService?.supported) {
      return {
        paymasterService: { url: process.env.NEXT_PUBLIC_CDP_PAYMASTER! },
      };
    }
    return {};
  }, [caps, address]);

  // 写入合约
  const { writeContracts } = useWriteContracts({
    mutation: { onSuccess: () => console.log('零 gas 铸造成功') },
  });

  const handleMint = async () => {
    setIsMinting(true);
    try {
      await writeContracts({
        contracts: [
          {
            address: contractAddress,
            abi,
            functionName: 'mintTo',
            args: [address],
          },
        ],
        capabilities,
      });
    } catch (e) {
      console.error('铸造失败:', e);
    } finally {
      setIsMinting(false);
    }
  };

  return (
    <main>
      <p>{isConnected ? `连接地址：${address}` : '请连接钱包'}</p>
      <button
        disabled={isMinting}
        onClick={() =>
          isConnected ? handleMint() : connect({ connector: coinbaseWallet() })
        }
      >
        {isMinting ? '铸造中...' : isConnected ? '免费铸造 NFT' : '连接钱包'}
      </button>
      {isConnected && <button onClick={() => disconnect()}>断开连接</button>}
    </main>
  );
}

3.2 项目目录简化示例

app/
 ├─ mint/
 │   └─ page.tsx          # 当前文件
 ├─ utils/
 │   ├─ abi.ts            # NFT 合约 ABI
 │   └─ contract.ts       # 合约地址常量

确保 abi.ts、contract.ts 与 CDP 白名单里的地址和函数一致，否则 Paymaster 会拒绝交易。

四、进阶场景：多合约、多网络、一体化 UI

批量铸造 – 通过 writeContracts 的数组连续调用多个函数，实现「一键空投」。
动态链切换 – 若需同时支持 Base 与 Base Sepolia，可把 chains: [base] 替换为 [base, baseSepolia]，并结合 query param 动态切换 Paymaster 端点。
气体补贴上限 – 控制台可限制单笔交易或每日总额，超出部分用户自费，避免滥用。

👉 想让用户“一点即可”，一键体验无 gas 铸造？这里有更极简的部署示例。

五、答疑环节

Q1：测试网没 Base Sepolia，直接使用 Sepolia 行吗？
A：不行，Base Paymaster 仅服务于 Base 系链，请切回 Base Sepolia 水龙头领取测试代币。

Q2：前端报“paymaster not allowed for domain XXX”怎么办？
A：在 CDP 的 Whitelisted Domains 添加你的网站源；本地开发就写 localhost:3000。

Q3：如何防止过度补贴导致的 Economical Attack？
A：管理员可在 Paymaster 控制台设置 每日上限、单地址上限 并开启 IP 速率限制。

Q4：ERC-721 的 mint(address) 与 mint(address,uint256) 能同时添加吗？
A：可以，两条函数都在白名单即可，但建议统一接口减少混淆。

Q5：用户用 MetaMask 而非 Coinbase Wallet，插槽会 fallback 吗？
A：MetaMask 通过 WalletConnect 的方式也能直连 Base，但能否享受 Paymaster 赞助 取决于钱包自身是否支持 ERC-4337；不支持时用户自付 gas。

六、典型错误与修复速查表

报错信息	可能原因	解决方案
paymaster call reverted	合约/函数未加入白名单	CDP → 添加地址 + 函数选择器
transaction underpriced	补贴限额被消耗完	提高限额或请求新配额
invalid paymasterService capability	钱包不支持 ERC-4337	提醒用户切换支持的钱包版本
ERR_EMPTY_RESPONSE	代理被禁用或网络超时	检查 `.env` URL，本地用 HTTPS

七、部署 checklist

[ ] .env 中已配置正式 CDN 代理地址（非裸写 CDP 域名）
[ ] CDP 控制台的白名单涵盖所有路径函数 + 合约地址
[ ] 前端实时监听 useCapabilities，拿到 paymasterService.supported = true
[ ] 打包时关闭 NEXT_PUBLIC_CDP_PAYMASTER 的源映射，避免泄露 secret

一键部署成功后，用户即可实现 真正的零 gas 体验！

👉 紧跟最新打法，查看更多去中心化前端性能优化技巧。