simulator-client 0.7.0

Async WebSocket client for the Solana simulator backtest API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

//! Ergonomic async client for the simulator backtest WebSocket API.
//!
//! This wraps the `simulator-api` request/response protocol with helpers for common
//! workflows (create session, wait ready, continue/advance, close), while still allowing full
//! access to raw `BacktestRequest` / `BacktestResponse` when needed.
//!
//! ## Quickstart
//! ```no_run
//! use std::time::Duration;
//!
//! use simulator_client::{BacktestClient, Continue, CreateSession};
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! let client = BacktestClient::builder()
//!     .url("ws://localhost:8900/backtest")
//!     .api_key("local-dev-key")
//!     .build();
//!
//! let mut session = client
//!     .create_session(
//!         CreateSession::builder()
//!             .start_slot(100)
//!             .slot_count(10)
//!             .build(),
//!     )
//!     .await?;
//!
//! session.ensure_ready(Some(Duration::from_secs(30))).await?;
//! session
//!     .continue_until_ready(
//!         Continue::builder().advance_count(1).build(),
//!         None,
//!         |_| {},
//!     )
//!     .await?;
//! session.close(Some(Duration::from_secs(10))).await?;
//! # Ok(()) }
//! ```
//!
//! ## Lifecycle notes
//! - `BacktestClient::create_session` sends `CreateBacktestSession` and waits for
//!   `SessionCreated`, buffering other responses until the session is ready.
//! - `BacktestSession::close` sends `CloseBacktestSession` and then closes the WebSocket.
//! - Dropping `BacktestSession` sends a best-effort WebSocket close frame if a Tokio runtime
//!   is available. Call `close` explicitly to ensure server-side session cleanup.
//! - `connect_timeout` governs the initial handshake; `request_timeout` applies to send/receive
//!   operations and can be overridden per call.
//! - For streaming workflows, use `BacktestSession::responses` (consumes the session) or
//!   `next_event` to keep readiness state in sync while consuming responses.

#![forbid(unsafe_code)]

mod builders;
mod client;
mod error;
pub mod injection;
mod ranges;
pub mod rpc;
mod session;
pub mod subscriptions;
mod transaction_step;
pub mod urls;

mod pnl;

pub use builders::{Continue, CreateSession, SerializeEncodeError};
pub use client::BacktestClient;
pub use error::{BacktestClientError, BacktestClientResult};
pub use injection::{ProgramModError, build_program_injection, modify_program_via_rpc};
pub use pnl::report_agent_pnl;
pub use ranges::{RangeBound, filter_ranges};
pub use session::{
    AdvanceState, BacktestSession, ContinueResult, CoverageError, ReadyOutcome, SessionCoverage,
};
pub use simulator_api::{AvailableRange, DiscoveryFilter, split_range};
pub use subscriptions::{
    AccountDiffContext, AccountDiffNotification, AccountDiffSubscriptionHandle,
    LogSubscriptionHandle, RoutedAccountDiffNotification, SubscriptionError, SubscriptionHandle,
    SubscriptionRuntimeError, subscribe_account_diffs, subscribe_account_diffs_many,
    subscribe_program_diffs, subscribe_program_logs,
};
pub use transaction_step::{DiscoveryPause, DiscoveryStepResult};
pub use urls::{UrlError, http_to_ws_url};