¿Qué es un paymaster?

Un paymaster es un contrato inteligente que paga el gas de la user operation de otra persona. ERC-4337 lo introdujo para que una app pueda patrocinar tarifas en el token nativo de la cadena, o dejar que un usuario pague esas tarifas con un token ERC-20 como USDC, mientras el bundler que envió la operación sigue cobrando en el token nativo.

Ese es todo el trabajo. Un usuario nuevo tiene USDC y no tiene ETH. El swap, el mint o el primer despliegue de la cuenta nunca arranca, porque la red no acepta una transacción que el emisor no puede pagar. El paymaster es el contrato que cubre esa tarifa bajo las reglas que define la app.

No es el wallet, y no es el bundler. El emisor suele ser una smart account. El bundler es el servicio offchain que empaqueta user operations en una transacción. El EntryPoint es el contrato onchain que revisa a todos, ejecuta la llamada y le paga al bundler. El paymaster es quien acepta financiar ese reembolso.

¿Qué es un paymaster?

Un paymaster es un contrato de ERC-4337 con un depósito del token de gas nativo en el EntryPoint. Cuando una user operation nombra a ese paymaster, el EntryPoint cobra la tarifa del depósito del paymaster, no del emisor.

La user operation lleva la dirección del paymaster en paymasterAndData (versiones anteriores del EntryPoint) o en los campos separados paymaster y paymasterData (EntryPoint v0.7 y posteriores). Esos datos son la forma en que el paymaster reconoce un patrocinio que ya aprobó. En el paymaster de Alchemy, esos datos son un rango de tiempo empaquetado de 32 bytes seguido de una firma de 65 bytes.

Sin un paymaster, la smart account tiene que tener ETH, o el token que la cadena use como gas, antes de poder hacer algo. Con uno, la app puede pagar, o el usuario puede pagar con un token que ya tiene.

¿Cuándo conviene usar un paymaster?

Usa un paymaster cuando la persona que hace la acción no debería tener que poseer el token de gas de la cadena.

Hay dos motivos que se mantienen.

Patrocinio. La app paga. Los usuarios nuevos terminan el onboarding, una campaña cubre las primeras acciones, o un producto oculta el gas como una fintech oculta las tarifas de la red de tarjetas. El depósito del paymaster en el EntryPoint es lo que liquida la tarifa.

Pago en ERC-20. El usuario paga con un token, a menudo una stablecoin, y el paymaster igual le liquida al bundler en el token nativo. El token no se convierte en el token de gas de la cadena. El paymaster cotiza un precio, toma los tokens y usa su propio depósito de token nativo para pagarle a la red.

Los dos pueden correr a la vez: patrocinar a algunos usuarios y dejar que otros paguen en USDC. La política decide cuál.

¿Cómo funciona un paymaster?

Un paymaster nunca envía la transacción. Lo hace el bundler. El EntryPoint es el contrato que llama al paymaster y después le paga al bundler.

Para una user operation patrocinada, la secuencia es:

1. El emisor firma una user operation que nombra a un paymaster.
2. El bundler envía un bundle a EntryPoint.handleOps.
3. El EntryPoint comprueba que el depósito del paymaster cubre el costo en el peor caso. Si el depósito es demasiado bajo, la operación falla con AA31 paymaster deposit too low.
4. El EntryPoint llama a validateUserOp en el emisor. Como paga un paymaster, no se le pide a la cuenta que deposite fondos para esta operación.
5. El EntryPoint llama a validatePaymasterUserOp en el paymaster. Si el paymaster rechaza la operación, no se ejecuta.
6. El EntryPoint ejecuta la llamada del emisor.
7. Si la validación devolvió un context no vacío, el EntryPoint llama a postOp para que el paymaster liquide, por ejemplo retirando un token ERC-20.
8. El EntryPoint le paga al bundler desde el depósito del paymaster. Si la operación no tenía paymaster, el depósito del propio emisor le paga al bundler.

¿Qué funciones debe implementar un paymaster?

La interfaz del paymaster tiene dos funciones.

