什么是 paymaster？

Paymaster 是一个智能合约，为别人的 user operation 支付 gas。ERC-4337 引入它，是为了让应用可以用链的原生代币赞助费用，或让用户用 USDC 这类 ERC-20 代币支付这些费用，而提交该操作的 bundler 仍然以原生代币获得偿还。

工作就是这些。新用户持有 USDC，没有 ETH。兑换、铸造，或第一次部署账户都不会开始，因为网络不接受发送者付不起的交易。Paymaster 就是按应用设定的规则承担这笔费用的合约。

它不是钱包，也不是 bundler。发送者通常是 smart account。Bundler 是把 user operation 打包进一笔交易的链下服务。EntryPoint 是链上合约，检查各方、执行调用，并偿还 bundler。Paymaster 是同意为这笔偿还出钱的一方。

什么是 paymaster？

Paymaster 是一个 ERC-4337 合约，在 EntryPoint 上存有原生 gas 代币的押金。当一笔 user operation 指定这个 paymaster 时，EntryPoint 从 paymaster 的押金里扣费，而不是从发送者那里扣。

User operation 把 paymaster 地址放在 paymasterAndData（较旧的 EntryPoint）里，或放在分开的 paymaster 和 paymasterData 字段里（EntryPoint v0.7 及以后）。这些数据是 paymaster 识别自己已经批准的赞助的方式。在 Alchemy 的 paymaster 上，这段数据是 32 字节打包的时间范围，后面跟着 65 字节的签名。

没有 paymaster 时，smart account 在做任何事之前必须持有 ETH，或该链用作 gas 的代币。有了它，应用可以代付，用户也可以用已经持有的代币支付。

什么时候应该使用 paymaster？

当执行操作的人不该必须持有该链的 gas 代币时，使用 paymaster。

有两个长期成立的理由。

赞助。应用来付。新用户完成引导，活动承担最初的操作，或者产品像金融科技隐藏卡组织费用那样隐藏 gas。结算费用的，是 EntryPoint 上 paymaster 的押金。

ERC-20 支付。用户用一种代币支付，通常是稳定币，paymaster 仍然用原生代币向 bundler 结算。这种代币不会变成该链的 gas 代币。Paymaster 给出报价，收取代币，并用自己的原生代币押金向网络付款。

两者可以同时运行：为一部分用户赞助，让另一部分用户用 USDC 支付。由策略决定用哪一种。

Paymaster 如何工作？

Paymaster 自己从不提交交易。提交的是 bundler。EntryPoint 是调用 paymaster、再把钱还给 bundler 的合约。

一笔被赞助的 user operation 按这个顺序进行：

1. 发送者签署一笔指定了 paymaster 的 user operation。
2. Bundler 把一个 bundle 提交到 EntryPoint.handleOps。
3. EntryPoint 检查 paymaster 的押金是否覆盖该操作的最坏成本。押金过低时，操作以 AA31 paymaster deposit too low 失败。
4. EntryPoint 在发送者上调用 validateUserOp。因为由 paymaster 付款，这次操作不会要求账户存入资金。
5. EntryPoint 在 paymaster 上调用 validatePaymasterUserOp。Paymaster 拒绝时，操作不会执行。
6. EntryPoint 执行发送者的调用。
7. 如果验证返回了非空的 context，EntryPoint 调用 postOp，让 paymaster 结算，例如划走 ERC-20 代币。
8. EntryPoint 从 paymaster 的押金向 bundler 付款。如果这笔操作没有 paymaster，就由发送者自己的押金向 bundler 付款。

Paymaster 必须实现哪些函数？

Paymaster 接口有两个函数。

validatePaymasterUserOp 在验证阶段运行。它接收 user operation、其哈希和最大成本。它返回一段 context 字节和一个验证结果。非空的 context 表示执行之后应该运行 postOp。空的 context 表示没有剩余的结算。

postOp 在调用之后运行，并且只在那段 context 非空时运行。ERC-20 paymaster 在这里从发送者转出代币。调用 revert 时它也会运行，以便 paymaster 对失败作出反应。mode 参数说明这次是哪一种情况。

两个函数都必须拒绝不是 EntryPoint 的调用者。接受任意来源调用的 paymaster，可能被骗去赞助它从未批准的操作。

有哪些类型的 paymaster？

ERC-4337 没有定义两种官方产品。它定义一个接口。团队按谁决定付款、以及向用户收取什么来区分 paymaster。

验证型 paymaster

