dequanto 0.0.1 → 0.1.3

package/test/fixtures/erc4337/core/Helpers.sol

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: GPL-3.0
+pragma solidity ^0.8.12;
+
+/* solhint-disable no-inline-assembly */
+
+/**
+ * returned data from validateUserOp.
+ * validateUserOp returns a uint256, with is created by `_packedValidationData` and parsed by `_parseValidationData`
+ * @param aggregator - address(0) - the account validated the signature by itself.
+ *              address(1) - the account failed to validate the signature.
+ *              otherwise - this is an address of a signature aggregator that must be used to validate the signature.
+ * @param validAfter - this UserOp is valid only after this timestamp.
+ * @param validaUntil - this UserOp is valid only up to this timestamp.
+ */
+    struct ValidationData {
+        address aggregator;
+        uint48 validAfter;
+        uint48 validUntil;
+    }
+
+//extract sigFailed, validAfter, validUntil.
+// also convert zero validUntil to type(uint48).max
+    function _parseValidationData(uint validationData) pure returns (ValidationData memory data) {
+        address aggregator = address(uint160(validationData));
+        uint48 validUntil = uint48(validationData >> 160);
+        if (validUntil == 0) {
+            validUntil = type(uint48).max;
+        }
+        uint48 validAfter = uint48(validationData >> (48 + 160));
+        return ValidationData(aggregator, validAfter, validUntil);
+    }
+
+// intersect account and paymaster ranges.
+    function _intersectTimeRange(uint256 validationData, uint256 paymasterValidationData) pure returns (ValidationData memory) {
+        ValidationData memory accountValidationData = _parseValidationData(validationData);
+        ValidationData memory pmValidationData = _parseValidationData(paymasterValidationData);
+        address aggregator = accountValidationData.aggregator;
+        if (aggregator == address(0)) {
+            aggregator = pmValidationData.aggregator;
+        }
+        uint48 validAfter = accountValidationData.validAfter;
+        uint48 validUntil = accountValidationData.validUntil;
+        uint48 pmValidAfter = pmValidationData.validAfter;
+        uint48 pmValidUntil = pmValidationData.validUntil;
+
+        if (validAfter < pmValidAfter) validAfter = pmValidAfter;
+        if (validUntil > pmValidUntil) validUntil = pmValidUntil;
+        return ValidationData(aggregator, validAfter, validUntil);
+    }
+
+/**
+ * helper to pack the return value for validateUserOp
+ * @param data - the ValidationData to pack
+ */
+    function _packValidationData(ValidationData memory data) pure returns (uint256) {
+        return uint160(data.aggregator) | (uint256(data.validUntil) << 160) | (uint256(data.validAfter) << (160 + 48));
+    }
+
+/**
+ * helper to pack the return value for validateUserOp, when not using an aggregator
+ * @param sigFailed - true for signature failure, false for success
+ * @param validUntil last timestamp this UserOperation is valid (or zero for infinite)
+ * @param validAfter first timestamp this UserOperation is valid
+ */
+    function _packValidationData(bool sigFailed, uint48 validUntil, uint48 validAfter) pure returns (uint256) {
+        return (sigFailed ? 1 : 0) | (uint256(validUntil) << 160) | (uint256(validAfter) << (160 + 48));
+    }
+
+/**
+ * keccak function over calldata.
+ * @dev copy calldata into memory, do keccak and drop allocated memory. Strangely, this is more efficient than letting solidity do it.
+ */
+    function calldataKeccak(bytes calldata data) pure returns (bytes32 ret) {
+        assembly {
+            let mem := mload(0x40)
+            let len := data.length
+            calldatacopy(mem, data.offset, len)
+            ret := keccak256(mem, len)
+        }
+    }
+

