@bananapus/core-v6 0.0.1

package/src/libraries/JBFees.sol

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.17;
+
+import {mulDiv} from "@prb/math/src/Common.sol";
+
+import {JBConstants} from "./../libraries/JBConstants.sol";
+
+/// @notice Fee calculations.
+library JBFees {
+    /// @notice Returns the fee amount that, when added to `amountAfterFee`, produces the gross amount needed to yield
+    /// `amountAfterFee` after the fee is deducted.
+    /// @dev Use this to back-calculate the fee from a desired post-fee payout.
+    /// @param amountAfterFee The desired post-fee amount, as a fixed point number.
+    /// @param feePercent The fee percent, out of `JBConstants.MAX_FEE`.
+    /// @return The fee amount, as a fixed point number with the same number of decimals as the provided `amount`.
+    function feeAmountResultingIn(uint256 amountAfterFee, uint256 feePercent) internal pure returns (uint256) {
+        return mulDiv(amountAfterFee, JBConstants.MAX_FEE, JBConstants.MAX_FEE - feePercent) - amountAfterFee;
+    }
+
+    /// @notice Returns the fee that would be taken from `amountBeforeFee`.
+    /// @dev Use this to forward-calculate the fee from a known pre-fee amount.
+    /// @param amountBeforeFee The amount before the fee is applied, as a fixed point number.
+    /// @param feePercent The fee percent, out of `JBConstants.MAX_FEE`.
+    /// @return The fee amount, as a fixed point number with the same number of decimals as the provided `amount`.
+    function feeAmountFrom(uint256 amountBeforeFee, uint256 feePercent) internal pure returns (uint256) {
+        return mulDiv(amountBeforeFee, feePercent, JBConstants.MAX_FEE);
+    }
+}

package/src/libraries/JBFixedPointNumber.sol

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.17;
+
+library JBFixedPointNumber {
+    function adjustDecimals(uint256 value, uint256 decimals, uint256 targetDecimals) internal pure returns (uint256) {
+        // If decimals need adjusting, multiply or divide the price by the decimal adjuster to get the normalized
+        // result.
+        if (targetDecimals == decimals) return value;
+        else if (targetDecimals > decimals) return value * 10 ** (targetDecimals - decimals);
+        else return value / 10 ** (decimals - targetDecimals);
+    }
+}

package/src/libraries/JBMetadataResolver.sol

