jb-v5-api

Juicebox V5 API Reference

Function signatures, parameters, and return values for the entire Juicebox V5 protocol ecosystem.

Note: For deep implementation details, edge cases, and tradeoffs, use /jb-v5-impl instead.

Protocol Architecture Overview

The V5 protocol consists of interconnected repositories:

Repository	Purpose
nana-core-v5	Core infrastructure: projects, rulesets, tokens, terminals
nana-suckers-v5	Cross-chain token bridging via merkle proofs
nana-buyback-hook-v5	Uniswap V3 token buyback integration
nana-swap-terminal-v5	Accept any token, auto-swap to ETH
nana-721-hook-v5	Tiered NFT minting on payment
nana-permission-ids-v5	Permission ID constants
nana-ownable-v5	Juicebox-aware ownership pattern
nana-omnichain-deployers-v5	Multi-chain project deployment
revnet-core-v5	Autonomous tokenized treasury networks
croptop-core-v5	Public NFT posting and contribution

---

NANA-CORE-V5: Core Protocol

Contract Layers

Core Contracts (State Management):

• JBProjects - ERC-721 project ownership
• JBRulesets - Time-bounded configuration queuing
• JBTokens - Credit and ERC-20 accounting
• JBDirectory - Terminal and controller mapping
• JBPermissions - Access control delegation
• JBFundAccessLimits - Withdrawal constraints
• JBPrices - Currency price feeds
• JBSplits - Payment distribution lists

Surface Contracts (User Entry Points):

• JBController - Ruleset and token coordination
• JBMultiTerminal - Payments, cash outs, distributions
• JBTerminalStore - Transaction bookkeeping

Utility Contracts:

• JBDeadline - Ruleset approval with advance notice
• JBERC20 - Standard project token
• JBFeelessAddresses - Fee exemption registry
• JBChainlinkV3PriceFeed - Chainlink integration

---

JBController Functions

Project Lifecycle

// Create a new project with initial rulesets
function launchProjectFor(
    address owner,                              // Receives project NFT
    string calldata projectUri,                 // IPFS metadata URI
    JBRulesetConfig[] calldata rulesetConfigurations,
    JBTerminalConfig[] calldata terminalConfigurations,
    string calldata memo
) external returns (uint256 projectId);

// Queue rulesets for existing project (first time setup)
function launchRulesetsFor(
    uint256 projectId,
    JBRulesetConfig[] calldata rulesetConfigurations,
    JBTerminalConfig[] calldata terminalConfigurations,
    string calldata memo
) external returns (uint256 rulesetId);

// Add rulesets to end of queue
function queueRulesetsOf(
    uint256 projectId,
    JBRulesetConfig[] calldata rulesetConfigurations,
    string calldata memo
) external returns (uint256 rulesetId);

// Migrate to a different controller
function migrate(uint256 projectId, IERC165 to) external;

Token Operations

// Mint tokens to beneficiary
function mintTokensOf(
    uint256 projectId,
    uint256 tokenCount,
    address beneficiary,
    string calldata memo,
    bool useReservedPercent    // Apply reserved rate?
) external returns (uint256 beneficiaryTokenCount);

// Burn tokens from holder
function burnTokensOf(
    address holder,
    uint256 projectId,
    uint256 tokenCount,
    string calldata memo
) external;

// Deploy ERC-20 for project (enables token claiming)
function deployERC20For(
    uint256 projectId,
    string calldata name,
    string calldata symbol,
    bytes32 salt              // For deterministic address
) external returns (IJBToken token);

// Convert credits to ERC-20 tokens
function claimTokensFor(
    address holder,
    uint256 projectId,
    uint256 tokenCount,
    address beneficiary
) external;

// Transfer credits between addresses
function transferCreditsFrom(
    address holder,
    uint256 projectId,
    address recipient,
    uint256 creditCount
) external;

// Distribute pending reserved tokens
function sendReservedTokensToSplitsOf(uint256 projectId)
    external returns (uint256);

Configuration

// Update project metadata URI
function setUriOf(uint256 projectId, string calldata uri) external;

// Set project's ERC-20 token
function setTokenFor(uint256 projectId, IJBToken token) external;

// Update split groups
function setSplitGroupsOf(
    uint256 projectId,
    uint256 rulesetId,
    JBSplitGroup[] calldata splitGroups
) external;

// Add price feed for currency conversion
function addPriceFeed(
    uint256 projectId,
    uint256 pricingCurrency,
    uint256 unitCurrency,
    IJBPriceFeed feed
) external;

View Functions

function currentRulesetOf(uint256 projectId)
    external view returns (JBRuleset, JBRulesetMetadata);

function upcomingRulesetOf(uint256 projectId)
    external view returns (JBRuleset, JBRulesetMetadata);

