Build on Juicebox.

1. Pick the model, and who this guide is for#

Juicebox gives you a project with a balance, programmable rules, and project tokens. Owners can change permitted terms subject to ruleset timing and approval. A revnet commits its core economic schedule at launch and retains a limited set of operator controls.

This guide has paths for three kinds of builder, with audience tags on the sections specific to each path. Project builders launch and run a project from this site without writing code. App builders connect a product to Juicebox with the SDK and the indexer. Contract builders extend the protocol with hooks and their own contracts. The parts overlap; read the tags and skip what is not yours.

• Learn how Juicebox works
• Building specifically with revnets

Back to contents ↑

2. Choose your first useful result#

You do not need to read this entire reference in order. Pick one result, follow its path, and return to the operation map when you need another feature. The Learn glossary explains terms such as ruleset, terminal, indexer, and SDK.

1. 1Launch a project without code: open the wizard, choose testnet, configure a small example, review the terms, and complete a test payment and payout before launching on mainnet.
2. 2Build an app: install the SDK, read a testnet project with the example below, then add indexed discovery and a quoted transaction flow.
3. 3Build a contract: inspect the V6 interfaces and deployed addresses, implement one hook or integration, and verify it against the local workflow and a pinned fork.

• Project builder path
• App builder quickstart
• Contract builder path
• Plain-language glossary

Back to contents ↑

3. Every operation, in one table#

Start with the user action, then identify its contract entrypoint. Some flows require multiple transactions, such as approving an ERC-20 before paying or claiming a cross-chain transfer. SDK helper names are listed where available; the call outlines below are reference shapes, with placeholders to replace before use.

Amounts are bigint in the token’s own decimals until the display boundary. A project’s identity is chain ID plus project ID; a sucker group links the chains but never makes their addresses, balances, or ruleset IDs interchangeable.

Back to contents ↑

4. The contracts, and where their addresses live#

Shared protocol deployments are listed by chain in deploy-all-v6 artifacts, including their address and ABI. The SDK’s address map follows those deployments. Project-specific tokens, hooks, terminals, and bridge instances can have their own addresses: resolve a project’s current controller and terminals through JBDirectory before composing a transaction.

• Chains: Ethereum, Optimism, Base, Arbitrum, plus Sepolia and the three L2 Sepolias. The SDK’s SUPPORTED_CHAINS and JB_CHAINS carry the list.
• Source: the repos ending in -v6 are current. Older Juicebox versions are not interchangeable with them, and this site redirects unknown routes to the legacy app for those.

• deploy-all-v6 (addresses)
• nana-core-v6
• Every V6 repo

Back to contents ↑

5. Launch from the wizard#

For: Project builders

The create page walks through five steps: Flavor, Look and feel, Rules (Stages for a revnet), Shop, Launch. The simple flavor skips Rules and launches with sensible defaults. Later rulesets can replace permitted project terms subject to the active timing and approval requirements. Revnet stage economics are committed at launch; metadata and other permitted operator controls remain editable.

• Open the wizard
• How the form becomes a launch call
• Draft format

Back to contents ↑

6. The rules, field by field#

For: Project builders

A ruleset defines project terms and can repeat across multiple cycles. These are the fields the wizard exposes, what they mean, and the units the contracts hold them in.

• Rules editor
• Rulesets, in the Learn guide
• jb-ruleset skill

Back to contents ↑

7. What happens when you launch#

For: Project buildersApp builders

• Which contract: a revnet goes through REVDeployer.deployFor; a linked multichain project through JBOmnichainDeployer.launchProjectFor, which also deploys the chain’s suckers; anything else through JB721TiersHookProjectDeployer.launchProjectFor, which sets up the shop as the data hook. This site never calls JBController.launchProjectFor directly.
• Creation fee: read from JBProjects.creationFee() right before each send and passed as the transaction value. JBProjects forwards it to the configured fee receiver; when routed as a project payment, token rewards go to the resolved fee payer.
• One transaction per chain: signed in sequence, with a shared salt kept in your session so a linked project gets matching sucker addresses. The same wallet must sign on every chain.
• Afterwards: each chain has its own project ID; the page lives at /<chain>:<id>. The Rulesets (or Terms) tab shows the terms as the contracts hold them.

