在 Wagmi 项目中集成 Base Paymaster 实现免 Gas 交易

本文将详细介绍如何在已有的 Wagmi 项目中集成 Base Paymaster，为用户提供免 Gas 费的区块链交易体验。我们将从环境配置开始，逐步讲解如何添加 Base 网络支持、配置 Paymaster 服务，并最终使用 Wagmi 的实验性钩子实现链上操作。

环境准备与 CDP 账户配置

首先，您需要拥有一个 Coinbase Developer Platform（CDP）账户。如果尚未创建，请前往官网进行注册或登录现有账户。

获取 Paymaster 和 Bundler 端点

选择您希望支持免 Gas 交易的链（Base 或 Base Sepolia），并复制 Paymaster & Bundler endpoint 部分提供的 RPC URL。

将该 URL 添加到项目的 .env 文件中，命名为 NEXT_PUBLIC_CDP_PAYMASTER。对于生产环境应用，建议通过代理服务来管理此敏感信息。

合约白名单配置

在 Contract allowlist 部分，添加您希望通过 Base Paymaster 交互的智能合约地址。为每个合约命名时，请务必包含具体的函数信息及合约地址，完成后点击 Add 保存。

配置 Wagmi 支持 Base 网络

接下来，打开项目的 wagmi.ts 配置文件，添加对 Base 网络、WalletConnect 和 Coinbase Wallet 连接器的支持：

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>;
  }
}

实现 Wagmi 实验性钩子

在应用需要进行链上操作（如铸造 NFT）时，使用 Wagmi 的实验性钩子来管理钱包连接、检查 Paymaster 功能并执行链上操作：

useCapabilities：获取连接钱包支持的功能，如用于免 Gas 交易的 paymasterService
useWriteContracts：执行链上写入操作，此处用于调用 NFT 合约的 mintTo 函数

以下是一个铸造 NFT 的示例实现：

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

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

  const { writeContracts } = useWriteContracts({
    mutation: { onSuccess: () => console.log('Mint successful') },
  });

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

  const { data: availableCapabilities } = useCapabilities({
    account: address,
  });

  const capabilities = useMemo(() => {
    if (!availableCapabilities || !address) return {};
    const capabilitiesForChain = availableCapabilities[address.chainId];
    if (
      capabilitiesForChain['paymasterService'] &&
      capabilitiesForChain['paymasterService'].supported
    ) {
      return {
        paymasterService: {
          url: process.env.NEXT_PUBLIC_CDP_PAYMASTER, // 生产环境使用代理
        },
      };
    }
    return {};
  }, [availableCapabilities, address]);

  return (
    <div>
      <p>{isConnected ? `Connected wallet: ${address}` : 'No wallet connected'}</p>
      <button
        onClick={() => connect({ connector: coinbaseWallet() })}
      >
        {isMinting ? 'Minting...' : isConnected ? 'Mint NFT' : 'Connect Wallet'}
      </button>
      {isConnected && <button onClick={() => disconnect()}>Disconnect</button>}
    </div>
  );
}

按照以上步骤操作后，您已成功将 Base Paymaster 集成到 Wagmi 项目中，实现了免 Gas 的链上交互功能。👉 查看实时集成工具来验证您的配置。

常见问题

Base Paymaster 支持哪些区块链？

目前支持 Base 主网和 Base Sepolia 测试网。您可以在 CDP 控制台的配置选项卡中切换不同网络。

为什么需要配置合约白名单？

合约白名单是安全措施，确保只有经过审核的合约才能使用 Paymaster 服务。这可以防止恶意合约消耗您的 Gas 赞助额度。

如何处理生产环境的安全问题？

建议通过代理服务来管理 Paymaster 端点，避免将敏感信息直接暴露在前端代码中。同时定期监控和更新访问权限。

useCapabilities 钩子的主要作用是什么？

该钩子用于检测连接钱包是否支持 Paymaster 服务，确保在执行交易前确认免 Gas 功能可用，避免用户交易失败。

集成过程中最常见的错误是什么？

常见错误包括网络配置不正确、合约地址或 ABI 错误、以及环境变量未正确设置。请仔细检查每个步骤的配置细节。

通过本指南，您应该能够顺利在 Wagmi 项目中实现免 Gas 交易功能，为用户提供更流畅的区块链体验。