Operator token rebalance: scheduled job to swap payment tokens back to SOL

[dev-jodee]

What would you like?

Goal: keep a paymaster's SOL runway stable without manual intervention.

A Kora node earns SPL tokens (payments) and spends SOL (transaction fees). Nothing converts them back today, so the operator's ability to keep paying fees drifts with the token price, and topping up SOL is a manual chore. The node should do this itself.

Shape we have in mind: a job that runs every X interval, checks the operator's token balances against configured criteria, and swaps back to SOL (Jupiter being the obvious route) when they're met.

Not already covered by what's in the repo:

• crates/lib/src/oracle/jupiter.rs uses Jupiter for price quotes during fee estimation only, never swap execution.
• crates/lib/src/plugin/plugin_gas_swap.rs is the inverse, user-driven flow: it validates a user's two-instruction "SPL in, SOL out" request. It never touches the operator's own balances.

Open questions

Proposals welcome on any of these:

1. Where the job lives. Inside the node process, or a separate binary/container an operator schedules? What happens on restart, and how are overlapping runs prevented?
2. Criteria. What should trigger a swap: absolute token balance, token value in SOL, SOL balance falling below a floor, or a target ratio? What cooldown between swaps?
3. Which balances. Fee payer ATAs, the configured payment_address ATAs, or both? With a signer pool, per-signer or aggregate?
4. Safety limits. A paymaster swapping its own funds on a schedule needs hard bounds: max slippage, max notional per run, route/program allowlist, and a dry-run mode. What belongs in v1?
5. Signing and observability. Which signer signs the swap, and how do these swaps surface in logs, metrics, and usage accounting so an operator can tell a rebalance from user traffic?

Worth flagging for whoever picks this up: this would be the first feature where Kora originates and sends its own transaction rather than co-signing a user's. The fee-payer policy and Lighthouse protections are built around the co-signing model and won't cover it, so the guardrails in question 4 aren't optional extras.

Proposed by @amilz.

Area

Other

[linear]

TOO-691

[skyyycodes]

I'd like to pick this up... happy to be assigned if nobody else is already on it.

I've spent a while reading through the codebase to understand how the existing pieces fit together before writing this so below is the shape I'd propose followed by the things I couldn't answer from the code alone.

The job can follow BalanceTracker::start_background_tracking (metrics/balance.rs:115) already a config-gated interval loop over every signer started from metrics/mod.rs:53. One task, sequential so overlapping runs can't happen within a node.

For the trigger I'd use the SOL balance rather than token balances: Swap when SOL falls below a floor and only enough to reach a target above it. Self-limiting, and the gap gives you hysteresis so it doesn't oscillate. Cooldown on top.

v1 guardrails: max slippage in bps (reject not clamp) max notional per run + rolling 24h cap. a floor it never swaps below, u64 base units end to end, and dry-run defaults so operators can watch it before it's live. Rebalance swaps should stay out of usage_limit accounting they're not user traffic.

Signing.. the signer whose ATA is drained signs its own swap so no new cross signer authority

Questions - these are the ones the reading the code didn't settle for me. (@dev-jodee @amilz)

1. Which token gets swapped? allowed_spl_paid_tokens can be an allowlist or All... so a node may hold several. Largest balance first, a configured priority order, or proportional? And with All set the node could be holding something illiquid or hook-laden, I'd lean toward a separate, explicit swap allowlist rather than inheriting the payment list. Swapping whatever showed up seems risky.

2. payment_address - external treasury or another node-owned account? I'm inferring from config not real usage. If it's a treasury, auto-swapping out of it should be optin at most, though if it's set and off-limits, the fee payer ATAs may be close to empty and the job has nothing to work with so this one decides how useful the feature is at all.

3. Multiple nodes against the same signer - real deployment? If so each gets its own loop and both would decide to swap off the same balance. in process doesn't cover that and the cooldown would need to be a distributed lock rather than a local timer.

4. In-process or separate binary? I've assumed in process above since it reuses the existing pattern, but that was your open question and I don't want to quietly answer it for you.. happy to go the other way.

5. Jupiter - execution needs the swap API, not just the price endpoint. Reuse the existing Jupiter config and key or configure routing separately?

6. Testing execution - I see external_live tests already get a JUPITER_API_KEY via the manual fork workflow so presumably that's where anything hitting Jupiter belongs. But those are read only price calls today and testing a real swap means a funded wallet spending actual tokens in CI. is that something you'd want to set up or should execution stay covered by mocked quote unit tests with the live path verified manually by an operator?

Also worth noting admin/token_util.rs::initialize_atas already sends a Kora-signed transaction so origination isn't new, the jump here is that it's autonomous and moves value.

Happy to split it up like, config + validation, then the job in dryrun, then execution.

[MayurK-cmd]

Can i be assigned for this?