• buildLaunchRequest
• jb-project skill
• jb-omnichain-ui skill

Back to contents ↑

8. Running it: the owner’s tabs#

For: Project builders

The project page groups available management actions into tabs. What you can use depends on the connected account, project rules, and installed extensions.

• Queue ruleset flow
• Permission catalogue

Back to contents ↑

9. The fees#

For: Project builders

The core protocol generally charges 2.5% on payouts, allowance withdrawals, and eligible cash out value. Exceptions depend on the route and fee-exempt addresses. Fees fund the Juicebox fee project, with its token rewards going to the operation’s designated beneficiary when processed as a payment. Network gas and extension or swap fees are separate.

• JBMultiTerminal.sol
• jb-protocol-fees skill

Back to contents ↑

10. Set up the SDK#

For: App builders

@bananapus/nana-sdk-core carries the ABIs, the addresses, the reads, and pure transaction builders. Do not hand-maintain selectors or addresses in product code. The root entry exports every ABI, jbContractAddress, the chain list, the bendystraw helpers, and project-metadata reads; the /v6 entry exports the reads and builders.

Builders are pure: validated input in, a { chainId, address, abi, functionName, args, value } request out. Keep reads on a public client for the target chain and writes on a wallet client connected to that same chain.

mkdir juicebox-starter
cd juicebox-starter
npm init -y
npm install @bananapus/nana-sdk-core viem

Create a V6 project on Base Sepolia with the wizard, or use a known V6 test project on that network. Its URL contains the project ID. Save this as read-project.mjs; it reads chain state and needs no wallet or private key.

import { createPublicClient, http } from "viem";
import { baseSepolia } from "@bananapus/nana-sdk-core/chains";
import { getCurrentRuleset } from "@bananapus/nana-sdk-core/v6";

const projectIdText = process.env.JB_PROJECT_ID;
if (!projectIdText || !/^[1-9][0-9]*$/.test(projectIdText)) {
  throw new Error("Set JB_PROJECT_ID to your Base Sepolia project ID.");
}

const client = createPublicClient({
  chain: baseSepolia,
  transport: http(process.env.BASE_SEPOLIA_RPC_URL),
});
const result = await getCurrentRuleset(client, {
  chainId: baseSepolia.id,
  projectId: BigInt(projectIdText),
});
if (result.ruleset.id === 0) {
  throw new Error("No active V6 ruleset: check the network and project ID.");
}
console.dir(result, { depth: null });

# Replace 123 with your Base Sepolia project ID.
JB_PROJECT_ID=123 node read-project.mjs
# Set BASE_SEPOLIA_RPC_URL as well to use your own RPC endpoint.

A successful read prints ruleset and metadata, including issuance, timing, and cash out settings. Compare them with the project’s Rulesets tab. If the RPC fails, retry through a configured endpoint; if the ID is wrong or no V6 ruleset is active, the example stops with an explanation.

import {
  buildPayTx, buildQueueRulesetsTx, buildRulesetConfiguration, buildRulesetMetadata,
  buildSetSplitGroupsTx, getCurrentRuleset, previewPay, slippageFloor,
} from "@bananapus/nana-sdk-core/v6";

import {
  getJBContractAddress, JBCoreContracts, jbMultiTerminalAbi, type JBChainId,
} from "@bananapus/nana-sdk-core";

const terminal = getJBContractAddress(JBCoreContracts.JBMultiTerminal, 6, chainId);

• V6 SDK package
• SDK source (repository name is historical; includes V6)
• Ruleset reader source
• Create a testnet project

Back to contents ↑

11. Read a project#

For: App builders

Use the index (next section) to find and display projects. Use the chain for anything a signature depends on, and read it again right before signing.

Back to contents ↑

12. Indexed data: Bendystraw#

For: App builders