验证型 paymaster 请链下服务批准操作，再在链上检查这次批准。常见检查是对 user operation 的签名，并且经常绑定一个时间窗口，使批准之后不能重放。

这是链上 paymaster 为应用赞助 gas 的模式。应用的后端，或 gas 策略服务，决定这个发送者、这次调用和这个成本被允许。合约信任的是签名。Alchemy 的 Onchain Paymaster 策略按这个方式工作。策略批准 user operation，alchemy_requestGasAndPaymasterAndData 返回 paymaster 地址、已签名的数据和 gas 估算。推荐的 Gas Sponsorship 策略不是这样。它在 bundler 上赞助，不返回 paymaster 字段。

验证型 paymaster 也可以放在银行卡或法币扣款后面。链下服务先确认付款。链上合约只看到一个签名，表示费用已被覆盖。

ERC-20 paymaster

ERC-20 paymaster 有时也叫 token paymaster 或 deposit paymaster，向用户收取 ERC-20 代币。EntryPoint 仍然从 paymaster 的押金里，用原生代币向 bundler 付款。postOp，或在某些设计里的验证步骤，收取代币，以便补回押金。

汇率必须在用户签名之前固定。Alchemy 在赞助被签名的那一刻锁定 Token Prices By Address API 的报价，而不是在操作被打包上链时锁定。签名和被纳入之间价格变动，会改变用户已经同意的费用。

转移代币有两种方式：

• 执行之后。这是起步应使用的模式。User operation 可以包含代币授权，因此不需要单独的授权交易。如果代币转账失败，整笔操作 revert，但赞助方仍然要对已使用的 gas 负责。先做模拟。模拟不是保证。
• 执行之前。转账发生在 validatePaymasterUserOp 内部。Paymaster 必须已经有 allowance，来自更早的 approve 或 permit 签名。缺少 allowance 时，操作会被拒绝。这会消耗更多 gas，并增加用户能看见的一步。

两种模式里，付给 bundler 的都是 paymaster 的原生代币押金。从用户处收取 USDC，并不能去掉这笔押金。

钱包如何请求 paymaster 数据？

钱包不该各自发明一套私有的赞助 API。ERC-7677 是 paymaster 网络服务标准。应用传入一个 paymaster 服务 URL。钱包在这个 URL 上调用两个 JSON-RPC 方法：

• pm_getPaymasterStubData 返回占位的 paymaster 字段，让钱包在用户签名之前估算 gas。
• pm_getPaymasterData 返回将提交给 bundler 的已签名 user operation 的最终字段。

服务必须识别 EntryPoint 版本。v0.6 期望 paymasterAndData。v0.7 及以后期望 paymaster 和 paymasterData。

Alchemy 为 Onchain Paymaster 策略实现了这些 pm_ 方法。alchemy_requestGasAndPaymasterAndData 同时返回 paymaster 字段和 gas 估算。alchemy_requestPaymasterAndData 是旧方法，正在被弃用。Bundler Sponsored Operations 不使用这些方法，也不返回 paymaster 字段。

EIP-7702 取代了 paymaster 吗？

没有。EIP-7702 让外部拥有账户在一笔交易期间，或直到账户更改这次委托之前，委托给智能合约代码。账户可以批量调用并使用 smart account 的能力，而不必先部署一个单独的合约钱包。仍然得有人支付 gas。

当这条路径使用链上 paymaster 时，付款方仍然是那个 paymaster，提交方仍然是 bundler。部署在 0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108 的 EntryPoint v0.8 增加了原生的 EIP-7702 检查：user operation 哈希包含委托地址，EntryPoint 检查委托是否匹配。已发布的 Gas Manager 请求示例指向 0x0000000071727De22E5E9d8BAf0edAc6f37da032 的 EntryPoint v0.7。传入你的账户所针对的 EntryPoint。Bundler 和 EntryPoint 仍然必须理解这次授权。

EIP-7702 让现有的 EOA 也能使用赞助。它没有从 ERC-4337 去掉 paymaster。Alchemy 推荐的 Gas Sponsorship 策略仍然可以覆盖已委托的 EOA，这条路径不把 paymaster 放进 user operation。那是 bundler 策略，不是对 EntryPoint 的改动。

如何限制被赞助的 gas？

没有限制的赞助策略会覆盖任何向它提出的请求。策略是放在 bundler 前面，或放在 paymaster 合约前面的允许和拒绝名单。

在 Gas Manager 上，一条赞助策略可以设置：

