A much more useful AI Auditor would be one that both auditors and developers can interact with and use in their work, to both find vulnerabilities and strengthen a protocol’s defenses & unit tests prior to external audit.

This article presents Amy; a semi-autonomously evolving, freely available open-source specialist smart contract auditor, focused on Vault / ERC4626 smart contract protocols. While Amy can work with any AI platform, she has self-evolved using Claude which gives the best performance in our testing.

Priming For AI Performance

In testing various AI platforms for smart contract vulnerability detection we found that AI would miss important findings in the code we wanted to audit, unless we first showed the AI some other code. This mimics the human experience; for example a human who has recently audited many Vault protocols will likely do better when subsequently auditing a new Vault protocol.

When asking AI to audit a type of protocol, it is ideal if the AI has been primed by showing it code and vulnerabilities from similar protocols. However this approach is not scalable since it would require an AI to ingest large amounts of data prior to each individual audit.

A workaround we discovered with the help of Claude was to first ingest learning data then create a “Primer” document which encapsulates the learned material, using Claude to generate & output its own Primer. The Primer can be saved offline then in future sessions quickly ingested to effectively “prime” AI prior to audits.

AI Self-Evolution Using Priming

We created Amy by first asking her to ingest code from a Vault protocol we had audited with the vulnerabilities found, then to create and output the Primer document enabling her to recall everything she had learned in future sessions.

Using Claude Max we ran this cycle many times with additional vault audits, both private audits and public contests. After the first 3 codebases we didn’t ask Amy to ingest the code anymore, only the found vulnerabilities many which contained vulnerable code samples inside them. Using Claude and the input data we provided, Amy was effectively able to evolve herself by first writing then continually updating her Primer document.

Claude does have a number of limitations to be aware of:

• Claude can’t output a file that you can download, so instead ask it to output the updated Primer then copy & paste to save it offline

• there is a session text length limit; as the Primer becomes larger in size, if you try and ingest too much new data during one session Claude will be unable to output the full updated Primer document

• Claude did once corrupt the Primer when outputting the updated version, losing many previous findings. I caught this and asked it to write some rules in the Primer when doing updates to prevent corruption, but the rules it wrote were too restrictive

• instead of using the restrictive update rules, when asking it to output the updated Primer I started giving it more explicit instructions. This appeared to prevent future corruption while still allowing Amy great freedom in how to update the Primer document

The evolution of the Primer document is a continuous cycle of Claude sessions with the following prompts:

• “ingest this primer” (copy current primer)

• “ingest findings from PROTOCOL_NAME audit, but don’t output anything yet” (copy findings)

• potentially ask it to ingest another set of findings/heuristics etc

• less restrictive => “output the updated primer incorporating new vulnerabilities learned from this session”

• more restrictive => “output the updated primer, ensuring the version number has been incremented, the Latest Update section notes what was added, and all new data is incorporated into the Critical Vulnerability Patterns, Common Attack Vectors, Integration Hazards, Audit Checklist and any useful invariants are put into Invariant Analysis”

• as the Primer is quite long, Claude takes multiple chats to output the entire document. Once each chat is finished copy that portion then click “Continue”, copy the next and so on until you have saved the entire updated Primer document offline

• after saving the updated Primer document, start a new session to prevent hitting the session text limit and being unable to output further updates to the Primer

Focused vs General Priming

Amy’s Primer document has been created primarily by examining vulnerabilities found in audits of Vault / ERC4626 protocols; so it is these protocols that Amy should excel in auditing. That being said she does have general knowledge of many other vulnerability types so can be used on any protocol.

One option for Amy’s continued evolution is to update her Primer with vulnerabilities from other protocol types such as DAOs, Account Abstraction / Smart Wallet etc - but it is not clear whether this would negatively impact Amy’s performance during Vault / ERC4626 audits.

Another option is to use the same process to create and evolve new AI Auditors for those other protocols; for example to create Mark an AI DAO Auditor by having Mark ingest vulnerabilities from DAO audits. More research is definitely needed in this area; ideally:

• multiple Auditor AIs would be evolved, both specialist and generalist AIs

• a “test suite” of codebases would be chosen that are not used in the evolutions

• after each evolution, the AIs would be run against the “test suite” and the number of valid findings and false positives would be recorded

• each evolution could be rejected if performance degraded

For single users such as auditors and developers, the simplest option which I’ve chosen is to evolve protocol-specific AIs such as Amy who specializes in Vault / ERC4626 protocols. This approach is simple and likely to provide maximum benefit for those protocol types with minimal drawbacks if matching specialist AI Auditors to audits of their protocol type.

Amy vs Human Auditors & Static Analysis Tools

After 3 days of focused evolution in our testing on vault codebases Amy is roughly equivalent to a Junior Auditor; Amy is quickly able to find many of the same bugs that a Junior Auditor would. In internal testing on Cyfrin private smart contract audits Amy has found Critical, High, Medium & Low severity issues, some of which a Junior Auditor would be unlikely to find. Amy can also find more difficult and valuable bugs by defining a list of invariants then attempting to break them. Amy can also make recommendations that would strengthen the defensiveness of the codebase which is something that Junior Auditors typically don’t do.

Amy’s ability to rapidly self-evolve gives her a major advantage over static analysis tools which rely on human engineers to code up relatively “dumb” detectors. Similarly Amy’s ability to reason in terms of protocol-specific invariants then carefully work through possible execution paths trying to break them also gives Amy a massive advantage over traditional static analyzers.

As Amy continues to evolve and AI platforms such as Claude continue to improve, specialist AI Auditors such as Amy will largely replace Junior Auditors and static analysis tools as they can provide a superior service for only the compute cost, and are also much cheaper to upgrade since they can evolve themselves given new inputs by updating their Primer.

Senior Auditors can effectively use Amy to explore protocol invariants and whether they can be broken, get ideas for possible attack paths (and explore these together with Amy), for general understanding of the protocol, to write up findings and generate bug Proof of Concepts (PoCs). To learn how I use Amy when auditing read this post.

Developers can also greatly benefit from Amy by having her analyze their code prior to seeking external audit, having Amy list important invariants then implementing them in a fuzz testing suite. Amy can also recommend defensive / hardening measures that protocols should implement to reduce attack surface or eliminate potential attack vectors.

Limitations Of Amy

Amy is able to do a decent job of using checklists, heuristics and invariants to find vulnerabilities, but the major drawback is an inability to seriously consider external integrations and on-chain state. Amy can also misunderstand protocol code and generate false positives; some of Amy’s false positives are rather silly and trivial for a human to detect that the vulnerability is not actually there.

Amy does not replace senior human auditors but compliments them. Human auditors can use Amy effectively by correcting her misunderstandings and jointly exploring protocol attack paths, invariants, state changes, the purpose of variables and more - the only limit is human imagination.

Though Amy can be used with any protocol, her speciality is Vaults / ERC4626 hence she should be paired with these protocols for maximum benefit.

Due to Claude’s current session text limit, it does not appear practical to evolve a Primer over ~7600 lines.

Future Development

By open-sourcing Amy’s Primer document, any auditor or developer can use and evolve Amy themselves paying only the Claude compute cost. Using the methodology described in this document anyone can create and evolve their own specialist AI Smart Contract Auditor. My hope is that the smart contract security community will embrace AI, evolving an open source collection of freely available specialist AI Auditors.

Looking to work with me for a Gas Audit on your protocol? DMs are open!

We’ll use the publicly available contest source code and start by focusing on the most interesting, complicated and mission-critical liquidation function Leverager::liquidatePosition.

Measuring Gas Cost

Foundry provides a number of in-built tools to measure gas cost including:

• gas reports via forge test --gas-report after configuration in foundry.toml for contract deployment and function call costs

• test function snapshots via forge snapshot to measure the gas costs of the entire unit test suite

• gas section snapshots via cheatcodes to measure gas costs of arbitrary code segments inside unit tests

We’ll fork the original source code and use the second and third options by:

• editing test/Leverager.t.sol to add a test_Gas_* prefix around the three tests which call Leverager::liquidatePosition

• changing test/BaseTest.sol to reduce fuzz runs to 100 by editing the relevant comments to /// forge-config: default.fuzz.runs = 100 to speed up the iterative optimization cycle

• add “gas section snapshots” inside the tests functions around the calls to Leverager::liquidatePosition:

vm.startSnapshotGas("lendingPoolLiquidation");
ILeverager(leverager).liquidatePosition(liqParams);
vm.stopSnapshotGas();

vm.startSnapshotGas("liquidateWithSwap");
ILeverager(leverager).liquidatePosition(liqParams);
vm.stopSnapshotGas();

vm.startSnapshotGas("liquidationNoSwap");
ILeverager(leverager).liquidatePosition(liqParams);
vm.stopSnapshotGas();

• get the initial “test function snapshots” by running forge snapshot --fork-url ETH_RPC_URL --fork-block-number 20956198 which generates a new file .gas-snapshot recording gas costs for all unit tests and overall gas cost (second option above)

• get the initial “gas section snapshot" by running forge test --gas-snapshot-check=true --match-test test_Gas --fork-url ETH_RPC_URL --fork-block-number 20956198 which generates a file snapshots/LeveragerTest.json showing the initial gas cost for the manual snapshots wrapping calls to Leverager::liquidatePosition (third option above):

{
  "lendingPoolLiquidation": "575367",
  "liquidateWithSwap": "618080",
  "liquidationNoSwap": "439622"
}

Back up these files to .gas-snapshot.original and snapshots/LeveragerTest.original.json to maintain a starting point record for easy comparison at the end. After any code change we can then run:

• forge snapshot --diff --fork-url ETH_RPC_URL --fork-block-number 20956198 to see whether the change reduced the per-test and overall all-tests gas costs. To override the existing .gas-snapshot file simply run it without the -diff flag. Important: all tests must pass for a new .gas-snapshot file to be generated

• forge test --gas-snapshot-check=true --match-test test_Gas --fork-url ETH_RPC_URL --fork-block-number 20956198 to see whether the change reduced the gas costs of the manual snapshots. To override the existing file simply remove the old file before running this command via rm snapshots/LeveragerTest.json

Cache Identical Storage Reads

Generally the easiest and most “bang-for-buck” gas optimization is to cache identical storage reads to prevent re-reading the same value from storage multiple times. This can be resolved by:

• if a contract is not upgradeable and a storage location is only ever set once in the constructor, the storage slot should be declared immutable

• otherwise the storage slot can be read once, cached, and passed as a parameter where it is required both in the current function and to child functions

Inspecting Leverager::liquidatePosition shows some quick and easy wins:

• feeRecipient is read twice at L328,329

• swapRouter is read two to four times at L354,355,363,364

Attempting to simply cache feeReceipient fails due to a “stack too deep” error. When caching storage it is more gas efficient to use local variables within a function but if that is not possible due to “stack too deep” errors then:

• declare a struct LiquidateContext to cache storage reads for the liquidation function:

    struct LiquidateContext {
        address feeRecipient;
        address swapRouter;
    }
  

• eliminate a local variable that is only read once by passing the result of IVault(up.vault).twapPrice() directly to _calculateTokenValues

• declare a new local variable LiquidateContext memory ctx inside the liquidation function to store the cached storage reads

The changes and result are seen in commit 1661887; the gas cost reduced for one test but grew for the other two, though this is just the beginning where we are laying the groundwork for further optimizations.

It also makes sense to consolidate the Position memory pos variable inside our LiquidateContext struct and create a new _getLiquidateContext internal function to return the struct:

struct LiquidateContext {
    // read from positions[liqParams.id]
    Position pos;

    address feeRecipient;
    address swapRouter;
}

function _getLiquidateContext(uint256 _id) internal view returns(LiquidateContext memory ctx) {
    ctx.pos = positions[_id];
}

