@bananapus/distributor-v6 0.0.37 → 0.0.42

package/README.md

@@ -6,13 +6,13 @@
 
 - [ARCHITECTURE.md](./ARCHITECTURE.md) — system overview, modules, trust boundaries, and core invariants.
 - [USER_JOURNEYS.md](./USER_JOURNEYS.md) — end-to-end flows for funders and claimants across token and 721 variants.
-- [INVARIANTS.md](./INVARIANTS.md) — per-section invariants for snapshot fairness, vesting math, claim authority, loans, and recycling.
+- [INVARIANTS.md](./INVARIANTS.md) — per-section invariants for snapshot fairness, vesting math, beneficiary routing, loans, and recycling.
 - [RISKS.md](./RISKS.md) — risk register with priority risks and the minimum invariants to verify.
 - [ADMINISTRATION.md](./ADMINISTRATION.md) — deployment parameters, control posture, and recovery guidance.
 - [SKILLS.md](./SKILLS.md) — quick index for routing tasks into the right sub-document.
 - [STYLE_GUIDE.md](./STYLE_GUIDE.md) — Solidity and repo conventions used across the Juicebox V6 ecosystem.
 - [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md) — audit framing, targets, and suggested hunting grounds.
-- [CHANGELOG.md](./CHANGELOG.md) — release notes and dependency bumps.
+- [CHANGELOG.md](./CHANGELOG.md) - V5 to V6 migration changelog.
 
 ## Overview
 
@@ -22,7 +22,7 @@ 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 the funded round's snapshot block are eligible
+- `JB721Distributor` distributes value to active 721 holders using the hook's checkpointed owner and active-vote data, ensuring only holders at the funded round's snapshot block are eligible
 
 Both concrete distributors implement `IJBSplitHook`, which makes them usable directly from Juicebox payout splits.
 
@@ -30,44 +30,52 @@ Use this repo when the problem is "how do we distribute already-owned assets ove
 
 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
+## 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 the funded round's snapshot block are eligible. |
+| `JB721Distributor` | NFT-aware distributor keyed to checkpointed voting power from the hook's checkpoint module. Only NFTs held at the funded round's snapshot block are eligible. |
 
-## Mental Model
+## Mental model
 
 1. a project funds the distributor, often through a payout split
 2. accepted funding is assigned to the current reward round for the chosen token or 721 stake source
-3. the distributor's immutable claim duration decides whether funded reward rounds expire
-4. the encoded token staker or current NFT owner later claims completed past reward rounds into a fresh vesting entry
-5. anyone can recycle expired unclaimed reward rounds after their deadline
-6. recipients collect their vested share as the configured vesting schedule unlocks
+3. each funded reward round records an active-vote snapshot denominator for its token, collection, or tier group
+4. anyone can start vesting completed past reward rounds for an encoded token staker or current NFT owner
+5. anyone can recycle expired reward-round inventory that has not started vesting after the claim deadline
+6. recipients collect their vested share as the configured vesting schedule unlocks; helpers can collect only to the
+   canonical holder
 7. eligible claimants can borrow against vesting revnet rewards without bypassing the vesting schedule
-8. some unclaimable value can be recycled through explicit cleanup paths, depending on the distributor type
+8. burned 721 rewards can be materialized and recycled through explicit cleanup paths as they vest
 
 This repo does not explain why an allocation exists. It only defines how funded inventory is handed out.
 
-## Read These Files First
+## Read these files first
 
 1. `src/interfaces/IJBDistributor.sol`
 2. `src/JBDistributor.sol`
 3. `src/JBTokenDistributor.sol`
 4. `src/JB721Distributor.sol`
 
-## Integration Traps
+## Integration traps
 
 - distribution correctness depends on the distributor actually holding the assets it is expected to vest
