As highlighted in this BlockSec threat model, hooks can either be benign but vulnerable or intentionally malicious. This article focuses on the former, in which there is some overlap between categories; however, it is equally important to account for the latter, as well as upgradeability risks, private key compromise, and other centralisation concerns, when interacting with unverified or otherwise unvetted hooks.

It is also worth noting that potential attack vectors can arise from existing, well-known smart contract vulnerabilities that manifest within the hook itself. While a few particularly interesting examples will be included, this article focuses primarily on exploits and other issues that are specific to Uniswap v4 insofar as they relate to custom hooks taking custody of funds and managing critical application state.

Hooks and permissions

Deploying hooks with permissions that are not implemented

Hook permissions are encoded in least significant bits of the hook address and compared against flags to determine whether it should implement the corresponding function:

function hasPermission(IHooks self, uint160 flag) internal pure returns (bool) {
    return uint160(address(self)) & flag != 0;
}

If a hook lacks the necessary permissions for a given function then it effectively behaves as a no-op; however, if the hook address encodes a certain permission for which the corresponding function is not implemented then (without any fallback logic) this will result in a revert.

The v4 periphery BaseHook abstract contract is designed to avoid deploying such a hook by validating that the deployed hook address agrees with the expected permissions of the hook. Similar and more extended functionality is provided by the OpenZeppelin implementation.

Heuristic: does the hook inherit an abstract BaseHook implementation? If not, are there checks in place to avoid deploying a hook that encodes specific permissions but does not implement the corresponding functions?

Deploying hooks without permissions required for implemented functions

As mentioned above, if a hook lacks the necessary permissions for a given function then its execution will be skipped. Counter to the case in which the permission is granted without implementing the necessary functionality, failing to encode the necessary permissions for implemented functions will most likely result in unexpected and undesired behaviour as key logic is omitted.

In this example, a protocol fee is intended to be taken in the afterSwap() hook; however, absence of the AFTER_SWAP_RETURNS_DELTA_FLAG permission results in a denial-of-service (DoS) of all swaps once the protocol fee is enabled.

The contract creation code in addition to the salt and deployer address determine the hook address, so different constructor parameters and deployer addresses will result in different hook addresses. Again, use of one of the base hook implementations will help to verify that the permissions of the derived hook address are encoded as intended:

/// @notice Utility function intended to be used in hook constructors to ensure
/// the deployed hooks address causes the intended hooks to be called
/// @param permissions The hooks that are intended to be called
/// @dev permissions param is memory as the function will be called from constructors
 function validateHookPermissions(IHooks self, Permissions memory permissions) internal pure {
    if (
        permissions.beforeInitialize != self.hasPermission(BEFORE_INITIALIZE_FLAG)
            || permissions.afterInitialize != self.hasPermission(AFTER_INITIALIZE_FLAG)
            || permissions.beforeAddLiquidity != self.hasPermission(BEFORE_ADD_LIQUIDITY_FLAG)
            || permissions.afterAddLiquidity != self.hasPermission(AFTER_ADD_LIQUIDITY_FLAG)
            || permissions.beforeRemoveLiquidity != self.hasPermission(BEFORE_REMOVE_LIQUIDITY_FLAG)
            || permissions.afterRemoveLiquidity != self.hasPermission(AFTER_REMOVE_LIQUIDITY_FLAG)
            || permissions.beforeSwap != self.hasPermission(BEFORE_SWAP_FLAG)
            || permissions.afterSwap != self.hasPermission(AFTER_SWAP_FLAG)
            || permissions.beforeDonate != self.hasPermission(BEFORE_DONATE_FLAG)
            || permissions.afterDonate != self.hasPermission(AFTER_DONATE_FLAG)
            || permissions.beforeSwapReturnDelta != self.hasPermission(BEFORE_SWAP_RETURNS_DELTA_FLAG)
            || permissions.afterSwapReturnDelta != self.hasPermission(AFTER_SWAP_RETURNS_DELTA_FLAG)
            || permissions.afterAddLiquidityReturnDelta != self.hasPermission(AFTER_ADD_LIQUIDITY_RETURNS_DELTA_FLAG)
            || permissions.afterRemoveLiquidityReturnDelta
                != self.hasPermission(AFTER_REMOVE_LIQUIDITY_RETURNS_DELTA_FLAG)
    ) {
        HookAddressNotValid.selector.revertWith(address(self));
    }
}

Heuristic: does the hook inherit an abstract BaseHook implementation? If not, are there checks in place to avoid deploying a hook that implements a specific function without encoding the corresponding permission?

Unimplemented functions allowing bypass through underlying Uniswap v4 contracts

When focusing on a specific hook implementation, it is easy to forget about the entrypoints that still exist on Uniswap v4 itself. Even with all hook permissions correctly encoded for the functions that are expected to be exposed, there can be instances in which unimplemented functions should have actually been implemented (and the permissions set accordingly). This issue can take many forms depending on the context but ultimately arises because the business logic of the application may dictate that certain actions should only be performed through the hook or a related contract.

For instance, it may be intended to restrict modifying liquidity to happen exclusively through the hook, but be overlooked that it would still be possible to do so directly through the PoolManager contract. Unless the relevant liquidity modification hooks are implemented to revert in this case, it is possible to circumvent execution of intended hook logic.

In this example, the intended behaviour of a hook designed to penalize just-in-time (JIT) liquidity provision in the afterRemoveLiquidity() function can be bypassed by first increasing the liquidity to collect all the fees accrued from swaps. This resets the fee state and hence bypasses the penalty mechanism. In this case, the solution is to extend the hook permissions to additionally track fee collection that occurs during liquidity additions within the beforeAddLiquidity() function.

Another simpler instance is when it may not desirable to allow donations. Without activating the beforeDonate() hook to always revert on donations, calls to PoolManager::donate would succeed in increasing the fee growth.

Heuristic: can actions that are intended to originate from the hook or otherwise alter the behaviour of other implemented hook functions be executed directly on the underlying Uniswap v4 contracts? Are the necessary hooks implemented to take control of execution in these cases?

Insufficient pool key validation

Uniswap v4 does not restrict who can create new liquidity pools, nor which hook address to use in a new liquidity pool. If a hook is not restricted to a specific pool or set of pools, an attacker could deploy a malicious pool with fake tokens using and abusing the hook through attack vectors such as reentrancy or manipulation of the internal accounting.

As with all unsafe external calls and caller-supplied inputs, insufficient validation can potentially compromise the hook contract depending on the context, so hooks that are designed for specific pools should validate token pairs specified within the pool key during initialization. Hook functions should in general also grant permissioned access to only the specific subset of Uniswap v4 pools that are intended to use and interact with the given hook contract.

C-01 details a variation of this vulnerability in which the victim contract, intended to coordinate all ecosystem hooks and associated contracts, can be drained by specification of a malicious pool key due to insufficient input validation of the hook and currency addresses.

More examples: [C-02, H-01, M-02, L-12, 5, 6, 7].

Heuristic: are the pool key and associated currency addresses validated to ensure that permissioned access is granted only to the specific subset of Uniswap v4 pools expected to use and interact with the hook?

Hook callbacks

Insufficient callback access controls

Similar to other types of callback, such as those invoked by flash loans providers, the v4 unlockCallback() and other hook function callbacks should in general be callable only by the singleton PoolManager contract. These details may differ slightly depending on the specifics of a given protocol design, in which case careful management of access control is of even more pertinent concern.

As above, protections can be implemented by inheriting one of the BaseHook implementations along with the SafeCallback base contract and overriding _unlockCallback().