package/test/fixtures/erc4337/core/NonceManager.sol

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: GPL-3.0
+pragma solidity ^0.8.12;
+
+import "../interfaces/IEntryPoint.sol";
+
+/**
+ * nonce management functionality
+ */
+contract NonceManager is INonceManager {
+
+    /**
+     * The next valid sequence number for a given nonce key.
+     */
+    mapping(address => mapping(uint192 => uint256)) public nonceSequenceNumber;
+
+    function getNonce(address sender, uint192 key)
+    public view override returns (uint256 nonce) {
+        return nonceSequenceNumber[sender][key] | (uint256(key) << 64);
+    }
+
+    // allow an account to manually increment its own nonce.
+    // (mainly so that during construction nonce can be made non-zero,
+    // to "absorb" the gas cost of first nonce increment to 1st transaction (construction),
+    // not to 2nd transaction)
+    function incrementNonce(uint192 key) public override {
+        nonceSequenceNumber[msg.sender][key]++;
+    }
+
+    /**
+     * validate nonce uniqueness for this account.
+     * called just after validateUserOp()
+     */
+    function _validateAndUpdateNonce(address sender, uint256 nonce) internal returns (bool) {
+
+        uint192 key = uint192(nonce >> 64);
+        uint64 seq = uint64(nonce);
+        return nonceSequenceNumber[sender][key]++ == seq;
+    }
+
+}

package/test/fixtures/erc4337/core/SenderCreator.sol

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: GPL-3.0
+pragma solidity ^0.8.12;
+
+/**
+ * helper contract for EntryPoint, to call userOp.initCode from a "neutral" address,
+ * which is explicitly not the entryPoint itself.
+ */
+contract SenderCreator {
+
+    /**
+     * call the "initCode" factory to create and return the sender account address
+     * @param initCode the initCode value from a UserOp. contains 20 bytes of factory address, followed by calldata
+     * @return sender the returned address of the created account, or zero address on failure.
+     */
+    function createSender(bytes calldata initCode) external returns (address sender) {
+        address factory = address(bytes20(initCode[0 : 20]));
+        bytes memory initCallData = initCode[20 :];
+        bool success;
+        /* solhint-disable no-inline-assembly */
+        assembly {
+            success := call(gas(), factory, 0, add(initCallData, 0x20), mload(initCallData), 0, 32)
+            sender := mload(0)
+        }
+        if (!success) {
+            sender = address(0);
+        }
+    }
+}