validatePaymasterUserOp corre durante la validación. Recibe la user operation, su hash y el costo máximo. Devuelve un arreglo de bytes de context y un resultado de validación. Un context no vacío es la señal de que postOp debe correr después de la ejecución. Un context vacío significa que no queda nada por liquidar.

postOp corre después de la llamada, y solo si ese context no estaba vacío. Aquí es donde un paymaster ERC-20 transfiere tokens desde el emisor. También corre si la llamada revirtió, para que el paymaster pueda reaccionar al fallo. El argumento de mode le dice cuál de los dos casos es.

Las dos funciones deben rechazar a cualquier caller que no sea el EntryPoint. Un paymaster que acepta llamadas de cualquiera puede ser engañado para patrocinar operaciones que nunca aprobó.

¿Qué tipos de paymasters hay?

ERC-4337 no define dos productos oficiales. Define una interfaz. Los equipos clasifican los paymasters según quién decide pagar y según qué se le cobra al usuario.

Paymasters de verificación

Un verifying paymaster le pide a un servicio offchain que apruebe la operación y después comprueba esa aprobación onchain. La comprobación habitual es una firma sobre la user operation, a menudo atada a una ventana de tiempo para que la aprobación no se pueda repetir después.

Este es el patrón de un paymaster onchain que patrocina el gas para la app. El backend de la app, o un servicio de políticas de gas, decide que este emisor, esta llamada y este costo están permitidos. La firma es lo que el contrato confía. La política Onchain Paymaster de Alchemy funciona así. La política aprueba la user operation, y alchemy_requestGasAndPaymasterAndData devuelve la dirección del paymaster, los datos firmados y las estimaciones de gas. La política recomendada, Gas Sponsorship, no. Patrocina en el bundler y no devuelve campos de paymaster.

Un verifying paymaster también puede quedar detrás de un cargo con tarjeta o en fiat. El servicio offchain confirma el pago primero. El contrato onchain solo ve una firma que dice que la tarifa está cubierta.

Paymasters ERC-20

Un paymaster ERC-20, a veces llamado token paymaster o deposit paymaster, le cobra al usuario en un token ERC-20. El EntryPoint igual le paga al bundler en el token nativo, desde el depósito del paymaster. postOp, o en algunos diseños el paso de validación, cobra los tokens para que el depósito se pueda reponer.

El tipo de cambio tiene que quedar fijo antes de que el usuario firme. Alchemy bloquea la cotización de la Token Prices By Address API en el momento en que se firma el patrocinio, no cuando se mina la operación. Un precio que se mueve entre la firma y la inclusión cambiaría la tarifa que el usuario ya aceptó.

Hay dos formas de mover los tokens:

• Después de la ejecución, que es el modo con el que conviene empezar. La user operation puede incluir la aprobación del token, así que no hay una transacción de aprobación aparte. Si la transferencia del token falla, toda la operación revierte, pero el patrocinador sigue siendo responsable del gas que se usó. Simula primero. La simulación no es una garantía.
• Antes de la ejecución. La transferencia ocurre dentro de validatePaymasterUserOp. El paymaster ya tiene que tener allowance, de un approve anterior o de una firma permit. Si falta el allowance, la operación se rechaza. Esto cuesta más gas y agrega un paso que el usuario ve.

El depósito de token nativo del paymaster es de donde se le paga al bundler en los dos modos. Tomar USDC del usuario no elimina la necesidad de ese depósito.

¿Cómo piden los wallets los datos del paymaster?

Los wallets no deberían inventar cada uno una API privada para el patrocinio. ERC-7677 es el estándar del servicio web del paymaster. Una app pasa una URL de paymaster service. El wallet llama a dos métodos JSON-RPC en esa URL:

• pm_getPaymasterStubData devuelve campos de paymaster de relleno para que el wallet pueda estimar el gas antes de que el usuario firme.
• pm_getPaymasterData devuelve los campos finales de la user operation firmada que se va a enviar a un bundler.

El servicio tiene que detectar la versión del EntryPoint. v0.6 espera paymasterAndData. v0.7 y posteriores esperan paymaster y paymasterData.

