@bananapus/core-v6 0.0.17 → 0.0.18

package/CHANGE_LOG.md

@@ -10,6 +10,14 @@ This document describes all changes between `nana-core` (v5, Solidity 0.8.23) an
 
 `setSplitGroupsOf` self-auth now requires the upper 96 bits of the `groupId` to be non-zero. The full self-auth check is: `uint160(groupId) == msg.sender && groupId >> 160 != 0`. GroupIds with zero upper 96 bits (bare addresses like `uint256(uint160(tokenAddress))`) are protocol-reserved for terminal payout groups and always require controller authorization. This prevents accepted token contracts from writing a project's payout splits without controller auth. The 721 hook is unaffected since it already uses `hookAddress | tierId << 160` (non-zero upper bits).
 
+### 0.2 JBMultiTerminal -- Fee-Free Cashout Bypass Prevention
+
+A new `_feeFreeSurplusOf` mapping (`projectId => token => uint256`) tracks cumulative fee-free intra-terminal payouts received by each project. When a split payout lands on the same terminal (intra-terminal routing, i.e. `terminal == this`), the net payout amount is added to `_feeFreeSurplusOf[projectId][token]`. During a cashout with `cashOutTaxRate == 0`, fees are now charged on the reclaim amount up to the tracked fee-free surplus (and the tracker is decremented accordingly). Cashouts beyond the fee-free surplus remain fee-free. This closes a round-trip fee bypass where funds could be routed fee-free into a project via an intra-terminal split payout and then cashed out fee-free via a zero-tax cashout.
+
+### 0.3 JBBeforeCashOutRecordedContext -- beneficiaryIsFeeless Field
+
+A `bool beneficiaryIsFeeless` field was added to the `JBBeforeCashOutRecordedContext` struct (before the `metadata` field). `recordCashOutFor` in `IJBTerminalStore` gained a corresponding `bool beneficiaryIsFeeless` parameter. The terminal passes the result of its feeless address check, allowing data hooks to skip their own fees when the beneficiary is already feeless (e.g., project-to-project routing via the router terminal). This is a **breaking change** to both the struct layout and the `recordCashOutFor` function signature.
+
 ---
 
 ## 1. Breaking Changes
@@ -29,16 +37,19 @@ A `rulesetId` parameter was added. Callers must now specify which ruleset to cac
 | Change | v5 | v6 |
 |--------|----|----|
 | `currentReclaimableSurplusOf` parameter rename | `uint256 tokenCount` (4-param overload) | `uint256 cashOutCount` |
+| `recordCashOutFor` new parameter | No `beneficiaryIsFeeless` parameter | `bool beneficiaryIsFeeless` added after `balanceAccountingContexts` |
 
 The parameter was renamed from `tokenCount` to `cashOutCount` in the simple 4-parameter overload.
 
+`recordCashOutFor` gained a `bool beneficiaryIsFeeless` parameter so the terminal can pass through its feeless address check to data hooks via the `JBBeforeCashOutRecordedContext` struct.
+
 #### IJBPayoutTerminal
 
 | Change | v5 | v6 |
 |--------|----|----|
 | `sendPayoutsOf` return value | `returns (uint256 netLeftoverPayoutAmount)` | `returns (uint256 amountPaidOut)` |
 
-The return value semantics changed: v5 returned the net leftover payout amount (sent to the project owner), while v6 returns the total amount paid out.
+The return variable name was corrected from `netLeftoverPayoutAmount` to `amountPaidOut` to match the actual implementation semantics (total amount paid out). The v5 implementation already returned the total amount from `STORE.recordPayoutFor()`, not the leftover — only the interface had the misleading name.
 
 #### IJBController
 
@@ -141,8 +152,8 @@ See section 2.2 above.
 
 | Contract | Event | Change |
 |----------|-------|--------|
