Build on Juicebox.

1. Choose a project or revnet#

A Juicebox project accepts money, issues tokens, and follows rules its owner can change when those rules allow it. A revnet fixes its terms at launch; its operator keeps a smaller set of controls.

Project builders can launch with an AI assistant or the launch form, without code. App builders connect their product through the SDK and Juicebox Center. Contract builders add new behavior in Solidity.

• Learn how Juicebox works
• Building specifically with revnets

Back to contents ↑

2. Start with one working example#

Choose one result below. Each path explains the tools you need as you use them. The Learn glossary is there when you need a definition.

1. 1Launch a project: have an AI assistant prepare it, or fill in the launch form on a test network. Review the terms, then try a small payment and payout before using real funds.
2. 2Build an app: follow Your first test payment. Read a project, preview a payment, and check the result.
3. 3Write a contract: choose one behavior to add. Read the V6 contract reference, build it, and test against a local copy of the chain.

• Project builder path
• Your first test payment
• Contract builder path
• Plain-language glossary
• How fees work and share revnet tokens with payers

Back to contents ↑

3. Find the right contract#

Juicebox publishes every deployed contract by chain, with its address and the format used to call it, called an ABI. The SDK includes the same address map. A project can use its own contracts, so use JBDirectory to find the contracts currently managing its rules and payments before building a transaction.

SURFACE    what users call
           JBController, JBMultiTerminal, JBTerminalStore
CORE       protocol state
           JBProjects, JBDirectory, JBPermissions, JBTokens,
           JBRulesets, JBSplits, JBPrices, JBFundAccessLimits,
           JBFeelessAddresses
OMNICHAIN  links chains
           JBSucker, JBSuckerDeployer, JBSuckerRegistry

• Chains: Ethereum, Optimism, Base, and Arbitrum, plus their Sepolia test networks. Find the list in the SDK’s SUPPORTED_CHAINS and JB_CHAINS.
• Source: the V6 source is current. Older Juicebox versions are not interchangeable with it, and this site redirects unknown routes to the legacy app for those.

• Deployed addresses
• Core contract source
• Every V6 repository

Back to contents ↑

4. Find a contract call#

The contract call and SDK builder behind each action. Some actions need more than one transaction, such as approving a token before paying. Examples later in this guide use placeholders; replace them before use.

Store amounts as whole numbers in the token’s smallest unit, using bigint. Convert only for display. Identify each project by both chain ID and project ID. Linked projects share a group ID, called a sucker group, but keep separate addresses, balances, and rule IDs on each chain.

Back to contents ↑

5. Launch with an AI assistant#

For: Project builders

Describe the project to an assistant and let it do the setup. Connect it to the Juicebox MCP: it reads projects, models terms, pins your name and logo to IPFS once you approve the upload, and prepares the exact launch transaction for each chain. It holds no keys and signs nothing. You review the plan and sign in your wallet.

Or have the assistant write a .jb draft. Import it at the top of the launch form, check every section, and launch from there.

• Juicebox MCP
• Juicebox V6 skills
• Draft format

Back to contents ↑

6. Launch without code#

For: Project builders

The launch form covers Flavor, Look and feel, Rules or Stages when needed, Shop, and Launch. The simple flavor skips Rules and uses preset terms. Other projects can schedule new terms when their rules allow it. A revnet fixes its main financial terms at launch, while its operator keeps a limited set of controls.

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

Back to contents ↑

7. Choose the project’s rules#

For: Project builders

A group of project terms is called a ruleset. It can repeat on a schedule, with each repeat called a cycle. These are the settings in the launch form.

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

Back to contents ↑

8. What happens when you launch#

For: Project buildersApp builders

• Launch contract: the app uses REVDeployer.deployFor for revnets, JBOmnichainDeployer.launchProjectFor for linked chains, and JB721TiersHookProjectDeployer.launchProjectFor for other projects. These launchers set up the required extensions.
• Transaction value: read JBProjects.creationFee() right before each launch and pass that exact amount as value. Show it in the review before signing.
• One transaction per chain: sign each launch in order with the same wallet. The app keeps a shared value, called a salt, so linked bridge contracts get matching addresses.
• 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 ↑

