@bananapus/distributor-v6 0.0.3

package/USER_JOURNEYS.md

@@ -0,0 +1,120 @@
+# User Journeys
+
+## Repo Purpose
+
+This repo distributes already-owned assets over time. It snapshots stake, starts vesting rounds, and lets eligible recipients collect what has unlocked.
+
+## Primary Actors
+
+- teams funding a distributor from a split or post-mint allocation
+- token holders or NFT holders collecting vested rewards
+- operators configuring round timing and deployment shape
+- auditors reviewing snapshot timing and stake-accounting correctness
+
+## Key Surfaces
+
+- `JBDistributor`: shared round and vesting engine
+- `JBTokenDistributor`: ERC-20 distributor using `IVotes`
+- `JB721Distributor`: NFT distributor using tier voting units
+
+## Journey 1: Fund A Distributor
+
+**Actor:** project or payout flow.
+
+**Intent:** move owned assets into a distributor that will vest them over time.
+
+**Preconditions**
+- the correct asset and distributor type are chosen
+- the distributor actually receives the inventory it is expected to vest
+
+**Main Flow**
+1. Fund the distributor directly or through a payout split.
+2. Confirm the tracked balance matches what the distributor received.
+3. Use the distributor as the vesting surface, not as the source of entitlement logic.
+
+**Failure Modes**
+- wrong asset funded
+- underfunded distributor
+- caller assumes funding alone starts vesting
+
+**Postconditions**
+- the distributor holds the asset inventory for future rounds
+
+## Journey 2: Start A Vesting Round
+
+**Actor:** any caller.
+
+**Intent:** snapshot the current round and begin vesting.
+
+**Preconditions**
+- the round timing and parameters are valid
+- the stake source is usable and non-zero
+
+**Main Flow**
+1. Call `beginVesting`.
+2. The distributor snapshots the relevant balance and stake source.
+3. Vesting entries become claimable over the configured schedule.
+
+**Failure Modes**
+- zero total stake
+- bad deployment parameters such as zero round duration or zero vesting rounds
+- stake snapshot is stale or surprising to operators
+
+**Postconditions**
+- a new vesting round exists with fixed snapshot assumptions
+
+## Journey 3: Collect Vested Rewards
+
+**Actor:** eligible recipient.
+
+**Intent:** collect the share that has unlocked for a round.
+
+**Preconditions**
+- the recipient is authorized under the distributor type
+- some share has already vested
+
+**Main Flow**
+1. Call the relevant claim function.
+2. The distributor checks authority and unlocked amount.
+3. The vested share transfers to the claimant.
+
+**Failure Modes**
+- invalid claimant
+- claim batch includes invalid 721 token IDs
+- reward token transfer fails
+
+**Postconditions**
+- vested rewards move to the claimant
+
+## Journey 4: Recycle Forfeited 721 Rewards
+
+**Actor:** caller using the 721 distributor path.
+
+**Intent:** release rewards tied to burned NFTs back into the future distribution pool.
+
+**Preconditions**
+- the distributor type is 721-based
+- the relevant NFTs are burned or otherwise forfeited under the configured rules
+
+**Main Flow**
+1. Call the forfeiture-release path.
+2. The distributor reduces current vesting obligations for those forfeited claims.
+3. The value remains in the distributor for future rounds instead of being destroyed.
+
+**Failure Modes**
+- caller expects the same behavior from the token distributor
+- off-chain systems treat forfeited value as burned instead of recycled
+
+**Postconditions**
+- forfeited 721 rewards return to the future distributable pool
+
+## Trust Boundaries
+
+- this repo trusts `JBDirectory` for authenticated split-hook caller checks
+- `JBTokenDistributor` trusts `IVotes` checkpoints
+- `JB721Distributor` trusts the 721 hook's `CHECKPOINTS()` module for historical voting power and the store for tier metadata
+
+## Hand-Offs
+
+- Use the upstream repo that funded the distributor when the question is about why an allocation exists.
+- Use [nana-721-hook-v6](../nana-721-hook-v6/USER_JOURNEYS.md) when the stake source is a tiered 721 hook.