@@ -0,0 +1,306 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.17;
+
+/**
+ * @notice Library to parse and create metadata to store {id: data} entries.
+ *
+ * @dev    Metadata are built as:
+ *         - 32B of reserved space for the protocol
+ *         - a lookup table `Id: offset`, defining the offset of the data for a given 4 bytes id.
+ *           The offset fits 1 bytes, the ID 4 bytes. This table is padded to 32B.
+ *         - the data for each id, padded to 32B each
+ *
+ *            +-----------------------+ offset: 0
+ *            | 32B reserved          |
+ *            +-----------------------+ offset: 1 = end of first 32B
+ *            |      (ID1,offset1)    |
+ *            |      (ID2,offset2)    |
+ *            |       0's padding     |
+ *            +-----------------------+ offset: offset1 = 1 + number of words taken by the padded table
+ *            |       id1 data1       |
+ *            | 0's padding           |
+ *            +-----------------------+ offset: offset2 = offset1 + number of words taken by the data1
+ *            |       id2 data2       |
+ *            | 0's padding           |
+ *            +-----------------------+
+ */
+library JBMetadataResolver {
+    error JBMetadataResolver_DataNotPadded();
+    error JBMetadataResolver_LengthMismatch();
+    error JBMetadataResolver_MetadataTooLong();
+    error JBMetadataResolver_MetadataTooShort();
+
+    // The various sizes used in bytes.
+    uint256 constant ID_SIZE = 4;
+    uint256 constant ID_OFFSET_SIZE = 1;
+    uint256 constant WORD_SIZE = 32;
+
+    // The size that an ID takes in the lookup table (Identifier + Offset).
+    uint256 constant TOTAL_ID_SIZE = 5; // ID_SIZE + ID_OFFSET_SIZE;
+
+    // The amount of bytes to go forward to get to the offset of the next ID (aka. the end of the offset of the current
+    // ID).
+    uint256 constant NEXT_ID_OFFSET = 9; // TOTAL_ID_SIZE + ID_SIZE;
+
+    // 1 word (32B) is reserved for the protocol .
+    uint256 constant RESERVED_SIZE = 32; // 1 * WORD_SIZE;
+    uint256 constant MIN_METADATA_LENGTH = 37; // RESERVED_SIZE + ID_SIZE + ID_OFFSET_SIZE;
+
+    /// @notice Add an {id: data} entry to an existing metadata. This is an append-only mechanism.
+    /// @param originalMetadata The original metadata
+    /// @param idToAdd The id to add
+    /// @param dataToAdd The data to add
+    /// @return newMetadata The new metadata with the entry added
+    function addToMetadata(
+        bytes memory originalMetadata,
+        bytes4 idToAdd,
+        bytes memory dataToAdd
+    )
+        internal
+        pure
+        returns (bytes memory newMetadata)
+    {
+        // Empty original metadata and maybe something in the first 32 bytes: create new metadata
+        if (originalMetadata.length <= RESERVED_SIZE) {
+            return abi.encodePacked(bytes32(originalMetadata), bytes32(abi.encodePacked(idToAdd, uint8(2))), dataToAdd);
+        }
+
+        // There is something in the table offset, but not a valid entry - avoid overwriting
+        if (originalMetadata.length < RESERVED_SIZE + ID_SIZE + 1) revert JBMetadataResolver_MetadataTooShort();
+
+        // Make sure the data is padded to 32 bytes.
+        if (dataToAdd.length < 32) revert JBMetadataResolver_DataNotPadded();
+
+        // Get the first data offset - upcast to avoid overflow (same for other offset)...
+        uint256 firstOffset = uint8(originalMetadata[RESERVED_SIZE + ID_SIZE]);
+
+        // ...go back to the beginning of the previous word (ie the last word of the table, as it can be padded)
+        uint256 lastWordOfTable = firstOffset - 1;
+
+        // The last offset stored in the table and its index
+        uint256 lastOffset;
+
+        // The number of words taken by the last data stored
+        uint256 numberOfWordslastData;
+
+        // Iterate to find the last entry of the table, lastOffset - we start from the end as the first value
+        // encountered
+        // will be the last offset
+        for (uint256 i = firstOffset * WORD_SIZE - 1; i > lastWordOfTable * WORD_SIZE - 1; i--) {
+            // If the byte is not 0, this is the last offset we're looking for
+            if (originalMetadata[i] != 0) {
+                lastOffset = uint8(originalMetadata[i]);
+                uint256 lastOffsetIndex = i;
+
+                // No rounding as this should be padded to 32B
+                numberOfWordslastData = (originalMetadata.length - lastOffset * WORD_SIZE) / WORD_SIZE;
+
+                // Copy the reserved word and the table and remove the previous padding
+                newMetadata = _sliceBytes(originalMetadata, 0, lastOffsetIndex + 1);
+
+                // Check if the new entry is still fitting in this word
+                if (i + TOTAL_ID_SIZE >= firstOffset * WORD_SIZE) {
+                    // Increment every offset by 1 (as the table now takes one more word)
+                    for (uint256 j = RESERVED_SIZE + ID_SIZE; j < lastOffsetIndex + 1; j += TOTAL_ID_SIZE) {
+                        newMetadata[j] = bytes1(uint8(originalMetadata[j]) + 1);
+                    }
+
+                    // Increment the last offset so the new offset will be properly set too
+                    lastOffset++;
+                }
+
+                break;
+            }
+        }
+
+        // Add the new entry after the last entry of the table, the new offset is the last offset + the number of words
+        // taken by the last data
+        // M-21: Compute in uint256 first — casting directly to uint8 silently wraps offsets > 255.
+        uint256 newOffset = lastOffset + numberOfWordslastData;
+        if (newOffset > 255) revert JBMetadataResolver_MetadataTooLong();
+        newMetadata = abi.encodePacked(newMetadata, idToAdd, bytes1(uint8(newOffset)));
+
+        // Pad as needed - inlined for gas saving
+        uint256 paddedLength =
+            newMetadata.length % WORD_SIZE == 0 ? newMetadata.length : (newMetadata.length / WORD_SIZE + 1) * WORD_SIZE;
+        assembly {
+            mstore(newMetadata, paddedLength)
+        }
+
+        // Add existing data at the end
+        newMetadata = abi.encodePacked(
+            newMetadata, _sliceBytes(originalMetadata, firstOffset * WORD_SIZE, originalMetadata.length)
+        );
+
+        // Pad as needed
+        paddedLength =
+            newMetadata.length % WORD_SIZE == 0 ? newMetadata.length : (newMetadata.length / WORD_SIZE + 1) * WORD_SIZE;
+        assembly {
+            mstore(newMetadata, paddedLength)
+        }
+
+        // Append new data at the end
+        newMetadata = abi.encodePacked(newMetadata, dataToAdd);
+
+        // Pad again again as needed
+        paddedLength =
+            newMetadata.length % WORD_SIZE == 0 ? newMetadata.length : (newMetadata.length / WORD_SIZE + 1) * WORD_SIZE;
+
+        assembly {
+            mstore(newMetadata, paddedLength)
+        }
+    }
+
+    /// @notice Create the metadata for a list of {id:data}
+    /// @dev Intended for offchain use (gas heavy)
+    /// @param ids The list of ids
+    /// @param datas The list of corresponding datas
+    /// @return metadata The resulting metadata
+    function createMetadata(bytes4[] memory ids, bytes[] memory datas) internal pure returns (bytes memory metadata) {
+        if (ids.length != datas.length) revert JBMetadataResolver_LengthMismatch();
+
+        // Add a first empty 32B for the protocol reserved word
+        metadata = abi.encodePacked(bytes32(0));
+
+        // First offset for the data is after the first reserved word...
+        uint256 offset = 1;
+
+        // ... and after the id/offset lookup table, rounding up to 32 bytes words if not a multiple
+        offset += ((ids.length * JBMetadataResolver.TOTAL_ID_SIZE) - 1) / JBMetadataResolver.WORD_SIZE + 1;
+
+        // Keep a reference to the number of ids.
+        uint256 numberOfIds = ids.length;
+
+        // For each id, add it to the lookup table with the next free offset, then increment the offset by the data
+        // length (rounded up)
+        for (uint256 i; i < numberOfIds; ++i) {
+            // Set the data being iterated on.
+            bytes memory data = datas[i];
+
+            if (data.length < 32 || data.length % JBMetadataResolver.WORD_SIZE != 0) {
+                revert JBMetadataResolver_DataNotPadded();
+            }
+
+            metadata = abi.encodePacked(metadata, ids[i], bytes1(uint8(offset)));
+            offset += data.length / JBMetadataResolver.WORD_SIZE;
+
+            // Overflowing a bytes1?
+            if (offset > 255) revert JBMetadataResolver_MetadataTooLong();
+        }
+
+        // Pad the table to a multiple of 32B
+        uint256 paddedLength = metadata.length % JBMetadataResolver.WORD_SIZE == 0
+            ? metadata.length
+            : (metadata.length / JBMetadataResolver.WORD_SIZE + 1) * JBMetadataResolver.WORD_SIZE;
+        assembly {
+            mstore(metadata, paddedLength)
+        }
+
+        // Keep a reference to the number of datas.
+        uint256 numberOfDatas = datas.length;
+
+        // Add each metadata to the array, each padded to 32 bytes
+        for (uint256 i; i < numberOfDatas; i++) {
+            metadata = abi.encodePacked(metadata, datas[i]);
+            paddedLength = metadata.length % JBMetadataResolver.WORD_SIZE == 0
+                ? metadata.length
+                : (metadata.length / JBMetadataResolver.WORD_SIZE + 1) * JBMetadataResolver.WORD_SIZE;
+
+            assembly {
+                mstore(metadata, paddedLength)
+            }
+        }
+    }
+
+    /// @notice Parse the metadata to find the data for a specific ID
+    /// @dev Returns false and an empty bytes if no data is found
+    /// @param id The ID to find.
+    /// @param metadata The metadata to parse.
+    /// @return found Whether the {id:data} was found
+    /// @return targetData The data for the ID (can be empty)
+    function getDataFor(bytes4 id, bytes memory metadata) internal pure returns (bool found, bytes memory targetData) {
+        // Either no data or empty one with only one selector (32+4+1)
+        if (metadata.length <= MIN_METADATA_LENGTH) return (false, "");
+
+        // Get the first data offset - upcast to avoid overflow (same for other offset)
+        uint256 firstOffset = uint8(metadata[RESERVED_SIZE + ID_SIZE]);
+
+        // Parse the id's to find id, stop when next offset == 0 or current = first offset
+        for (uint256 i = RESERVED_SIZE; metadata[i + ID_SIZE] != bytes1(0) && i < firstOffset * WORD_SIZE;) {
+            // Set the current offset.
+            uint256 currentOffset = uint256(uint8(metadata[i + ID_SIZE]));
+
+            bytes4 parsedId;
+            assembly {
+                parsedId := mload(add(add(metadata, 0x20), i))
+            }
+
+            // _id found?
+            if (parsedId == id) {
+                // Are we at the end of the lookup table (either at the start of data's or next offset is 0/in the
+                // padding)
+                // If not, only return until from this offset to the begining of the next offset
+                uint256 end = (i + NEXT_ID_OFFSET >= firstOffset * WORD_SIZE || metadata[i + NEXT_ID_OFFSET] == 0)
+                    ? metadata.length
+                    : uint256(uint8(metadata[i + NEXT_ID_OFFSET])) * WORD_SIZE;
+
+                return (true, _sliceBytes(metadata, currentOffset * WORD_SIZE, end));
+            }
+            unchecked {
+                i += TOTAL_ID_SIZE;
+            }
+        }
+    }
+
+    /// @notice Returns an unique id following a suggested format (`xor(address(this), purpose name)` where purpose name
+    /// is a string giving context to the id (Permit2, quoteForSwap, etc)
+    /// @param purpose A string describing the purpose associated with the id
+    /// @return id The resulting ID.
+    function getId(string memory purpose) internal view returns (bytes4) {
+        return getId(purpose, address(this));
+    }
+
+    /// @notice Returns an unique id following a suggested format (`xor(address(this), purpose name)` where purpose name
+    /// is a string giving context to the id (Permit2, quoteForSwap, etc)
+    /// @param purpose A string describing the purpose associated with the id
+    /// @param target The target which will use the metadata
+    /// @return id The resulting ID.
+    function getId(string memory purpose, address target) internal pure returns (bytes4) {
+        return bytes4(bytes20(target) ^ bytes20(keccak256(bytes(purpose))));
+    }
+
+    /// @notice Slice bytes from a start index to an end index.
+    /// @param data The bytes array to slice
+    /// @param start The start index to slice at.
+    /// @param end The end index to slice at.
+    /// @param slicedBytes The sliced array.
+    function _sliceBytes(bytes memory data, uint256 start, uint256 end)
+        private
+        pure
+        returns (bytes memory slicedBytes)
+    {
+        assembly {
+            let length := sub(end, start)
+
+            // M-20: Allocate memory at freemem — round up to 32-byte boundary so subsequent
+            // allocations do not overlap the tail of this buffer.
+            slicedBytes := mload(0x40)
+            mstore(0x40, and(add(add(add(slicedBytes, length), 0x20), 0x1f), not(0x1f)))
+
+            // Store the length (first element)
+            mstore(slicedBytes, length)
+
+            // compute the actual data first offset only once
+            let startBytes := add(add(data, 0x20), start)
+
+            // same for the out array
+            let sliceBytesStartOfData := add(slicedBytes, 0x20)
+
+            // M-20: Copy data — bound is `length` not `end`. Using `end` (an absolute source offset)
+            // would over-copy by `start` bytes past the allocated buffer.
+            for { let i := 0 } lt(i, length) { i := add(i, 0x20) } {
+                mstore(add(sliceBytesStartOfData, i), mload(add(startBytes, i)))
+            }
+        }
+    }
+}

