EntryPoint
このページでは、BOT Chain にデプロイされた EntryPoint のオンチェーンインターフェースを説明します。UserOperation を直接送信する場合、呼び出し側が Bundler の役割を担います。
1. PackedUserOperation
EntryPoint は次のオンチェーン構造を受け取ります。
struct PackedUserOperation {
address sender;
uint256 nonce;
bytes initCode;
bytes callData;
bytes32 accountGasLimits;
uint256 preVerificationGas;
bytes32 gasFees;
bytes paymasterAndData;
bytes signature;
}
1.1 フィールドとエンコード
| フィールド | 意味 | エンコードレイアウト |
|---|---|---|
sender | スマートアカウントアドレス | smartAccount(160) |
nonce | EntryPoint が管理する 2 次元 nonce | key(192) ‖ sequence(64) |
initCode | 初回デプロイ用 Factory アドレスと calldata | 未デプロイ：factory(160) ‖ factoryData(N)、デプロイ済み：0x |
callData | スマートアカウントへの実行データ | selector(32) ‖ encodedArguments(N) |
accountGasLimits | 検証・実行の Gas 上限 | verificationGasLimit(128) ‖ callGasLimit(128) |
preVerificationGas | オンチェーン検証外の calldata・bundle オーバーヘッド | preVerificationGas(256) |
gasFees | EIP-1559 優先手数料と最大総手数料 | maxPriorityFeePerGas(128) ‖ maxFeePerGas(128) |
paymasterAndData | 任意の Paymaster、Gas 上限、独自データ | 使用時：paymaster(160) ‖ paymasterVerificationGasLimit(128) ‖ paymasterPostOpGasLimit(128) ‖ paymasterData(N)、未使用：0x |
signature | スマートアカウントが検証する認可データ | accountSignature(N) |
括弧内は bit 長で、N は可変長です。
2. 実行インターフェース
function handleOps(PackedUserOperation[] calldata ops, address payable beneficiary) external;
function handleAggregatedOps(UserOpsPerAggregator[] calldata opsPerAggregator, address payable beneficiary) external;
2.1 handleOps
| 引数 | 説明 |
|---|---|
ops | 署名アグリゲーターを使わない UserOperation 配列 |
beneficiary | バッチの実際の Gas 手数料を受け取るアドレス |
EntryPoint はバッチ全体を検証してから、各アカウントの callData を実行します。検証エラーはバッチ全体を revert する場合があります。ビジネス実行の revert はイベントに記録され、外側のトランザクションを必ずしも revert しません。
2.2 handleAggregatedOps
アカウントがゼロ以外の署名アグリゲーターを返す場合に使用します。UserOperation はアグリゲーター別にグループ化され、各グループが集約署名を保持します。署名集約が不要なら handleOps を使用します。
| フィールド | 型 | 説明 |
|---|---|---|
userOps | PackedUserOperation[] | 現在のアグリゲーターが処理する操作 |
aggregator | IAggregator | グループのアグリゲーター。ゼロアドレスは集約不要を示す |
signature | bytes | グループの集約署名 |
3. Hash、nonce、アドレス
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
アカウントが検証する UserOperation hash を返します。hash は次を結び付けます。
signatureを除く UserOperation の内容- 現在の EntryPoint アドレス
- 現在の chainId
署名後に対象フィールドを変更すると署名は無効になります。
3.2 getNonce
指定アカウントと nonce key の次の完全な nonce を返します。
nonce = uint192 key || uint64 sequence
SimpleAccount は既定で key 0 を使用します。Owner EOA のトランザクション nonce やスマートアカウントの eth_getTransactionCount で代用しないでください。
3.3 incrementNonce
呼び出し側が自分の nonce key の sequence を先に進めます。通常は検証成功後の EntryPoint による更新を利用します。
3.4 getSenderAddress
initCode から反実仮想アカウントアドレスを計算します。常に revert し、独自エラー SenderAddressResult(address sender) で結果を返します。
4. Deposit と 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 Deposit
Deposit はアカウントまたは Paymaster が UserOperation Gas 支払い用に EntryPoint へ事前入金する残高です。
| メソッド | 説明 |
|---|---|
balanceOf | エンティティの deposit を照会 |
getDepositInfo | deposit、stake、ロック解除状態を一括照会 |
depositTo | 任意のアドレスから指定エンティティへ入金 |
withdrawTo | 呼び出し側自身の deposit を引き出す |
4.2 Stake
Stake は Factory、Paymaster、アグリゲーターが検証・レピュテーション規則を満たすためにロックする資金で、Gas 支払いには直接使いません。
| メソッド | 説明 |
|---|---|
addStake | stake を追加して最短ロック解除遅延を設定 |
unlockStake | ロック解除待機期間を開始 |
withdrawStake | 待機期間後に stake を引き出す |
Deposit と stake は独立しています。stake だけでは Gas を支払えず、deposit だけでは制限付き storage へアクセスするエンティティに対する Bundler の stake 要件を満たすとは限りません。
5. 主要イベント
| イベント | 主なフィールド | 用途 |
|---|---|---|
UserOperationEvent | userOpHash, sender, paymaster, nonce, success, actualGasCost, actualGasUsed | 各 UserOperation の最終結果 |
AccountDeployed | userOpHash, sender, factory, paymaster | 反実仮想アカウントのデプロイを記録 |
UserOperationRevertReason | userOpHash, sender, nonce, revertReason | ビジネス呼び出しの revert データ |
PostOpRevertReason | userOpHash, sender, nonce, revertReason | Paymaster postOp の revert |
UserOperationPrefundTooLow | userOpHash, sender, nonce | 実行中の prefund 不足 |
BeforeExecution | なし | 検証段階と実行段階のイベントを分離 |
Deposited / Withdrawn | account, amount | deposit の変更 |
StakeLocked / StakeUnlocked / StakeWithdrawn | account, stake, time | stake のライフサイクル |
外側の handleOps が成功しても、各 UserOperation の成功を意味しません。UserOperationEvent.success を確認してください。
6. 主要エラー
| エラー | 説明 |
|---|---|
FailedOp(opIndex, reason) | 指定操作が検証または prefund 段階で失敗 |
FailedOpWithRevert(opIndex, reason, inner) | アカウント、Factory、Paymaster の内部 revert データを伴う失敗 |
PostOpReverted(returnData) | Paymaster の postOp が revert |
SignatureValidationFailed(aggregator) | 集約署名の検証失敗 |
SenderAddressResult(sender) | getSenderAddress の想定結果コンテナ |