kbarbel640-del Juicebox V5 Simplification Checklist
Before writing custom contracts, run through this checklist to find simpler solutions.
The Simplification Principle
Native mechanics > Off-the-shelf hooks > Custom hooks > Custom contracts
Every level of abstraction you can avoid:
- Reduces deployment costs
- Reduces attack surface
- Improves UI compatibility
- Makes the project easier to audit
Pre-Implementation Checklist
1. Do You Need a Custom Pay Hook?
| What You Want | Simpler Solution |
|---|---|
| Mint NFTs on payment | Use nana-721-hook-v5 directly |
| Buy tokens from DEX if cheaper | Use nana-buyback-hook-v5 directly |
| Restrict who can pay | Use off-chain allowlists or payment metadata |
| Different tokens per tier | Use 721 hook tiers with different prices |
| Cap individual payments | Consider if this is actually needed |
Only write a custom pay hook if: You need logic that modifies payment recording that no existing hook provides.
2. Do You Need a Custom Cash Out Hook?
| What You Want | Simpler Solution |
|---|---|
| Burn NFT to redeem | Use nana-721-hook-v5 - it already does this |
| Pro-rata redemption against surplus | Set cashOutTaxRate: 0 - native behavior |
| Partial redemption (bonding curve) | Set cashOutTaxRate to desired value |
| Time-locked redemptions | Use ruleset with pauseCashOut: true, queue future ruleset |
| Redemption against external pool | This might actually need a custom hook |
Only write a custom cash out hook if: Redemption value must come from somewhere other than project surplus.
3. Do You Need a Custom Split Hook?
| What You Want | Simpler Solution |
|---|---|
| Send to multiple addresses | Use multiple splits with direct beneficiaries |
| Send to another JB project | Set projectId in the split |
| Add to project balance instead of paying | Set preferAddToBalance: true |
| Restrict who can claim | Set beneficiary to a multisig/contract |
| Swap tokens before forwarding | Yes, need split hook |
| Add to LP position | Yes, need split hook |
Only write a custom split hook if: You need to transform tokens or interact with external protocols.
4. Do You Need Multiple Queued Rulesets?
| What You Want | Simpler Solution |
|---|---|
| Monthly distributions | One ruleset with duration: 30 days |
| Increasing/decreasing token issuance | Use weightCutPercent for automatic issuance cut |
| Different phases over time | Queue rulesets only for actual changes |
| Vesting over 12 months | One cycling ruleset, NOT 12 queued rulesets |
Only queue multiple rulesets if: Configuration actually changes between periods.
5. Do You Need Custom NFT Logic?
| What You Want | Simpler Solution |
|---|---|
| NFT minting on payment | Use nana-721-hook-v5 directly |
| Different prices per tier | Configure tiers in 721 hook |
| Static artwork per tier | Use encodedIPFSUri in tier config |
| Dynamic/generative art | Implement IJB721TokenUriResolver only |
| Composable/layered NFTs | Implement IJB721TokenUriResolver only |
| On-chain SVG | Implement IJB721TokenUriResolver only |
| Custom minting logic | This might need a custom hook |
Only write a custom pay/data hook if: You need to change how the 721 hook processes payments. For custom content, use the resolver interface.
Reference: banny-retail-v5 shows composable NFTs using only a custom resolver.
5b. When DO You Need to Extend 721-Hook?
Extending the 721-hook (not just resolver) is necessary when you need to change treasury mechanics, not just content:
| What You Want | Why You Need Custom Delegate |
|---|---|
| Dynamic cash out weights | Redemption value changes based on outcomes |
| First-owner tracking | Rewards go to original minter, not current holder |
| Phase-based restrictions | Different rules during different game phases |
| On-chain governance for outcomes | Scorecard voting determines payouts |
Reference: defifa-collection-deployer-v5 shows prediction games with dynamic weights.
6. Do You Need a Custom Contract at All?
| What You Want | Simpler Solution |
|---|---|
| Vesting | Payout limits + cycling rulesets |
| Treasury reserve | Surplus allowance |
| NFT-gated treasury | 721 hook + native cash outs |
| Immutable configuration | Transfer ownership to burn address |
| Multi-sig control | Set owner to Safe/multisig |
| Governance | Use existing governance frameworks |
Simplification Questions
Ask these questions in order. Stop at the first "yes":
For Payments
- Can the 721 hook handle this? → Use 721 hook
- Can the buyback hook handle this? → Use buyback hook
- Can payment metadata + off-chain logic handle this? → Use native pay
- → Consider custom pay hook
For Redemptions
- Is it just burning NFTs for surplus? → Use 721 hook
- Is it just tokens for surplus? → Use native cash out with tax rate
- Does value come from project surplus? → Use native cash out
- → Consider custom cash out hook
For Distributions
- Are recipients just addresses? → Use native splits
- Are recipients other JB projects? → Use splits with projectId
- Do you need token transformation? → Use split hook
- → Consider custom split hook
For Time-Based Logic
- Is it recurring at fixed intervals? → Use cycling ruleset
- Is it a one-time schedule change? → Queue one future ruleset
- Is it conditional on external events? → Consider approval hook
- → Consider custom logic
For NFT Content
- Is artwork static per tier? → Use encodedIPFSUri in tier config
- Need dynamic/generative art? → Implement IJB721TokenUriResolver
- Need composable NFTs? → Implement IJB721TokenUriResolver
- Need to change minting logic? → Consider wrapping 721 hook
For Games/Predictions
- Fixed redemption values per tier? → Use standard 721-hook
- Outcome determines payout distribution? → Extend 721-hook (Defifa pattern)
- Need on-chain outcome voting? → Add Governor contract
- Rewards to original minter only? → Track first-owner in delegate
Common Over-Engineering Mistakes
Mistake 1: Wrapping the 721 Hook
❌ WRONG: Create DataHookWrapper that delegates to 721 hook
✅ RIGHT: Use 721 hook directly, achieve goals via ruleset config
Mistake 2: Vesting Split Hook
❌ WRONG: VestingSplitHook that holds funds and releases over time
✅ RIGHT: Payout limits reset each cycle, achieving the same result
Mistake 3: Queue 12 Rulesets for 12-Month Vesting
❌ WRONG: Queue 12 identical rulesets with different start times
✅ RIGHT: One ruleset with duration: 30 days that cycles automatically
Mistake 4: Split Hook for Simple Forwarding
❌ WRONG: Split hook that just forwards ETH to an address
✅ RIGHT: Set the address as the split beneficiary directly
Mistake 5: Custom Redemption Math
❌ WRONG: Custom hook calculating pro-rata share of surplus
✅ RIGHT: cashOutTaxRate: 0 gives linear redemption natively
Mistake 6: Custom Hook for NFT Artwork
❌ WRONG: Write custom pay hook to generate dynamic NFT metadata
✅ RIGHT: Use 721 hook + custom IJB721TokenUriResolver for content only
Complexity Cost Table
| Solution | Gas Cost | Audit Risk | UI Support |
|---|---|---|---|
| Native config only | Lowest | Lowest | Full |
| Off-the-shelf hooks | Low | Low | Full |
| Custom token URI resolver | Low | Low | Full |
| Custom split hook | Medium | Medium | Partial |
| Custom pay hook | Medium | Medium | Partial |
| Extended 721-hook delegate | Medium-High | Medium-High | Custom UI needed |
| Custom cash out hook | High | High | Limited |
| Full custom system | Highest | Highest | None |
When Higher Complexity Is Justified
Not all complexity is bad. These patterns justify extending hooks:
| Pattern | Justification |
|---|---|
| Prediction games (Defifa) | Dynamic weights can't be done any other way |
| Composable NFTs (Banny) | Resolver-only keeps treasury mechanics standard |
| Phase-based games | Rulesets + custom delegate is cleaner than alternatives |
Key insight: Extend hooks for treasury mechanics, use resolvers for content only.
Final Checklist
Before finalizing your design, verify:
- No custom hook where a direct beneficiary works
- No split hook where multiple native splits work
- No wrapped data hook where using the hook directly works
- No multiple queued rulesets where one cycling ruleset works
- No custom vesting where payout limits work
- No custom treasury where surplus allowance works
- No custom redemption where native cash out works
- No custom pay hook where IJB721TokenUriResolver handles content needs
If all boxes are checked and you still need custom code, proceed with confidence that it's actually necessary.
Related Skills
/jb-patterns- Common design patterns with examples/jb-project- Project deployment/jb-pay-hook- When you DO need a custom pay hook/jb-cash-out-hook- When you DO need a custom cash out hook/jb-split-hook- When you DO need a custom split hook