function latestQueuedRulesetOf(uint256 projectId)
    external view returns (JBRuleset, JBRulesetMetadata, JBApprovalStatus);

function getRulesetOf(uint256 projectId, uint256 rulesetId)
    external view returns (JBRuleset, JBRulesetMetadata);

function allRulesetsOf(uint256 projectId, uint256 startingId, uint256 size)
    external view returns (JBRulesetWithMetadata[]);

function totalTokenSupplyWithReservedTokensOf(uint256 projectId)
    external view returns (uint256);

function setTerminalsAllowed(uint256 projectId) external view returns (bool);
function setControllerAllowed(uint256 projectId) external view returns (bool);

---

JBTokens Functions

Manages project token accounting, including credits (unclaimed balances) and ERC20 tokens.

Token Deployment

// Deploy standard JBERC20 for a project
function deployERC20For(
    uint256 projectId,
    string calldata name,
    string calldata symbol,
    bytes32 salt              // For deterministic address (0 for non-deterministic)
) external returns (IJBToken token);

// Set a custom ERC20 as the project token
function setTokenFor(
    uint256 projectId,
    IJBToken token            // Must implement IJBToken interface
) external;

Token Operations

// Mint tokens to a holder (called by controller)
function mintFor(
    address holder,
    uint256 projectId,
    uint256 count
) external;

// Burn tokens from a holder (called by controller)
function burnFrom(
    address holder,
    uint256 projectId,
    uint256 count
) external;

// Convert credits to ERC20 tokens
function claimTokensFor(
    address holder,
    uint256 projectId,
    uint256 count,
    address beneficiary
) external;

// Transfer credits between addresses
function transferCreditsFrom(
    address holder,
    uint256 projectId,
    address recipient,
    uint256 count
) external;

View Functions

// Get the ERC20 token for a project (address(0) if credits-only)
function tokenOf(uint256 projectId) external view returns (IJBToken);

// Get the project ID for a token
function projectIdOf(IJBToken token) external view returns (uint256);

// Get credit balance for a holder
function creditBalanceOf(address holder, uint256 projectId) external view returns (uint256);

// Get total credit supply for a project
function totalCreditSupplyOf(uint256 projectId) external view returns (uint256);

// Get total balance (credits + ERC20) for a holder
function totalBalanceOf(address holder, uint256 projectId) external view returns (uint256);

// Get total supply (credits + ERC20) for a project
function totalSupplyOf(uint256 projectId) external view returns (uint256);

IJBToken Interface (for Custom Tokens)

Custom tokens must implement this interface:

interface IJBToken is IERC20 {
    // Standard ERC20 functions (name, symbol, decimals, totalSupply, balanceOf, transfer, etc.)

    /// @notice Check if this token can be added to a project.
    /// @dev Must return true for setTokenFor() to succeed.
    function canBeAddedTo(uint256 projectId) external view returns (bool);

    /// @notice Mint tokens. Called by JBTokens on payments.
    function mint(address holder, uint256 amount) external;

    /// @notice Burn tokens. Called by JBTokens on cash outs.
    function burn(address holder, uint256 amount) external;
}

Custom Token Requirements

Requirement	Details
18 decimals	decimals() must return 18
canBeAddedTo	Must return true for the target project ID
Unique assignment	Cannot be assigned to multiple projects
Controller access	Must allow JBController to mint/burn

---

JBMultiTerminal Functions

Payments

// Pay a project
function pay(
    uint256 projectId,
    address token,              // address(0) for native
    uint256 amount,
    address beneficiary,        // Receives minted tokens
    uint256 minReturnedTokens,  // Slippage protection
    string calldata memo,
    bytes calldata metadata     // Hook data
) external payable returns (uint256 beneficiaryTokenCount);

// Add funds without minting tokens
function addToBalanceOf(
    uint256 projectId,
    address token,
    uint256 amount,
    bool shouldReturnHeldFees,
    string calldata memo,
    bytes calldata metadata
) external payable;

Cash Outs (Redemptions)

// Cash out tokens for funds
function cashOutTokensOf(
    address holder,
    uint256 projectId,
    uint256 cashOutCount,       // Tokens to burn
    address tokenToReclaim,     // Which token to receive
    uint256 minTokensReclaimed, // Slippage protection
    address payable beneficiary,
    bytes calldata metadata
) external returns (uint256 reclaimAmount);

Distributions

// Send payouts to splits (within payout limit)
function sendPayoutsOf(
    uint256 projectId,
    address token,
    uint256 amount,
    uint256 currency,
    uint256 minTokensPaidOut
) external returns (uint256 amountPaidOut);

// Use surplus allowance (discret

---

*Content truncated.*