Bendystraw is the Juicebox indexer: a Ponder service that watches every V6 contract on every supported chain and serves the results over GraphQL. It is how this site lists projects, draws activity feeds and price charts, ranks trending projects, and reads LP positions — none of which are practical to assemble from RPC calls at page-load speed.

Use it for anything a person reads. Use the chain for anything a wallet signs: re-read balances, rulesets, allowances, and quotes onchain right before building a transaction. The index can lag the chain by a few blocks, and a lagging index looks like empty data, not an error.

POST https://bendystraw.up.railway.app/graphql
{
  projects(where: { chainId: 8453, version: 6 }, orderBy: "balance", orderDirection: "desc", limit: 10) {
    items { projectId chainId name balance suckerGroupId }
    totalCount
  }
}

1. 1Every V6 row is versioned: filter with version: 6, and key a project by chainId + projectId, never projectId alone — the same number exists on every chain.
2. 2Numeric arguments on singular queries are Float!, not Int! (Ponder’s choice). Declare variables as Float! or the request fails validation with no data.
3. 3Lists page with limit and offset and return totalCount; loop until you have them all rather than trusting one page.
4. 4suckerGroupId is as-of-event: when chains are linked later, old event rows keep the group id they were written with. Query by every project in the group when you need the full history.
5. 5The SDK’s requestBendystraw(endpoint, query, variables) handles the POST, error surfacing, and endpoint normalisation; selectBendystrawEndpoint picks mainnet vs testnet from a chainId.

• Source reference

Back to contents ↑

13. Wallets, Safes, Relayr, and Permit2#

For: App builders

Four kinds of signing show up in a Juicebox app: a plain wallet write, a Safe proposal, a Relayr bundle for many chains at once, and a Permit2 signature for pool swaps. This site routes every owner action through one dispatcher that picks the path from who is connected.

RPC goes through Juicebox Center, an origin-allowlisted provider with no client-side key. Wallets connect through injected and EIP-6963 wallets, WalletConnect, Coinbase, the Safe App connector when framed, and an embedded Para wallet that also provides the card on-ramp.

• runAuthorityCalls
• Relayr
• Safe
• Relayr integration skill

Back to contents ↑

14. Metadata and IPFS#

For: App builders

• Shape: JBProjectMetadata: name, description, projectTagline, logoUri, coverImageUri, infoUri, payButton, payDisclosure, tags, twitter, telegram, discord, archived.
• Read: getProjectMetadata(publicClient, { jbControllerAddress, projectId }) resolves the project’s uri and fetches it; ipfsUri and cidFromIpfsUri handle the encoding.
• Pin: this site pins JSON, images (25 MB), and media (500 MB) straight from the browser to Juicebox Center, which is origin-allowlisted and guards against empty files. The gateway is juicebox.center/ipfs/.
• Write: the owner updates the pointer with JBController.setUriOf (SET_PROJECT_URI).

• Juicebox Center IPFS client

Back to contents ↑

15. One transaction boundary#

For: App builders

The request you quote, simulate, decode, show, and submit must be the same object, not five reconstructions of it. Right before signing, refresh the reads that set bounds and permissions, rebuild, simulate with the real account, then decode the calldata and present it. After submission, keep wallet rejection, Safe proposal, inclusion, revert, and confirmed success as separate states.

This site enforces it mechanically: the review step re-encodes the request after the user has seen it and aborts on any drift; simulation is a raw eth_call with a gas cap; a script fails the build if any write bypasses the three reviewed entry points, with the count of write sites pinned in a fixture.

  fresh reads
    → pure builder
      → simulateContract with the real account
        → encode and decode the calldata, show it to the user
          → writeContract
            → waitForTransactionReceipt
              → success only on receipt.status === "success"

• Review
• Every write builder
• Write-site inventory check

Back to contents ↑

16. Run this site locally#

For: App builders

Use the Node.js and npm versions declared in package.json. Copy the example public configuration before starting. NEXT_PUBLIC values are shipped to the browser, so they must never contain private keys or secrets.

git clone https://github.com/mejango/juicebox-money.git
cd juicebox-money
npm ci
cp .env.example .env.local
npm run dev

