hex-audit 0.6.3 → 0.8.0

package/dist/skills/fuzz/scripts/setup_fuzz_profile.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+# setup_fuzz_profile.sh — Create a [profile.fuzz] in foundry.toml that disables
+# via_ir when possible, falling back to via_ir with optimizer_runs=0 when the
+# codebase requires IR (stack too deep).
+#
+# This exists because via_ir causes Medusa's branch-level coverage to be
+# deflated: the IR optimizer merges/eliminates branches, so reported coverage
+# is lower than actual source-level coverage.
+#
+# Usage: setup_fuzz_profile.sh <PROJECT_ROOT>
+#
+# Output (stdout, last line):
+#   FUZZ_PROFILE=no-ir        — compiled without via_ir, coverage is accurate
+#   FUZZ_PROFILE=ir-no-opt    — needs via_ir but optimizer_runs=0, ~10% deflation
+#   FUZZ_PROFILE=default      — both attempts failed, using default profile
+#
+# Exit codes:
+#   0 — fuzz profile created (or not needed)
+#   1 — could not create a working fuzz profile, fall back to default
+
+set -euo pipefail
+
+PROJECT_ROOT="${1:-.}"
+
+if [ ! -f "$PROJECT_ROOT/foundry.toml" ]; then
+    echo "ERROR: foundry.toml not found in $PROJECT_ROOT"
+    exit 1
+fi
+
+TOML="$PROJECT_ROOT/foundry.toml"
+
+# ――――――――――――――――――――――――― Check if via_ir is enabled ―――――――――――――――――――――――――
+
+# Match via_ir = true or via-ir = true (TOML allows both)
+if ! grep -qE '^\s*via[_-]ir\s*=\s*true' "$TOML"; then
+    echo "via_ir is not enabled — no fuzz profile needed."
+    echo "FUZZ_PROFILE=no-ir"
+    exit 0
+fi
+
+echo "via_ir = true detected in foundry.toml."
+
+# ――――――――――――――――――――――――― Check for existing fuzz profile ―――――――――――――――――――――――――
+
+if grep -qE '^\[profile\.fuzz\]' "$TOML"; then
+    echo "[profile.fuzz] already exists in foundry.toml — skipping creation."
+    # Try to determine what mode it's in
+    if grep -A5 '^\[profile\.fuzz\]' "$TOML" | grep -qE 'via[_-]ir\s*=\s*false'; then
+        echo "Existing fuzz profile has via_ir = false."
+        # Verify it compiles
+        if cd "$PROJECT_ROOT" && FOUNDRY_PROFILE=fuzz forge build 2>/dev/null; then
+            echo "FUZZ_PROFILE=no-ir"
+            exit 0
+        else
+            echo "Existing fuzz profile does not compile — will attempt to fix."
+        fi
+    else
+        echo "Existing fuzz profile does not disable via_ir."
+        echo "FUZZ_PROFILE=ir-no-opt"
+        exit 0
+    fi
+fi
+
+# ――――――――――――――――――――――――― Attempt 1: Disable via_ir ―――――――――――――――――――――――――
+
+echo ""
+echo "Attempt 1: Adding [profile.fuzz] with via_ir = false ..."
+
+# Remove any previous fuzz profile block we may have partially written
+# (defensive — only removes our marker-bounded block)
+sed -i.bak '/^# >>> fizz fuzz profile/,/^# <<< fizz fuzz profile/d' "$TOML"
+rm -f "$TOML.bak"
+
+cat >> "$TOML" <<'FUZZ_BLOCK'
+
+# >>> fizz fuzz profile
+[profile.fuzz]
+via_ir = false
+# <<< fizz fuzz profile
+FUZZ_BLOCK
+
+echo "Trying: FOUNDRY_PROFILE=fuzz forge build ..."
+cd "$PROJECT_ROOT"
+BUILD_OUTPUT=$(FOUNDRY_PROFILE=fuzz forge build 2>&1) && BUILD_EXIT=0 || BUILD_EXIT=$?
+
+if [ "$BUILD_EXIT" -eq 0 ]; then
+    echo "Compilation succeeded without via_ir."
+    echo "FUZZ_PROFILE=no-ir"
+    exit 0
+fi
+
+# Check if it's a stack-too-deep error
+if echo "$BUILD_OUTPUT" | grep -qi "stack too deep\|Stack too deep"; then
+    echo "Stack too deep — codebase requires via_ir."
+else
+    echo "Build failed (not stack-too-deep). Output:"
+    echo "$BUILD_OUTPUT" | tail -20
+    echo ""
+    echo "Attempting fallback anyway..."
+fi
+
+# ――――――――――――――――――――――――― Attempt 2: via_ir + optimizer_runs=0 ―――――――――――――――――――――――――
+
+echo ""
+echo "Attempt 2: [profile.fuzz] with via_ir = true, optimizer_runs = 0 ..."
+
+# Replace the fuzz profile block
+sed -i.bak '/^# >>> fizz fuzz profile/,/^# <<< fizz fuzz profile/d' "$TOML"
+rm -f "$TOML.bak"
+
+cat >> "$TOML" <<'FUZZ_BLOCK'
+
+# >>> fizz fuzz profile
+[profile.fuzz]
+via_ir = true
+optimizer = false
+optimizer_runs = 0
+# <<< fizz fuzz profile
+FUZZ_BLOCK
+
+echo "Trying: FOUNDRY_PROFILE=fuzz forge build ..."
+BUILD_OUTPUT=$(FOUNDRY_PROFILE=fuzz forge build 2>&1) && BUILD_EXIT=0 || BUILD_EXIT=$?
+
+if [ "$BUILD_EXIT" -eq 0 ]; then
+    echo "Compilation succeeded with via_ir + optimizer disabled."
+    echo "FUZZ_PROFILE=ir-no-opt"
+    exit 0
+fi
+
+# ――――――――――――――――――――――――― Both failed ―――――――――――――――――――――――――
+
+echo ""
+echo "Both attempts failed. Removing fuzz profile block."
+sed -i.bak '/^# >>> fizz fuzz profile/,/^# <<< fizz fuzz profile/d' "$TOML"
+rm -f "$TOML.bak"
+
+echo "Build output from last attempt:"
+echo "$BUILD_OUTPUT" | tail -20
+echo ""
+echo "Falling back to default profile. Coverage numbers will be deflated."
+echo "FUZZ_PROFILE=default"
+exit 1

