@bananapus/core-v6 0.0.1

package/test/formal/BondingCurveProperties.t.sol

@@ -0,0 +1,411 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.17;
+
+import "forge-std/Test.sol";
+import {mulDiv} from "@prb/math/src/Common.sol";
+import {JBCashOuts} from "../../src/libraries/JBCashOuts.sol";
+import {JBFees} from "../../src/libraries/JBFees.sol";
+import {JBConstants} from "../../src/libraries/JBConstants.sol";
+import {JBRulesetMetadataResolver} from "../../src/libraries/JBRulesetMetadataResolver.sol";
+import {JBRuleset} from "../../src/structs/JBRuleset.sol";
+import {JBRulesetMetadata} from "../../src/structs/JBRulesetMetadata.sol";
+
+/// @title BondingCurveProperties
+/// @notice Formal verification of bonding curve properties using symbolic execution.
+/// @dev Works with both Halmos (check_* pattern) and forge test (test_* pattern).
+///      Each property is dual-implemented: `check_` for Halmos and `testFuzz_` for forge.
+contract BondingCurveProperties is Test {
+    uint256 constant MAX_TAX = JBConstants.MAX_CASH_OUT_TAX_RATE; // 10_000
+    uint256 constant MAX_FEE = JBConstants.MAX_FEE; // 1_000
+
+    // =========================================================================
+    // Property 1: Boundedness — cashOutFrom never exceeds surplus
+    // =========================================================================
+    /// @notice cashOutFrom(S, c, T, r) <= S for all valid inputs.
+    function check_cashOut_boundedness(
+        uint256 surplus,
+        uint256 cashOutCount,
+        uint256 totalSupply,
+        uint256 cashOutTaxRate
+    )
+        public
+        pure
+    {
+        // Bound inputs to valid ranges
+        vm.assume(surplus > 0 && surplus <= type(uint128).max);
+        vm.assume(totalSupply > 0 && totalSupply <= type(uint128).max);
+        vm.assume(cashOutCount > 0 && cashOutCount <= totalSupply);
+        vm.assume(cashOutTaxRate <= MAX_TAX);
+
+        uint256 result = JBCashOuts.cashOutFrom(surplus, cashOutCount, totalSupply, cashOutTaxRate);
+        assert(result <= surplus);
+    }
+
+    function testFuzz_cashOut_boundedness(
+        uint128 surplus,
+        uint128 totalSupply,
+        uint128 cashOutCount,
+        uint16 cashOutTaxRate
+    )
+        public
+        pure
+    {
+        vm.assume(surplus > 0);
+        vm.assume(totalSupply > 0);
+        vm.assume(cashOutCount > 0 && cashOutCount <= totalSupply);
+        vm.assume(cashOutTaxRate <= MAX_TAX);
+
+        uint256 result = JBCashOuts.cashOutFrom(surplus, cashOutCount, totalSupply, cashOutTaxRate);
+        assertLe(result, surplus, "Boundedness: cashOutFrom should never exceed surplus");
+    }
+
+    // =========================================================================
+    // Property 2: Monotonicity — more tokens → more reclaim
+    // =========================================================================
+    /// @notice cashOutFrom(S, c1, T, r) <= cashOutFrom(S, c2, T, r) when c1 <= c2.
+    function check_cashOut_monotonicity(
+        uint256 surplus,
+        uint256 c1,
+        uint256 c2,
+        uint256 totalSupply,
+        uint256 cashOutTaxRate
+    )
+        public
+        pure
+    {
+        vm.assume(surplus > 0 && surplus <= type(uint128).max);
+        vm.assume(totalSupply > 0 && totalSupply <= type(uint128).max);
+        vm.assume(c1 > 0 && c2 > 0);
+        vm.assume(c1 <= c2);
+        vm.assume(c2 <= totalSupply);
+        vm.assume(cashOutTaxRate <= MAX_TAX);
+
+        uint256 result1 = JBCashOuts.cashOutFrom(surplus, c1, totalSupply, cashOutTaxRate);
+        uint256 result2 = JBCashOuts.cashOutFrom(surplus, c2, totalSupply, cashOutTaxRate);
+
+        assert(result1 <= result2);
+    }
+
+    function testFuzz_cashOut_monotonicity(
+        uint128 surplus,
+        uint128 totalSupply,
+        uint128 c1,
+        uint128 c2,
+        uint16 cashOutTaxRate
+    )
+        public
+        pure
+    {
+        vm.assume(surplus > 0);
+        vm.assume(totalSupply > 0);
+        vm.assume(c1 > 0 && c2 > 0);
+        if (c1 > c2) (c1, c2) = (c2, c1); // Ensure c1 <= c2
+        vm.assume(c2 <= totalSupply);
+        vm.assume(cashOutTaxRate <= MAX_TAX);
+
+        uint256 result1 = JBCashOuts.cashOutFrom(surplus, c1, totalSupply, cashOutTaxRate);
+        uint256 result2 = JBCashOuts.cashOutFrom(surplus, c2, totalSupply, cashOutTaxRate);
+
+        assertLe(result1, result2, "Monotonicity: more tokens should yield >= reclaim");
+    }
+
+    // =========================================================================
+    // Property 3: Full redemption — when c >= T, result is S (full surplus)
+    // =========================================================================
+    /// @notice When cashOutCount >= totalSupply, the full surplus is returned.
+    function check_cashOut_fullRedemption(uint256 surplus, uint256 totalSupply, uint256 cashOutTaxRate) public pure {
+        vm.assume(surplus > 0 && surplus <= type(uint128).max);
+        vm.assume(totalSupply > 0 && totalSupply <= type(uint128).max);
+        vm.assume(cashOutTaxRate <= MAX_TAX);
+        vm.assume(cashOutTaxRate < MAX_TAX); // Exclude max tax (which returns 0)
+
+        // When cashing out the entire supply
+        uint256 result = JBCashOuts.cashOutFrom(surplus, totalSupply, totalSupply, cashOutTaxRate);
+        assert(result == surplus);
+    }
+
+    function testFuzz_cashOut_fullRedemption(uint128 surplus, uint128 totalSupply, uint16 cashOutTaxRate) public pure {
+        vm.assume(surplus > 0);
+        vm.assume(totalSupply > 0);
+        vm.assume(cashOutTaxRate < MAX_TAX); // Exclude max tax
+
+        uint256 result = JBCashOuts.cashOutFrom(surplus, totalSupply, totalSupply, cashOutTaxRate);
+        assertEq(result, surplus, "Full redemption should return entire surplus");
+    }
+
+    // =========================================================================
+    // Property 4: Max tax → zero reclaim
+    // =========================================================================
+    /// @notice When cashOutTaxRate == MAX_CASH_OUT_TAX_RATE, result is 0.
+    function check_cashOut_maxTaxIsZero(uint256 surplus, uint256 cashOutCount, uint256 totalSupply) public pure {
+        vm.assume(surplus > 0 && surplus <= type(uint128).max);
+        vm.assume(totalSupply > 0 && totalSupply <= type(uint128).max);
+        vm.assume(cashOutCount > 0 && cashOutCount <= totalSupply);
+
+        uint256 result = JBCashOuts.cashOutFrom(surplus, cashOutCount, totalSupply, MAX_TAX);
+        assert(result == 0);
+    }
+
+    function testFuzz_cashOut_maxTaxIsZero(uint128 surplus, uint128 totalSupply, uint128 cashOutCount) public pure {
+        vm.assume(surplus > 0);
+        vm.assume(totalSupply > 0);
+        vm.assume(cashOutCount > 0 && cashOutCount <= totalSupply);
+
+        uint256 result = JBCashOuts.cashOutFrom(surplus, cashOutCount, totalSupply, MAX_TAX);
+        assertEq(result, 0, "Max tax rate should return 0");
+    }
+
+    // =========================================================================
+    // Property 5: No-arbitrage (subadditivity)
+    // =========================================================================
+    /// @notice Splitting a cash out into two parts should never yield more than a single cash out.
+    ///         cashOutFrom(S, a, T, r) + cashOutFrom(S', b, T', r) <= cashOutFrom(S, a+b, T, r)
+    ///         where S' = S - cashOutFrom(S, a, T, r) and T' = T - a
+    function check_cashOut_noArbitrage(
+        uint256 surplus,
+        uint256 a,
+        uint256 b,
+        uint256 totalSupply,
+        uint256 cashOutTaxRate
+    )
+        public
+        pure
+    {
+        vm.assume(surplus > 0 && surplus <= type(uint96).max);
+        vm.assume(totalSupply > 0 && totalSupply <= type(uint96).max);
+        vm.assume(a > 0 && b > 0);
+        vm.assume(a + b <= totalSupply);
+        vm.assume(cashOutTaxRate <= MAX_TAX);
+        vm.assume(cashOutTaxRate < MAX_TAX); // Exclude 100% tax (trivially 0)
+
+        // Single cash out of a+b
+        uint256 singleResult = JBCashOuts.cashOutFrom(surplus, a + b, totalSupply, cashOutTaxRate);
+
+        // First part: cash out a
+        uint256 firstResult = JBCashOuts.cashOutFrom(surplus, a, totalSupply, cashOutTaxRate);
+
+        // After first cash out: reduced surplus and supply
+        uint256 remainingSurplus = surplus - firstResult;
+        uint256 remainingSupply = totalSupply - a;
+
+        // Second part: cash out b from remaining state
+        uint256 secondResult = JBCashOuts.cashOutFrom(remainingSurplus, b, remainingSupply, cashOutTaxRate);
+
+        // NOTE: Strict subadditivity (firstResult + secondResult <= singleResult) was proven to be
+        // violated due to mulDiv rounding accumulation (FV-1 in AUDIT_FINDINGS.md).
+        // The violation is bounded by rounding precision and is economically insignificant (~0.00001%).
+        // We verify the weaker property: the excess is bounded by rounding tolerance.
+        if (firstResult + secondResult > singleResult) {
+            // The excess should be tiny relative to the result
+            uint256 excess = (firstResult + secondResult) - singleResult;
+            // Allow up to 1 basis point (0.01%) rounding tolerance
+            assert(excess * 10_000 <= singleResult);
+        }
+    }
+
+    function testFuzz_cashOut_noArbitrage(
+        uint96 surplus,
+        uint96 totalSupply,
+        uint96 a,
+        uint96 b,
+        uint16 cashOutTaxRate
+    )
+        public
+        pure
+    {
+        vm.assume(surplus > 0);
+        vm.assume(totalSupply > 0);
+        vm.assume(a > 0 && b > 0);
+        vm.assume(uint256(a) + uint256(b) <= totalSupply);
+        vm.assume(cashOutTaxRate <= MAX_TAX);
+        vm.assume(cashOutTaxRate < MAX_TAX);
+
+        uint256 singleResult = JBCashOuts.cashOutFrom(surplus, uint256(a) + b, totalSupply, cashOutTaxRate);
+        uint256 firstResult = JBCashOuts.cashOutFrom(surplus, a, totalSupply, cashOutTaxRate);
+
+        uint256 remainingSurplus = surplus - firstResult;
+        uint256 remainingSupply = totalSupply - a;
+
+        uint256 secondResult = JBCashOuts.cashOutFrom(remainingSurplus, b, remainingSupply, cashOutTaxRate);
+
+        // NOTE: Strict subadditivity violated due to mulDiv rounding (FV-1 in AUDIT_FINDINGS.md).
+        // Verify the weaker property: excess bounded by rounding tolerance (< 0.01%).
+        if (firstResult + secondResult > singleResult) {
+            uint256 excess = (firstResult + secondResult) - singleResult;
+            assertLe(excess * 10_000, singleResult, "No-arbitrage: rounding excess should be < 0.01%");
+        }
+    }
+
+    // =========================================================================
+    // Property 6: Fee round-trip — fee amounts are consistent
+    // =========================================================================
+    /// @notice The forward and reverse fee functions should be consistent:
+    ///         amount - feeAmountFrom(amount, fee) + feeAmountResultingIn(net, fee) >= feeAmountFrom(amount, fee)
+    ///         where net = amount - feeAmountFrom(amount, fee)
+    function check_fee_roundTrip(uint256 amount, uint256 feePercent) public pure {
+        vm.assume(amount > 0 && amount <= type(uint128).max);
+        vm.assume(feePercent > 0 && feePercent < MAX_FEE);
+
+        uint256 feeForward = JBFees.feeAmountFrom(amount, feePercent);
+        uint256 netAmount = amount - feeForward;
+
+        // Reverse fee: what fee would result in netAmount after deduction?
+        uint256 feeReverse = JBFees.feeAmountResultingIn(netAmount, feePercent);
+
+        // The reverse fee should be >= the forward fee (due to rounding direction)
+        // This ensures the protocol never undercharges
+        assert(feeReverse >= feeForward);
+    }
+
+    function testFuzz_fee_roundTrip(uint128 amount, uint16 feePercent) public pure {
+        vm.assume(amount > 0);
+        vm.assume(feePercent > 0 && feePercent < MAX_FEE);
+
+        uint256 feeForward = JBFees.feeAmountFrom(amount, feePercent);
+        uint256 netAmount = amount - feeForward;
+
+        uint256 feeReverse = JBFees.feeAmountResultingIn(netAmount, feePercent);
+
+        assertGe(feeReverse, feeForward, "Fee round-trip: reverse fee should be >= forward fee");
+    }
+
+    // =========================================================================
+    // Property 7: Metadata packing round-trip
+    // =========================================================================
+    /// @notice packRulesetMetadata(m) → expandMetadata should return the original metadata.
+    function check_metadataPacking_roundTrip(
+        uint16 reservedPercent,
+        uint16 cashOutTaxRate,
+        uint32 baseCurrency,
+        uint16 boolFlags, // Pack 14 bools into a uint16
+        address dataHook,
+        uint16 extraMetadata
+    )
+        public
+        pure
+    {
+        vm.assume(reservedPercent <= 10_000);
+        vm.assume(cashOutTaxRate <= 10_000);
+        vm.assume(extraMetadata <= 0x3FFF);
+
+        JBRulesetMetadata memory original = JBRulesetMetadata({
+            reservedPercent: reservedPercent,
+            cashOutTaxRate: cashOutTaxRate,
+            baseCurrency: baseCurrency,
+            pausePay: boolFlags & 1 != 0,
+            pauseCreditTransfers: boolFlags & 2 != 0,
+            allowOwnerMinting: boolFlags & 4 != 0,
+            allowSetCustomToken: boolFlags & 8 != 0,
+            allowTerminalMigration: boolFlags & 16 != 0,
+            allowSetTerminals: boolFlags & 32 != 0,
+            allowSetController: boolFlags & 64 != 0,
+            allowAddAccountingContext: boolFlags & 128 != 0,
+            allowAddPriceFeed: boolFlags & 256 != 0,
+            ownerMustSendPayouts: boolFlags & 512 != 0,
+            holdFees: boolFlags & 1024 != 0,
+            useTotalSurplusForCashOuts: boolFlags & 2048 != 0,
+            useDataHookForPay: boolFlags & 4096 != 0,
+            useDataHookForCashOut: boolFlags & 8192 != 0,
+            dataHook: dataHook,
+            metadata: extraMetadata
+        });
+
+        uint256 packed = JBRulesetMetadataResolver.packRulesetMetadata(original);
+
+        JBRuleset memory ruleset;
+        ruleset.metadata = packed;
+
+        JBRulesetMetadata memory roundTripped = JBRulesetMetadataResolver.expandMetadata(ruleset);
+
+        assert(roundTripped.reservedPercent == original.reservedPercent);
+        assert(roundTripped.cashOutTaxRate == original.cashOutTaxRate);
+        assert(roundTripped.baseCurrency == original.baseCurrency);
+        assert(roundTripped.pausePay == original.pausePay);
+        assert(roundTripped.pauseCreditTransfers == original.pauseCreditTransfers);
+        assert(roundTripped.allowOwnerMinting == original.allowOwnerMinting);
+        assert(roundTripped.allowSetCustomToken == original.allowSetCustomToken);
+        assert(roundTripped.allowTerminalMigration == original.allowTerminalMigration);
+        assert(roundTripped.allowSetTerminals == original.allowSetTerminals);
+        assert(roundTripped.allowSetController == original.allowSetController);
+        assert(roundTripped.allowAddAccountingContext == original.allowAddAccountingContext);
+        assert(roundTripped.allowAddPriceFeed == original.allowAddPriceFeed);
+        assert(roundTripped.ownerMustSendPayouts == original.ownerMustSendPayouts);
+        assert(roundTripped.holdFees == original.holdFees);
+        assert(roundTripped.useTotalSurplusForCashOuts == original.useTotalSurplusForCashOuts);
+        assert(roundTripped.useDataHookForPay == original.useDataHookForPay);
+        assert(roundTripped.useDataHookForCashOut == original.useDataHookForCashOut);
+        assert(roundTripped.dataHook == original.dataHook);
+        assert(roundTripped.metadata == original.metadata);
+    }
+
+    function testFuzz_metadataPacking_roundTrip(
+        uint16 reservedPercent,
+        uint16 cashOutTaxRate,
+        uint32 baseCurrency,
+        uint16 boolFlags, // Pack 14 bools into a uint16
+        address dataHook,
+        uint16 extraMetadata
+    )
+        public
+        pure
+    {
+        vm.assume(reservedPercent <= 10_000);
+        vm.assume(cashOutTaxRate <= 10_000);
+        vm.assume(extraMetadata <= 0x3FFF);
+
+        JBRulesetMetadata memory original = JBRulesetMetadata({
+            reservedPercent: reservedPercent,
+            cashOutTaxRate: cashOutTaxRate,
+            baseCurrency: baseCurrency,
+            pausePay: boolFlags & 1 != 0,
+            pauseCreditTransfers: boolFlags & 2 != 0,
+            allowOwnerMinting: boolFlags & 4 != 0,
+            allowSetCustomToken: boolFlags & 8 != 0,
+            allowTerminalMigration: boolFlags & 16 != 0,
+            allowSetTerminals: boolFlags & 32 != 0,
+            allowSetController: boolFlags & 64 != 0,
+            allowAddAccountingContext: boolFlags & 128 != 0,
+            allowAddPriceFeed: boolFlags & 256 != 0,
+            ownerMustSendPayouts: boolFlags & 512 != 0,
+            holdFees: boolFlags & 1024 != 0,
+            useTotalSurplusForCashOuts: boolFlags & 2048 != 0,
+            useDataHookForPay: boolFlags & 4096 != 0,
+            useDataHookForCashOut: boolFlags & 8192 != 0,
+            dataHook: dataHook,
+            metadata: extraMetadata
+        });
+
+        uint256 packed = JBRulesetMetadataResolver.packRulesetMetadata(original);
+
+        JBRuleset memory ruleset;
+        ruleset.metadata = packed;
+
+        JBRulesetMetadata memory result = JBRulesetMetadataResolver.expandMetadata(ruleset);
+
+        assertEq(result.reservedPercent, original.reservedPercent, "reservedPercent mismatch");
+        assertEq(result.cashOutTaxRate, original.cashOutTaxRate, "cashOutTaxRate mismatch");
+        assertEq(result.baseCurrency, original.baseCurrency, "baseCurrency mismatch");
+        assertEq(result.pausePay, original.pausePay, "pausePay mismatch");
+        assertEq(result.pauseCreditTransfers, original.pauseCreditTransfers, "pauseCreditTransfers mismatch");
+        assertEq(result.allowOwnerMinting, original.allowOwnerMinting, "allowOwnerMinting mismatch");
+        assertEq(result.allowSetCustomToken, original.allowSetCustomToken, "allowSetCustomToken mismatch");
+        assertEq(result.allowTerminalMigration, original.allowTerminalMigration, "allowTerminalMigration mismatch");
+        assertEq(result.allowSetTerminals, original.allowSetTerminals, "allowSetTerminals mismatch");
+        assertEq(result.allowSetController, original.allowSetController, "allowSetController mismatch");
+        assertEq(
+            result.allowAddAccountingContext, original.allowAddAccountingContext, "allowAddAccountingContext mismatch"
+        );
+        assertEq(result.allowAddPriceFeed, original.allowAddPriceFeed, "allowAddPriceFeed mismatch");
+        assertEq(result.ownerMustSendPayouts, original.ownerMustSendPayouts, "ownerMustSendPayouts mismatch");
+        assertEq(result.holdFees, original.holdFees, "holdFees mismatch");
+        assertEq(
+            result.useTotalSurplusForCashOuts,
+            original.useTotalSurplusForCashOuts,
+            "useTotalSurplusForCashOuts mismatch"
+        );
+        assertEq(result.useDataHookForPay, original.useDataHookForPay, "useDataHookForPay mismatch");
+        assertEq(result.useDataHookForCashOut, original.useDataHookForCashOut, "useDataHookForCashOut mismatch");
+        assertEq(result.dataHook, original.dataHook, "dataHook mismatch");
+        assertEq(result.metadata, original.metadata, "metadata mismatch");
+    }
+}