Open http://localhost:3001. Confirm the configured indexer, RPC service, wallet providers, and allowed origin work in your environment. Start with project reads, then connect a testnet wallet for transaction flows.

• Env: NEXT_PUBLIC_SITE_URL, NEXT_PUBLIC_BENDYSTRAW_URL, NEXT_PUBLIC_TESTNET_BENDYSTRAW_URL, NEXT_PUBLIC_PARA_API_KEY, NEXT_PUBLIC_PARA_ENV, NEXT_PUBLIC_VERSION; WalletConnect and the on-ramp provider are optional. No RPC or IPFS keys live in the client.
• Tests: the fixture-based browser suite isolates external services; use the documented fork and live-service checks separately when validating an integration.

• Repository
• TESTING.md

Back to contents ↑

17. Launch#

For: App buildersContract builders

Everything starts with JBController.launchProjectFor(). This single call:

1. 1Mints an ERC-721 project NFT to the owner address
2. 2Configures initial rulesets (payout limits, token weights, reserved percents, etc.)
3. 3Sets up terminal configurations (which tokens the project accepts)
4. 4Registers the project in JBDirectory

launchProjectFor(
  owner,                    // receives the project NFT
  projectUri,               // metadata (name, description, logo)
  rulesetConfigurations[],  // operational parameters
  terminalConfigurations[], // payment processing setup
  memo                      // transaction description
)
// Send exactly JBProjects.creationFee() as transaction value.

• Source reference

Back to contents ↑

18. Configure#

For: App buildersContract builders

After launch, inspect and understand your project’s configuration:

• Source reference

Back to contents ↑

19. Get funded#

For: App buildersContract builders

Once launched, anyone can contribute to the project through its configured terminals.

pay(
  projectId,
  token,              // which token to pay with
  amount,             // how much
  beneficiary,        // who receives the minted tokens
  minReturnedTokens,  // slippage protection
  memo,               // message attached to the payment
  metadata            // extra data for hooks
)
// Returns: number of tokens minted for the beneficiary

• Source reference

Back to contents ↑

20. Manage tokens#

For: App buildersContract builders

Tokens start as internal credits. Deploy an ERC-20 whenever you’re ready.

• Source reference

Back to contents ↑

21. Distribute#

For: App buildersContract builders

Projects distribute funds through payouts and reserved tokens. By default anyone can trigger distribution; the ownerMustSendPayouts ruleset flag restricts payouts to the owner or an operator with SEND_PAYOUTS permission.

sendPayoutsOf(
  projectId,
  token,
  amount,              // up to the payout limit
  currency,
  minTokensPaidOut     // slippage protection
)
// Distributes to splits, leftover to project owner
// 2.5% protocol fee on payouts, except same-terminal project payouts and eligible feeless recipients

sendReservedTokensToSplitsOf(projectId)
// Anyone can call this at any time
// Mints accumulated reserved tokens and distributes to splits

• Source reference

Back to contents ↑

22. Cash out#

For: App buildersContract builders

Token holders can cash out tokens against the project’s current surplus under its tax, hook, and fee settings. In a single accounting context, surplus is the terminal balance above the remaining payout limit. Read a hook-aware quote for the actual transaction.

At 0% cash out tax the core formula returns a proportional share before fees. Higher rates reduce the amount returned to a holder cashing out part of the supply; at 100% it returns zero. The tax is separate from protocol and hook fees.

cashOutTokensOf(
  holder,
  projectId,
  cashOutCount,         // how many tokens to burn
  tokenToReclaim,       // which token to receive
  minTokensReclaimed,   // slippage protection
  beneficiary,          // who receives the funds
  metadata
)

  For taxRate below MAX:
  reclaim = surplus × (cashOutCount / totalSupply)
         × [(MAX - taxRate) + taxRate × (cashOutCount / totalSupply)]
         ÷ MAX

  taxRate = 0%    → full proportional redemption
  taxRate = 100%  → returns zero (separate contract branch)

• Source reference