package/dist/skills/fuzz/templates/Actor.sol

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.6.2 <0.9.0;
+
+contract ForceSendETH {
+    constructor(address dst) payable {
+        // Use assembly to stay compatible across Solidity versions where
+        // selfdestruct is deprecated or removed
+        assembly {
+            selfdestruct(dst)
+        }
+    }
+}
+
+/// @notice Represents an actor interacting with the system
+contract Actor {
+    constructor() payable {
+        
+    }
+
+    receive() external payable {}
+
+    function forceSendETH(address recipient, uint256 amount) public {
+        new ForceSendETH{value: amount}(recipient);
+    }
+
+    // ――――――――――――――――――― Flash loan borrower ――――――――――――――――――――
+
+    function onFlashLoan(address initiator, address token, uint256 amount, uint256 fee, bytes calldata data)
+        external
+        returns (bytes32)
+    {
+        // Implement here flash loan logic, if needed
+        return keccak256("ERC3156FlashBorrower.onFlashLoan");
+    }
+
+    // ――――――――――――――――――――― ERC-721 receiver ―――――――――――――――――――――
+
+    function onERC721Received(address operator, address from, uint256 tokenId, bytes calldata data)
+        external
+        returns (bytes4)
+    {
+        return this.onERC721Received.selector;
+    }
+
+    // ―――――――――――――――――――― ERC-1155 receiver ―――――――――――――――――――――
+
+    function onERC1155Received(address operator, address from, uint256 id, uint256 value, bytes calldata data)
+        external
+        returns (bytes4)
+    {
+        return this.onERC1155Received.selector;
+    }
+
+    function onERC1155BatchReceived(
+        address operator,
+        address from,
+        uint256[] calldata ids,
+        uint256[] calldata values,
+        bytes calldata data
+    ) external returns (bytes4) {
+        return this.onERC1155BatchReceived.selector;
+    }
+}

package/dist/skills/fuzz/templates/Base.sol

