O que é um paymaster?

Um paymaster é um smart contract que paga o gas da user operation de outra pessoa. O ERC-4337 o introduziu para que um app possa patrocinar taxas no token nativo da chain, ou deixar um usuário pagar essas taxas com um token ERC-20 como USDC, enquanto o bundler que enviou a operação continua sendo reembolsado no token nativo.

Esse é o trabalho inteiro. Um usuário novo tem USDC e não tem ETH. O swap, o mint ou o primeiro deploy da account nunca começa, porque a rede não aceita uma transação que o sender não consegue pagar. O paymaster é o contrato que cobre essa taxa sob as regras que o app define.

Ele não é a wallet, e não é o bundler. O sender costuma ser uma smart account. O bundler é o serviço offchain que empacota user operations em uma transação. O EntryPoint é o contrato onchain que confere todo mundo, executa a call e reembolsa o bundler. O paymaster é quem aceita financiar esse reembolso.

O que é um paymaster?

Um paymaster é um contrato do ERC-4337 com um depósito do token de gas nativo no EntryPoint. Quando uma user operation nomeia esse paymaster, o EntryPoint tira a taxa do depósito do paymaster, e não do sender.

A user operation carrega o endereço do paymaster em paymasterAndData (versões anteriores do EntryPoint) ou nos campos separados paymaster e paymasterData (EntryPoint v0.7 e posteriores). Esses dados são como o paymaster reconhece um patrocínio que já aprovou. No paymaster da Alchemy, esses dados são um intervalo de tempo empacotado de 32 bytes seguido de uma assinatura de 65 bytes.

Sem um paymaster, a smart account precisa ter ETH, ou o que a chain usar como gas, antes de fazer qualquer coisa. Com um, o app pode pagar, ou o usuário pode pagar com um token que já tem.

Quando usar um paymaster?

Use um paymaster quando a pessoa que faz a ação não deveria precisar ter o token de gas da chain.

Há dois motivos que permanecem.

Patrocínio. O app paga. Usuários novos concluem o onboarding, uma campanha cobre as primeiras ações, ou um produto esconde o gas do jeito que uma fintech esconde as taxas da rede de cartões. O depósito do paymaster no EntryPoint liquida a taxa.

Pagamento em ERC-20. O usuário paga com um token, muitas vezes uma stablecoin, e o paymaster ainda liquida o bundler no token nativo. O token não vira o token de gas da chain. O paymaster cotiza um preço, toma os tokens e usa o próprio depósito de token nativo para pagar a rede.

Os dois podem rodar ao mesmo tempo: patrocinar alguns usuários e deixar outros pagarem em USDC. A policy decide qual.

Como um paymaster funciona?

Um paymaster nunca envia a transação. O bundler envia. O EntryPoint é o contrato que chama o paymaster e depois paga o bundler de volta.

Para uma user operation patrocinada, a sequência é:

1. O sender assina uma user operation que nomeia um paymaster.
2. O bundler envia um bundle para EntryPoint.handleOps.
3. O EntryPoint confere se o depósito do paymaster cobre o custo no pior caso. Se o depósito for baixo demais, a operação falha com AA31 paymaster deposit too low.
4. O EntryPoint chama validateUserOp no sender. Como um paymaster está pagando, a account não é obrigada a depositar fundos para esta operação.
5. O EntryPoint chama validatePaymasterUserOp no paymaster. Se o paymaster rejeitar a operação, ela não roda.
6. O EntryPoint executa a call do sender.
7. Se a validação devolveu um context não vazio, o EntryPoint chama postOp para o paymaster liquidar, por exemplo puxando um token ERC-20.
8. O EntryPoint paga o bundler a partir do depósito do paymaster. Se a operação não tinha paymaster, o depósito do próprio sender paga o bundler.

Quais funções um paymaster precisa implementar?

A interface do paymaster tem duas funções.