Back to contents ↑

23. Evolve#

For: App buildersContract builders

Projects evolve by queuing new rulesets. A timed ruleset changes at an eligible cycle boundary. A flexible ruleset can change without a cycle boundary, but any configured start time, notice, or approval still applies.

queueRulesetsOf(
  projectId,
  rulesetConfigurations[],  // new parameters
  memo
)
// If an approval hook is configured, it must approve
// the changes before they can activate.

• Source reference

Back to contents ↑

24. What’s a revnet?#

A revnet is a Juicebox project owned by REVOwner, which locks its staged economic parameters at launch. Its operator retains specific permissions: review these alongside the stage schedule.

The token is deployed as an ERC-20 at launch. Revenue can back cash outs under the configured terms. Fixed issuance rules do not guarantee revenue or fix the token’s market price.

Revnets use stages to describe their predetermined economic progression. Operator controls can still include split recipients, metadata, buyback settings, router selection, and configured NFT features.

  PROJECT
  • owned by a wallet or contract
  • owner can change rulesets
  • manual ERC-20 deploy
  • flexible governance
  • good for: DAOs, collectives

  REVNET
  • owned by REVOwner contract
  • stages locked at deploy
  • ERC-20 auto-deployed
  • fixed staged economics
  • good for: protocols, tokens

• Source reference

Back to contents ↑

25. Deploy a revnet#

For: App buildersContract builders

Deploy with REVDeployer.deployFor():

deployFor(
  revnetId,                        // project ID (or 0 for auto)
  configuration,                   // REVConfig with stages
  accountingContextsToAccept[],    // tokens the terminal should accept
  suckerDeploymentConfiguration,   // cross-chain setup
  tiered721HookConfiguration,      // optional NFT tiers
  allowedPosts[]                   // optional croptop posts
)
// New revnet (revnetId == 0): include the current project creation fee.
// Existing project ID: send no native value.

A revnet uses the same core payment and cash out entrypoints as other projects, with REVOwner applying its revnet terms and fee logic. Quote through the configured hooks and inspect the operator’s retained permissions.

• Source reference

Back to contents ↑

26. Stages#

For: App buildersContract builders

Stages are pre-programmed rulesets. A revnet might start with high token issuance (bootstrapping), then reduce over time (scarcity), and eventually reach a steady state.

Each stage can configure: token weight, weight decay, reserved splits, cash out tax rate, and more. Once deployed, stages progress automatically at their configured boundaries.

• Source reference

Back to contents ↑

27. Revnet fees#

Ordinary taxed revnet cash outs can incur both fees below. The revnet fee is skipped for zero-tax cash outs, feeless beneficiaries, or when the fee project has no compatible terminal.

1. 12.5% protocol fee — taken from the reclaimed value by JBMultiTerminal, sent to the Juicebox protocol’s project
2. 22.5% revnet fee — REVOwner allocates a share of the token count to the fee calculation and sends its associated reclaim value to the revnet fee project.

The protocol fee is based on reclaimed value. The revnet fee is calculated from a share of the token count; its recipient receives the associated reclaim value, not those project tokens. The rates have different bases, so do not simply subtract 5% from a core quote.

• Source reference

Back to contents ↑

28. Go deeper on revnets#

revnet.money carries the full revnet build guide: the wizard field by field, .jb drafts and agent launches, what deploy does, the operator’s nine permissions, loans from a contract, the extension points REVOwner allows and forbids, and the sharp edges. Use its linked source references to verify the configuration you plan to deploy.

• revnet.money/build
• revnet.money/learn

Back to contents ↑

29. Install the code and launch from Solidity#

For: Contract builders

The V6 repos ship as npm packages and import by package path; remappings.txt in every repo only maps forge-std, and node_modules resolves the rest. Solidity 0.8.28.

• JBController.sol
• JBRulesetMetadata.sol
• JBRulesets.sol
• jb-fund-access-limits skill

Back to contents ↑

30. Custom hooks#

For: Contract builders

Build custom logic that executes at key moments in the payment lifecycle. Hooks are the primary extension mechanism.