package/test/formal/FeeProperties.t.sol

@@ -0,0 +1,246 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.17;
+
+import "forge-std/Test.sol";
+import {JBFees} from "../../src/libraries/JBFees.sol";
+import {JBConstants} from "../../src/libraries/JBConstants.sol";
+
+/// @title FeeProperties
+/// @notice Formal verification of fee arithmetic properties using symbolic execution.
+/// @dev Works with both Halmos (check_* pattern) and forge test (testFuzz_* pattern).
+///      Each property is dual-implemented: `check_` for Halmos and `testFuzz_` for forge.
+contract FeeProperties is Test {
+    uint256 constant MAX_FEE = JBConstants.MAX_FEE; // 1_000
+
+    // =========================================================================
+    // Property 1: Fee additivity error bound
+    // =========================================================================
+    /// @notice feeAmountFrom(a+b, fee) vs feeAmountFrom(a, fee) + feeAmountFrom(b, fee)
+    ///         differ by at most 1 wei due to mulDiv rounding.
+    function check_fee_additivity(uint256 a, uint256 b, uint256 feePercent) public pure {
+        vm.assume(a > 0 && b > 0);
+        vm.assume(a <= type(uint128).max && b <= type(uint128).max);
+        vm.assume(a + b <= type(uint128).max); // No overflow
+        vm.assume(feePercent > 0 && feePercent < MAX_FEE);
+
+        uint256 feeCombined = JBFees.feeAmountFrom(a + b, feePercent);
+        uint256 feeSeparate = JBFees.feeAmountFrom(a, feePercent) + JBFees.feeAmountFrom(b, feePercent);
+
+        // The difference should be at most 1 wei
+        if (feeCombined >= feeSeparate) {
+            assert(feeCombined - feeSeparate <= 1);
+        } else {
+            assert(feeSeparate - feeCombined <= 1);
+        }
+    }
+
+    function testFuzz_fee_additivity(uint128 a, uint128 b, uint16 feePercent) public pure {
+        vm.assume(a > 0 && b > 0);
+        vm.assume(uint256(a) + uint256(b) <= type(uint128).max);
+        vm.assume(feePercent > 0 && feePercent < MAX_FEE);
+
+        uint256 feeCombined = JBFees.feeAmountFrom(uint256(a) + uint256(b), feePercent);
+        uint256 feeSeparate = JBFees.feeAmountFrom(a, feePercent) + JBFees.feeAmountFrom(b, feePercent);
+
+        uint256 diff = feeCombined >= feeSeparate ? feeCombined - feeSeparate : feeSeparate - feeCombined;
+
+        assertLe(diff, 1, "Additivity: fee(a+b) and fee(a)+fee(b) should differ by at most 1 wei");
+    }
+
+    // =========================================================================
+    // Property 2: Return fee consistency (protocol never undercharges)
+    // =========================================================================
+    /// @notice feeAmountResultingIn(netAmount, fee) >= feeAmountFrom(netAmount + feeAmountResultingIn(netAmount, fee),
+    // fee) /         The reverse fee is always >= the forward fee on the gross amount, ensuring
+    ///         the protocol never undercharges when returning held fees.
+    function check_fee_returnConsistency(uint256 netAmount, uint256 feePercent) public pure {
+        vm.assume(netAmount > 0 && netAmount <= type(uint128).max);
+        vm.assume(feePercent > 0 && feePercent < MAX_FEE);
+
+        uint256 reverseFee = JBFees.feeAmountResultingIn(netAmount, feePercent);
+        uint256 grossAmount = netAmount + reverseFee;
+        uint256 forwardFee = JBFees.feeAmountFrom(grossAmount, feePercent);
+
+        // The reverse fee should be >= the forward fee on the reconstructed gross
+        // This means the protocol never undercharges
+        assert(reverseFee >= forwardFee);
+    }
+
+    function testFuzz_fee_returnConsistency(uint128 netAmount, uint16 feePercent) public pure {
+        vm.assume(netAmount > 0);
+        vm.assume(feePercent > 0 && feePercent < MAX_FEE);
+
+        uint256 reverseFee = JBFees.feeAmountResultingIn(netAmount, feePercent);
+        uint256 grossAmount = uint256(netAmount) + reverseFee;
+        uint256 forwardFee = JBFees.feeAmountFrom(grossAmount, feePercent);
+
+        assertGe(
+            reverseFee,
+            forwardFee,
+            "Return consistency: reverse fee should be >= forward fee (protocol never undercharges)"
+        );
+    }
+
+    // =========================================================================
+    // Property 3: Fee-return round trip (reconstructed gross >= original, bounded overshoot)
+    // =========================================================================
+    /// @notice Take fee: fee1 = feeAmountFrom(amount, feePercent), net = amount - fee1.
+    ///         Return fee: fee2 = feeAmountResultingIn(net, feePercent).
+    ///         The reconstructed gross (net + fee2) should always be >= the original amount
+    ///         (protocol never undercharges on fee return).
+    ///         The overshoot is bounded by MAX_FEE / (MAX_FEE - feePercent): the rounding
+    ///         error in fee1 (at most 1 wei of net) gets amplified by the fee ratio when
+    ///         computing the reverse fee, plus 1 for the reverse mulDiv rounding itself.
+    function check_fee_roundTrip(uint256 amount, uint256 feePercent) public pure {
+        vm.assume(amount > 0 && amount <= type(uint128).max);
+        vm.assume(feePercent > 0 && feePercent < MAX_FEE);
+
+        uint256 fee1 = JBFees.feeAmountFrom(amount, feePercent);
+        uint256 net = amount - fee1;
+
+        uint256 fee2 = JBFees.feeAmountResultingIn(net, feePercent);
+
+        // Reconstructed gross should always be >= original (never undercharge)
+        assert(net + fee2 >= amount);
+
+        // Overshoot is bounded by the fee ratio amplification of rounding error.
+        // The forward mulDiv floors by at most 1, making net up to 1 too large.
+        // The reverse multiplies net by MAX_FEE/(MAX_FEE-fee), amplifying that error.
+        uint256 maxOvershoot = MAX_FEE / (MAX_FEE - feePercent) + 1;
+        assert(net + fee2 <= amount + maxOvershoot);
+    }
+
+    function testFuzz_fee_roundTrip(uint128 amount, uint16 feePercent) public pure {
+        vm.assume(amount > 0);
+        vm.assume(feePercent > 0 && feePercent < MAX_FEE);
+
+        uint256 fee1 = JBFees.feeAmountFrom(amount, feePercent);
+        uint256 net = uint256(amount) - fee1;
+
+        uint256 fee2 = JBFees.feeAmountResultingIn(net, feePercent);
+
+        assertGe(net + fee2, amount, "Round trip: reconstructed gross should be >= original (never undercharge)");
+
+        uint256 maxOvershoot = MAX_FEE / (MAX_FEE - uint256(feePercent)) + 1;
+        assertLe(
+            net + fee2,
+            uint256(amount) + maxOvershoot,
+            "Round trip: overshoot should be bounded by fee ratio amplification"
+        );
+    }
+
+    // =========================================================================
+    // Property 4: Partial return monotonicity
+    // =========================================================================
+    /// @notice feeAmountResultingIn(a, fee) <= feeAmountResultingIn(b, fee) when a <= b.
+    function check_fee_partialReturnMonotonicity(uint256 a, uint256 b, uint256 feePercent) public pure {
+        vm.assume(a > 0 && b > 0);
+        vm.assume(a <= type(uint128).max && b <= type(uint128).max);
+        vm.assume(a <= b);
+        vm.assume(feePercent > 0 && feePercent < MAX_FEE);
+
+        uint256 feeA = JBFees.feeAmountResultingIn(a, feePercent);
+        uint256 feeB = JBFees.feeAmountResultingIn(b, feePercent);
+
+        assert(feeA <= feeB);
+    }
+
+    function testFuzz_fee_partialReturnMonotonicity(uint128 a, uint128 b, uint16 feePercent) public pure {
+        vm.assume(a > 0 && b > 0);
+        if (a > b) (a, b) = (b, a); // Ensure a <= b
+        vm.assume(feePercent > 0 && feePercent < MAX_FEE);
+
+        uint256 feeA = JBFees.feeAmountResultingIn(a, feePercent);
+        uint256 feeB = JBFees.feeAmountResultingIn(b, feePercent);
+
+        assertLe(feeA, feeB, "Monotonicity: feeAmountResultingIn(a) <= feeAmountResultingIn(b) when a <= b");
+    }
+
+    // =========================================================================
+    // Property 5: Held fee subtraction safety (fee never exceeds amount)
+    // =========================================================================
+    /// @notice For any heldFeeAmount > 0 and valid feePercent:
+    ///         fee = feeAmountFrom(heldFeeAmount, feePercent) <= heldFeeAmount.
+    ///         This guarantees leftover = heldFeeAmount - fee never underflows, and
+    ///         leftover + fee == heldFeeAmount (exact decomposition).
+    function check_fee_subtractionSafety(uint256 heldFeeAmount, uint256 feePercent) public pure {
+        vm.assume(heldFeeAmount > 0 && heldFeeAmount <= type(uint128).max);
+        vm.assume(feePercent > 0 && feePercent < MAX_FEE);
+
+        uint256 fee = JBFees.feeAmountFrom(heldFeeAmount, feePercent);
+
+        // Fee must never exceed the held amount (no underflow on subtraction)
+        assert(fee <= heldFeeAmount);
+
+        // Exact decomposition: leftover + fee == heldFeeAmount
+        uint256 leftover = heldFeeAmount - fee;
+        assert(leftover + fee == heldFeeAmount);
+    }
+
+    function testFuzz_fee_subtractionSafety(uint128 heldFeeAmount, uint16 feePercent) public pure {
+        vm.assume(heldFeeAmount > 0);
+        vm.assume(feePercent > 0 && feePercent < MAX_FEE);
+
+        uint256 fee = JBFees.feeAmountFrom(heldFeeAmount, feePercent);
+
+        assertLe(fee, heldFeeAmount, "Subtraction safety: fee should never exceed held amount");
+
+        uint256 leftover = uint256(heldFeeAmount) - fee;
+        assertEq(leftover + fee, heldFeeAmount, "Subtraction safety: leftover + fee should exactly equal held amount");
+    }
+
+    // =========================================================================
+    // Property 6: Multi-split fee accumulation error bound
+    // =========================================================================
+    /// @notice After N splits each paying fee, total fee error vs single-payment fee
+    ///         is bounded by N wei. For N=10: sum(feeAmountFrom(amount/N, fee), N times)
+    ///         vs feeAmountFrom(amount, fee) differ by at most N.
+    function check_fee_multiSplitAccumulation(uint256 amount, uint256 feePercent) public pure {
+        vm.assume(amount >= 10); // Must be divisible into 10 parts
+        vm.assume(amount <= type(uint128).max);
+        vm.assume(feePercent > 0 && feePercent < MAX_FEE);
+
+        uint256 N = 10;
+        uint256 perSplit = amount / N;
+        uint256 remainder = amount - (perSplit * N);
+
+        // Single fee on total amount
+        uint256 singleFee = JBFees.feeAmountFrom(amount, feePercent);
+
+        // Sum of fees on each split
+        uint256 splitFeeSum = 0;
+        for (uint256 i = 0; i < N; i++) {
+            // Last split gets any remainder from integer division
+            uint256 splitAmount = (i == N - 1) ? perSplit + remainder : perSplit;
+            splitFeeSum += JBFees.feeAmountFrom(splitAmount, feePercent);
+        }
+
+        // Difference should be bounded by N
+        if (singleFee >= splitFeeSum) {
+            assert(singleFee - splitFeeSum <= N);
+        } else {
+            assert(splitFeeSum - singleFee <= N);
+        }
+    }
+
+    function testFuzz_fee_multiSplitAccumulation(uint128 amount, uint16 feePercent) public pure {
+        vm.assume(amount >= 10);
+        vm.assume(feePercent > 0 && feePercent < MAX_FEE);
+
+        uint256 N = 10;
+        uint256 perSplit = uint256(amount) / N;
+        uint256 remainder = uint256(amount) - (perSplit * N);
+
+        uint256 singleFee = JBFees.feeAmountFrom(amount, feePercent);
+
+        uint256 splitFeeSum = 0;
+        for (uint256 i = 0; i < N; i++) {
+            uint256 splitAmount = (i == N - 1) ? perSplit + remainder : perSplit;
+            splitFeeSum += JBFees.feeAmountFrom(splitAmount, feePercent);
+        }
+
+        uint256 diff = singleFee >= splitFeeSum ? singleFee - splitFeeSum : splitFeeSum - singleFee;
+
+        assertLe(diff, N, "Multi-split accumulation: total rounding error should be bounded by N wei");
+    }
+}