Learn Juicebox.

1. What is Juicebox?#

Juicebox lets people collect and manage funds together. A project accepts blockchain payments, can issue its own tokens, and sends funds to recipients under rules that anyone can inspect.

A project token records participation. It can let its holder exchange tokens for part of the project’s available funds, called a cash out. Voting, membership, and other benefits depend on what the project has actually set up; receiving a token does not automatically give you those benefits or ownership of the project.

You can explore projects and read their terms without connecting a wallet. To pay or launch, connect a wallet on a supported network and keep enough of that network’s native token, such as ETH, to pay the transaction fee (gas). The payment form shows which tokens and routes that project currently accepts.

• Explore projects
• What to check before paying
• Launch a project without code
• Protocol user journeys

Back to contents ↑

2. How it works#

A payment adds funds and may issue project tokens. Payouts send project funds to configured recipients. A cash out exchanges project tokens for funds under the current rules. These actions happen when someone submits a transaction; a payout schedule does not send money by itself.

  1. Someone PAYS into a project
     └─▶ They may receive project tokens

  2. The project DISTRIBUTES payouts
     └─▶ To team members, partners, other projects

  3. Token holders can CASH OUT
     └─▶ Burn tokens, reclaim a share of what’s left

  surplus = balance above the remaining payout limit
  cash out = a share of surplus, adjusted by the rules and fees

The project owner configures payout limits, token issuance, and cash out terms. A ruleset is a scheduled set of these terms. Owners may queue later rulesets, subject to the current duration, permissions, and any required notice or approval.

Optional extensions, called hooks, can change how a payment or cash out works. For example, a shop can issue an NFT, and a buyback hook can buy existing project tokens from a trading pool.

Paying a project and adding to its balance are different actions. A payment may issue project tokens or shop rewards; adding to balance funds the project without issuing project tokens. Transaction fees paid to the network are separate from Juicebox’s protocol fees.

Back to contents ↑

3. Before your first payment#

Start with a project you recognize. Its payment form and current terms are the place to check what this particular payment will do.

1. 1Confirm the project, network, and payment token. A multichain project has different balances on each network; verify that the route and destination match your intent.
2. 2Open Rulesets (or Terms for a revnet). Check current and upcoming issuance, the reserved-token share, payout limits, surplus allowance, cash out tax, and any delay before cash outs are available.
3. 3Check who owns or operates the project and which controls remain. Read its description, payment notice, and any shop item terms to understand what the tokens or NFTs provide.
4. 4Enter an amount and review the tokens or items you will receive, the minimum output, any swap, and network fees. Keep enough native currency for gas. An ERC-20 payment may first require an approval transaction.
5. 5Review the wallet request, submit it, and wait for confirmation. If it fails or remains pending, check the transaction status before submitting again. Your activity and balance should update after confirmation.

• Find a project
• Understand cash out value

Back to contents ↑

4. Projects#

A Juicebox project has an onchain balance and programmable rules. It also has a project NFT: the wallet or contract holding that NFT is the owner. This ownership NFT is separate from the project tokens that supporters receive.

The owner’s powers depend on the current ruleset and permissions. They may include queuing new terms, choosing payout recipients, minting more tokens, or changing extensions. Read both the active and upcoming terms to see what the owner can change and when.

Projects can hold ETH and configured ERC-20 tokens, such as stablecoins. A router can convert other supported payment tokens. Multichain projects have a separate project ID and balance on each network, linked by bridge contracts.

  ┌───────────────────────────────────────────────┐
  │  YOUR PROJECT                                  │
  │                                                │
  │  accepts payments ──▶ issues tokens            │
  │  holds funds      ──▶ distributes payouts      │
  │  tracks surplus   ──▶ enables cash outs        │
  │                                                │
  │  rules set by owner, enforced by protocol      │
  └───────────────────────────────────────────────┘

• How rules can change
• Owners and delegated permissions
• Protocol ownership and administration

Back to contents ↑

5. Revnets#