package/src/libraries/JBRulesetMetadataResolver.sol

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.17;
+
+import {JBRuleset} from "./../structs/JBRuleset.sol";
+import {JBRulesetMetadata} from "./../structs/JBRulesetMetadata.sol";
+
+library JBRulesetMetadataResolver {
+    function reservedPercent(JBRuleset memory ruleset) internal pure returns (uint16) {
+        return uint16(ruleset.metadata >> 4);
+    }
+
+    function cashOutTaxRate(JBRuleset memory ruleset) internal pure returns (uint16) {
+        // Cash out tax rate is a number 0-10000.
+        return uint16(ruleset.metadata >> 20);
+    }
+
+    function baseCurrency(JBRuleset memory ruleset) internal pure returns (uint32) {
+        // Currency is a number 0-4294967295.
+        return uint32(ruleset.metadata >> 36);
+    }
+
+    function pausePay(JBRuleset memory ruleset) internal pure returns (bool) {
+        return ((ruleset.metadata >> 68) & 1) == 1;
+    }
+
+    function pauseCreditTransfers(JBRuleset memory ruleset) internal pure returns (bool) {
+        return ((ruleset.metadata >> 69) & 1) == 1;
+    }
+
+    function allowOwnerMinting(JBRuleset memory ruleset) internal pure returns (bool) {
+        return ((ruleset.metadata >> 70) & 1) == 1;
+    }
+
+    function allowSetCustomToken(JBRuleset memory ruleset) internal pure returns (bool) {
+        return ((ruleset.metadata >> 71) & 1) == 1;
+    }
+
+    function allowTerminalMigration(JBRuleset memory ruleset) internal pure returns (bool) {
+        return ((ruleset.metadata >> 72) & 1) == 1;
+    }
+
+    function allowSetTerminals(JBRuleset memory ruleset) internal pure returns (bool) {
+        return ((ruleset.metadata >> 73) & 1) == 1;
+    }
+
+    function allowSetController(JBRuleset memory ruleset) internal pure returns (bool) {
+        return ((ruleset.metadata >> 74) & 1) == 1;
+    }
+
+    function allowAddAccountingContext(JBRuleset memory ruleset) internal pure returns (bool) {
+        return ((ruleset.metadata >> 75) & 1) == 1;
+    }
+
+    function allowAddPriceFeed(JBRuleset memory ruleset) internal pure returns (bool) {
+        return ((ruleset.metadata >> 76) & 1) == 1;
+    }
+
+    function ownerMustSendPayouts(JBRuleset memory ruleset) internal pure returns (bool) {
+        return ((ruleset.metadata >> 77) & 1) == 1;
+    }
+
+    function holdFees(JBRuleset memory ruleset) internal pure returns (bool) {
+        return ((ruleset.metadata >> 78) & 1) == 1;
+    }
+
+    function useTotalSurplusForCashOuts(JBRuleset memory ruleset) internal pure returns (bool) {
+        return ((ruleset.metadata >> 79) & 1) == 1;
+    }
+
+    function useDataHookForPay(JBRuleset memory ruleset) internal pure returns (bool) {
+        return (ruleset.metadata >> 80) & 1 == 1;
+    }
+
+    function useDataHookForCashOut(JBRuleset memory ruleset) internal pure returns (bool) {
+        return (ruleset.metadata >> 81) & 1 == 1;
+    }
+
+    function dataHook(JBRuleset memory ruleset) internal pure returns (address) {
+        return address(uint160(ruleset.metadata >> 82));
+    }
+
+    function metadata(JBRuleset memory ruleset) internal pure returns (uint16) {
+        return uint16(ruleset.metadata >> 242);
+    }
+
+    /// @notice Pack the funding cycle metadata.
+    /// @param rulesetMetadata The ruleset metadata to validate and pack.
+    /// @return packed The packed uint256 of all metadata params. The first 8 bits specify the version.
+    function packRulesetMetadata(JBRulesetMetadata memory rulesetMetadata) internal pure returns (uint256 packed) {
+        // version 1 in the bits 0-3 (4 bits).
+        packed = 1;
+        // reserved percent in bits 4-19 (16 bits).
+        packed |= uint256(rulesetMetadata.reservedPercent) << 4;
+        // cash out tax rate in bits 20-35 (16 bits).
+        // cash out tax rate is a number 0-10000.
+        packed |= uint256(rulesetMetadata.cashOutTaxRate) << 20;
+        // base currency in bits 36-67 (32 bits).
+        // base currency is a number 0-4294967295.
+        packed |= uint256(rulesetMetadata.baseCurrency) << 36;
+        // pause pay in bit 68.
+        if (rulesetMetadata.pausePay) packed |= 1 << 68;
+        // pause credit transfers in bit 69.
+        if (rulesetMetadata.pauseCreditTransfers) packed |= 1 << 69;
+        // allow discretionary minting in bit 70.
+        if (rulesetMetadata.allowOwnerMinting) packed |= 1 << 70;
+        // allow a custom token to be set in bit 71.
+        if (rulesetMetadata.allowSetCustomToken) packed |= 1 << 71;
+        // allow terminal migration in bit 72.
+        if (rulesetMetadata.allowTerminalMigration) packed |= 1 << 72;
+        // allow set terminals in bit 73.
+        if (rulesetMetadata.allowSetTerminals) packed |= 1 << 73;
+        // allow set controller in bit 74.
+        if (rulesetMetadata.allowSetController) packed |= 1 << 74;
+        // allow add accounting context in bit 75.
+        if (rulesetMetadata.allowAddAccountingContext) packed |= 1 << 75;
+        // allow add price feed in bit 76.
+        if (rulesetMetadata.allowAddPriceFeed) packed |= 1 << 76;
+        // owner must send payouts in bit 77.
+        if (rulesetMetadata.ownerMustSendPayouts) packed |= 1 << 77;
+        // hold fees in bit 78.
+        if (rulesetMetadata.holdFees) packed |= 1 << 78;
+        // useTotalSurplusForCashOuts in bit 79.
+        if (rulesetMetadata.useTotalSurplusForCashOuts) packed |= 1 << 79;
+        // use pay data source in bit 80.
+        if (rulesetMetadata.useDataHookForPay) packed |= 1 << 80;
+        // use cash out data source in bit 81.
+        if (rulesetMetadata.useDataHookForCashOut) packed |= 1 << 81;
+        // data source address in bits 82-241.
+        packed |= uint256(uint160(address(rulesetMetadata.dataHook))) << 82;
+        // metadata in bits 242-255 (14 bits).
+        packed |= (uint256(rulesetMetadata.metadata) & 0x3FFF) << 242;
+    }
+
+    /// @notice Expand the funding cycle metadata.
+    /// @param ruleset The funding cycle having its metadata expanded.
+    /// @return rulesetMetadata The ruleset's metadata object.
+    function expandMetadata(JBRuleset memory ruleset) internal pure returns (JBRulesetMetadata memory) {
+        return JBRulesetMetadata(
+            reservedPercent(ruleset),
+            cashOutTaxRate(ruleset),
+            baseCurrency(ruleset),
+            pausePay(ruleset),
+            pauseCreditTransfers(ruleset),
+            allowOwnerMinting(ruleset),
+            allowSetCustomToken(ruleset),
+            allowTerminalMigration(ruleset),
+            allowSetTerminals(ruleset),
+            allowSetController(ruleset),
+            allowAddAccountingContext(ruleset),
+            allowAddPriceFeed(ruleset),
+            ownerMustSendPayouts(ruleset),
+            holdFees(ruleset),
+            useTotalSurplusForCashOuts(ruleset),
+            useDataHookForPay(ruleset),
+            useDataHookForCashOut(ruleset),
+            dataHook(ruleset),
+            metadata(ruleset)
+        );
+    }
+}