• 全局最大支出，以 USD 计
• 每个发送者的最大支出，以及每笔 user operation 的最大支出
• 被赞助操作的最大次数，全局和按发送者
• 发送者 allowlist 和发送者 blocklist
• 开始时间和结束时间
• 赞助过期时间，以毫秒计，也就是一次已签名批准保持有效的时长

后两项在链上 paymaster 上不同。开始和结束时间约束策略。过期时间约束一次 paymaster 签名。Bundler Sponsored Operations 要求设置每笔 user operation 的最大支出，bundler 会重试到这个金额。这条路径没有 paymaster 签名，所以过期时间从 bundler 接受 user operation 时开始。

对于不是支出上限的规则，挂上 webhook。Gas Manager 调用你的 URL，并用响应允许或拒绝操作。approveOnFailure 选择这次调用出错或超时时怎么做：如果你更想保持可用就批准，如果你更想严格就拒绝。默认是拒绝。

在控制台创建策略，或用 Gas Manager Admin API 创建。ERC-20 规则也是同一形状，包括接受哪些代币，以及是否在执行之后收款。

Alchemy 如何赞助 gas？

Gas Manager 持有策略。它并不总是链上 paymaster。

推荐的策略类型是 Gas Sponsorship，由 Bundler Sponsored Operations 支撑。BSO 在 bundler 通过 eth_sendUserOperation 收到已签名的 user operation 时检查该策略。User operation 不携带 paymaster 字段，也没有 paymaster 合约可调用。Bundler 承担 gas，并重试提交，直到策略的每笔 user operation 最大支出。Rundler 是我们运行的开源 bundler。

Onchain Paymaster 策略是 EVM 上的另一种选择。那是验证型 paymaster。你在用户签名之前请求 paymaster 字段，user operation 携带 paymaster 签名，EntryPoint 从 paymaster 押金偿还 bundler。

Wallet APIs 位于两者之上，给那些不该手工组装 user operation 的应用使用。把 BSO 策略 ID 传给 smart wallet client，或传给单次调用。SDK 按该策略赞助这次调用。在 EIP-7702 流程里，wallet_prepareCalls 返回的是供用户签名的授权，不是 user operation，所以下面的 gas 字段置零不适用于那里。发送者是 smart account，或委托到 smart account 代码的 EOA。wallet_prepareCalls 和 wallet_sendCalls 仍然附上批处理，以及 EIP-7702 委托。

如何发送 Bundler Sponsored Operation？

创建类型为 Bundler Sponsored Operations 的 Gas Manager 策略，并设置 Max Spend Per UO。这个上限是必需的。Bundler 会重试到这个金额。

低层集成用 eth_sendUserOperation 发送已签名的 user operation。把策略 ID 放进 x-alchemy-policy-id 请求头，并把 maxFeePerGas、maxPriorityFeePerGas 和 preVerificationGas 设为 0。Bundler 把这些 0 当作填充 gas 并赞助该操作的信号。不要为这条策略调用 alchemy_requestGasAndPaymasterAndData。BSO 的 user operation 没有 paymaster 地址，也没有 paymaster 签名。

资格在 bundler 收到操作时决定。如果策略上限已经达到，发送会失败。Bundler 接受之后，操作仍须在赞助过期之前进入 bundle。如果没有，bundler 会丢弃它。

什么时候使用链上 paymaster？

当 user operation 必须指定 paymaster 合约时，使用 Onchain Paymaster 策略。这包括 ERC-20 gas 支付：用户用代币付款，paymaster 仍然用原生代币向 bundler 结算。用 alchemy_requestGasAndPaymasterAndData 或 ERC-7677 的 pm_ 方法请求字段，然后通过 Bundler 提交。策略在用户签名之前检查。Paymaster 签名会过期，所以操作必须在这个窗口内发送。

赞助 gas 要花多少钱？

Gas Manager 已公布的费用，来自 Gas Manager FAQ：

• 每个方案的测试网赞助都免费。
• 免费方案不包含主网赞助。
• 按量付费在所覆盖的主网 gas 之上加收 8%。在你购买 gas 额度或另行安排上限之前，没有固定的主网额度。
• Enterprise 的费用和上限是定制的。

你覆盖的 gas 会计入月度账单。Gas 额度是一次性的 USD 购买，计入该账单，并在用完之前结转。用量提醒会在赞助上限的 50%、75%、90% 和 100% 发给账单管理员。因为赞助按批批准，繁忙的策略可能在短时间内略微超出上限。