@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.6.2 <0.9.0;
+
+import {Actor} from "./Actor.sol";
+import {Clamp} from "./utils/Clamp.sol";
+import {DecimalPrinter} from "./utils/DecimalPrinter.sol";
+import {Deployer} from "./utils/Deployer.sol";
+import {vm} from "./utils/Hevm.sol";
+import {Logger} from "./utils/Logger.sol";
+import {Math} from "./utils/Math.sol";
+import {StringUtils} from "./utils/StringUtils.sol";
+import {EnumerableSet} from "./utils/EnumerableSet.sol";
+
+/// @notice Base contract with state variables and setup functions
+abstract contract Base is StringUtils, Clamp, Deployer, Math {
+    using DecimalPrinter for uint256;
+
+    string[] internal ACTOR_LABELS = ["Alice", "Bob", "Charlie"];
+    uint256 internal constant BLOCK_INTERVAL = 12 seconds;
+    uint256 internal constant INITIAL_ETH_BALANCE = 1_000 ether;
+    uint256 internal constant INITIAL_TOKEN_BALANCE = 10_000;
+
+    // ―――――――――――――――――――――――――― Ghosts ――――――――――――――――――――――――――
+
+    struct Ghosts {
+        uint256 _placeholder;
+    }
+
+    Ghosts internal ghosts;
+
+    // ―――――――――――――――――――――――――― Actors ――――――――――――――――――――――――――
+
+    address[] internal actors;
+    address internal actor;
+    address internal admin;
+
+    modifier asActor() virtual {
+        vm.startPrank(actor);
+        _;
+        vm.stopPrank();
+    }
+
+    modifier asAdmin() virtual {
+        vm.startPrank(admin);
+        _;
+        vm.stopPrank();
+    }
+
+    // ―――――――――――――――――――――――― Contracts ―――――――――――――――――――――――――
+
+    // FIXME: Contract instances go here, e.g.:
+    // Foo public foo;
+
+    // ―――――――――――――――――――――――――― Setup ―――――――――――――――――――――――――――
+
+    function setup() internal {
+        // FIXME: Add initial setup (e.g. deploy contracts, set initial state, etc.)
+
+        setupActors();
+    }
+
+    function setupActors() internal {
+        admin = address(this);
+        vm.label(admin, "Admin");
+
+		for (uint256 i; i < ACTOR_LABELS.length; i++) {
+			address _actor = address(new Actor{value: INITIAL_ETH_BALANCE}());
+            actors.push(_actor);
+            if (ACTOR_LABELS.length > i) {
+                vm.label(_actor, ACTOR_LABELS[i]);
+            }
+            // FIXME: Add any required actor setup (e.g. minting tokens, setting allowances, etc.)
+            //        If needed, Actor's constructor can also be used for this purpose
+		}
+        actor = actors[0];
+    }
+
+    // ――――――――――――――――――――――――― Helpers ――――――――――――――――――――――――――
+
+    // Maps an arbitrary address to an actor address
+    function toActor(address addy) internal view returns (address) {
+        return actors[uint256(uint160(addy)) % actors.length];
+    }
+
+    // Maps an arbitrary address to an actor address that is different from the current actor
+    function toActorNotCurrent(address addy) internal view returns (address) {
+        address _actor = actors[uint256(uint160(addy)) % actors.length];
+        if (_actor == actor) {
+            _actor = actors[(uint256(uint160(addy)) + 1) % actors.length];
+        }
+        return _actor;
+    }
+
+    // Sums the native token balances of all actors
+    function sumActorsBalances() internal view returns (uint256 sumOfBalances) {
+        for (uint256 i; i < actors.length; i++) {
+            sumOfBalances += actors[i].balance;
+        }
+    }
+
+    // Sums the ERC-20 token balances of all actors for a given token
+    function sumActorsERC20Balances(address _token) internal view returns (uint256 sumOfBalances) {
+        for (uint256 i; i < actors.length; i++) {
+            bytes memory data = abi.encodeWithSignature("balanceOf(address)", actors[i]);
+            (bool success, bytes memory result) = _token.staticcall(data);
+            require(success, "sumActorsERC20Balances: failed to get balance");
+            sumOfBalances += abi.decode(result, (uint256));
+        }
+    }
+
+    function skipBlocks(uint256 blocks) internal {
+        vm.roll(block.number + blocks);
+        vm.warp(block.timestamp + blocks * BLOCK_INTERVAL);
+    }
+
+    function skipTime(uint256 time) internal {
+        uint256 blocks = (time + BLOCK_INTERVAL - 1) / BLOCK_INTERVAL;
+        vm.roll(block.number + blocks);
+        vm.warp(block.timestamp + time);
+    }
+}

package/dist/skills/fuzz/templates/FoundryTester.sol

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.6.2 <0.9.0;
+
+import {Test} from "forge-std/Test.sol";
+import {console} from "forge-std/console.sol";
+import {Handlers} from "./handlers/Handlers.sol";
+
+/// @notice Contract to be used for quick testing with Foundry
+contract FoundryTester is Test, Handlers {
+    modifier asActor() override {
+        vm.startPrank(actor);
+        _;
+        vm.stopPrank();
+    }
+
+    function setUp() public {
+        setup();
+    }
+
+    // forge test --match-test test_sequence -vvv
+    function test_sequence() public {
+        // Add here call sequence to Handler's functions to reproduce failing property
+    }
+
+    // ── Violation Repros (auto-generated by Step 11) ──────────────────
+    // Each test_repro_* function below replays a shrunk fuzzer call
+    // sequence that violated a property. Run all with:
+    //   forge test --match-contract FoundryTester -vvv
+}