package/src/libraries/JBSplitGroupIds.sol

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+/// @notice Group IDs that categorize splits.
+library JBSplitGroupIds {
+    uint256 public constant RESERVED_TOKENS = 1;
+}

package/src/libraries/JBSurplus.sol

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.17;
+
+import {IJBTerminal} from "../interfaces/IJBTerminal.sol";
+import {JBAccountingContext} from "../structs/JBAccountingContext.sol";
+
+/// @notice Surplus calculations.
+library JBSurplus {
+    /// @notice Gets the total current surplus amount across all of a project's terminals.
+    /// @dev This amount changes as the value of the balances changes in relation to the currency being used to measure
+    /// the project's payout limits.
+    /// @param projectId The ID of the project to get the total surplus for.
+    /// @param terminals The terminals to look for surplus within.
+    /// @param accountingContexts The accounting contexts to use to calculate the surplus.
+    /// @param decimals The number of decimals that the fixed point surplus result should include.
+    /// @param currency The currency that the surplus result should be in terms of.
+    /// @return surplus The total surplus of a project's funds in terms of `currency`, as a fixed point number with the
+    /// specified number of decimals.
+    function currentSurplusOf(
+        uint256 projectId,
+        IJBTerminal[] memory terminals,
+        JBAccountingContext[] memory accountingContexts,
+        uint256 decimals,
+        uint256 currency
+    )
+        internal
+        view
+        returns (uint256 surplus)
+    {
+        // Keep a reference to the number of terminals.
+        uint256 numberOfTerminals = terminals.length;
+
+        // Add the current surplus for each terminal.
+        for (uint256 i; i < numberOfTerminals; i++) {
+            surplus += terminals[i].currentSurplusOf({
+                projectId: projectId, accountingContexts: accountingContexts, decimals: decimals, currency: currency
+            });
+        }
+    }
+}