package/foundry.toml

@@ -0,0 +1,22 @@
+[profile.default]
+solc = '0.8.28'
+evm_version = 'cancun'
+optimizer_runs = 200
+libs = ["node_modules", "lib"]
+fs_permissions = [{ access = "read-write", path = "./"}]
+
+[fuzz]
+runs = 4096
+
+[invariant]
+runs = 1024
+depth = 100
+fail_on_revert = false
+
+[fmt]
+number_underscore = "thousands"
+multiline_func_header = "all"
+wrap_comments = true
+
+[rpc_endpoints]
+ethereum = "${RPC_ETHEREUM_MAINNET}"

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@bananapus/distributor-v6",
+  "version": "0.0.3",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bananapus/nana-distributor-v6"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "test": "forge test",
+    "test:fork": "forge test --fork-url $RPC_ETHEREUM_MAINNET",
+    "coverage": "forge coverage --match-path \"./src/*.sol\" --report lcov --report summary",
+    "deploy:mainnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks mainnets",
+    "deploy:testnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks testnets"
+  },
+  "dependencies": {
+    "@bananapus/721-hook-v6": "^0.0.36",
+    "@bananapus/core-v6": "^0.0.34",
+    "@bananapus/permission-ids-v6": "^0.0.17",
+    "@openzeppelin/contracts": "^5.6.1",
+    "@prb/math": "^4.1.0"
+  },
+  "devDependencies": {
+    "@sphinx-labs/plugins": "^0.33.2"
+  }
+}

package/references/operations.md

@@ -0,0 +1,25 @@
+# Operations
+
+## Change checklist
+
+| If you're editing... | Verify... |
+|---|---|
+| `JBDistributor` vesting math | Claim totals, `totalVestingAmountOf`, and pool balances still reconcile across rounds |
+| `JBTokenDistributor` checkpoint logic | `getPastVotes` and `getPastTotalSupply` are read at the intended round-start block |
+| `JB721Distributor` stake math | Minted, remaining, and burned supply still produce the intended tier-weighted total stake |
+| `processSplitWith` | Terminal allowance flow and controller pre-funding flow both preserve actual received balances |
+| Deployment inputs | `DIRECTORY_ADDRESS`, `ROUND_DURATION`, and `VESTING_ROUNDS` match the intended chain and operator plan |
+
+## Common failure modes
+
+| Symptom | Likely cause |
+|---|---|
+| A holder gets no rewards in the token distributor | They never delegated, so `getPastVotes` returned zero |
+| Rewards appear stuck in the distributor | Supply was undelegated, vesting never began for the target token IDs, or the round boundary assumption is wrong |
+| 721 reward shares look diluted | Burned supply was not excluded correctly or token-to-tier mapping is wrong |
+| Split-hook funding credits the wrong amount | The caller path was misclassified between allowance-pull and pre-funded controller flow |
+
+## Read Next
+
+- [`script/Deploy.s.sol`](../script/Deploy.s.sol) when the failure might be deployment config rather than distributor math.
+- [`test/invariant/JB721DistributorInvariant.t.sol`](../test/invariant/JB721DistributorInvariant.t.sol) when a local patch looks safe but may have broken a longer-lived accounting invariant.

package/references/runtime.md