A revnet (revenue network) is a Juicebox project whose core economic schedule is committed at launch. Its stages define token issuance, issuance cuts, cash out tax rates, and stage timing. A contract called REVOwner holds the project NFT and restricts changes to that schedule.

A stage can reduce how many tokens a payment receives over time. This fixes the issuance schedule; it does not fix a market price, guarantee future revenue, or guarantee what a token will return in a cash out.

Revnets still have an operator with limited powers, such as updating metadata, directing reserved-token recipients, and managing permitted extensions. The revnet’s terms and enabled extensions show which controls remain.

  PROJECT                         REVNET
  owner may queue new terms       core stage schedule committed at launch
  powers depend on rules          limited operator powers remain
  flexible project management     predictable issuance and cash out rules

Projects and revnets share Juicebox’s payment and cash out infrastructure. A revnet also supports loans against project tokens. Read the dedicated guide for stages, fees, operator controls, and loan repayment.

• Learn about revnets
• REVOwner: permitted operations

Back to contents ↑

6. Rulesets#

A ruleset defines a project’s terms: token issuance, payout limits, cash out tax, and owner powers. The Rulesets tab shows the active ruleset and what is scheduled next.

A ruleset with a nonzero duration repeats until an eligible replacement takes over. An optional issuance cut reduces the tokens issued per unit paid on each repeat. A duration of zero is flexible: it has no repeating cycle and continues until replaced.

For a timed ruleset, replacements start at an eligible cycle boundary. A flexible ruleset can be replaced without waiting for a cycle boundary, but any configured notice or approval still applies. Queuing a ruleset does not mean it is active yet.

  queue ruleset    approval hook     cycle boundary
       │              checks              │
       ▼                │                  ▼
   QUEUED ──────▶ APPROVED ──────▶ ACTIVE ──cycles──▶ ACTIVE...
       │                                   ▲
       └── if no approval hook ────────────┘

• Configure each ruleset field
• Ruleset scheduling source

Back to contents ↑

7. Tokens#

A payment can issue project tokens according to the ruleset’s issuance rate. For example, a rate of 500 tokens per ETH creates 1,000 tokens for a 2 ETH payment before the reserved share. A zero issuance rate creates no tokens; a buyback route may deliver existing tokens instead.

The reserved percentage sends part of a new issuance to designated recipients. With a 20% reserve, the payer receives 80% and the reserved recipients are allocated 20%. Reserved balances may need a later transaction to distribute them.

Tokens can be held as internal credits or as an ERC-20 token, a standard wallet-transferable token. Both count toward Juicebox balances and supply. Once the project has an ERC-20, a holder can claim their credits as that token without creating an additional economic balance.

  payment: 2 ETH
  weight:  500 tokens per ETH
  reserved: 20%

  total minted = 1,000 tokens
       │
  ┌────┴─────────────────┐
  │                      │
  ▼                      ▼
  800 tokens          200 tokens
  (to payer)          (to team splits)

• Cash out value and a worked example
• Credits and ERC-20 accounting

Back to contents ↑

8. Cash outs: what you can receive#

Cashing out burns project tokens in exchange for the currently available surplus under the project’s rules. It is not a refund of the original payment. No surplus, a disabled cash out, or an unfinished delay can mean there is nothing available to receive.

For the standard core calculation, let S be surplus, x your fraction of the total token supply, and t the cash out tax written as a fraction. The amount before protocol fees is S × x × (1 − t + t × x). At a 100% tax, the contract returns zero. A data hook can change the inputs or route.

The cash out tax leaves more funds for the remaining token supply. It is a curve parameter, so a 30% setting is not simply a flat 30% deduction from every holder’s proportional share. Payouts, new payments, minting, other cash outs, and changing terms can all change your next quote.

1. 1Open the project’s cash out action on the network where you hold tokens.
2. 2Enter the token amount and check the available surplus, tax, fees, recipient, and minimum output. Credits and ERC-20 balances may both count toward your holding.
3. 3Submit the reviewed transaction and wait for confirmation. A market-sale route and a protocol cash out can produce different settlement and fee behavior.