/// @dev We force the onlyPoolManager modifier by exposing a virtual function after the onlyPoolManager check.
function unlockCallback(bytes calldata data) external onlyPoolManager returns (bytes memory) {
    return _unlockCallback(data);
}

/// @dev to be implemented by the child contract, to safely guarantee the logic is only executed by the PoolManager
function _unlockCallback(bytes calldata data) internal virtual returns (bytes memory);

Perhaps the most high profile example of this attack vector was its use as a lever in the $12 million Cork Protocol exploit in which the beforeSwap() function was called by an attacker with malicious hook data.

Other examples include:

• H-02 in which is insufficient access control allowed any address to call beforeInitialize() directly to overwrite the stored pool key.

• C-06 in which is insufficient access control allowed any address to call beforeSwap() and afterSwap(), undermining the core limit order mechanism.

• The example v4-stoploss hook which allows any address to call afterSwap() with arbitrary parameters, again undermining the limit order mechanism.

Heuristic: does the hook inherit an abstract BaseHook implementation? Does the hook or related contract(s) inherit the abstract SafeCallback? If not, are there checks in place to prevent unprivileged callers from invoking unlockCallback() and other hook functions?

Incorrect callback return data encoding

The length of data returned by a hook callback should at least be sufficient to contain the 4 byte selector, encoded in 32 bytes:

// Length must be at least 32 to contain the selector. Check expected selector and returned selector match.
if (result.length < 32 || result.parseSelector() != data.parseSelector()) {
    InvalidHookResponse.selector.revertWith();
}

For the hook functions invoked using Hooks::callHookWithReturnDelta and expecting to parse a return delta, the length of data should be exactly 64 bytes to contain both the encoded selector plus the 32 byte delta:

// A length of 64 bytes is required to return a bytes4, and a 32 byte delta
if (result.length != 64) InvalidHookResponse.selector.revertWith();
return result.parseReturnDelta();

Hooks::beforeSwap additionally expects a 3 byte fee override and enforces a length of 96 bytes:

// A length of 96 bytes is required to return a bytes4, a 32 byte delta, and an LP fee
if (result.length != 96) InvalidHookResponse.selector.revertWith();

If the length of return data is not as expected, either because the incorrect types are encoded or otherwise, then execution will revert.

Heuristic: does the hook inherit an abstract BaseHook implementation? If not, are the hook function signatures and return data lengths as expected by the Hooks library?

Before vs after hooks

It may not seem important whether some functionality is implemented in a hook that executes before an operation versus one that executes afterwards, and indeed in certain circumstances this may be perfectly fine; however, hook developers and auditors should be clear on the assumptions that are being made about the placement of such logic as this can give rise to a category of very subtle bugs.

Consider the example of some custom incentives logic. Say, perhaps, that it intends to clean up critical state used in such computations upon complete removal of liquidity. If this is performed in the beforeRemoveLiquidity() hook rather than afterRemoveLiquidity() then at the point of execution the liquidity will remain unchanged and the state will never be updated, the consequence being that incentives will be computed for liquidity positions that no longer exist. While this seems obvious in hindsight, it can be challenging to spot as complexity grows.

This could also play out in the reverse scenario, as in this example in which tick initialization logic present in the afterAddLiquidity() hook should have been placed in beforeAddLiquidity(). Executing after the core liquidity modification logic has already run means the tick will already have been initialized once execution returns to the hook and so the conditional logic will never be triggered.

More examples: [1].

Heuristic: is hook logic dependent on whether it is executed before or after the core Uniswap v4 logic? Will liquidity, tick initialization state, etc differ depending on the choice of before/after hook? Will a mistake here cause key logic to execute differently, incorrectly, or be entirely omitted?

Unhandled reverts

When reviewing hooks, it is important to be very mindful of potential sources of reverts both in the hook business logic and also based on liquidity modification/swaps.

Sync before unlock

PoolManager::sync has the onlyWhenUnlocked modifier to ensure that the currency and reserves transient storage can only be synchronised after PoolManager::unlock has already been called. If a hook function attempts to synchronise the currency reserves before unlocking the PoolManager, execution will revert. Instead, this logic should be moved to the unlock callback and executed prior to any custom accounting.

Heuristic: are calls to sync() always performed following a prior unlock()?

Unsettled deltas from uncleared or unsynchronised dust

The key invariant of flash accounting and the unlock mechanism is that all deltas must be settled before returning execution from the unlock callback to the PoolManager. Actions such as swapping tokens or modifying liquidity generate deltas which represent the net changes in token balances owed by or to the pool and are accumulated in transient storage. If there are any unsettled deltas at the end of execution, the integrating contract may need to withdraw assets owed to the user using the take() function or deposit assets owed to the pool followed by a call to the settle() function.

In some instances, there may be small “dust” balances that prevent account deltas from being fully settled and so the clear() function should be used to explicitly account this to the pool. This is implemented as a protection against loss of caller funds; however, dust balances can thus be used as a DoS attack vector if this scenario is not properly handled, as in H-01.

In similar fashion, L-13 details a DoS scenario in which tokens are donated but not synchronised in transient storage with a call to sync(), resulting in a revert when attempting to settle the deltas of an operation.

Heuristic: are there any scenarios in which dust could accumulate and, if so, is it explicitly cleared? Are the currency and reserves always synced in transient storage before performing operations that modify account deltas?

Reverts when modifying liquidity

Unhandled reverts in either the beforeRemoveLiquidity() or afterRemoveLiquidity() hook can result in liquidity provider (LP) funds being permanently locked unless there is some way of escaping from this DoS state. This scenario can also prevent fees from ever being collected, since unlike Uniswap v3 the delta due to fee growth is required to be settled on every liquidity modification. Reverts during the addition of liquidity are slightly less problematic since this cannot result in funds becoming locked but will still cause severe disruption to the protocol.

Other examples include H-8 in which the initial LP cannot withdraw due to protocol-specific initialization, which as additionally noted by M-6 does not refund unused tokens for this initial liquidity provision.

Heuristic: are there any calls within the liquidity modification hooks that could revert? Are these potentially problematic calls explicitly handled to prevent unexpected reverts?

Reverts in peripheral hook logic

Peripheral logic, such as custom incentives and rebalancing, should be treated with care to avoid DoS and potential loss of funds due to unhandled reverts. The severity of such reverts depends on which functionality is disabled and whether it can be recovered. While an inability to add liquidity and swap against an affected pool represents loss of core functionality, the most impactful cases are those in which funds are permanently locked, for example due to an inability to remove existing liquidity from the pool or withdraw other tokens in the custody of the contract(s).

While not critical, some sources of reverts may never allow the intended functionality to run, where incorrect access control prevents an external integration from executing correctly. If the hook is not upgradeable then it would need to be redeployed with the fix which could cause severe disruption to the protocol and its users.

Sometimes, the logic may appear sound for one invocation of an operation but then fail on subsequent calls, as in this example of a top-of-block swap tax that is erroneously applied to all other swaps and causes a DoS. There may also be edge cases in the math used to compute such taxes/prices/etc that can cause some subset of calls to fail.

H-05 is an example of DoS due to a failure to account for multiple pool IDs. Certain operations, such as rebalancing, may be possible for multiple pools associated with a given hook within a given block; however, the logic may be such that this is overlooked, restricting the functionality to only a single pool if a distinct nonce is not used.

In the examples [1, 2, 3, 4], permissionless rewards distribution and range creation can be abused to trigger reverts due to overflow and excessive gas usage. This DoS vector is also demonstrated in rebalancing and incentives logic due to differences between chains.

More examples: [1].

Heuristic: are there any calls in custom logic within hook function implementations that could revert? Are there any peripheral accounting mechanisms that could revert, perhaps due to excessive gas usage or under/overflow? Are these potentially problematic cases explicitly handled to prevent unexpected reverts?