package/dist/skills/fuzz/templates/FuzzTester.sol

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.6.2 <0.9.0;
+
+import {Handlers} from "./handlers/Handlers.sol";
+
+/// @notice Entry point for fuzzing tests
+contract FuzzTester is Handlers {
+    constructor() payable {
+        setup();
+    }
+}

package/dist/skills/fuzz/templates/Properties.sol

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.6.2 <0.9.0;
+
+import {Snapshots} from "./Snapshots.sol";
+import {PropertiesAsserts} from "./utils/PropertiesAsserts.sol";
+
+/// @notice Contains the functions that check the properties (invariants)
+abstract contract Properties is PropertiesAsserts, Snapshots {
+
+    // ―――――――――――――――――――― Global properties ―――――――――――――――――――――
+    // These properties must always hold after any function call.
+    // They MUST BE PUBLIC so that fuzzers can find and call them.
+
+    // ――――――――――――――――――― Specific properties ――――――――――――――――――――
+    // These properties must hold after specific function calls.
+    // They MUST BE INTERNAL and called at the end of the relevant handlers.
+}

package/dist/skills/fuzz/templates/README.md

@@ -0,0 +1,56 @@
+# Fizz Suite
+
+## What Is Here
+
+- `Base.sol`: shared setup, deployed contract references, actors, helpers, and ghost state
+- `Snapshots.sol`: before/after state capture used by properties
+- `Properties.sol`: global and function-specific invariants
+- `handlers/`: protocol actions exposed to the fuzzers
+- `harness/`: (optional) harness contracts that inherit from target contracts to expose private/internal state needed by properties
+- `utils/`: shared helper libraries, assertions, clamping logic, math helpers, deploy helpers, logging, and mocks
+- `FuzzTester.sol`: main Echidna/Medusa fuzzing entry point
+- `FoundryTester.sol`: Foundry harness for quick debugging and local repros
+
+## Inheritance Chain
+
+```
+Base (is StringUtils, Clamp, Deployer, Math)
+        └─► Snapshots (is Base)
+              └─► Properties (is PropertiesAsserts, Snapshots)
+                    └─► <Contract>Handler (is Properties)   — one per target contract
+                          └─► Handlers (is <all handlers>)  — aggregator + actor switching
+                                ├─► FuzzTester (is Handlers)       — Echidna/Medusa entry point
+                                └─► FoundryTester (is Test, Handlers) — Foundry quick debug/PoC entry point
+```
+
+## Related Paths Outside This Directory
+
+- `../../fizz_data/`: extracted ABI inventory, entry-point selection, protocol-understanding notes, corpora, logs, and coverage outputs
+- `../../echidna.yaml`: Echidna config
+- `../../medusa.json`: Medusa config
+
+## How To Run
+
+From the project root:
+
+```bash
+forge build
+forge test --match-contract FoundryTester
+echidna . --contract FuzzTester --config echidna.yaml
+medusa fuzz --config medusa.json
+```
+
+## How To Read The Suite
+
+Recommended order:
+
+1. `README.md`
+2. `Base.sol`
+3. `handlers/Handlers.sol`
+4. individual handler files under `handlers/`
+5. `Snapshots.sol`
+6. `Properties.sol`
+7. `harness/` (if present) — to understand what private/internal state is exposed and why
+8. `utils/` when you need to understand helper behavior or mocks
+9. `FuzzTester.sol`
+10. `FoundryTester.sol`

package/dist/skills/fuzz/templates/Snapshots.sol

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.6.2 <0.9.0;
+
+import {Base} from "./Base.sol";
+
+/// @notice Used to take snapshots of the state before and after a function call
+abstract contract Snapshots is Base {
+    struct State {
+        uint256 _placeholder;
+    }
+
+    State internal stateBefore;
+    State internal stateAfter;
+
+    function _takeSnapshot(State storage state) private {
+        state._placeholder = actor.balance;
+    }
+    
+    function snapshotBefore() internal {
+        _takeSnapshot(stateBefore);
+    }
+
+    function snapshotAfter() internal {
+        _takeSnapshot(stateAfter);
+    }
+}