-| `IJBCashOutTerminal` | `CashOut` | Event order changed in the interface (moved before `HookAfterRecordCashOut`); NatSpec added. No field changes. |
-| `IJBCashOutTerminal` | `HookAfterRecordCashOut` | Event order changed in the interface (moved after `CashOut`); NatSpec added. No field changes. |
+| `IJBCashOutTerminal` | `CashOutTokens` | Event order changed in the interface (moved before `HookAfterRecordCashOut`); NatSpec added. No field changes. |
+| `IJBCashOutTerminal` | `HookAfterRecordCashOut` | Event order changed in the interface (moved after `CashOutTokens`); NatSpec added. No field changes. |
 
 ### 3.3 All Interfaces Gained NatSpec
 
@@ -189,7 +200,13 @@ See section 2.3 above.
 
 ## 5. Struct Changes
 
-All structs are **identical** between v5 and v6. The only differences are:
+All structs are identical between v5 and v6 except:
+
+| Struct | Change |
+|--------|--------|
+| `JBBeforeCashOutRecordedContext` | New `bool beneficiaryIsFeeless` field added before `metadata`. Indicates whether the cash out's beneficiary is a feeless address, allowing data hooks to skip their own fees for in-protocol routing. |
+
+Other struct-level differences (non-functional):
 - `forge-lint: disable-next-line(pascal-case-struct)` comments added to all struct definitions.
 - `JBSplit`: Additional NatSpec documentation on the `beneficiary` field behavior when set to `address(0)`.
 
@@ -269,6 +286,8 @@ No changes.
 | **Migration held fees** | Migration intentionally does not transfer held fees (documented: held fees belong to fee beneficiary, not the migrating project). |
 | **Held fee processing (reentrancy hardening)** | `processHeldFeesOf` now re-reads the storage index each iteration (instead of caching), deletes the entry before the external call, and updates the index before the external call. |
 | **Split payout documentation** | Failed split payouts documented as consuming payout limit by design. |
+| **Fee-free cashout bypass prevention** | New `_feeFreeSurplusOf` mapping tracks cumulative fee-free intra-terminal payouts per project/token. During zero-tax cashouts, fees are charged up to this tracked amount (then decremented), preventing round-trip fee bypass. See Section 0.2. |
+| **beneficiaryIsFeeless passthrough** | `cashOutTokensOf` now passes `_isFeeless(beneficiary)` to `recordCashOutFor`, which forwards it to data hooks via `JBBeforeCashOutRecordedContext.beneficiaryIsFeeless`. |
 
 ### 8.3 JBRulesets
 
@@ -285,36 +304,42 @@ No changes.
 |--------|-------------|
 | **Migration ordering** | `setControllerOf` now calls `migrate()` on the old controller BEFORE updating `controllerOf` in storage (so `migrate()` runs while the directory still points to the old controller). After updating storage, it calls `afterReceiveMigrationFrom` on the new controller. |
 
-### 8.5 JBTokens
+### 8.5 JBSplits
+
+| Change | Description |
+|--------|-------------|
+| **Stale storage cleanup** | `_setSplitsOf` now deletes stale packed split data when the new split count is smaller than the previous count, preventing leftover storage from prior configurations. |
+
+### 8.6 JBTokens
 
 | Change | Description |
 |--------|-------------|
 | **Overflow check timing** | `mintFor` now checks `totalSupplyOf(projectId) + count > type(uint208).max` BEFORE minting (v5 checked after). |
 
-### 8.6 JBERC20
+### 8.7 JBERC20
 
 | Change | Description |
 |--------|-------------|
 | **Named revert** | `initialize()` now reverts with `JBERC20_AlreadyInitialized()` instead of a bare `revert()`. |
 
-### 8.7 JBChainlinkV3PriceFeed
+### 8.8 JBChainlinkV3PriceFeed
 
 | Change | Description |
 |--------|-------------|
 | **Incomplete round check order** | The check for `updatedAt == 0` (incomplete round) now runs BEFORE the stale price check, avoiding false stale errors on incomplete rounds. |
 
-### 8.8 JBChainlinkV3SequencerPriceFeed
+### 8.9 JBChainlinkV3SequencerPriceFeed
 
 | Change | Description |
 |--------|-------------|
 | **Typo fix** | Error parameter `gradePeriodTime` corrected to `gracePeriodTime` in `JBChainlinkV3SequencerPriceFeed_SequencerDown`. |
 | **Threshold docs** | Constructor parameter `threshold` documentation corrected from "blocks" to "seconds". |
 