package/test/fixtures/erc4337/core/StakeManager.sol

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.12;
+
+import "../interfaces/IStakeManager.sol";
+
+/* solhint-disable avoid-low-level-calls */
+/* solhint-disable not-rely-on-time */
+/**
+ * manage deposits and stakes.
+ * deposit is just a balance used to pay for UserOperations (either by a paymaster or an account)
+ * stake is value locked for at least "unstakeDelay" by a paymaster.
+ */
+abstract contract StakeManager is IStakeManager {
+
+    /// maps paymaster to their deposits and stakes
+    mapping(address => DepositInfo) public deposits;
+
+    /// @inheritdoc IStakeManager
+    function getDepositInfo(address account) public view returns (DepositInfo memory info) {
+        return deposits[account];
+    }
+
+    // internal method to return just the stake info
+    function _getStakeInfo(address addr) internal view returns (StakeInfo memory info) {
+        DepositInfo storage depositInfo = deposits[addr];
+        info.stake = depositInfo.stake;
+        info.unstakeDelaySec = depositInfo.unstakeDelaySec;
+    }
+
+    /// return the deposit (for gas payment) of the account
+    function balanceOf(address account) public view returns (uint256) {
+        return deposits[account].deposit;
+    }
+
+    receive() external payable {
+        depositTo(msg.sender);
+    }
+
+    function _incrementDeposit(address account, uint256 amount) internal {
+        DepositInfo storage info = deposits[account];
+        uint256 newAmount = info.deposit + amount;
+        require(newAmount <= type(uint112).max, "deposit overflow");
+        info.deposit = uint112(newAmount);
+    }
+
+    /**
+     * add to the deposit of the given account
+     */
+    function depositTo(address account) public payable {
+        _incrementDeposit(account, msg.value);
+        DepositInfo storage info = deposits[account];
+        emit Deposited(account, info.deposit);
+    }
+
+    /**
+     * add to the account's stake - amount and delay
+     * any pending unstake is first cancelled.
+     * @param unstakeDelaySec the new lock duration before the deposit can be withdrawn.
+     */
+    function addStake(uint32 unstakeDelaySec) public payable {
+        DepositInfo storage info = deposits[msg.sender];
+        require(unstakeDelaySec > 0, "must specify unstake delay");
+        require(unstakeDelaySec >= info.unstakeDelaySec, "cannot decrease unstake time");
+        uint256 stake = info.stake + msg.value;
+        require(stake > 0, "no stake specified");
+        require(stake <= type(uint112).max, "stake overflow");
+        deposits[msg.sender] = DepositInfo(
+            info.deposit,
+            true,
+            uint112(stake),
+            unstakeDelaySec,
+            0
+        );
+        emit StakeLocked(msg.sender, stake, unstakeDelaySec);
+    }
+
+    /**
+     * attempt to unlock the stake.
+     * the value can be withdrawn (using withdrawStake) after the unstake delay.
+     */
+    function unlockStake() external {
+        DepositInfo storage info = deposits[msg.sender];
+        require(info.unstakeDelaySec != 0, "not staked");
+        require(info.staked, "already unstaking");
+        uint48 withdrawTime = uint48(block.timestamp) + info.unstakeDelaySec;
+        info.withdrawTime = withdrawTime;
+        info.staked = false;
+        emit StakeUnlocked(msg.sender, withdrawTime);
+    }
+
+
+    /**
+     * withdraw from the (unlocked) stake.
+     * must first call unlockStake and wait for the unstakeDelay to pass
+     * @param withdrawAddress the address to send withdrawn value.
+     */
+    function withdrawStake(address payable withdrawAddress) external {
+        DepositInfo storage info = deposits[msg.sender];
+        uint256 stake = info.stake;
+        require(stake > 0, "No stake to withdraw");
+        require(info.withdrawTime > 0, "must call unlockStake() first");
+        require(info.withdrawTime <= block.timestamp, "Stake withdrawal is not due");
+        info.unstakeDelaySec = 0;
+        info.withdrawTime = 0;
+        info.stake = 0;
+        emit StakeWithdrawn(msg.sender, withdrawAddress, stake);
+        (bool success,) = withdrawAddress.call{value : stake}("");
+        require(success, "failed to withdraw stake");
+    }
+
+    /**
+     * withdraw from the deposit.
+     * @param withdrawAddress the address to send withdrawn value.
+     * @param withdrawAmount the amount to withdraw.
+     */
+    function withdrawTo(address payable withdrawAddress, uint256 withdrawAmount) external {
+        DepositInfo storage info = deposits[msg.sender];
+        require(withdrawAmount <= info.deposit, "Withdraw amount too large");
+        info.deposit = uint112(info.deposit - withdrawAmount);
+        emit Withdrawn(msg.sender, withdrawAddress, withdrawAmount);
+        (bool success,) = withdrawAddress.call{value : withdrawAmount}("");
+        require(success, "failed to withdraw");
+    }
+}