ERC-20 的 gas 支付计入同一上限。在链上 paymaster 上，链上结算的仍然是原生代币押金。Bundler Sponsored Operations 不使用这笔押金。文档把 BSO gas 定价为链上结算成本，加上 bundler 重试和更快打包的服务费。

哪些网络支持 gas 赞助？

网络列表会随着链的增加而变化。Gas Manager 和 Bundler 的支持以功能支持表为准。Bundler Sponsored Operations 运行在 Alchemy 提供 gas 赞助的每条链上，MegaETH 除外。ERC-20 gas 代币按策略启用。控制台列表不是上限：当 Token Prices By Address API 有该代币的价格，或你设置了小数位数相同的参考代币时，可以通过 Admin API 添加自定义代币。

部署地址会随 EntryPoint 版本和新网络变化。使用你所在网络的 Gas Manager 文档中的地址，不要使用抄来的列表。

Solana 上有 paymaster 吗？

没有 ERC-4337 的那种。Solana 没有 EntryPoint，也没有 user operation。Gas Manager 仍然赞助 Solana 费用，通过 alchemy_requestFeePayer，它返回交易上的 fee payer 签名，以及费用和 rent 估算。产品要做的事相同，应用支付网络费用，机制不是 paymaster。不要把 Solana 交易指向 validatePaymasterUserOp。

Bundler 如何限制恶意 paymaster？

Paymaster 的存储被使用它的同一个 bundle 里的每笔操作共享。一次恶意的 validatePaymasterUserOp 可以让该 bundle 中后面的操作失败。这是针对 bundler 的拒绝服务，不是针对单个用户。

ERC-4337 用声誉评分和限流，以及一笔质押来应对。这笔质押不会被罚没，也可以取出。它的存在是为了让攻击者不能为每次尝试都廉价部署一个新的 paymaster。Bundler 也可以封禁持续使其他操作失效的 paymaster。规则在 ERC-4337 的声誉一节。

常见问题

ERC-4337 中的 paymaster 是什么？

Paymaster 是为 user operation 支付 gas 的智能合约。它把链的原生代币存入 EntryPoint，在 validatePaymasterUserOp 中批准操作，并从这笔押金偿还 bundler。它可以直接赞助费用，也可以向用户收取 ERC-20 代币，同时仍然用原生代币向 bundler 结算。

Paymaster 和 bundler 有什么区别？

Bundler 提交 user operation，并先向链付款。链上 paymaster 决定是否承担这笔成本，并通过 EntryPoint 向 bundler 退款。Bundler Sponsored Operation 跳过 paymaster 合约。Bundler 在收到已签名操作时检查 Gas Manager 策略，并自己承担 gas。应用需要的是策略，以及一个愿意接受该操作的 bundler。只有链上路径才需要 paymaster 合约，包括 ERC-20 gas 支付。

用户可以用 USDC 支付 gas 吗？

可以。ERC-20 paymaster 给出代币价格，从 smart account 收取 USDC（或另一种已启用的代币），并用原生 gas 代币向 bundler 付款。优先选择执行后收款，这样授权可以放进同一笔 user operation。如果这次转账失败，操作会 revert，赞助方仍然欠这笔 gas。

EIP-7702 取代了 paymaster 吗？

没有。EIP-7702 让 EOA 委托给合约代码。当 user operation 指定链上 paymaster 时，那个 paymaster 仍然为 bundler 提供资金，EntryPoint v0.8 会检查委托。Alchemy 推荐的 Gas Sponsorship 策略可以覆盖这个已委托的 EOA，而不在 user operation 上放置 paymaster。

Alchemy 赞助 gas 收多少钱？

测试网免费。主网赞助不在免费方案里。按量付费是所覆盖主网 gas 的 8%，前提是你加上额度或上限。Enterprise 定价是定制的。在为上线做预算之前，先在 Gas Manager FAQ 确认当前表格。

如何开始赞助 gas？

应用赞助 gas 时，创建一条 Gas Sponsorship 策略。它使用 Bundler Sponsored Operations。低层调用方把策略 ID 放进 x-alchemy-policy-id 请求头，并把 maxFeePerGas、maxPriorityFeePerGas 和 preVerificationGas 设为 0。Wallet APIs 调用方传入同一个策略 ID，不组装 paymaster 字段。只有当 user operation 必须指定 paymaster 时，包括 ERC-20 gas，才使用 Onchain Paymaster 策略，以及 alchemy_requestGasAndPaymasterAndData 或 ERC-7677 的 pm_ 方法。先打开 BSO 指南、策略类型和策略规则。