@@ -0,0 +1,36 @@
+# Runtime
+
+## Core role
+
+`JBDistributor` tracks balances per `(hook, rewardToken)`, allocates a round's claimable amount when vesting begins, and releases rewards over fixed vesting rounds.
+
+`JBTokenDistributor` uses `IVotes` checkpoints. Each `tokenId` encodes a staker address, and stake is `getPastVotes(encodedAddress, roundStartBlock(currentRound()))`.
+
+`JB721Distributor` uses the 721 hook store. Stake is derived from each token's tier `votingUnits`, while total stake sums minted-minus-burned supply across all tiers.
+
+## High-risk areas
+
+### Round and checkpoint semantics
+
+The token distributor depends on checkpointed voting power at the round start block. Holders must delegate for `getPastVotes` to count them, and undelegated supply can leave rewards stranded in the pool for later rounds.
+
+### Funding path split
+
+`processSplitWith` supports two funding patterns:
+
+- Terminal path: pull tokens via allowance and credit the actual received amount.
+- Controller path: assume tokens were transferred before the hook call and credit `context.amount`.
+
+Mixing these assumptions causes under- or over-accounting.
+
+### 721 burned-token behavior
+
+The 721 distributor excludes burned NFTs from total stake and treats `ownerOf` failure as burn evidence. Changes to burn detection or tier accounting can change reward shares retroactively.
+
+## Tests to trust first
+
+| Test file | What it covers |
+|---|---|
+| [`test/JBTokenDistributor.t.sol`](../test/JBTokenDistributor.t.sol) | Checkpointed vote allocation, non-delegated supply behavior, vesting flow, split-hook funding |
+| [`test/JB721Distributor.t.sol`](../test/JB721Distributor.t.sol) | Tier-based share math, burned token handling, split-hook funding, vesting collection |
+| [`test/invariant/JB721DistributorInvariant.t.sol`](../test/invariant/JB721DistributorInvariant.t.sol) | Longer-lived 721 accounting relationships that are easier to break than unit tests suggest |

package/remappings.txt

@@ -0,0 +1 @@
+forge-std/=lib/forge-std/src/

package/script/Deploy.s.sol

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {Script} from "forge-std/Script.sol";
+
+import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
+
+import {JB721Distributor} from "../src/JB721Distributor.sol";
+
+contract Deploy is Script {
+    function run() public {
+        vm.startBroadcast();
+
+        // Configure these values before deploying.
+        IJBDirectory directory = IJBDirectory(vm.envAddress("DIRECTORY_ADDRESS"));
+        uint256 roundDuration = vm.envUint("ROUND_DURATION");
+        uint256 vestingRounds = vm.envUint("VESTING_ROUNDS");
+
+        new JB721Distributor(directory, roundDuration, vestingRounds);
+
+        vm.stopBroadcast();
+    }
+}

package/slither-ci.config.json

@@ -0,0 +1,10 @@
+{
+  "detectors_to_exclude": "timestamp,uninitialized-local,naming-convention,solc-version,shadowing-local",
+  "exclude_informational": true,
+  "exclude_low": false,
+  "exclude_medium": false,
+  "exclude_high": false,
+  "disable_color": false,
+  "filter_paths": "(mocks/|test/|node_modules/|lib/)",
+  "legacy_ast": false
+}

package/src/JB721Distributor.sol