package/test/fixtures/erc4337/interfaces/IAccount.sol

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: GPL-3.0
+pragma solidity ^0.8.12;
+
+import "./UserOperation.sol";
+
+interface IAccount {
+
+    /**
+     * Validate user's signature and nonce
+     * the entryPoint will make the call to the recipient only if this validation call returns successfully.
+     * signature failure should be reported by returning SIG_VALIDATION_FAILED (1).
+     * This allows making a "simulation call" without a valid signature
+     * Other failures (e.g. nonce mismatch, or invalid signature format) should still revert to signal failure.
+     *
+     * @dev Must validate caller is the entryPoint.
+     *      Must validate the signature and nonce
+     * @param userOp the operation that is about to be executed.
+     * @param userOpHash hash of the user's request data. can be used as the basis for signature.
+     * @param missingAccountFunds missing funds on the account's deposit in the entrypoint.
+     *      This is the minimum amount to transfer to the sender(entryPoint) to be able to make the call.
+     *      The excess is left as a deposit in the entrypoint, for future calls.
+     *      can be withdrawn anytime using "entryPoint.withdrawTo()"
+     *      In case there is a paymaster in the request (or the current deposit is high enough), this value will be zero.
+     * @return validationData packaged ValidationData structure. use `_packValidationData` and `_unpackValidationData` to encode and decode
+     *      <20-byte> sigAuthorizer - 0 for valid signature, 1 to mark signature failure,
+     *         otherwise, an address of an "authorizer" contract.
+     *      <6-byte> validUntil - last timestamp this operation is valid. 0 for "indefinite"
+     *      <6-byte> validAfter - first timestamp this operation is valid
+     *      If an account doesn't use time-range, it is enough to return SIG_VALIDATION_FAILED value (1) for signature failure.
+     *      Note that the validation code cannot use block.timestamp (or block.number) directly.
+     */
+    function validateUserOp(UserOperation calldata userOp, bytes32 userOpHash, uint256 missingAccountFunds)
+    external returns (uint256 validationData);
+}

package/test/fixtures/erc4337/interfaces/IAggregator.sol

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: GPL-3.0
+pragma solidity ^0.8.12;
+
+import "./UserOperation.sol";
+
+/**
+ * Aggregated Signatures validator.
+ */
+interface IAggregator {
+
+    /**
+     * validate aggregated signature.
+     * revert if the aggregated signature does not match the given list of operations.
+     */
+    function validateSignatures(UserOperation[] calldata userOps, bytes calldata signature) external view;
+
+    /**
+     * validate signature of a single userOp
+     * This method is should be called by bundler after EntryPoint.simulateValidation() returns (reverts) with ValidationResultWithAggregation
+     * First it validates the signature over the userOp. Then it returns data to be used when creating the handleOps.
+     * @param userOp the userOperation received from the user.
+     * @return sigForUserOp the value to put into the signature field of the userOp when calling handleOps.
+     *    (usually empty, unless account and aggregator support some kind of "multisig"
+     */
+    function validateUserOpSignature(UserOperation calldata userOp)
+    external view returns (bytes memory sigForUserOp);
+
+    /**
+     * aggregate multiple signatures into a single value.
+     * This method is called off-chain to calculate the signature to pass with handleOps()
+     * bundler MAY use optimized custom code perform this aggregation
+     * @param userOps array of UserOperations to collect the signatures from.
+     * @return aggregatedSignature the aggregated signature
+     */
+    function aggregateSignatures(UserOperation[] calldata userOps) external view returns (bytes memory aggregatedSignature);
+}

package/test/fixtures/erc4337/interfaces/IEntryPoint.sol