-- ERC-20 and ERC-721 distributions share historical reward-round accounting, but claim authority differs:
-  token rewards are claimed by the encoded staker address, while 721 rewards are claimed by the current NFT owner
-- `CLAIM_DURATION` is fixed at deployment; `0` means reward rounds do not expire, otherwise all funding paths use the
-  same deadline measured from when the funded round first becomes claimable
-- `burnExpiredRewards` is permissionless and only recycles the unclaimed remainder; already-materialized vesting entries
-  remain claimable on their normal vesting curve
-- expired and forfeited rewards stay in distributor inventory and are recycled into the current reward round
+- ERC-20 and ERC-721 distributions share historical reward-round accounting, but their canonical beneficiaries differ:
+  token rewards belong to the encoded staker address, while 721 rewards belong to the current NFT owner
+- `beginVesting` is permissionless because no value leaves the distributor; `collectVestedRewards` is permissionless
+  only when paid to the canonical beneficiary, while an authorized holder can still choose any beneficiary
+- `CLAIM_DURATION` is fixed at deployment; `0` means reward rounds do not expire, while nonzero values set the window
+  after which unmaterialized reward inventory can be recycled
+- token distributors record `IJBActiveVotes.getPastTotalActiveVotes` at the funded round's snapshot block; only
+  addresses with `getPastVotes` at that block share the pot
+- 721 distributors record the hook checkpoint module's active total for all-tiers rewards, or the summed active totals
+  for a tier-scoped reward group; both modes cap each NFT claim by the snapshot owner's remaining active units for that
+  NFT's tier
+- `recycleExpiredRewards` is permissionless; it recycles the expired round's unmaterialized remainder while preserving
+  amounts that already started vesting
+- eligible expired and forfeited rewards stay in distributor inventory and are recycled into the current reward round
 - revnet loan-backed vesting is opt-in at deployment; the reward token must be a REVOwner-owned revnet token, the
   distributor keeps the loan NFT, and repayment restores the original vesting schedule instead of releasing all
   collateral immediately
@@ -75,26 +83,28 @@ This repo does not explain why an allocation exists. It only defines how funded
   stale collection lock and forfeit only the vesting rewards that were collateralized by that loan
 - distributors deployed with `VESTING_ROUNDS == 0` disable revnet vesting loans because rewards are immediately
   collectible instead of locked in a vesting position
-- `releaseForfeitedRewards` matters for 721 distributions; token-vote distributions do not have the same burned-token
-  forfeiture path
+- `releaseForfeitedRewards` matters for 721 distributions; it first materializes any unclaimed historical shares for
+  burned NFTs, then recycles only the amount unlocked by the vesting schedule. Token-vote distributions do not have the
+  same burned-token forfeiture path
 - reward, vesting, and loan accounting carries a `groupId`: `0` is the all-tiers group (the default pool), a non-zero
   group is `keccak256(abi.encode(tierIds))`. The tier overloads live on `JB721Distributor`; the base is tier-agnostic.
   Split funding via `processSplitWith` always lands in group 0 — a split cannot carry a tier set; tier-scoped pots
   require the explicit `fund(hook, tierIds, token, amount)` overload, and claims/collections must pass the same
   `tierIds` to hit that group
 - tier-scoped 721 pots weigh each eligible NFT by its tier's `votingUnits` against a summed
-  `getPastTierVotingUnits` denominator, which requires `@bananapus/721-hook-v6 >= 0.0.63` for that checkpoints API
+  `getPastTotalTierActiveVotes` denominator, then cap each numerator with `getPastAccountTierActiveVotes`; this
+  requires `@bananapus/721-hook-v6 >= 0.0.73` for the active-vote checkpoints API
 - 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
+## Where state lives
 
 - round and vesting state: `JBDistributor`
 - historical reward-round inputs: `JBRewardRoundData`
 - vesting schedule state: `JBVestingData`
 - asset-specific claim behavior: the concrete distributor
 
-## High-Signal Tests
+## High-signal tests
 
 1. `test/JBTokenDistributor.t.sol`
 2. `test/JB721Distributor.t.sol`
@@ -121,7 +131,7 @@ Useful scripts:
 - `npm run deploy:mainnets`
 - `npm run deploy:testnets`
 
-## Repository Layout
+## Repository layout
 
 ```text
 src/
@@ -136,15 +146,15 @@ script/
   Deploy.s.sol
 ```
 