validatePaymasterUserOp roda durante a validação. Ela recebe a user operation, o hash e o custo máximo. Devolve um array de bytes de context e um resultado de validação. Um context não vazio é o sinal de que postOp deve rodar depois da execução. Um context vazio significa que não resta nada para liquidar.

postOp roda depois da call, e só se aquele context não estava vazio. É aqui que um paymaster ERC-20 transfere tokens a partir do sender. Ela também roda se a call reverteu, para o paymaster poder reagir à falha. O argumento de mode diz qual dos casos é este.

As duas funções precisam rejeitar qualquer caller que não seja o EntryPoint. Um paymaster que aceita chamadas de qualquer lugar pode ser induzido a patrocinar operações que nunca aprovou.

Que tipos de paymaster existem?

O ERC-4337 não define dois produtos oficiais. Define uma interface. Os times separam os paymasters por quem decide pagar e pelo que é cobrado do usuário.

Verifying paymasters

Um verifying paymaster pede a um serviço offchain que aprove a operação e depois confere essa aprovação onchain. A checagem usual é uma assinatura sobre a user operation, muitas vezes presa a uma janela de tempo para a aprovação não poder ser repetida depois.

Esse é o padrão de um paymaster onchain que patrocina o gas para o app. O backend do app, ou um serviço de policy de gas, decide que este sender, esta call e este custo são permitidos. A assinatura é o que o contrato confia. A policy Onchain Paymaster da Alchemy funciona assim. A policy aprova a user operation, e alchemy_requestGasAndPaymasterAndData devolve o endereço do paymaster, os dados assinados e as estimativas de gas. A policy recomendada, Gas Sponsorship, não. Ela patrocina no bundler e não devolve campos de paymaster.

Um verifying paymaster também pode ficar atrás de uma cobrança no cartão ou em fiat. O serviço offchain confirma o pagamento primeiro. O contrato onchain só vê uma assinatura que diz que a taxa está coberta.

Paymasters ERC-20

Um paymaster ERC-20, às vezes chamado de token paymaster ou deposit paymaster, cobra o usuário em um token ERC-20. O EntryPoint ainda paga o bundler no token nativo, a partir do depósito do paymaster. O postOp, ou em alguns desenhos o passo de validação, coleta os tokens para o depósito poder ser reposto.

A taxa de câmbio tem que estar fixa antes de o usuário assinar. A Alchemy trava a cotação da Token Prices By Address API no momento em que o patrocínio é assinado, não quando a operação é minerada. Um preço que se move entre a assinatura e a inclusão mudaria a taxa que o usuário já aceitou.

Há duas formas de mover os tokens:

• Depois da execução, que é o modo para começar. A user operation pode incluir a aprovação do token, então não há uma transação de aprovação separada. Se a transferência do token falhar, a operação inteira reverte, mas o patrocinador continua responsável pelo gas que foi usado. Simule antes. A simulação não é uma garantia.
• Antes da execução. A transferência acontece dentro de validatePaymasterUserOp. O paymaster já precisa ter allowance, de um approve anterior ou de uma assinatura permit. Se o allowance faltar, a operação é rejeitada. Isso custa mais gas e adiciona um passo que o usuário vê.

O depósito de token nativo do paymaster é de onde o bundler é pago nos dois modos. Tirar USDC do usuário não elimina a necessidade desse depósito.

Como as wallets pedem dados do paymaster?

As wallets não deveriam inventar cada uma uma API privada de patrocínio. O ERC-7677 é o padrão de web service do paymaster. Um app passa uma URL de paymaster service. A wallet chama dois métodos JSON-RPC nessa URL:

• pm_getPaymasterStubData devolve campos de paymaster de preenchimento para a wallet estimar o gas antes de o usuário assinar.
• pm_getPaymasterData devolve os campos finais da user operation assinada que será enviada a um bundler.

O serviço precisa detectar a versão do EntryPoint. A v0.6 espera paymasterAndData. A v0.7 e as posteriores esperam paymaster e paymasterData.