@@ -0,0 +1,205 @@
+/**
+ ** Account-Abstraction (EIP-4337) singleton EntryPoint implementation.
+ ** Only one instance required on each chain.
+ **/
+// SPDX-License-Identifier: GPL-3.0
+pragma solidity ^0.8.12;
+
+/* solhint-disable avoid-low-level-calls */
+/* solhint-disable no-inline-assembly */
+/* solhint-disable reason-string */
+
+import "./UserOperation.sol";
+import "./IStakeManager.sol";
+import "./IAggregator.sol";
+import "./INonceManager.sol";
+
+interface IEntryPoint is IStakeManager, INonceManager {
+
+    /***
+     * An event emitted after each successful request
+     * @param userOpHash - unique identifier for the request (hash its entire content, except signature).
+     * @param sender - the account that generates this request.
+     * @param paymaster - if non-null, the paymaster that pays for this request.
+     * @param nonce - the nonce value from the request.
+     * @param success - true if the sender transaction succeeded, false if reverted.
+     * @param actualGasCost - actual amount paid (by account or paymaster) for this UserOperation.
+     * @param actualGasUsed - total gas used by this UserOperation (including preVerification, creation, validation and execution).
+     */
+    event UserOperationEvent(bytes32 indexed userOpHash, address indexed sender, address indexed paymaster, uint256 nonce, bool success, uint256 actualGasCost, uint256 actualGasUsed);
+
+    /**
+     * account "sender" was deployed.
+     * @param userOpHash the userOp that deployed this account. UserOperationEvent will follow.
+     * @param sender the account that is deployed
+     * @param factory the factory used to deploy this account (in the initCode)
+     * @param paymaster the paymaster used by this UserOp
+     */
+    event AccountDeployed(bytes32 indexed userOpHash, address indexed sender, address factory, address paymaster);
+
+    /**
+     * An event emitted if the UserOperation "callData" reverted with non-zero length
+     * @param userOpHash the request unique identifier.
+     * @param sender the sender of this request
+     * @param nonce the nonce used in the request
+     * @param revertReason - the return bytes from the (reverted) call to "callData".
+     */
+    event UserOperationRevertReason(bytes32 indexed userOpHash, address indexed sender, uint256 nonce, bytes revertReason);
+
+    /**
+     * an event emitted by handleOps(), before starting the execution loop.
+     * any event emitted before this event, is part of the validation.
+     */
+    event BeforeExecution();
+
+    /**
+     * signature aggregator used by the following UserOperationEvents within this bundle.
+     */
+    event SignatureAggregatorChanged(address indexed aggregator);
+
+    /**
+     * a custom revert error of handleOps, to identify the offending op.
+     *  NOTE: if simulateValidation passes successfully, there should be no reason for handleOps to fail on it.
+     *  @param opIndex - index into the array of ops to the failed one (in simulateValidation, this is always zero)
+     *  @param reason - revert reason
+     *      The string starts with a unique code "AAmn", where "m" is "1" for factory, "2" for account and "3" for paymaster issues,
+     *      so a failure can be attributed to the correct entity.
+     *   Should be caught in off-chain handleOps simulation and not happen on-chain.
+     *   Useful for mitigating DoS attempts against batchers or for troubleshooting of factory/account/paymaster reverts.
+     */
+    error FailedOp(uint256 opIndex, string reason);
+
+    /**
+     * error case when a signature aggregator fails to verify the aggregated signature it had created.
+     */
+    error SignatureValidationFailed(address aggregator);
+
+    /**
+     * Successful result from simulateValidation.
+     * @param returnInfo gas and time-range returned values
+     * @param senderInfo stake information about the sender
+     * @param factoryInfo stake information about the factory (if any)
+     * @param paymasterInfo stake information about the paymaster (if any)
+     */
+    error ValidationResult(ReturnInfo returnInfo,
+        StakeInfo senderInfo, StakeInfo factoryInfo, StakeInfo paymasterInfo);
+
+    /**
+     * Successful result from simulateValidation, if the account returns a signature aggregator
+     * @param returnInfo gas and time-range returned values
+     * @param senderInfo stake information about the sender
+     * @param factoryInfo stake information about the factory (if any)
+     * @param paymasterInfo stake information about the paymaster (if any)
+     * @param aggregatorInfo signature aggregation info (if the account requires signature aggregator)
+     *      bundler MUST use it to verify the signature, or reject the UserOperation
+     */
+    error ValidationResultWithAggregation(ReturnInfo returnInfo,
+        StakeInfo senderInfo, StakeInfo factoryInfo, StakeInfo paymasterInfo,
+        AggregatorStakeInfo aggregatorInfo);
+
+    /**
+     * return value of getSenderAddress
+     */
+    error SenderAddressResult(address sender);
+
+    /**
+     * return value of simulateHandleOp
+     */
+    error ExecutionResult(uint256 preOpGas, uint256 paid, uint48 validAfter, uint48 validUntil, bool targetSuccess, bytes targetResult);
+
+    //UserOps handled, per aggregator
+    struct UserOpsPerAggregator {
+        UserOperation[] userOps;
+
+        // aggregator address
+        IAggregator aggregator;
+        // aggregated signature
+        bytes signature;
+    }
+
+    /**
+     * Execute a batch of UserOperation.
+     * no signature aggregator is used.
+     * if any account requires an aggregator (that is, it returned an aggregator when
+     * performing simulateValidation), then handleAggregatedOps() must be used instead.
+     * @param ops the operations to execute
+     * @param beneficiary the address to receive the fees
+     */
+    function handleOps(UserOperation[] calldata ops, address payable beneficiary) external;
+
+    /**
+     * Execute a batch of UserOperation with Aggregators
+     * @param opsPerAggregator the operations to execute, grouped by aggregator (or address(0) for no-aggregator accounts)
+     * @param beneficiary the address to receive the fees
+     */
+    function handleAggregatedOps(
+        UserOpsPerAggregator[] calldata opsPerAggregator,
+        address payable beneficiary
+    ) external;
+
+    /**
+     * generate a request Id - unique identifier for this request.
+     * the request ID is a hash over the content of the userOp (except the signature), the entrypoint and the chainid.
+     */
+    function getUserOpHash(UserOperation calldata userOp) external view returns (bytes32);
+
+    /**
+     * Simulate a call to account.validateUserOp and paymaster.validatePaymasterUserOp.
+     * @dev this method always revert. Successful result is ValidationResult error. other errors are failures.
+     * @dev The node must also verify it doesn't use banned opcodes, and that it doesn't reference storage outside the account's data.
+     * @param userOp the user operation to validate.
+     */
+    function simulateValidation(UserOperation calldata userOp) external;
+
+    /**
+     * gas and return values during simulation
+     * @param preOpGas the gas used for validation (including preValidationGas)
+     * @param prefund the required prefund for this operation
+     * @param sigFailed validateUserOp's (or paymaster's) signature check failed
+     * @param validAfter - first timestamp this UserOp is valid (merging account and paymaster time-range)
+     * @param validUntil - last timestamp this UserOp is valid (merging account and paymaster time-range)
+     * @param paymasterContext returned by validatePaymasterUserOp (to be passed into postOp)
+     */
+    struct ReturnInfo {
+        uint256 preOpGas;
+        uint256 prefund;
+        bool sigFailed;
+        uint48 validAfter;
+        uint48 validUntil;
+        bytes paymasterContext;
+    }
+
+    /**
+     * returned aggregated signature info.
+     * the aggregator returned by the account, and its current stake.
+     */
+    struct AggregatorStakeInfo {
+        address aggregator;
+        StakeInfo stakeInfo;
+    }
+
+    /**
+     * Get counterfactual sender address.
+     *  Calculate the sender contract address that will be generated by the initCode and salt in the UserOperation.
+     * this method always revert, and returns the address in SenderAddressResult error
+     * @param initCode the constructor code to be passed into the UserOperation.
+     */
+    function getSenderAddress(bytes memory initCode) external;
+
+
+    /**
+     * simulate full execution of a UserOperation (including both validation and target execution)
+     * this method will always revert with "ExecutionResult".
+     * it performs full validation of the UserOperation, but ignores signature error.
+     * an optional target address is called after the userop succeeds, and its value is returned
+     * (before the entire call is reverted)
+     * Note that in order to collect the the success/failure of the target call, it must be executed
+     * with trace enabled to track the emitted events.
+     * @param op the UserOperation to simulate
+     * @param target if nonzero, a target address to call after userop simulation. If called, the targetSuccess and targetResult
+     *        are set to the return from that call.
+     * @param targetCallData callData to pass to target address
+     */
+    function simulateHandleOp(UserOperation calldata op, address target, bytes calldata targetCallData) external;
+}
+