function afterPayRecordedWith(
  JBAfterPayRecordedContext calldata context
) external payable;

// context includes:
//   payer, projectId, rulesetId, amount,
//   forwardedAmount, weight, newlyIssuedTokenCount,
//   beneficiary, hookMetadata, payerMetadata

• Source reference

Back to contents ↑

31. Hook mechanics: funds, metadata, minting, reentrancy#

For: Contract builders

• Installing a data hook: set metadata.dataHook and useDataHookForPay / useDataHookForCashOut on the ruleset. beforePayRecordedWith returns the weight to use and pay hook specifications; beforeCashOutRecordedWith returns the tax rate, count, supply, surplus, and cash out hook specifications.
• Funds: native value arrives at a pay or cash out hook as msg.value; ERC-20 arrives as an allowance you must transferFrom during the call, revoked afterwards. Fee treatment depends on the operation and recipient; quote the net amount delivered to the hook. A specification with noop = true is informational and never called.
• Two metadatas: hookMetadata is authored by the data hook, while payerMetadata / cashOutMetadata comes from the caller. Trust hookMetadata only after authenticating the calling terminal and the expected hook path; validate caller-supplied fields.
• Metadata format: JBMetadataResolver: a reserved first word, then a table of 4-byte ids with word offsets, then 32-byte-aligned blobs. createMetadata(ids, datas), addToMetadata, getDataFor(id, metadata). Ids are getId(purpose, target) = bytes4(bytes20(target) ^ bytes20(keccak256(purpose))).
• Minting from a hook: JBController.mintTokensOf lets the terminal, the ruleset’s data hook, or any address the data hook’s hasMintPermissionFor approves mint without a grant; everyone else needs MINT_TOKENS (10) and allowOwnerMinting.
• Split hooks: a split whose hook field is set receives its share through processSplitWith. On the reserved-token path the controller approves an ERC-20 for the amount and burns whatever the hook leaves unspent; on payouts the terminal checks ERC-165 first.
• Reentrancy: pay and cashOutTokensOf call hooks after recording state. Review every callback and protect your own state transitions against reentrancy; a blanket guard on core-dependent flows can also break intended composition. Use override(ERC165, IERC165) for supportsInterface.

• IJBRulesetDataHook.sol
• JBMetadataResolver.sol
• jb-pay-hook skill
• jb-cash-out-hook skill
• jb-split-hook skill

Back to contents ↑

32. Permissions#

For: Contract buildersApp builders

Grant fine-grained access to other addresses with JBPermissions. Each permission is a bit in a 256-bit field.

setPermissionsFor(
  account,         // the address granting permission
  permissionsData  // { operator, projectId, permissionIds[] }
)
// projectId = 0 is the wildcard: every project `account` controls on this chain

• Source reference

Back to contents ↑

33. Test against the real thing#

For: Contract builders

• TestBaseWorkflow

Back to contents ↑

34. Sharp edges#

For: Contract buildersApp builders

• Who is the payer: context.payer is the terminal’s msg.sender. Through a router, project payer, or wrapper it is that contract, unless the contract exposes originalPayer() (IJBPayerTracker), which the router registry probes. Expose the original payer where the integration expects it, and set beneficiary/refund addresses explicitly so rewards or refunds are not accidentally credited to the intermediary.
• Router terminal cold start: the router registry reverts accountingContextForTokenOf for projects below its threshold; it is not universally accepting. Probe with previewPayFor before assuming a route.
• Buyback metadata is three words: the pay metadata under getId("pay") for the buyback hook decodes as (amountToSwapWith, minimumSwapAmountOut, skipSplits). Always encode all three.
• Payouts to a project without a terminal: a payout split to a project that has no terminal for the token is caught, the balance is restored, and no fee is taken, but the payout limit is still consumed.
• Permissions die with the NFT: every check asks whether the current owner granted the permission; grants by a previous owner stop authorizing anything when the project NFT moves.
• Held fees: a failed processHeldFeesOf forgives the fee. Cash out fees are never held.
• Sucker salt: the omnichain deployer derives sucker addresses from the sender and the salt, so a different wallet on another chain produces a project that cannot be linked.