@@ -0,0 +1,180 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {IJB721Checkpoints} from "@bananapus/721-hook-v6/src/interfaces/IJB721Checkpoints.sol";
+import {IJB721TiersHook} from "@bananapus/721-hook-v6/src/interfaces/IJB721TiersHook.sol";
+import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
+import {IJBSplitHook} from "@bananapus/core-v6/src/interfaces/IJBSplitHook.sol";
+import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
+import {JBSplitHookContext} from "@bananapus/core-v6/src/structs/JBSplitHookContext.sol";
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+import {IERC721} from "@openzeppelin/contracts/token/ERC721/IERC721.sol";
+import {IVotes} from "@openzeppelin/contracts/governance/utils/IVotes.sol";
+
+import {IJB721Distributor} from "./interfaces/IJB721Distributor.sol";
+import {JBDistributor} from "./JBDistributor.sol";
+
+/// @notice A singleton distributor that distributes ERC-20 rewards to JB 721 NFT stakers with linear vesting.
+/// @dev Any project can use this distributor by configuring a payout split with
+/// `hook = this contract` and `beneficiary = address(their 721 hook)`.
+/// @dev The stake weight of each NFT is its tier's `votingUnits`. Burned NFTs are excluded from the total stake
+/// calculation and their unvested rewards can be reclaimed via `releaseForfeitedRewards`.
+/// @dev Implements `IJBSplitHook` so it can receive tokens directly from Juicebox project payout splits.
+contract JB721Distributor is JBDistributor, IJB721Distributor {
+    using SafeERC20 for IERC20;
+
+    //*********************************************************************//
+    // --------------------------- custom errors ------------------------- //
+    //*********************************************************************//
+
+    /// @notice Thrown when the caller is not a terminal or controller for the project.
+    error JB721Distributor_Unauthorized();
+
+    //*********************************************************************//
+    // ---------------- public immutable stored properties --------------- //
+    //*********************************************************************//
+
+    /// @notice The JB directory used to verify terminal/controller callers.
+    IJBDirectory public immutable DIRECTORY;
+
+    //*********************************************************************//
+    // -------------------------- constructor ---------------------------- //
+    //*********************************************************************//
+
+    /// @param directory The JB directory used to verify terminal/controller callers.
+    /// @param roundDuration_ The minimum amount of time stakers have to claim rewards, specified in blocks.
+    /// @param vestingRounds_ The number of rounds until tokens are fully vested.
+    constructor(
+        IJBDirectory directory,
+        uint256 roundDuration_,
+        uint256 vestingRounds_
+    )
+        JBDistributor(roundDuration_, vestingRounds_)
+    {
+        DIRECTORY = directory;
+    }
+
+    //*********************************************************************//
+    // ---------------------- receive ----------------------------------- //
+    //*********************************************************************//
+
+    /// @notice Allows the contract to receive native ETH (e.g. from payout splits).
+    receive() external payable {}
+
+    //*********************************************************************//
+    // ---------------------- external transactions ---------------------- //
+    //*********************************************************************//
+
+    /// @notice Receives tokens from a Juicebox payout split.
+    /// @dev Only callable by a terminal or controller for the project in the context.
+    /// @dev The hook address is read from `context.split.beneficiary`.
+    /// @dev The terminal grants an ERC-20 allowance before calling — we pull via `transferFrom`.
+    /// The controller sends tokens directly before calling — nothing to pull.
+    /// For native ETH, the terminal sends the amount as `msg.value`.
+    /// @param context The split hook context from the terminal or controller.
+    function processSplitWith(JBSplitHookContext calldata context) external payable override {
+        // Only terminals and controllers for the project can call this.
+        if (
+            !DIRECTORY.isTerminalOf(context.projectId, IJBTerminal(msg.sender))
+                && DIRECTORY.controllerOf(context.projectId) != IERC165(msg.sender)
+        ) revert JB721Distributor_Unauthorized();
+
+        // The target hook is the split's beneficiary.
+        address hook = address(context.split.beneficiary);
+
+        // If it's not a native-token transfer, check if the caller approved tokens (terminal pattern).
+        if (msg.value == 0 && context.amount != 0) {
+            uint256 balanceBefore = IERC20(context.token).balanceOf(address(this));
+            // Check if the caller has granted an allowance (terminal). If so, pull the tokens.
+            // The controller sends tokens before calling, so no pull is needed in that case.
+            uint256 allowance = IERC20(context.token).allowance(msg.sender, address(this));
+            if (allowance >= context.amount) {
+                // Terminal pattern: pull tokens via transferFrom.
+                IERC20(context.token).safeTransferFrom(msg.sender, address(this), context.amount);
+            }
+            // For both terminal and controller paths, credit actual received amount (handles fee-on-transfer).
+            _balanceOf[hook][IERC20(context.token)] += IERC20(context.token).balanceOf(address(this)) - balanceBefore;
+        } else if (msg.value != 0) {
+            // Native ETH: credit actual value received.
+            _balanceOf[hook][IERC20(context.token)] += msg.value;
+        }
+    }
+
+    //*********************************************************************//
+    // -------------------------- public views --------------------------- //
+    //*********************************************************************//
+
+    /// @notice Indicates whether this contract supports the given interface.
+    /// @param interfaceId The interface ID to check.
+    /// @return A flag indicating support.
+    function supportsInterface(bytes4 interfaceId) public pure override returns (bool) {
+        return interfaceId == type(IJB721Distributor).interfaceId || interfaceId == type(IJBSplitHook).interfaceId
+            || interfaceId == type(IERC165).interfaceId;
+    }
+
+    //*********************************************************************//
+    // ---------------------- internal transactions ---------------------- //
+    //*********************************************************************//
+
+    /// @notice Check if the account owns the given NFT token ID.
+    /// @param hook The hook the token belongs to.
+    /// @param tokenId The ID of the token to check.
+    /// @param account The account to check ownership for.
+    /// @return canClaim True if the account owns the token.
+    function _canClaim(address hook, uint256 tokenId, address account) internal view override returns (bool canClaim) {
+        canClaim = IERC721(hook).ownerOf(tokenId) == account;
+    }
+
+    /// @notice The stake weight of a given NFT token ID based on its tier's voting units, validated against historical
+    /// state.
+    /// @dev Returns 0 if the token's current owner had no checkpointed voting power at the round's start block,
+    /// preventing late mints from capturing pro-rata rewards within the current round.
+    /// @param hook The hook the token belongs to.
+    /// @param tokenId The ID of the token to get the stake weight of.
+    /// @return tokenStakeAmount The voting units of the token's tier (or 0 if ineligible).
+    function _tokenStake(address hook, uint256 tokenId) internal view override returns (uint256 tokenStakeAmount) {
+        uint256 votingUnits = IJB721TiersHook(hook).STORE().tierOfTokenId(hook, tokenId, false).votingUnits;
+
+        // Use the checkpoints module to verify the token's owner had voting power at the round's start block.
+        // If they had no voting power at that time, this token was minted or acquired after the round started
+        // and is not eligible for this round's rewards.
+        IJB721Checkpoints checkpoints = IJB721TiersHook(hook).CHECKPOINTS();
+        address owner = IERC721(hook).ownerOf(tokenId);
+        uint256 pastVotes = IVotes(address(checkpoints)).getPastVotes(owner, roundStartBlock(currentRound()));
+
+        // If the owner had no voting power at round start, the token is ineligible.
+        // slither-disable-next-line incorrect-equality
+        if (pastVotes == 0) return 0;
+
+        // Cap at the token's tier voting units — the owner's past votes may cover multiple tokens,
+        // but each individual token's stake is at most its tier's voting units.
+        tokenStakeAmount = votingUnits < pastVotes ? votingUnits : pastVotes;
+    }
+
+    /// @notice The total stake at a specific block, using the hook's checkpoints module for historical accuracy.
+    /// @dev Uses `IVotes.getPastTotalSupply` from the hook's CHECKPOINTS module. This ensures that only NFTs
+    /// that existed (and were delegated) at `blockNumber` are counted, preventing late mints from diluting or
+    /// capturing rewards within the current round.
+    /// @param hook The hook to get the total stake for.
+    /// @param blockNumber The block number to get the total staked amount at.
+    /// @return total The total checkpointed voting units at the given block.
+    function _totalStake(address hook, uint256 blockNumber) internal view override returns (uint256 total) {
+        IJB721Checkpoints checkpoints = IJB721TiersHook(hook).CHECKPOINTS();
+        total = IVotes(address(checkpoints)).getPastTotalSupply(blockNumber);
+    }
+
+    /// @notice Checks if the given token was burned.
+    /// @param hook The hook the token belongs to.
+    /// @param tokenId The tokenId to check.
+    /// @return tokenWasBurned True if the token was burned.
+    function _tokenBurned(address hook, uint256 tokenId) internal view override returns (bool tokenWasBurned) {
+        // slither-disable-next-line unused-return
+        try IERC721(hook).ownerOf(tokenId) returns (address) {
+            tokenWasBurned = false;
+        } catch {
+            tokenWasBurned = true;
+        }
+    }
+}