A Alchemy implementa esses métodos pm_ para uma policy Onchain Paymaster. alchemy_requestGasAndPaymasterAndData devolve os campos do paymaster e as estimativas de gas juntos. alchemy_requestPaymasterAndData é o método antigo e está sendo descontinuado. Bundler Sponsored Operations não usam esses métodos e não devolvem campos de paymaster.

O EIP-7702 substituiu os paymasters?

Não. O EIP-7702 deixa uma externally owned account delegar para código de smart contract durante uma transação, ou até a account mudar essa delegação. A account pode agrupar calls e usar recursos de smart account sem fazer o deploy de uma contract wallet separada antes. Alguém ainda precisa pagar o gas.

Quando esse fluxo usa um paymaster onchain, quem paga continua sendo esse paymaster, e quem envia continua sendo um bundler. O EntryPoint v0.8, implantado em 0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108, adiciona checagens nativas de EIP-7702: o hash da user operation inclui o endereço de delegação, e o EntryPoint confere se a delegação bate. O exemplo publicado de request do Gas Manager aponta para o EntryPoint v0.7 em 0x0000000071727De22E5E9d8BAf0edAc6f37da032. Passe o EntryPoint para o qual a sua account foi construída. O bundler e o EntryPoint ainda precisam entender a autorização.

O EIP-7702 tornou o patrocínio disponível para EOAs que já existem. Não removeu o paymaster do ERC-4337. A policy recomendada da Alchemy, Gas Sponsorship, ainda pode cobrir uma EOA delegada, e esse caminho deixa o paymaster fora da user operation. Isso é uma policy do bundler, não uma mudança no EntryPoint.

Como limitar o gas patrocinado?

Uma policy de patrocínio sem limites cobre o que pedirem. A policy é a lista de permitidos e negados na frente do bundler, ou na frente do contrato paymaster.

No Gas Manager, uma policy de patrocínio pode definir:

• Um gasto máximo global, em USD
• Um gasto máximo por sender, e um gasto máximo por user operation
• Um número máximo de operações patrocinadas, global e por sender
• Uma allowlist de senders e uma blocklist de senders
• Um horário de início e um horário de fim
• Um vencimento do patrocínio, em milissegundos, que é por quanto tempo uma aprovação assinada continua válida

Esses dois últimos são diferentes num paymaster onchain. Os horários de início e fim delimitam a policy. O vencimento delimita uma assinatura do paymaster. Bundler Sponsored Operations exigem o gasto máximo por user operation, e o bundler tenta de novo até esse valor. Nesse caminho o vencimento começa quando o bundler aceita a user operation, porque não há assinatura de paymaster.

Para regras que não são um teto de gasto, anexe um webhook. O Gas Manager chama a sua URL e usa a resposta para permitir ou negar a operação. approveOnFailure escolhe o que acontece se essa chamada falhar ou estourar o tempo: aprovar, se você prefere continuar no ar, ou negar, se você prefere ser estrito. O padrão é negar.

Crie a policy no dashboard, ou com a Gas Manager Admin API. A mesma forma existe para regras ERC-20, inclusive quais tokens são aceitos e se a cobrança acontece depois da execução.

Como a Alchemy patrocina gas?

O Gas Manager guarda a policy. Nem sempre é um paymaster onchain.

O tipo de policy recomendado é Gas Sponsorship, sustentado por Bundler Sponsored Operations. O BSO confere essa policy quando o bundler recebe a user operation assinada por eth_sendUserOperation. A user operation não carrega campos de paymaster, e não há um contrato paymaster para chamar. O Bundler cobre o gas e tenta o envio de novo até o gasto máximo por user operation da policy. O Rundler é o bundler open source que operamos.

Uma policy Onchain Paymaster é a outra escolha na EVM. Essa é um verifying paymaster. Você pede os campos do paymaster antes de o usuário assinar, a user operation carrega a assinatura do paymaster, e o EntryPoint reembolsa o bundler a partir do depósito do paymaster.

