Skip to content

Commit d9fd2a5

Browse files
authored
feat: add opt-in strict snapshot loading (solana-foundation#905)
1 parent 7e020f7 commit d9fd2a5

8 files changed

Lines changed: 796 additions & 27 deletions

File tree

‎README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,17 @@ surfpool start --help
130130

131131
Is documenting all the options available.
132132

133+
To fail startup when a declared snapshot account cannot be loaded, use:
134+
135+
```console
136+
surfpool start --snapshot dependencies.json --strict-snapshot
137+
```
138+
139+
The flag requires `--snapshot` and preserves its JSON format (`null` fetches upstream).
140+
Failures, including missing required program data, abort before RPC startup; default
141+
loading remains best effort. Strict loading neither discovers protocol dependencies
142+
nor rolls back partial database writes.
143+
133144
## Crypto Infrastructure as Code: A New Standard in Web3
134145

135146
Infrastructure as code (IaC) transforms how teams deploy and operate Solana programs:

‎crates/cli/src/cli/mod.rs‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -382,6 +382,9 @@ pub struct StartAccountOptions {
382382
long_help = "JSON account snapshot to preload. Can be specified multiple times.\n\nThe snapshot format matches the surfnet_exportSnapshot RPC output. Account values can be null to fetch the account from the remote RPC. Later files override earlier files for duplicate keys.\n\nExample: surfpool start --snapshot ./snapshot1.json --snapshot ./snapshot2.json"
383383
)]
384384
pub snapshot: Vec<String>,
385+
/// Fail startup if any snapshot account cannot be loaded.
386+
#[arg(long = "strict-snapshot", requires = "snapshot")]
387+
pub strict_snapshot: bool,
385388
/// Database connection URL for persistent Surfnet state.
386389
#[arg(
387390
long = "db",
@@ -732,6 +735,7 @@ impl StartSimnet {
732735
skip_blockhash_check: self.svm.skip_blockhash_check,
733736
surfnet_id: self.accounts.surfnet_id.clone(),
734737
snapshot,
738+
strict_snapshot: self.accounts.strict_snapshot,
735739
genesis_hash: self.network.genesis_hash,
736740
}
737741
}
@@ -1402,6 +1406,28 @@ mod tests {
14021406
assert_eq!(cmd.project.runbooks, vec!["deploy", "seed"]);
14031407
}
14041408

