@bananapus/distributor-v6 0.0.6 → 0.0.8

package/README.md

@@ -80,8 +80,8 @@ npm install @bananapus/distributor-v6
 
 ```bash
 npm install
-forge build
-forge test
+forge build --deny notes
+forge test --deny notes
 ```
 
 Useful scripts:

package/package.json

@@ -1,11 +1,20 @@
 {
   "name": "@bananapus/distributor-v6",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Bananapus/nana-distributor-v6"
   },
+  "files": [
+    "CHANGELOG.md",
+    "foundry.lock",
+    "foundry.toml",
+    "references/",
+    "remappings.txt",
+    "script/",
+    "src/"
+  ],
   "engines": {
     "node": ">=20.0.0"
   },
@@ -17,13 +26,13 @@
     "deploy:testnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks testnets"
   },
   "dependencies": {
-    "@bananapus/721-hook-v6": "^0.0.38",
-    "@bananapus/core-v6": "^0.0.36",
-    "@bananapus/permission-ids-v6": "^0.0.19",
-    "@openzeppelin/contracts": "^5.6.1",
-    "@prb/math": "^4.1.0"
+    "@bananapus/721-hook-v6": "0.0.43",
+    "@bananapus/core-v6": "0.0.39",
+    "@bananapus/permission-ids-v6": "0.0.22",
+    "@openzeppelin/contracts": "5.6.1",
+    "@prb/math": "4.1.1"
   },
   "devDependencies": {
-    "@sphinx-labs/plugins": "^0.33.2"
+    "@sphinx-labs/plugins": "0.33.3"
   }
 }

package/src/JB721Distributor.sol