package/dist/skills/fuzz/templates/echidna.yaml

@@ -0,0 +1,18 @@
+testMode: "assertion"
+prefix: "property_"
+seqLen: 100
+testLimit: 50000
+balanceContract: 0xffffffffffffffffffffffffffffffffffffffffffffffff
+coverage: true
+corpusDir: "fizz_data/corpus_echidna"
+cryticArgs: ["--foundry-compile-all"]
+contractAddr: "0x7FA9385bE102ac3EAc297483Dd6233D62b3e1496"
+deployer: "0x1804c8AB1F12E6bbf3894d4083f33e07309d1f38"
+# output format (comment out for TUI)
+format: "text"
+# Hide solc stderr output and additional information during the testing.
+quiet: false
+stopOnFail: false
+disableSlither: false
+
+# https://secure-contracts.com/program-analysis/echidna/configuration.html

package/dist/skills/fuzz/templates/handlers/Handlers.sol

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.6.2 <0.9.0;
+
+import "../Base.sol";
+
+/// @notice Inherits from all the handlers to expose all entry points in a single contract.
+///         Manages environment changes (e.g. current actor, current token, mocks setup, etc.).
+abstract contract Handlers
+{
+	function setCurrentActor(uint256 entropy) public {
+        actor = actors[entropy % actors.length];
+    }
+}

package/dist/skills/fuzz/templates/medusa.json

@@ -0,0 +1,93 @@
+{
+	"fuzzing": {
+	   "workers": 10,
+	   "workerResetLimit": 50,
+	   "timeout": 0,
+	   "testLimit": 500000,
+	   "callSequenceLength": 100,
+	   "corpusDirectory": "fizz_data/corpus_medusa",
+	   "coverageEnabled": true,
+	   "deploymentOrder": [
+		  "FuzzTester"
+	   ],
+	   "targetContracts": [
+		  "FuzzTester"
+	   ],
+	   "targetContractsBalances": [
+		  "0xffffffffffffffffffffffffffffffffffffffffffffffff"
+	   ],
+	   "constructorArgs": {},
+	   "deployerAddress": "0x1804c8AB1F12E6bbf3894d4083f33e07309d1f38",
+	   "senderAddresses": [
+		  "0x10000",
+		  "0x20000",
+		  "0x30000"
+	   ],
+	   "blockNumberDelayMax": 60480,
+	   "blockTimestampDelayMax": 604800,
+	   "blockGasLimit": 125000000,
+	   "transactionGasLimit": 12500000,
+	   "testing": {
+		  "stopOnFailedTest": false,
+		  "stopOnFailedContractMatching": false,
+		  "stopOnNoTests": true,
+		  "testAllContracts": false,
+		  "traceAll": false,
+		  "assertionTesting": {
+			 "enabled": true,
+			 "testViewMethods": true,
+			 "panicCodeConfig": {
+				"failOnCompilerInsertedPanic": false,
+				"failOnAssertion": true,
+				"failOnArithmeticUnderflow": false,
+				"failOnDivideByZero": false,
+				"failOnEnumTypeConversionOutOfBounds": false,
+				"failOnIncorrectStorageAccess": false,
+				"failOnPopEmptyArray": false,
+				"failOnOutOfBoundsArrayAccess": false,
+				"failOnAllocateTooMuchMemory": false,
+				"failOnCallUninitializedVariable": false
+			 }
+		  },
+		  "propertyTesting": {
+			 "enabled": true,
+			 "testPrefixes": [
+				"property_"
+			 ]
+		  },
+		  "optimizationTesting": {
+			 "enabled": false,
+			 "testPrefixes": [
+				"optimize_"
+			 ]
+		  }
+	   },
+	   "chainConfig": {
+		  "codeSizeCheckDisabled": true,
+		  "cheatCodes": {
+			 "cheatCodesEnabled": true,
+			 "enableFFI": false
+		  }
+	   }
+	},
+	"compilation": {
+	   "platform": "crytic-compile",
+	   "platformConfig": {
+		  "target": ".",
+		  "solcVersion": "",
+		  "exportDirectory": "fizz_data/crytic-export",
+		  "args": [
+			 "--foundry-compile-all"
+		  ]
+	   }
+	},
+	"slither": {
+    	"enabled": true,
+     	"cachePath": "fizz_data/slither_results.json"
+  	},
+	"logging": {
+	   "level": "info",
+	   "logDirectory": "fizz_data/logs_medusa",
+	   "noColor": false
+	}
+ }