Alchemy implementa esos métodos pm_ para una política Onchain Paymaster. alchemy_requestGasAndPaymasterAndData devuelve los campos del paymaster y las estimaciones de gas juntos. alchemy_requestPaymasterAndData es el método anterior y se está deprecando. Bundler Sponsored Operations no usan estos métodos, y no devuelven campos de paymaster.

¿EIP-7702 reemplazó a los paymasters?

No. EIP-7702 deja que una cuenta de propiedad externa delegue en código de contrato inteligente durante una transacción, o hasta que la cuenta cambie esa delegación. La cuenta puede agrupar llamadas y usar funciones de smart account sin desplegar primero un contract wallet aparte. Alguien igual tiene que pagar el gas.

Cuando ese flujo usa un paymaster onchain, quien paga sigue siendo ese paymaster, y quien envía sigue siendo un bundler. EntryPoint v0.8, desplegado en 0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108, agrega comprobaciones nativas de EIP-7702: el hash de la user operation incluye la dirección de delegación, y el EntryPoint comprueba que la delegación coincida. El ejemplo publicado de request de Gas Manager apunta al EntryPoint v0.7 en 0x0000000071727De22E5E9d8BAf0edAc6f37da032. Pasa el EntryPoint para el que está construida tu cuenta. El bundler y el EntryPoint igual tienen que entender la autorización.

EIP-7702 puso el patrocinio al alcance de las EOA que ya existen. No eliminó al paymaster de ERC-4337. La política recomendada de Alchemy, Gas Sponsorship, igual puede cubrir una EOA delegada, y ese camino deja al paymaster fuera de la user operation. Eso es una política del bundler, no un cambio del EntryPoint.

¿Cómo se limita el gas patrocinado?

Una política de patrocinio sin límites cubre lo que le pidan. La política es la lista de permitidos y denegados delante del bundler, o delante del contrato paymaster.

En Gas Manager, una política de patrocinio puede definir:

• Un gasto máximo global, en USD
• Un gasto máximo por emisor, y un gasto máximo por user operation
• Un número máximo de operaciones patrocinadas, global y por emisor
• Una allowlist de emisores y una blocklist de emisores
• Una hora de inicio y una hora de fin
• Un vencimiento del patrocinio, en milisegundos, que es cuánto tiempo sigue válida una aprobación firmada

Esas dos últimas son distintas en un paymaster onchain. Las horas de inicio y fin acotan la política. El vencimiento acota una firma del paymaster. Bundler Sponsored Operations exigen el gasto máximo por user operation, y el bundler reintenta hasta ese monto. En ese camino el vencimiento empieza cuando el bundler acepta la user operation, porque no hay firma de paymaster.

Para reglas que no son un tope de gasto, adjunta un webhook. Gas Manager llama a tu URL y usa la respuesta para permitir o denegar la operación. approveOnFailure elige qué pasa si esa llamada falla o se agota el tiempo: aprobar, si prefieres seguir disponible, o denegar, si prefieres ser estricto. El valor por defecto es denegar.

Crea la política en el dashboard, o con la Gas Manager Admin API. La misma forma existe para las reglas ERC-20, incluido qué tokens se aceptan y si el cobro ocurre después de la ejecución.

¿Cómo patrocina Alchemy el gas?

Gas Manager guarda la política. No siempre es un paymaster onchain.

El tipo de política recomendado es Gas Sponsorship, impulsado por Bundler Sponsored Operations. BSO comprueba esa política cuando el bundler recibe la user operation firmada mediante eth_sendUserOperation. La user operation no lleva campos de paymaster, y no hay un contrato paymaster que llamar. El Bundler cubre el gas y reintenta el envío hasta el gasto máximo por user operation de la política. Rundler es el bundler de código abierto que operamos.

Una política Onchain Paymaster es la otra opción en EVM. Esa sí es un verifying paymaster. Pides los campos del paymaster antes de que el usuario firme, la user operation lleva la firma del paymaster, y el EntryPoint le reembolsa al bundler desde el depósito del paymaster.