/// @notice Liquidates a certain leveraged position.
/// @dev Check the ILeverager contract for comments on all LiquidateParams arguments
/// @dev Does not support partial liquidations
/// @dev Collects fees first, in order to properly calculate whether a position is actually liquidateable
function liquidatePosition(LiquidateParams calldata liqParams) external collectFees(liqParams.id) nonReentrant {
    // read everything required from storage once
    LiquidateContext memory ctx = _getLiquidateContext(liqParams.id);

collectFees Modifier Reads Identical Storage Slots

Next examine the modifiers to see if they re-read the same storage slots; it is common for developers to write modifiers that read the same storage slots as the function body resulting in inefficient code. In this case there is only one modifier of interest collectFees which copies the entire Position into memory again resulting in 10 identical storage reads:

modifier collectFees(uint256 _id) {
    // @gas 10 identical storage reads since `Position` already read from
    // storage to memory inside `liquidatePosition` function
    Position memory up = positions[_id];
    address strat = IVault(up.vault).strategy();
    IStrategy(strat).collectFees();
    _;
}

Since the collectFees modifier is only called by the liquidatePosition function we can simply inline it to save 10 storage reads:

function liquidatePosition(LiquidateParams calldata liqParams) external nonReentrant {
    // read everything required from storage once
    LiquidateContext memory ctx = _getLiquidateContext(liqParams.id);

    // must collect fees before checking if a position is liquidatable
    IStrategy(IVault(ctx.pos.vault).strategy()).collectFees();

With this change all three tests are now more gas efficient than the original code:

$ more snapshots/LeveragerTest.json 
{
  "lendingPoolLiquidation": "574354",
  "liquidateWithSwap": "616824",
  "liquidationNoSwap": "438617"
}
$ more snapshots/LeveragerTest.original.json 
{
  "lendingPoolLiquidation": "575367",
  "liquidateWithSwap": "618080",
  "liquidationNoSwap": "439622"
}

isLiquidatable Function Reads Identical Storage Slots

Having finished with the modifiers, start working through the function body looking for child functions. The first encountered function is isLiquidatable; looking at its implementation it also copies the entire Position from storage into memory again resulting in another 10 identical storage reads:

function isLiquidatable(uint256 _id) public view returns (bool liquidatable) {
    // another 10 identical storage reads when called by `liquidatePosition`
    Position memory pos = positions[_id];

In the original code during every liquidation transaction Position was being copied into memory 3 times for 30 identical storage reads! Solve this by introducing an internal helper function _isLiquidatable which:

• takes as input the cached LiquidateContext memory ctx

• can be called by both liquidatePosition and isLiquidatable

The changes are seen in commits (143cec6, e960acf):

function liquidatePosition(LiquidateParams calldata liqParams) external nonReentrant {
    // read everything required from storage once
    LiquidateContext memory ctx = _getLiquidateContext(liqParams.id);

    // must collect fees before checking if a position is liquidatable
    IStrategy(IVault(ctx.pos.vault).strategy()).collectFees();

    require(_isLiquidateable(ctx), "isnt liquidateable");


function isLiquidateable(uint256 _id) public view returns (bool liquidateable) {
    liquidateable = _isLiquidateable(_getLiquidateContext(_id));
}

// gas: internal helper function saves reading positions[_id] multiple times during liquidations
function _isLiquidateable(LiquidateContext memory ctx) internal view returns (bool liquidateable) {
    VaultParams memory vp = vaultParams[ctx.pos.vault];

    uint256 vaultSupply = IVault(ctx.pos.vault).totalSupply();

    // Assuming a price of X, a LP position has its lowest value when the pool price is exactly X.
    // Any price movement, would actually overvalue the position.
    // For this reason, attackers cannot force a position to become liquidateable with a swap.
    (uint256 vaultBal0, uint256 vaultBal1) = IVault(ctx.pos.vault).balances();
    uint256 userBal0 = ctx.pos.shares * vaultBal0 / vaultSupply;
    uint256 userBal1 = ctx.pos.shares * vaultBal1 / vaultSupply;
    uint256 price = IVault(ctx.pos.vault).twapPrice();

    uint256 totalValueUSD = _calculateTokenValues(ctx.pos.token0, ctx.pos.token1, userBal0, userBal1, price);
    uint256 bPrice = IPriceFeed(pricefeed).getPrice(ctx.pos.denomination);
    uint256 totalDenom = totalValueUSD * (10 ** ERC20(ctx.pos.denomination).decimals()) / bPrice;

    uint256 bIndex = ILendingPool(lendingPool).getCurrentBorrowingIndex(ctx.pos.denomination);
    uint256 owedAmount = ctx.pos.borrowedAmount * bIndex / ctx.pos.borrowedIndex;

    /// here we make a calculation what would be the necessary collateral
    /// if we had the same borrowed amount, but at max leverage. Check docs for better explanation why.
    uint256 base = owedAmount * 1e18 / (vp.maxTimesLeverage - 1e18);
    base = base < ctx.pos.initCollateralValue ? base : ctx.pos.initCollateralValue;

    if (owedAmount > totalDenom || totalDenom - owedAmount < vp.minCollateralPct * base / 1e18) return true;
}

This results in further gas savings:

- [lendingPoolLiquidation] 574354 → 572916
- [liquidateWithSwap] 616824 → 615384
- [liquidationNoSwap] 438617 → 437178

_isLiquidatable Function Copies All VaultParams

Next inspecting the _isLiquidatable function observe that it:

• copies VaultParams from storage to memory

• only uses maxTimesLeverage and minCollateralPct from VaultParams

Since VaultParams is defined as:

struct VaultParams {
    bool leverageEnabled;
    uint256 maxUsdLeverage;
    uint256 maxTimesLeverage;
    uint256 minCollateralPct;
    uint256 maxCumulativeBorrowedUSD;
    uint256 currBorrowedUSD;
}

This means that _isLiquidatable is performing 4 unnecessary storage reads every time it copies VaultParams from storage to memory! Fix this by:

• expanding the LiquidateContext struct to contain the additional fields

• adding code to _getLiquidateContext to cache those fields

• changing _isLiquidatable to use the cached fields

// cache storage reads in memory
struct LiquidateContext {
    // read from positions[liqParams.id]
    Position pos;

    // read from vaultParams[pos.vault]
    uint256 maxTimesLeverage;
    uint256 minCollateralPct;

    address feeRecipient;
    address swapRouter;
}

function _getLiquidateContext(uint256 _id) internal view returns(LiquidateContext memory ctx) {
    ctx.pos = positions[_id];

    VaultParams storage vpRef = vaultParams[ctx.pos.vault];
    (ctx.maxTimesLeverage, ctx.minCollateralPct)
        = (vpRef.maxTimesLeverage, vpRef.minCollateralPct);
}

function _isLiquidatable(LiquidateContext memory ctx) internal view returns (bool liquidateable) {
    /* snip */
    uint256 base = owedAmount * 1e18 / (ctx.maxTimesLeverage - 1e18);
    base = base < ctx.pos.initCollateralValue ? base : ctx.pos.initCollateralValue;

    if (owedAmount > totalDenom || totalDenom - owedAmount < ctx.minCollateralPct * base / 1e18) return true;

Resulting in further gas savings:

- [lendingPoolLiquidation] 572916 → 572396
- [liquidateWithSwap] 615384 → 614864
- [liquidationNoSwap] 437178 → 436658

pricefeed Identical Reads In liquidatePosition & _isLiquidatable

A common mistake developers make is re-reading identical values from storage in child functions called by parent functions; in this case:

• liquidatePosition calls _isLiquidatable which reads pricefeed from storage into memory

• liquidatePosition itself reads pricefeed again, resulting in a duplicate storage read

Fix this by:

• adding priceFeed to struct LiquidateContext

• reading it once inside getLiquidateContext

• reading it from the cached copy in _isLiquidatable and liquidatePosition

This again reduces the gas costs across the board:

- [lendingPoolLiquidation] 572396 → 572345
- [liquidateWithSwap] 614864 → 614813
- [liquidationNoSwap] 436658 → 436608

pricefeed Identical Reads In _calculateTokenValues

Continuing to examine the _isLiquidatable child function, observe it:

• calls _calculateTokenValues which is also called by the main function liquidatePosition

• _calculateTokenValues reads the same identical value of pricefeed from storage up to 4 times:

if (IPriceFeed(pricefeed).hasPriceFeed(token0)) {
    chPrice0 = IPriceFeed(pricefeed).getPrice(token0);
    usdValue += amount0 * chPrice0 / decimals0;
}
if (IPriceFeed(pricefeed).hasPriceFeed(token1)) {
    chPrice1 = IPriceFeed(pricefeed).getPrice(token1);
    usdValue += amount1 * chPrice1 / decimals1;
}

This is easily fixed by changing _calculateTokenValues to take the cached pricefeed as input, resulting in even greater gas savings:

- [lendingPoolLiquidation] 572345 → 571293
- [liquidateWithSwap] 614813 → 613761
- [liquidationNoSwap] 436608 → 435556

Leverager Further Optimizations

Further but potentially unsafe gas optimizations could be made by:

• caching the result of external calls such as ILendingPool(lendingPool).getCurrentBorrowingIndex(ctx.pos.denomination)

• using this to cache the calculated owedAmount

Ideally duplicate computations and external calls should be cached if it is safe to do so, but this would be unsafe if it is intended that later duplicate computations and external calls can return different values. Caching is only a safe optimization when the same value is read from storage (or received from an external call) multiple times.

Additional safe gas optimizations made to other Leverager functions include:

• cache swapRouter in openLeveragedPosition and in withdraw

• don’t read new position from storage in openLeveragePosition

• pass cached price feed when building new liquidation context in openLeveragedPosition

• revert if new position is liquidatable prior to writing to storage

• revert fast prior to reading storage in withdraw

• read only required VaultParams and fail fast in _checkWithinLimits

Leverager High Finding - feeRecipient Never Set

One heuristic to look for when doing gas optimizations in non-upgradeable contracts is storage slots which can be set to immutable if they are only set once in the constructor. When checking all Leverager storage slots I found that feeRecipient is never set anywhere meaning that either:

• all the fees will be sent to the zero address for tokens which allow this, or

• liquidation will be bricked for tokens which revert when sending tokens to the zero address

Strategy High Finding - Incorrect Upper Tick in collectFees

While looking for identical storage reads to cache I noticed this code block where the third call to collectPositionFees was re-reading mainPosition.tickUpper from storage when it likely shouldn’t be:

if (mainPosition.liquidity != 0) collectPositionFees(mainPosition.tickLower, mainPosition.tickUpper);
if (secondaryPosition.liquidity != 0) {
    collectPositionFees(secondaryPosition.tickLower, secondaryPosition.tickUpper);
}
if (ongoingVestingPosition) {
    // @audit `mainPosition.tickUpper` likely not intended to be read from
    // storage again here, should be `vestPosition.tickUpper`
    collectPositionFees(vestPosition.tickLower, mainPosition.tickUpper);
}

The impact is that Strategy::collectFees may revert or fail to collect the correct fees since it is passing the wrong upper tick.

LendingPool Gas Optimizations

Similar gas optimizations can be made to the LendingPool contract including:

• don’t initialize to default values

• cache yTokenAddress in redeem and deposit

• cache totalBorrows in repay

• don’t copy entire ReserveData in pullFunds, pushFunds and getLeverageParams

Strategy Gas Optimizations

The Strategy contract can also benefit from the following gas optimizations:

• use immutable for storage slots only set once in constructor

• cache ongoingVestingPosition, protocolFee and feeRecipient in collectFees

• cache tickTwapDeviation in _priceWithinRange

• cache maxObservationDeviation in checkPoolActivity

• cache twap in twapTick

• cache new lower/upper ticks in _setSecondaryPositionsTicks

• use cached VestingPosition for final check in _withdrawPartOfVestingPosition

• in rebalance cache updated ticks and use when adding liquidity

• cache twap inside _priceWithinRange and pass to child functions

• in rebalance cache main/secondary positions and use cache when collecting fees and removing positions

Vault Gas Optimizations

The Vault contract was improved with some minor gas optimizations:

• make token0 and token1 immutable

• cache strategy and depositFee in deposit

• cache strategy in withdraw and addVestingPosition

Internal Library Gas Optimizations

Internal libraries which execute functions over storage references also benefit from gas optimizations:

• cache several fields used in InterestRateUtils::calculateBorrowingRate

• cache lastUpdateTimestamp in ReserveLogic::latestBorrowingIndex

• lazy loading, storage caching and only write to storage if values changed in ReserveLogic::_updateIndexes

• cache borrowingIndex in ReserveLogic::borrowedLiquidity

Interim Gas Optimization Results

Run forge snapshot --diff --fork-url ETH_RPC_URL --fork-block-number 20956198 to get the “test function snapshots” gas output:

test_canDepositAtAnyPrice(uint256,uint256,uint256) (gas: -9887 (-1.166%)) 
test_canDepositAtAnyPrice(uint256,uint256,uint256) (gas: -9931 (-1.170%)) 
test_compound() (gas: -15758 (-1.207%)) 
test_compound() (gas: -15758 (-1.207%)) 
test_addVestingPosition() (gas: -19229 (-1.217%)) 
test_addVestingPosition() (gas: -19229 (-1.217%)) 
test_fuzzDepositAndWithdraw(uint256,uint256) (gas: -10083 (-1.376%)) 
test_fuzzDepositAndWithdraw(uint256,uint256) (gas: -10086 (-1.376%)) 
test_Gas_LendingPool() (gas: -40343 (-1.465%)) 
test_fuzzRebalance(uint256,uint256) (gas: -11360 (-1.478%)) 
test_fuzzRebalance(uint256,uint256) (gas: -11361 (-1.478%)) 
test_cantOpenPositionDueToVolatileVault() (gas: -14377 (-1.562%)) 
test_fuzzDepositWithdrawRemainRatio(uint256) (gas: -19643 (-1.634%)) 
test_fuzzDepositWithdrawRemainRatio(uint256) (gas: -19660 (-1.636%)) 
testDeposit() (gas: -16235 (-1.735%)) 
testDeposit() (gas: -16236 (-1.735%)) 
test_LendingPoolRepaymentFromBorrower() (gas: -30923 (-1.738%)) 
test_LendingPoolRepaymentAndClaim() (gas: -30923 (-1.802%)) 
test_borrowInThirdToken() (gas: -62728 (-2.585%)) 
test_partialWithdraw() (gas: -67099 (-2.880%)) 
test_vaultLimitsWork2() (gas: -55670 (-2.916%)) 
test_fuzzWithdraw(uint256) (gas: -10889 (-2.960%)) 
test_fuzzWithdraw(uint256) (gas: -10893 (-2.961%)) 
test_vaultLimitsWork1() (gas: -61307 (-3.212%)) 
test_Gas_liquidationNoSwap() (gas: -84678 (-3.814%)) 
test_Gas_liquidationWithSwap() (gas: -85708 (-3.840%)) 
test_cantOpenPositionWhenReserveInactive() (gas: -68329 (-4.091%)) 
test_lendingRate() (gas: -70875 (-4.276%)) 
test_permissionedFunctions() (gas: -108575 (-4.305%)) 
test_borrowToken1() (gas: -69476 (-4.594%)) 
test_cantOpenDueToPoolPriceOff() (gas: 0 (NaN%)) 
Overall gas change: -1077249 (-2.503%)

So far across the entire test suite we’ve reduced gas costs by 1.166% → 4.594% with an overall gas reduction of 2.503% saving 1,077,249 gas, largely by refactoring the existing Solidity code to reduce the amount of identical storage reads.

External Library Gas Optimizations

The protocol uses a number of external libraries from OpenZeppelin. Further gas savings can be realized by changing the contracts to use similar functions from Solady. First install Solady using:

• forge install Vectorized/solady

• add "@solady/=lib/solady/src/", to foundry.toml remappings

Next systematically change the protocol’s contracts to use Solady libraries instead of OpenZeppelin:

• Solady ERC20, SafeTransferLib and ReentrancyGuardTransient in yToken

• Solady ERC20, SafeTransferLib and Ownable in Vault

• Solady SafeTransferLib, Ownable and FixedPointMathLib in Strategy

• Solady ERC721, Ownable, SafeTransferLib and ReentrancyGuardTransient in Leverager

• Solady Ownable, SafeTransferLib and ReentrancyGuardTransient in LendingPool

• Solady FixedPointMathLib in LiquidtyAmounts

With the optimized external libraries run forge snapshot --diff --fork-url ETH_RPC_URL --fork-block-number 20956198 to refresh the “test function snapshots” gas output:

test_compound() (gas: -20293 (-1.555%)) 
test_compound() (gas: -20293 (-1.555%)) 
test_canDepositAtAnyPrice(uint256,uint256,uint256) (gas: -14501 (-1.711%)) 
test_addVestingPosition() (gas: -28079 (-1.777%)) 
test_addVestingPosition() (gas: -28080 (-1.777%)) 
test_canDepositAtAnyPrice(uint256,uint256,uint256) (gas: -15237 (-1.796%)) 
test_fuzzRebalance(uint256,uint256) (gas: -15522 (-2.019%)) 
test_fuzzRebalance(uint256,uint256) (gas: -15522 (-2.019%)) 
test_fuzzDepositAndWithdraw(uint256,uint256) (gas: -15992 (-2.183%)) 
test_fuzzDepositAndWithdraw(uint256,uint256) (gas: -15994 (-2.183%)) 
test_fuzzDepositWithdrawRemainRatio(uint256) (gas: -27003 (-2.247%)) 
test_fuzzDepositWithdrawRemainRatio(uint256) (gas: -27004 (-2.247%)) 
testDeposit() (gas: -21996 (-2.351%)) 
testDeposit() (gas: -21996 (-2.351%)) 
test_cantOpenPositionDueToVolatileVault() (gas: -27920 (-3.034%)) 
test_Gas_LendingPool() (gas: -85556 (-3.107%)) 
test_fuzzWithdraw(uint256) (gas: -12440 (-3.382%)) 
test_fuzzWithdraw(uint256) (gas: -12444 (-3.382%)) 
test_permissionedFunctions() (gas: -94015 (-3.728%)) 
test_LendingPoolRepaymentFromBorrower() (gas: -78629 (-4.418%)) 
test_LendingPoolRepaymentAndClaim() (gas: -78069 (-4.548%)) 
test_partialWithdraw() (gas: -125069 (-5.367%)) 
test_borrowInThirdToken() (gas: -135182 (-5.570%)) 
test_lendingRate() (gas: -92864 (-5.602%)) 
test_vaultLimitsWork2() (gas: -110189 (-5.773%)) 
test_borrowToken1() (gas: -89333 (-5.907%)) 
test_cantOpenPositionWhenReserveInactive() (gas: -98835 (-5.917%)) 
test_vaultLimitsWork1() (gas: -115929 (-6.073%)) 
test_Gas_liquidationNoSwap() (gas: -136030 (-6.126%)) 
test_Gas_liquidationWithSwap() (gas: -138334 (-6.198%)) 
test_cantOpenDueToPoolPriceOff() (gas: 0 (NaN%)) 
Overall gas change: -1718350 (-3.992%)

Optimizing the external libraries increased:

• minimum gas saving from 1.166% to 1.555%

• maximum gas saving from 4.594% to 6.198%

• overall gas saving from 2.503% to 3.992%, saving 1,718,350 gas instead of only 1,077,249 which is a nice 37% improvement!

Enabling The Optimizer

We can do even better by adding the following to foundry.toml to enable the optimizer:

optimizer = true
optimizer_runs = 1_000_000

Now running forge snapshot --diff --fork-url ETH_RPC_URL --fork-block-number 20956198 to refresh the “test function snapshots” gas output gives:

test_fuzzWithdraw(uint256) (gas: -29626 (-8.053%)) 
test_fuzzWithdraw(uint256) (gas: -29628 (-8.054%)) 
test_compound() (gas: -139490 (-10.689%)) 
test_compound() (gas: -139525 (-10.691%)) 
test_fuzzDepositWithdrawRemainRatio(uint256) (gas: -143294 (-11.923%)) 
test_fuzzDepositWithdrawRemainRatio(uint256) (gas: -143340 (-11.927%)) 
test_addVestingPosition() (gas: -201759 (-12.766%)) 
test_addVestingPosition() (gas: -201764 (-12.767%)) 
test_Gas_LendingPool() (gas: -390653 (-14.188%)) 
test_canDepositAtAnyPrice(uint256,uint256,uint256) (gas: -120991 (-14.260%)) 
test_canDepositAtAnyPrice(uint256,uint256,uint256) (gas: -120980 (-14.271%)) 
test_borrowInThirdToken() (gas: -354141 (-14.593%)) 
test_partialWithdraw() (gas: -341000 (-14.634%)) 
testDeposit() (gas: -137266 (-14.672%)) 
testDeposit() (gas: -137286 (-14.673%)) 
test_LendingPoolRepaymentAndClaim() (gas: -261501 (-15.235%)) 
test_cantOpenPositionDueToVolatileVault() (gas: -141161 (-15.338%)) 
test_LendingPoolRepaymentFromBorrower() (gas: -273610 (-15.374%)) 
test_fuzzRebalance(uint256,uint256) (gas: -119467 (-15.540%)) 
test_fuzzRebalance(uint256,uint256) (gas: -119520 (-15.546%)) 
test_Gas_liquidationWithSwap() (gas: -351131 (-15.731%)) 
test_vaultLimitsWork2() (gas: -300941 (-15.765%)) 
test_vaultLimitsWork1() (gas: -305623 (-16.010%)) 
test_fuzzDepositAndWithdraw(uint256,uint256) (gas: -120873 (-16.496%)) 
test_fuzzDepositAndWithdraw(uint256,uint256) (gas: -120924 (-16.502%)) 
test_Gas_liquidationNoSwap() (gas: -367226 (-16.539%)) 
test_lendingRate() (gas: -286293 (-17.271%)) 
test_borrowToken1() (gas: -265396 (-17.548%)) 
test_cantOpenPositionWhenReserveInactive() (gas: -293424 (-17.566%)) 
test_permissionedFunctions() (gas: -684835 (-27.154%)) 
test_cantOpenDueToPoolPriceOff() (gas: 0 (NaN%)) 
Overall gas change: -6642668 (-15.434%)

Enabling the optimizer has provided major gas improvements across the board, increasing:

• minimum gas saving from 1.555% to 8.053%

• maximum gas saving from 6.198% to 27.154%

• overall gas saving from 3.992% to 15.434%, saving 6,642,668 gas instead of only 1,718,350 resulting in an amazing 3.86x improvement!

Finally let’s get the “gas section snapshots” we put around the key Leverager::liquidatePosition function by running forge test --gas-snapshot-check=true --match-test test_Gas --fork-url ETH_RPC_URL --fork-block-number 20956198:

- [lendingPoolLiquidation] 575367 → 484711 (-15.75%)
- [liquidateWithSwap] 618080 → 536423 (-13.211%)
- [liquidationNoSwap] 439622 → 365286 (-16.909%)

We’ve reduced the gas cost of calling Leverager::liquidatePosition by anywhere from 13.211% to 16.909% which matches well with the previously observed overall gas reduction of 15.434%.

Looking to work with me for a Gas Audit on your protocol? DMs are open!

Additional Resources

• Solidity Gas Optimization Examples

• Solidity Gas Optimization Tips

• Solidity Gas Optimization CheatSheet

• Book of Solidity Gas Optimizations

Two common terms frequently used with their definitions:

• Liquidatable : collateral_value * loan_to_value_ratio < borrow_value
  - sufficient collateral remains to cover the borrow
  - no bad debt is created if promptly liquidated

• Insolvent : collateral_value < borrow_value
  - insufficient collateral remains to cover the borrow
  - creates bad debt for the protocol even after liquidation

The goal of liquidation is to avoid bad debt by promptly liquidating “Liquidatable” positions so they do not become “Insolvent”.

No Liquidation Incentive

Many decentralized protocols don’t use trusted liquidators but allow any address to perform “trustless” liquidation. To incentivize prompt and efficient trustless liquidators such protocols offer a liquidation incentive usually in the form of a liquidation “bonus” or “reward”.

Incentivized trustless liquidators (usually in the form of MEV bots) promptly liquidate any liquidatable positions if the liquidation incentive is greater than the gas cost to perform the liquidation, generating small risk-free profits on a consistent basis.

Heuristic: if the protocol relies on trustless liquidators, does it incentivize liquidators via a reward or bonus?

No Incentive To Liquidate Small Positions

If the protocol does not enforce minimum deposits and position sizes, small positions can accumulate which trustless liquidators have no incentive to liquidate. An accumulation of insolvent small positions can theoretically be especially problematic for stablecoin protocols by allowing bad debt to accumulate causing the protocol to become under-collateralized.

In addition to enforcing minimum position size for new positions, for protocols that allow:

• modification of an existing position size, the final position size should be checked to not be too small

• partial liquidation, a partial liquidation should not result in the remaining debt position being too small

Heuristic: does the protocol enforce minimum position size? Is this enforced in every function which can change position size, or only when opening a new position?

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

Profitable User Withdraws All Collateral Removing Liquidation Incentive

In trading protocols such as perpetuals, users with open long/short positions have their current profit/loss (PNL) counted when determining the total value of their collateral. When a user’s position has a large positive PNL, that user may be able to withdraw most or even all of their deposited collateral while continuing to remain solvent.

If the user’s PNL subsequently declines the position will become liquidatable. However since the user has withdrawn their collateral there is nothing to seize and give as incentive to the liquidator beyond the remaining positive PNL. The lack of collateral may result insufficient liquidation incentive (or even a panic revert when attempting liquidation) causing the position to not be liquidated and subsequently become insolvent.

A simple mitigation is to always ensure that a user with open trading positions must have a minimal amount of collateral deposited regardless of their potentially large positive PNL. Another mitigation may be to “discount” positive PNL such that it doesn’t provide the same “collateral weight” compared to actually deposited collateral.

Allowing users to borrow deposited collateral without limits can also be dangerous as it can lead to the same state.

Heuristic: can a profitable user withdraw their deposited collateral? If yes, what happens if the market reverses and the user becomes unprofitable?

More examples: [1]

No Mechanism To Handle Bad Debt

A liquidatable position if not promptly liquidated can reach an insolvent state where the liquidation reward and seized collateral received for liquidating the position is worth less than the debt tokens required to resolve the bad debt and liquidate the position.

In such a scenario trustless liquidators have no incentive to liquidate the position, allowing bad debt to accrue in the protocol. Protocols may also not account for this state causing the liquidation transaction to panic revert, making liquidation of insolvent positions impossible. This issue can be mitigated by:

• operating trusted liquidators which promptly liquidate all liquidatable positions

• having an “insurance fund” typically funded via protocol fees which can absorb the bad debt such that trustless liquidators still profit from liquidating normally unprofitable positions

• socializing bad debt amongst protocol users such as liquidity providers

Heuristic: does the protocol implement a mechanism to handle bad debt? What happens when an insolvent position gets liquidated?

More examples: [1, 2]

Partial Liquidation Bypasses Bad Debt Accounting

Consider this liquidation code:

// additional processing when position closed by liquidation
if (!hasPosition) {
    int256 remainingMargin = vault.margin;

    // credit positive margin to vault recipient
    if (remainingMargin > 0) {
        if (vault.recipient != address(0)) {
            vault.margin = 0;

            sentMarginAmount = uint256(remainingMargin);

            ERC20(pairStatus.quotePool.token).safeTransfer(
                vault.recipient, sentMarginAmount);
        }
    }
    // otherwise ensure liquidator covers bad debt
    else if (remainingMargin < 0) {
        vault.margin = 0;

        // any losses that cannot be covered by the vault
        // must be compensated by the liquidator
        ERC20(pairStatus.quotePool.token).safeTransferFrom(
            msg.sender, address(this), uint256(-remainingMargin));
    }
}

If the liquidation transaction was a full liquidation that closed the position, this code ensures that the liquidator covers any bad debt associated with the position. However as this check only occurs if the position was completely liquidated, a partial liquidator can bypass this check by not liquidating the entire position.

This allows a liquidator to bypass the bad debt accounting allowing bad debt to accrue within the protocol. One potential mitigation is to ensure that when partial liquidations are performed on an insolvent position, the corresponding amount of the position’s bad debt is covered by the insurance fund or bad debt socialization mechanism.

Heuristic: is bad debt accounted for during partial liquidation of an insolvent position?

No Partial Liquidation Prevents Whale Liquidation

In protocols where trustless liquidators supply the debt tokens required to resolve a borrower’s bad debt, partial liquidation should be supported to allow liquidators to liquidate portions of large liquidatable positions. If partial liquidation is not supported this makes it impossible to liquidate large liquidatable positions opened by whales since individual liquidators may not have enough tokens to resolve the large debt.

Flash loans can be used to liquidate large positions but only if the loan size does not exceed current market liquidity - which is not guaranteed to always be true.

Heuristic: does the protocol support partial liquidation? If not, how can a whale user be liquidated? Are there other safeguards such as caps on maximum position size? If so, how effective are these additional safeguards at ensuring the largest possible position can be liquidated?

Liquidation Denial Of Service

If an attacker can permanently cause liquidations to revert or prevent themselves from being liquidated, this represents a critical danger to the solvency of many protocols as it allows bad debt to build up in the system. Several known attack paths have been found in audits of real-world protocols:

Attacker Uses Many Small Positions To Prevent Liquidation

Consider the following liquidation code which iterates over all of a user’s current positions:

function _removePosition(uint256 positionId) internal {
    address trader = userPositions[positionId].owner;
    positionIDs[trader].removeItem(positionId);
}

// @audit called by `_removePosition`
function removeItem(uint256[] storage items, uint256 item) internal {
    uint256 index = getItemIndex(items, item);

    removeItemByIndex(items, index);
}

// @audit called by `removeItem`
function getItemIndex(uint256[] memory items, uint256 item) internal pure returns (uint256) {
    uint256 index = type(uint256).max;

    // @audit OOG revert for large items.length
    for (uint256 i = 0; i < items.length; i++) {
        if (items[i] == item) {
            index = i;
            break;
        }
    }

    return index;
}

A malicious user could exploit this for loop to make themselves impossible to liquidate by opening many small positions and allowing the last position to become liquidatable; whenever a liquidator attempts to liquidate that last position the liquidation will revert due to out of gas. This issue can be mitigated by:

• enforcing a minimum position size to prevent many “dust” positions

• using a mapping or other data structure that prevents iterating over every position

Heuristic: does the protocol iterate over an unbounded list which the users can add items to? Is there a minimum position size enforced?

More examples: [1, 2, 3]

Attacker Uses Multiple Positions To Prevent Liquidation

In some protocols where a user can have multiple open positions, their health score is considered collectively across all positions to determine whether that user is subject to liquidation. In these protocols when liquidation occurs all of a user’s open positions are liquidated in the same transaction.

Consider the following code:

// load open markets for account being liquidated
ctx.amountOfOpenPositions = tradingAccount.activeMarketsIds.length();

// iterate through open markets
for (uint256 j = 0; j < ctx.amountOfOpenPositions; j++) {
    // load current active market id into working data
    // @audit assumes constant ordering of active markets
    ctx.marketId = tradingAccount.activeMarketsIds.at(j).toUint128();

    // snip - a bunch of liquidation processing code //

    // remove this active market from the account
    // @audit this calls `EnumerableSet::remove` which changes the order of `activeMarketIds`
    tradingAccount.updateActiveMarkets(ctx.marketId, ctx.oldPositionSizeX18, SD_ZERO);

Because EnumerableSet provides no guarantees that the order of elements is preserved and its remove function uses the swap-and-pop method for performance reasons, the ordering of a user’s active markets will be corrupted when an active market is removed if that active market is not the last active market for that user.

A malicious user can weaponize this to make their account impossible to liquidate by opening multiple positions and triggering this corruption, causing any liquidation attempt to revert with panic: array out-of-bounds access.

A simple way to prevent this issue is to iterate over a memory copy of activeMarketIds by calling EnumerableSet::values instead of iterating over the storage directly.

Heuristic: can a user with multiple open positions be liquidated? Does the test suite contain a test for this scenario?

Attacker Uses Front-Run To Prevent Liquidation

Can a liquidatable user change variables used during the liquidation transaction such that this change would cause liquidation to revert? If so a user can make themselves impossible to liquidate by front-running any liquidation transaction to make the required changes and hence cause that transaction to subsequently revert. Some examples include blocking liquidation by:

• incrementing the nonce

• partial (very small) self-liquidation which prevents liquidation in the same block or for a longer period by resetting a cool-down

Heuristic: is there any user-controlled variable that makes liquidation revert? If so, can a liquidatable user front-run the liquidation transaction to change this variable forcing liquidation to revert? What actions can a liquidatable user perform, and should they be able to perform those actions?

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

Attacker Uses Pending Action To Prevent Liquidation

Consider this check during liquidation:

require(balance - (withdrawalPendingAmount + depositPendingAmount) > 0);

A malicious user can abuse this by creating a pending withdrawal equal to their balance which forces all subsequent liquidation attempts to revert, making themselves impossible to liquidate. A simple mitigation is to prevent users who are subject to liquidation from performing many protocol functions such as deposits, withdrawals and swaps, though this still leaves an edge case when an innocent user had a pending withdrawal then became subject to liquidation.

An attacker may also be able to use protocol functions while being in a liquidatable state to profit from the subsequent liquidation - protocols should carefully evaluate which actions if any a liquidatable user can perform.

Heuristic: are there any actions which take several transactions over multiple blocks to complete? If so, what happens when a user is liquidated while these actions are in a “pending” state? What actions can a liquidatable user perform, and should they be able to perform those actions?

More examples: [1, 2]

Attacker Uses Malicious onERC721Received Callback To Prevent Liquidation

If an NFT ERC721 token is “pushed” to an attacker-controlled address during liquidation, the attacker can configure their deployed contract at that address to revert in the onERC721Received callback function making it impossible for them to be liquidated.

A simple mitigation is to implement a “pull” function by which ERC721 token owners can retrieve their NFT in a separate transaction.

The same attack can occur if an ERC20 token used for liquidation settlement contains transfer hooks.

Heuristic: if liquidation uses “push” to send tokens, can an attacker leverage callbacks to force the liquidation to revert?

Attacker Uses Yield Vault To Prevent Collateral Seizure During Liquidation

Multi-collateral protocols may allow users to deposit their collateral into vaults or farms which generate yield to achieve maximum capital efficiency for users’ deposited collateral. Such protocols must ensure they correctly account for collateral deposited into yield vaults and generated yield when:

• calculating minimum collateral required to avoid liquidation

• seizing collateral and generated yield during liquidation

If the first is implemented but not the second, an attacker can drain the protocol by:

• taking a loan against their deposited collateral

• allowing the loan to be liquidated

• withdrawing their collateral & yield from the vault/farm

Smart contract auditors should carefully check that all instruments which can be used as collateral are accounted for during liquidation and that any other contracts where collateral can be deposited or registered are notified of the liquidation.

Heuristic: are there any features which allow users to do interesting things such as earning yield with their deposited collateral? If so, is the liquidation code aware of and integrated with the additional features? Can a user “hide” their deposited collateral anywhere the liquidation code is not aware of?

More examples: [1]

Liquidation Reverts When Bad Debt Greater Than Insurance Fund

For protocols that use an insurance fund to cover bad debt, liquidation will revert if the bad debt is larger than the insurance fund unless the protocol has special handling for this edge-case. Such protocols can enter into and indefinitely remain in a state where large insolvent positions are unable to be liquidated until the insurance fund accrues enough fees to cover the bad debt.

Heuristic: what happens when the bad debt from liquidating an insolvent position is greater than the amount in the insurance fund?

More examples: [1]

Liquidation Reverts From Insufficient Funds Due To Fixed Liquidation Bonus

Consider this code which aims to always provide a fixed 10% liquidation bonus in the form of additional seized collateral to the liquidator:

uint256 tokenAmountFromDebtCovered = getTokenAmountFromUsd(collateral, debtToCover);
// liquidator always receives 10% bonus
uint256 bonusCollateral = (tokenAmountFromDebtCovered * LIQUIDATION_BONUS) / LIQUIDATION_PRECISION;
_redeemCollateral(collateral, tokenAmountFromDebtCovered + bonusCollateral, user, msg.sender);

The fixed liquidation bonus causes liquidation to revert when the user has a < 110% collateral ratio since there is insufficient collateral to pay the bonus, even though at < 110% the user in that protocol was considered under-collateralized and subject to liquidation. A simple mitigation is to check whether the borrower has sufficient collateral to provide the bonus and if not then cap the bonus to the maximum possible amount.

Heuristic: what happens if there is not enough collateral to cover the liquidation bonus?

More examples: [1, 2]

Liquidation Reverts For Non-18 Decimal Collateral

Multi-collateral protocols can support a wide range of collateral some of which don’t use standard ERC20 18 decimal precision. Protocols usually employ a strategy which uses:

• 18 decimals for all internal calculation and storage

• native token decimals when transferring tokens

• native token decimals in external function inputs that users call

This strategy works well when consistently used however in large protocols with multiple developers an inconsistency can easily slip in; auditors should always verify that liquidation works correctly when either the collateral token or the debt token does not have 18 decimal places.

Heuristic: does liquidation work correctly when tokens use different decimal precision?

Liquidation Reverts Due To Multiple nonReentrancy Modifiers

In larger protocols liquidation code can be quite complicated involving optional calls to multiple other contracts. Smart contract auditors should carefully verify that there is no execution path through which two functions with the nonReentrant modifier are called on the same contract, causing liquidation to revert.

Heuristic: are there any liquidation execution paths that would hit multiple nonReentrant modifiers in the same contract?

Liquidation Reverts From Zero Value Token Transfers

Liquidation code usually involves calculating multiple token amounts such as the liquidator reward and associated fees followed by multiple token transfers. If there is no zero value checks prior to token transfers this can cause liquidation to revert with tokens that revert on zero value transfer.

Heuristic: does the protocol do zero value checks before token transfers? If not, does it support tokens which revert on zero token transfer?

More examples: [1]

Liquidation Reverts From Token Deny List

Some tokens such as USDC implement “deny lists” which allow token admins to freeze user funds, causing all transfer attempts to revert for addresses on the deny list. Many liquidation implementations use “push” mechanisms which send token amounts to different addresses during the liquidation transaction. If the protocol supports tokens which use deny lists and any of the addresses sent tokens during liquidation are on the deny list, then liquidation will revert due to deny list making it impossible to liquidate that position.

As the risk is low many protocols choose to simply acknowledge this risk, but one slightly more complicated mitigation is allowing users to claim tokens (“pull”) instead of sending them out (“push”).

Heuristic: does the protocol use “push” during liquidation and support tokens with deny lists? If so, what happens during liquidation when sending tokens to blocked users?

More examples: [1, 2, 3]

Impossible To Liquidate When Only One Borrower

Consider this liquidation logic:

// get number of borrowers
uint256 troveCount = troveManager.getTroveOwnersCount();

// only process liquidations when more than 1 borrower
while (trovesRemaining > 0 && troveCount > 1) {

This code fails to liquidate if there is only one borrower. This is a design flaw as even if there is only one borrower, the borrower should still be subject to liquidation if their position becomes liquidatable.

Heuristic: if there is only one borrower, can that user be liquidated?

More examples: [1]

Incorrect Liquidation Calculations

During a liquidation there are many required calculations such as the value of collateral, the amount of bad debt, calculation of liquidator rewards and fees. Subtle errors can slip into these calculations with disastrous effects:

Incorrect Calculation Of Liquidator Reward

Liquidation can often involve dealing with debt and collateral tokens which use different decimal precisions. Errors when handling precision differences between debt and collateral tokens can result in the calculated liquidation reward being:

• too small so there will be no incentive to liquidate

• too large so liquidators will receive much more than they should

Consider this simplified code:

function executeLiquidate(State storage state, LiquidateParams calldata params)
    external returns (uint256 liquidatorProfitCollateralToken) {

    // @audit debtPosition = USDC using 6 decimals
    DebtPosition storage debtPosition = state.getDebtPosition(params.debtPositionId);

    // @audit assignedCollateral = WETH using 18 decimals
    uint256 assignedCollateral = state.getDebtPositionAssignedCollateral(debtPosition);

    // @audit debtPosition.futureValue = USDC using 6 decimals
    //        debtInCollateralToken = WETH using 18 decimals
    uint256 debtInCollateralToken = state.debtTokenAmountToCollateralTokenAmount(debtPosition.futureValue);

    if (assignedCollateral > debtInCollateralToken) {
        uint256 liquidatorReward = Math.min(
            assignedCollateral - debtInCollateralToken,
            // @audit liquidatorReward calculated using debtPosition.futureValue using
            // 6 decimals instead of debtInCollateralToken using 18 decimals, even though
            // liquidation reward is paid in WETH collateral which uses 18 decimals 
            Math.mulDivUp(debtPosition.futureValue, state.feeConfig.liquidationRewardPercent, PERCENT)
            // @audit should be:
         // Math.mulDivUp(debtInCollateralToken, ...)

        );

This liquidation functions pays out the liquidation reward using the collateral token (WETH with 18 decimals), but it is calculating the liquidation reward paid out using the debt token position (USDC with 6 decimals). Hence liquidators won’t be incentivized as their expected reward will be dramatically reduced.

The liquidation reward should scale linearly such that if the total borrow amount is identical, borrowing against 3 lenders using one account should result in the liquidation reward being roughly the same as borrowing against 3 lenders using 3 individual accounts.

Incorrect calculation of liquidation reward can occur due to many different errors in the reward calculation; there is no clear heuristic so auditors need to carefully examine the particular implementation for all sorts of errors. More examples: [1, 2, 3, 4, 5, 6, 7, 8, 9]

Failure To Prioritize Liquidation Reward

During liquidation there may be a number of associated fees that need to be paid to different entities. If there is insufficient collateral (or insurance fund in the case of bad debt) to pay out all the fees, the protocol should prioritize paying the liquidation reward in order to incentivize prompt liquidation.

Heuristic: what happens if there is not enough collateral to pay out all the fees as part of a liquidation? Is the liquidator reward prioritized - especially in protocols relying on trustless liquidators?

Incorrect Calculation Of Protocol Liquidation Fee

Some protocols charge a “protocol fee” which the liquidator or user being liquidated pays during a liquidation. If this fee is incorrectly calculated to be larger than it should be, this can make many liquidations unprofitable which removes the incentive to liquidate causing bad debt to accrue in the protocol. Consider this protocol liquidation fee calculation code:

function _transferAssetsToLiquidator(address position, AssetData[] calldata assetData) internal {
    // transfer position assets to the liquidator and accrue protocol liquidation fees
    uint256 assetDataLength = assetData.length;
    for (uint256 i; i < assetDataLength; ++i) {
        // ensure assetData[i] is in the position asset list
        if (Position(payable(position)).hasAsset(assetData[i].asset) == false) {
            revert PositionManager_SeizeInvalidAsset(position, assetData[i].asset);
        }
        // compute fee amt
        // [ROUND] liquidation fee is rounded down, in favor of the liquidator
        // @audit liquidator fee calculated from seized collateral amount
        //         makes many liquidations unprofitable
        uint256 fee = liquidationFee.mulDiv(assetData[i].amt, 1e18);

        // transfer fee amt to protocol
        Position(payable(position)).transfer(owner(), assetData[i].asset, fee);
        // transfer difference to the liquidator
        Position(payable(position)).transfer(msg.sender, assetData[i].asset, assetData[i].amt - fee);
    }
}

Here the protocol liquidation fee is calculated as a percentage of the total amount of seized collateral which makes many liquidations unprofitable; in this case the protocol liquidation fee was 30% of the seized collateral significantly removing incentives to liquidate many liquidatable positions. Possible mitigations include:

• having no protocol liquidation fee or having a small flat fee

• calculating the protocol liquidation fee as a percentage of the liquidator’s profit, not the raw seized collateral amount

The protocol liquidation fee calculation can also be incorrectly implemented the other way where a liquidator pays less than required to liquidate a liquidatable position.

Heuristic: is the protocol liquidation fee calculated as a percentage of the liquidator’s profit? If not, can the protocol fee make liquidation unprofitable disincentivizing liquidators?

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

Liquidation Fees Not Counted In Minimum Collateral Requirement

When opening a new position or calculating if a position is solvent, the minimum collateral requirement calculation should include liquidation fees if that position would subsequently be liquidated.

If the liquidation fee isn’t included in the minimum collateral requirement calculation then sufficient collateral may not be exist when the position is liquidated and the protocol may revert upon liquidation or incur bad debt in the form of any liquidation fees. This is debatable however and some protocols may choose not to implement this as being unfair to the user.

Heuristic: are liquidation fees included in minimum collateral requirements? If not, has the protocol explicitly documented the reason?

Unfair Liquidation As Earned Yield Not Added To Collateral Value

Some protocols support mechanisms for deposited collateral to earn yield in order to maximize capital efficiency. When valuing a user’s collateral if the earned yield is not factored into the total collateral value the user can be unfairly liquidated.

Heuristic: is earned yield factored into a user’s total collateral value? If not, can the user be unfairly liquidated? If yes, what happens to the earned yield - is it lost?

Unfair Liquidation As Positive PNL Not Added To Collateral Value

Liquidation mechanisms in trading protocols should consider the current profitability of an open leveraged position when calculating the total value of a trader’s collateral:

• if a position has negative PNL, the negative PNL should be deducted from the collateral value causing liquidation to occur sooner - this should always be implemented in all protocols

• if a position has positive PNL, the positive PNL should be added to the collateral value delaying liquidation - some protocols may have valid reasons for not doing this though this should be explicitly documented for users

Leveraged trading protocols which don’t consider open PNL during liquidation can unfairly liquidate traders with large positive PNL.

Heuristic: is open user PNL accounted for when determining if a user can be liquidated? If not, can the user be unfairly liquidated? If yes, what happens to the open PNL - is it lost?

Unfair Liquidation After L2 Sequencer Grace Period

Chainlink’s official documentation recommends implementing a grace period after an L2 sequencer has come back online and only fetching price data after that grace period has expired. If transactions such as depositing additional collateral are prevented during this grace period, then users may be immediately unfairly liquidated once the grace period expires and fresh price data starts being fetched.

Protocols should consider whether to allow depositing additional collateral during the grace period in order to allow users to protect their open positions once the L2 sequencer has come back online but before the grace period has expired and fresh price data becomes available.

Heuristic: once the L2 sequencer comes back online, can users deposit additional collateral during the grace period before price data resumes? Does the protocol implement a grace period to allow this, or will it liquidate users immediately after the L2 sequencer comes back online?

Unfair Liquidation As Borrow Interest Accumulates While Paused

If the protocol supports pausing and the user is prevented from repaying their loan while the protocol is paused, then borrow interest should not accumulate during the paused period otherwise the user can be instantly unfairly liquidated when the protocol is unpaused due to the interest build-up while paused.

Heuristic: does borrow interest accumulate while the protocol is paused and users are unable to repay?

Unfair Liquidation As Repayment Paused While Liquidations Enabled

Protocols ideally shouldn’t be able to enter a state where repayments are paused but liquidations are enabled, as this will result in unfair liquidations for borrowers who wanted to repay but were prevented from doing so by the protocol admin. Ideally there should also be a grace period after liquidations are unpaused to allow repayments and collateral deposits for users who became liquidatable while the protocol was paused.

Heuristic: can the protocol enter a state where users are unable to repay but subject to liquidation? After unpausing is there a grace period or are users who became liquidatable during the pause period immediately liquidated?

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

Late Liquidation As isLiquidatable Doesn’t Refresh Interest / Funding Fees

Whenever a protocol checks that a user is liquidatable, it must always first refresh any fees such as total interest owed on a loan or total funding fees owed on a leveraged trading position, before determining whether a user is liquidatable.

Smart contract auditors should be especially attentive to view functions that don’t change state but need to calculate the latest owed fees prior to determining whether an account is liquidatable. When liquidation occurs all of these fees also need to be updated prior to the user being liquidated.

Heuristic: does the protocol always refresh all interest, yield, funding fees, PNL etc before determining whether a user is liquidatable?

Positive PNL, Yield & Rewards Lost When Account Liquidated

In leveraged trading protocols the following interesting edge case can occur:

• trader deposits collateral $C and uses it to open a long leveraged trading position on asset $A

• the market value of $A increases such that the trader has significant positive unrealized profit

• the market value of $C decreases even more such that even though the trader is in profit on their trade, their overall position is liquidatable

• alternatively borrow / funding fees accumulate such that the total owed fees is greater than the position’s profit and the overall position becomes liquidatable

When this edge-case occurs the trader’s positive PNL should be credited to the account during liquidation otherwise it will be lost. The same is true for yield and other rewards that can be earned by a borrower/trader; all rewards should be accumulated prior to liquidation.

Heuristic: is all open profit such as yield, rewards and positive PNL realized prior to liquidation and factored into the liquidation calculations? If not, is it lost after liquidation?

More examples: [1, 2, 3]

No Swap Fee Charged On Liquidation

Protocols may implement swap fees when swapping internally from one asset to another. If internal swap fees are implemented, they may also need to be charged when a liquidator provides debt tokens in order to receive seized collateral tokens as part of the liquidation. Failing to charge swap fees during liquidation leads to the protocol and potentially the insurance fund accruing less tokens than it should.

Heuristic: does the protocol generally charge swap fees and also perform swaps during liquidation? If yes, does it charge a swap fee during liquidation? If no, does it explicitly document the reason for this discrepancy?

Profitable Self-Liquidation Using Oracle Update Sandwich

An attacker can exploit a user-triggered oracle update for profitable self-liquidation by using an attack contract to:

• flash-loan a large amount of collateral tokens

• deposit the collateral and borrow the maximum amount of debt tokens (max leverage)

• trigger the oracle price update

• liquidate themselves

The attack is profitable when the oracle price update results in the entire collateral balance being recovered while repaying fewer debt tokens than were borrowed. Simple mitigations which help to reduce the profitability of this attack are:

• charging borrow and liquidation fees

• implementing a cool-off period during which an account can’t be liquidated

More advanced mitigations involve restricting leverage for volatile collateral assets and choosing oracles with smaller price deviation updates that can’t be user-triggered.

Self-liquidation can be a dangerous attack vector especially when users can cause themselves to become liquidatable.

Heuristic: Can a user make themselves liquidatable and self-liquidate? Can a user weaponize oracle price updates to extract value from the protocol?

Healthy Borrower Can Be Liquidated

Liquidation should only be allowed for borrowers that are liquidatable, and this check should be done prior to any actions which occur as part of liquidation such as debt repayment and collateral transfer. If this check is performed after debt repayment and collateral transfer, due to the liquidation bonus liquidators can over-remove collateral relative to repaid debt, forcing healthy positions into an under-collateralized liquidatable state.

Liquidation Leaves Borrower With Lower Health Score

Liquidation (whether full or partial) should always leave the borrower being liquidated in a “healthier” state where after liquidation they are less likely to be liquidated in the future. But in advanced protocols which support multiple collateral types and partial liquidation, subtle bugs can exist which leave borrowers in an unhealthier position post-liquidation, making it more likely for them to be liquidated in the future.

Consider this liquidate function:

function liquidatePartiallyFromTokens(
    uint256 _nftId,
    uint256 _nftIdLiquidator,
    address _paybackToken,
    address _receiveToken, //@audit liquidator can choose collateral
    uint256 _shareAmountToPay
)

This liquidate function allows the liquidator to choose which collateral to seize and receive in compensation for the liquidation. Why is this dangerous? Because different collateral have different:

• borrowing factors which enable users to borrow more or less against a particular collateral

• risk profiles as some collateral can be very stable (USDC) while other collateral can be much more volatile (ETH and especially speculative ERC20 tokens)

A liquidator can abuse this feature by choosing to first liquidate a user’s more stable, higher borrowing factor collateral. After liquidation this leaves the user with a less healthier collateral basket as:

• their remaining collateral is more volatile in regards to price movement

• they have a reduced borrowing factor since they are left with riskier more volatile collateral which has reduced borrowing factor

Both of these outcomes make it more likely the user will be liquidated in the future and may subject to user to cascading liquidation where the first liquidation transaction makes them immediately subject to a second liquidation and so on, as liquidation leaves the trader with an unhealthier and riskier collateral basket.

One potential mitigation is during the liquidation transaction:

• calculate the borrower’s health score before and after liquidation

• revert if the “after” health score <= the “before” health score

Two simple health score implementations are:

• collateral_value / borrow_value (collateral : debt ratio)

• collateral_value * loan_to_value_ratio / borrow_value (borrowing power)

Heuristic: can liquidation leave a borrower in an unhealthier state? Can the liquidator choose which collateral to seize, leaving the borrower with a more volatile collateral basket with reduced borrowing factor?

More examples: [1, 2, 3, 4]

Corruption Of Collateral Priority Order

In protocols which support multiple collaterals, another mitigation for the previous vulnerability is to enforce a collateral priority order for liquidation where the riskier more volatile collateral is liquidated first. However care must be taken when implementing functions which change the collateral priority order to prevent corrupting the collateral priority order resulting in incorrect order of collateral liquidation.

Heuristic: can the collateral liquidation priority order become corrupt by functions which change it?

Borrower Replacement Results In Incorrect Repayment Attribution

Some protocols support an optional “replacement” liquidation technique where a liquidatable position can be used to “fill” an order from an order-book, effectively replacing an unhealthy borrower with a healthy borrower.

Other protocols allow users to “buy” a liquidatable position effectively taking it over as long as they have enough collateral deposited to make the position solvent. This achieves the same effective end state which is the transfer of a debt position from the original unhealthy borrower to a different healthy borrower.

In both cases the borrower’s address is changed to the new borrower but most other fields including the id and debt of the position remain the same. Consider what can happen when the following two transactions are concurrently initiated:

• TX1 - the liquidatable original borrower attempts to repay their liquidatable position passing as input their position’s id

• TX2 - a replacement liquidation transaction attempts to transfer the liquidatable position to a healthier borrower

If TX2 is executed before TX1 the liquidatable position is acquired by the new borrower prior to the original borrower’s repayment transaction being executed - the original borrower effectively repays someone else’s debt! In protocols where users can “buy” liquidatable positions an MEV attacker could weaponize this to front-run repayment transactions, buying the liquidatable positions then having the original borrower repay the debt on the position they just acquired!

One potential mitigation is to have repayment transactions specify the borrower’s address as part of the input and revert if the current borrower’s address does not match.

Heuristic: can a liquidatable position be transferred from an unhealthy user to a healthy user? If so, what happens if the unhealthy user attempts to repay at the same time as the transfer?

More examples: [1]

No Gap Between Borrow And Liquidation Loan To Value Ratio

Most protocols require a lower Loan To Value (LTV) ratio to open a new borrow but use a higher LTV ratio for determining whether a position is liquidatable; this design aims to prevent borrowers from being liquidated very soon after opening a new borrow.

If there is no gap between the borrow and liquidation LTV ratio then borrowers can open new positions on the edge of liquidation which increases the likelihood of subsequent liquidations, threatening the stability of the protocol and creating a poor user experience.

Heuristic: can a user become liquidatable very soon after opening a new position? What about after modifying an existing position?

More examples: [1, 2, 3, 4]

Borrower Accrues Interest While Liquidation Auction Running

Some protocols use an “auction” mechanism where a liquidatable position is put up for auction over a period of time. In such cases interest payments on debt should be paused as soon as debt is put up for auction; positions being liquidated shouldn’t continue accruing additional interest during the liquidation auction process.

Heuristic: does a borrower continue to accrue interest while their debt is being auctioned?

No Slippage For Liquidation & Swaps

Ideally when performing a liquidation the liquidator should be able to specify the minimum amount of rewards (in the form of tokens, shares or other instruments) they are willing to receive. This is especially important for protocols which perform swaps during liquidation where those swaps could be exploited via MEV causing the liquidator to receive less rewards than they expected to receive.

Heuristic: can the liquidator specify a slippage parameter? If swaps occur during the liquidation, can that result in the liquidator (or the protocol or the user being liquidated) receiving less tokens than expected?

Additional Resources

• Lending & Borrowing Deep Dive

• 13 Critical Liquidation Vulnerabilities

• How DeFi Liquidations Work

• Liquidation Mechanisms: Aave, Morpho & Euler

Since fuzz testing may seem daunting at first, I presented a simple methodology for learning to “Think In Invariants” that any developer could learn and apply to start building effective invariant fuzz testing suites. In response many researchers and developers reached out asking if a similar approach could be used with Formal Verification (FV) and the answer is a resounding “Yes”, though with some modifications.

This article will showcase using Certora Verification Language (CVL) to solve the same simplified versions of real world vulnerabilities from my previous invariant fuzz testing deep dive. Certora graciously provides a generous free tier which anyone can sign up for that I continuously used to create these solutions (including many failed attempts) and still didn’t get close to reaching the limit, so sign up today!

Special thanks also to:

• Updraft Assembly & Formal Verification Course which is free and great for learning Certora!

• alexzoid_eth who provided invaluable assistance improving some of the solutions

• kirsteinuri for reviewing this article and providing valuable corrections

Before we get to the Certora solutions lets briefly examine some important differences between how to use invariant fuzzers and Certora.

Invariant Fuzz Testing vs Formal Verification

Everything regarding “thinking in invariants” still applies and carries over from fuzz testing into formal verification - we need to specify useful properties to make effective use of both fuzz testing and formal verification. However some notable differences include:

Solidity vs Certora Verification Language (CVL)

Our fuzzers were all written in Solidity but when using Certora we write “specifications” using Certora’s domain-specific language, CVL. These specifications are used as input to Certora’s “Prover” which compares rules in the specification against the underlying smart contract being verified to identify scenarios which could lead to assertions being violated. Writing specifications in CVL takes some getting used to but is very powerful, allowing the creation of elegant and concise solutions compared to much bulkier fuzzers, as we’ll soon see.

Fuzz Locally vs Cloud Formal Verification

The fuzzers we wrote all ran locally, though since we used the Chimera framework they could easily be run in the cloud using getrecon.xyz. In contrast Certora’s command-line tool will do some basic error checking and compilation then send it to the cloud for execution; the results can take anywhere from 30-60 seconds to be visible in Certora’s web interface.

Fuzz Setup vs Formal Verification Relationships

A fuzz test over one or more smart contracts will typically:

• create contracts through their constructors, setting important parameters to specific values

• call any initialization functions, setup roles and grant permissions

• wrap the contract’s underlying functions using “handler” functions which update ghost variables and satisfy preconditions reducing the amount of wasted fuzz runs

Within the environment we’ve created the fuzzer tries many random combinations of function calls attempting to break the defined invariants. One important consequence of this approach is that all of the restrictions on parameter values in require statements within the contract being fuzzed are respected, such that if the fuzzer breaks an invariant there is a high likelihood that will be a valid finding.

In contrast when using Certora there is no “setup” function, we aren’t explicitly creating the contracts, setting parameters or writing any Solidity. Instead we:

• define a .conf configuration file with some basic information - the contracts we are testing and optional Certora flags

• write a .spec specification file containing our Certora specification using CVL which defines invariants and relationships between objects (such as storage locations or environment parameters) using CVL require statements to restrict Certora from breaking invariants by reaching an invalid state

One benefit is that Certora specifications can be very concise compared to much bulkier fuzz testing code. However one drawback is that some restrictions present in the underlying contracts may need to be duplicated in the specification using CVL require statements to prevent Certora from setting storage slots to values that would never be possible and hence breaking invariants through invalid states.

Fuzz Invariant vs Certora rule and invariant

All 3 fuzzers we used generally have the same type of invariant; a function that either returns a boolean (Echidna/Medusa) or fails an assert (Foundry). In contrast Certora has two ways to implement an “invariant”, using the rule and invariant keywords.

• rule is ideally used when describing a conditional “scenario” to Certora; the conditions are expressed using a set of require statements that specify relationships between storage and/or environment. The conditions are followed by one or more assert or satisfy statements which are the actual properties we are trying to break

• invariant doesn’t support scenarios and is best used for simple boolean expressions which should always be true

Personally I found rule to be the most powerful so that is what most of our solutions use.

Fuzz Cheat Codes vs Certora env

In our fuzz handlers we used a number of cheat codes such as vm.prank to change msg.sender or vm.warp to set block.timestamp. In contrast Certora has a special env type which is:

• declared and passed as the first parameter to underlying function calls

• used together with CVL require statements to constrain environment properties such as msg.sender or block.timestamp

Additional Certora Features

Certora has a number of very powerful additional features including parametric rules and opcode hooks - keep the user guide open as a handy reference. There are also a number of important command-line parameters which we encode in the .conf files, the most important being optimistic_loop and optimistic_fallback.

Now that we are aware of important differences between using fuzz testing and Certora, let’s see what the Certora specifications look like for each of the simplified real-world vulnerabilities we solved in the invariant fuzzing deep dive!

Example 1 - Flash Loan Denial Of Service

Specification: there are 2 contracts Receiver and Lender. Receiver has a function executeFlashLoan that calls Lender::flashLoan to take a flash loan, and the important invariant is that Receiver should always be able to take a flash loan if Lender has sufficient tokens available. First we create the configuration file certora.conf:

{
  "files": [
    "src/02-unstoppable/ReceiverUnstoppable.sol",
    "src/02-unstoppable/UnstoppableLender.sol",
    "src/TestToken.sol"
  ],
  "verify": "ReceiverUnstoppable:test/02-unstoppable/certora.spec",
  "link": [
        "ReceiverUnstoppable:pool=UnstoppableLender",
        "UnstoppableLender:damnValuableToken=TestToken"
    ],
  "packages":[
        "@openzeppelin=lib/openzeppelin-contracts"
    ],
  "optimistic_loop": true
}

The Certora configuration:

• defines the Solidity source files required for the test

• marks the contract to verify and the certora.spec file which contains the Certora specification that will be sent to the Prover

• for contracts which have references to other contracts, instructs Certora to link those storage variables to the appropriate contract type

• necessary packages for library paths similar to Foundry remappings

• add an optional command-line parameter optimistic_loop required to prevent unnecessary counterexamples from incomplete loop iterations due to the Prover's bounded model checking

Then put our Certora specification in certora.spec:

using ReceiverUnstoppable as receiver;
using UnstoppableLender as lender;
using TestToken as token;

methods {
    // `dispatcher` summary to prevent HAVOC
    function _.receiveTokens(address tokenAddress, uint256 amount) external => DISPATCHER(true);

    // `envfree` definitions to call functions without explicit `env`
    function token.balanceOf(address) external returns (uint256) envfree;
}

// executeFlashLoan() -> f() -> executeFlashLoan() should always succeed
rule executeFlashLoan_mustNotRevert(uint256 loanAmount) {
    // enforce valid msg.sender:
    // 1) not a protocol contract
    // 2) equal to ReceiverUnstoppable::owner
    env e1;
    require e1.msg.sender != currentContract &&
            e1.msg.sender != lender &&
            e1.msg.sender != receiver &&
            e1.msg.sender != token &&
            e1.msg.sender == receiver.owner &&
            e1.msg.value  == 0; // not payable

    // enforce sufficient tokens exist to take out flash loan
    require loanAmount > 0 && loanAmount <= token.balanceOf(lender);

    // first executeFlashLoan() succeeds
    executeFlashLoan(e1, loanAmount);

    // perform another arbitrary successful transaction f()
    env e2;
    require e2.msg.sender != currentContract &&
            e2.msg.sender != lender &&
            e2.msg.sender != receiver &&
            e2.msg.sender != token;
    method f;
    calldataarg args;
    f(e2, args);

    // second executeFlashLoan() should always succeed; there should
    // exist no previous transaction f() that could make it fail
    executeFlashLoan@withrevert(e1, loanAmount);
    assert !lastReverted;
}

The Certora specification contains:

• a methods section giving Certora some additional information about functions in the underlying contracts, the most common of these being marking view functions as envfree so that Certora’s special env type does not need to be passed as an input parameter when calling them

• a rule describing the “scenario” we wish to test

• require statements which restrict the env environment especially msg.sender and also instruct Certora to satisfy preconditions such as sufficient tokens being available for the flash loan

• a first executeFlashLoan call which always succeeds

• a parametric function call instructing Certora to perform any arbitrary successful function call f()

• a second executeFlashLoan call using @withrevert to consider scenarios where this call may revert

• an assertion which fails if the previous call reverts, meaning Certora has broken the rule and hence found a valid attack path

Example 2 - Reward Distribution Stuck

Specification: a Proposal contract is deployed by a DAO with some ETH to be distributed if the proposal succeeds:

• Proposal is active until voting has finished or the proposal has timed out

• While active, eligible voters can vote for or against

• if quorum is reached the ETH should be distributed between the for voters

• otherwise the ETH should be refunded to the proposal creator

Our Certora specification uses an invariant construction which is very similar to the fuzzer invariant we used for this challenge, but note the total absence of any setup, handlers or other “infrastructure” - everything is self-contained within the certora.spec file:

methods {
    // `envfree` definitions to call functions without explicit `env`
    function isActive() external returns (bool) envfree;
}

// define constants and require them later to prevent HAVOC into invalid state
definition MIN_FUNDING() returns uint256 = 1000000000000000000;
definition MIN_VOTERS()  returns uint256 = 3;
definition MAX_VOTERS()  returns uint256 = 9;

// Proposal state must be:
// 1) active with balance >= min_funding OR
// 2) not active with balance == 0
invariant proposal_complete_all_rewards_distributed()
    (isActive()  && nativeBalances[currentContract] >= MIN_FUNDING()) ||
    (!isActive() && nativeBalances[currentContract] == 0)
{
    // enforce state requirements to prevent HAVOC into invalid state
    preserved {
        // enforce valid total allowed voters
        require(currentContract.s_totalAllowedVoters >= MIN_VOTERS() &&
                currentContract.s_totalAllowedVoters <= MAX_VOTERS() &&
                // must be odd number
                currentContract.s_totalAllowedVoters % 2 == 1);

        // enforce valid for/against votes matches total current votes
        require(currentContract.s_votersFor.length +
                currentContract.s_votersAgainst.length
                == currentContract.s_totalCurrentVotes);

        // enforce that when a proposal is active, the total number of current
        // votes must be at maximum half the total allowed voters, since proposal
        // is automatically finalized once >= 51% votes are cast
        require(!isActive() || 
                    (isActive() && 
                    currentContract.s_totalCurrentVotes <= currentContract.s_totalAllowedVoters/2)
                );
    }
}

Since there is no setup we used require statements within a preserved block inside the invariant to enforce valid values for key contract parameters. Normally the smart contract’s constructor would enforce these restrictions but Certora sets storage slots to arbitrary values after the constructor. Using require statements we define relationships which restrict the range of possible values, preventing Certora from breaking the invariant due to an invalid state.

Also of note is the usage of currentContract - a special keyword that allows direct access to the underlying contract being verified.

Example 3 - Voting Power Destruction

Specification: a VotingNft contract:

• allows users to deposit ETH collateral against their NFT to give it DAO voting power

• NFTs can be created by the owner until the “power calculation start time”

• Once power calculation begins all NFTs start with max voting power which declines over time for NFTs which have not been backed by deposited ETH

• NFT voting power which has declined can never be increased; depositing the required ETH collateral simply prevents any future decrease

Using a rule construction we approximate the same invariant as the fuzz test in our Certora specification:

methods {
    // `envfree` definitions to call functions without explicit `env`
    function getTotalPower()    external returns (uint256) envfree;
    function totalSupply()      external returns (uint256) envfree;
    function owner()            external returns (address) envfree;
    function ownerOf(uint256)   external returns (address) envfree;
    function balanceOf(address) external returns (uint256) envfree;
}

// define constants and require them later to prevent HAVOC into invalid state
definition PERCENTAGE_100() returns uint256 = 1000000000000000000000000000;

// given: safeMint() -> power calculation start time -> f()
// there should exist no f() where a permissionless attacker
// could nuke total power to 0 when power calculation starts
rule total_power_gt_zero_power_calc_start(address to, uint256 tokenId) {
    // enforce basic sanity checks on variables set during constructor
    require currentContract.s_requiredCollateral > 0 &&
            currentContract.s_powerCalcTimestamp > 0 &&
            currentContract.s_maxNftPower > 0 &&
            currentContract.s_nftPowerReductionPercent > 0 &&
            currentContract.s_nftPowerReductionPercent < PERCENTAGE_100();

    // enforce no nfts have yet been created; in practice some may
    // exist in storage though due to certora havoc
    require totalSupply() == 0 && getTotalPower() == 0 && balanceOf(to) == 0;

    // enforce msg.sender as owner required to mint nfts
    env e1;
    require e1.msg.sender == currentContract.owner();

    // enforce block.timestamp < power calculation start time
    // so new nfts can still be minted
    require e1.block.timestamp < currentContract.s_powerCalcTimestamp;

    // first safeMint() succeeds
    safeMint(e1, to, tokenId);

    // sanity check results of first mint
    assert totalSupply() == 1 && balanceOf(to) == 1 && ownerOf(tokenId) == to &&
           getTotalPower() == currentContract.s_maxNftPower;

    // perform any arbitrary successful transaction at power calculation
    // start time, where msg.sender is not an nft owner or an admin
    env e2;
    require e2.msg.sender != currentContract &&
            e2.msg.sender != to &&
            e2.msg.sender != currentContract.owner() &&
            balanceOf(e2.msg.sender) == 0 &&
            e2.block.timestamp == currentContract.s_powerCalcTimestamp;
    method f;
    calldataarg args;
    f(e2, args);

    // total power should not equal to 0
    assert getTotalPower() != 0;
}

Note again the usage of require statements to prevent corruption of the initial storage state which would lead to the invariant being broken due to an invalid state.

Example 4 - Token Sale Drain

Specification: a TokenSale contract:

• allows a DAO to sell its governance sellToken for another buyToken

• the token sale is only for allowed users and each user can only buy up to a max per-user limit to prevent concentration of voting power

• in our simplified version we assume an exchange rate of 1:1 and that sellToken always has decimals greater or equal to buyToken

This underlying contract uses two tokens; we found that in the configuration it was necessary to specify a different contract for each token otherwise the formal verification would “pass” but without actually running due to vacuity. The certora.conf looks like this:

{
  "files": [
    "src/05-token-sale/TokenSale.sol",
    "src/TestToken.sol",
    "src/TestToken2.sol"
  ],
  "verify": "TokenSale:test/05-token-sale/certora.spec",
  "link": [
        "TokenSale:s_sellToken=TestToken",
        "TokenSale:s_buyToken=TestToken2"
  ],
  "packages":[
        "@openzeppelin=lib/openzeppelin-contracts"
  ],
  "optimistic_fallback": true,
  "optimistic_loop": true
}

For the Certora specification we implemented the two fuzzer invariants using one rule per invariant which worked very well:

methods {
    // `envfree` definitions to call functions without explicit `env`
    function getSellTokenSoldAmount() external returns (uint256) envfree;
}

// define constants and require them later to prevent HAVOC into invalid state
definition MIN_PRECISION_BUY() returns uint256 = 6;
definition PRECISION_SELL()    returns uint256 = 18;
definition FUNDING_MIN()       returns uint256 = 100;
definition BUYERS_MIN()        returns uint256 = 3;

// the amount of tokens bought should equal the amount of tokens sold
// due to 1:1 exchange ratio
rule tokens_bought_eq_tokens_sold(uint256 amountToBuy) {
    env e1;

    uint8 sellTokenDecimals = currentContract.s_sellToken.decimals(e1);
    uint8 buyTokenDecimals  = currentContract.s_buyToken.decimals(e1);

    // enforce basic sanity checks on variables set during constructor
    require currentContract.s_sellToken != currentContract.s_buyToken &&
            sellTokenDecimals == PRECISION_SELL()    &&
            buyTokenDecimals  >= MIN_PRECISION_BUY() &&
            buyTokenDecimals  <= PRECISION_SELL()    &&
            currentContract.s_sellTokenTotalAmount >= FUNDING_MIN() * 10 ^ sellTokenDecimals &&
            currentContract.s_maxTokensPerBuyer <= currentContract.s_sellTokenTotalAmount &&
            currentContract.s_totalBuyers >= BUYERS_MIN();

    // enforce valid msg.sender
    require e1.msg.sender != currentContract.s_creator &&
            e1.msg.sender != currentContract.s_buyToken &&
            e1.msg.sender != currentContract.s_sellToken &&
            e1.msg.value == 0;

    // enforce buyer has not yet bought any tokens being sold
    require currentContract.s_sellToken.balanceOf(e1, e1.msg.sender) == 0 &&
            getSellTokenSoldAmount() == 0;

    // enforce buyer has tokens with which to buy tokens being sold
    uint256 buyerBuyTokenBalPre = currentContract.s_buyToken.balanceOf(e1, e1.msg.sender);
    require buyerBuyTokenBalPre > 0 && amountToBuy > 0;

    // perform a successful `buy` transaction
    buy(e1, amountToBuy);

    // buyer must have received some tokens from the sale
    assert getSellTokenSoldAmount() > 0;
    uint256 buyerSellTokensBalPost = currentContract.s_sellToken.balanceOf(e1, e1.msg.sender);
    assert buyerSellTokensBalPost > 0;

    uint256 buyerBuyTokenBalPost = currentContract.s_buyToken.balanceOf(e1, e1.msg.sender);

    // verify buyer paid 1:1 for the tokens they bought when accounting for decimal difference
    assert getSellTokenSoldAmount() == (buyerBuyTokenBalPre - buyerBuyTokenBalPost) 
                                       * 10 ^ (sellTokenDecimals - buyTokenDecimals);
}

// this rule was provided by https://x.com/alexzoid_eth
rule max_token_buy_per_user(env e1, env e2, uint256 amountToBuy1, uint256 amountToBuy2) {   
    // enforce valid initial state
    require(currentContract.s_maxTokensPerBuyer <= currentContract.s_sellTokenTotalAmount);

    // enforce same buyer in different calls
    require e1.msg.sender == e2.msg.sender;
    require e1.msg.sender != currentContract && e1.msg.sender != currentContract.s_creator;

    // save initial balance
    mathint balanceBefore = currentContract.s_sellToken.balanceOf(e1, e1.msg.sender);

    // prevent over-flow in ERC20 (otherwise totalSupply and balances synchronization required)
    require balanceBefore < max_uint128 && amountToBuy1 < max_uint128 && amountToBuy2 < max_uint128;

    // perform two separate buy transactions
    buy(e1, amountToBuy1);
    buy(e2, amountToBuy2);

    // save final balance
    mathint balanceAfter = currentContract.s_sellToken.balanceOf(e1, e1.msg.sender);

    // verify total bought by same user must not exceed max limit per user
    mathint totalBuy = balanceAfter > balanceBefore ? balanceAfter - balanceBefore : 0;
    assert totalBuy <= currentContract.s_maxTokensPerBuyer;
}

Example 5 - Vesting Points Increase

Specification: a Vesting contract allocates points to users which can be used to redeem tokens once their vesting period has been served. The contract implements an initialization invariant in the constructor ensuring that all points are allocated:

require(totalPoints == TOTAL_POINTS, "Not enough points");

Users can transfer their points to another address but apart from this users have no way to increase or decrease their allocated points, hence the sum of individual user points should always remain equal to the initial total allocated.

Instead of re-implementing the same invariant as the fuzzer, I used Certora’s parametric rules to implement a much simpler rule that achieves the same outcome:

// there should exist no function f() that allows a user
// to increase their allocated points
rule user_cant_increase_points(address user) {
    require user != currentContract;

    // enforce that user has some allocated points
    uint24 userPointsPre = currentContract.allocations[user].points;
    require userPointsPre > 0;

    // user performs any arbitrary successful transaction f()
    env e;
    require e.msg.sender == user;
    method f;
    calldataarg args;
    f(e, args);

    // verify that no transaction exists which allows user to
    // increase their allocated points
    assert userPointsPre >= currentContract.allocations[user].points;
}

This elegant and concise solution beautifully illustrates the powerful nature of Certora’s Verification Language especially when using parametric rules. alexzoid_eth also implemented another rule which uses the same idea as the fuzzer invariant:

// sum of users' individual points should always remain equal to TOTAL_POINTS
// solution provided by https://x.com/alexzoid_eth
methods {
    function TOTAL_POINTS_PCT() external returns uint24 envfree => ALWAYS(100000);
}

// tracks the address of user whose points have increased
ghost address targetUser;

// ghost mapping to track points for each user address
ghost mapping (address => mathint) ghostPoints {
    axiom forall address user. ghostPoints[user] >= 0 && ghostPoints[user] <= max_uint24;
}

// hook to verify storage reads match ghost state
hook Sload uint24 val allocations[KEY address user].points {
    require(require_uint24(ghostPoints[user]) == val);
} 

// hook to update ghost state on storage writes
// also tracks first user to receive a points increase
hook Sstore allocations[KEY address user].points uint24 val {
    // Update targetUser only if not set and points are increasing
    targetUser = (targetUser == 0 && val > ghostPoints[user]) ? user : targetUser;
    ghostPoints[user] = val;
}

function initialize_constructor(address user1, address user2, address user3) {
    // Only user1, user2, and user3 can have non-zero points
    require(forall address user. user != user1 && user != user2 && user != user3 => ghostPoints[user] == 0);
    // Sum of their points must equal total allocation (100%)
    require(ghostPoints[user1] + ghostPoints[user2] + ghostPoints[user3] == TOTAL_POINTS_PCT());
}

function initialize_env(env e) {
    // Ensure message sender is a valid address
    require(e.msg.sender != 0);
}

function initialize_users(address user1, address user2, address user3) {
    // Validate user addresses:
    // - Must be non-zero addresses
    require(user1 != 0 && user2 != 0 && user3 != 0);
    // - Must be unique addresses
    require(user1 != user2 && user1 != user3 && user2 != user3);
    // Initialize targetUser to zero address
    require(targetUser == 0);
}

// Verify that total points always equal TOTAL_POINTS_PCT (100%)
rule users_points_sum_eq_total_points(env e, address user1, address user2, address user3) {
    // Set up initial state
    initialize_constructor(user1, user2, user3);
    initialize_env(e);
    initialize_users(user1, user2, user3);

    // Execute any method with any arguments
    method f;
    calldataarg args;
    f(e, args);

    // Calculate points for targetUser if it's not one of the initial users
    mathint targetUserPoints = targetUser != user1 && targetUser != user2 && targetUser != user3 ? ghostPoints[targetUser] : 0;

    // Assert total points remain constant at 100%
    assert(ghostPoints[user1] + ghostPoints[user2] + ghostPoints[user3] + targetUserPoints == TOTAL_POINTS_PCT());

    // All other addresses must have zero points
    assert(forall address user. user != user1 && user != user2 && user != user3 && user != targetUser
        => ghostPoints[user] == 0
    );
}

Example 6 - Vesting Preclaim Abuse

Specification: a VestingExt contract contains the same functionality as the previous Vesting contract plus an additional feature which lets users preclaim part of their token allocation, allowing users to get a limited amount of tokens before their vesting period is served.

When implementing the fuzzer invariant I verified that the total preclaimed points is always less than or equal to the maximum preclaimable points (which is just the number of users multiplied by the maximum preclaim point amount per user):

function property_total_preclaimed_lt_eq_max_preclaimable() public view returns(bool result) {
    result = totalPreclaimed <= MAX_PRECLAIMABLE;
}

However alexzoid_eth implemented a Certora rule which verifies preclaimed amounts are transferred at the same time as points:

// solution provided by https://x.com/alexzoid_eth
methods {
    // `envfree` definitions to call functions without explicit `env`
    function allocations(address) external returns (uint24, uint8, bool, uint96) envfree;
    function getUserTokenAllocation(uint24) external returns (uint96) envfree;
    function getUserMaxPreclaimable(uint96) external returns (uint96) envfree;
}

// reusable helper functions to get data from underlying contract
function userPointsCVL(address user) returns uint24 {
    uint24 points; uint8 vestingWeeks; bool claimed; uint96 preclaimed;
    (points, vestingWeeks, claimed, preclaimed) = allocations(user);
    return points;
}
function userPreclaimedCVL(address user) returns uint96 {
    uint24 points; uint8 vestingWeeks; bool claimed; uint96 preclaimed;
    (points, vestingWeeks, claimed, preclaimed) = allocations(user);
    return preclaimed;
}
function userMaxPreclaimableCVL(address user) returns uint96 {
    uint96 maxPreclaimable = getUserMaxPreclaimable(getUserTokenAllocation(userPointsCVL(user)));
    return maxPreclaimable;
}

// when a user who has preclaimed transfers their points to another
// address, the preclaimed amount should transfer over to prevent
// gaming preclaim functionality by preclaiming more than allowed
rule preclaimedTransferred(env e, address targetUser, uint24 points) {
    // enforce address sanity checks
    require e.msg.sender != currentContract && targetUser != currentContract &&
            e.msg.sender != 0 && targetUser != 0;

    // enforce sender already preclaimed
    require userPreclaimedCVL(e.msg.sender) == userMaxPreclaimableCVL(e.msg.sender);
    // enforce receiver has no points and not preclaimed
    require userPreclaimedCVL(targetUser) == 0 && userPointsCVL(targetUser) == 0;

    // perform successful points transfer transaction
    transferPoints(e, targetUser, points);

    // assert both sender and receiver have preclaimed correctly
    // updated from their updated points 
    assert userPreclaimedCVL(e.msg.sender) == userMaxPreclaimableCVL(e.msg.sender);
    assert userPreclaimedCVL(targetUser)   == userMaxPreclaimableCVL(targetUser);
}

Given that there is no setup, handlers or other fuzzing “infrastructure”, this again is quite an elegant and concise solution.

Example 7 - Operator Registry Corruption

Specification: an OperatorRegistry contract allows users to register as operators and receive an operatorId where the first operatorId = 1 and subsequent ids are incremented.

The contract storage has multiple inter-related data structures which use both the user’s address and operatorId as keys in mappings to reference one another, enabling lookup of operator data by either address or operatorId. Users can also update their address.

I implemented the same invariant as the fuzzer but in a more elegant and concise Certora rule, showing once again the great power of Certora’s domain-specific formal verification language especially when using parametric rules:

// given two registered operators, there should be no f() that could
// corrupt the unique relationship between operator_id : operator_address
rule operator_addresses_have_unique_ids(address opAddr1, address opAddr2) {
    // enforce unique addresses in `operatorAddressToId` mapping
    require opAddr1 != opAddr2;

    uint128 op1AddrToId = currentContract.operatorAddressToId[opAddr1];
    uint128 op2AddrToId = currentContract.operatorAddressToId[opAddr2];

    // enforce valid and unique operator_ids in `operatorAddressToId` mapping
    require op1AddrToId != op2AddrToId && op1AddrToId > 0 && op2AddrToId > 0;

    // enforce matching addresses in `operatorIdToAddress` mapping
    require currentContract.operatorIdToAddress[op1AddrToId] == opAddr1 &&
            currentContract.operatorIdToAddress[op2AddrToId] == opAddr2;

    // perform any arbitrary successful transaction f()
    env e;
    method f;
    calldataarg args;
    f(e, args);

    // verify that no transaction exists which corrupts the uniqueness
    // property between operator_id : operator_address
    assert currentContract.operatorIdToAddress[op1AddrToId] !=
           currentContract.operatorIdToAddress[op2AddrToId];
}

Note again the use of require statements instructing Certora to create an initial valid state.

Example 8 - Liquidate Denial Of Service

Specification: a LiquidateDos contract allows traders to enter multiple markets and have one open position in each market. Traders can also be liquidated:

• all open positions are accounted when determining if a trader is liquidatable

• if liquidated, all open positions are closed for the trader being liquidated

• liquidation should never fail with unexpected errors

Unfortunately at this time Certora can’t be used for Unexpected Denial Of Service checks as CVL does not return the reason for a revert - it only provides lastReverted and lastHasThrown which are both booleans (and size if using a revert opcode hook). Certora has confirmed in their discord that “we have a plan to implement this feature in the prover” so we will update once this feature is added.

Example 9 - Stability Pool Drain

Specification: a StabilityPool contract which:

• allows users to deposit debtToken which is used to pay down bad debt during liquidations

• in exchange debtToken depositors receive a share of collateralToken rewards from collateral seized during liquidations

• contains quite complicated logic to calculate the reward share debtToken depositors should receive

• must always remain solvent; the pool should always have sufficient collateralToken to pay out rewards owed to debtToken depositors

Using a rule construction I transformed the invariant used in the fuzzer into a “scenario” which Certora was able to solve:

methods {
    // `envfree` definitions to call functions without explicit `env`
    function getDepositorCollateralGain(address) external returns (uint256) envfree;
}

// stability pool depositors should not be able to drain the stability
// pool; the stability pool should always hold enough collateral tokens
// to pay out rewards owed to depositors
rule stability_pool_solvent(address spDep1, address spDep2) {
    // enforce address sanity checks
    require spDep1 != spDep2 &&
            spDep1 != currentContract &&
            spDep1 != currentContract.debtToken &&
            spDep1 != currentContract.collateralToken &&
            spDep2 != currentContract &&
            spDep2 != currentContract.debtToken &&
            spDep2 != currentContract.collateralToken;

    // enforce neither user has active deposits or rewards
    require currentContract.accountDeposits[spDep1].amount     == 0 &&
            currentContract.accountDeposits[spDep1].timestamp  == 0 &&
            currentContract.depositSnapshots[spDep1].P         == 0 &&
            currentContract.depositSnapshots[spDep1].scale     == 0 &&
            currentContract.depositSnapshots[spDep1].epoch     == 0 &&
            currentContract.depositSums[spDep1]                == 0 &&
            currentContract.collateralGainsByDepositor[spDep1] == 0 &&
            currentContract.accountDeposits[spDep2].amount     == 0 &&
            currentContract.accountDeposits[spDep2].timestamp  == 0 &&
            currentContract.depositSnapshots[spDep2].P         == 0 &&
            currentContract.depositSnapshots[spDep2].scale     == 0 &&
            currentContract.depositSnapshots[spDep2].epoch     == 0 &&
            currentContract.depositSums[spDep2]                == 0 &&
            currentContract.collateralGainsByDepositor[spDep2] == 0;

    // enforce that both users have tokens to deposit into stability pool
    env e;
    uint256 user1DebtTokens = currentContract.debtToken.balanceOf(e, spDep1);
    uint256 user2DebtTokens = currentContract.debtToken.balanceOf(e, spDep2);
    require user1DebtTokens >= 1000000000000000000 && user2DebtTokens >= 1000000000000000000 &&
            user1DebtTokens == user2DebtTokens;

    // both users deposit their debt tokens into the stability pool
    env e1;
    require e1.msg.sender == spDep1;
    provideToSP(e1, user1DebtTokens);
    env e2;
    require e2.msg.sender == spDep2;
    provideToSP(e2, user2DebtTokens);

    // stability pool is used to offset debt from a liquidation
    uint256 debtTokensToOffset = require_uint256(user1DebtTokens + user2DebtTokens);
    uint256 seizedCollateral = debtTokensToOffset; // 1:1
    env e3;
    registerLiquidation(e3, debtTokensToOffset, seizedCollateral);

    require(currentContract.collateralToken.balanceOf(e, currentContract) == seizedCollateral);

    // enforce each user is owed same reward since they deposited the same
    uint256 rewardPerUser = getDepositorCollateralGain(spDep1);
    require rewardPerUser > 0;
    require rewardPerUser == getDepositorCollateralGain(spDep2);

    // enforce contract has enough reward tokens to pay both users
    require(currentContract.collateralToken.balanceOf(e, currentContract) >= require_uint256(rewardPerUser * 2));

    // first user withdraws their reward
    env e4;
    require e4.msg.sender == spDep1;
    claimCollateralGains(e4);

    // enforce contract has enough reward tokens to pay second user
    require(currentContract.collateralToken.balanceOf(e, currentContract) >= rewardPerUser);

    // first user perform any arbitrary successful transaction f()
    env e5;
    require e5.msg.sender == spDep1;
    method f;
    calldataarg args;
    f(e5, args);

    // second user withdraws their reward
    env e6;
    require e6.msg.sender == spDep2 &&
            e6.msg.value  == 0;
    claimCollateralGains@withrevert(e6);

    // verify first user was not able to do anything that would make
    // second user's withdrawal revert
    assert !lastReverted;
}

Note again the heavy usage of require statements to prevent Certora from breaking the assertion by generating an invalid state.

Example 10 - Collateral Priority Corruption

Specification: a Priority contract used in multi-collateral lending protocols:

• defines a liquidation priority order for collaterals

• when a liquidation occurs, the riskiest collaterals are liquidated first such that the borrower’s remaining collateral basket is more stable post-liquidation

• allows collaterals to be added and removed; adding always puts the new collateral at the end of the priority queue while removing preserves the existing order minus the removed element

Here I used a similar approach to Example #9, translating the fuzzer invariant into a rule which describes a scenario then verifies an assertion that Certora was able to break:

methods {
    // `envfree` definitions to call functions without explicit `env`
    function getCollateralAtPriority(uint8) external returns(uint8)   envfree;
    function containsCollateral(uint8)      external returns(bool)    envfree;
    function numCollateral()                external returns(uint256) envfree;
}

// verify priority queue order is correctly maintained:
// - `addCollateral` adds new id to end of the queue
// - `removeCollateral` maintains existing order minus removed id
rule priority_order_correct() {
    // require no initial collateral to prevent HAVOC corrupting
    // EnumerableSet _positions -> _values references
    require numCollateral() == 0   && !containsCollateral(1) &&
            !containsCollateral(2) && !containsCollateral(3);

    // setup initial state with collateral_id order: 1,2,3 which ensures
    // EnumerableSet _positions -> _values references are correct
    env e1;
    addCollateral(e1, 1);
    addCollateral(e1, 2);
    addCollateral(e1, 3);

    // sanity check initial state
    assert numCollateral() == 3  && containsCollateral(1) &&
           containsCollateral(2) && containsCollateral(3);

    // sanity check initial order; this also verifies that
    // `addCollateral` worked as expected
    assert getCollateralAtPriority(0) == 1 &&
           getCollateralAtPriority(1) == 2 &&
           getCollateralAtPriority(2) == 3;

    // successfully remove first id 1
    removeCollateral(e1, 1);

    // verify it was removed and other ids still exist
    assert numCollateral() == 2  && !containsCollateral(1) &&
           containsCollateral(2) && containsCollateral(3);

    // assert existing order 2,3 preserved minus the removed first id 1
    assert getCollateralAtPriority(0) == 2 &&
           getCollateralAtPriority(1) == 3;
}

Bonus - Certora Foundry Plug-In

Certora has experimental Foundry integration (docs, examples) that allows running Foundry stateless fuzz tests through Certora’s formal verification. Consider the function test_RarelyFalse containing a Chimera-style t() assertion which fails if _rarelyFalse returns false:

uint256 constant private OFFSET = 1234;
uint256 constant private POW    = 80;
uint256 constant private LIMIT  = type(uint256).max - OFFSET;

// fuzzers call this function
function test_RarelyFalse(uint256 n) external {
    // input preconditions
    n = between(n, 1, LIMIT);

    // assertion to break
    t(_rarelyFalse(n + OFFSET, POW), "Should not be false");
}

// actual implementation to test
function _rarelyFalse(uint256 n, uint256 e) private pure returns(bool) {
    if(n % 2**e == 0) return false;
    return true;
}

At the current time of writing, none of the Fuzzers (Foundry/Echidna/Medusa) are able to find a case where _rarelyFalse returns false making the assertion in test_RarelyFalse fail - but Certora can find it very quickly without writing any extra code! First create the configuration file certora.conf which along with the usual fields has an additional optional foundry_tests_mode set to true:

{
  "files": [
    "test/06-rarely-false/RarelyFalseCryticToFoundry.sol"
  ],
  "verify": "RarelyFalseCryticToFoundry:test/06-rarely-false/certora.spec",
  "packages":[
        "@chimera=lib/chimera/src",
        "forge-std=lib/forge-std/src"
    ],
  "foundry_tests_mode": true
}

Then the certora.spec file has this exact one line which is not specific at all to the test:

use builtin rule verifyFoundryFuzzTests;

This simple setup allows Foundry stateless fuzz tests to be formally verified using Certora!

Possible Improvements

Since Certora has created their own domain-specific language, it would be nice if it contained some “syntactic sugar” to make common patterns much easier and not error-prone to implement.

One common pattern is where a ghost variable is used to track the sum of all values in a mapping; this was used in the second solution to Example 5. Currently this pattern is quite cumbersome and error-prone to implement - it would be much nicer if some syntactic sugar could be provided that would turn it into a one liner like this:

// sum all values in a mapping
ghost mathint sumOfPoints = always_sum(currentContract.allocations.points);

// sum values in a mapping for a given set of keys (here addresses)
ghost mathint sumOfPoints = always_sum(currentContract.balances, users);

Another potential improvement would be having certoraRun automagically read the library paths from the Hardhat/Foundry configuration so these wouldn’t need to be replicated inside the .conf file.

“Syntactic sugar” could condense the parameterized function calls eg:

// call anything
env e;
method f;
calldataarg args;
f(e, args);

// call anything syntactic sugar
call_anything();

// call anything as `user`
env e5;
require e5.msg.sender == user;
method f;
calldataarg args;
f(e5, args);

// call anything as `user` syntactic sugar
call_anything(msg.sender == user);

Conclusion

From the 10 fuzzing challenges based on simplified real-world vulnerabilities we were able to efficiently write 9 Certora specifications which correctly identified the same vulnerabilities, missing only challenge 8 due to CVL’s lack of support for returning the revert reason. In many cases the Certora solutions were more elegant and concise than the corresponding fuzzers since:

• there was no need to code setup or handlers

• due to Certora’s powerful features such as parametric rules

While it may sound daunting to learn Certora’s domain specific language, using the Certora lessons in Updraft’s free course and the official user guide I was able to learn enough CVL to write these solutions and this deep dive in only 7 days - if I can do it, then so can you!

Formal Verification using Certora is an effective tool which smart contract developers can use to identify a wide range of vulnerabilities prior to external audit. Certora’s generous free tier allows developers and auditors to sign up for free and get a lot of free usage every month, more than sufficient for most small-medium size protocols.

2026 Update - RareSkills has published a great Certora tutorial!

Given the fees that “Tier 1” external audit firms charge per week, having the invariant tests done in-house prior to external audit is also more cost-effective. This is especially the case as protocol developers already have full context of important protocol & contract properties so can more rapidly write the invariants.

Thinking In Invariants

The primary skill developers need to acquire is learning to think in invariants. I have previously presented a simple framework for this which:

• uses Chimera to write one codebase that works across Echidna, Medusa & Foundry fuzzers while enabling easy cloud fuzzing using Recon

• breaks the contract lifecycle into at least 3 phases: construction/initialization, regular functioning and an optional end state

• categorizes invariants into 2 basic categories: “black box” which can be gleaned from the protocol design and documentation, and “white box” which are based upon the smart contract’s internal implementation code

Invariants can further be classified into the following types:

• Relationships between inter-related storage locations, eg:
  - the sum of all values in a mapping X must equal Y stored elsewhere in storage (regular, white box)
  - all addresses present in EnumerableSet X must also exist as keys in mapping Y (regular, white box)

• Monetary value held by contract/protocol and solvency requirements, eg:
  - Once token/reward/yield distribution is complete the contract should have 0 balance (end state, black box)
  - contract should always have enough tokens to cover liabilities (regular, black box)

• Logical invariants that prevent invalid states, eg:
  - account with active borrow can’t exit market where they borrowed from (regular, black box)
  - protocol should never enter a state where borrower can be liquidated but can’t repay (regular, black box)

• Denial of Service (DoS) from unexpected errors, eg:
  - liquidation should never revert with unexpected errors such as access array out of bounds, under/overflow etc (regular, white box)

Handlers Vs No Handlers

Invariant fuzzers can use “handler” functions which wrap underlying functions from the target contract, satisfying preconditions to prevent trivial reverts. Alternatively fuzzers can also use no handlers which lets the fuzzer explore freely. The trade-offs between these choices are:

• when using no handlers, if the search space is too large the fuzzer may not have enough time to find invariant-breaking sequences and there may be many wasted runs due to trivial reverts

• using handlers eliminates wasted runs due to trivial reverts increasing the fuzz efficiency but also restricts the search space so may miss some invariant-breaking sequences

In general most developers will want to use handlers in order to improve the efficiency of their fuzz runs by satisfying basic preconditions, while being mindful not to overly-constrain the fuzz inputs.

Example 1 - Flash Loan Denial Of Service

Specification: there are 2 contracts Receiver and Lender. Receiver has a function executeFlashLoan that calls Lender::flashLoan to take a flash loan, and the important invariant is that Receiver should always be able to take a flash loan if Lender has sufficient tokens available. Simply from this specification without even looking at the code we could write a (regular, black box) invariant like this:

function invariant_receiver_can_take_flash_loan() public returns (bool result) {
    receiver.executeFlashLoan(10);
    result = true;
}

By examining the implementation of Lender::flashLoan we can write an even more specific (regular, white box) invariant based on the knowledge of how that function works:

function invariant_pool_bal_equal_token_pool_bal() public view returns(bool result) {
    result = pool.poolBalance() == token.balanceOf(address(pool));
}

Generally fuzzers are more easily able to break the second more specific white box invariant and it is harder for them to break the first more generic black box invariant. In this case Foundry, Echidna & Medusa can all break both invariants.

Neither of these invariants took any special auditor-specific skills to write; the protocol developer could easily write such invariants as part of the protocol’s test suite.

While this was not a real codebase as it was taken from Damn Vulnerable DeFi Unstoppable challenge, all of the following simplified examples will be from my private audit findings on real codebases while working with Cyfrin.

Example 2 - Reward Distribution Stuck

Specification: a Proposal contract is deployed by a DAO with some ETH to be distributed if the proposal succeeds:

• Proposal is active until voting has finished or the proposal has timed out

• While active, eligible voters can vote for or against

• if quorum is reached the ETH should be distributed between the for voters

• otherwise the ETH should be refunded to the proposal creator

Without even looking at the implementation we can write a black box invariant that covers both the regular functioning and the end state:

function property_proposal_complete_all_rewards_distributed() public returns(bool) {
    uint256 proposalBalance = address(prop).balance;

    // only visible when invariant fails
    emit ProposalBalance(proposalBalance);

    return(
        // either proposal is active and contract balance > 0
        (prop.isActive() && proposalBalance > 0) ||

        // or proposal is not active and contract balance == 0
        (!prop.isActive() && proposalBalance == 0)
    );
}

This invariant uncovered a High severity issue that resulted in tokens being permanently stuck in the contract.

Example 3 - Voting Power Destruction

Specification: a VotingNft contract:

• allows users to deposit ETH collateral against their NFT to give it DAO voting power

• NFTs can be created by the owner until the “power calculation start time”

• Once power calculation begins all NFTs start with max voting power which declines over time for NFTs which have not been backed by deposited ETH

• NFT voting power which has declined can never be increased; depositing the required ETH collateral simply prevents any future decrease

Purely from this specification we can write an (initialization, black box) invariant to verify that when power calculation begins, the total voting power of all NFTs is equal to the max voting power multiplied by the number of created NFTs:

function property_total_power_eq_init_max_power_calc_start() public view returns(bool result) {
    result = votingNft.getTotalPower() == initMaxNftPower;
}

This very simple invariant uncovered two serious issues:

• a Critical asymmetry vulnerability which a permission-less attacker could exploit to permanently set every NFT’s voting power to 0

• a High vulnerability that allowed a permission-less attacker to dramatically lower the total voting power to almost 0 while maintaining individual NFT voting power, massively increasing the voting power of any NFT holder

Example 4 - Token Sale Drain

Specification: a TokenSale contract:

• allows a DAO to sell its governance sellToken for another buyToken

• the token sale is only for allowed users and each user can only buy up to a max per-user limit to prevent concentration of voting power

• in our simplified version we assume an exchange rate of 1:1 and that sellToken always has decimals greater or equal to buyToken

Using only the specification we can create two (regular, black box) invariants. The first invariant verifies that the number of tokens bought matches the number of tokens sold (due to the simplified 1:1 exchange):

function invariant_tokens_bought_eq_tokens_sold() public view returns(bool result) {
    uint256 soldAmount = tokenSale.getSellTokenSoldAmount();
    uint256 boughtBal  = buyToken.balanceOf(address(this));

    // scale up `boughtBal` by the precision difference
    // SELL_DECIMALS >= BUY_DECIMALS
    boughtBal *= 10 ** (SELL_DECIMALS - BUY_DECIMALS);

    result = (boughtBal == soldAmount);
}

The second invariant verifies that a user can only buy up to the maximum sellToken amount allowed per user:

function invariant_max_token_buy_per_user() public view returns(bool result) {
    for(uint256 i; i<buyers.length; ++i) {
        address buyer = buyers[i];

        if(sellToken.balanceOf(buyer) > MAX_TOKENS_PER_BUYER) {
            return false;
        }
    }

    result = true;
}

These two simple invariants uncovered:

• a Critical rounding down to zero vulnerability found by my teammate which allowed a user to get free tokens

• a High vulnerability which allowed a user to bypass the per-user max buy token limit, buying all the tokens and hence gaining dominant voting power

Example 5 - Vesting Points Increase

Specification: a Vesting contract allocates points to users which can be used to redeem tokens once their vesting period has been served. The contract implements an initialization invariant in the constructor ensuring that all points are allocated:

require(totalPoints == TOTAL_POINTS, "Not enough points");

Users can transfer their points to another address but apart from this users have no way to increase or decrease their allocated points, hence the sum of individual user points should always remain equal to the initial total allocated.

From the specification we can write a (regular, black box) invariant to verify that the sum of all user points always remains equal to the initial total allocated points:

function property_users_points_sum_eq_total_points() public view returns(bool result) {
    uint24 totalPoints;

    // sum up all user points using `recipients` ghost variable
    for(uint256 i; i<recipients.length; i++) {
        (uint24 points, , ) = vesting.allocations(recipients[i]);

        totalPoints += points;
    }

    // true if invariant held, false otherwise
    if(totalPoints == TOTAL_POINTS) result = true;

    // note: Solidity always initializes to default values
    // so no need to explicitly set result = false as false
    // is the default value for bool
}

This invariant exposed a High severity vulnerability which allowed users to give themselves an infinite number of points and hence drain the token allocation.

Example 6 - Vesting Preclaim Abuse

Specification: a VestingExt contract contains the same functionality as the previous Vesting contract plus an additional feature which lets users preclaim part of their token allocation, allowing users to get a limited amount of tokens before their vesting period is served.

Using only the specification we can create a (regular, black box) invariant which verifies the total preclaimed points is always less than or equal to the maximum preclaimable points (which is just the number of users multiplied by the maximum preclaim point amount per user):

function property_total_preclaimed_lt_eq_max_preclaimable() public view returns(bool result) {
    result = totalPreclaimed <= MAX_PRECLAIMABLE;
}

This invariant discovered a Medium severity vulnerability which allowed users to preclaim their entire token allocation and in the case of the code under audit, rapidly gain more voting power in the DAO than they should be able to.

Example 7 - Operator Registry Corruption

Specification: an OperatorRegistry contract allows users to register as operators and receive an operatorId where the first operatorId = 1 and subsequent ids are incremented.

The contract storage has multiple inter-related data structures which use both the user’s address and operatorId as keys in mappings to reference one another, enabling lookup of operator data by either address or operatorId. Users can also update their address.

From this specification we can write a (regular, black box) invariant that verifies the data integrity of these inter-related data structures by ensuring that every operatorId is related to a unique address:

EnumerableSet.AddressSet foundAddresses;

function property_operator_ids_have_unique_addresses() public returns(bool result) {
    // first remove old found from ghost storage
    uint256 oldFoundLength = foundAddresses.length();
    if(oldFoundLength > 0) {
        address[] memory values = foundAddresses.values();

        for(uint256 i; i<oldFoundLength; i++) {
            foundAddresses.remove(values[i]);
        }
    }

    // then iterate over every current operator, fetch its address
    // and attempt to add it to the found set. If the add fails it is
    // a duplicate breaking the invariant
    uint128 numOperators = operatorRegistry.numOperators();
    if(numOperators > 0) {
        // operator ids start at 1
        for(uint128 operatorId = 1; operatorId <= numOperators; operatorId++) {
            if(!foundAddresses.add(operatorRegistry.operatorIdToAddress(operatorId))) {
                return false;
            }
        }
    }

    result = true;
}

This invariant uncovered a Low severity issue found by my teammate where two different operatorIds could point to the same user address & associated data, corrupting the inter-related data structure relationships. This was a Low severity issue in our audit as the function which triggered the corruption was permissioned and the impact was limited but this could easily have Medium or High severity in other codebases depending on how the corruption could be triggered and exploited.

Example 8 - Liquidate Denial Of Service

Specification: a LiquidateDos contract allows traders to enter multiple markets and have one open position in each market. Traders can also be liquidated:

• all open positions are accounted when determining if a trader is liquidatable

• if liquidated, all open positions are closed for the trader being liquidated

• liquidation should never fail with unexpected errors

Using this specification we can write a (regular, white box) invariant that verifies the liquidate function doesn’t revert with unexpected errors. This invariant is white box as it requires us to know the specific implementation details of liquidate in order to know which errors are expected.

When implementing DoS invariant fuzz tests there are two approaches:

1. run Echidna and Medusa in assertion mode, and have assertions in the fuzz handler - but this won’t work with Foundry

2. have a bool ghost variable which is set in the fuzz handler then wrap an invariant around it - this works with all 3 fuzzers

Here is the handler and invariant using the second implementation:

// TargetFunctions fuzz handler
function handler_liquidate(uint8 victimIndex) external {
    address victim = _getRandomAddress(victimIndex);

    try liquidateDos.liquidate(victim) {
        // update ghost variables
        delete userActiveMarketsCount[victim];

        for(uint8 marketId = liquidateDos.MIN_MARKET_ID();
            marketId <= liquidateDos.MAX_MARKET_ID();
            marketId++) {
            delete userActiveMarkets[victim][marketId];
        }
    }
    catch(bytes memory err) {
        bytes4[] memory allowedErrors = new bytes4[](2);
        allowedErrors[0] = ILiquidateDos.LiquidationsDisabled.selector;
        allowedErrors[1] = ILiquidateDos.LiquidateUserNotInAnyMarkets.selector;

        if(_isUnexpectedError(bytes4(err), allowedErrors)) {
            liquidateUnexpectedError = true;
        }
    }
}

// returns whether error was unexpected
function _isUnexpectedError(
    bytes4 errorSelector,
    bytes4[] memory allowedErrors
) internal pure returns(bool isUnexpectedError) {
    for (uint256 i; i < allowedErrors.length; i++) {
        if (errorSelector == allowedErrors[i]) {
            return false;
        }
    }

    isUnexpectedError = true;
}

// Properties invariant
function property_liquidate_no_unexpected_error() public view returns(bool result) {
    result = !liquidateUnexpectedError;
}

This invariant uncovered a Critical severity vulnerability which a trader could weaponize to make themselves impossible to liquidate.

Example 9 - Stability Pool Drain

Specification: a StabilityPool contract which:

• allows users to deposit debtToken which is used to pay down bad debt during liquidations

• in exchange debtToken depositors receive a share of collateralToken rewards from collateral seized during liquidations

• contains quite complicated logic to calculate the reward share debtToken depositors should receive

• must always remain solvent; the pool should always have sufficient collateralToken to pay out rewards owed to debtToken depositors

A (regular, black box) invariant which naturally flows from the specification is to verify the pool’s solvency:

function property_stability_pool_solvent() public view returns(bool result) {
    uint256 totalClaimableRewards;

    // sum total claimable rewards for each possible user
    for(uint8 i; i<ADDRESS_POOL_LENGTH; i++) {
        address user = addressPool[i];

        totalClaimableRewards += stabilityPool.getDepositorCollateralGain(user);
    }

    // pool is solvent if the total claimable rewards are
    // lte its collateral token balance
    if(totalClaimableRewards <= collateralToken.balanceOf(address(stabilityPool)))
        result = true;
}

This simple invariant uncovered a Critical vulnerability in the original protocol from which the code I was auditing was forked. The vulnerability had been introduced in a “small fix” and laid dormant in the codebase for 1 year; it allowed a debtToken depositor to completely drain all collateralTokens from the StabilityPool.

The simplicity of this invariant serves to illustrate the great power of invariant fuzz testing: without understanding the complicated reward calculation code, we can write a simple black box invariant which the fuzzer will break finding an extremely valuable Critical exploit.

Example 10 - Collateral Priority Corruption

Specification: a Priority contract used in multi-collateral lending protocols:

• defines a liquidation priority order for collaterals

• when a liquidation occurs, the riskiest collaterals are liquidated first such that the borrower’s remaining collateral basket is more stable post-liquidation

• allows collaterals to be added and removed; adding always puts the new collateral at the end of the priority queue while removing preserves the existing order minus the removed element

From the specification we can write a (regular, black box) invariant to verify the collateral order is always correct. To simplify the implementation in our fuzz test we use 4 collaterals, update the expected order in the fuzz handlers then compare the expected order to the actual in the invariant:

// TargetFunctions fuzz handlers update ghost variable expected order
function handler_addCollateral(uint8 collateralId) external {
    collateralId = uint8(between(collateralId,
                                 priority.MIN_COLLATERAL_ID(),
                                 priority.MAX_COLLATERAL_ID()));

    priority.addCollateral(collateralId);

    // update ghost variables with expected order
    if(priority0 == 0) priority0 = collateralId;
    else if(priority1 == 0) priority1 = collateralId;
    else if(priority2 == 0) priority2 = collateralId;
    else priority3 = collateralId;
}

function handler_removeCollateral(uint8 collateralId) external {
    collateralId = uint8(between(collateralId,
                                 priority.MIN_COLLATERAL_ID(),
                                 priority.MAX_COLLATERAL_ID()));

    priority.removeCollateral(collateralId);

    // update ghost variables with expected order
    if(priority0 == collateralId) {
        priority0 = priority1;
        priority1 = priority2;
        priority2 = priority3;
    }
    else if(priority1 == collateralId) {
        priority1 = priority2;
        priority2 = priority3;
    }
    else if(priority2 == collateralId) {
        priority2 = priority3;
    }

    delete priority3;
}

// Properties invariant
function property_priority_order_correct() public view returns(bool result) {
    if(priority0 != 0) {
        if(priority.getCollateralAtPriority(0) != priority0) return false;
    }
    if(priority1 != 0) {
        if(priority.getCollateralAtPriority(1) != priority1) return false;
    }
    if(priority2 != 0) {
        if(priority.getCollateralAtPriority(2) != priority2) return false;
    }
    if(priority3 != 0) {
        if(priority.getCollateralAtPriority(3) != priority3) return false;
    }

    result = true;
}

This invariant uncovered a High vulnerability that corrupted the collateral priority order resulting in incorrect collateral being prioritized for liquidation, which results in traders being left with an unhealthier collateral basket post-liquidation increasing the likelihood of future liquidations.

Conclusion

We have reviewed 9 simplified examples from my private audits on real codebases where invariant fuzz testing could have been used “in-house” by protocol developers to detect and fix important vulnerabilities prior to engaging external auditors.

Only 1 of these invariants was white box meaning that to write it required understanding of smart contract internal implementation details. The other 8 were all black box so could be deduced simply from the protocol or contract specification. All 9 invariants were relatively simple to write and implement.

Protocol developers and smart contract auditors can significantly improve the security of their protocols by learning to think in invariants and implementing invariant fuzz tests as part of their work.

Additional Resources

• EVM Fuzzing Resources

Chimera is best thought of as a “swiss army knife” - collection of tools that allow smart contract developers and auditors to use as few or as many of the tools, in order to achieve the goal of writing one codebase that can be used to execute multiple fuzzers.

Let’s explore how to use Chimera to write a smart contract invariant fuzz testing suite using a simplified version of a real finding from a recent private audit. The full code can be found in my Solidity Fuzzing Challenge repository.

Vulnerable Vesting Contract

Our vulnerable contract Vesting.sol implements a simplified vesting scheme where users receive points which can be redeemed for tokens once the vesting period has expired. Much of the complexity has been removed to only contain the code and functionality relevant to our example:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.23;

contract Vesting {
    uint24 public constant TOTAL_POINTS = 100_000;

    struct AllocationInput {
        address recipient;
        uint24 points;
        uint8  vestingWeeks;
    }

    struct AllocationData {
        uint24 points;
        uint8  vestingWeeks;
        bool   claimed;
    }

    mapping(address recipient => AllocationData data) public allocations;

    constructor(AllocationInput[] memory allocInput) {
        uint256 inputLength = allocInput.length;
        require(inputLength > 0, "No allocations");

        uint24 totalPoints;
        for(uint256 i; i<inputLength; i++) {
            require(allocInput[i].points != 0, "Zero points invalid");
            require(allocations[allocInput[i].recipient].points == 0, "Already set");

            totalPoints += allocInput[i].points;
            require(totalPoints <= TOTAL_POINTS, "Too many points");

            allocations[allocInput[i].recipient].points = allocInput[i].points;
            allocations[allocInput[i].recipient].vestingWeeks = allocInput[i].vestingWeeks;
        }

        require(totalPoints == TOTAL_POINTS, "Not enough points");
    }

    // users entitled to an allocation can transfer their points to
    // another address if they haven't claimed
    function transferPoints(address to, uint24 points) external {
        require(points != 0, "Zero points invalid");

        AllocationData memory fromAllocation = allocations[msg.sender];
        require(fromAllocation.points >= points, "Insufficient points");
        require(!fromAllocation.claimed, "Already claimed");

        AllocationData memory toAllocation = allocations[to];
        require(!toAllocation.claimed, "Already claimed");

        // enforce identical vesting periods if `to` has an active vesting period
        if(toAllocation.vestingWeeks != 0) {
            require(fromAllocation.vestingWeeks == toAllocation.vestingWeeks, "Vesting mismatch");
        }

        allocations[msg.sender].points = fromAllocation.points - points;
        allocations[to].points = toAllocation.points + points;

        // if `to` had no active vesting period, copy from `from`
        if (toAllocation.vestingWeeks == 0) {
            allocations[to].vestingWeeks = fromAllocation.vestingWeeks;
        }
    }
}

Thinking In Invariants

The primary challenge of writing good invariant fuzz tests is learning to think in terms of contract and protocol invariants. One systematic way to do this is to think in terms of “contract lifecycle” and “white/black-box”.

Contract Lifecycle

Smart contracts have 3 primary phases of life:

• construction / initialization

• regular functioning

• optionally an end state

It can be helpful to think of which properties must remain true during each of these life phases. For example in our contract at the initialization state, the total amount of points allocated to recipients must equal the expected total number of points. Since this invariant is “cheap” (in terms of gas costs) to implement, it makes sense to implement it directly into our code.

During the regular functioning and end of life phases of the contract lifecycle, a good invariant property would be:

• the total amount of points allocated to users must remain equal to the total number of points

However this invariant property is “expensive” in that it is cost-prohibitive to iterate and sum every user’s points at the smart contract level. Hence such invariants should be implemented “off-chain” by developers as part of a protocol’s invariant fuzz tests.

White/Black Box

Another way of thinking about invariants is in terms of white or black boxes.

A “white box” invariant is one that we implement based upon internal knowledge of how the smart contract works, while a “black box” invariant is a property that we can glean from the protocol’s design or documentation, without needing to know about the internals of how the protocol actually implements its functionality.

For the full version of the contract a useful “end state” invariant would be that the total amount of tokens which have been distributed to users is equal to the amount of vested tokens. This invariant is “black-box” since we don’t need to know anything about the contract’s underlying implementation, we just know this property exists and should be true at the end state.

Writing The Test Setup

The first thing we need to do is create a Setup.sol file which will inherit from Chimera’s BaseSetup contract. Our Setup contract can:

• either inherit directly from the contract being tested or have that contract as a member variable

• contain “ghost” variables use to track important state for comparison with contract state during invariant checks

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.23;

import { Vesting } from "../../src/09-vesting/Vesting.sol";
import { BaseSetup } from "@chimera/BaseSetup.sol";

abstract contract Setup is BaseSetup {
    // contract being tested
    uint24 constant TOTAL_POINTS = 100_000;
    Vesting vesting;

    // ghost variables
    address[] recipients;

    function setup() internal virtual override {
        // use two recipients with equal allocation
        recipients.push(address(0x1111));
        recipients.push(address(0x2222));

        // prepare allocation array
        Vesting.AllocationInput[] memory inputs
            = new Vesting.AllocationInput[](2);
        inputs[0].recipient = recipients[0];
        inputs[0].points = TOTAL_POINTS / 2;
        inputs[0].vestingWeeks = 10;
        inputs[1].recipient = recipients[1];
        inputs[1].points = TOTAL_POINTS / 2;
        inputs[1].vestingWeeks = 10;

        vesting = new Vesting(inputs);
    }
}

Avoid Fuzzer-Specific Cheatcodes In Setup

When writing the test setup we need to avoid using fuzzer-specific cheatcodes. A good way to do this is to only use cheatcodes from Chimera’s IHevm interface which prevents using any cheatcodes that won’t work across all fuzzers.

Implementing The Invariants

Next we create a Properties.sol file to define our invariants; it inherits from our Setup contract and Chimera’s Asserts contract. In this file we will implement the invariants as Echidna/Medusa-style invariants which are functions that return a boolean and we’ll use property_ as the function prefix:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.23;

import { Setup } from "./Setup.sol";
import { Asserts } from "@chimera/Asserts.sol";

abstract contract Properties is Setup, Asserts {

    function property_users_points_sum_eq_total_points() public view returns(bool result) {
        uint24 totalPoints;

        // sum up all user points
        for(uint256 i; i<recipients.length; i++) {
            (uint24 points, , ) = vesting.allocations(recipients[i]);

            totalPoints += points;
        }

        // true if invariant held, false otherwise
        if(totalPoints == TOTAL_POINTS) result = true;

        // note: Solidity always initializes to default values
        // so no need to explicitly set result = false as false
        // is the default value for bool
    }
}

Wrapping The Target Functions

With our setup complete and invariants defined, the next step is to create “handlers” which “wrap” the target functions of the contract being tested. The general goals are to:

• exercise the contract’s functionality as organically as possible

• prevent wasted runs that would revert due to failing to satisfy basic preconditions

A “handler” is a function with a handler_ prefix followed by the underlying function name which wraps that function and satisfies required preconditions. Create a new file TargetFunctions.sol which inherits from our Properties contract and Chimera’s BaseTargetFunctions contract:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.23;

import { Properties } from "./Properties.sol";
import { BaseTargetFunctions } from "@chimera/BaseTargetFunctions.sol";
import { IHevm, vm } from "@chimera/Hevm.sol";

abstract contract TargetFunctions is BaseTargetFunctions, Properties {

    function handler_transferPoints(uint256 recipientIndex,
                                    uint256 senderIndex,
                                    uint24 pointsToTransfer) external {
        // get an index into the recipients array to randomly
        // select a valid recipient
        //
        // note: using `between` provided by Chimera instead of
        // Foundry's `bound` for cross-fuzzer compatibility
        recipientIndex = between(recipientIndex, 0, recipients.length-1);
        senderIndex    = between(senderIndex, 0, recipients.length-1);

        address sender = recipients[senderIndex];
        address recipient = recipients[recipientIndex];

        (uint24 senderMaxPoints, , ) = vesting.allocations(sender);

        pointsToTransfer = uint24(between(pointsToTransfer, 1, senderMaxPoints));

        // note: using `vm` from Chimera's IHevm
        // for cross-fuzzer cheatcode compatibility
        vm.prank(sender);
        vesting.transferPoints(recipient, pointsToTransfer);
    }
}

Writing Echidna & Medusa Front-End

Now that all of our components are in-place, we only need to write the “front-end” contracts for our fuzzers and provide any configuration files. Firstly let’s write the Echidna & Medusa front-end VestingCryticTester.sol which is used to execute the Echidna and Medusa fuzzers. It inherits from our TargetFunctions contract and Chimera’s CryticAsserts contract:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.23;

import { TargetFunctions } from "./TargetFunctions.sol";
import { CryticAsserts } from "@chimera/CryticAsserts.sol";

// configure solc-select to use compiler version:
// solc-select install 0.8.23
// solc-select use 0.8.23
//
// run from base project directory with:
// echidna . --contract VestingCryticTester --config test/09-vesting/echidna.yaml
// medusa --config test/09-vesting/medusa.json fuzz
contract VestingCryticTester is TargetFunctions, CryticAsserts {
  constructor() payable {
    setup();
  }
}

Echidna Config

We also need to create the following configuration file echidna.yaml:

# don't allow fuzzer to use all functions
# since we are using handlers
allContracts: false

# record fuzzer coverage to see what parts of the code
# fuzzer executes
corpusDir: "./test/09-vesting/coverage-echidna"

# prefix of invariant function
prefix: "property_"

# instruct foundry to compile tests
cryticArgs: ["--foundry-compile-all"]

Medusa Config

Similarly we need to create Medusa’s configuration file medusa.json:

{
    "fuzzing": {
        "workers": 10,
        "workerResetLimit": 50,
        "_COMMENT_TESTING_1": "changed timeout to limit fuzzing time",
        "timeout": 10,
        "testLimit": 0,
        "callSequenceLength": 100,
        "_COMMENT_TESTING_8": "added directory to store coverage data",
        "corpusDirectory": "coverage-medusa",
        "coverageEnabled": true,
        "_COMMENT_TESTING_2": "added test contract to deploymentOrder",
        "targetContracts": ["VestingCryticTester"],
        "targetContractsBalances": [],
        "constructorArgs": {},
        "deployerAddress": "0x30000",
        "senderAddresses": [
            "0x10000",
            "0x20000",
            "0x30000"
        ],
        "blockNumberDelayMax": 60480,
        "blockTimestampDelayMax": 604800,
        "blockGasLimit": 125000000,
        "transactionGasLimit": 12500000,
        "testing": {
            "stopOnFailedTest": true,
            "stopOnFailedContractMatching": true,
            "stopOnNoTests": true,
            "testAllContracts": false,
            "traceAll": false,
            "assertionTesting": {
                "enabled": false,
                "testViewMethods": false,
                "assertionModes": {
                    "failOnCompilerInsertedPanic": false,
                    "failOnAssertion": true,
                    "failOnArithmeticUnderflow": false,
                    "failOnDivideByZero": false,
                    "failOnEnumTypeConversionOutOfBounds": false,
                    "failOnIncorrectStorageAccess": false,
                    "failOnPopEmptyArray": false,
                    "failOnOutOfBoundsArrayAccess": false,
                    "failOnAllocateTooMuchMemory": false,
                    "failOnCallUninitializedVariable": false
                }
            },
            "propertyTesting": {
                "enabled": true,
                "_COMMENT_TESTING_6": "changed prefix to match invariant function",
                "testPrefixes": [
                    "property_"
                ]
            },
            "optimizationTesting": {
                "enabled": false,
                "testPrefixes": [
                    "optimize_"
                ]
            }
        },
        "chainConfig": {
            "codeSizeCheckDisabled": true,
            "cheatCodes": {
                "cheatCodesEnabled": true,
                "enableFFI": false
            }
        }
    },
    "compilation": {
        "platform": "crytic-compile",
        "platformConfig": {
            "_COMMENT_TESTING_7": "changed target to point to main directory where command is run from",
            "target": "./../../.",
            "solcVersion": "",
            "exportDirectory": "",
            "args": ["--foundry-compile-all"]
        }
    },
    "logging": {
        "level": "info",
        "logDirectory": ""
    }
}

Writing Foundry Front-End

The final piece required is our Foundry “front-end” contract; create a new file VestingCryticToFoundry.sol. This contract will:

• inherit from our TargetFunctions contract and Chimera’s FoundryAsserts contract

• programmatically implement required setup as Foundry doesn’t use configuration files

• wrap each of our Echidna/Medusa-style property_* invariants into Foundry-style invariant_* functions that simply assert the property_* functions return true:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.23;

import { TargetFunctions } from "./TargetFunctions.sol";
import { FoundryAsserts } from "@chimera/FoundryAsserts.sol";
import { Test } from "forge-std/Test.sol";

// run from base project directory with:
// forge test --match-contract VestingCryticToFoundry
// (if an invariant fails add -vvvvv on the end to see what failed)
//
// get coverage report (see https://medium.com/@rohanzarathustra/forge-coverage-overview-744d967e112f):
//
// 1) forge coverage --report lcov --report-file test/09-vesting/coverage-foundry.lcov --match-contract VestingCryticToFoundry
// 2) genhtml test/09-vesting/coverage-foundry.lcov -o test/09-vesting/coverage-foundry
// 3) open test/09-vesting/coverage-foundry/index.html in your browser and
//    navigate to the relevant source file to see line-by-line execution records

contract VestingCryticToFoundry is Test, TargetFunctions, FoundryAsserts {
    function setUp() public {
      setup();

      // Foundry doesn't use config files but does
      // the setup programmatically here

      // target the fuzzer on this contract as it will
      // contain the handler functions
      targetContract(address(this));

      // handler functions to target during invariant tests
      bytes4[] memory selectors = new bytes4[](1);
      selectors[0] = this.handler_transferPoints.selector;

      targetSelector(FuzzSelector({ addr: address(this), selectors: selectors }));
    }

    // wrap every "property_*" invariant function into
    // a Foundry-style "invariant_*" function
    function invariant_users_points_sum_eq_total_points() public {
      assertTrue(property_users_points_sum_eq_total_points());
    }
}

Running All Fuzzers

Now we can run all 3 fuzzers from the project directory like this:

echidna . --contract VestingCryticTester --config test/09-vesting/echidna.yaml
medusa --config test/09-vesting/medusa.json fuzz
forge test --match-contract VestingCryticToFoundry

Additionally all 3 fuzzers will generate their own coverage folder where we can inspect line-by-line coverage. Checking coverage is very important when building a test suite for your protocol to ensure that all the relevant lines are being exercised by the test suite.

Using Chimera to build the fuzz suite also allows easy cloud-based fuzzing via getrecon.xyz.

Verifying The Fix

All 3 fuzzers are easily able to break the invariant; the Vesting::transferPoints function is vulnerable to self-transfer where a user can transfer points to themselves which ends up increasing their points. This could be weaponized by a user to give themselves maximum points then drain the entire token allocation.

To fix this prevent self-transfer in Vesting::transferPoints:

    function transferPoints(address to, uint24 points) external {
        require(points != 0, "Zero points invalid");
+       require(msg.sender != to, "Self transfer invalid");

Then re-run all 3 fuzzers and verify none are able to break the invariant.

Conclusion

Chimera is an excellent framework that lets smart contract developers and auditors more easily write invariant fuzz testing suites which can be used across multiple fuzzers. Smart contract developers should strongly consider defining contract and protocol invariants and using Chimera to create multi-fuzzer invariant fuzz testing suites for their protocols.

• Provers to make claims without revealing the private information they use to make those claims

• Verifiers to verify claims made by a Prover without having to trust the Prover or know any of the private information the Prover used to make their claims

ZK Properties

ZK systems have 3 important properties:

1. Completeness - given valid inputs, the Prover is able to generate valid Proofs which are accepted by the Verifier

2. Soundness - a malicious Prover is unable (in practice has a very low probability) to generate invalid / forged Proofs which will be accepted by the Verifier

3. Zero Knowledge - Private Inputs known by the Prover are not leaked and can’t be reverse engineered from the Proof or Public Inputs provided to the Verifier

ZK Vulnerabilities

Many vulnerabilities in ZK Circuits involve breaking one or more of these important properties; most circuit vulnerabilities can be categorized into 3 general categories:

1. Over-Constrained - a Prover is able to create a valid Proof but the Verifier is unable to verify it as the Circuit contains too many Constraints, breaking the "Completeness" property

2. Under-Constrained - a malicious Prover can create an invalid Proof which the Verifier subsequently verifies as the Circuit contains too few Constraints, breaking the "Soundness" property

3. Non-Zero Knowledge - the Private Inputs used by the Prover leak out or are able to be reverse-engineered by the Verifier or other observers, breaking the "Zero Knowledge" property

Vulnerable Circuit - "Is Not Prime"

Let's start off by creating a Circuit to prove that a number is not a prime number. To setup the repository use one of the Circom “starter” repositories which integrate Hardhat [1,2] for easier compilation & testing workflow. For this example we'll use the second link then:

• copy the 2-hardhat-integration into a new folder to be our project folder

• change the URL for ptau in hardhat.config.js to be ptau: "<https://hermez.s3-eu-west-1.amazonaws.com/powersOfTau28_hez_final_15.ptau>"

For simplicity we won’t create new files but simply edit already existing files; start by putting our example Circuit code inside circuits/multiplier.circom:

pragma circom 2.1.4;

// Prover uses Circuit `IsNotPrime` to prove that `val` is not 
// a prime number without revealing the private factors
// which the Prover knows and uses to prove this
template IsNotPrime() {
    signal input factorOne;
    signal input factorTwo;
    signal input val;

    // constraint: factors multipled result in val
    // will fail for prime numbers
    val === factorOne * factorTwo;
}

// `val` is public, factors are private
component main {public [val]} = IsNotPrime();

This Circuit:

• takes 1 Public Input val which is the number the Prover claims is not prime

• takes 2 Private Inputs factorOne and factorTwo which are secret inputs the Prover uses to assert their claim; these should never be leaked or otherwise disclosed to the Verifier or other observers

• contains 1 Constraint (using the === operator) which enforces that the multiplication of factorOne and factorTwo results in val - if this is true then val should not be prime

Next put the inputs inside circuits/multiplier.json:

{
    "val": 21,
    "factorOne": 3,
    "factorTwo": 7
}

Then put the test inside test/multiplier.test.js:

const hre = require("hardhat");
const { assert } = require("chai");

describe("multiplier circuit", () => {
  let circuit;

  const sampleInput = {
    val: "21",
    factorOne: "7",
    factorTwo: "3"
  };
  const sanityCheck = true;

  before(async () => {
    circuit = await hre.circuitTest.setup("multiplier");
  });

  it("produces a witness with valid constraints", async () => {
    const witness = await circuit.calculateWitness(sampleInput, sanityCheck);
    await circuit.checkConstraints(witness);
  });

  it("has expected witness values", async () => {
    const witness = await circuit.calculateLabeledWitness(
      sampleInput,
      sanityCheck
    );
    assert.propertyVal(witness, "main.val", sampleInput.val);
    assert.propertyVal(witness, "main.factorOne", sampleInput.factorOne);
    assert.propertyVal(witness, "main.factorTwo", sampleInput.factorTwo);
  });
});

Compile with yarn circom:dev and run the test with yarn test - everything passes and our Circuit appears to be working correctly!

Exploiting Under-Constrained Factors

Recall that the Circuit has only 1 Constraint: the product of both factors must equal the value being proved:

// constraint: factors multipled result in val
// will fail for prime numbers
val === factorOne * factorTwo;

However there are no Constraints on the possible values of factorOne and factorTwo; the Prover can set these to whatever they like. Could a malicious Prover abuse this to create a false Proof? It turns out the answer is yes.

A Prime Number is an unsigned integer which:

• is greater than 1

• cannot be written as a product of two smaller numbers which are themselves also greater than 1

Change sampleInput in test/multiplier.test.js to multiply the number being proved by 1:

  const sampleInput = {
    val: "7",
    factorOne: "1",
    factorTwo: "7"
  };

Then re-run the test suite using yarn test and everything passes - a malicious Prover was able to exploit the under-constraining of factorOne and factorTwo to create a false Proof which successfully verified the number 7 is not a prime number, which of course is incorrect as 7 is a prime number!

Constraining The Factors

As the Circuit is Under-Constrained we'll need to add additional Constraints to prevent factorOne and factorTwo from being equal to 1. In Solidity this would be relatively simple:

require(factorOne != 1 && factorTwo != 1);

However Circom Constraints must be Quadratic Equations so they can be easily used with the Rank One Constraint System (R1CS). Hence we must use some mathematical tricks to express require(x != 1) in a compatible form. To do this we will modify one math trick already in the circomlib library; put the new expanded Circuit into circuits/multiplier.circom:

pragma circom 2.1.4;

// slightly modified from
// https://github.com/iden3/circomlib/blob/master/circuits/comparators.circom#L24-L34
// math hack to implement `require(input != 1)`
// doesn't gracefully handle case where input == 0
// but that isn't required for this circuit
// as factors of 0 couldn't be used to create
// false proofs
template IsOne() {
    signal input in;
    signal output out;

    // intermediate signal
    signal inv;

    // store into `inv` intermediate signal:
    //   if input != 1 -> inv = 1/in
    // else input == 1 -> inv = 0
    inv <-- in != 1 ? 1/in : 0;

    // store and constrain `out` using a math trick that
    // will make the constraint at the end fail for input == 1
    //
    // case a) if input was 1 then inv = 0
    //         out <== -1 * 0 + 1
    //         out <== 1 (will make constraint at end fail)
    // case b) if input was 2 then inv = 1/2
    //         out <== -2*1/2 + 1
    //         out <== -1 + 1
    //         out <== 0
    out <== -in*inv + 1;

    // constraint prevents factors of 1
    // case a) if input was 1 then in = 1 and out = 1
    //         in*out = 1*1 = 1 -> constraint fails
    // case b) if input was 2 then in = 2 and out = 0
    //         in*out = 2*0 = 0 -> constraint passes
    in*out === 0;
}

// Prover uses Circuit `IsNotPrime` to prove that `val` is not 
// a prime number without revealing the private factors
// which the Prover knows and uses to prove this
template IsNotPrime() {
    signal input factorOne;
    signal input factorTwo;
    signal input val;

    // constraint: factors multiplied result in val
    // will fail for prime numbers
    val === factorOne * factorTwo;

    // prevent factorOne == 1
    component f1Check = IsOne();
    f1Check.in <== factorOne;

    // prevent factorTwo == 1
    component f2Check = IsOne();
    f2Check.in <== factorTwo;
}

// `val` is public, factors are private
component main {public [val]} = IsNotPrime();

After compiling again with yarn circom:dev, change the test sampleInputs inside test/multiplier.test.js to use different values for different runs to verify that the Prover can no longer create a false Proof by multiplying val by 1:

  // fails as factorOne == 1
  const sampleInput = {
    val: "21",
    factorOne: "1",
    factorTwo: "21"
  };

  // fails as factorTwo == 1
  const sampleInput = {
    val: "21",
    factorOne: "21",
    factorTwo: "1"
  };

  // succeeds as factorOne != 1 and
  //             factorTwo != 1 and
  //             factorOne * factorTwo == val
  const sampleInput = {
    val: "21",
    factorOne: "7",
    factorTwo: "3"
  };

  // fails as factorOne * factorTwo != val
  const sampleInput = {
    val: "21",
    factorOne: "7",
    factorTwo: "4"
  };

Our 2 additional Constraints and expanded test suite appears to have resolved the issue; a malicious Prover can no longer exploit the Circuit by having a prime number multiply itself by 1 to falsely prove it is not prime. However there is a much more subtle vulnerability still present..

Exploiting Modular Arithmetic Overflow In Finite Fields

ZK Circuits operate using Modular Arithmetic in a Finite Field Fp with a default value of p = 21888242871839275222246405745257275088548364400416034343698204186575808495617 though the value of p can be changed using the -p compilation option.

Due to Modular Arithmetic numbers wrap around; for simplicity consider p = 11 for a Finite Field F11. A Prover could then pass the following inputs to our "fixed" Circuit:

  const sampleInput = {
    val: "7",
    factorOne: "6",
    factorTwo: "3"
  };

When the Circuit executes, 6 * 3 = 18 wraps to 7 since 11 wraps to 0 due to Modular Arithmetic in F11 with p = 11 . A malicious Prover could exploit this overflow to create a false Proof that 7 is not a prime number! Hence the "fixed" Circuit still contains a critical and more subtle "Under-Constrained" vulnerability because there is no constraint on the range of inputs which operate using Modular Arithmetic within a Finite Field.

Range Constraints To Prevent Overflow

To handle the multiplication overflow from factorOne * factorTwo we'll need to constrain both factors such that their product is smaller than p of the Finite Field Fp. To achieve this we constrain each factor x in range 2 <= x < sqrt(p) ; in practice for Circom's default p we can use 2 <= x < 2 ** 100 but auditors must always be aware of which p value the Circuit they are auditing uses and the consequences this has for range constraints & overflow due to Modular Arithmetic.

For our updated solution we'll write a new InRange template to perform the range check leveraging some more math tricks from circomlib. This allows us to delete the previous Constraints enforcing factor != 1 as this is now handled by the range checks. Put the new complete code in circuits/multiplier.circom :

pragma circom 2.1.4;

// helpers taken from circomlib
template Num2Bits(n) {
    signal input in;
    signal output out[n];
    var lc1=0;

    var e2=1;
    for (var i = 0; i<n; i++) {
        out[i] <-- (in >> i) & 1;
        out[i] * (out[i] -1 ) === 0;
        lc1 += out[i] * e2;
        e2 = e2+e2;
    }

    lc1 === in;
}

template LessThan(n) {
    assert(n <= 252);
    signal input in[2];
    signal output out;

    component n2b = Num2Bits(n+1);

    n2b.in <== in[0]+ (1<<n) - in[1];

    out <== 1-n2b.out[n];
}

template LessEqThan(n) {
    signal input in[2];
    signal output out;

    component lt = LessThan(n);

    lt.in[0] <== in[0];
    lt.in[1] <== in[1]+1;
    lt.out ==> out;
}

template GreaterEqThan(n) {
    signal input in[2];
    signal output out;

    component lt = LessThan(n);

    lt.in[0] <== in[1];
    lt.in[1] <== in[0]+1;
    lt.out ==> out;
}

// written using circomlib helpers
// to enforce range constraints preventing
// overflow due to modular arithmetic
template InRange() {
    signal input a;
    signal input lowerbound;
    signal input upperbound;
    signal output out;

    // if lowerbound <= a <= upperbound return 1 else 0
    component lteCheck = LessEqThan(124);
    lteCheck.in[0] <== a;
    lteCheck.in[1] <== upperbound;

    component gteCheck = GreaterEqThan(124);
    gteCheck.in[0] <== a;
    gteCheck.in[1] <== lowerbound;

    out <== lteCheck.out * gteCheck.out;
}


// Prover uses Circuit `IsNotPrime` to prove that `val` is not 
// a prime number without revealing the private factors
// which the Prover knows and uses to prove this
template IsNotPrime() {
    signal input factorOne;
    signal input factorTwo;
    signal input val;

    // constraint: factors multiplied result in val
    // will fail for prime numbers
    val === factorOne * factorTwo;

    // Circom circuits: 
    // * operate in a Finite Field Fp where p is one of 
    //   several potential primes
    // * use Modular Arithmetic (mod p) such that
    //   p wraps back around to 0
    //
    // Consider simple case F11 so 11 wraps to 0, a Prover
    // could call this circuit with:
    // factorOne = 6
    // factorTwo = 3
    //       val = 7
    //
    // 6 * 3 = 18 which wraps to 7 due to mod 11
    // Hence the Prover could use this Circuit to
    // create a false proof that 7 is not prime
    // by exploiting overflow due to Modular Arithmetic
    //
    // To prevent overflow implement range check
    // constraints on the factors

    // {0, 1} not valid factors
    var MIN_RANGE = 2; 

    // must be below sqrt(p) for Fp, 2**100 works for default p
    // https://docs.circom.io/circom-language/basic-operators/#field-elements
    var MAX_RANGE = 2 ** 100;

    component f1RangeCheck = InRange();
    f1RangeCheck.a <== factorOne;
    f1RangeCheck.lowerbound <== MIN_RANGE;
    f1RangeCheck.upperbound <== MAX_RANGE;

    component f2RangeCheck = InRange();
    f2RangeCheck.a <== factorTwo;
    f2RangeCheck.lowerbound <== MIN_RANGE;
    f2RangeCheck.upperbound <== MAX_RANGE;

    // constraint to enforce factor range constraints
    1 === f1RangeCheck.out * f2RangeCheck.out;
}

// `val` is public, factors are private
component main {public [val]} = IsNotPrime();

While the factor range check Constraints prevent the overflow exploit, one necessary consequence to be aware of is that they also limit the range of numbers for which the Circuit can be used to prove a number is not a prime.

Additional Resources

Special thanks to rkm0959 and cergyk1337 for invaluable ZK insights and cyfrin.io for providing me with research time between audits to study and explore. Some helpful additional resources include:

• Taxonomy of ZK Vulns

• ZK Security Explained

• ZK Bug Tracker

Prerequisite Knowledge

In order to understand this deep dive you'll need to have completed at least Section 1 of Updraft's Assembly & Formal Verification course or already have equivalent knowledge of:

• EVM Opcodes

• EVM Stack Machine

• Solidity's Free Memory Pointer

• Foundry's Debugger

Memory Corruption From External Call

The return value of an external call is stored into memory at the Next Free Memory Address (NFMA), which is retrieved by reading memory at the Free Memory Pointer Address(FMPA - 0x40). If the smart contract developer has not accounted for this, when an external call occurs after an assembly block the return value of the external call can over-write data stored in memory by the preceding assembly block. This can result in insidious vulnerabilities if that data is used by subsequent calculations.

To see exactly how this memory corruption occurs examine this simplified stand-alone Foundry example based upon this real-world finding:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.26;

import {Test} from "forge-std/Test.sol";

// separate contracts accessed via interfaces
// prevents the optimizer from being "too smart", helping
// to better approximate real-world execution
interface IInfoRetriever {
    function getVal() external returns(uint256);
}

// this contract gets used to return additional
// values required by the primary computation
contract InfoRetriever is IInfoRetriever {
    uint256 returnVal = 3;

    function setVal(uint256 newVal) public {
        returnVal = newVal;
    }

    function getVal() external view returns(uint256) {
       return returnVal;
    }
}

interface IHasher {
    function hashInputs(uint256 a, uint256 b, uint256 additionalInputCount) external returns(bytes32 result);
}

// actual implementation that computes a hash of
// two primary inputs and an optional number of
// secondary inputs
contract HasherImpl is IHasher {

    // used to retrieve optional number of secondary inputs
    IInfoRetriever infoRetriever;

    constructor(IInfoRetriever _infoRetriever) {
        infoRetriever = _infoRetriever;
    }

    function _getSecondaryInputs(uint256 dataPtr, uint256 inputsToFetch) private returns(uint256) {
        for(uint256 i; i<inputsToFetch; i++) {
            // make external call to retrieve the data
            uint256 input = infoRetriever.getVal();

            assembly {
                // for each additional input, store it into memory
                // at next free memory address
                mstore(dataPtr, input)

                // update pointer to subsequent next free memory address
                dataPtr := add(dataPtr, 0x20)
            }
        }

        // returns updated dataPtr
        return dataPtr;
    }

    function hashInputs(uint256 a, uint256 b, uint256 additionalInputCount) external returns(bytes32 result) {
        uint256 dataPtr;

        assembly {
            // read free memory pointer to find next free memory address
            dataPtr := mload(0x40)

            // store `a` in memory at next free memory address
            mstore(dataPtr, a)

            // update pointer to subsequent next free memory address
            dataPtr := add(dataPtr, 0x20)

            // store `b` in memory at next free memory address
            mstore(dataPtr, b)

            // update pointer to subsequent next free memory address
            dataPtr := add(dataPtr, 0x20)
        }

        // get the additional input from the info retriever, passing the updated
        // `dataPtr` so any new elements will be saved in subsequent free memory
        // addresses
        dataPtr = _getSecondaryInputs(dataPtr, additionalInputCount);

        // compute hash of all inputs
        assembly {
            let startPtr := mload(0x40)
            result := keccak256(startPtr, sub(dataPtr, startPtr))
        }
    }
}

// test harness
contract HasherTest is Test {

    IInfoRetriever infoRetriever = new InfoRetriever();
    IHasher hasher = new HasherImpl(infoRetriever);
    uint256 a = 1;
    uint256 b = 2;

    function test_HashWithoutAdditionalInput() external {
        // works great
        bytes32 result = hasher.hashInputs(a, b, 0);

        assertEq(result, keccak256(abi.encode(1, 2)));
    }

    function test_HashWithAdditionalInput() external {
        // fails due to calculating incorrect hash
        bytes32 result = hasher.hashInputs(a, b, 1);

        assertEq(result, keccak256(abi.encode(1, 2, 3)));   
    }
}

This simplified example contains a contract HasherImpl whose purpose is to:

• receive a set of primary inputs (a, b)

• optionally retrieve a set of secondary inputs

• calculate a hash over the entire set of primary and secondary inputs

HasherImpl uses assembly to:

• correctly calculate Next Free Memory Addresses (NFMA)

• correctly store both primary and secondary inputs into NFMAs

• perform a gas-efficient hash over the entire input set

When no secondary inputs exist everything works correctly which can be verified by forge test --match-contract HasherTest --match-test test_HashWithoutAdditionalInput

However when using one or more secondary inputs the relevant test test_HashWithAdditionalInput fails as an incorrect hash is calculated. This occurs for two reasons - let's examine the first cause in detail!

Manual Assembly Analysis

Examining the assembly code superficially everything looks great; each primary and secondary input is saved into the NFMA and dataPtr is always updated to point to the next NFMA such that no variables will over-write each-other.

However when secondary inputs are retrieved a very subtle bug occurs due to the external call(s) to IInfoRetriever::getVal since:

• the manual assembly never updated the FMPA (0x40) and stored the first input a at the Starting Next Free Memory Address (SNFMA - 0x80)

• when setting up for the external call, the FMPA will be loaded from memory and a temporary value used in the external call will be stored at the address it points to (0x80)

• when the external call completes, the FMPA will again be loaded from memory and the return value stored at the address it points to (0x80)

• this causes memory corruption at 0x80, over-writing the input variable a both before and after the external call

Hence the hash will never execute over the entire input set since at least one of the inputs was over-written, resulting in an incorrect hash being calculated. Let's prove this is exactly what happens using Foundry's debugger to step through every opcode and see the exact moment when memory corruption occurs!

Opcode Execution Trace

To start the debugger execute forge test --match-contract HasherTest --debug test_HashWithAdditionalInput. We are concerned with the execution inside HasherImpl::hashInputs:

• from the first PUSH1(0x40) after calldata has been loaded onto the stack and JUMPDEST has been called

• until the memory corruption occurs

The relevant execution starts at PC 0x56 (86) and looks like this:

// push Free Memory Pointer Address (FMPA) onto stack
PUSH1(0x40) [Stack : 0x40, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]    
            [Memory: 0x40 = 0x80                             ]

// duplicate FMPA
DUP1        [Stack : 0x40, 0x40, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80                                   ]

// load Starting Next Free Memory Address (SNFMA) by reading FMPA
MLOAD       [Stack : 0x80, 0x40, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80                                   ]

// duplicate value of `a` input
DUP5        [Stack : 0x01, 0x80, 0x40, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80                                         ]

// duplicate SNFMA
DUP2        [Stack : 0x80, 0x01, 0x80, 0x40, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80                                               ]

// store value of `a` into memory at SNFMA
MSTORE      [Stack : 0x80, 0x40, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80, 0x80 = 0x01                      ]

// push 0x20 onto stack (2nd param of first `add` call)
// this is an offset to calculate Next Free Memory Address (NFMA)
PUSH1(0x20) [Stack : 0x20, 0x80, 0x40, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80, 0x80 = 0x01                            ]

// duplicate SNFMA
DUP2        [Stack : 0x80, 0x20, 0x80, 0x40, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80, 0x80 = 0x01                                  ]

// calculate NFMA by SNFMA + offset (0x80 + 0x20)
ADD         [Stack : 0xa0, 0x80, 0x40, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80, 0x80 = 0x01                            ]

// duplicate value of `b` input
DUP5        [Stack : 0x02, 0xa0, 0x80, 0x40, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80, 0x80 = 0x01                                  ]

// exchange 2nd and 1st elements
SWAP1       [Stack : 0xa0, 0x02, 0x80, 0x40, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80, 0x80 = 0x01                                  ]

// store value of `b` into memory at NFMA
MSTORE      [Stack : 0x80, 0x40, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80, 0x80 = 0x01, 0xa0 = 0x02         ]

// not sure what the purpose of this is?
PUSH1(0x00) [Stack : 0x00, 0x80, 0x40, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80, 0x80 = 0x01, 0xa0 = 0x02               ]

// exchange 3rd and 1st stack elements
SWAP2       [Stack : 0x40, 0x80, 0x00, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80, 0x80 = 0x01, 0xa0 = 0x02               ]

// calculate NFMA by SNFMA + offset (0x80 + 0x40) 
ADD         [Stack : 0xc0, 0x00, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80, 0x80 = 0x01, 0xa0 = 0x02         ]

// `a` and `b` primary inputs have been written to memory
// and the next free memory address 0xc0 has been calculated and
// on the stack. We skip opcodes concerned with calling internal 
// function `getSecondaryInputs` and evaluating `for` loop condition
// until we reach PC 0xc2 (194) which is setting up for the external
// call
DUP2        [Stack : 0xe1cb0e52..00, 0x80, 0xe1cb0e52..00, 0x5616..b72f, 0x00, 0x00, 0x00, 0x01, 0xc0, 0x71, 0xc0, 0x00, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80, 0x80 = 0x01, 0xa0 = 0x02                                                                                                 ]

// before making external call the value of `a` at 0x80 will be 
// over-written - memory corruption first occurs before external call!
MSTORE      [Stack : 0xe1cb0e52..00, 0x5616..b72f, 0x00, 0x00, 0x00, 0x01, 0xc0, 0x71, 0xc0, 0x00, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80,
                     0x80 = 0xe1cb0e52..00, // `a` over-written
                     0xa0 = 0x02]

// we then move forward into `InfoRetriever::getVal` until `RETURN`
// takes us back into `HasherImpl::_getSecondaryInputs` PC 0x0d5 (213),
// where we observe that 0x80 now contains the return value `3` from
// the external call
ISZERO      [Stack : 0x84, 0xe1cb0e52..00, 0x5616..b72f, 0x00, 0x00, 0x00, 0x01, 0xc0, 0x71, 0xc0, 0x00, 0x01, 0x02, 0x01, 0x43, 0xe98b5f2d]
            [Memory: 0x40 = 0x80,
                     0x80 = 0x03, // `a` over-written again
                     0xa0 = 0x02]

// manual assembly to store `3` gets executed at PC 0x10b (267)
// which stores the return value of the external call at 0xc0.
// however the return value `3` was also stored at 0x80 where `a` was 
// previously stored so the correct hash can no longer be computed.
// also note that solidity has updated the FMPA 0x40 to point to
// 0xa0 which is where we are storing the value of variable `b` meaning
// that the second input variable could also be over-written
MSTORE      [Memory: 0x40 = 0xa0, // FMPA updated to where `b` stored!
                     0x80 = 0x03, // `a` remains over-written
                     0xa0 = 0x02, // `b` correct
                     0xc0 = 0x03  // manual assembly stores return val]

The above opcode trace shows:

• the value of input variable a stored in memory at 0x80 gets over-written twice; once before and once after the external call

• Solidity has updated the FMPA to point to 0xa0 which is where the manual assembly is storing the value of input variable b - this makes it possible for future operations to also over-write the second input variable

• it is impossible to now calculate the correct hash as at least one input variable a has been over-written due to memory corruption caused by the manual assembly not accounting for how Solidity uses memory during the external function call

To fix this problem we need to modify the first block in our manual assembly to update the Free Memory Pointer Address (FMPA) to point to the Next Free Memory Address (NFMA) like so:

function hashInputs(uint256 a, uint256 b, uint256 additionalInputCount) external returns(bytes32 result) {
    uint256 dataPtr;

    assembly {
        // read free memory pointer to find next free memory address
        dataPtr := mload(0x40)

        // store `a` in memory at next free memory address
        mstore(dataPtr, a)

        // update pointer to subsequent next free memory address
        dataPtr := add(dataPtr, 0x20)

        // store `b` in memory at next free memory address
        mstore(dataPtr, b)

        // update pointer to subsequent next free memory address
        dataPtr := add(dataPtr, 0x20)

        // @audit this prevents the external call in `_getSecondaryInputs`
        // from over-writing value of `a` stored at 0x80
        //
        // update free memory pointer to point to next free memory address
        mstore(0x40, dataPtr)
    }

Making this change then re-running the Foundry debugger shows at PC 0x110 (272):

• the return value of the external call is stored in memory at 0xc0 with both primary and secondary input variables having been correctly stored in memory

• the FMPA 0x40 points to unused 0xe0 such that any new values stored in memory won't over-write the primary and secondary input variables required for the hash calculation

MSTORE      [Memory: 0x40 = 0xe0, // FMPA updated to unused value
                     0x80 = 0x01, // `a` correct
                     0xa0 = 0x02, // `b` correct
                     0xc0 = 0x03] // returned secondary input correct

However this is not enough as another subtle bug lies in wait to corrupt our hash calculation!

Assuming Unchanged Free Memory Pointer Address

Another subtle problem when mixing blocks of manual assembly with normal Solidity code is when the manual assembly code assumes that the Free Memory Pointer Address (FMPA) hasn't changed simply because it hasn't changed it - this is a dangerous assumption because the normal Solidity code in between manual assembly blocks could have updated the FMPA.

In the previous opcode execution trace we observed that:

• even before making our fix for the identified bug, Solidity updated the FMPA after returning the secondary input value from the external call

• our fix required a manual update to the FMPA before the external call

Any update to the FMPA is problematic for our code because the manual assembly block which calculates the hash:

• reads the Next Free Memory Address (NFMA) from the current FMPA

• assumes that the inputs to be hashed start at that NFMA

// compute hash of all inputs
assembly {
    // @audit assumes FMPA unchanged from first assembly block
    // where primary inputs are stored my first loading FMPA
    let startPtr := mload(0x40)
    result := keccak256(startPtr, sub(dataPtr, startPtr))
}

Hence once the external function which fetches the secondary inputs executes and the FMPA has been updated, the hashing code will never correctly hash the appropriate inputs even if memory corruption didn't occur. We can observe this in the opcode execution traces, firstly for the original version without our first fix starting from PC 0x079 (121):

// exchange 2nd and 1st stack elements
SWAP1       [Stack : 0xa0, 0x40, ......]    
            [Memory: 0x40 = 0xa0,
                     0x80 = 0x03, // value of 'a' corrupted by ext func
                     0xa0 = 0x02,
                     0xc0 = 0x03]

// call keccak256(offset, size)
// this will hash memory 0xa0 and 0xc0
// returning keccak256(abi.encode(2,3))
KECCAK256(0xa0, 0x40)

Secondly the same error occurs in our "fixed" version where the memory corruption issue has been resolved starting from PC 0x7e (126):

// exchange 2nd and 1st stack elements
SWAP1       [Stack : 0xe0, 0x00, ......]    
            [Memory: 0x40 = 0xe0,
                     0x80 = 0x01, // no memory corruption
                     0xa0 = 0x02,
                     0xc0 = 0x03]

// call keccak256(offset, size)
// this will hash empty memory since now FMPA points to unused memory
KECCAK256(0xa0, 0x00)

To resolve the second issue:

• the first manual assembly block needs to save the starting memory address for where the input variables are stored

• before the external function call the FMPA needs to be updated to an unused address (our first fix)

• the final assembly block needs to use the saved starting memory address to calculate the offset and size parameters passed to keccak256

The full fixed source code contains @audit tags to indicate all changes made:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.25;

import {Test} from "forge-std/Test.sol";

// separate contracts accessed via interfaces
// prevents the optimizer from being "too smart", helping
// to better approximate real-world execution
interface IInfoRetriever {
    function getVal() external returns(uint256);
}

// this contract gets used to return additional
// values required by the primary computation
contract InfoRetriever is IInfoRetriever {
    uint256 returnVal = 3;

    function setVal(uint256 newVal) public {
        returnVal = newVal;
    }

    function getVal() external view returns(uint256) {
       return returnVal;
    }
}

interface IHasher {
    function hashInputs(uint256 a, uint256 b, uint256 additionalInputCount) external returns(bytes32 result);
}

// actual implementation that computes a hash of
// two primary inputs and an optional number of
// secondary inputs
contract HasherImpl is IHasher {

    // used to retrieve optional number of secondary inputs
    IInfoRetriever infoRetriever;

    constructor(IInfoRetriever _infoRetriever) {
        infoRetriever = _infoRetriever;
    }

    function _getSecondaryInputs(uint256 dataPtr, uint256 inputsToFetch) private returns(uint256) {
        for(uint256 i; i<inputsToFetch; i++) {

            // @audit once this external call completes it will:
            // - read the free memory pointer to find next free memory address
            //   which will be 0x80 as we never updated it since we are manually
            //   allocating memory
            // - write the result of the external call to this memory address
            // - but this is where the input variable `a` was saved!
            // - hence `a` gets subtly over-written by the return
            //   value of this external call which results in the hash calculation
            //   becoming corrupted!
            //
            // make external call to retrieve the data
            uint256 input = infoRetriever.getVal();

            assembly {
                // for each additional input, store it into memory
                // at next free memory address
                mstore(dataPtr, input)

                // update pointer to subsequent next free memory address
                dataPtr := add(dataPtr, 0x20)
            }
        }

        // returns updated dataPtr
        return dataPtr;
    }

    function hashInputs(uint256 a, uint256 b, uint256 additionalInputCount) external returns(bytes32 result) {
        uint256 dataPtr;

        // @audit used to hash correct memory addresses at the end
        uint256 startDataPtr;

        assembly {
            // read free memory pointer to find next free memory address
            dataPtr := mload(0x40)

            // @audit save starting address where we save our variables
            // as 0x40 gets overwritten later 
            startDataPtr := dataPtr

            // store `a` in memory at next free memory address
            mstore(dataPtr, a)

            // update pointer to subsequent next free memory address
            dataPtr := add(dataPtr, 0x20)

            // store `b` in memory at next free memory address
            mstore(dataPtr, b)

            // update pointer to subsequent next free memory address
            dataPtr := add(dataPtr, 0x20)

            // @audit this prevents the external call in `_getSecondaryInputs` from
            // over-writing value of `a` stored at 0x80
            //
            // update free memory pointer to point to next free memory address
            mstore(0x40, dataPtr)
        }

        // get the additional input from the info retriever, passing the updated
        // `dataPtr` so any new elements will be saved in subsequent free memory
        // addresses
        dataPtr = _getSecondaryInputs(dataPtr, additionalInputCount);

        // compute hash of all inputs
        assembly {
            // @audit using saved starting memory address
            result := keccak256(startDataPtr, sub(dataPtr, startDataPtr))
        }
    }
}

// test harness
contract HasherTest is Test {

    IInfoRetriever infoRetriever = new InfoRetriever();
    IHasher hasher = new HasherImpl(infoRetriever);
    uint256 a = 1;
    uint256 b = 2;

    function test_HashWithoutAdditionalInput() external {
        // works great
        bytes32 result = hasher.hashInputs(a, b, 0);

        assertEq(result, keccak256(abi.encode(1, 2)));
    }

    function test_HashWithAdditionalInput() external {
        // now also works
        bytes32 result = hasher.hashInputs(a, b, 1);

        assertEq(result, keccak256(abi.encode(1, 2, 3)));

        // also works for more than 1 secondary input
        result = hasher.hashInputs(a, b, 3);

        assertEq(result, keccak256(abi.encode(1, 2, 3, 3, 3)));
    }
}

Verify that both tests pass using forge test --match-contract HasherTest .

Memory Corruption Due To Insufficient Allocation

Another subtle memory corruption issue that can occur is due to insufficient allocation, a subsequent memory variable can become corrupted when the variable before it in memory is updated. This is likely to occur if there is an asymmetry between functions which allocate capacity and functions which write. Consider this real-world insufficient allocation memory corruption from Ethereum Name Service (ENS) smart contract audit which I've simplified into the following stand-alone Foundry test harness:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.25;

import {Test} from "forge-std/Test.sol";

// finding   : https://solodit.xyz/issues/memory-corruption-in-buffer-fixed-consensys-ens-permanent-registrar-markdown
// code from : https://github.com/ensdomains/buffer/blob/c06d796e2f6086473d229a96c2eb75053a19b8ec/contracts/Buffer.sol
library Buffer {

    struct buffer {
        bytes buf;
        uint capacity;
    }

    function init(buffer memory buf, uint capacity) internal pure returns(buffer memory) {
        if (capacity % 32 != 0) {
            capacity += 32 - (capacity % 32);
        }
        // Allocate space for the buffer data
        buf.capacity = capacity;
        assembly {
            let ptr := mload(0x40)
            mstore(buf, ptr)
            mstore(ptr, 0)

            // @audit does not account for length 0x20 (32),
            // even though the `write` function does
            mstore(0x40, add(ptr, capacity))
            // @audit fix:
            //mstore(0x40, add(32, add(ptr, capacity)))
        }
        return buf;
    }

    function append(buffer memory buf, bytes memory data) internal pure returns (buffer memory) {
        return write(buf, buf.buf.length, bytes32(data), data.length);
    }

    function write(buffer memory buf, uint off, bytes32 data, uint len) private pure returns(buffer memory) {
        if (len + off > buf.capacity) {
            resize(buf, max(buf.capacity, len) * 2);
        }

        uint mask = 256 ** len - 1;
        // Right-align data
        data = data >> (8 * (32 - len));
        assembly {
            // Memory address of the buffer data
            let bufptr := mload(buf)
            // Address = buffer address + sizeof(buffer length) + off + len
            let dest := add(add(bufptr, off), len)
            mstore(dest, or(and(mload(dest), not(mask)), data))
            // Update buffer length if we extended it
            if gt(add(off, len), mload(bufptr)) {
                mstore(bufptr, add(off, len))
            }
        }
        return buf;
    }

    function resize(buffer memory buf, uint capacity) private pure {
        bytes memory oldbuf = buf.buf;
        init(buf, capacity);
        append(buf, oldbuf);
    }

    function max(uint a, uint b) private pure returns(uint) {
        if (a > b) {
            return a;
        }
        return b;
    }

}

// test harness
contract BufferTest is Test {
    using Buffer for Buffer.buffer;

    function test_MemoryCorruption() external {
        Buffer.buffer memory buffer;
        buffer.init(1);

        // `foo` immediately follows buffer.buf in memory
        bytes memory foo = new bytes(0x01);

        // sanity check passes
        assert(1 == foo.length);

        // append "A" 0x41 (65) to buffer. This gets written to
        // the high order byte of `foo.length`!
        buffer.append("A");

        // foo.length == 0x4100000000000000000000000000000000000000000000000000000000000001
        //            == 29400335157912315244266070412362164103369332044010299463143527189509193072641
        // this passes showing the memory corruption
        assertEq(29400335157912315244266070412362164103369332044010299463143527189509193072641, 
                 foo.length);
    }
}

Run the test in Foundry's debugger using forge test --match-contract BufferTest --debug test_MemoryCorruption and let's examine how this memory corruption happens:

// PC 0x9b6 (2486) executing this line in `Buffer::init`:
// mstore(0x40, add(ptr, capacity))
// updates the Free Memory Pointer Address (FMPA) to 0x120
MSTORE(0x40, 0x120)
Memory: [0x40 = 0x120, // FMPA updated
         0x80 = 0x100,
         0xa0 = 0x20,
         0xc0 = 0x60]

// PC 0x697 (1687) executing this line in `BufferTest::test_Mem...`
// bytes memory foo = new bytes(0x01);
// writes `foo.length` to 0x120
MSTORE(0x120, 0x01)
Memory: [0x40 = 0x120,
         0x80 = 0x100,
         0xa0 = 0x20,
         0xc0 = 0x60,
         0x120 = 0x01] // foo.length

// PC 0xbad (2989) executing this line in `Buffer::write`
// mstore(dest, or(and(mload(dest), not(mask)), data))
// over-writes high-order byte of `foo.length`
MSTORE(0x101, 0x41)
Memory: [0x40 = 0x120,
         0x80 = 0x100,
         0xa0 = 0x20,
         0xc0 = 0x60,
         0x120 = 0x4100..01] // foo.length memory corrupted

Applying the suggested fix results in foo.length being written to 0x140 which prevents the memory corruption. Similar findings: [1, 2]

External Call To Non-Existent Contract

When using low-level call, a call to an address without code deployed is always successful. Consider the following code based upon this real-world mainnet finding:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.25;

import {Test} from "forge-std/Test.sol";

// external smart contract wallet which verifies a wallet's signature
// for a given hash
interface IWallet {
    function isValidSignature(bytes32 _hash, bytes calldata signature) external returns (bool);
}

// separate contracts accessed via interfaces
// prevents the optimizer from being "too smart", helping
// to better approximate real-world execution
interface IWalletVerifier {
    function isValidWalletSignature(bytes32 _hash, address walletAddress, bytes memory signature)
        external view returns(bool);
}

// implements vulnerable function used to make external call
contract WalletVerifier is IWalletVerifier {
    function isValidWalletSignature(bytes32 _hash, address walletAddress, bytes calldata signature)
        external view returns (bool isValid) {

        bytes memory callInput = abi.encodeWithSelector(
            IWallet(walletAddress).isValidSignature.selector,
            _hash,
            signature
        );

        assembly {
            let cdStart := add(callInput, 32)
            let success := staticcall(
                gas(),            // forward all gas
                walletAddress,    // address of Wallet contract
                cdStart,          // pointer to start of input
                mload(callInput), // length of input
                cdStart,          // write output over input
                32                // output size is 32 bytes
            )

            switch success
            case 0 {
                // Revert with `Error("WALLET_ERROR")`
                /* snip */
                revert(0, 100)
            }
            case 1 {
                // Signature is valid if call did not revert and returned true
                isValid := mload(cdStart)
            }
        }
        return isValid;
    }
}

// test harness
contract CallTest is Test {
    IWalletVerifier verifier = new WalletVerifier();

    function test_EOAAddressCallVerifiesInvalidSig() external view {
        bytes32 emptyHash;
        bytes memory emptySignature;

        bool returnVal = verifier.isValidWalletSignature(emptyHash, address(0x1234), emptySignature);

        assert(returnVal);
    }
}

The function WalletVerifier::isValidWalletSignature verifies a signature by calling an external wallet smart contract. But if this function is called passing the address of an Externally Owned Account (EOA - an ordinary user wallet) then it will always return true as:

• the staticcall to walletAddress will always return 1 for EOA addresses

• the staticcall specifies the output from the external call should be written over the input memory

• in this case there is no external output hence the inputs will not be overwritten

• hence the mload will return valid data which will be converted into true resulting in the return variable isValid being set to true

This would allow an invalid signature to be verified for EOA accounts. To resolve this vulnerability when using low-level calls:

1. before making the external call, the size of the contract should be checked to ensure it has code:

if iszero(extcodesize(walletAddress)) {
    // Revert with `Error("WALLET_ERROR")`
    revert(0, 100)
}

2. if the external call was successful, the length of the returned data should be verified to match the expected length:

if iszero(eq(returndatasize(), 32)) {
    // Revert with `Error("WALLET_ERROR")`
    revert(0, 100)
}

Overflow / Underflow During Inline Assembly

Using inline assembly for opcodes such as add and mult does not offer any overflow/underflow protection which normal Solidity provides. Consider the following simplified stand-alone example based on this unique audit contest finding:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.25;

import {Test} from "forge-std/Test.sol";

// separate contracts accessed via interfaces
// prevents the optimizer from being "too smart", helping
// to better approximate real-world execution
interface IDexPair {
    function getSwapQuote(uint256 amountToSwap) external view returns(uint256);
}

// represents a decentralized exchange pair between
// two assets
contract DexPair is IDexPair {
    // given an amount of input tokens
    // always return +1 output tokens
    function getSwapQuote(uint256 amountToSwap) external view returns(uint256 outputTokens) {
        assembly {
            outputTokens := add(amountToSwap, 1)
        }
    }
}

// test harness
contract OverflowTest is Test {
    IDexPair dexPair = new DexPair();

    function test_SwapQuoteOverflow() external {
        // correct: swapping 1 token returns 2 tokens
        assertEq(2, dexPair.getSwapQuote(1));

        // incorrect: swapping max returns 0 due to overflow
        assertEq(0, dexPair.getSwapQuote(type(uint256).max));
    }
}

In order to safeguard against overflow when using add inline assembly one option is to manually check that the result is not smaller than the input:

function getSwapQuote(uint256 amountToSwap) external view returns(uint256 outputTokens) {
    assembly {
        outputTokens := add(amountToSwap, 1)

        // detect overflow if outputTokens < amountToSwap
        if lt(outputTokens, amountToSwap) { revert(0, 0) }
    }
}

Appropriate overflow/underflow checks also need to be implemented for multiplication and subtraction when using inline assembly.

Uint128 Overflow Evades Detection As In-Line Assembly Uses 256 Bits

Another similar yet more subtle overflow vulnerability can exist when instead of using uint256 the previous example solidity code uses uint128 or smaller - the recommended overflow check mitigation fails to capture this overflow! Consider the following simplified stand-alone example based upon this actual audit finding:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.25;

import {Test} from "forge-std/Test.sol";

// separate contracts accessed via interfaces
// prevents the optimizer from being "too smart", helping
// to better approximate real-world execution
interface IDexPair {
    function getSwapQuoteUint128(uint128 amountToSwap) external view returns(uint128 outputTokens);
}

// represents a decentralized exchange pair between
// two assets
contract DexPair is IDexPair {
    // given an amount of input tokens always return +1 output tokens
    // capping max input to uint128 and using explicit code to
    // detect overflow 
    function getSwapQuoteUint128(uint128 amountToSwap) external view returns(uint128 outputTokens) {
        assembly {
            outputTokens := add(amountToSwap, 1)

            // detect overflow if outputTokens < amountToSwap
            if lt(outputTokens, amountToSwap) { revert(0, 0) }
        }
    }
}

// test harness
contract OverflowTest is Test {
    IDexPair dexPair = new DexPair();

    function test_SwapQuoteUint128Overflow() external {
        // correct: swapping 1 token returns 2 tokens
        assertEq(2, dexPair.getSwapQuoteUint128(1));

        // incorrect: swapping max uint128 returns 0 due to overflow
        // assembly overflow check fails to capture this!
        assertEq(0, dexPair.getSwapQuoteUint128(type(uint128).max));
    }
}

Even though DexPair::getSwapQuoteUint128 restricts both its input and output parameters to uint128 , the in-line assembly always operates on 256 bit values. Hence:

• the add opcode always returns a 256 bit value

• even if type(uint128).max is passed as input for amountToSwap, inside the in-line assembly block the value of outputTokens will be represented in 256 bits and therefore greater than the input amountToSwap

• therefore the overflow detection using the lt opcode will fail to detect the overflow, but the overflow still occurs after the in-line assembly block causing the function to return an incorrect value

One option when working with numbers smaller than uint256 is to use addmod to prevent the use of the full 256 bits:

function getSwapQuoteUint128(uint128 amountToSwap) external view returns(uint128 outputTokens) {
    assembly {
        // use addmod(a,b,N) with N = type(uint128).max
        // to prevent use of full 256 bits
        outputTokens := addmod(amountToSwap, 1, 340282366920938463463374607431768211455)

        // detect overflow if outputTokens < amountToSwap
        if lt(outputTokens, amountToSwap) { revert(0, 0) }
    }
}

Another option to detect these more subtle overflows is to include a check using normal Solidity after the in-line assembly block:

function getSwapQuoteUint128(uint128 amountToSwap) external view returns(uint128 outputTokens) {
    assembly {
        outputTokens := add(amountToSwap, 1)
    }

    // detect overflow outside in-line assembly to
    // prevent uint128 overflow not being detected due to
    // in-line assembly working with 256 bit values
    require(outputTokens >= amountToSwap, "Overflow detected!");
}

Additional Resources

• Low level vulnerabilities

function getKeccak256(uint256 a, uint256 b, uint256 c) external pure returns(bytes32 result) {
    result = keccak256(abi.encode(a,b,c));
}

However it is possible to reduce the gas cost of computing the hash by ~42% using the following assembly:

function getKeccak256(uint256 a, uint256 b, uint256 c) external pure returns(bytes32 result) {
    assembly {
        let mPtr := mload(0x40)
        mstore(mPtr, a)
        mstore(add(mPtr, 0x20), b)
        mstore(add(mPtr, 0x40), c)

        result := keccak256(mPtr, 0x60)
    }
}

Let's examine how and why this gas saving occurs!

Prerequisite Knowledge

In order to understand the next section you'll need to have completed at least Section 1 of Updraft's Assembly & Formal Verification course or already have equivalent knowledge of:

• EVM Opcodes

• EVM Stack Machine

• Solidity's Free Memory Pointer

• Foundry's Debugger

Foundry Testing Code

To examine the execution of both functions we'll use the following stand-alone Foundry test contract:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.25;

import "forge-std/Test.sol";

// separate contracts for each implementation then accessing
// implementations via an interface in the test contract
// prevents the optimizer from being "too smart", helping
// to better approximate real-world execution
interface IGasImpl {
    function getKeccak256(uint256 a, uint256 b, uint256 c) external pure returns(bytes32 result);
}

contract GasImplNormal is IGasImpl {
    function getKeccak256(uint256 a, uint256 b, uint256 c) external pure returns(bytes32 result) {
        result = keccak256(abi.encode(a,b,c));
    }
}

contract GasImplAssembly is IGasImpl {
    function getKeccak256(uint256 a, uint256 b, uint256 c) external pure returns(bytes32 result) {
        assembly {
            let mPtr := mload(0x40)
            mstore(mPtr, a)
            mstore(add(mPtr, 0x20), b)
            mstore(add(mPtr, 0x40), c)

            result := keccak256(mPtr, 0x60)
        }
    }
}

// actual testing contract
contract GasDebugTest is Test {
    IGasImpl gasImplNormal   = new GasImplNormal();
    IGasImpl gasImplAssembly = new GasImplAssembly();
    uint256 a = 1;
    uint256 b = 2;
    uint256 c = 3;

    // forge test --match-contract GasDebugTest --debug test_GasImplNormal
    function test_GasImplNormal() external {
        bytes32 result = gasImplNormal.getKeccak256(a,b,c);
        assertEq(result, 0x6e0c627900b24bd432fe7b1f713f1b0744091a646a9fe4a65a18dfed21f2949c);
    }

    // forge test --match-contract GasDebugTest --debug test_GasImplAssembly
    function test_GasImplAssembly() external {
        bytes32 result = gasImplAssembly.getKeccak256(a,b,c);
        assertEq(result, 0x6e0c627900b24bd432fe7b1f713f1b0744091a646a9fe4a65a18dfed21f2949c);
    }
}

Execution Trace - Assembly Version

Next we'll step through the assembly version using Foundry's debugger by executing this command: forge test --match-contract GasDebugTest --debug test_GasImplAssembly

We are concerned with the execution inside the GasImplAssembly contract:

• from the first PUSH1(0x40) after calldata has been loaded onto the stack and JUMPDEST has been called

• until keccak256 has been called and the calculated hash put on the stack

The above execution started at PC 0x39 (57) until 0x4f (79) and used 341-224 = 117 gas. Some useful acronyms are:

• Free Memory Pointer Address (FMPA)

• Starting Next Free Memory Address (SNFMA)

• Next Free Memory Address (NFMA)

Let's step through the execution examining how the assembly version works:

// push Free Memory Pointer Address (FMPA) onto stack
PUSH1(0x40) [Stack : 0x40, 0x03, 0x02, 0x01, 0x52, 0x05536b19]    
            [Memory: 0x40 = 0x80                             ]

// duplicate FMPA
DUP1        [Stack : 0x40, 0x40, 0x03, 0x02, 0x01, 0x52, 0x05536b19]
            [Memory: 0x40 = 0x80                                   ]

// load Starting Next Free Memory Address (SNFMA) by reading FMPA
MLOAD       [Stack : 0x80, 0x40, 0x03, 0x02, 0x01, 0x52, 0x05536b19]
            [Memory: 0x40 = 0x80                                   ]

// exchange 5th and 1st stack elements
// note: a common pattern follows to store input parameters in memory
SWAP4       [Stack : 0x01, 0x40, 0x03, 0x02, 0x80, 0x52, 0x05536b19]
            [Memory: 0x40 = 0x80                                   ]

// duplicate SNFMA
DUP5        [Stack : 0x80, 0x01, 0x40, 0x03, 0x02, 0x80, 0x52, 0x05536b19]
            [Memory: 0x40 = 0x80                                         ]

// store value of `a` into memory at SNFMA
MSTORE      [Stack : 0x40, 0x03, 0x02, 0x80, 0x52, 0x05536b19]
            [Memory: 0x40 = 0x80, 0x80 = 0x01                ]

// push 0x20 onto stack (2nd param of first `add` call)
// this is an offset to calculate Next Free Memory Address (NFMA)
PUSH1(0x20) [Stack : 0x20, 0x40, 0x03, 0x02, 0x80, 0x52, 0x05536b19]
            [Memory: 0x40 = 0x80, 0x80 = 0x01                      ]

// duplicate SNFMA
DUP5        [Stack : 0x80, 0x20, 0x40, 0x03, 0x02, 0x80, 0x52, 0x05536b19]
            [Memory: 0x40 = 0x80, 0x80 = 0x01                            ]

// calculate NFMA by SNFMA + offset (0x80 + 0x20)
ADD         [Stack : 0xa0, 0x40, 0x03, 0x02, 0x80, 0x52, 0x05536b19]
            [Memory: 0x40 = 0x80, 0x80 = 0x01                      ]

// exchange 4th and 1st stack elements
SWAP3       [Stack : 0x02, 0x40, 0x03, 0xa0, 0x80, 0x52, 0x05536b19]
            [Memory: 0x40 = 0x80, 0x80 = 0x01                      ]

// exchange 2nd and 1st stack elements
SWAP1       [Stack : 0x40, 0x02, 0x03, 0xa0, 0x80, 0x52, 0x05536b19]
            [Memory: 0x40 = 0x80, 0x80 = 0x01                      ]

// exchange 4th and 1st stack elements
SWAP3       [Stack : 0xa0, 0x02, 0x03, 0x40, 0x80, 0x52, 0x05536b19]
            [Memory: 0x40 = 0x80, 0x80 = 0x01                      ]

// store value of `b` into memory at NFMA
MSTORE      [Stack : 0x03, 0x40, 0x80, 0x52, 0x05536b19   ]
            [Memory: 0x40 = 0x80, 0x80 = 0x01, 0xa0 = 0x02]

// exchange 2nd and 1st stack elements
SWAP1       [Stack : 0x40, 0x03, 0x80, 0x52, 0x05536b19   ]
            [Memory: 0x40 = 0x80, 0x80 = 0x01, 0xa0 = 0x02]

// duplicate SNFMA
DUP3        [Stack : 0x80, 0x40, 0x03, 0x80, 0x52, 0x05536b19]
            [Memory: 0x40 = 0x80, 0x80 = 0x01, 0xa0 = 0x02   ]

// calculate NFMA by SNFMA + offset (0x80 + 0x40)
ADD         [Stack : 0xc0, 0x03, 0x80, 0x52, 0x05536b19   ]
            [Memory: 0x40 = 0x80, 0x80 = 0x01, 0xa0 = 0x02]

// store value of `c` into memory at NFMA
MSTORE      [Stack : 0x80, 0x52, 0x05536b19                            ]
            [Memory: 0x40 = 0x80, 0x80 = 0x01, 0xa0 = 0x02, 0xc0 = 0x03]

// note: all input parameters are now stored in memory

// push `size` parameter for call to keccak onto stack
PUSH1(0x60) [Stack : 0x60, 0x80, 0x52, 0x05536b19                      ]
            [Memory: 0x40 = 0x80, 0x80 = 0x01, 0xa0 = 0x02, 0xc0 = 0x03]

// exchange 2nd and 1st stack elements
SWAP1       [Stack : 0x80, 0x60, 0x52, 0x05536b19                      ]
            [Memory: 0x40 = 0x80, 0x80 = 0x01, 0xa0 = 0x02, 0xc0 = 0x03]

// call keccak256(offset, size)
KECCAK256   [Stack : result, 0x52, 0x05536b19                          ]
            [Memory: 0x40 = 0x80, 0x80 = 0x01, 0xa0 = 0x02, 0xc0 = 0x03]