9. Manage your project#

For: Project builders

The project page groups available management actions into tabs. Available actions depend on your account, project rules, and extensions.

• Queue ruleset flow
• Permission catalogue

Back to contents ↑

10. Use the Juicebox software library#

For: App builders

The Juicebox software library (SDK), @bananapus/nana-sdk-core, helps you read projects and prepare transactions. It includes addresses and contract call formats (ABIs). Import shared addresses, formats, and project details from the package root; import V6 reads and transaction builders from /v6.

A builder prepares a request without sending it: { chainId, address, abi, functionName, args, value }. Read with a public client and sign with a wallet client on the same chain.

• Start Your first test payment
• Download the tested read-project.mjs example
• Next: preview, simulate, and inspect a payment

The tutorial uses an existing project on the Base Sepolia test network. It includes the full working example, package versions, expected output, and help when a step fails.

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. One place for chain data, files, and indexed data#

For: App builders

Juicebox Center (juicebox.center) runs the shared services an app needs, so you hold no provider keys. Read any supported chain through its RPC, pin and read files on IPFS, query Bendystraw data through its API, and connect assistants through its MCP.

• Juicebox Center
• API directory

Back to contents ↑

12. 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 ↑

13. Search project data with Bendystraw#

For: App builders

Bendystraw gathers Juicebox chain records into a searchable database. This service, called an indexer, supplies project lists, activity, charts, and market positions through GraphQL queries.

Use it for fast browsing. Before signing, read balances, terms, spending approvals, and quotes directly from the chain again. The index can be a few blocks behind, so missing activity does not prove that a transaction failed.

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.
6. 6Do not send GraphQL text from a browser to an index you expose. Register each query on your server under an operation id and have the browser post { operation, variables } to a same-origin route that validates them. Keep heavy history and ranking queries server-only.
7. 7Pool reserves need no RPC: sum the indexed positions at the latest swap’s sqrtPriceX96. The jb-bendystraw skill has the recipe.

• Source reference

Back to contents ↑

14. Accept payments#

For: App builders

A payment goes to the project’s terminal, which issues tokens under the current ruleset. When a buyback hook finds more tokens in the pool, it buys there instead. Quote the terminal, compare any market route, then sign with a minimum token output, and tell the payer which route they take.

For an ERC-20, approve only the request’s address for only the amount; Permit2 is for direct pool swaps. Native payments carry the amount as value. A shop purchase is a payment with tier metadata: show every item and the token result in the review. addToBalanceOf adds funds without issuing tokens.

const quote = await previewPay(publicClient, {
  chainId, terminal, projectId, token, amount, beneficiary, metadata,
});
if (quote.beneficiaryTokenCount <= 0n) throw new Error("No token output; review the payment terms");

const tx = buildPayTx({
  chainId, terminal, projectId, token, amount, beneficiary, metadata,
  minReturnedTokens: slippageFloor(quote.beneficiaryTokenCount, 100n), // 1% tolerance
  memo,
});

// ERC-20: approve tx.address. Native: tx.value === amount.

• JBMultiTerminal.sol
• jb-pay-hook skill

Back to contents ↑

15. Cash out#

For: App builders

Holders exchange tokens for part of the surplus: the balance not scheduled for payouts. The cash out tax sets how much stays for remaining holders; 0% returns a proportional share, 100% turns cash outs off. The tokens are burned.

Quote with previewCashOutFrom, which runs the project’s data hook and any buyback decision; a surplus-only calculation can disagree with the real transaction. The route decides where the minimum goes: minTokensReclaimed on the terminal path, buyback metadata on the pool path. Re-quote after any change to rules, supply, balance, pool, or fees.

const prepared = await prepareHookAwareCashOut(publicClient, {
  chainId, terminal, holder, projectId, cashOutCount, tokenToReclaim,
  beneficiary,
});