-### 8.9 Solidity Version
+### 8.10 Solidity Version
 
 All contracts upgraded from `pragma solidity 0.8.23` to `pragma solidity 0.8.26`.
 
-### 8.10 Named Arguments
+### 8.11 Named Arguments
 
 Throughout the codebase, function calls were updated to use named argument syntax (e.g., `foo({bar: 1, baz: 2})`) for improved readability.
 
@@ -328,7 +353,7 @@ Throughout the codebase, function calls were updated to use named argument synta
 |----|----|-------|
 | `IJBController` | `IJBController` | Gained `setTokenMetadataOf`. `calldata` for terminal configs. |
 | `IJBRulesets` | `IJBRulesets` | `updateRulesetWeightCache` gained `rulesetId` parameter |
-| `IJBTerminalStore` | `IJBTerminalStore` | `tokenCount` renamed to `cashOutCount` in `currentReclaimableSurplusOf`. View functions reordered. |
+| `IJBTerminalStore` | `IJBTerminalStore` | `tokenCount` renamed to `cashOutCount` in `currentReclaimableSurplusOf`. `recordCashOutFor` gained `beneficiaryIsFeeless` param. View functions reordered. |
 | `IJBPayoutTerminal` | `IJBPayoutTerminal` | `sendPayoutsOf` returns `amountPaidOut` (was `netLeftoverPayoutAmount`). `SendPayoutToSplit` event moved. |
 | `IJBPermitTerminal` | `IJBPermitTerminal` | Gained `Permit2AllowanceFailed` event |
 | `IJBMigratable` | `IJBMigratable` | Gained `afterReceiveMigrationFrom` function |
@@ -344,7 +369,7 @@ Throughout the codebase, function calls were updated to use named argument synta
 | v5 | v6 | Notes |
 |----|----|-------|
 | `JBController` | `JBController` | Token metadata, migration lifecycle (`afterReceiveMigrationFrom`), `LAUNCH_RULESETS` permission |
-| `JBMultiTerminal` | `JBMultiTerminal` | Reentrancy hardening, decimal validation rename, Permit2 event |
+| `JBMultiTerminal` | `JBMultiTerminal` | Reentrancy hardening, decimal validation rename, Permit2 event, fee-free bypass prevention (`_feeFreeSurplusOf`), `beneficiaryIsFeeless` passthrough |
 | `JBRulesets` | `JBRulesets` | Approval hook try/catch, weight cache changes, threshold increase |
 | `JBDirectory` | `JBDirectory` | Migration ordering fix, afterReceiveMigration call |
 | `JBTokens` | `JBTokens` | Token metadata support, overflow check timing |
@@ -366,7 +391,7 @@ Throughout the codebase, function calls were updated to use named argument synta
 
 | v5 | v6 | Notes |
 |----|----|-------|