@@ -6,6 +6,7 @@ import {IJB721TiersHook} from "@bananapus/721-hook-v6/src/interfaces/IJB721Tiers
 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 {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.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";
@@ -32,6 +33,9 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when native ETH is sent but context.token is not NATIVE_TOKEN.
+    error JB721Distributor_TokenMismatch();
+
     /// @notice Thrown when the caller is not a terminal or controller for the project.
     error JB721Distributor_Unauthorized();
 
@@ -133,6 +137,8 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
                 _balanceOf[hook][IERC20(context.token)] += context.amount;
             }
         } else if (msg.value != 0) {
+            // Validate that context.token matches NATIVE_TOKEN to prevent cross-booking attacks.
+            if (context.token != JBConstants.NATIVE_TOKEN) revert JB721Distributor_TokenMismatch();
             // Native ETH: credit actual value received.
             _balanceOf[hook][IERC20(context.token)] += msg.value;
             _accountedBalanceOf[IERC20(context.token)] += msg.value;
@@ -250,8 +256,8 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
 
     /// @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 snapshot block,
-    /// preventing late mints from capturing pro-rata rewards within the current round.
+    /// @dev Returns 0 if the token was not owned at the round's snapshot block or if its snapshot owner had no
+    /// checkpointed voting power, 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).
@@ -259,16 +265,17 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         uint256 votingUnits =
             IJB721TiersHook(hook)
         .STORE()
-        .tierOfTokenId({hook: hook, tokenId: tokenId, includeResolvedUri: false})
-        .votingUnits;
+        .tierOfTokenId({hook: hook, tokenId: tokenId, includeResolvedUri: false}).votingUnits;
 
-        // Use the checkpoints module to verify the token's owner had voting power at the round's snapshot 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({account: owner, timepoint: roundSnapshotBlock[currentRound()]});
+        // Stake eligibility is fixed at the round snapshot block, not the caller's current block.
+        uint256 snapshotBlock = roundSnapshotBlock[currentRound()];
+        address owner = _snapshotOwnerOf({hook: hook, tokenId: tokenId, snapshotBlock: snapshotBlock});
+        if (owner == address(0)) return 0;
+
+        // Use the checkpoints module to verify the token's snapshot owner had voting power at the round's snapshot
+        // block. If the token did not exist then, ownerOfAt returns zero above and the token is not eligible.
+        uint256 pastVotes = IVotes(address(IJB721TiersHook(hook).CHECKPOINTS()))
+            .getPastVotes({account: owner, timepoint: snapshotBlock});
 
         // If the owner had no voting power at round start, the token is ineligible.
         // slither-disable-next-line incorrect-equality
@@ -295,6 +302,35 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
     // ----------------------- private helpers --------------------------- //
     //*********************************************************************//
 
+    /// @notice Returns the token owner at the round snapshot block.
+    /// @dev Returns zero if the hook has no checkpoint module, the module does not support historical ownership, the
+    /// call fails, or the token was not owned at `snapshotBlock`. Treating all of these as ineligible prevents late
+    /// mints and current-owner transfers from claiming rewards for a snapshot they did not participate in.
+    /// @param hook The 721 hook whose checkpoint module is queried.
+    /// @param tokenId The token ID to query.
+    /// @param snapshotBlock The round snapshot block to prove ownership at.
+    /// @return owner The historical token owner, or zero if ownership cannot be proven.
+    function _snapshotOwnerOf(
+        address hook,
+        uint256 tokenId,
+        uint256 snapshotBlock
+    )
+        private
+        view
+        returns (address owner)
+    {
+        // The 721 hook owns the checkpoint module; the distributor only trusts that module's historical proof.
+        IJB721Checkpoints checkpoints = IJB721TiersHook(hook).CHECKPOINTS();
+
+        // Use staticcall so older hooks without `ownerOfAt` fail closed instead of reverting the whole distribution.
+        (bool success, bytes memory data) =
+            address(checkpoints).staticcall(abi.encodeCall(IJB721Checkpoints.ownerOfAt, (tokenId, snapshotBlock)));
+        if (!success || data.length < 32) return address(0);
+
+        // A zero owner means the token was not owned at the snapshot block and is not eligible this round.
+        owner = abi.decode(data, (address));
+    }
+
     /// @notice Vest a single NFT token, enforcing a per-owner voting power cap across the batch.
     /// @dev Returns 0 for burned tokens, already-vested tokens, tokens whose owner had no snapshot voting power,
     ///      and tokens whose owner has already exhausted their voting power cap within this batch.
@@ -344,21 +380,22 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         uint256 votingUnits =
             IJB721TiersHook(ctx.hook)
         .STORE()
-        .tierOfTokenId({hook: ctx.hook, tokenId: tokenId, includeResolvedUri: false})
-        .votingUnits;
+        .tierOfTokenId({hook: ctx.hook, tokenId: tokenId, includeResolvedUri: false}).votingUnits;
 
-        // Look up the owner, verify snapshot eligibility, and find or create the owner's tracking slot.
+        // Look up the snapshot owner, verify snapshot eligibility, and find or create the owner's tracking slot.
         uint256 ownerIndex;
         uint256 pastVotes;
         {
-            // Get the current owner of the NFT.
-            address owner = IERC721(ctx.hook).ownerOf(tokenId);
+            // Reuse the same round snapshot block for every token in this vesting batch.
+            uint256 snapshotBlock = roundSnapshotBlock[currentRound()];
+            address owner = _snapshotOwnerOf({hook: ctx.hook, tokenId: tokenId, snapshotBlock: snapshotBlock});
+            if (owner == address(0)) return (0, newUniqueCount);
 
             // Query the owner's checkpointed voting power at the round's snapshot block.
             pastVotes = IVotes(address(IJB721TiersHook(ctx.hook).CHECKPOINTS()))
-                .getPastVotes({account: owner, timepoint: roundSnapshotBlock[currentRound()]});
+                .getPastVotes({account: owner, timepoint: snapshotBlock});
 
-            // If the owner had no voting power at round start, the token is ineligible for this round.
+            // If the snapshot owner had no voting power at round start, the token is ineligible for this round.
             // slither-disable-next-line incorrect-equality
             if (pastVotes == 0) return (0, newUniqueCount);
 

package/src/JBTokenDistributor.sol

@@ -4,6 +4,7 @@ pragma solidity 0.8.28;
 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 {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
 import {JBSplitHookContext} from "@bananapus/core-v6/src/structs/JBSplitHookContext.sol";
 import {IVotes} from "@openzeppelin/contracts/governance/utils/IVotes.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
@@ -30,6 +31,9 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
     /// @notice Thrown when a tokenId has non-zero upper bits (above 160), which would alias to the same staker address.
     error JBTokenDistributor_InvalidTokenId();
 
+    /// @notice Thrown when native ETH is sent but context.token is not NATIVE_TOKEN.
+    error JBTokenDistributor_TokenMismatch();
+
     /// @notice Thrown when the caller is not a terminal or controller for the project.
     error JBTokenDistributor_Unauthorized();
 
@@ -102,6 +106,8 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
                 _balanceOf[hook][IERC20(context.token)] += context.amount;
             }
         } else if (msg.value != 0) {
+            // Validate that context.token matches NATIVE_TOKEN to prevent cross-booking attacks.
+            if (context.token != JBConstants.NATIVE_TOKEN) revert JBTokenDistributor_TokenMismatch();
             // Native ETH: credit actual value received.
             _balanceOf[hook][IERC20(context.token)] += msg.value;
             _accountedBalanceOf[IERC20(context.token)] += msg.value;
@@ -133,6 +139,8 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
     function _canClaim(address hook, uint256 tokenId, address account) internal pure override returns (bool canClaim) {
         hook; // Silence unused variable warning.
         if (tokenId >> 160 != 0) revert JBTokenDistributor_InvalidTokenId();
+        // The high bits were checked above, so this cast recovers the encoded address.
+        // forge-lint: disable-next-line(unsafe-typecast)
         canClaim = address(uint160(tokenId)) == account;
     }
 
@@ -156,6 +164,8 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
     /// @return tokenStakeAmount The delegated voting power at the round's snapshot block.
     function _tokenStake(address hook, uint256 tokenId) internal view override returns (uint256 tokenStakeAmount) {
         if (tokenId >> 160 != 0) revert JBTokenDistributor_InvalidTokenId();
+        // The high bits were checked above, so this cast recovers the encoded address.
+        // forge-lint: disable-next-line(unsafe-typecast)
         tokenStakeAmount = IVotes(hook).getPastVotes(address(uint160(tokenId)), roundSnapshotBlock[currentRound()]);
     }
 

package/.github/pull_request_template.md

@@ -1,33 +0,0 @@
-# Description
-
-What does this PR do, how, and why?
-
-## Risk Surface
-
-What new trust boundary, failure mode, operational dependency, or integration caveat does this PR introduce or remove?
-
-## RISKS.md Impact
-
-- [ ] No runtime, admin, deployment, or integration risk surface changed
-- [ ] Updated this repo's `RISKS.md`
-- [ ] Updated `/v6/evm/RISKS.md` because ecosystem behavior changed
-- [ ] If no `RISKS.md` update was needed, I explained why in this PR
-
-Reference: [`/v6/evm/RISKS_MAINTENANCE.md`](../../RISKS_MAINTENANCE.md)
-
-## Checklist
-
-- [ ] Tests cover the behavior change
-- [ ] Code is natspec'd where needed
-- [ ] Code is linted and formatted
-- [ ] I ran the relevant tests locally
-- [ ] I checked for stale docs and updated them where needed
-- [ ] `STYLE_GUIDE.md` is adhered to — no lint errors, warnings, or notes
-- [ ] No build errors, warnings, or notes
-
-## Interactions
-
-These changes impact the following contracts or docs:
-
-- Directly:
-- Indirectly:

package/.github/workflows/lint.yml

@@ -1,19 +0,0 @@
-name: lint
-on:
-  pull_request:
-    branches:
-      - main
-  push:
-    branches:
-      - main
-jobs:
-  forge-test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          submodules: recursive
-      - name: Install Foundry
-        uses: foundry-rs/foundry-toolchain@v1
-      - name: Check linting
-        run: forge fmt --check

package/.github/workflows/publish.yml

@@ -1,19 +0,0 @@
-name: publish
-on:
-  push:
-    branches:
-      - main
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22.4.x
-          registry-url: https://registry.npmjs.org
-      # This will fail if the version in package.json has not increased.
-      - name: Publish to npm
-        run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/slither.yml

@@ -1,23 +0,0 @@
-name: slither
-on:
-  pull_request:
-    branches: [main]
-  push:
-    branches: [main]
-jobs:
-  slither:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          submodules: recursive
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22.4.x
-      - name: Install npm dependencies
-        run: npm install --omit=dev
-      - name: Run Slither
-        uses: crytic/slither-action@v0.3.1
-        with:
-          slither-config: slither-ci.config.json
-          fail-on: medium

package/.github/workflows/test.yml

@@ -1,28 +0,0 @@
-name: test
-on:
-  pull_request:
-    branches:
-      - main
-  push:
-    branches:
-      - main
-jobs:
-  forge-test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          submodules: recursive
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22.4.x
-      - name: Install npm dependencies
-        run: npm install --omit=dev
-      - name: Install Foundry
-        uses: foundry-rs/foundry-toolchain@v1
-      - name: Run tests
-        run: forge test --fail-fast --summary --detailed --skip "*/script/**"
-        env:
-          RPC_ETHEREUM_MAINNET: ${{ secrets.RPC_ETHEREUM_MAINNET }}
-      - name: Check contract sizes
-        run: forge build --sizes --skip "*/test/**" --skip "*/script/**" --skip SphinxUtils

package/.gitmodules

@@ -1,3 +0,0 @@
-[submodule "lib/forge-std"]
-	path = lib/forge-std
-	url = https://github.com/foundry-rs/forge-std

package/ADMINISTRATION.md

@@ -1,65 +0,0 @@
-# Administration
-
-## At A Glance
-
-| Item | Details |
-| --- | --- |
-| Scope | Round-based vesting and distribution configuration |
-| Control posture | Mostly parameter- and caller-driven, with asset-specific authority checks |
-| Highest-risk actions | Bad deployment parameters, wrong funding assumptions, and stale snapshot timing |
-| Recovery posture | Some value can remain for future rounds, but bad parameters can brick an instance |
-
-## Purpose
-
-`nana-distributor-v6` has less admin complexity than many sibling repos, but deployment parameters and funding assumptions still create real control risk.
-
-## Control Model
-
-- vesting is mostly driven by deployment parameters and permissionless round starts
-- claim authority differs by distributor type
-- 721 forfeiture handling adds a separate recovery path not present in the token distributor
-
-## Roles
-
-| Role | How Assigned | Scope | Notes |
-| --- | --- | --- | --- |
-| Round starter | Any caller | Per distributor | Vesting is permissionless |
-| Token claimant | Encoded claimant address | Per token slot | Token distributor authority model |
-| NFT claimant | Current NFT owner | Per token ID | 721 distributor authority model |
-
-## Privileged Surfaces
-
-- deployment parameters
-- funding flows
-- claim entrypoints with distributor-specific authority checks
-- 721 forfeiture release path
-
-## Immutable And One-Way
-
-- bad constructor parameters can permanently make an instance unusable
-- snapshots define a round once taken
-- vested or collected value does not rewind
-
-## Operational Notes
-
-- review round timing and vesting-round count before deployment
-- verify the distributor holds the correct asset before starting rounds
-- do not assume token and 721 variants behave identically
-
-## Recovery
-
-- unclaimed value can remain for future rounds
-- 721 forfeiture release can recycle some value
-- bad deployment parameters usually require a new distributor instance
-
-## Admin Boundaries
-
-- this repo does not create upstream entitlement logic
-- permissionless vesting means operators do not fully control snapshot timing
-- the distributor cannot make a missing or wrong stake source correct
-
-## Source Map
-
-- `src/JBDistributor.sol`
-- `src/JBTokenDistributor.sol`
-- `src/JB721Distributor.sol`

package/ARCHITECTURE.md

@@ -1,89 +0,0 @@
-# Architecture
-
-## Purpose
-
-`nana-distributor-v6` provides round-based vesting and claiming for already-owned assets. It supports both `IVotes`-based ERC-20 distributions and 721-based distributions without becoming a treasury or accounting layer.
-
-## System Overview
-
-`JBDistributor` is the shared vesting engine. `JBTokenDistributor` changes stake measurement to checkpointed voting power. `JB721Distributor` changes stake measurement to checkpointed voting power from the hook's `CHECKPOINTS()` module, ensuring only NFTs held at round start are eligible.
-
-Both variants can be used as `IJBSplitHook` receivers.
-
-## Core Invariants
-
-- snapshot timing must stay coherent
-- tracked funded balance must cover current vesting obligations
-- claim authority must match the distributor type
-- 721 forfeiture handling must not over-allocate or burn value accidentally
-- token and 721 variants must preserve the same core vesting math
-
-## Modules
-
-| Module | Responsibility | Notes |
-| --- | --- | --- |
-| `JBDistributor` | Shared rounds, vesting, snapshots, and claims | Economic core |
-| `JBTokenDistributor` | ERC-20 distribution using `IVotes` checkpoints | Token stake source |
-| `JB721Distributor` | NFT distribution using checkpointed voting power | 721 stake source |
-
-## Trust Boundaries
-
-- split-hook caller authentication depends on `JBDirectory`
-- `JBTokenDistributor` trusts `IVotes` checkpoint history
-- `JB721Distributor` trusts the 721 hook's `CHECKPOINTS()` module for historical voting power and the store for tier metadata
-- upstream entitlement logic still lives outside this repo
-
-## Critical Flows
-
-### Begin Vesting
-
-```text
-funded distributor
-  -> begin a round
-  -> snapshot stake and tracked balance for that round
-  -> record vesting entries for the requested token IDs
-```
-
-### Collect
-
-```text
-claimant
-  -> prove authority for the token ID or encoded claimant slot
-  -> compute unlocked share
-  -> transfer the vested amount
-```
-
-## Accounting Model
-
-This repo owns vesting-round accounting. It does not own upstream treasury accounting or entitlement creation.
-
-The main variables are snapshot balance, total vesting amount, and the stake source used to split each round.
-
-## Security Model
-
-- wrong snapshots can misallocate a whole round
-- bad constructor parameters can brick a distributor instance
-- split-funding caller assumptions matter because `processSplitWith` distinguishes pull and pre-sent flows
-- 721 and token variants intentionally differ in authority and forfeiture behavior
-
-## Safe Change Guide
-
-- review snapshot timing and vesting math together
-- if claim authority changes, re-check both distributor variants separately
-- if funding semantics change, test terminal-style and controller-style flows explicitly
-
-## Canonical Checks
-
-- token distribution behavior:
-  `test/JBTokenDistributor.t.sol`
-- 721 distribution behavior:
-  `test/JB721Distributor.t.sol`
-- 721 invariants:
-  `test/invariant/JB721DistributorInvariant.t.sol`
-
-## Source Map
-
-- `src/JBDistributor.sol`
-- `src/JBTokenDistributor.sol`
-- `src/JB721Distributor.sol`
-- `src/interfaces/IJBDistributor.sol`

package/AUDIT_INSTRUCTIONS.md

@@ -1,52 +0,0 @@
-# Audit Instructions
-
-This repo is a shared vesting engine plus two concrete distributor variants. Audit it as payout logic whose main risks are snapshot timing, stake measurement, and funding assumptions.
-
-## Audit Objective
-
-Find issues that:
-
-- misallocate rewards because the snapshot or stake source is wrong
-- break vesting or claiming because parameters are invalid
-- let caller or claim authority drift from the intended model
-- make split-funding assumptions unsafe
-
-## Scope
-
-In scope:
-
-- `src/JBDistributor.sol`
-- `src/JBTokenDistributor.sol`
-- `src/JB721Distributor.sol`
-- interfaces and structs under `src/`
-
-## Start Here
-
-1. `src/JBDistributor.sol`
-2. `src/JBTokenDistributor.sol`
-3. `src/JB721Distributor.sol`
-
-## Security Model
-
-The shared distributor:
-
-- snapshots balance and stake for a round
-- tracks vesting obligations
-- lets authorized claimants collect what has unlocked
-
-The concrete variants only change how stake and claimant authority are measured.
-
-## Critical Invariants
-
-1. Snapshot and stake source stay coherent.  
-   A round should not allocate more or less than the chosen stake source supports.
-2. Tracked balance covers vesting obligations.  
-   Current and future vesting must reconcile with funded inventory.
-3. Claim authority matches distributor type.  
-   The token and 721 variants must enforce their distinct authority models correctly.
-
-## Verification
-
-- `npm install`
-- `forge build`
-- `forge test`

package/RISKS.md

@@ -1,78 +0,0 @@
-# Distributor Risk Register
-
-This file covers the shared vesting engine in `JBDistributor` and the two concrete payout-split receivers, `JB721Distributor` and `JBTokenDistributor`.
-
-## How To Use This File
-
-- Read `Priority risks` first. Those are the failure modes with the highest payout-integrity impact.
-- Treat the shared `JBDistributor` logic as the economic core.
-- Use `Invariants to verify` as the minimum test envelope before routing live splits through a distributor.
-
-## Priority Risks
-
-| Priority | Risk | Why it matters | Primary controls |
-|----------|------|----------------|------------------|
-| P0 | Wrong stake snapshot or stale stake source | A bad stake reading misallocates rewards for an entire round. | Snapshot review, invariants, and careful integration with the chosen hook or `IVotes` token. |
-| P1 | Zero-stake or bad-parameter deployment | Bad constructor inputs or zero total stake can make core flows revert. | Deployment-time validation and operator runbooks. |
-| P1 | Split funding trust mismatch | `processSplitWith` distinguishes terminal-style pull flows from controller-style pre-sent flows. | Restrict callers and test both paths. |
-
-## 1. Trust Assumptions
-
-- **`JBDirectory` is trusted.**
-- **Stake sources are trusted.**
-- **Deployment parameters must be sane.**
-
-## 2. Economic Risks
-
-- **Round snapshot timing has a zero-balance edge case.**
-- **Unclaimed value stays in the pool.**
-- **Partial-round claims are linear, not cliff-based.**
-- **Forfeited 721 rewards are recycled, not burned.**
-- **Undelegated `IVotes` balances can dilute participation.**
-
-## 3. Access Control And Caller Risks
-
-- **Vesting is permissionless.**
-- **Claim authority differs by distributor type.**
-- **721 claim batches are brittle to invalid token IDs.**
-- **Forfeiture release is effectively 721-only.**
-- **Split-hook entry is tightly gated.**
-
-## 4. DoS And Liveness Risks
-
-- **Zero stake reverts vesting.**
-- **Zero distributable balance reverts vesting.** The `beginVesting` call reverts with `JBDistributor_NothingToDistribute` if the distributable balance for a token is zero.
-- **Bad constructor parameters can brick the instance.**
-- **Resolver or token callback failures can block collection.**
-
-## 5. Integration Risks
-
-- **Controller-vs-terminal split funding heuristic matters.**
-- **Fee-on-transfer handling uses balance-delta accounting.** Both terminal-pull and controller-pre-send paths measure `balanceAfter - balanceBefore` to credit the actual received amount.
-- **721 stake weights depend on checkpointed voting power at round start.** The `CHECKPOINTS()` module must be deployed and delegates must be set before the round snapshot block, or stakers receive zero weight.
-- **721 vesting and claiming treat burned tokens differently.**
-- **Checkpoint availability matters for both `IVotes` token distributors and 721 distributors.**
-- **Token distributor rejects token IDs with non-zero upper bits** (above 160) to prevent aliasing to the same staker address.
-
-## 6. Invariants To Verify
-
-- `totalVestingAmountOf <= _balanceOf`
-- collections plus remaining vesting plus future distributable balance never exceed tracked funded balance
-- non-zero round snapshots stay stable within a round
-- `latestVestedIndexOf` advances contiguously
-- burned NFTs are excluded from 721 stake (via zero checkpointed votes) and only recycled through the explicit forfeiture path
-- only the encoded address can collect from the token distributor
-
-## 7. Accepted Behaviors
-
-### 7.1 Anyone can trigger a round snapshot
-
-This improves liveness, but it also means operators do not fully control the exact block when a round is crystallized.
-
-### 7.2 Rewards can remain undistributed when stake is missing
-
-If some potential participants have zero effective stake for a round, the corresponding value stays in the distributor for future rounds.
-
-### 7.3 721 and `IVotes` variants intentionally differ
-
-They share the vesting engine but not the same ownership model.