Dynamic fees

Incorrect dynamic fee accounting

Uniswap v4 pools can support dynamic swap fees beyond the typical static options if the pool key specifies the fee using LPFeeLibrary.DYNAMIC_FEE_FLAG to signal support. This is queried in Hooks::beforeSwap like so:

// dynamic fee pools that want to override the cache fee, return a valid fee with the override flag. If override flag
// is set but an invalid fee is returned, the transaction will revert. Otherwise the current LP fee will be used
if (key.fee.isDynamicFee()) lpFeeOverride = result.parseFee();

The dynamic fee can be updated by either:

• Having the hook contract call PoolManager::updateDynamicLPFee.

• Returning fee | LPFeeLibrary.OVERRIDE_FEE_FLAG from the beforeSwap() hook.

Dynamic fee pools initialize with a 0% default fee, so this should be overridden with a call to the updateDynamicLPFee() function in the afterInitialize() hook.

The per-swap override allows the dynamic fee to change on every swap, avoiding repeated calls to the PoolManager, and is handled by Pool::swap like so:

// if the beforeSwap hook returned a valid fee override, use that as the LP fee, otherwise load from storage
// lpFee, swapFee, and protocolFee are all in pips
{
    uint24 lpFee = params.lpFeeOverride.isOverride()
    ? params.lpFeeOverride.removeOverrideFlagAndValidate()
    : slot0Start.lpFee();

    swapFee = protocolFee == 0 ? lpFee : uint16(protocolFee).calculateSwapFee(lpFee);
}

If either of LPFeeLibrary.DYNAMIC_FEE_FLAG or LPFeeLibrary.OVERRIDE_FEE_FLAG are omitted then the intended fee override will not be applied and default fee will be used.

Even with the dynamic fee correctly specified, the actual accounting logic may be implemented incorrectly. This could result in miscalculation of the fees assigned to the intended recipient(s) or even unrecoverable balances becoming locked in the hook.

More examples: [C-02, M-03, M-4, M-11, 5, 6, 7, 8].

Heuristic: does the hook intend to support dynamic swap fees and, if so, does the pool key signal support? Is functionality exposed with sufficient access control to update the dynamic fee directly on the PoolManager? Is the default dynamic fee overridden in the afterInitialize() hook? Are dynamic fees returned correctly from the beforeSwap() hook with the LP fee override flag applied?

Abuse of dynamic fees

Depending on how the protocol is configured, there are instances in which privileged callers can obtain the right to set and adjust dynamic swap fees. For example, Bunni v2 implements the auction-managed AMM mechanism to run censorship-resistant onchain auctions for the right to temporarily set the swap fee rate and receive accrued fees from swaps.

TOB-BUNNI-11 details a scenario in which a malicious manager can manipulate the TWAP price while avoiding arbitrage. If the oracle is used determine asset prices in an external lending protocol then it is possible for the manager to exploit this by borrowing against overvalued collateral.

H-02 demonstrates how a malicious manager could capture fees at the expense of the protocol.

More examples: [H-02].

Heuristic: can dynamic swap fees be manually set or adjusted by an actor other than the protocol administrator? Are reasonable bounds applied to prevent manipulation and loss to other fee recipients?

Custom accounting

Custom accounting is a very powerful feature of Uniswap v4, but by the same token can easily put entire protocol liquidity at risk. Unlike vanilla hooks, those leveraging custom accounting take control of the underlying liquidity and so any bug in the business logic of these hooks, or any other related contracts that store or otherwise handle ERC-6909 claim tokens, is likely to be catastrophic. It is imperative that this accounting is water tight. Even if it is seemingly well-implemented, developers and auditors alike should be very paranoid of all sources and sinks of value, as will be demonstrated below.

Insufficient input validation

Insufficient input validation can give rise to multiple categories of bugs and is often a precursor to some of the highest severity exploits. In the context of custom accounting, more complex hook protocol architecture can have its accounting be abused or otherwise broken by a caller invoking certain functions with arbitrary inputs.

Consider TOB-BUNNI-6 in which anyone can call the rebalance order pre/post hooks to trigger the rebalance logic outside of legitimate order fulfilment which results in funds being pulled from the central BunniHub contract. TOB-BUNNI-7 details a similar issue with the rebalance order fulfilment mechanism, in this instance insufficient validation of the order fulfilment inputs themselves, allowing for asymmetric execution of the rebalance order pre/post hooks which violates the intended symmetric execution.

More examples: [TOB-BUNNI-8].

Heuristic: are the inputs of all functions touching logic associated with custom accounting sufficiently validated? Are there specific permissioned addresses that should be required? Are there any combinations of inputs that allows the intended, possibly symmetric, execution to be bypassed or otherwise violated?

Incorrect segregation of funds

As with typical smart contract accounting, there may be token balances designated to different purposes and beneficial owners. Incorrect segregation of funds is a common issue in which one of potentially multiple entities can perform some action with access to an asset/amount to which they should not be entitled.

The severity of such issues depends on the specific business logic, perhaps limited to elevated admin control in the less impactful case but potentially allowing an attacker to extract value in higher-severity occurrences. Custom Uniswap v4 accounting is no different. Recursive LP tokens, fees, donations, and other incentive balances are often sources of this type of issue that are easy to overlook.

C-05 demonstrates how a mismatch between raw ERC-20 and ERC-6909 accounting could be abused to drain the underlying currency of a pool. In this example, such an exploit is predicated on utilizing the LP token of one pool, stored in the target contract as rent payments, as a currency of the recursive malicious pool.

A similar example of abusing recursive LP tokens to drain rewards balances can be found here. In this case, deltas are lost to the PoolManager upon liquidity provision. The underlying tokenised incentives that are encapsulated by the wrapped liquidity tokens can be stolen by leveraging flash accounting to sync, claim on behalf of the PoolManager, settle, and finally take the extracted tokens.

H-04 shows how dust balances accumulated by either fee/donation mechanism can result in the hook reverting due to the issue of unsettled deltas from uncleared or unsynchronised dust as explained above.

More examples: [H-02, 2, 3, 4, 5, 6].

Heuristic: are there any assets or addresses with multiple accounting designations? Is there a mixture of ERC-20 and ERC-6909 accounting? If so, does is it work correctly in tandem? Are fees, donations, or any other reserved assets explicitly considered? Should recursive LP tokens be supported and can any underlying yield be stolen when provided as liquidity?

Incorrect swap logic

A key aspect of the design space unlocked by custom accounting is the ability to override the swap logic of the underlying concentrated liquidity model. While this pioneering feature allows for innovative AMM designs to be built on top of the primitive Uniswap v4 hook architecture, this greatly increases the attack surface and potential for subtle arithmetic bugs that can completely break the core functionality.

Consider TOB-BUNNI-15/16/17/18 and M-21 in which it was possible to:

• Execute free swaps, providing zero input tokens but receiving a non-zero amount of output tokens.

• Gain a net positive amount tokens from round trip swaps.

• Receive a different amount of input/output tokens depending on the exact input/output configuration.

• Trigger unhandled panic reverts due to arithmetic errors.

• Underestimate the liquidity available to a swap.

A separate example M-13 additionally details a DoS vector for swaps erroneously using the specified swap price limit instead of computing the price target for the next swap step.

Heuristic: does the hook override the underlying concentrated liquidity model? Do swaps behave as expected? Can any of the AMM invariants be broken?

Incorrect delta accounting