1409+
#[test]
1410+
fn strict_snapshot_requires_snapshot_and_reaches_config() {
1411+
let err = Opts::try_parse_from(["surfpool", "start", "--strict-snapshot"])
1412+
.expect_err("strict snapshot requires a snapshot file");
1413+
assert_eq!(err.kind(), clap::error::ErrorKind::MissingRequiredArgument);
1414+
1415+
let default_cmd = parse_start(&["surfpool", "start"]);
1416+
assert!(
1417+
!default_cmd
1418+
.simnet_config(vec![], BTreeMap::new())
1419+
.strict_snapshot
1420+
);
1421+
let cmd = parse_start(&[
1422+
"surfpool",
1423+
"start",
1424+
"--snapshot",
1425+
"snapshot.json",
1426+
"--strict-snapshot",
1427+
]);
1428+
assert!(cmd.simnet_config(vec![], BTreeMap::new()).strict_snapshot);
1429+
}
1430+
14051431
#[test]
14061432
fn start_parser_keeps_rpc_network_conflict() {
14071433
let err = Opts::try_parse_from([
Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
use std::{
2+
fs::{self, File},
3+
net::{TcpListener, TcpStream},
4+
process::{Child, Command, Stdio},
5+
thread,
6+
time::{Duration, Instant},
7+
};
8+
9+
struct ChildGuard(Child);
10+
11+
impl Drop for ChildGuard {
12+
fn drop(&mut self) {
13+
let _ = self.0.kill();
14+
let _ = self.0.wait();
15+
}
16+
}
17+
18+
#[test]
19+
fn strict_snapshot_offline_missing_account_fails_startup() {
20+
let dir = tempfile::tempdir().unwrap();
21+
let address = "11111111111111111111111111111111";
22+
fs::write(
23+
dir.path().join("snapshot.json"),
24+
format!("{{\"{address}\":null}}"),
25+
)
26+
.unwrap();
27+
28+
// Hold all three sockets until ports have been selected so they are distinct.
29+
let listeners: Vec<_> = (0..3)
30+
.map(|_| TcpListener::bind(("127.0.0.1", 0)).unwrap())
31+
.collect();
32+
let ports: Vec<_> = listeners
33+
.iter()
34+
.map(|l| l.local_addr().unwrap().port())
35+
.collect();
36+
drop(listeners);
37+
let stdout = dir.path().join("stdout.txt");
38+
let stderr = dir.path().join("stderr.txt");
39+
// Files avoid a full output pipe blocking the child before it exits.
40+
let mut child = ChildGuard(
41+
Command::new(env!("CARGO_BIN_EXE_surfpool"))
42+
.args([
43+
"start",
44+
"--offline",
45+
"--no-deploy",
46+
"--no-tui",
47+
"--no-studio",
48+
"--airdrop-amount",
49+
"0",
50+
"--snapshot",
51+
"snapshot.json",
52+
"--strict-snapshot",
53+
"--port",
54+
&ports[0].to_string(),
55+
"--ws-port",
56+
&ports[1].to_string(),
57+
"--studio-port",
58+
&ports[2].to_string(),
59+
])
60+
.current_dir(dir.path())
61+
.stdout(Stdio::from(File::create(&stdout).unwrap()))
62+
.stderr(Stdio::from(File::create(&stderr).unwrap()))
63+
.spawn()
64+
.expect("start surfpool"),
65+
);
66+
let deadline = Instant::now() + Duration::from_secs(30);
67+
let mut rpc_observed = false;
68+
let status = loop {
69+
rpc_observed |= TcpStream::connect(("127.0.0.1", ports[0])).is_ok();
70+
if let Some(status) = child.0.try_wait().expect("poll surfpool") {
71+
break status;
72+
}
73+
assert!(
74+
Instant::now() < deadline,
75+
"surfpool did not exit within 30 seconds"
76+
);
77+
thread::sleep(Duration::from_millis(50));
78+
};
79+
let output = format!(
80+
"{}\n{}",
81+
fs::read_to_string(stdout).unwrap(),
82+
fs::read_to_string(stderr).unwrap()
83+
);
84+
assert!(!status.success(), "unexpected success: {output}");
85+
assert!(
86+
output.contains(address),
87+
"missing account address: {output}"
88+
);
89+
assert!(
90+
!output.contains("Preloaded"),
91+
"unexpected preload success: {output}"
92+
);
93+
assert!(
94+
!rpc_observed,
95+
"RPC became available before failure: {output}"
96+
);
97+
}

‎crates/core/src/runloops/mod.rs‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -237,10 +237,11 @@ pub async fn start_local_surfnet_runloop(
237237
// Load snapshot accounts if provided
238238
if !simnet.snapshot.is_empty() {
239239
match svm_locker
240-
.load_snapshot(
240+
.load_snapshot_with_options(
241241
&simnet.snapshot,
242242
remote_rpc_client.as_ref(),
243243
CommitmentConfig::confirmed(),
244+
simnet.strict_snapshot,
244245
)
245246
.await
246247
{
@@ -253,6 +254,9 @@ pub async fn start_local_surfnet_runloop(
253254
});
254255
}
255256
Err(e) => {
257+
if simnet.strict_snapshot {
258+
return Err(e.into());
259+
}
256260
let _ = svm_locker.with_svm_reader(|svm| {
257261
svm.simnet_events_tx
258262
.warn(format!("Error loading snapshot accounts: {}", e))

0 commit comments

Comments
 (0)