dvcrn/openclaw-skills-marketplace/jb-v5-currency-types

Juicebox V5 Currency Types

Problem

Juicebox V5 has two different currency systems that are easy to confuse, leading to:

• Inconsistent issuance rates across chains
• Projects vulnerable to stablecoin depegs
• Misconfigured accounting contexts
• Cross-chain ruleset interpretation failures

Context / Trigger Conditions

Apply this knowledge when:

• Setting ruleset.baseCurrency for token issuance
• Configuring JBAccountingContext.currency for terminals
• Working with JBCurrencyAmount in payout limits or allowances
• Building cross-chain projects that need consistent behavior
• Debugging why issuance rates differ between chains
• Seeing different currency values for "the same" token on different chains

Solution

Two Currency Systems

1. Real-World Currencies (JBCurrencies)

Abstract values representing the concept of a currency, chain-agnostic:

These are stable across ALL chains. baseCurrency=2 means "issue X tokens per USD" whether you're on Ethereum, Base, Celo, or Polygon.

2. Token-Derived Currencies

Computed from token addresses, chain-specific:

currency = uint32(uint160(tokenAddress))

When to Use Which

Critical Rules

1. NEVER use token currencies for `baseCurrency`

• Token addresses change across chains
• Would cause different issuance rates per chain
• Breaks cross-chain project consistency

1. NEVER use NATIVE_TOKEN's currency (4008636142) for `baseCurrency`

• Different chains have different native tokens (ETH, CELO, MATIC, etc.)
• NATIVE_TOKEN represents "whatever is native on this chain" - not specifically ETH
• If you want issuance relative to ETH, use JBCurrencies.ETH (which is 1)
• JBPrices provides a 1:1 price feed between NATIVE_TOKEN currency and ETH currency on chains where ETH is the native token

1. ALWAYS use token currencies for `JBAccountingContext`

• Formula: currency = uint32(uint160(token))
• The terminal needs to know exactly which token it's accounting for

1. USD vs USDC distinction matters

• USD (2) = abstract dollar concept
• USDC (token-derived) = specific stablecoin
• If USDC depegs to $0.98, a project with baseCurrency=2 still issues tokens per dollar (protected)
• JBPrices handles the exchange rate between USD and USDC

JBPrices

JBPrices manages exchange rates between:

• Real-world currencies (ETH ↔ USD)
• Token currencies (USDC ↔ USD, ETH token ↔ ETH concept)
• Cross-currency conversions for payments and cash outs

Verification

To verify correct configuration:

1. Check baseCurrency is 1 or 2, never a large token-derived number
2. Check JBAccountingContext.currency matches uint32(uint160(token))
3. Deploy to testnet on two different chains and verify issuance rates match

Example

Correct cross-chain project configuration:

const rulesetConfig = {
  // ... other fields
  metadata: {
    baseCurrency: 2,  // USD - same on all chains
    // ...
  }
}
const terminalConfig = {
  terminal: JBMultiTerminal5_1,
  accountingContextsToAccept: [{
    token: USDC_ADDRESS[chainId],  // Different per chain
    decimals: 6,
    currency: uint32(uint160(USDC_ADDRESS[chainId]))  // Different per chain
  }]
}

Wrong:

const rulesetConfig = {
  metadata: {
    baseCurrency: 909516616,  // WRONG! This is Ethereum USDC's token currency
    // This would break on other chains or if USDC depegs
  }
}

Also wrong:

const rulesetConfig = {
  metadata: {
    baseCurrency: 4008636142,  // WRONG! This is NATIVE_TOKEN's currency
    // NATIVE_TOKEN is CELO on Celo, MATIC on Polygon, etc.
    // If you want "per ETH" issuance, use 1 (JBCurrencies.ETH)
  }
}

Notes

• Price feeds between all currency types are managed by JBPrices contract
• The NATIVE_TOKEN address (0xEEEE...EEEe) is special and constant across chains, but represents different actual tokens per chain
• baseCurrency=1 (ETH) means "issue tokens relative to ETH the asset" - JBPrices correlates NATIVE_TOKEN to ETH at 1:1 on ETH-native chains
• On non-ETH-native chains (Celo, Polygon), JBPrices provides the ETH/NATIVE_TOKEN exchange rate so issuance stays ETH-denominated
• This architecture enables truly portable rulesets that behave identically regardless of deployment chain
• The separation between "real-world currency concepts" and "token-derived currencies" is what makes cross-chain consistency possible

Related Skills

• /jb-suckers - Cross-chain bridging mechanics via sucker contracts
• /jb-omnichain-ui - Building omnichain UIs with Relayr and Bendystraw