const { route, transaction: tx } = prepared;
// Pool routes are re-previewed with their slippage metadata before return.

• Cash outs, with a worked example
• jb-cash-out-hook skill

Back to contents ↑

16. Move tokens across chains#

For: App builders

Linked projects move tokens through bridge contract pairs called suckers. A move has separate steps: prepare on the source chain, send through a bridge, then claim on the destination with a proof. A source receipt does not mean the destination tokens are ready.

Track each move’s source sucker, peer, token mapping, leaf index, beneficiary, proof, fees, and status, and keep queued, in transit, claimable, claimed, and failed distinct. CCIP and native bridges need different value and take different times; find the payable value by simulating the exact call. Accounting sync is separate: it updates the peer’s view of the balance without moving funds.

• nana-suckers-v6
• jb-suckers skill

Back to contents ↑

17. Connect wallets and request approval#

For: App builders

A wallet can send a transaction directly. A shared Safe wallet needs a proposal and approvals before execution. A group of approved calls can be sent across chains with one payment. Permit2 grants limited token spending for swaps. This site chooses the flow based on the connected account.

Chain reads go through Juicebox Center’s RPC. Connections include browser wallets, WalletConnect, Coinbase, and Safe. Para provides an embedded wallet and card purchases. A Safe’s L1 and L2 versions differ, so a Safe that controls a project on one chain may not exist at the same address on another; check before offering an action there.

• runAuthorityCalls
• Cross-chain execution
• Safe
• Cross-chain execution integration skill

Back to contents ↑

18. Save names, descriptions, and media#

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 ↑

19. Review, send, and confirm a transaction#

For: App builders

Use one request from preview through submission. Just before signing, refresh balances, limits, and permissions. Prepare the request, run a trial with the actual account, and show what it does and the minimum it will return. After sending, distinguish a rejected wallet request, a shared-wallet proposal, a pending transaction, and a confirmed success or failure.

The app checks that the encoded request still matches what the user reviewed. Its trial uses eth_call with a gas limit. A source check also verifies that every contract write uses one of the reviewed submission functions.

  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 ↑

20. 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 ↑

21. Manage tokens#

For: App buildersContract builders

Juicebox can track token balances itself; these balances are called credits. A project can also create a separate token contract using the ERC-20 standard. Holders can then move credits into that contract. Count both forms when showing a holder’s total balance.

• Source reference

Back to contents ↑

22. Send funds and reserved tokens#

For: App buildersContract builders

Payouts send funds to the project’s chosen recipients. Reserved tokens are new tokens set aside for other recipients. Anyone can normally trigger these distributions, but the ownerMustSendPayouts setting can restrict payouts to the owner or an operator with SEND_PAYOUTS permission.

sendPayoutsOf(
  projectId,
  token,
  amount,              // up to the payout limit
  currency,
  minTokensPaidOut     // minimum amount the recipient must receive
)
// Distributes to splits, leftover to project owner
// Review the final amount each recipient will receive

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

• Source reference

Back to contents ↑

23. Build with revnets#

A revnet uses the same payment, cash out, and bridge calls as any project, so everything above applies. The Revnet build guide covers what only revnets have: launching with REVDeployer.deployFor, stages, splits, loans, and the operator.

• Launch a revnet
• deployFor, field by field
• Loans
• Operator actions
• The whole Revnet build guide

Back to contents ↑

24. 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 ↑

25. Add custom behavior with hooks#

For: Contract builders

An extension can change a payment’s token output, send rewards, or check a rule change. These extensions are called hooks. Choose the interface for the moment when your code needs to run.

function afterPayRecordedWith(
  JBAfterPayRecordedContext calldata context
) external payable;

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

• Source reference

Back to contents ↑

26. Implement an extension#

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. Quote the amount the hook will actually receive. 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: a hook can call back into your contract before its first call finishes, called reentrancy. Protect your state updates and test each callback. A guard that blocks every nested call can break intended flows. 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 ↑

27. Fees, in detail#

For: Contract builders

