@bananapus/distributor-v6 0.0.7 → 0.0.9

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.

package/SKILLS.md

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

package/USER_JOURNEYS.md

@@ -1,122 +0,0 @@
-# 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.
-
-**Snapshot timing:** The snapshot for each round is taken when the previous round first sees activity (`poke`, `beginVesting`, or `collectVestedRewards`). To be included in round N's distribution, make sure your tokens are held and delegated before anyone interacts with round N-1. In practice, keep your delegation current — if it is set before the previous round's activity begins, your voting power will be counted for the next round.
-
-**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/slither-ci.config.json

@@ -1,10 +0,0 @@
-{
-  "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
-}