• Cash out formula in the core contract
• Understand protocol and extension fees
• Integrate a cash out

Back to contents ↑

9. Splits & payouts#

Splits direct percentages of payouts or reserved project tokens to a wallet, another project, or a custom contract. A recipient list describes where a distribution goes; someone must still submit the transaction that sends it.

A payout limit caps distributions per ruleset cycle, accounting token, terminal, and chain. Surplus is the balance above the unused payout limit, after currency conversion where needed. Cash outs draw on that surplus. An enabled surplus allowance can also let the owner withdraw from it.

A split locked until a future date must be preserved until its lock expires. Owners can extend its lock and add other splits within the remaining percentage. Inspect locked recipients, payout limits, and allowances together to understand how much money can leave a project.

  project balance
       │
  ┌────┴──────────────────────┐
  │                           │
  ▼                           ▼
  payout limit             surplus
  (distributed to splits)  (available for cash outs)

• Send payouts and manage funds
• Payout limits and allowances
• Locked split rules

Back to contents ↑

10. Fees#

A normal payment into a project has no core Juicebox protocol fee. Network gas, token swaps, shops, or other extensions may add costs. Launching a project also has a configurable creation fee, at most 0.001 ETH per chain, plus gas.

The core protocol generally charges 2.5% on payouts and surplus-allowance withdrawals. Transfers within the same terminal and eligible fee-exempt recipients are exceptions. Fees fund the Juicebox fee project; token rewards go to the operation’s designated beneficiary when the fee is processed as a payment.

Cash outs with a tax rate above 0% generally incur a 2.5% protocol fee on the reclaimed amount. With a 0% tax, the fee applies only to the portion that arrived through certain fee-exempt project transfers, tracked as feeFreeSurplusOf. A zero cash out tax therefore does not always mean a zero protocol fee. Revnet or other extension fees are additional.

With holdFees enabled, eligible payout and allowance fees are held for 28 days. Adding funds back with the return-held-fees option can return a matching portion. Once the holding period ends, a transaction must process the fees; the passage of time alone does not send them. Cash out fees are never held.

  100 ETH payout
     └─▶ 2.5 ETH fee
     └─▶ 97.5 ETH distributed to splits

  if holdFees is on:  fee held 28 days, refundable
  if holdFees is off: fee processed immediately

• Fee details for project builders
• Fee charging and exceptions
• Creation fee cap

Back to contents ↑

11. Architecture#

Everything you’ve read about so far — projects, rulesets, tokens, splits, fees — each lives in its own smart contract. These contracts are organized in layers.

Surface contracts are what users interact with: the controller orchestrates project operations, and the terminal handles money in and out. Core contracts store the underlying data: who owns what, what the rules are, where funds go. Omnichain contracts move tokens and funds across blockchains.

┌──────────────────────────────────────────────────────────────┐
│  SURFACE — what users interact with                          │
│  JBController · JBMultiTerminal · JBTerminalStore            │
├──────────────────────────────────────────────────────────────┤
│  CORE — stores protocol state                                │
│  JBProjects · JBDirectory · JBPermissions · JBTokens         │
│  JBRulesets · JBSplits · JBPrices · JBFundAccessLimits       │
│  JBFeelessAddresses                                          │
├──────────────────────────────────────────────────────────────┤
│  OMNICHAIN — cross-chain connectivity                        │
│  JBSucker · JBSuckerDeployer · JBSuckerRegistry              │
└──────────────────────────────────────────────────────────────┘

• Architecture and accounting reference
• Contract roles and deployment addresses

Back to contents ↑

12. Hooks & extensions#

A "hook" is a custom contract that plugs into the protocol at a specific moment — like a callback. When a payment comes in, when tokens are cashed out, or when a ruleset changes, the protocol can call your hook to run custom logic.

Projects can add features like NFT rewards, automatic market buybacks, content publishing, and approval gates without modifying the core protocol. Hooks are optional and composable.

