simulator_client/
builders.rs

1use std::collections::{BTreeMap, BTreeSet};
2
3use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64};
4use bon::Builder;
5use simulator_api::{
6    AccountData, AccountModifications, BinaryEncoding, ContinueParams,
7    CreateBacktestSessionRequest, CreateBacktestSessionRequestV1, CreateSessionParams,
8};
9use solana_address::Address;
10use solana_client::rpc_client::SerializableTransaction;
11use thiserror::Error;
12
13use crate::BacktestClientError;
14
15/// Error serializing a transaction for injection.
16#[derive(Debug, Error)]
17pub enum SerializeEncodeError {
18    #[error("bincode serialization error: {0}")]
19    Bincode(#[from] bincode::error::EncodeError),
20}
21
22fn serialize_to_base64(value: &impl serde::Serialize) -> Result<String, SerializeEncodeError> {
23    let bytes = bincode::serde::encode_to_vec(
24        value,
25        bincode::config::standard()
26            .with_fixed_int_encoding()
27            .with_little_endian(),
28    )?;
29    Ok(BASE64.encode(&bytes))
30}
31
32/// Builder for `CreateBacktestSession`.
33///
34/// Set either `end_slot` or `slot_count` (not both). Use the helper methods to
35/// add account filters or preload programs.
36#[derive(Debug, Clone, Builder)]
37pub struct CreateSession {
38    pub start_slot: u64,
39
40    pub end_slot: Option<u64>,
41
42    pub slot_count: Option<u64>,
43
44    #[builder(default)]
45    pub signer_filter: BTreeSet<Address>,
46
47    #[builder(default)]
48    pub preload_programs: BTreeSet<Address>,
49
50    #[builder(default)]
51    pub preload_account_bundles: Vec<String>,
52
53    /// When true, include a session summary with transaction statistics in the Completed response.
54    #[builder(default)]
55    pub send_summary: bool,
56
57    /// When true, ask manager to create all available sessions in the target epoch.
58    #[builder(default)]
59    pub parallel: bool,
60
61    pub disconnect_timeout_secs: Option<u16>,
62}
63
64impl CreateSession {
65    /// Add an account to the signer filter.
66    pub fn add_signer_filter(mut self, address: Address) -> Self {
67        self.signer_filter.insert(address);
68        self
69    }
70
71    /// Add a program to preload before the first continue.
72    pub fn add_preload_program(mut self, address: Address) -> Self {
73        self.preload_programs.insert(address);
74        self
75    }
76
77    /// Convert the builder into API parameters, validating slot options.
78    pub fn into_params(self) -> Result<CreateSessionParams, BacktestClientError> {
79        let end_slot = match (self.end_slot, self.slot_count) {
80            (Some(_), Some(_)) => {
81                return Err(BacktestClientError::InvalidParams {
82                    message: "CreateSession: set only one of end_slot or slot_count".to_string(),
83                });
84            }
85            (Some(end_slot), None) => end_slot,
86            (None, Some(slot_count)) => {
87                self.start_slot.checked_add(slot_count).ok_or_else(|| {
88                    BacktestClientError::InvalidParams {
89                        message: "CreateSession: start_slot + slot_count overflow".to_string(),
90                    }
91                })?
92            }
93            (None, None) => {
94                return Err(BacktestClientError::InvalidParams {
95                    message: "CreateSession: must set end_slot or slot_count".to_string(),
96                });
97            }
98        };
99
100        if end_slot < self.start_slot {
101            return Err(BacktestClientError::InvalidParams {
102                message: format!(
103                    "CreateSession: end_slot ({end_slot}) must be >= start_slot ({})",
104                    self.start_slot
105                ),
106            });
107        }
108
109        Ok(CreateSessionParams {
110            start_slot: self.start_slot,
111            end_slot,
112            signer_filter: self.signer_filter,
113            preload_programs: self.preload_programs,
114            preload_account_bundles: self.preload_account_bundles,
115            send_summary: self.send_summary,
116            disconnect_timeout_secs: self.disconnect_timeout_secs,
117        })
118    }
119
120    /// Convert the builder into versioned create request payload.
121    pub fn into_request(self) -> Result<CreateBacktestSessionRequest, BacktestClientError> {
122        let parallel = self.parallel;
123        let request = self.into_params()?;
124        if parallel {
125            Ok(CreateBacktestSessionRequestV1 { request, parallel }.into())
126        } else {
127            Ok(request.into())
128        }
129    }
130}
131
132/// Builder for `Continue` requests.
133///
134/// Use this to advance the simulation, inject transactions, or patch accounts.
135#[derive(Debug, Builder)]
136pub struct Continue {
137    #[builder(default = ContinueParams::default_advance_count())]
138    pub advance_count: u64,
139
140    #[builder(default)]
141    pub transactions: Vec<String>,
142
143    #[builder(default)]
144    pub modify_accounts: BTreeMap<Address, AccountData>,
145}
146
147impl Continue {
148    /// Append a base64-encoded transaction payload.
149    pub fn push_transaction_base64(mut self, data: impl Into<String>) -> Self {
150        self.transactions.push(data.into());
151        self
152    }
153
154    /// Append a raw transaction payload encoded as base64.
155    pub fn push_transaction_bytes(mut self, bytes: &[u8]) -> Self {
156        self.transactions.push(BinaryEncoding::Base64.encode(bytes));
157        self
158    }
159
160    /// Append a serializable transaction encoded as base64.
161    pub fn push_transaction(
162        mut self,
163        transaction: &impl SerializableTransaction,
164    ) -> Result<Self, SerializeEncodeError> {
165        self.transactions.push(serialize_to_base64(&transaction)?);
166        Ok(self)
167    }
168
169    /// Modify an account state prior to execution.
170    pub fn modify_account(mut self, address: Address, account: AccountData) -> Self {
171        self.modify_accounts.insert(address, account);
172        self
173    }
174
175    /// Convert the builder into API parameters.
176    pub fn into_params(self) -> ContinueParams {
177        ContinueParams {
178            advance_count: self.advance_count,
179            transactions: self.transactions,
180            modify_account_states: AccountModifications(self.modify_accounts),
181        }
182    }
183}
simulator_client/builders.rs

simulator_client/
builders.rs
