jb-omnichain-payout-limits

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.

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

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:

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

// 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                           │   │
│  └────────────────────

---

*Content truncated.*