Wallet APIs quedan por encima de las dos para las apps que no deberían armar una user operation a mano. Pasa el ID de la política BSO en el smart wallet client, o en una sola llamada. El SDK patrocina esa llamada bajo la política. En el flujo de EIP-7702, wallet_prepareCalls devuelve una autorización para que el usuario firme, no una user operation, así que los campos de gas en cero de abajo no aplican ahí. El emisor es la smart account, o una EOA delegada en código de smart account. wallet_prepareCalls y wallet_sendCalls igual adjuntan el batching y la delegación de EIP-7702.

¿Cómo envías una Bundler Sponsored Operation?

Crea una política de Gas Manager con tipo Bundler Sponsored Operations y define Max Spend Per UO. Ese tope es obligatorio. El bundler reintenta hasta ese monto.

Una integración de bajo nivel envía la user operation firmada con eth_sendUserOperation. Pon el ID de la política en el header x-alchemy-policy-id, y pon maxFeePerGas, maxPriorityFeePerGas y preVerificationGas en cero. El bundler trata esos ceros como la señal para completar el gas y patrocinar la operación. No llames a alchemy_requestGasAndPaymasterAndData para esta política. Una user operation de BSO no tiene dirección de paymaster ni firma de paymaster.

La elegibilidad se decide cuando el bundler recibe la operación. Si el límite de la política ya se alcanzó, el envío falla. Después de que el bundler la acepta, la operación todavía tiene que entrar en un bundle antes del vencimiento del patrocinio. Si no entra, el bundler la descarta.

¿Cuándo usas un paymaster onchain?

Usa una política Onchain Paymaster cuando la user operation tiene que nombrar un contrato paymaster. Eso incluye los pagos de gas en ERC-20, donde el usuario paga en un token y el paymaster igual le liquida al bundler en el token nativo. Pide los campos con alchemy_requestGasAndPaymasterAndData o con los métodos pm_ de ERC-7677, y después envía por el Bundler. La política se comprueba antes de que el usuario firme. La firma del paymaster vence, así que la operación tiene que enviarse dentro de esa ventana.

¿Cuánto cuesta el gas patrocinado?

Tarifas publicadas de Gas Manager, de la Gas Manager FAQ:

• El patrocinio en testnet es gratis en todos los planes.
• El plan gratis no incluye patrocinio en mainnet.
• Pay as you go suma 8% sobre el gas de mainnet cubierto. No hay una asignación fija de mainnet hasta que compres créditos de gas o arregles un límite.
• Las tarifas y los límites de Enterprise son a medida.

El gas que cubres se suma a la factura mensual. Los créditos de gas son una compra única en USD que se aplica a esa factura y se acumula hasta que se usa. Las alertas de uso llegan a los admins de facturación al 50%, 75%, 90% y 100% del límite de patrocinio. Como el patrocinio se aprueba por lotes, una política con mucho tráfico puede gastar un poco por encima de un tope durante un momento breve.

Los pagos de gas en ERC-20 cuentan para el mismo límite. En un paymaster onchain, el depósito de token nativo sigue siendo lo que se liquida onchain. Bundler Sponsored Operations no usan ese depósito. La documentación cotiza el gas de BSO como el costo de liquidación onchain más una tarifa de servicio por los reintentos del bundler y una inclusión más rápida.

¿Qué redes admiten patrocinio de gas?

La lista de redes cambia a medida que se agregan cadenas. El soporte de Gas Manager y Bundler sigue la tabla de soporte por función. Bundler Sponsored Operations corren en cada cadena donde Alchemy ofrece patrocinio de gas, excepto MegaETH. Los tokens de gas ERC-20 se habilitan por política. La lista del dashboard no es el techo: se puede agregar un token custom por la Admin API cuando la Token Prices By Address API tiene un precio para él, o cuando defines un token de referencia con la misma cantidad de decimales.

Las direcciones de despliegue se mueven con las versiones del EntryPoint y con las redes nuevas. Usa las direcciones de la documentación de Gas Manager para la red en la que estás, en lugar de una lista copiada.