package/src/periphery/JBDeadline1Day.sol

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.23;
+
+import {JBDeadline} from "../JBDeadline.sol";
+
+contract JBDeadline1Day is JBDeadline {
+    constructor() JBDeadline(1 days) {}
+}

package/src/periphery/JBDeadline3Days.sol

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.23;
+
+import {JBDeadline} from "../JBDeadline.sol";
+
+contract JBDeadline3Days is JBDeadline {
+    constructor() JBDeadline(3 days) {}
+}

package/src/periphery/JBDeadline3Hours.sol

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.23;
+
+import {JBDeadline} from "../JBDeadline.sol";
+
+contract JBDeadline3Hours is JBDeadline {
+    constructor() JBDeadline(3 hours) {}
+}

package/src/periphery/JBDeadline7Days.sol

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.23;
+
+import {JBDeadline} from "../JBDeadline.sol";
+
+contract JBDeadline7Days is JBDeadline {
+    constructor() JBDeadline(7 days) {}
+}

package/src/periphery/JBMatchingPriceFeed.sol

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.23;
+
+import {IJBPriceFeed} from "src/interfaces/IJBPriceFeed.sol";
+
+contract JBMatchingPriceFeed is IJBPriceFeed {
+    constructor() {}
+
+    /// @inheritdoc IJBPriceFeed
+    function currentUnitPrice(uint256 decimals) public view virtual override returns (uint256) {
+        return 10 ** decimals;
+    }
+}