The 2.5% fee applies to payouts, surplus allowance withdrawals, and cash outs with a tax above 0%. It is paid into the fee revnet, which returns its tokens to the fee recipient.

• Recipient: set a recipient for the fee payment to return tokens; a zero recipient gets none.
• Exempt: payments between projects on the same terminal, and addresses listed in JBFeelessAddresses. A transfer forwarded straight to a non-exempt extension is still charged.
• Fee-free surplus: a 0% tax cash out still pays the fee on funds that arrived through fee-free payouts, tracked as feeFreeSurplusOf.
• Held fees: with holdFees, payout and allowance fees wait 28 days. Returning funds with the return-held-fees option recovers a matching part. After the delay someone must process them. Cash out fees are never held.
• Failures: a failed direct fee payment credits the funds back to the source project. Through a router gateway, a failed fee route stays pending for retry or refund; a successful receipt does not mean it settled.
• Loans: revnet loan fees are covered in the Revnet build guide.

• JBMultiTerminal.sol
• JBFeelessAddresses.sol
• Revnet loan fees
• Fees in plain language

Back to contents ↑

28. Migration and price feeds#

For: Contract builders

When its rules allow it, a project can move to new contracts. JBDirectory.setControllerOf hands rules and tokens to a new controller; both controllers run checks before the handoff completes. JBMultiTerminal.migrateBalanceOf moves a balance to a terminal that accepts the same token. Neither check proves the new contract is trustworthy or keeps every old setting.

JBPrices converts currencies, for example to price terms in USD while accepting ETH. It uses a project-specific feed when one exists, otherwise the default, and can use a feed in reverse. A registered feed cannot be replaced; projects add their own when allowAddPriceFeed is set. With no usable feed the action reverts; a failed lookup is never a price of zero. Feeds that watch an L2 sequencer pause price-dependent actions during an outage and a recovery period after it.

• JBDirectory.sol
• JBPrices.sol

Back to contents ↑

29. Permissions#

For: Contract buildersApp builders

Give another address permission for a specific action with JBPermissions. Choose only the permissions it needs and the project they apply to. The contract stores each permission as one 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 ↑

30. Test against deployed contracts#

For: Contract builders

• TestBaseWorkflow

Back to contents ↑

31. Behavior to check carefully#

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", hook) decodes as (amountToSwapWith, minimumSwapAmountOut, skipSplits). Always encode all three; two-word quotes revert. Buyback 1.4.0 falls back to minting when the TWAP floor cannot be filled.
• Router gateway custody: resolve registry.terminalOf(projectId), then gateway.ROUTER() when the selected terminal is a gateway. Eligible failed fee routes remain held for retry, not paid or forgiven. Track QueuePendingCall, ProcessPendingCall, RecordTerminalCallFailure and RefundPendingCall; pendingCallCount is the lifetime count of issued IDs, not the number currently pending.
• Per-chain rollout and prices: use canonical executed deployment records, preserving previous and v1 addresses for history. Mainnet proposals do not activate the new stack. JBRatioPriceFeed supplies project-zero defaults for USDC→NATIVE and USDC→ETH; addresses vary by chain and OP Sepolia has the feed without hook/router/gateway.
• Payouts to a project without a terminal: if the recipient project has no payment contract for the asset, its payout fails and the balance is restored. The payout limit is still consumed.
• Ownership changes reset permissions: permissions must come from the current owner. A previous owner’s grants stop working after ownership transfers.
• 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 ↑

32. Sell collectibles and memberships#

For: Project buildersApp buildersContract builders

A project shop can sell uniquely identified tokens, called NFTs. Items are grouped into tiers with a price and supply. The JB721TiersHook extension delivers the selected items when a payment covers their price.

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 ↑

33. Buy existing tokens when they offer more#

For: App buildersContract builders

A payment can create new tokens or buy existing ones from a market. JBBuybackHook compares both and uses the configured Uniswap V4 pool when it gives the payer more tokens. It can also route cash outs.