Another aspect of custom accounting that goes in hand with modifying the swap logic is the ability for hooks to override the deltas that represent the net token movement between the pool, hook, and caller. If these deltas are computed or applied incorrectly, this can result in silent but severe accounting discrepancies that leak value at the expense of either the protocol or its users depending on the nature of the oversight.

An easy mistake to make here is misinterpreting the sign convention of swapDelta, hookDelta, or callerDelta. This may, for instance, result in the hook underpaying its users if the caller delta of the specified token is underestimated in beforeSwap() or overcharging users if the hook delta is overestimated in afterSwap(). In the worst case, value could be extracted from the pool if tokens are transferred in the wrong direction at the expense of the hook.

Note that the core Hooks::beforeSwap logic prevents the semantics of a swap from changing with application of the hook delta:

// Update the swap amount according to the hook's return, and check that the swap type doesn't change (exact input/output)
if (hookDeltaSpecified != 0) {
    bool exactInput = amountToSwap < 0;
    amountToSwap += hookDeltaSpecified;
    if (exactInput ? amountToSwap > 0 : amountToSwap < 0) {
        HookDeltaExceedsSwapAmount.selector.revertWith();
    }
}

In other words, exact input swaps are explicitly forbidden from becoming considered exact output swaps and vice versa. However, if afterSwap() returns a hookDelta with the incorrect sign, thinking it is owed then the magnitude and direction of payment can become inverted.

More examples: [M-02, 2].

Heuristic: is the direction of net value flow consistent with the original intent? Can users be under/overcharged or extract value directly from the hook? Are deltas ever added/incremented when they should be subtracted/decremented, or vice versa?

Reentrancy

As mentioned in the introduction, hooks can suffer from well-known smart contract vulnerabilities, including reentrancy which may arise from chaining together a number of lower-severity issues within more complex hook protocol architecture. This is exactly what happened with the live critical vulnerability in Bunni v2, reported by Cyfrin, in which the total protocol TVL was at risk.

In short, through deployBunniToken() it was possible to deploy malicious hooks with no validation which could subsequently be used to unlock the global reentrancy guard. Since the hook of a Bunni pool was not constrained to be the canonical BunniHook implementation, and given that unlockForRebalance() simply required the hook of a given pool to be the caller, anyone could create a malicious hook that invoked this function directly to unlock the reentrancy guard protecting the core BunniHub contract. This combined with the caching of pool state before unsafe external calls to rehypothecation vaults, which could again be freely specified as arbitrary malicious addresses by an attacker, meant that reentrancy from within both hookHandleSwap() and withdraw() was in fact possible to recursively extract both raw balances and vault reserves accounted across all pools.

C-03 details a similar, less impactful variation of this issue, in which execution of deposits over intermediate state between pre/post hooks could be abused. This also happened to be the finding that introduced the problematic function allowing the chain of lower severity vulnerabilities to be assembled into a full-drain critical exploit. In a manner similar to the $197 million Euler exploit, this highlights the challenge of full-coverage mitigation review and importance of recognising the potential downstream effects of subtle, seemingly trivial, logic changes.

Even if direct reentrancy on the target contracts is not possible, read-only re-entrancy may still affect integrating contracts relying on quoter functions due to missing re-entrancy guards as noted in L-13.

Heuristic: does the canonical hook or any of its associated contracts perform unsafe external calls? Can this be influenced caller-defined inputs which may specify malicious addresses? Is a reentrancy guard applied to all critical functions? Can it be bypassed, perhaps by a malicious hook implementation?

Rounding and precision loss

Another well-known albeit tricky smart contract vulnerability is precision loss due to rounding. While it may be relatively straightforward to identify the instances in which this behaviour will occur, it is significantly more challenging to land upon the specific scenario that may be leveraged in an attack.

In the case of the $8.4 million Bunni v2 exploit, the above disclosure was very unfortunately not sufficient to prevent a ruinous loss of funds. At its core, this exploit was caused by floor rounding which allowed for the construction of an atomic liquidity increase by the attacker. To summarise, the exploit steps included:

1. Swapping almost all of the pool’s reserves to minimise the active balance to the point where rounding errors become significant.

2. Repeatedly withdrawing a small number of shares to abuse the rounding behaviour of the idle balance, effectively creating a share price inflation while disproportionately decreasing the liquidity calculation based on the active and idle balances.

3. Swapping back to lock in the atomic liquidity increase and then drain the pool at the inflated price.

While the above points may seem simple enough, this was a complex exploit against a complex protocol. The sad irony is the precision with which the attacker crafted the inputs to pull this off. A full post-mortem writeup can be found here, along with a more detailed analysis here. It is strongly recommended to read both of these understand the full nuance of the issue.

More examples: [1, 2].

Heuristic: is any of the hook logic susceptible to rounding errors? If so, is it obvious how it might be abused? If not, consider which other calculations may depend on it (e.g. share price, liquidity, etc) and how execution may proceed at the extremes.

Tick Trouble

Misaligned ticks

Depending on the tick spacing of a given pool, there is a small region of tick space between the minimum/maximum usable ticks and the actual minimum/maximum ticks defined by the Uniswap v3 math that should be carefully avoided. For example, assuming a tick spacing of 60, the usable tick range is [-887220, 887220]. Thus, it should not be possible for the sqrt price tick to enter either range [-887272, -887220) or (887220, 887272].

Uniswap will revert when the tick of a liquidity position is not an exact multiple of the pool’s tick spacing. This can result in DoS [1, 2] and/or unusable positions if not correctly validated by the hook.