package/src/structs/JBAccountingContext.sol

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+/// @custom:member token The address of the token that accounting is being done with.
+/// @custom:member decimals The number of decimals expected in that token's fixed point accounting.
+/// @custom:member currency The currency that the token is priced in terms of. By convention, this is
+/// `uint32(uint160(tokenAddress))` for tokens, or a constant ID from e.g. `JBCurrencyIds` for other currencies.
+struct JBAccountingContext {
+    address token;
+    uint8 decimals;
+    uint32 currency;
+}

package/src/structs/JBAfterCashOutRecordedContext.sol

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {JBTokenAmount} from "./JBTokenAmount.sol";
+
+/// @custom:member holder The holder of the tokens being cashed out.
+/// @custom:member projectId The ID of the project being cashed out from.
+/// @custom:member rulesetId The ID of the ruleset the cash out is being made during.
+/// @custom:member cashOutCount The number of project tokens being cashed out.
+/// @custom:member cashOutTaxRate The current ruleset's cash out tax rate.
+/// @custom:member reclaimedAmount The token amount being reclaimed from the project's terminal balance. Includes the
+/// token being
+/// reclaimed, the value, the number of decimals included, and the currency of the amount.
+/// @custom:member forwardedAmount The token amount being forwarded to the cash out hook. Includes the token
+/// being forwarded, the value, the number of decimals included, and the currency of the amount.
+/// @custom:member beneficiary The address the reclaimed amount will be sent to.
+/// @custom:member hookMetadata Extra data specified by the data hook, which is sent to the cash out hook.
+/// @custom:member cashOutMetadata Extra data specified by the account cashing out, which is sent to the cash out hook.
+struct JBAfterCashOutRecordedContext {
+    address holder;
+    uint256 projectId;
+    uint256 rulesetId;
+    uint256 cashOutCount;
+    JBTokenAmount reclaimedAmount;
+    JBTokenAmount forwardedAmount;
+    uint256 cashOutTaxRate;
+    address payable beneficiary;
+    bytes hookMetadata;
+    bytes cashOutMetadata;
+}