package/test/fixtures/erc4337/interfaces/INonceManager.sol

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: GPL-3.0
+pragma solidity ^0.8.12;
+
+interface INonceManager {
+
+    /**
+     * Return the next nonce for this sender.
+     * Within a given key, the nonce values are sequenced (starting with zero, and incremented by one on each userop)
+     * But UserOp with different keys can come with arbitrary order.
+     *
+     * @param sender the account address
+     * @param key the high 192 bit of the nonce
+     * @return nonce a full nonce to pass for next UserOp with this sender.
+     */
+    function getNonce(address sender, uint192 key)
+    external view returns (uint256 nonce);
+
+    /**
+     * Manually increment the nonce of the sender.
+     * This method is exposed just for completeness..
+     * Account does NOT need to call it, neither during validation, nor elsewhere,
+     * as the EntryPoint will update the nonce regardless.
+     * Possible use-case is call it with various keys to "initialize" their nonces to one, so that future
+     * UserOperations will not pay extra for the first transaction with a given key.
+     */
+    function incrementNonce(uint192 key) external;
+}

package/test/fixtures/erc4337/interfaces/IPaymaster.sol

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: GPL-3.0
+pragma solidity ^0.8.12;
+
+import "./UserOperation.sol";
+
+/**
+ * the interface exposed by a paymaster contract, who agrees to pay the gas for user's operations.
+ * a paymaster must hold a stake to cover the required entrypoint stake and also the gas for the transaction.
+ */
+interface IPaymaster {
+
+    enum PostOpMode {
+        opSucceeded, // user op succeeded
+        opReverted, // user op reverted. still has to pay for gas.
+        postOpReverted //user op succeeded, but caused postOp to revert. Now it's a 2nd call, after user's op was deliberately reverted.
+    }
+
+    /**
+     * payment validation: check if paymaster agrees to pay.
+     * Must verify sender is the entryPoint.
+     * Revert to reject this request.
+     * Note that bundlers will reject this method if it changes the state, unless the paymaster is trusted (whitelisted)
+     * The paymaster pre-pays using its deposit, and receive back a refund after the postOp method returns.
+     * @param userOp the user operation
+     * @param userOpHash hash of the user's request data.
+     * @param maxCost the maximum cost of this transaction (based on maximum gas and gas price from userOp)
+     * @return context value to send to a postOp
+     *      zero length to signify postOp is not required.
+     * @return validationData signature and time-range of this operation, encoded the same as the return value of validateUserOperation
+     *      <20-byte> sigAuthorizer - 0 for valid signature, 1 to mark signature failure,
+     *         otherwise, an address of an "authorizer" contract.
+     *      <6-byte> validUntil - last timestamp this operation is valid. 0 for "indefinite"
+     *      <6-byte> validAfter - first timestamp this operation is valid
+     *      Note that the validation code cannot use block.timestamp (or block.number) directly.
+     */
+    function validatePaymasterUserOp(UserOperation calldata userOp, bytes32 userOpHash, uint256 maxCost)
+    external returns (bytes memory context, uint256 validationData);
+
+    /**
+     * post-operation handler.
+     * Must verify sender is the entryPoint
+     * @param mode enum with the following options:
+     *      opSucceeded - user operation succeeded.
+     *      opReverted  - user op reverted. still has to pay for gas.
+     *      postOpReverted - user op succeeded, but caused postOp (in mode=opSucceeded) to revert.
+     *                       Now this is the 2nd call, after user's op was deliberately reverted.
+     * @param context - the context value returned by validatePaymasterUserOp
+     * @param actualGasCost - actual gas used so far (without this postOp call).
+     */
+    function postOp(PostOpMode mode, bytes calldata context, uint256 actualGasCost) external;
+}