@bananapus/distributor-v6 0.0.3

package/.github/pull_request_template.md

@@ -0,0 +1,33 @@
+# 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/docs/RISKS_MAINTENANCE.md`](../docs/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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,23 @@
+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

@@ -0,0 +1,26 @@
+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/**"
+      - name: Check contract sizes
+        run: forge build --sizes --skip "*/test/**" --skip "*/script/**" --skip SphinxUtils

package/.gitmodules

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

package/ADMINISTRATION.md

@@ -0,0 +1,65 @@
+# 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

@@ -0,0 +1,89 @@
+# 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

@@ -0,0 +1,52 @@
+# 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/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.0.1
+
+Initial release of the Juicebox V6 distributor system.
+
+### Features
+
+- **JBDistributor**: Abstract base contract with round-based distribution and configurable linear vesting.
+- **JBTokenDistributor**: Singleton distributor for IVotes-compatible ERC-20 tokens. Stake weight = delegated voting power at round start.
+- **JB721Distributor**: Singleton distributor for JB 721 NFT holders. Stake weight = tier's `votingUnits`. Burned NFTs excluded from stake; forfeited rewards reclaimable.
+- Both implement `IJBSplitHook` for direct integration with Juicebox payout splits.
+- Linear vesting over configurable number of rounds.
+- Fee-on-transfer token support via balance-delta pattern.
+- Native ETH distribution support.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Bananapus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# Juicebox Distributor
+
+`@bananapus/distributor-v6` distributes ERC-20 balances or 721 token inventories to many recipients under round-based vesting rules. It is a payout utility package for Juicebox-adjacent flows, not a protocol accounting layer.
+
+Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
+User journeys: [USER_JOURNEYS.md](./USER_JOURNEYS.md)  
+Skills: [SKILLS.md](./SKILLS.md)  
+Risks: [RISKS.md](./RISKS.md)  
+Administration: [ADMINISTRATION.md](./ADMINISTRATION.md)  
+Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
+
+## Overview
+
+This repo provides reusable distributors for teams that need deterministic post-funding or post-mint distribution.
+
+The package separates distribution mechanics by asset type:
+
+- `JBDistributor` coordinates shared round and vesting logic
+- `JBTokenDistributor` distributes ERC-20 balances using `IVotes` checkpointed voting power
+- `JB721Distributor` distributes value to 721 holders using checkpointed voting power, ensuring only holders at round start are eligible
+
+Both concrete distributors implement `IJBSplitHook`, which makes them usable directly from Juicebox payout splits.
+
+Use this repo when the problem is "how do we distribute already-owned assets over time?" Do not use it when the problem is project accounting, treasury settlement, or terminal execution.
+
+If the issue is "where did the project's value come from?" start in `nana-core-v6`, `nana-721-hook-v6`, or the upstream repo that minted or received the assets first.
+
+## Key Contracts
+
+| Contract | Role |
+| --- | --- |
+| `JBDistributor` | Shared round-based vesting, claiming, and accounting logic. |
+| `JBTokenDistributor` | ERC-20 distributor keyed to `IVotes` checkpointed voting power. |
+| `JB721Distributor` | NFT-aware distributor keyed to checkpointed voting power from the hook's `CHECKPOINTS()` module. Only NFTs held at round start are eligible. |
+
+## Mental Model
+
+1. a project funds the distributor, often through a payout split
+2. a vesting round begins and snapshots the eligible stake state
+3. recipients collect their pro-rata share as that round vests
+4. some unclaimable value can be reclaimed through explicit recovery paths, depending on the distributor type
+
+This repo does not explain why an allocation exists. It only defines how funded inventory is handed out.
+
+## Read These Files First
+
+1. `src/interfaces/IJBDistributor.sol`
+2. `src/JBDistributor.sol`
+3. `src/JBTokenDistributor.sol`
+4. `src/JB721Distributor.sol`
+
+## Integration Traps
+
+- distribution correctness depends on the distributor actually holding the assets it is expected to vest
+- ERC-20 and ERC-721 distributions share a mental model, but their edge cases are different
+- `releaseForfeitedRewards` matters for 721 distributions; token-vote distributions do not have the same burned-token path
+- snapshot timing is part of the trusted surface
+- this repo settles distributions, but it does not prove the upstream entitlement math was correct
+
+## Where State Lives
+
+- round and vesting state: `JBDistributor`
+- token snapshot inputs: `JBTokenSnapshotData`
+- vesting schedule state: `JBVestingData`
+- asset-specific claim behavior: the concrete distributor
+
+## High-Signal Tests
+
+1. `test/JBTokenDistributor.t.sol`
+2. `test/JB721Distributor.t.sol`
+3. `test/invariant/JB721DistributorInvariant.t.sol`
+
+## Install
+
+```bash
+npm install @bananapus/distributor-v6
+```
+
+## Development
+
+```bash
+npm install
+forge build
+forge test
+```
+
+Useful scripts:
+
+- `npm run test:fork`
+- `npm run deploy:mainnets`
+- `npm run deploy:testnets`
+
+## Repository Layout
+
+```text
+src/
+  JBDistributor.sol
+  JBTokenDistributor.sol
+  JB721Distributor.sol
+  interfaces/
+  structs/
+test/
+  token, 721, and invariant coverage
+script/
+  Deploy.s.sol
+```
+
+## Risks And Notes
+
+- distributors are only as trustworthy as the vesting parameters and funding they receive
+- operational mistakes often come from funding the wrong asset or underfunding the distributor
+- teams should review claim timing and snapshot assumptions with the same care they review the payout source
+
+## For AI Agents
+
+- Treat this repo as distribution plumbing, not as the source of upstream entitlement math.
+- Read both the ERC-20 and ERC-721 tests before claiming the flows are equivalent.

package/RISKS.md

@@ -0,0 +1,78 @@
+# 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.

package/SKILLS.md

@@ -0,0 +1,36 @@
+# Juicebox Distributor
+
+## Use This File For
+
+- Use this file when the task involves round-based vesting, split-hook distribution, or snapshot-based payout allocation.
+- Start here, then decide whether the issue is in shared vesting logic, `IVotes`-based stake measurement, or 721-based stake measurement.
+
+## Read This Next
+
+| If you need... | Open this next |
+|---|---|
+| Repo overview and architecture | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
+| Shared vesting engine | [`src/JBDistributor.sol`](./src/JBDistributor.sol), [`src/interfaces/IJBDistributor.sol`](./src/interfaces/IJBDistributor.sol) |
+| Token distributor behavior | [`src/JBTokenDistributor.sol`](./src/JBTokenDistributor.sol) |
+| 721 distributor behavior | [`src/JB721Distributor.sol`](./src/JB721Distributor.sol) |
+| Types and structs | [`src/structs/`](./src/structs/) |
+| Main tests | [`test/JBTokenDistributor.t.sol`](./test/JBTokenDistributor.t.sol), [`test/JB721Distributor.t.sol`](./test/JB721Distributor.t.sol), [`test/invariant/JB721DistributorInvariant.t.sol`](./test/invariant/JB721DistributorInvariant.t.sol) |
+
+## Repo Map
+
+| Area | Where to look |
+|---|---|
+| Main contracts | [`src/`](./src/) |
+| Structs and interfaces | [`src/structs/`](./src/structs/), [`src/interfaces/`](./src/interfaces/) |
+| Tests | [`test/`](./test/) |
+
+## Purpose
+
+Shared vesting and distribution engine for ERC-20 and 721-based payout flows.
+
+## Working Rules
+
+- Start in [`src/JBDistributor.sol`](./src/JBDistributor.sol) for shared round logic.
+- Treat snapshot timing as part of correctness.
+- `JBTokenDistributor` and `JB721Distributor` share a vesting engine but not the same ownership model.
+- Verify the distributor actually holds the asset it is meant to vest before reasoning about payout correctness.