• jb-terminal-selection skill
• Buyback hook integration reference
• jb-suckers skill

Back to contents ↑

35. NFT tiers#

For: Project buildersApp buildersContract builders

Deploy tiered NFTs as pay hooks using JB721TiersHook. Payers pick tiers in the pay metadata and receive the NFTs their payment covers.

launchProjectFor(
  owner,
  deployTiersHookConfig,    // NFT name, symbol, tiers[]
  launchProjectConfig,      // standard project config
  controller,
  salt                      // CREATE2 salt for a deterministic hook address (0 for none)
)
// Always use this deployer, even with empty tiers

• Source reference

Back to contents ↑

36. Buyback hook#

For: App buildersContract builders

JBBuybackHook compares the mint price against a Uniswap V4 pool price and routes payments (and cash outs) to whichever gives better value. Slippage tolerance defaults to a TWAP-based sigmoid; a payer can override it with a quote and minimum in the pay metadata.

// Set up the buyback hook with a Uniswap V4 pool
JBBuybackHook.setPoolFor(
  projectId,
  fee,              // Uniswap pool fee tier
  tickSpacing,      // pool tick spacing
  twapWindow,       // TWAP observation window (seconds)
  terminalToken     // the terminal token to route
)
// The pool key is once-only; the TWAP window stays mutable via setTwapWindowOf
// Requires SET_BUYBACK_POOL permission

  payment arrives
     │
     ▼
  query TWAP oracle for market price
     │
     ├─ pool gives more tokens than minting
     │  └─▶ swap on Uniswap V4, mint any unswapped remainder
     │
     └─ minting gives equal or more tokens
        └─▶ normal mint flow (weight × amount)

• Source reference

Back to contents ↑

37. Router terminal#

For: App buildersContract builders

JBRouterTerminal is a universal payment terminal: it accepts any token and automatically converts it into whatever token the destination project accepts, then forwards the result to that project’s primary terminal. It’s a pass-through — it never holds a balance.

There is no fixed output token. For each payment, a JBPayRouteResolver evaluates every token the destination project accepts and picks the route that yields the most project tokens for the payer — choosing among direct forwarding, a Uniswap V3 or V4 swap, a recursive cash out of JB tokens, or a combination. Pools and routes are discovered automatically, not configured per project.

The router is reached through JBRouterTerminalRegistry, which is what a project adds to JBDirectory alongside JBMultiTerminal; the registry resolves to JBRouterTerminal. Routing is internal (JBPayRouteResolver) — there is no per-project pool configuration.

• Source reference

Back to contents ↑

38. Payer address#

For: Project buildersContract builders

A JBProjectPayer address is deployed as a minimal proxy (clone). The constructor takes only a JBDirectory address. After deployment, defaults are set via initialize() or setDefaultValues().

The receive path accepts the native token (ETH) only. When defaultAddToBalance is false, incoming native ETH triggers pay() — minting tokens for the beneficiary. When true, funds are added via addToBalanceOf() without minting. With no explicit or default beneficiary, the contract resolves the original payer, including supported upstream payer trackers. ERC-20 payments must call pay() or addToBalanceOf() after approval; direct ERC-20 transfers do not trigger either path.

// Set via initialize() after clone deployment:
defaultProjectId       // which project to forward to
defaultBeneficiary     // who gets the tokens (0 = msg.sender)
defaultMemo            // attached to each payment
defaultMetadata        // extra data for hooks
defaultAddToBalance    // false = pay(), true = addToBalance()

// Anyone sends ETH to the payer address:
//   → receive() fires
//   → looks up DIRECTORY.primaryTerminalOf(projectId, token)
//   → calls pay() or addToBalanceOf() with defaults

• Source reference

Back to contents ↑

39. Project handles#

For: Project buildersApp builders

JBProjectHandles maps ENS names to Juicebox project IDs using bidirectional verification. Anyone can propose a handle, but only verified ones (where the ENS text record matches) are returned by handleOf().

