revenue_pool.json

{
  "contract": "callora-revenue-pool",
  "version": "0.0.1",
  "description": "Simple revenue distribution contract. Receives USDC when the vault forwards deducted funds and lets the admin distribute those funds to developer wallets individually or in batch.",
  "crate": "callora-revenue-pool",
  "source": "contracts/revenue_pool/src/lib.rs",

  "types": {},

  "functions": [
    {
      "name": "init",
      "description": "Initialize the revenue pool with an admin and the USDC token address. Can only be called once. The admin must authorize the call.",
      "access": "admin (must sign)",
      "params": [
        {
          "name": "admin",
          "type": "Address",
          "optional": false,
          "description": "Address that may call distribute, batch_distribute, receive_payment, and set_admin."
        },
        {
          "name": "usdc_token",
          "type": "Address",
          "optional": false,
          "description": "Stellar USDC (or wrapped USDC) token contract address."
        }
      ],
      "returns": "void",
      "panics": [
        "\"revenue pool already initialized\" — called more than once."
      ],
      "events": [
        { "topics": ["\"init\"", "admin"], "data": "usdc_token (Address)" }
      ]
    },

    {
      "name": "pause",
      "description": "Activate the circuit-breaker. Blocks distribute and batch_distribute until unpause is called. Admin rotation (set_admin / claim_admin) remains available while paused.",
      "access": "admin or pause guardian",
      "params": [
        { "name": "caller", "type": "Address", "optional": false, "description": "Must be the current admin or configured pause guardian; must authorize." }
      ],
      "returns": "void",
      "panics": [
        "\"unauthorized: caller is not admin or pause guardian\" — caller is neither current admin nor configured pause guardian.",
        "\"revenue pool already paused\" — pool is already paused."
      ],
      "events": [
        { "topics": ["\"pause_set\"", "caller"], "data": "true (bool)" }
      ]
    },

    {
      "name": "unpause",
      "description": "Deactivate the circuit-breaker, restoring distribute and batch_distribute.",
      "access": "admin",
      "params": [
        {
          "name": "caller",
          "type": "Address",
          "optional": false,
          "description": "Must be the current admin; must authorize."
        }
      ],
      "returns": "void",
      "panics": [
        "\"unauthorized: caller is not admin\" — caller != current admin.",
        "\"revenue pool not paused\" — pool is not currently paused."
      ],
      "events": [
        { "topics": ["\"pause_set\"", "caller"], "data": "false (bool)" }
      ]
    },

    {
      "name": "is_paused",
      "description": "Return true if the revenue pool is currently paused, false otherwise. Defaults to false before any pause call.",
      "access": "any",
      "params": [],
      "returns": "bool",
      "panics": [],
      "events": []
    },

    {
      "name": "set_pause_guardian",
      "description": "Set or replace the emergency pause guardian. The guardian can pause the pool but cannot unpause, distribute, rotate admin, change caps, or upgrade.",
      "access": "admin",
      "params": [
        { "name": "caller",   "type": "Address", "optional": false, "description": "Must be the current admin; must authorize." },
        { "name": "guardian", "type": "Address", "optional": false, "description": "Address that may call pause." }
      ],
      "returns": "void",
      "panics": [
        "\"unauthorized: caller is not admin\" — caller != current admin."
      ],
      "events": [
        { "topics": ["\"pause_guardian_set\"", "caller"], "data": "guardian (Address)" }
      ]
    },

    {
      "name": "clear_pause_guardian",
      "description": "Remove the configured emergency pause guardian. After clearing, only the admin can pause.",
      "access": "admin",
      "params": [
        { "name": "caller", "type": "Address", "optional": false, "description": "Must be the current admin; must authorize." }
      ],
      "returns": "void",
      "panics": [
        "\"unauthorized: caller is not admin\" — caller != current admin.",
        "\"no pause guardian set\" — no guardian is configured."
      ],
      "events": [
        { "topics": ["\"pause_guardian_cleared\"", "caller"], "data": "previous guardian (Address)" }
      ]
    },

    {
      "name": "get_pause_guardian",
      "description": "Return the configured emergency pause guardian, or None if no guardian is set.",
      "access": "any",
      "params": [],
      "returns": "Option<Address>",
      "panics": [],
      "events": []
    },

    {
      "name": "distribute",
      "description": "Transfer USDC from this contract to a developer wallet. Admin only. Blocked while paused.",
      "access": "admin",
      "params": [
        {
          "name": "caller",
          "type": "Address",
          "optional": false,
          "description": "Must be the current admin; must authorize."
        },
        {
          "name": "to",
          "type": "Address",
          "optional": false,
          "description": "Developer address to receive USDC."
        },
        {
          "name": "amount",
          "type": "i128",
          "optional": false,
          "description": "Amount in USDC base units; must be > 0."
        }
      ],
      "returns": "void",
      "panics": [
        "\"revenue pool is paused\" — pool is paused.",
        "\"unauthorized: caller is not admin\" — caller != current admin.",
        "\"amount must be positive\" — amount <= 0.",
        "\"revenue pool not initialized\" — called before init.",
        "\"insufficient USDC balance\" — contract holds less than amount."
      ],
      "events": [
        { "topics": ["\"distribute\"", "to"], "data": "amount (i128)" }
      ]
    },

    {
      "name": "batch_distribute",
      "description": "Atomically distribute USDC to multiple developer wallets. Validates the total against the available balance before any transfer. One event is emitted per payment. Admin only. Blocked while paused.",
      "access": "admin",
      "params": [
        {
          "name": "caller",
          "type": "Address",
          "optional": false,
          "description": "Must be the current admin; must authorize."
        },
        {
          "name": "payments",
          "type": "Vec<(Address, i128)>",
          "optional": false,
          "description": "Ordered list of (developer_address, amount) pairs. All amounts must be > 0."
        }
      ],
      "returns": "void",
      "panics": [
        "\"revenue pool is paused\" — pool is paused.",
        "\"unauthorized: caller is not admin\" — caller != current admin.",
        "\"amount must be positive\" — any individual amount <= 0.",
        "\"total overflow\" — extremely unlikely sum overflow.",
        "\"revenue pool not initialized\" — called before init.",
        "\"insufficient USDC balance\" — total amount exceeds contract balance."
      ],
      "events": [
        {
          "note": "One event per payment entry.",
          "topics": ["\"batch_distribute\"", "to"],
          "data": "amount (i128)"
        }
      ]
    },

    {
      "name": "receive_payment",
      "description": "Event-only helper — does NOT move tokens. Emits a receive_payment event for indexer alignment when the backend wants to log a payment credited from the vault. USDC is received passively when any address transfers tokens to this contract; no explicit call is required for token receipt.",
      "access": "admin",
      "params": [
        {
          "name": "caller",
          "type": "Address",
          "optional": false,
          "description": "Must be the current admin; must authorize."
        },
        {
          "name": "amount",
          "type": "i128",
          "optional": false,
          "description": "Amount received (for event logging only; no tokens are moved)."
        },
        {
          "name": "from_vault",
          "type": "bool",
          "optional": false,
          "description": "True if the source was the vault contract."
        }
      ],
      "returns": "void",
      "panics": [
        "\"unauthorized: caller is not admin\" — caller != current admin."
      ],
      "events": [
        {
          "topics": ["\"receive_payment\"", "caller"],
          "data": "(amount, from_vault) tuple"
        }
      ]
    },

    {
      "name": "balance",
      "description": "Return the contract's current USDC balance.",
      "access": "any",
      "params": [],
      "returns": "i128",
      "panics": ["\"revenue pool not initialized\" — called before init."],
      "events": []
    },

    {
      "name": "get_admin",
      "description": "Return the current admin address.",
      "access": "any",
      "params": [],
      "returns": "Address",
      "panics": ["\"revenue pool not initialized\" — called before init."],
      "events": []
    },

    {
      "name": "get_pending_admin",
      "description": "Return the pending admin address, or null if no two-step transfer is in progress. Integrators can poll this to detect an in-flight admin handover before accept_admin or claim_admin is called.",
      "access": "any",
      "params": [],
      "returns": "Address | null",
      "panics": [],
      "events": []
    },

    {
      "name": "set_admin",
      "description": "Initiate replacement of the current admin. The proposed new admin must call claim_admin to complete the transfer.",
      "access": "admin",
      "params": [
        {
          "name": "caller",
          "type": "Address",
          "optional": false,
          "description": "Must be the current admin; must authorize."
        },
        {
          "name": "new_admin",
          "type": "Address",
          "optional": false,
          "description": "Address of the proposed new admin."
        }
      ],
      "returns": "void",
      "panics": [
        "\"unauthorized: caller is not admin\" — caller != current admin."
      ],
      "events": [
        {
          "topics": ["\"admin_transfer_started\"", "current_admin"],
          "data": "new_admin (Address)"
        }
      ]
    },


    {
      "name": "get_treasury",
      "description": "Return the current treasury address authorized to call deposit_yield. Deployments without a dedicated treasury key fall back to the admin address.",
      "access": "any",
      "params": [],
      "returns": "Address",
      "panics": ["\"revenue pool not initialized\" — called before init and no treasury fallback exists."],
      "events": []
    },

    {
      "name": "get_pending_treasury",
      "description": "Return the pending treasury address, or null if no two-step treasury transfer is in progress.",
      "access": "any",
      "params": [],
      "returns": "Address | null",
      "panics": [],
      "events": []
    },

    {
      "name": "set_treasury",
      "description": "Nominate a new treasury. The current admin must authorize, and the nominee must call accept_treasury before deposit_yield authority changes.",
      "access": "admin",
      "params": [
        { "name": "caller", "type": "Address", "optional": false, "description": "Must be the current admin; must authorize." },
        { "name": "new_treasury", "type": "Address", "optional": false, "description": "Address of the proposed treasury." }
      ],
      "returns": "void",
      "panics": [
        "\"unauthorized: caller is not admin\" — caller != current admin.",
        "\"new treasury is already current treasury\" — nominee is already active."
      ],
      "events": [
        { "topics": ["\"treasury_transfer_started\"", "caller"], "data": "(old_treasury, new_treasury)" }
      ]
    },

    {
      "name": "accept_treasury",
      "description": "Complete a pending treasury transfer. Must be called by the pending treasury.",
      "access": "pending treasury (must sign)",
      "params": [
        { "name": "caller", "type": "Address", "optional": false, "description": "Must be the pending treasury; must authorize." }
      ],
      "returns": "void",
      "panics": [
        "\"no pending treasury\" — set_treasury was not called first.",
        "\"unauthorized: caller is not pending treasury\" — caller is not the pending treasury."
      ],
      "events": [
        { "topics": ["\"treasury_transfer_completed\"", "new_treasury"], "data": "old_treasury (Address)" }
      ]
    },

    {
      "name": "cancel_treasury_transfer",
      "description": "Cancel a pending treasury transfer. Only the current admin may call this.",
      "access": "admin",
      "params": [
        { "name": "caller", "type": "Address", "optional": false, "description": "Must be the current admin; must authorize." }
      ],
      "returns": "void",
      "panics": [
        "\"unauthorized: caller is not admin\" — caller != current admin.",
        "\"no treasury transfer pending\" — no pending treasury is configured."
      ],
      "events": [
        { "topics": ["\"treasury_cancelled\"", "caller"], "data": "pending_treasury (Address)" }
      ]
    },

    {
      "name": "claim_admin",
      "description": "Complete the admin transfer. Must be called by the pending admin set via set_admin.",
      "access": "pending admin (must sign)",
      "params": [
        {
          "name": "caller",
          "type": "Address",
          "optional": false,
          "description": "Must be the pending admin; must authorize."
        }
      ],
      "returns": "void",
      "panics": [
        "\"no pending admin\" — set_admin was not called first.",
        "\"unauthorized: caller is not pending admin\" — caller is not the pending admin."
      ],
      "events": [
        {
          "topics": ["\"admin_transfer_completed\"", "new_admin"],
          "data": "void"
        }
      ]
    },

    {
      "name": "propose_emergency_drain",
      "description": "Propose a timelocked USDC emergency drain to a treasury address. Stores a PendingEmergencyDrain snapshot; execution is only possible after EMERGENCY_DRAIN_TIMELOCK_SECONDS (86 400 s = 24 h) have elapsed. A new proposal replaces any existing one, resetting the clock. When the admin is a Stellar multisig account, require_auth enforces the native multi-signature threshold automatically, providing Multisig + timelock protection.",
      "access": "admin (must sign; multisig threshold enforced by Soroban host when admin is a multisig account)",
      "params": [
        {
          "name": "caller",
          "type": "Address",
          "optional": false,
          "description": "Must be the current admin; must authorize."
        },
        {
          "name": "treasury",
          "type": "Address",
          "optional": false,
          "description": "Destination address for drained USDC. Cannot be the contract itself."
        },
        {
          "name": "amount",
          "type": "i128",
          "optional": false,
          "description": "USDC amount in base units. Must be positive."
        }
      ],
      "returns": "void",
      "panics": [
        "\"unauthorized: caller is not admin\" — caller != current admin.",
        "\"amount must be positive\" — amount <= 0.",
        "\"invalid recipient: cannot drain to the contract itself\" — treasury == contract address.",
        "\"timelock overflow\" — proposed_at + 86400 would overflow u64."
      ],
      "events": [
        {
          "topics": ["\"emergency_drain_proposed\"", "caller"],
          "data": "PendingEmergencyDrain { to, amount, proposed_at, execute_after }"
        }
      ]
    },

    {
      "name": "execute_emergency_drain",
      "description": "Execute a pending emergency drain after the 24-hour timelock has expired. Transfers the proposed USDC amount to the destination address and removes the pending snapshot (replay protection).",
      "access": "admin (must sign)",
      "params": [
        {
          "name": "caller",
          "type": "Address",
          "optional": false,
          "description": "Must be the current admin; must authorize."
        }
      ],
      "returns": "void",
      "panics": [
        "\"unauthorized: caller is not admin\" — caller != current admin.",
        "\"no pending emergency drain\" — propose_emergency_drain was not called first.",
        "\"emergency drain timelock has not expired\" — current timestamp < execute_after.",
        "\"insufficient USDC balance\" — contract holds less than the proposed amount."
      ],
      "events": [
        {
          "topics": ["\"emergency_drain_executed\"", "caller"],
          "data": "(to, amount, proposed_at, executed_at) tuple"
        }
      ]
    },

    {
      "name": "cancel_emergency_drain",
      "description": "Cancel a pending emergency drain. May be called at any time before execution, including before the timelock expires. Removes the snapshot and emits an audit event.",
      "access": "admin (must sign)",
      "params": [
        {
          "name": "caller",
          "type": "Address",
          "optional": false,
          "description": "Must be the current admin; must authorize."
        }
      ],
      "returns": "void",
      "panics": [
        "\"unauthorized: caller is not admin\" — caller != current admin.",
        "\"no pending emergency drain\" — no proposal exists to cancel."
      ],
      "events": [
        {
          "topics": ["\"emergency_drain_cancelled\"", "caller"],
          "data": "PendingEmergencyDrain { to, amount, proposed_at, execute_after }"
        }
      ]
    },

    {
      "name": "get_pending_emergency_drain",
      "description": "Return the pending emergency drain proposal snapshot, or null if none exists. Off-chain monitors and the admin can poll this to verify or cancel a pending drain before the timelock expires.",
      "access": "any",
      "params": [],
      "returns": "Option<PendingEmergencyDrain>",
      "panics": [],
      "events": []
    }
  ],

  "types_detail": {
    "PendingEmergencyDrain": {
      "description": "Immutable snapshot of a pending emergency drain proposal.",
      "fields": {
        "to": { "type": "Address", "description": "Destination address for the drained USDC." },
        "amount": { "type": "i128", "description": "USDC amount in base units to drain." },
        "proposed_at": { "type": "u64", "description": "Ledger timestamp (seconds) when the proposal was created." },
        "execute_after": { "type": "u64", "description": "Earliest ledger timestamp at which execute_emergency_drain may succeed. Equals proposed_at + 86400." }
      }
    }
  }
}