-| All 22 structs | Same names, same fields | Only lint comments added |
+| All 22 structs | Same names | All identical except `JBBeforeCashOutRecordedContext` (gained `beneficiaryIsFeeless` field). Lint comments added to all. |
 
 ### Enums
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "license": "MIT",
   "repository": {
     "type": "git",

package/docs/book.css

@@ -1,13 +0,0 @@
-table {
-    margin: 0 auto;
-    border-collapse: collapse;
-    width: 100%;
-}
-
-table td:first-child {
-    width: 15%;
-}
-  
-table td:nth-child(2) {
-    width: 25%;
-}

package/docs/book.toml

@@ -1,12 +0,0 @@
-[book]
-src = "src"
-title = ""
-
-[output.html]
-no-section-label = true
-additional-js = ["solidity.min.js"]
-additional-css = ["book.css"]
-git-repository-url = "https://github.com/Bananapus/nana-core"
-
-[output.html.fold]
-enable = true

package/docs/solidity.min.js

@@ -1,74 +0,0 @@
-hljs.registerLanguage("solidity",(()=>{"use strict";function e(){try{return!0
-}catch(e){return!1}}
-var a=/-?(\b0[xX]([a-fA-F0-9]_?)*[a-fA-F0-9]|(\b[1-9](_?\d)*(\.((\d_?)*\d)?)?|\.\d(_?\d)*)([eE][-+]?\d(_?\d)*)?|\b0)(?!\w|\$)/
-;e()&&(a=a.source.replace(/\\b/g,"(?<!\\$)\\b"));var s={className:"number",
-begin:a,relevance:0},n={
-keyword:"assembly let function if switch case default for leave break continue u256 jump jumpi stop return revert selfdestruct invalid",
-built_in:"add sub mul div sdiv mod smod exp not lt gt slt sgt eq iszero and or xor byte shl shr sar addmod mulmod signextend keccak256 pc pop dup1 dup2 dup3 dup4 dup5 dup6 dup7 dup8 dup9 dup10 dup11 dup12 dup13 dup14 dup15 dup16 swap1 swap2 swap3 swap4 swap5 swap6 swap7 swap8 swap9 swap10 swap11 swap12 swap13 swap14 swap15 swap16 mload mstore mstore8 sload sstore msize gas address balance selfbalance caller callvalue calldataload calldatasize calldatacopy codesize codecopy extcodesize extcodecopy returndatasize returndatacopy extcodehash create create2 call callcode delegatecall staticcall log0 log1 log2 log3 log4 chainid origin gasprice basefee blockhash coinbase timestamp number difficulty gaslimit",
-literal:"true false"},i={className:"string",
-begin:/\bhex'(([0-9a-fA-F]{2}_?)*[0-9a-fA-F]{2})?'/},t={className:"string",
-begin:/\bhex"(([0-9a-fA-F]{2}_?)*[0-9a-fA-F]{2})?"/};function r(e){
-return e.inherit(e.APOS_STRING_MODE,{begin:/(\bunicode)?'/})}function l(e){
-return e.inherit(e.QUOTE_STRING_MODE,{begin:/(\bunicode)?"/})}var o={
-SOL_ASSEMBLY_KEYWORDS:n,baseAssembly:e=>{
-var a=r(e),o=l(e),c=/[A-Za-z_$][A-Za-z_$0-9.]*/,d=e.inherit(e.TITLE_MODE,{
-begin:/[A-Za-z$_][0-9A-Za-z$_]*/,lexemes:c,keywords:n}),u={className:"params",
-begin:/\(/,end:/\)/,excludeBegin:!0,excludeEnd:!0,lexemes:c,keywords:n,
-contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,a,o,s]},_={
-className:"operator",begin:/:=|->/};return{keywords:n,lexemes:c,
-contains:[a,o,i,t,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,s,_,{
-className:"function",lexemes:c,beginKeywords:"function",end:"{",excludeEnd:!0,
-contains:[d,u,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,_]}]}},
-solAposStringMode:r,solQuoteStringMode:l,HEX_APOS_STRING_MODE:i,
-HEX_QUOTE_STRING_MODE:t,SOL_NUMBER:s,isNegativeLookbehindAvailable:e}
-;const{baseAssembly:c,solAposStringMode:d,solQuoteStringMode:u,HEX_APOS_STRING_MODE:_,HEX_QUOTE_STRING_MODE:m,SOL_NUMBER:b,isNegativeLookbehindAvailable:E}=o
-;return e=>{for(var a=d(e),s=u(e),n=[],i=0;i<32;i++)n[i]=i+1
-;var t=n.map((e=>8*e)),r=[];for(i=0;i<=80;i++)r[i]=i
-;var l=n.map((e=>"bytes"+e)).join(" ")+" ",o=t.map((e=>"uint"+e)).join(" ")+" ",g=t.map((e=>"int"+e)).join(" ")+" ",M=[].concat.apply([],t.map((e=>r.map((a=>e+"x"+a))))),p={
-keyword:"var bool string int uint "+g+o+"byte bytes "+l+"fixed ufixed "+M.map((e=>"fixed"+e)).join(" ")+" "+M.map((e=>"ufixed"+e)).join(" ")+" enum struct mapping address new delete if else for while continue break return throw emit try catch revert unchecked _ function modifier event constructor fallback receive error virtual override constant immutable anonymous indexed storage memory calldata external public internal payable pure view private returns import from as using pragma contract interface library is abstract type assembly",
-literal:"true false wei gwei szabo finney ether seconds minutes hours days weeks years",
-built_in:"self this super selfdestruct suicide now msg block tx abi blockhash gasleft assert require Error Panic sha3 sha256 keccak256 ripemd160 ecrecover addmod mulmod log0 log1 log2 log3 log4"
-},O={className:"operator",begin:/[+\-!~*\/%<>&^|=]/
-},C=/[A-Za-z_$][A-Za-z_$0-9]*/,N={className:"params",begin:/\(/,end:/\)/,
-excludeBegin:!0,excludeEnd:!0,lexemes:C,keywords:p,
-contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,a,s,b,"self"]},f={
-begin:/\.\s*/,end:/[^A-Za-z0-9$_\.]/,excludeBegin:!0,excludeEnd:!0,keywords:{
-built_in:"gas value selector address length push pop send transfer call callcode delegatecall staticcall balance code codehash wrap unwrap name creationCode runtimeCode interfaceId min max"
-},relevance:2},y=e.inherit(e.TITLE_MODE,{begin:/[A-Za-z$_][0-9A-Za-z$_]*/,
-lexemes:C,keywords:p}),w={className:"built_in",
-begin:(E()?"(?<!\\$)\\b":"\\b")+"(gas|value|salt)(?=:)"};function x(e,a){return{
-begin:(E()?"(?<!\\$)\\b":"\\b")+e+"\\.\\s*",end:/[^A-Za-z0-9$_\.]/,
-excludeBegin:!1,excludeEnd:!0,lexemes:C,keywords:{built_in:e+" "+a},
-contains:[f],relevance:10}}var h=c(e),v=e.inherit(h,{
-contains:h.contains.concat([{begin:/\./,end:/[^A-Za-z0-9$.]/,excludeBegin:!0,
-excludeEnd:!0,keywords:{built_in:"slot offset length address selector"},
-relevance:2},{begin:/_/,end:/[^A-Za-z0-9$.]/,excludeBegin:!0,excludeEnd:!0,
-keywords:{built_in:"slot offset"},relevance:2}])});return{aliases:["sol"],
-keywords:p,lexemes:C,
-contains:[a,s,_,m,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,b,w,O,{
-className:"function",lexemes:C,
-beginKeywords:"function modifier event constructor fallback receive error",
-end:/[{;]/,excludeEnd:!0,
-contains:[y,N,w,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE],illegal:/%/
-},x("msg","gas value data sender sig"),x("block","blockhash coinbase difficulty gaslimit basefee number timestamp chainid"),x("tx","gasprice origin"),x("abi","decode encode encodePacked encodeWithSelector encodeWithSignature encodeCall"),x("bytes","concat"),f,{
-className:"class",lexemes:C,beginKeywords:"contract interface library",end:"{",
-excludeEnd:!0,illegal:/[:"\[\]]/,contains:[{beginKeywords:"is",lexemes:C
-},y,N,w,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},{lexemes:C,
-beginKeywords:"struct enum",end:"{",excludeEnd:!0,illegal:/[:"\[\]]/,
-contains:[y,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},{
-beginKeywords:"import",end:";",lexemes:C,keywords:"import from as",
-contains:[y,a,s,_,m,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,O]},{
-beginKeywords:"using",end:";",lexemes:C,keywords:"using for",
-contains:[y,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,O]},{className:"meta",
-beginKeywords:"pragma",end:";",lexemes:C,keywords:{
-keyword:"pragma solidity experimental abicoder",
-built_in:"ABIEncoderV2 SMTChecker v1 v2"},
-contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,e.inherit(a,{
-className:"meta-string"}),e.inherit(s,{className:"meta-string"})]},{
-beginKeywords:"assembly",end:/\b\B/,
-contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,e.inherit(v,{begin:"{",
-end:"}",endsParent:!0,contains:v.contains.concat([e.inherit(v,{begin:"{",
-end:"}",contains:v.contains.concat(["self"])})])})]}],illegal:/#/}}})());
-
-// Ugly hack to reload HLJS
-hljs.initHighlightingOnLoad();