Juicebox JBX Distributor

@bananapus/jbx-distributor-v6 distributes split-funded rewards to mainnet JBX stakers. Rewards are shared by JBX holders with nonzero delegated voting power at each reward round's snapshot block, then vest linearly before they are collected.

The package is intentionally narrow:

• projects submit rewards through Juicebox split hooks
• same-chain mainnet splits fund JBX reward rounds directly
• remote-chain project-token splits queue for a sucker bridge to mainnet
• mainnet sucker claims settle bridged project tokens into the same JBX reward ledger
• the admin sets the JBX staking token once, and cannot replace it

Documentation

• ARCHITECTURE.md - module overview, cross-chain flow, and trust boundaries.
• USER_JOURNEYS.md - end-to-end flows for projects, keepers, and JBX stakers.
• INVARIANTS.md - properties the reward ledger, vesting math, and bridge settlement must preserve.
• RISKS.md - operational and integration risks.
• ADMINISTRATION.md - deployment parameters and one-time admin action.
• SKILLS.md - quick index for routing tasks into the right sub-document.
• STYLE_GUIDE.md - Solidity and repo conventions used across the Juicebox V6 ecosystem.
• AUDIT_INSTRUCTIONS.md - audit framing, targets, and suggested hunting grounds.
• CHANGELOG.md - V5 to V6 migration changelog.
• references/operations.md - operator checklist.
• references/runtime.md - runtime behavior notes.

Contracts

| Contract | Role | | --- | --- | | JBXDistributor | Split hook, remote bridge queue, mainnet sucker settlement, and JBX reward specialization. | | JBDistributor | Shared round, vesting, collection, expiry, and optional Revnet vesting-loan accounting. | | IJBXDistributor | Integration interface for split-hook funding, bridge preparation, settlement, and JBX setup. |

Reward Model

Each funded round records:

• the accepted reward token and amount
• a snapshot block fixed at first funding for that round
• IJBActiveVotes.getPastTotalActiveVotes(snapshotBlock) as the denominator
• the configured claim deadline, if CLAIM_DURATION != 0

Recycling only moves inventory forward. If a keeper passes the current reward round to recycleExpiredRewards, the call is a no-op, including for zero-active rounds; those rounds can be recycled once a later round is current.

Claim helpers should bound how much history they scan. Rewards can remain claimable across many rounds, but a wallet or keeper should page through historical rounds instead of promising a single unbounded helper call.

Each staker's numerator is IVotes(JBX).getPastVotes(staker, snapshotBlock). The delegate address determines whether the holder has active voting power, but rewards belong to the encoded holder address. Helpers can begin vesting or collect to that canonical holder, so stakers do not need to submit every reward-cycle transaction themselves.

Cross-Chain Model

Remote chains do not distribute directly. A remote project's split sends that project's token to JBXDistributor on the remote chain. A keeper calls bridgeToMainnet, which prepares a sucker leaf with this distributor as the mainnet beneficiary and metadata identifying the origin chain and project. On mainnet, claimRemoteRewards authenticates the leaf against the origin project ID, then records the mainnet project's destination tokens as JBX rewards.

Direct ETH or token balances at the distributor are not rewards until an explicit same-chain funding, remote claim, or recycle path assigns them to a reward round.

Install

npm install @bananapus/jbx-distributor-v6

Development

npm install
forge test --deny notes --fail-fast --summary --detailed --skip "*/script/**"
forge fmt --check