As Wallet APIs ficam acima das duas para apps que não deveriam montar uma user operation na mão. Passe o ID da policy BSO no smart wallet client, ou numa única call. O SDK patrocina essa call sob a policy. No fluxo de EIP-7702, wallet_prepareCalls devolve uma autorização para o usuário assinar, não uma user operation, então os campos de gas zerados abaixo não se aplicam ali. O sender é a smart account, ou uma EOA delegada para código de smart account. wallet_prepareCalls e wallet_sendCalls ainda anexam batching e a delegação de EIP-7702.

Como você envia uma Bundler Sponsored Operation?

Crie uma policy do Gas Manager com o tipo Bundler Sponsored Operations e defina Max Spend Per UO. Esse teto é obrigatório. O bundler tenta de novo até esse valor.

Uma integração de baixo nível envia a user operation assinada com eth_sendUserOperation. Coloque o ID da policy no header x-alchemy-policy-id, e zere maxFeePerGas, maxPriorityFeePerGas e preVerificationGas. O bundler trata esses zeros como o sinal para preencher o gas e patrocinar a operação. Não chame alchemy_requestGasAndPaymasterAndData para essa policy. Uma user operation de BSO não tem endereço de paymaster nem assinatura de paymaster.

A elegibilidade é decidida quando o bundler recebe a operação. Se o limite da policy já foi atingido, o envio falha. Depois que o bundler aceita, a operação ainda precisa entrar num bundle antes do vencimento do patrocínio. Se não entrar, o bundler a descarta.

Quando você usa um paymaster onchain?

Use uma policy Onchain Paymaster quando a user operation precisa nomear um contrato paymaster. Isso inclui pagamentos de gas em ERC-20, em que o usuário paga com um token e o paymaster ainda liquida o bundler no token nativo. Peça os campos com alchemy_requestGasAndPaymasterAndData ou com os métodos pm_ do ERC-7677, e depois envie pelo Bundler. A policy é conferida antes de o usuário assinar. A assinatura do paymaster vence, então a operação precisa ser enviada dentro dessa janela.

Quanto custa o gas patrocinado?

Taxas publicadas do Gas Manager, da Gas Manager FAQ:

• Patrocínio em testnet é grátis em todos os planos.
• O plano gratuito não inclui patrocínio em mainnet.
• Pay as you go adiciona 8% sobre o gas de mainnet coberto. Não há uma franquia fixa de mainnet até você comprar créditos de gas ou combinar um limite.
• Taxas e limites Enterprise são sob medida.

O gas que você cobre entra na fatura mensal. Créditos de gas são uma compra única em USD que se aplica a essa fatura e acumula até ser usada. Alertas de uso vão para os admins de billing em 50%, 75%, 90% e 100% do limite de patrocínio. Como o patrocínio é aprovado em lotes, uma policy movimentada pode gastar um pouco além de um teto por um instante.

Pagamentos de gas em ERC-20 contam para o mesmo limite. Num paymaster onchain, o depósito de token nativo continua sendo o que liquida onchain. Bundler Sponsored Operations não usam esse depósito. A documentação precifica o gas de BSO como o custo de liquidação onchain mais uma taxa de serviço pelas novas tentativas do bundler e por uma inclusão mais rápida.

Quais redes aceitam patrocínio de gas?

A lista de redes muda conforme chains são adicionadas. O suporte de Gas Manager e Bundler segue a tabela de suporte por recurso. Bundler Sponsored Operations rodam em toda chain em que a Alchemy oferece patrocínio de gas, exceto MegaETH. Tokens de gas ERC-20 são habilitados por policy. A lista do dashboard não é o teto: um token custom pode ser adicionado pela Admin API quando a Token Prices By Address API tem um preço para ele, ou quando você define um token de referência com o mesmo número de decimais.

