--- name: jb-omnichain-payout-limits description: | Omnichain projects have per-chain payout limits, not aggregate limits. This is a fundamental constraint with no perfect solution. Use when: (1) user wants a fixed total fundraising cap across chains, (2) asking about aggregate payout limits on omnichain projects, (3) designing omnichain projects with payout constraints, (4) exploring oracle or monitoring solutions for cross-chain state. Covers the limitation, why it exists, and practical approaches with tradeoffs. --- # Omnichain Payout Limit Constraints > **Note**: This applies to projects using payout limits (standard Juicebox projects with treasury distributions). Revnets don't use payout limits - they use unlimited surplus allowances for loans via REVLoans, so this limitation doesn't affect them. ## The Problem **Payout limits in Juicebox V5 are per-chain, not aggregate.** When you deploy an omnichain project (linked via Suckers), each chain has its own independent payout limit. Setting a 10 ETH payout limit on a 5-chain project means you could potentially pay out 50 ETH total (10 ETH × 5 chains), not 10 ETH total. ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Omnichain Project with 10 ETH "Payout Limit" │ │ │ │ Chain 1 (Ethereum): Limit = 10 ETH → Can pay out 10 ETH │ │ Chain 2 (Optimism): Limit = 10 ETH → Can pay out 10 ETH │ │ Chain 3 (Base): Limit = 10 ETH → Can pay out 10 ETH │ │ Chain 4 (Arbitrum): Limit = 10 ETH → Can pay out 10 ETH │ │ ───────────────── │ │ TOTAL: 40 ETH possible │ │ │ │ User expectation: 10 ETH max │ │ Reality: 40 ETH max │ └─────────────────────────────────────────────────────────────────────┘ ``` ## Why This Is Fundamentally Hard Cross-chain state is **asynchronous**. There is no atomic way to know the aggregate raised/paid across all chains in real-time. Any solution that coordinates cross-chain state introduces: - **Latency**: Not real-time (seconds to minutes of delay) - **Trust assumptions**: Who runs the oracle? Who can manipulate it? - **Manipulation windows**: Attackers can exploit sync delays - **Gas costs**: Cross-chain messaging is expensive - **Complexity**: More moving parts = more failure modes This is not a bug in Juicebox - it's a fundamental property of multi-chain systems. ## Approaches ### Approach 1: Accept & Design Around It **Best for**: Projects where approximate limits are acceptable Set per-chain limits that sum to your target, accepting that distribution may not match expectations. ```solidity // Goal: ~100 ETH total across 5 chains // Strategy: 20 ETH limit per chain // Each chain's ruleset config: fundAccessLimitGroups: [{ terminal: MULTI_TERMINAL, token: NATIVE_TOKEN, payoutLimits: [{ amount: 20 ether, // Per-chain limit currency: 1 // ETH }], surplusAllowances: [] }] ``` **Tradeoffs**: - One chain might hit its limit while others have slack - Total raised could be less than desired if distribution is uneven - No coordination required - simplest approach **When to use**: - Soft caps (nice-to-have limits, not hard requirements) - Projects where ~80-120% of target is acceptable - Early-stage projects testing omnichain --- ### Approach 2: Monitoring + Manual Pause **Best for**: Projects with active operators who can respond quickly Use Bendystraw to monitor aggregate raises, manually pause payments when approaching threshold. ```typescript const BENDYSTRAW_API = 'https://bendystraw.xyz/{API_KEY}/graphql'; // Query aggregate balance across all chains async function getAggregateBalance(suckerGroupId: string) { const query = ` query($id: String!) { suckerGroup(id: $id) { balance volume projects_rel { chainId balance } } } `; const data = await fetch(BENDYSTRAW_API, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ query, variables: { id: suckerGroupId } }) }).then(r => r.json()); return data.data.suckerGroup; } // Monitoring loop async function monitorAndAlert(suckerGroupId: string, threshold: bigint) { const group = await getAggregateBalance(suckerGroupId); const balance = BigInt(group.balance); if (balance >= threshold * 90n / 100n) { // 90% of threshold - send alert console.log('ALERT: Approaching threshold, consider pausing'); } if (balance >= threshold) { // At threshold - operator should pause console.log('THRESHOLD REACHED: Pause payments now'); // Could trigger notification (email, Telegram, Discord webhook) } } ``` **Manual pause action**: ```typescript // Project owner calls on each chain await controller.queueRulesetsOf(projectId, [{ // ... existing config metadata: { // ... existing metadata pausePay: true // Disable new payments } }]); ``` **Tradeoffs**: - Requires active monitoring (someone watching) - Reaction time matters - payments during delay - Human error risk (forget to pause, pause wrong chain) - Not suitable for trustless/autonomous projects **When to use**: - Projects with dedicated operators - Lower stakes where brief overruns are acceptable - Transitional approach while building automation --- ### Approach 3: Automated Cron + Relayr **Best for**: Projects wanting automation without full oracle complexity A cron job monitors aggregate balance via Bendystraw, uses Relayr to pause payments across all chains when threshold approaches. ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Automated Threshold Monitor │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Cron Job │────►│ Bendystraw │────►│ Check │ │ │ │ (every 5m) │ │ Query │ │ Threshold │ │ │ └──────────────┘ └──────────────┘ └──────┬───────┘ │ │ │ │ │ threshold met? │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Relayr Bundle: Pause payments on all chains │ │ │ │ │ │ │ │ Chain 1: queueRulesetsOf(projectId, {pausePay: true}) │ │ │ │ Chain 2: queueRulesetsOf(projectId, {pausePay: true}) │ │ │ │ Chain 3: queueRulesetsOf(projectId, {pausePay: true}) │ │ │ │ Chain 4: queueRulesetsOf(projectId, {pausePay: true}) │ │ │ └──────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ ``` **Implementation requirements**: 1. **Operator address**: Needs `QUEUE_RULESETS` permission on each chain's project 2. **Cron infrastructure**: Reliable job runner (AWS Lambda, Cloudflare Workers, dedicated server) 3. **Bendystraw API key**: For querying aggregate state 4. **Relayr integration**: For multi-chain transaction bundling ```typescript // Simplified cron handler async function checkAndPauseIfNeeded(config: { suckerGroupId: string; threshold: bigint; projectIds: { chainId: number; projectId: number }[]; operatorKey: string; }) { // 1. Check aggregate balance const group = await getAggregateBalance(config.suckerGroupId); const balance = BigInt(group.balance); if (balance < config.threshold) { return; // Under threshold, do nothing } // 2. Build pause transactions for each chain const pauseTxs = config.projectIds.map(({ chainId, projectId }) => ({ chain: chainId, target: CONTROLLER_ADDRESSES[chainId], data: encodeFunctionData({ abi: JB_CONTROLLER_ABI, functionName: 'queueRulesetsOf', args: [projectId, /* rulesetConfigs with pausePay: true */] }), value: '0' })); // 3. Submit via Relayr const bundle = await relayr.createBundle(pauseTxs); await relayr.payForBundle(bundle, config.operatorKey); console.log(`Paused payments across ${config.projectIds.length} chains`); } ``` **Tradeoffs**: - **Latency**: 5-minute cron + Relayr execution time = potential overshoot - **Trust**: Operator key holder can act unilaterally - **Infrastructure**: Requires running and maintaining a service - **Cost**: Relayr fees + gas on all chains - **Reliability**: Cron failures = missed threshold **When to use**: - Projects with some trust in a designated operator - Soft caps where ~5-10% overshoot is acceptable - Projects without resources for full oracle implementation --- ### Approach 4: Oracle in Pay Hook **Best for**: Projects requiring hard limits with strong guarantees A pay hook checks an oracle for aggregate state before allowing payments. The oracle is updated by a relayer watching all chains. ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Oracle-Based Aggregate Limit │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Oracle Contract (deployed on each chain) │ │ │ │ ├── aggregateBalance: uint256 (updated by relayer) │ │ │ │ ├── threshold: uint256 │ │ │ │ └── lastUpdate: uint256 (timestamp) │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ ▲ │ │ │ update │ │ ┌────────────────────────┴────────────────────────────────────┐ │ │ │ Relayer Service │ │ │ │ ├── Watches PayEvents on all chains │ │ │ │ ├── Calculates aggregate balance │ │ │ │ └── Updates oracle on all chains │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ Pay Flow: │ │ User → pay() → PayHook.beforePayRecordedWith() → Oracle.check() │ │ │ │ If oracle.aggregateBalance + payAmount > threshold: │ │ REVERT "Aggregate limit exceeded" │ └─────────────────────────────────────────────────────────────────────┘ ``` **Implementation sketch**: ```solidity // Oracle contract contract AggregateBalanceOracle { uint256 public aggregateBalance; uint256 public threshold; uint256 public lastUpdate; address public relayer; function updateBalance(uint256 newBalance) external { require(msg.sender == relayer, "UNAUTHORIZED"); aggregateBalance = newBalance; lastUpdate = block.timestamp; } function wouldExceedThreshold(uint256 additionalAmount) external view returns (bool) { return aggregateBalance + additionalAmount > threshold; } } // Pay hook that checks oracle contract AggregateLimitPayHook is IJBPayHook { AggregateBalanceOracle public oracle; uint256 public maxStaleness = 5 minutes; function beforePayRecordedWith(JBBeforePayRecordedContext calldata context) external view override returns (uint256, uint256, uint256, JBPayHookSpecification[] memory) { // Check oracle freshness require( block.timestamp - oracle.lastUpdate() <= maxStaleness, "Oracle stale" ); // Check aggregate limit require( !oracle.wouldExceedThreshold(context.amount.value), "Aggregate limit exceeded" ); // Allow payment return (context.weight, context.newlyIssuedTokenCount, context.totalSupply, new JBPayHookSpecification[](0)); } } ``` **Tradeoffs**: - **Complexity**: Multiple contracts + relayer service - **Latency**: Oracle updates lag behind reality - **Staleness window**: Payments during oracle delay can exceed limit - **Relayer trust**: Single point of failure/manipulation - **Cost**: Continuous relayer operation + oracle update gas - **UX**: Payments can fail if oracle is stale or near threshold **When to use**: - Hard regulatory/compliance limits that must be enforced - High-stakes projects where overshoot is unacceptable - Projects with resources to build and maintain infrastructure **Current status**: No off-the-shelf implementation exists. Would need custom development. --- ### Approach 5: Single-Chain Treasury **Best for**: Projects that can centralize treasury operations Accept payments on all chains, but bridge all funds to a single "home" chain for treasury operations. Payout limit on home chain is the only one that matters. ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Single-Chain Treasury Pattern │ │ │ │ Chain 1 (Home): Treasury lives here │ │ ├── Payout limit: 100 ETH (THIS IS THE REAL LIMIT) │ │ ├── Accepts payments │ │ └── All payouts happen here │ │ │ │ Chain 2-4: Payment collection only │ │ ├── Payout limit: 0 (no direct payouts) │ │ ├── Accept payments │ │ └── Funds bridged to Chain 1 via Suckers │ │ │ │ Flow: │ │ User pays on Chain 2 → Tokens issued on Chain 2 │ │ → User bridges funds to Chain 1 (manual) │ │ → Chain 1 treasury grows │ │ → Payouts from Chain 1 only │ └─────────────────────────────────────────────────────────────────────┘ ``` **The blocker**: Suckers require explicit user action to bridge. The project cannot automatically sweep funds from other chains to the home chain. Users must: 1. Call `prepare()` on the source chain 2. Wait for bridging 3. Call `claim()` on the destination chain **Potential workarounds**: - Incentivize users to bridge (bonus tokens, lower fees on home chain) - Build a "sweeper" bot that bridges on behalf of users (requires trust + gas) - Accept that some funds remain distributed **Tradeoffs**: - **User friction**: Extra steps to bridge funds - **Fragmentation**: Funds spread across chains until bridged - **Complexity**: Users must understand the pattern - **Cannot enforce**: Can't force users to bridge **When to use**: - Projects where most activity naturally happens on one chain - Projects willing to accept some treasury fragmentation - Transitional approach for projects moving toward single-chain --- ## Comparison Matrix | Approach | Enforcement | Latency | Trust Required | Complexity | Best For | |----------|-------------|---------|----------------|------------|----------| | Accept & Design | Soft | N/A | None | Low | Soft caps | | Manual Monitoring | Soft | Minutes | Operator | Low | Active teams | | Cron + Relayr | Soft | ~5-10 min | Operator | Medium | Automation | | Oracle Pay Hook | Hard* | Seconds | Relayer | High | Compliance | | Single-Chain | Medium | N/A | None | Medium | Centralized ops | *Oracle enforcement has latency window during updates --- ## Recommendations by Use Case ### "We need a hard cap for regulatory compliance" **Answer**: This is very difficult in omnichain. Consider: 1. Single-chain only (no omnichain) 2. Oracle pay hook (complex, custom development) 3. Accept that enforcement is approximate ### "We want a fundraising goal but it's not legally binding" **Answer**: Use Approach 1 (Accept & Design) or Approach 2 (Manual Monitoring) - Set per-chain limits that sum to ~80% of your goal - Monitor via Bendystraw - Pause manually when approaching target ### "We have an operator who can manage this" **Answer**: Use Approach 3 (Cron + Relayr) - Automate the monitoring and pausing - Accept 5-10% potential overshoot - Ensure operator key security ### "We're building a revnet" **Answer**: This limitation doesn't apply to revnets - Revnets don't use payout limits - they use surplus allowances for loans (via REVLoans) - Surplus allowances are unlimited by design (for loan collateral access) - If you need aggregate fundraising caps on a revnet, see the oracle or monitoring approaches above --- ## Future Considerations ### Could Juicebox natively support aggregate limits? Theoretically, but it would require: 1. **Cross-chain messaging protocol**: Native integration with bridges 2. **Consensus on aggregate state**: Which chain is source of truth? 3. **Latency acceptance**: Users accept payments may fail during sync 4. **Cost distribution**: Who pays for cross-chain messages? This is a significant protocol-level change, not a simple feature add. ### Could a shared oracle service exist? Yes - a community-run oracle service could: - Watch all Juicebox projects across chains - Provide aggregate state queries - Update on-chain oracles This could be built as infrastructure, but requires: - Ongoing operational funding - Trust in the service operator - Integration with pay hooks --- ## Related Skills - `/jb-omnichain-ui` - Building omnichain frontends - `/jb-suckers` - Cross-chain token bridging mechanics - `/jb-bendystraw` - Querying aggregate project data - `/jb-relayr` - Multi-chain transaction bundling - `/jb-fund-access-limits` - Per-chain payout limit configuration