EntryPoint

Esta página documenta la interfaz on-chain del EntryPoint desplegado en BOT Chain. Al enviar UserOperations directamente, quien realiza la llamada debe asumir las responsabilidades de un Bundler.

1. PackedUserOperation

EntryPoint acepta la siguiente estructura on-chain:

struct PackedUserOperation {
    address sender;
    uint256 nonce;
    bytes initCode;
    bytes callData;
    bytes32 accountGasLimits;
    uint256 preVerificationGas;
    bytes32 gasFees;
    bytes paymasterAndData;
    bytes signature;
}

1.1 Campos y codificación

Campo	Significado	Disposición de codificación
sender	Dirección de la cuenta inteligente	smartAccount(160)
nonce	Nonce bidimensional gestionado por EntryPoint	key(192) ‖ sequence(64)
initCode	Dirección del Factory y calldata del primer despliegue	Sin desplegar: factory(160) ‖ factoryData(N); desplegada: 0x
callData	Datos de ejecución enviados a la cuenta inteligente	selector(32) ‖ encodedArguments(N)
accountGasLimits	Límites de Gas para validación y ejecución de la cuenta	verificationGasLimit(128) ‖ callGasLimit(128)
preVerificationGas	Sobrecoste de calldata y bundle fuera de la validación on-chain	preVerificationGas(256)
gasFees	Tarifa prioritaria y tarifa total máxima EIP-1559	maxPriorityFeePerGas(128) ‖ maxFeePerGas(128)
paymasterAndData	Dirección, límites de Gas y datos personalizados opcionales del Paymaster	Usado: paymaster(160) ‖ paymasterVerificationGasLimit(128) ‖ paymasterPostOpGasLimit(128) ‖ paymasterData(N); sin usar: 0x
signature	Datos de autorización validados por la cuenta inteligente	accountSignature(N)

Los números entre paréntesis son longitudes en bits; N indica una longitud variable.

2. Interfaces de ejecución

function handleOps(
    PackedUserOperation[] calldata ops,
    address payable beneficiary
) external;

function handleAggregatedOps(
    UserOpsPerAggregator[] calldata opsPerAggregator,
    address payable beneficiary
) external;

2.1 handleOps

Parámetro	Descripción
ops	UserOperations que no utilizan agregador de firmas
beneficiary	Dirección que recibe las tarifas de Gas reales del lote

EntryPoint valida el lote completo antes de ejecutar el callData de cada cuenta. Un error de validación puede revertir todo el lote. Una reversión de la ejecución de negocio se registra mediante un evento y no necesariamente revierte la transacción externa.

2.2 handleAggregatedOps

Utiliza este método cuando las cuentas devuelvan un agregador de firmas distinto de cero. Las UserOperations se agrupan por agregador y cada grupo incluye una firma agregada. Usa handleOps cuando no se requiera agregación de firmas.

UserOpsPerAggregator contiene:

Campo	Tipo	Descripción
userOps	PackedUserOperation[]	Operaciones gestionadas por el agregador actual
aggregator	IAggregator	Agregador del grupo; solo en handleAggregatedOps, un grupo con dirección cero indica que no necesita agregación
signature	bytes	Firma agregada del grupo

3. Hash, nonce y dirección

function getUserOpHash(
    PackedUserOperation calldata userOp
) external view returns (bytes32);

function getNonce(
    address sender,
    uint192 key
) external view returns (uint256 nonce);

function incrementNonce(uint192 key) external;

function getSenderAddress(bytes memory initCode) external;

3.1 getUserOpHash

Devuelve el hash de UserOperation que debe validar la cuenta. El hash vincula:

• El contenido de la UserOperation, sin incluir signature
• La dirección actual de EntryPoint
• El chainId actual

Cambiar cualquier campo participante después de firmar invalida la firma.

3.2 getNonce

Devuelve el siguiente nonce completo para una cuenta y una clave de nonce:

nonce = uint192 key || uint64 sequence

SimpleAccount utiliza la clave 0 de forma predeterminada. No la sustituyas por el nonce de transacción de la EOA Owner ni por eth_getTransactionCount de la cuenta inteligente.

3.3 incrementNonce

Permite que quien llama adelante la secuencia de una de sus claves de nonce. Las cuentas normales suelen dejar que EntryPoint actualice el nonce después de una validación correcta.

3.4 getSenderAddress

Calcula una dirección de cuenta contrafactual a partir de initCode. El método siempre revierte y devuelve el resultado mediante el error personalizado SenderAddressResult(address sender).

4. Depósito y stake

function getDepositInfo(
    address account
) external view returns (DepositInfo memory info);

function balanceOf(address account)
    external view returns (uint256);

function depositTo(address account) external payable;

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

function addStake(uint32 unstakeDelaySec) external payable;

function unlockStake() external;

function withdrawStake(
    address payable withdrawAddress
) external;

4.1 Depósito

El depósito es el saldo que una cuenta o Paymaster financia por adelantado en EntryPoint para pagar el Gas de las UserOperations.

Método	Descripción
balanceOf	Consulta el depósito de una entidad
getDepositInfo	Consulta conjuntamente depósito, stake y estado de desbloqueo
depositTo	Permite que cualquier dirección financie la entidad indicada
withdrawTo	Retira el depósito de quien realiza la llamada

4.2 Stake

Un Factory, Paymaster o agregador bloquea stake para cumplir las reglas de validación y reputación. No se utiliza directamente para pagar el Gas de UserOperation.

Método	Descripción
addStake	Añade stake y establece el retraso mínimo de desbloqueo
unlockStake	Inicia el periodo de espera para desbloquear
withdrawStake	Retira el stake una vez finalizado el periodo de espera

El depósito y el stake son independientes. El stake por sí solo no puede pagar Gas, y el depósito por sí solo no necesariamente satisface el requisito de stake del Bundler para entidades que acceden a almacenamiento restringido.

5. Eventos principales

Evento	Campos principales	Uso
UserOperationEvent	userOpHash, sender, paymaster, nonce, success, actualGasCost, actualGasUsed	Determina el resultado final de cada UserOperation
AccountDeployed	userOpHash, sender, factory, paymaster	Registra el despliegue contrafactual de una cuenta
UserOperationRevertReason	userOpHash, sender, nonce, revertReason	Registra los datos de reversión de la llamada de negocio de la cuenta
PostOpRevertReason	userOpHash, sender, nonce, revertReason	Registra una reversión de postOp del Paymaster
UserOperationPrefundTooLow	userOpHash, sender, nonce	Registra prefund insuficiente durante la ejecución
BeforeExecution	Ninguno	Separa los eventos de validación de los de ejecución
Deposited / Withdrawn	account, amount	Registra cambios de depósito
StakeLocked / StakeUnlocked / StakeWithdrawn	account, stake, time	Registra el ciclo de vida del stake

Que la transacción externa handleOps tenga éxito no significa que todas las UserOperations lo hayan tenido. Usa UserOperationEvent.success como resultado.

6. Errores principales

Error	Descripción
FailedOp(opIndex, reason)	La UserOperation indicada falló durante la validación o el prefunding
FailedOpWithRevert(opIndex, reason, inner)	Fallo con datos de reversión internos de una cuenta, Factory o Paymaster
PostOpReverted(returnData)	El postOp del Paymaster revirtió
SignatureValidationFailed(aggregator)	Falló la validación de la firma agregada
SenderAddressResult(sender)	Contenedor de resultado previsto para getSenderAddress