Endereços de deploy mudam com as versões do EntryPoint e com redes novas. Use os endereços da documentação do Gas Manager para a rede em que você está, em vez de uma lista copiada.

Existe um paymaster na Solana?

Não um do ERC-4337. Solana não tem EntryPoint nem user operations. O Gas Manager ainda patrocina taxas da Solana, por alchemy_requestFeePayer, que devolve uma assinatura de fee payer na transação mais estimativas de taxa e de rent. O trabalho do produto é o mesmo, o app paga a taxa da rede, e o mecanismo não é um paymaster. Não aponte uma transação da Solana para validatePaymasterUserOp.

Como os bundlers limitam um paymaster malicioso?

O storage de um paymaster é compartilhado por toda operação de um bundle que o usa. Um validatePaymasterUserOp hostil pode fazer operações posteriores daquele bundle falharem. Isso é uma negação de serviço contra o bundler, não contra um único usuário.

O ERC-4337 responde com pontuação de reputação e throttling, e com um stake. O stake não sofre slashing, e pode ser retirado. Ele existe para um atacante não conseguir fazer o deploy barato de um paymaster novo a cada tentativa. Bundlers também podem banir um paymaster que continua invalidando outras operações. As regras estão na seção de reputação do ERC-4337.

Perguntas frequentes

O que é um paymaster no ERC-4337?

Um paymaster é um smart contract que paga o gas de uma user operation. Ele deposita o token nativo da chain no EntryPoint, aprova operações em validatePaymasterUserOp e reembolsa o bundler a partir desse depósito. Pode patrocinar a taxa por completo, ou cobrar um token ERC-20 do usuário e ainda liquidar o bundler no token nativo.

Qual é a diferença entre um paymaster e um bundler?

O bundler envia user operations e paga a chain adiantado. Um paymaster onchain decide se cobre esse custo e reembolsa o bundler pelo EntryPoint. Uma Bundler Sponsored Operation pula o contrato paymaster. O bundler confere a policy do Gas Manager quando recebe a operação assinada e cobre o gas. Um app precisa da policy e de um bundler que aceite a operação. Precisa de um contrato paymaster só no caminho onchain, inclusive nos pagamentos de gas em ERC-20.

Usuários podem pagar gas em USDC?

Sim. Um paymaster ERC-20 cotiza um preço do token, tira USDC (ou outro token habilitado) da smart account e paga o bundler no token de gas nativo. Prefira a cobrança depois da execução para a aprovação poder ir na mesma user operation. Se essa transferência falhar, a operação reverte e o patrocinador ainda deve o gas.

O EIP-7702 substituiu os paymasters?

Não. O EIP-7702 deixa uma EOA delegar para código de contrato. Um paymaster onchain ainda financia o bundler quando a user operation o nomeia, e o EntryPoint v0.8 confere a delegação. A policy recomendada da Alchemy, Gas Sponsorship, pode cobrir essa EOA delegada sem um paymaster na user operation.

Quanto a Alchemy cobra para patrocinar gas?

Testnets são grátis. Patrocínio em mainnet não está no plano gratuito. Pay as you go é 8% do gas de mainnet coberto, depois que você adiciona créditos ou um limite. O preço Enterprise é sob medida. Confirme a tabela atual na Gas Manager FAQ antes de orçar um lançamento.

Como começo a patrocinar gas?

Para gas patrocinado pelo app, crie uma policy Gas Sponsorship. Ela usa Bundler Sponsored Operations. Quem integra em baixo nível envia o ID da policy no header x-alchemy-policy-id e zera maxFeePerGas, maxPriorityFeePerGas e preVerificationGas. Quem usa Wallet APIs passa o mesmo ID de policy e não monta campos de paymaster. Use uma policy Onchain Paymaster, e alchemy_requestGasAndPaymasterAndData ou os métodos pm_ do ERC-7677, só quando a user operation precisa nomear um paymaster, inclusive no gas em ERC-20. Abra primeiro o guia de BSO, os tipos de policy e as regras de policy.