function flipTick(mapping(int16 => uint256) storage self, int24 tick, int24 tickSpacing) internal {
    // Equivalent to the following Solidity:
    //     if (tick % tickSpacing != 0) revert TickMisaligned(tick, tickSpacing);
    //     (int16 wordPos, uint8 bitPos) = position(tick / tickSpacing);
    //     uint256 mask = 1 << bitPos;
    //     self[wordPos] ^= mask;
    assembly ("memory-safe") {
        tick := signextend(2, tick)
        tickSpacing := signextend(2, tickSpacing)
        // ensure that the tick is spaced
        if smod(tick, tickSpacing) {
            let fmp := mload(0x40)
            mstore(fmp, 0xd4d8f3e6) // selector for TickMisaligned(int24,int24)
            mstore(add(fmp, 0x20), tick)
            mstore(add(fmp, 0x40), tickSpacing)
            revert(add(fmp, 0x1c), 0x44)
        }
    ...
}

More examples: [1].

Heuristic: are caller-specified ticks validated to be aligned to the tick spacing? Are the range edge cases validated against the minimum and maximum usable ticks?

Operations over zero liquidity

If out-of-range initialization of the square root price is not prevented and swaps against zero liquidity are not explicitly handled then this can allow the price to be freely manipulated to outside the intended tick range. Even If there is a small non-zero amount of liquidity in a pool, various issues can arise from the tick being manipulated to an extreme value.

In some circumstances, this can result in losses to honest users through arbitrage, as in C-03. In others, swaps and the addition of single-sided liquidity to these end ranges can result in complete DoS of core functionality.

For protocols that implement additional incentives, care should be taken to avoid performing computations and depositing tokens when there is no pool liquidity.

More examples: [H-01, L-26].

Heuristic: are ticks/ranges free to be pushed to or otherwise specified as extreme values? Are they validated against the the minimum/maximum usable ticks for the given tick spacing? Are there any additional mechanisms that will behave incorrectly when there is no liquidity?

Incorrect tick crossings

The Uniswap v3 concentrated liquidity tick crossing logic defines where liquidity is considered in range and active (i.e., price is between upper/lower ticks). Active liquidity is utilized by swaps and earns fees, so fee growth state updates are also triggered for the liquidity positions becoming active/inactive whenever the price crosses a tick boundary.

Miscalculation of the active liquidity can have disastrous consequences, as evidenced by the KyberSwap Elastic critical vulnerability disclosure, $56 million KyberSwap Elastic exploit (very well-explained here), and $4.4 million Raydium exploit. This could be due to rounding or incorrect state updates when crossing ticks during swaps, or modifying liquidity, for example resulting in double counting or other discrepancies that can be leveraged by an attacker.

In this example, active liquidity calculations appear to function as expected; however, for zero-for-one swaps where the current tick is an exact multiple of the tick spacing at the upper end of a liquidity range, the effect of the boundary tick is skipped and the liquidity is accounted incorrectly. As a result, the net liquidity is significantly smaller than expected which ultimately inflates the computed fee growth and allows for all rewards to be stolen by such an intentionally, or perhaps even inadvertently, malicious position.

More examples: [H-01, 2].

Heuristic: are tick crossings handled correctly? Are there any edge cases, such as starting/ending exactly on a tick/word boundary, in which the logic breaks? Are there sufficient tests around these boundary conditions?

Miscellaneous

Native token handling

Unlike Uniswap v3, Uniswap v4 has support for native ETH abstracted via the custom Currency type. While this succeeds in providing a better user and developer experience, it is not without its dangers. Insufficient or otherwise incorrect handling of native tokens can give rise to some typical issues that are associated with and should be expected when dealing with native token support.

The first and likely most impactful point is that native token transfers are a source of potential reentrancy. This may be more easily overlooked when dealing with the Currency type and ERC-6909 representations, but it is nevertheless incredibly important to identify all sources of unsafe external calls that could be reentered.

A second, more subtle error is the absence of a receive() function. This can result in DoS depending on how the hook and its associated contracts are intended to transfer and receive value in the form of the native token. H-04 demonstrates how this could occur when unable to receive dust balances redirected from a router contract.

In the worst case, if the capability is implemented but the msg.value is insufficiently validated then this could result in the native token balance becoming locked, as in L-22. This could also result in breaking the custom swap delta accounting, as in M-19.

Also note that it is not necessary to perform validation on currency1 as the native token can only ever be token0, since currencies are ordered by address and address(0) is used for the native currency [1, 2].

Heuristic: does the hook have support for native ETH? If so, can it be used to reenter any critical functionality? Do contracts that expect to receive native tokens implement the receive() function? If not, have edge cases such as router integration been considered? Is msg.value sufficiently validated?

JIT liquidity

Just-in-time liquidity enables innovative capital-efficient protocol designs (e.g. Euler) but can also be used maliciously to manipulate pricing or reward mechanisms. This could include temporarily inflating liquidity positions to capture fees, incentives, or alter other core state before withdrawing immediately after, as in M-1/2 which rely on front-running custom liquidity and rewards logic.

The scenario described by TOB-BUNNI-9 shows how an error in the hook withdrawal queue logic enabled JIT liquidity provision which could be used to manipulate the pool rebalance order computation, potentially leaving it in a worse state than before.

More examples: [1].

Heuristic: can JIT liquidity be provided? Does it represent net positive flow, or can it be malicious and should it be disincentivised/prevented?

Incorrect router parameters

While the Uniswap V4Router is, like all other router implementations, a peripheral contract, care must be taken to ensure that:

1. All recipient and token addresses are correct.

2. Amounts are not accidentally zero or reversed.

C-03 is an example of the former while C-04/H-07 are examples of the latter, though these errors can of course also occur in the hook logic itself.

Heuristic: is the correct recipient address specified? It is not necessarily always msg.sender. Is amount0/token0 accidentally used in place of amount1/token1 and vice versa?

Custom incentives

The following is a list of various other interesting findings not directly related to Uniswap v4 hooks but rather the implementation of custom LP fee handling and other incentives logic [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27].

The main takeaways here are to be cautious of Uniswap v3 math that has been reimplemented for custom purposes, particularly when considering the swap math, tick crossings, and fee growth computations. For more complex hooks, full end-to-end tests should also validate the flow of tokens between multiple integrating contracts to ensure that there is no missing logic/transfers that could result in stuck funds.

Conclusion

Hooks are a very powerful innovation. This design considerably lowers the barrier to AMM experimentation but equally raises the bar for sound and secure implementation, especially when customising the underlying concentrated liquidity mechanism. The overall attack surface is large and can be fairly nuanced, as hopefully demonstrated in this article. If you found it to be helpful, amplification and all feedback would be greatly appreciated!

This article will focus on the security considerations for integrating Chainlink Functions & Automation, demonstrated with findings from a recent Cyfrin private audit for Chainlink Build Program project The Standard. A full list of high and medium severity findings can be found here, along with the full report here.

Note that while the main categories of findings and associated heuristics discussed in this article are around the implementation-specific composition of the two Chainlink services, chaining Automation upkeep calls with the fulfillment of the triggered Functions requests, it remains very pertinent to other codebases both when the services are leveraged in isolation and by virtue of the fact this multi-faceted integration is not an uncommon design pattern to observe.

A Note on Chainlink Services and Reverts

To first elucidate some nuances about the Chainlink Functions and Automation services that both leverage the same shared subscription and billing model, note that:

• The Chainlink Automation DON performs the upkeep check every block.

• Upkeep transactions are broadcast immediately, save for some latency associated with transaction inclusion and confirmation.

• The subscription is billed for every Automation upkeep transaction.

• The Chainlink Functions DON reports the status of both off-chain computation and on-chain callback.

• The Chainlink Functions DON will only ever attempt to fulfill a given request once.

• Only one of the Functions callback response/err parameters will be set to non-zero bytes.

• Failed Functions executions will not be retried, so the subscription is billed only once even if the callback reverts.

• There exists a five-minute timeout after which a Functions request becomes stale, hence it is not guaranteed that the callback will receive a response.

As we will see below, it is thus imperative to ensure that mission-critical logic contained within the Functions callback, potentially triggered by Automation upkeep, does not revert unless absolutely unavoidable. If it does, this case should be handled gracefully with an optional but highly recommended admin-controlled escape hatch to avoid halting further executions. The flow looks something like this:

1. `checkUpkeep()` called off-chain by Chainlink Automation DON.
2. Upkeep required.
3. `performUpkeep()` called on-chain by Chainlink Automation DON.
4. Chainlink Functions request triggered within upkeep logic.
5. Chainlink Functions DON attempts to fulfill request.
6. Chainlink Functions `fulfillRequest()` callback reverts.
7. Mission-critical logic is not executed, leaving state corrupted.
8. Admin resets corrupted state, allowing execution to resume as normal.

DoS of Core Functionality

With the stage freshly set, let’s consider all the ways to avoid having the fulfillRequest() callback revert:

• Do not revert if an error in off-chain computation is reported by the Functions DON (i.e. don’t bubble up err bytes).

• Avoid attempting to decode an empty response when there are non-zero err bytes present.

• Validate the response against its expected length to ensure that the decoding does not revert.

• Avoid reverting if validation of the contents of the API response fails.

• Handle reverts from all external calls using try/catch blocks.

• Short-circuit if specific inputs would cause other calls to revert.

• Be very wary of return data bombs and other gas-exhaustion attacks.

• Optionally add an access-controlled admin function to reset critical state.

In this example, upkeep can only be triggered when there are no in-flight requests waiting to be fulfilled. An unhandled revert in AutoRedemption::fulfillRequest would cause execution to end without resetting the required lastRequestId state. Due to the absence of any other method for resetting the state, this therefore results in a denial-of-service on the entire upkeep → callback mechanism.

function performUpkeep(bytes calldata performData) external {
    if (lastRequestId == bytes32(0)) {
        triggerRequest();
    }
}

function fulfillRequest(bytes32 requestId, bytes memory response, bytes memory err) internal override {
    // TODO proper error handling
    // if (err) revert; // @audit - no, don't do this!
    if (requestId != lastRequestId) revert("wrong request"); // @audit - avoid this also!
    ...
    lastRequestId = bytes32(0); // @audit - this will not be reset if execution reverts!
}

Also note that as mentioned above, there is always some small chance that despite a very high degree of reliability the Chainlink Functions DON may not respond if a request becomes stale. Drawing on an excellent example present in the Tunnl smart contracts, this can be handled gracefully by implementing a manual or automated retry mechanism that allows Functions requests to be sent again in the event of failure.

/*
* @notice This function is called in case of Twitter API failure, RPC issue, or any general
* failure in order to manually retry functions request via admins based on status of offer
* @param offerIds The offer Ids to be sent for batch manual retry request
*/
function retryRequests(bytes32[] calldata offerIds) external onlyAdmins {
    for (uint256 i = 0; i < offerIds.length; i++) {
        bytes32 offerId = offerIds[i];

        // Check if the offer is eligible for a retry based on its status
        if (
            s_offers[offerId].status == Status.VerificationFailed ||
            s_offers[offerId].status == Status.VerificationInFlight ||
            s_offers[offerId].status == Status.AwaitingVerification
        ) {
            sendFunctionsRequest(offerId, RequestType.Verification);
        }
        if (
            s_offers[offerId].status == Status.PayoutFailed ||
            s_offers[offerId].status == Status.PayoutInFlight ||
            (s_offers[offerId].status == Status.Active && s_offers[offerId].payoutDate <= block.timestamp)
        ) {
            sendFunctionsRequest(offerId, RequestType.Payout);
        }
    }
}

Heuristic: is it possible for Chainlink Functions & Automation calls to revert? Can an attacker manipulate state to force this case? Is there an escape hatch to reset state in the event of failed requests or other incomplete execution?

More examples: [1, 2, 3, 4, 5, 6].

Insufficient Access Controls

While it may be tempting to overlook access controls on the checkUpkeep() and performUpkeep() functions of AutomationCompatibleInterface given the intention to automate key aspects of a protocol, this is very likely to provide would-be attackers with one or more levers for manipulation. It is also important to note that, without use of the cannotExexute() modifier, both functions allow for state changes when called; therefore, even though checkUpkeep() is used for simulation and subsequent triggering of performUpkeep() by the Chainlink Automation DON, it could also contain state-changing logic. This means it may not be sufficient to add access controls to just one function or the other – always analyse the context and verify the behaviour of both.

In this example, recalling the context from above, upkeep can only be triggered when the lastRequestId state variable is equal to bytes32(0); however, since this state is reset at the end of execution initiated within triggerRequest(), specifically in AutoRedemption::fulfillRequest, this means that upkeep can be repeatedly performed after the previous one has succeeded. Note that this is possible regardless of the trigger condition both due to the absence of access controls and a failure to re-check the trigger condition to prevent execution based on stale or manipulated data when upkeep is actually performed.

function checkUpkeep(bytes calldata checkData) external returns (bool upkeepNeeded, bytes memory performData) {
    (uint160 sqrtPriceX96,,,,,,) = pool.slot0();
    upkeepNeeded = sqrtPriceX96 <= triggerPrice;
}

function performUpkeep(bytes calldata performData) external { // @audit - no access controls!
    if (lastRequestId == bytes32(0)) {
        triggerRequest(); // note: triggers a call to autoRedemption()
    }
}

From here, an attacker can leverage other implementation errors in the logic triggered by the callback to force a revert and permanently disable the functionality. For example, the incorrect calculation of the debt redeemed, as reported here and shown below, causes a panic revert due to underflow when the given vault is fully redeemed but a dust amount of USDs is transferred to the contract beforehand.

function autoRedemption(...) external onlyAutoRedemption returns (uint256 _redeemed) {
    ...
    _redeemed = USDs.balanceOf(address(this)); // @audit - dust amount can be sent to inflate this value!
    minted -= _redeemed; // @audit - meaning this could revert due to underflow if the vault is fully redeemed.
    ...
}

As mentioned above, given that there is no other way to reset lastRequestId, this represents a state from which a non-upgradeable contract cannot recover.

Heuristic: are the AutomationCompatibleInterface functions permissionless? Is the execution of logic within these functions sensitive to on-chain state? Is it problematic if they be called by any account at any time?

More examples: [1].

Unintended/Incomplete Execution

As stated before, the Chainlink Automation DON checks the upkeep condition every block. Once the trigger condition is met and upkeep is required, the DON will send a transaction on-chain. In a sense, this can be thought of as asynchronous execution of a state transition within a finite state machine.

If such a state transition is not completed fully, correctly, or even intentionally, then problems may arise. This scenario could occur in a manner similar to the first example, where unhandled reverts result in an irrecoverable state, or caused through a similar vector in which an attacker additionally leverages incorrect implementation details as in the second example.

In this example, the trigger condition is based on a price oracle that is derived from the instantaneous reserves of a Uniswap v3 pool. As you may have already noted, this oversight can be leveraged by an attacker through manipulation of the pool reserves to trigger upkeep when it is potentially not desired.

function checkUpkeep(bytes calldata checkData) external returns (bool upkeepNeeded, bytes memory performData) {
    (uint160 sqrtPriceX96,,,,,,) = pool.slot0();
    upkeepNeeded = sqrtPriceX96 <= triggerPrice;
}

While I recommend reading the full finding linked above for more details about the potential manipulation and considerations around the maintenance of such a manipulation given the latency of upkeep performance, the repeated triggering of upkeep in this manner could result in the subscription being fraudulently billed to exhaustion.

Heuristic: is every state transition properly accounted for? Can the state be manipulated into an incorrect transition? Is a permissionless call to performUpkeep() safe for all inputs? Should the trigger condition be re-checked when performing upkeep?

More examples: [1, 2].

Request Authentication & Secrets

With increasingly advanced smart contract applications now commonly leveraging additional off-chain infrastructure, it is important to highlight in this final example that great care must be taken to secure both the on-chain and off-chain components. Here, the source constant defined within AutoRedemption is used to execute the corresponding JavaScript code within the Chainlink Functions DON; however, the target API endpoint is exposed without any form of authentication which allows any observer to send requests.

string private constant source =
        "const { ethers } = await import('npm:ethers@6.10.0'); const apiResponse = await Functions.makeHttpRequest({ url: 'https://smart-vault-api.thestandard.io/redemption' }); if (apiResponse.error) { throw Error('Request failed'); } const { data } = apiResponse; const encoded = ethers.AbiCoder.defaultAbiCoder().encode(['uint256', 'address', 'uint256'], [data.tokenID, data.collateral, data.value]); return ethers.getBytes(encoded)";

At a minimum, rate limiting should be implemented to mitigate against coordinated DDoS attacks on the API endpoint. Ideally, authentication should be added to the request using Chainlink Functions secrets.

Heuristic: does the Chainlink Functions request leak sensitive information? Are self-hosted API endpoints sufficiently protected? Is the off-chain infrastructure configured to be resilient to DDoS attacks?

Conclusion

To summarise, when integrating Chainlink Functions and/or Automation:

• Unhandled reverts should be avoided at all costs. An attacker should not be able manipulate state to force this case and the application should be designed in such a way to avoid irrecoverable execution. If this is not possible, the contract admin should have access to a permissioned function to reset critical paths.

• The execution of callback functions should likely not be permissionless, especially if they are sensitive to on-chain state and/or timing that could be manipulated by an attacker. This includes trigger conditions that should also be resistant to manipulation.

• Every state transition should be properly accounted for and trigger conditions should generally be re-checked during execution.

• Sensitive off-chain information, such as API endpoints and associated secrets, should be sufficiently protected if exposed on-chain.

That is all for this article. I hope it gives developers and security researchers alike some inspiration when it comes to reviewing the integration of these lesser-discussed Chainlink services. Watch out for a couple of additional findings from this audit related to the Uniswap v3 integration and some tick weirdness that will be explored in a future article!

RISC Zero

The RISC Zero zkVM is an implementation of the RISC-V architecture as an arithmetic circuit. Specifically, the zkVM implements RV32IM which is the 32-bit base instruction set along with the multiplication feature, extended using the ECALL instruction to add optimized cryptographic instructions. Additional technical details can be found here.

Mathematically, the RV32IM circuit encodes RISC-V as polynomial constraints within a STARK-based proving system. In short, the memory and register transitions of the emulated processor at each clock cycle are captured within the execution trace, providing a complete snapshot of the guest program being executed.

1. The guest program is compiled to an executable format known as the ELF binary.

2. The untrusted host program orchestrates verifiable computation, handling two-way communication with the zkVM environment and transmitting private inputs to the guest program.

   • ExecutorEnvBuilder::write is used to pass private data from the host to the guest.

   • env::write is used to pass private data from the guest to the host.

   • env::commit is used to pass public data from the guest to the host.

3. The executor runs the ELF binary and records the execution trace (aka the session).

4. The prover checks and proves the validity of the session, producing a cryptographic receipt that attests to the execution of the guest program.

   ⚠️

   Proving with private data should be done with local proof generation to ensure it never leaves the machine, as the prover can see all private information involved.

   1. The receipt claim portion of the receipt contains the journal and other important details.

      • The journal portion of the receipt claim contains the public output committed by the guest.

      • The cryptographic image ID indicates the method or boot image for zkVM execution.

      • The guest program exit status and memory state are also included in the claim.

   2. The seal portion of the receipt is a zk-STARK that attests to the receipt claim.

      • The control ID is the first entry in the seal. It is the Merkle hash of the contents of the control columns, assumed to be known to the verifier as part of the circuit definition.

5. Verification of the receipt provides a cryptographic assurance of honest journal creation.

   

   1. The RISC-V Circuit proves zkVM execution by dividing the session into multiple segments and generating a proof for each segment, forming a composite receipt of multiple STARKs.

   2. The Recursion Circuit uses incrementally verifiable computation to combine the proofs of a composite receipt into a single STARK, generating a succinct receipt. It is also used to aggregate and efficiently verify multiple succinct receipts in a similar manner. More details can be found here and a full example analogous to verifiable encryption with RSA can be found here.

   3. The Groth16 Circuit converts a succinct receipt into a single Groth16 receipt, acting as a compact SNARK wrapper around the larger STARK proof that can be verified on-chain by calling IRiscZeroVerifier::verify.

Parity Example

Suppose we want to prove the parity of a integer value without revealing the value itself. The trivial guest program could look something like this:

#![no_main]
#![no_std]

use risc0_zkvm::guest::env;

risc0_zkvm::guest::entry!(main);

fn main() {
    // Load the number from the host
    let x: u32 = env::read();

    // Compute the product while being careful with integer overflow
    let is_even: bool = x % 2 == 0;

    // Commit the result to the journal without exposing the value
    env::commit(&is_even);
}

Note that it is perfectly fine to panic within the guest, for example with the following snippet if we wanted to consider non-zero integers only:

// Verify the value is non-zero
if x == 0 {
   panic!("Number is zero")
}

We would just need to make sure to handle it appropriately within host, but will omit this for simplicity. The host program can be split into multiple files for some logical separation. Here is an idea of how the proving could look in lib.rs:

use is_even_methods::IS_EVEN_ELF;
use risc0_zkvm::{default_prover, ExecutorEnv, Receipt};

// Compute whether the value is even inside the zkVM
pub fn is_even(x: u32) -> (Receipt, bool) {
    let env = ExecutorEnv::builder()
        // Send x to the guest
        .write(&x)
        .unwrap()
        .build()
        .unwrap();

    // Obtain the default prover.
    let prover = default_prover();

    // Produce a receipt by proving the specified ELF binary.
    let receipt = prover.prove(env, IS_EVEN_ELF).unwrap().receipt;

    // Extract journal of receipt (i.e. output b, where b = x % 2 == 0)
    let b: bool = receipt.journal.decode().expect(
        "Journal output should deserialize into the same types (& order) that it was written",
    );

    // Report the result
    println!("I know the value is {}, and I can prove it!", b);

    (receipt, b)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_is_even() {
        const TEST_VALUE: u32 = 5;
        let (_, result) = is_even(5);
        let actual: bool = TEST_VALUE % 2 == 0;
        assert_eq!(
            result,
            actual,
            "We expect the zkVM output to be {}", actual
        );
    }
}

And the rest of the host program in main.rs:

use rand::Rng;
use is_even_methods::EVEN_ID;

fn main() {
    // Initialize tracing. To view logs, run `RUST_LOG=info cargo run`
    tracing_subscriber::fmt()
        .with_env_filter(tracing_subscriber::EnvFilter::from_default_env())
        .init();

    // Generate a random number
    let mut rng = rand::thread_rng();
    let x: u32 = rng.gen::<u32>();

    let (receipt, _) = is_even(5);

    // Here is where one would send 'receipt' over the network...

    // Verify receipt, panic if it's wrong
    receipt.verify(IS_EVEN_ID).expect(
        "Code you have proven should successfully verify; did you specify the correct image ID?",
    );
}

Steel

Steel is a production-ready smart contract execution prover that enables unbounded runtime for EVM apps by proving correctness of off-chain execution without the need for writing ZK circuits.

• Steel uses revm for simulation of an EVM environment which is constructed and pre-populated in the host program before being passed as an input to the guest program.

  • EVM state can be queried within the RISC Zero zkVM using alloy’s sol! macro.

  • Merkle storage proofs are verified by the guest to validate the integrity of RPC data.

• The STARK proofs produced by the zkVM are wrapped in circom Groth16 SNARKs, which are significantly smaller and faster (read: cheaper) to verify on-chain.

  • The STARK proof control root is passed as a public input to the SNARK, allowing for updates to the RISC-V prover without requiring a new trusted setup ceremony.

  • It is recommended to use the router to forward verification to the appropriate contract. Additional details and considerations can be found in the on-chain verifier and version management design document here.

• Steel commitments, comprising a block identifier and block digest, are validated on-chain to guarantee the correctness of blockchain state associated with the Steel proof.

  • Block hash commitments are verified with the blockhash opcode, up to 256 blocks.

  • Beacon block commitments are verified with the EIP-4788 beacon root contract, extending L1 Ethereum validation time to just over 24 hours.

  • Steel history separates the execution and commitment blocks to enable state older than 24 hours to be queried, up to the Cancun upgrade date of March 13 2024.

Counter Example

Consider the trivial smart contract that allows counter to be incremented if, and only if, the ERC20 balance of the sender is at least one token:

pragma solidity ^0.8.20;

import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";

contract Counter {
    IERC20 public immutable token;

    uint256 public counter;

    constructor(address _token) {
            token = IERC20(_token);
        }

    function increment(address account) public {
        require(account == msg.sender, "Invalid sender");
        require(IERC20(token).balanceOf(account) >= token.decimals(), "Insufficient balance");

        ++counter;
    }
}

With Steel, leveraging RISC Zero as a coprocessor for efficient proof generation and verification, this becomes:

pragma solidity ^0.8.20;

import {IRiscZeroVerifier} from "risc0-ethereum/IRiscZeroVerifier.sol";
import {Steel} from "risc0-ethereum/contracts/src/steel/Steel.sol";
import {ImageID} from "./ImageID.sol"; // auto-generated contract after running `cargo build`.

contract SteelCounter {
    address public immutable token;
    IRiscZeroVerifier public immutable verifier;

    uint256 public counter;
    mapping(bytes32 => bool) public processedJournals;

    constructor(address _token, address _verifier) {
            token = _token;
            verifier = IRiscZeroVerifier(_verifier);
        }

    function increment(bytes calldata journalData, bytes calldata seal) public {
        // Decode the public outputs of the zkVM guest program
        Journal memory journal = abi.decode(journalData, (Journal));

        // Validate journal data & Steel commitment to ensure the proof can be trusted
        require(journal.token == token, "Invalid token address");
        require(journal.account == msg.sender, "Invalid sender address");
        require(Steel.validateCommitment(journal.commitment), "Invalid Steel Commitment");

        // Compute the journal hash
        bytes32 journalHash = sha256(journalData);

        // Mark the journal as processed to prevent replay
        require(!processedJournals[journalHash], "Journal already processed");
            processedJournals[journalHash] = true;

        // Verify the execution proof & increment the counter if successful
        verifier.verify(seal, imageID, journalHash);
        ++counter;
    }
}

Note that the proof is verified if, and only if, the token address, sender address, and the Steel commitment are valid. Successful verification of the RISC Zero Groth16 proof thus ensures that the account balance is at least one token, so counter is incremented without repeating EVM execution.

With on-chain verification in place, the corresponding guest program could look something like this:

#![no_main]

use alloy_primitives::{Address, U256};
use alloy_sol_types::sol;
use risc0_steel::{
    ethereum::{EthEvmInput, ETH_SEPOLIA_CHAIN_SPEC},
    Commitment, Contract,
};
use risc0_zkvm::guest::env;

risc0_zkvm::guest::entry!(main);

// Specify the function to call using the [`sol!`] macro.
// This parses the Solidity syntax to generate a struct that implements the `SolCall` trait.
sol! {
    interface IERC20 {
        function balanceOf(address account) public view returns (uint);
        function decimals() public view returns (uint);
    }
}

// ABI encodable journal data.
sol! {
    struct Journal {
        Commitment commitment;
        address token;
        address account;
    }
}

fn main() {
    // Load the EVM input, token address, and sender address from the host
    let input: EthEvmInput = env::read();
    let contract: Address = env::read();
    let sender: Address = env::read();

    // Convert the input into an `EvmEnv` for execution, specifying the chain configuration.
    // This checks that the state matches the state root in the header provided in the input.
    let env = input.into_env().with_chain_spec(&ETH_SEPOLIA_CHAIN_SPEC);

    // Execute the view call(s), returning the result in the type(s) generated by the `sol!` macro.
    let balance_call = IERC20::balanceOfCall { sender };
    let decimals_call = IERC20::decimalsCall {};
    let contract = Contract::::new(contract, &env);
    let balance = contract.call_builder(&balance_call).call();
    let decimals = contract.call_builder(&decimals_call).call();

    // Check that the given account holds at least 1 token.
    assert!(balance._0 >= U256::from(decimals));

    // Commit the block hash and number used when deriving `view_call_env` to the journal.
    let journal = Journal {
        commitment: env.into_commitment(),
        token: contract,
        account: sender
    };
    env::commit_slice(&journal.abi_encode());
}

While the host program, including the preflight calls to prepare the inputs that are required to execute the functions in the guest without RPC access, could look something like this:

use alloy_primitives::{address, Address};
use alloy_sol_types::{sol, SolCall, SolType};
use anyhow::{Context, Result};
use clap::Parser;
use erc20_methods::ERC20_GUEST_ELF;
use risc0_steel::{
    ethereum::{EthEvmEnv, ETH_SEPOLIA_CHAIN_SPEC},
    Commitment, Contract,
};
use risc0_zkvm::{default_executor, ExecutorEnv};
use tracing_subscriber::EnvFilter;
use url::Url;

sol! {
    // ERC-20 interface – must match that in the guest.
    interface IERC20 {
        function balanceOf(address account) public view returns (uint);
        function decimals() public view returns (uint);
    }
}

/// Function(s) to call, implements the [SolCall] trait.
const BALANCE_CALL: IERC20::balanceOfCall = IERC20::balanceOfCall {
    account: address!("d8dA6BF26964aF9D7eEd9e03E53415D37aA96045"), // vitalik.eth
};
const DECIMALS_CALL: IERC20::decimalsCall = IERC20::decimalsCall {};

/// Address of the deployed contract to call the function(s) on (USDT contract on Sepolia).
const CONTRACT: Address = address!("aA8E23Fb1079EA71e0a56F48a2aA51851D8433D0");
/// Address of the caller.
const CALLER: Address = address!("f08A50178dfcDe18524640EA6618a1f965821715");

#[derive(Parser, Debug)]
#[command(about, long_about = None)]
struct Args {
    /// URL of the RPC endpoint
    #[arg(short, long, env = "RPC_URL")]
    rpc_url: Url,
}

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize tracing. To view logs, run `RUST_LOG=info cargo run`
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::from_default_env())
        .init();

    // Parse the command line arguments.
    let args = Args::parse();

    // Create an EVM environment from an RPC endpoint, defaulting to the latest block.
    let mut env = EthEvmEnv::builder().rpc(args.rpc_url).build().await?;
    // The `with_chain_spec` method is used to specify the chain configuration.
    env = env.with_chain_spec(&ETH_SEPOLIA_CHAIN_SPEC);

    // Preflight the call(s) to prepare the input that is required to execute the function in
    // the guest without RPC access. It also returns the result of the call.
    let mut contract = Contract::preflight(CONTRACT, &mut env);
    let balance = contract.call_builder(&BALANCE_CALL).from(CALLER).call().await?;
    println!(
        "Call {} Function by {:#} on {:#} returns: {}",
        IERC20::balanceOfCall::SIGNATURE,
        CALLER,
        CONTRACT,
        returns._0
    );
    let decimals = contract.call_builder(&DECIMALS_CALL).from(CALLER).call().await?;
    println!(
        "Call {} Function by {:#} on {:#} returns: {}",
        IERC20::decimalsCall::SIGNATURE,
        CALLER,
        CONTRACT,
        returns._0
    );

    // Finally, construct the input from the environment.
    let input = env.into_input().await?;

    println!("Running the guest with the constructed input...");
    let session_info = {
        let env = ExecutorEnv::builder()
            .write(&input)
            .unwrap()
            .build()
            .context("failed to build executor env")?;
        let exec = default_executor();
        exec.execute(env, COUNTER_GUEST_ELF)
            .context("failed to run executor")?
    };

    // The journal should be the ABI encoded commitment.
    let commitment = Commitment::abi_decode(session_info.journal.as_ref(), true)
        .context("failed to decode journal")?;
    println!("{:?}", commitment);

    Ok(())
}

Resources

• A glossary of key terminology is available here.

• The risc0-zkvm crate can be found here. A full list of Rust crates can be found here.

• Compatibility of various crates with zkVM can be found in the nightly Crate Validation Report.

• Several example zkVM applications can be found here, with some leveraging Steel found here.

Security

• Various audits can be found in the rz-security repository.

• Several security advisories can be found in the risc0 repository.

• A bug bounty program can be found on HackenProof.

• A cryptographic security model can be found here, with details of the trusted setup here.