¿Hay un paymaster en Solana?

No uno de ERC-4337. Solana no tiene EntryPoint ni user operations. Gas Manager igual patrocina tarifas de Solana, mediante alchemy_requestFeePayer, que devuelve una firma de fee payer sobre la transacción más estimaciones de tarifa y de rent. El trabajo del producto es el mismo, la app paga la tarifa de la red, y el mecanismo no es un paymaster. No apuntes una transacción de Solana a validatePaymasterUserOp.

¿Cómo limitan los bundlers a un paymaster malicioso?

El storage de un paymaster lo comparten todas las operaciones de un bundle que lo usan. Un validatePaymasterUserOp hostil puede hacer fallar operaciones posteriores de ese bundle. Eso es una denegación de servicio contra el bundler, no contra un solo usuario.

ERC-4337 responde con puntuación de reputación y con throttling, y con un stake. El stake no se penaliza con slashing, y se puede retirar. Existe para que un atacante no pueda desplegar barato un paymaster nuevo en cada intento. Los bundlers también pueden banear a un paymaster que sigue invalidando otras operaciones. Las reglas están en la sección de reputación de ERC-4337.

Preguntas frecuentes

¿Qué es un paymaster en ERC-4337?

Un paymaster es un contrato inteligente que paga el gas de una user operation. Deposita el token nativo de la cadena en el EntryPoint, aprueba operaciones en validatePaymasterUserOp y le paga al bundler desde ese depósito. Puede patrocinar la tarifa por completo, o cobrar un token ERC-20 del usuario y igual liquidarle al bundler en el token nativo.

¿Cuál es la diferencia entre un paymaster y un bundler?

El bundler envía user operations y le paga a la cadena por adelantado. Un paymaster onchain decide si cubre ese costo y le reembolsa al bundler a través del EntryPoint. Una Bundler Sponsored Operation se salta el contrato paymaster. El bundler comprueba la política de Gas Manager cuando recibe la operación firmada y cubre el gas. Una app necesita la política y un bundler que acepte la operación. Necesita un contrato paymaster solo en el camino onchain, incluidos los pagos de gas en ERC-20.

¿Los usuarios pueden pagar el gas en USDC?

Sí. Un paymaster ERC-20 cotiza un precio del token, toma USDC (u otro token habilitado) de la smart account y le paga al bundler en el token de gas nativo. Prefiere el cobro después de la ejecución para que la aprobación pueda ir en la misma user operation. Si esa transferencia falla, la operación revierte y el patrocinador igual debe el gas.

¿EIP-7702 reemplazó a los paymasters?

No. EIP-7702 deja que una EOA delegue en código de contrato. Un paymaster onchain igual le paga al bundler cuando la user operation lo nombra, y EntryPoint v0.8 comprueba la delegación. La política recomendada de Alchemy, Gas Sponsorship, puede cubrir esa EOA delegada sin un paymaster en la user operation.

¿Cuánto cobra Alchemy por patrocinar gas?

Las testnets son gratis. El patrocinio en mainnet no está en el plan gratis. Pay as you go es el 8% del gas de mainnet cubierto, una vez que agregas créditos o un límite. El precio de Enterprise es a medida. Confirma la tabla vigente en la Gas Manager FAQ antes de presupuestar un lanzamiento.

¿Cómo empiezo a patrocinar gas?

Para gas patrocinado por la app, crea una política Gas Sponsorship. Esa usa Bundler Sponsored Operations. Quien integra a bajo nivel envía el ID de la política en el header x-alchemy-policy-id y pone maxFeePerGas, maxPriorityFeePerGas y preVerificationGas en cero. Quien usa Wallet APIs pasa el mismo ID de política y no arma campos de paymaster. Usa una política Onchain Paymaster, y alchemy_requestGasAndPaymasterAndData o los métodos pm_ de ERC-7677, solo cuando la user operation tiene que nombrar un paymaster, incluido el gas en ERC-20. Abre primero la guía de BSO, los tipos de política y las reglas de política.