To limit price changes during a swap, the hook uses an average price over time, called TWAP, to calculate its default minimum. Buyback 1.4.0 falls back to minting when the swap cannot meet that floor. Pay metadata under getId("pay", hook) must encode (amountToSwapWith, minimumSwapAmountOut, skipSplits); the third word is a bool, and a two-word quote reverts.

// 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 ↑

34. Accept payments in other assets#

For: App buildersContract builders

A router can convert a payment into an asset the project accepts. JBRouterTerminal finds a supported route, makes the conversion, and forwards the result to the project’s payment contract. It does not keep a project balance.

JBPayRouteResolver compares available routes by the tokens the payer would receive. A route may forward an accepted asset, swap through Uniswap V3 or V4, cash out other Juicebox tokens, or combine these steps. Availability depends on the project, asset, and market; check previewPayFor before offering the route.

Projects attach JBRouterTerminalRegistry to JBDirectory alongside JBMultiTerminal. Read terminalOf(projectId) to find the selected route: current deployments use JBRouterTerminalGateway → ROUTER(), while unmigrated projects can still select the previous router. The gateway takes custody before routing. Eligible failed fee routes remain pending for retry instead of being settled or forgiven; finalization can refund the source project after qualified failures. Use canonical deployment records per chain: a proposed mainnet deployment is not a live gateway.

• Source reference

Back to contents ↑

35. Create an address that forwards payments#

For: Project buildersContract builders

A payer address forwards incoming ETH to a project. Deploy JBProjectPayer as a small copy of a shared implementation, called a clone. Its constructor takes JBDirectory; set defaults through initialize() or setDefaultValues().

When defaultAddToBalance is false, incoming ETH calls pay() and delivers project tokens to the beneficiary. When true, it adds funds without creating tokens. With no chosen beneficiary, the contract finds the original payer, including through supported forwarding contracts. ERC-20 payments need an explicit pay() or addToBalanceOf() call after approval; sending those tokens directly will not trigger a payment.

// 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 ↑

36. Give a project a name#

For: Project buildersApp builders

A project can use a readable Ethereum Name Service (ENS) name. JBProjectHandles checks that the name’s record also points back to the project before returning it from handleOf().

Anyone can propose a name. The registry stores each proposal by its setter, chain ID, and project ID. Apps should also check that the project’s current owner or operator claimed the name.

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. handleOf 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 ↑

37. Share rewards over time#

For: Contract builders

A distributor shares reward tokens with eligible holders over time. Rewards unlock gradually, called vesting. Deploy this optional extension for your project; it is separate from the shared core contracts.

JBTokenDistributor supports tokens with IJBActiveVotes, such as Juicebox JBERC20. JB721Distributor supports NFT holders. Fund either through project distributions or direct deposits. Each round records the available rewards and holders’ eligible balances, then unlocks their shares evenly over the configured rounds.

• Source reference

Back to contents ↑

38. 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 zero-tax cash outs.
• Payouts: limits apply per chain and cycle; a recipient project without a payment contract can consume the limit without receiving funds.
• 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.

Test against a local copy of the current deployments. Publish the addresses, source, user actions, and schedule of terms so people can check how your product works. The audit page has prompts for reviewing a whole product or one transaction.

• Audit prompts and source index
• Reference web client

Back to contents ↑

39. Use this app as a reference#

Use Juicebox Money’s source to build your own product. Its Next.js app shows how to find projects, load details and media, and prepare transactions against the current V6 contracts.

Start with a flow close to yours, such as Pay, Cash Out, Create, or Shop. Read its source and tests to see how it checks current data, prepares a request, and shows what the user will sign.

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 assistant the relevant source, tests, guide link, V6 contracts, and Juicebox V6 skills library to help it explain anything Juicebox.
3. 3Use indexed data for browsing. Refresh the chain data the transaction depends on just before building and sending it.
4. 4Prepare one request and check that encoding and decoding preserves its fields. Test the behavior your product depends on before asking a wallet to sign.

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

Use the app to study the experience and its source to see how it works. The server helps with search, media, and request preparation. The wallet signs only after the action is shown and checked against the V6 contract format.

• Source reference

Back to contents ↑