-## Risks And Notes
+## 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
-- deployers that set a nonzero claim duration should choose a window long enough for expected claimants, because
-  expired unclaimed rewards can be recycled by anyone
+- token distributors require hooks that expose `IJBActiveVotes`; expiring token rounds recycle any unmaterialized
+  remainder after the deadline
 
-## For AI Agents
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/distributor-v6",
-  "version": "0.0.37",
+  "version": "0.0.42",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -24,12 +24,12 @@
     "deploy:testnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks testnets"
   },
   "dependencies": {
-    "@bananapus/721-hook-v6": "^0.0.65",
-    "@bananapus/core-v6": "^0.0.78",
-    "@bananapus/permission-ids-v6": "^0.0.28",
+    "@bananapus/721-hook-v6": "^0.0.73",
+    "@bananapus/core-v6": "^0.0.86",
+    "@bananapus/permission-ids-v6": "^0.0.30",
     "@openzeppelin/contracts": "5.6.1",
-    "@prb/math": "4.1.1",
-    "@rev-net/core-v6": "^0.0.84"
+    "@prb/math": "4.1.2",
+    "@rev-net/core-v6": "^0.0.89"
   },
   "devDependencies": {
     "@sphinx-labs/plugins": "0.33.3"

package/references/operations.md

@@ -5,10 +5,10 @@
 | 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 |
+| `JBTokenDistributor` checkpoint logic | Non-expiring rounds read `getPastVotes` and `getPastTotalSupply` at the intended snapshot block; active-voter rounds read `getPastVotes` and `getPastTotalActiveVotes` at the intended snapshot block |
 | `JB721Distributor` stake math | Minted, remaining, and burned supply still produce the intended tier-weighted total stake |
 | `processSplitWith` | Allowance-based `transferFrom` flow preserves actual received balances; split funding still records under `groupId == 0` only (a split cannot carry a tier set) |
-| `groupId` threading | The `groupId` dimension stays consistent across the reward (`rewardRoundOf`), vesting (`vestingDataOf`, `latestVestedIndexOf`, `nextClaimRoundOf`), and loan (`activeVestingLoanIdOf`, `JBVestingLoan`) maps; the `tierIds` overloads (`fund`/`beginVesting`/`collectVestedRewards`/`borrowAgainstVesting`/`burnExpiredRewards`/`releaseForfeitedRewards`) live on `JB721Distributor` and derive the group ID via `_groupIdFor`; the base is tier-agnostic and group 0 is the default all-tiers pool |
+| `groupId` threading | The `groupId` dimension stays consistent across the reward (`rewardRoundOf`), vesting (`vestingDataOf`, `latestVestedIndexOf`, `nextClaimRoundOf`), and loan (`activeVestingLoanIdOf`, `JBVestingLoan`) maps; the `tierIds` overloads (`fund`/`beginVesting`/`collectVestedRewards`/`borrowAgainstVesting`/`recycleExpiredRewards`/`releaseForfeitedRewards`) live on `JB721Distributor` and derive the group ID via `_groupIdFor`; the base is tier-agnostic and group 0 is the default all-tiers pool |
 | Deployment inputs | `DIRECTORY_ADDRESS`, `ROUND_DURATION`, and `VESTING_ROUNDS` match the intended chain and operator plan |
 
 ## Common failure modes
@@ -16,11 +16,11 @@
 | 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 |
+| Rewards appear stuck in the distributor | Supply was undelegated in a non-expiring token round, an active-voter token round had zero active votes and has not been recycled, 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 did not grant a sufficient ERC-20 allowance before calling `processSplitWith` |
 
-## Read Next
+## 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

@@ -12,7 +12,7 @@
 
 ### 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.
+The token distributor depends on checkpointed voting power at the reward round's snapshot block. Holders must delegate for `getPastVotes` to count them. Deployments with `CLAIM_DURATION == 0` use `getPastTotalSupply`, so undelegated supply can dilute claims; deployments with nonzero claim duration use `IJBActiveVotes.getPastTotalActiveVotes`, so undelegated balances such as AMM custody with no delegate do not share the pot.
 
 ### Funding path