• Build a custom hook
• Data hook interface

Back to contents ↑

13. Projects across chains#

A project can run on multiple blockchains, such as Ethereum, Optimism, Base, and Arbitrum. Each chain has its own project ID, token contract, and balances. A linked project does not give every address or balance the same meaning on every chain.

Bridge contracts called suckers move project tokens together with a proportional share of backing funds. Native bridges and Chainlink CCIP provide different supported routes. A transfer involves preparation, bridge delivery, and a claim on the receiving chain; it is not instant.

Once a token mapping has been used for a bridge transfer, it cannot be remapped to a different remote token. It can be disabled. Available local liquidity, token mappings, bridge delivery, and the project’s configuration all affect whether a transfer can complete.

If a bridge is deprecated, a configured delay and emergency-exit process can let eligible holders reclaim funds locally. Recovery depends on the bridge’s state and the required transactions. Before moving tokens, check the route, destination, expected delay, and where you will claim them.

  Ethereum funds ◄──── sucker ────► Optimism funds
       │                                    │
       └── tokens bridged ──────────────────┘
           funds move proportionally

• Sucker bridge source
• Multichain integration details

Back to contents ↑

14. Price feeds#

Price feeds translate between the currency used to price a project’s terms and the token being paid or withdrawn. For example, a USD issuance rate can be used with an ETH payment if a usable ETH/USD feed is available.

A JBPrices feed registration cannot be overwritten once set. Projects can add project-specific feeds that take priority over protocol defaults, subject to the project’s rules and permissions. Inverse prices allow a feed in one direction to serve the other direction too.

JBPrices tries applicable project and default feeds and fails the dependent transaction when none provides a usable price. A reverted or zero-valued feed may fall through to another configured feed; it should not be displayed as a zero price.

Sequencer-aware feeds on supported L2 deployments also check whether the network’s sequencer is down or still within its recovery grace period. During those periods, transactions requiring that price can be unavailable.

• Price resolution source

Back to contents ↑

15. Permissions#

Owners can grant specific abilities to other addresses, such as queuing new rulesets or updating metadata, without transferring the project NFT. Some operations, including payouts when the rules permit it, can already be called by anyone.

Each ability has a permission ID. SEND_PAYOUTS is #5 and is required when the ownerMustSendPayouts ruleset flag restricts distributions. ROOT (#1) grants all Juicebox permissions in its scope; it still does not bypass the project’s rules.

Permissions are per-project. Granting someone access to project #5 doesn’t give them any access to project #6. Granting with project ID 0 is the wildcard: it applies to every project the GRANTING account controls on that chain — not to every project the operator touches.

• Grant a specific permission
• Permission checks

Back to contents ↑

16. NFT rewards#

A project’s shop can offer NFTs organized into tiers. Each tier has a price, supply, and category. Selecting an item adds tier-selection metadata to the payment; whether a payment mints an NFT also depends on that tier’s availability and the hook’s settings.

Tiers are grouped by category, and categories must be defined in ascending order. Each tier can also have governance weight (voting power per NFT), reserved NFTs that accrue to a reserve beneficiary as others are minted, and, if the tier allows it, owner minting without payment.

The NFT artwork and metadata can live on IPFS (a decentralized file system) or onchain. This system is powered by a pay hook called JB721TiersHook that automatically mints NFTs when payments come in.

• NFT tier hook source
• Configure NFT tiers

Back to contents ↑

17. Croptop#

Croptop adds content publishing to a project configured with its posting permissions. Posts become NFT tiers that supporters can collect; availability depends on the project’s posting rules.

The project owner sets rules for what can be posted: minimum price, supply limits, and optionally an allowlist of who can post. Within those rules, posting is open to everyone. Each post creates a new NFT tier, and supporters mint copies by paying into the project.

