Paymasters personalizados

Los desarrolladores pueden desplegar un Paymaster compatible con EntryPoint v0.7 para pagar el Gas de las UserOperations que cumplan una política personalizada. Son responsables del contrato Paymaster, el servicio de patrocinio, los fondos, la política de firma, los controles de riesgo y la disponibilidad.

Implementaciones de referencia:

• TokenPaymaster.sol
• VerifyingPaymaster.sol
• LegacyTokenPaymaster.sol

1. API IPaymaster

interface IPaymaster {
    enum PostOpMode {
        opSucceeded,
        opReverted,
        postOpReverted
    }

    function validatePaymasterUserOp(
        PackedUserOperation calldata userOp,
        bytes32 userOpHash,
        uint256 maxCost
    ) external returns (
        bytes memory context,
        uint256 validationData
    );

    function postOp(
        PostOpMode mode,
        bytes calldata context,
        uint256 actualGasCost,
        uint256 actualUserOpFeePerGas
    ) external;
}

1.1 validatePaymasterUserOp

Parámetro	Descripción
userOp	PackedUserOperation completa que se patrocinará
userOpHash	Hash de UserOperation vinculado a EntryPoint y chainId
maxCost	Coste máximo calculado a partir de los límites y precios de Gas

Valores devueltos:

Campo	Descripción
context	Contexto enviado a postOp; bytes vacíos significan que postOp no es necesario
validationData	Validez de la firma y rango temporal

validationData del Paymaster utiliza la misma disposición que los datos de validación de la cuenta:

160 bits inferiores: 0 para válido, 1 para firma no válida
48 bits siguientes: validUntil; 0 significa sin vencimiento
48 bits superiores: validAfter

Un Paymaster no puede devolver la dirección de un agregador. Un valor distinto de 0 o 1 en los 160 bits inferiores provoca un fallo de validación.

Este método debe:

• Aceptar llamadas únicamente del EntryPoint vinculado.
• Validar paymasterData, sender, llamada de destino, límites y vencimiento.
• Revertir o devolver fallo de firma si la UserOperation incumple la política de patrocinio.
• Comprobar presupuesto y cuota dentro de maxCost.
• Cumplir las reglas ERC-7562 del Bundler sobre acceso al almacenamiento y cambios de estado.

1.2 postOp

Parámetro	Descripción
mode	Indica si la ejecución de UserOperation tuvo éxito o revirtió
context	Contexto devuelto por la fase de validación
actualGasCost	Coste de Gas real acumulado antes de llamar a postOp
actualUserOpFeePerGas	Precio de Gas real pagado por la UserOperation

Valores de PostOpMode:

Valor	Descripción
opSucceeded	La llamada de negocio de la cuenta tuvo éxito
opReverted	La llamada revirtió; el Paymaster sigue pagando el Gas
postOpReverted	Estado interno de limpieza de EntryPoint; no se pasa al Paymaster como argumento

EntryPoint llama a postOp únicamente cuando context no está vacío. Si la validación devuelve contexto, el Paymaster debe proporcionar un postOp fiable. Una reversión de postOp hace fallar la UserOperation, pero el Gas ya consumido debe pagarse.

2. BasePaymaster

BasePaymaster.sol proporciona vinculación con EntryPoint, validación del llamador y gestión de depósito y stake. La subclase solo debe implementar la política de patrocinio.

2.1 Interfaces de extensión de la subclase

function _validatePaymasterUserOp(
    PackedUserOperation calldata userOp,
    bytes32 userOpHash,
    uint256 maxCost
) internal virtual returns (
    bytes memory context,
    uint256 validationData
);

function _postOp(
    PostOpMode mode,
    bytes calldata context,
    uint256 actualGasCost,
    uint256 actualUserOpFeePerGas
) internal virtual;

_validatePaymasterUserOp es obligatorio. Sobrescribe _postOp cuando la validación devuelva un contexto no vacío; la implementación predeterminada de BasePaymaster revierte.

2.2 Interfaces de gestión de fondos

function entryPoint() external view returns (address);
function deposit() external payable;
function getDeposit() external view returns (uint256);

function withdrawTo(
    address payable withdrawAddress,
    uint256 amount
) external;

function addStake(uint32 unstakeDelaySec) external payable;
function unlockStake() external;

function withdrawStake(
    address payable withdrawAddress
) external;

Salvo deposit, BasePaymaster restringe los métodos de retirada y gestión de stake al Owner.

3. Campos RPC de UserOperation

Al usar un Paymaster, la UserOperation RPC contiene:

Campo	Tipo	Descripción
paymaster	address	Dirección del contrato Paymaster
paymasterVerificationGasLimit	QUANTITY	Límite de Gas para validar el Paymaster
paymasterPostOpGasLimit	QUANTITY	Límite de Gas de postOp
paymasterData	DATA	Autorización, firma o datos de política personalizados

Ambos límites de Gas deben incluirse en el objeto final. La implementación del Paymaster y el servicio de patrocinio definen el formato de paymasterData.

Omite los cuatro campos si no se usa Paymaster. No proporciones la dirección cero.

4. Disposición de paymasterAndData

Los campos RPC se empaquetan en PackedUserOperation con esta disposición:

Offset 0, longitud 20 bytes: paymaster
Offset 20, longitud 16 bytes: paymasterVerificationGasLimit
Offset 36, longitud 16 bytes: paymasterPostOpGasLimit
Offset 52 hasta el final: paymasterData

Cuando se utiliza un Paymaster, el campo tiene como mínimo 52 bytes. Sin Paymaster, paymasterAndData son bytes vacíos.

5. Depósito y stake

5.1 Depósito

El depósito paga el Gas real de UserOperation. EntryPoint comprueba y reserva el prefund requerido durante la validación.

Interfaz	Descripción
depositTo(paymaster)	Añade fondos al depósito de Gas del Paymaster
balanceOf(paymaster)	Consulta el depósito disponible
withdrawTo	Retira el depósito del propio Paymaster

Un depósito insuficiente produce AA31 paymaster deposit too low.

5.2 Stake

El stake respalda la reputación del Bundler y sus protecciones frente a denegación de servicio; no paga Gas directamente.

Interfaz	Descripción
addStake	Añade stake y establece el retraso de desbloqueo
unlockStake	Inicia el periodo de espera de desbloqueo
withdrawStake	Retira el stake después del periodo de espera

Cuando un Paymaster accede a almacenamiento asociado o cambia determinados estados durante la validación, el Bundler puede exigir un stake mínimo y un retraso de unstake. Los umbrales dependen de su configuración.

6. Errores comunes

Error	Significado
AA31	El depósito del Paymaster es insuficiente
AA32	El rango temporal de validationData no es válido
AA33	validatePaymasterUserOp revirtió
AA34	Los 160 bits inferiores de validationData no son 0
AA36	La validación del Paymaster superó su límite de Gas
PostOpReverted	postOp revirtió; revisa también el evento PostOpRevertReason
AA93	La longitud o disposición de paymasterAndData no es válida