Optimizer Design

The optimizer coordinates your bot fleet. It deploys bots to validators, pushes configuration down, and receives signals back. The design work is deciding what those messages carry.

Designing Your Messages

Before writing any code, answer three questions:

• What does the bot need to know? Thresholds, weights, target accounts, rate limits — anything the optimizer controls at runtime goes into AdjustConfiguration.
• What does the bot report back? PnL, latency, price signals, fill rates — anything the optimizer needs to make decisions.
• When does the optimizer act? What state change triggers a new configuration push?

These answers define your message interface. The bot side lives in message.rs and configuration.rs. The optimizer side lives in manager/bot/message.go.

Where to Look in the Code

manager/bot/message.go — implement your inbound message handlers here. OnCustom is called every time the bot sends a custom outbound message:

func (in *internalBot) OnCustom(pair *catmsg.Pair) error {
    // pair.Key identifies the message type
    // pair.Value carries the payload
    // update your state here, push new config if needed
    return nil
}

manager/bot/bot.go — use Bot.Send(msg) to push messages down to a bot, including AdjustConfiguration.

Example: PnL-Based Spend Control

The bot reports trade results. The optimizer tracks rolling PnL per bot and adjusts max_spend_lamports in response.

Bot side (message.rs):

pub enum CustomMessageOutbound {
    TradeResult { pnl: f64, slot: u64 },
}

Optimizer side (manager/bot/message.go):

func (in *internalBot) OnCustom(pair *catmsg.Pair) error {
    // decode pair.Value into TradeResult
    // update rolling PnL tracker
    // if PnL below threshold, call Bot.Send with new AdjustConfiguration
    return nil
}

When the bot’s PnL drops below the threshold, the optimizer pushes a new Configuration with max_spend_lamports: 0 to pause it. When performance recovers, it opens the bot back up.

For more strategy patterns, see Use Cases.