The publisher takes a 5% fee from the posting payment; the remainder is paid to the project. When an existing tier matches the post’s reuse conditions, it can be reused rather than creating a duplicate. Ordinary later purchases of a tier follow the shop’s payment path.

  someone publishes content + pays the mint price
     │
     ├─▶ content validated against project’s posting rules
     ├─▶ new NFT tier created for this content
     ├─▶ 5% fee to Croptop protocol
     └─▶ remaining payment → project funds
         └─▶ poster receives the first NFT

Croptop can be combined with projects or revnets. The configured posting rules decide who may publish and what price and supply limits their posts must follow.

• Croptop source

Back to contents ↑

18. Buyback hook#

A buyback hook can route a payment through a configured Uniswap V4 pool to buy existing project tokens when its quote is better than issuing new ones. Any unspent portion can follow the normal issuance path.

A usable pool, liquidity, price observations, and the supplied transaction limits determine which route is available. The hook compares supported routes; it does not search every market or guarantee the best price everywhere.

The hook can also route a cash out through a market sale when the supported pool offers a better result than the protocol cash out. An app should show the expected route and enforce the minimum amount the holder agreed to receive.

  incoming payment
     │
     ├─ market gives more tokens than minting?
     │  └─▶ swap on the trading pool
     │      └─▶ any leftover amount still minted normally
     │
     └─ minting gives equal or more tokens?
        └─▶ normal mint (no swap needed)

Slippage is the difference between a quote and the price when a transaction executes. The hook has automatic price bounds, and apps can supply explicit minimum outputs. Review the minimum you will receive: a quote is an estimate, while an enforced minimum can make the transaction revert if the result is too low.

• Buyback routing and minimum outputs
• Integrate the buyback hook

Back to contents ↑

19. Loans#

Eligible revnet token holders can borrow from the revnet using project tokens as collateral. While the loan is open, those tokens are burned. Repayment can restore them; they are not a spendable token balance during the loan.

The loan is represented by a transferable NFT that tracks the debt and collateral. The available amount depends on the revnet’s current cash out terms, available funds, source token, and any cash out delay.

Borrowing deducts the core protocol fee, a 1% REV fee when applicable, and a source-revnet prepaid fee selected between 2.5% and 50%. The minimum 2.5% is part of that selected prepaid fee, not an additional fee on top. A larger prepayment buys a longer period without an additional time-based source fee.

After the prepaid period, the repayment fee grows with time. Repay before the 10-year expiry to recover the applicable collateral. After expiry, anyone can clean up the expired loan and the collateral remains burned. Compare net proceeds, total repayment, and expiry with the cash out quote before choosing either action.

  borrow
     └─▶ your tokens are burned as collateral
     └─▶ funds sent to you from the project (minus fees)
     └─▶ you receive a loan NFT as your receipt

  repay (before 10-year expiry)
     └─▶ return the funds + any time-based fee
     └─▶ your collateral tokens are re-minted back to you

  liquidation (after 10 years)
     └─▶ loan written off — collateral stays burned
     └─▶ the borrowed funds are not automatically returned

A loan preserves the possibility of recovering tokens through repayment. It does not guarantee a better result than a cash out: fees, the repayment date, and the revnet’s current terms determine the comparison.

• Revnet loan walkthrough
• Loan fee and repayment source

Back to contents ↑

20. Migration#

A project can move to compatible controllers or terminals when its current rules and permissions allow it. A controller manages project rules and tokens; a terminal manages accepted funds and payments.

A controller migration runs a handoff between the old and new contracts. A terminal migration moves a balance to a terminal accepting the same token. Compatibility checks are part of the process, but they do not make an arbitrary replacement contract trustworthy or preserve every old accounting setting.

The owner or an authorized operator initiates migration. Changing controllers uses JBDirectory.setControllerOf; moving funds uses JBMultiTerminal.migrateBalanceOf. Check the destination contracts, accounting configuration, and any fee before authorizing the move.

  CONTROLLER
  1. JBDirectory.setControllerOf(newController)
  2. new controller runs its "before receive" check
  3. old controller hands its state over (migrate)
  4. new controller runs its "after receive" check

  TERMINAL
  1. JBMultiTerminal.migrateBalanceOf(to)
  2. balance moves to a terminal that accepts the same token
     (2.5% fee unless the new terminal is feeless)