All functions take a chainId parameter — handles are chain-aware. Storage is keyed by the setter address, so multiple addresses can propose different handles for the same project.

Name parts are in reverse order. handleOf returns the dot-joined labels without a .eth suffix; the suffix is only added when computing the namehash for verification. `_formatHandle` (JBProjectHandles.sol:220-232) walks the array from the LAST element to the first, so the innermost label goes last. For "myproject.eth" → ["myproject"]. For "sub.myproject.eth" → ["myproject", "sub"]. Parts cannot contain dots, ASCII control characters, DEL, "eth", or be empty. Unicode normalization (ENSIP-15) is the caller/client’s responsibility, not the contract’s.

• Source reference

Back to contents ↑

40. Distributor#

For: Contract builders

JBDistributor is an optional, project-deployed add-on (not part of the core protocol deployment). It distributes ERC-20 rewards to stakers in time-based rounds with linear vesting. Two implementations exist: JBTokenDistributor (for IJBActiveVotes token holders, e.g. a Juicebox JBERC20) and JB721Distributor (for NFT holders).

The distributor is funded via split hooks or direct deposits. Each round, a snapshot captures the distributable balance. Stakers claim their pro-rata share, which vests linearly over a configured number of rounds.

• Source reference

Back to contents ↑

41. Test what can surprise you#

• Launch: the encoded configuration round-trips through the ABI; the creation fee is read at send time; the same sender and salt yield the same sucker addresses on a second chain.
• Payments: the chosen route’s executable minimum is no worse than the alternatives shown; an empty pool falls back to issuance; a router route is probed, not assumed.
• Cash outs: the terminal or hook enforces the same minimum the confirmation shows, including at 0% fee-free surplus.
• Payouts: limits are per chain and per cycle; a recipient project without a terminal consumes the limit without paying; fees are held or not as the ruleset says.
• Rulesets: a queue with too little notice fails its approval hook; an inherited weight is decayed, not copied.
• Permissions: the narrowest ID is granted, scoped to the project; a Safe proposal is not success.
• Hooks: reentrancy from a hostile hook or token, an under-pulling split hook, hostile payer metadata.

Fork-test against the current deployments. Then publish the addresses, source, transaction map, and a human-readable ruleset schedule so users can check your product against the contracts themselves. The audit page has prompts for a whole-system review and for a single transaction.

• Audit prompts and source index
• Reference web client

Back to contents ↑

42. Build from this client#

Juicebox Money is a production V6 client you can study, fork, or use as a reference for your own product. Its Next.js interface combines server-assisted indexing and IPFS services with wallet flows that build and verify Juicebox transactions from the current V6 contracts.

Treat each working flow as an implementation example, not a black box. The project, account, shop, and create surfaces show how product interactions map to indexed reads, fresh onchain checks, transaction builders, ABI round trips, and clear signing previews. Give the relevant source and tests to your coding agent when you want to reuse one of those patterns.

1. 1Start from the product flow closest to yours — such as Pay, Cash Out, project creation, ruleset editing, or the Shop — and identify its component, supporting reads, and transaction builder.
2. 2Give your coding agent that source, its tests, this guide’s deep link, the current V6 contract repository below, and the Juicebox V6 skills library (github.com/mejango/juicebox-skills) — a Claude Code plugin whose skills carry the addresses, ABIs, fee math, and transaction-safety rules so the agent does not reconstruct them from memory.
3. 3Keep indexed data for fast discovery and display, but re-read signing-critical state onchain immediately before building and submitting a transaction.
4. 4Reuse the pure transaction-builder and ABI round-trip pattern, then add product-specific invariants and browser tests before asking a wallet to sign.

• Juicebox Money’s repo (source + tests)
• V6 contracts (version-6)

Use the app as a product reference and the repository as the implementation reference. Server routes improve indexing, search, media, and transaction preparation; signing remains explicit, and each wallet-bound action is decoded and checked against the V6 ABI before submission.

• Source reference

Back to contents ↑