The new controller checks the handoff on both sides, so a controller migration only completes if the receiver accepts it. Terminal migration is a plain balance move.

• Controller handoff
• Terminal balance migration

Back to contents ↑

21. Distributor#

A distributor is an optional extension for sharing funded rewards among eligible participants. It must be deployed, funded, and configured separately; holding a project token alone does not automatically create a reward stream.

Distributions run in rounds with snapshots and gradual vesting. Eligibility depends on the distributor: the ERC-20 version uses delegated voting-power checkpoints, while the NFT version uses qualifying NFT tiers. Check delegation and snapshot requirements before assuming a wallet is eligible.

Rewards unlock over configured rounds, and participants submit a claim to collect them. Check the distributor’s address, funded reward token, round schedule, vesting, and claim expiry.

  funds deposited into the distributor
     │
     ▼
  round starts → snapshot of eligible checkpoints
     │
     ▼
  participants begin vesting their share
     └─▶ share = your eligible weight / total eligible weight
     └─▶ rewards unlock gradually over time
     │
     ▼
  collect unlocked rewards as rounds pass

If an NFT is burned while rewards are still vesting, anyone can release the forfeited portion back into the current round — it doesn’t disappear. Unclaimed rounds do expire.

• Distributor eligibility and claims
• Deploy and integrate a distributor

Back to contents ↑

22. Project handles#

Instead of referring to projects by number ("project #47"), you can give yours a human-readable name like "myproject.eth" using ENS — the Ethereum Name Service, which works like a phonebook for blockchain addresses.

To set up a handle, you need two things: an ENS name you own, and a text record on that name pointing to your project. This two-way link proves that the name owner actually wants the association — anyone can propose a name for a project, but it only counts if the ENS name confirms it.

Multiple people can propose different names for the same project. Frontends (apps and websites) decide which proposer to trust. This open design means no single gatekeeper controls naming.

  1. own an ENS name (e.g. "myproject.eth")
  2. add a "juicebox" text record: "1:42"  (chain:project)
  3. register the name onchain for your project
  4. apps verify the ENS record matches
  5. your project now shows as "myproject.eth"

Subdomains work too, stored innermost-last: "sub.myproject.eth" is stored as ["myproject", "sub"] — the contract joins the parts in reverse and appends .eth, then verifies the result against the ENS registry.

• ENS handle registration
• Set a project handle

Back to contents ↑

23. Payer address#

A payer address is a dedicated native-token (ETH) deposit address for your project. Native ETH sent directly to it is automatically forwarded into your project — no extra steps for the sender. ERC-20 tokens sent directly to the address do not trigger a payment.

In payment mode, project tokens go to the configured beneficiary, or to the original payer when no beneficiary is set. In add-to-balance mode, funds enter the project without issuing project tokens. The payer address’s owner can change these defaults, including the destination project: verify its current settings before sending.

The payer address resolves the project’s current terminal, so compatible terminal migrations do not require a new deposit address. Direct ERC-20 transfers do not call its payment logic; integrations must use its explicit pay or addToBalanceOf function for those tokens.

  someone sends ETH to the payer address
     │
     ▼
  payer address looks up the project’s current terminal
     │
     ├─ default mode
     │  └─▶ pays the project → tokens for the configured beneficiary or payer
     │
     └─ "add to balance" mode
        └─▶ adds funds to balance → no tokens minted

This is especially useful for integrations. Any contract, wallet, or payment flow that can send ETH to an address can now fund your project — they don’t need to know anything about Juicebox.

• Payer address source
• Deploy a payer address

Back to contents ↑

24. Glossary and next steps#

Use these definitions when reading a project page or the developer guide.

• Explore projects
• Create a project
• Build an app or extension
• Inspect source and audit prompts
• Explore revnet economics

Back to contents ↑