Skip to content

Commit 2a01556

Browse files
authored
feat(core/scenarios): introduce keep alive feature (solana-foundation#906)
1 parent d552d45 commit 2a01556

10 files changed

Lines changed: 1140 additions & 84 deletions

File tree

‎Cargo.lock‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -538,7 +538,7 @@ pub async fn start_block_production_runloop(
538538
));
539539
}
540540

541-
if let Err(e) = svm_locker.with_svm_writer(|svm_writer| svm_writer.apply_time_travel(clock)) {
541+
if let Err(e) = svm_locker.apply_time_travel(clock, &remote_client_with_commitment).await {
542542
svm_locker.simnet_events_tx().error(format!("Failed to time travel: {e}"));
543543
}
544544
}
@@ -551,7 +551,8 @@ pub async fn start_block_production_runloop(
551551
}
552552

553553
let epoch_info = svm_locker
554-
.with_svm_writer(|svm_writer| svm_writer.apply_time_travel(clock))
554+
.apply_time_travel(clock, &remote_client_with_commitment)
555+
.await
555556
.map_err(|e| e.to_string());
556557

557558
// Send confirmation back

‎crates/core/src/scenarios/README.md‎

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,8 @@ non-numeric segment on an array is a hard error, never a silent write elsewhere.
3838

3939
An override is applied once, when the surfnet produces its slot; nothing is applied during the
4040
registration call. Its resulting account state remains in later slots until a transaction or another
41-
override writes that account again.
41+
override writes that account again. The exception is [keep-alive](#keep-alive), which rewrites the
42+
fields a protocol's own off-chain actor would every slot.
4243
`surfnet_timeTravel` produces only the next slot before it jumps, so overrides scheduled in the slots
4344
it skips are never applied; step one slot at a time to play a scenario under a paused clock.
4445

@@ -82,6 +83,48 @@ Each collection uses exactly one write model: an IDL-backed collection cannot se
8283
compiled into Surfpool's built-in template registry; there is no runtime raw-layout registration
8384
endpoint.
8485

86+
### Keep-alive
87+
88+
Some accounts are rewritten every slot by the protocol's own off-chain actor, such as a market maker
89+
republishing its quote. Nobody runs those actors against a surfnet, so a template can import
90+
keep-alive templates: ordinary override templates in a separate file of the protocol, loaded with
91+
`TemplateRegistry::load_keep_alive` and never offered in Studio or MCP. A template imports them in its
92+
`keep_alive` list, or a whole file at its top level; a template's own list replaces the file's, and
93+
`keep_alive: []` turns it off.
94+
95+
```yaml
96+
templates:
97+
- id: example-vault-balance
98+
properties:
99+
- path: balance
100+
offset: 64
101+
encoding: u64
102+
- path: oracle
103+
type: input
104+
value_type: pubkey
105+
description: The oracle of the vault's market
106+
keep_alive:
107+
- template: example-oracle-fresh
108+
address: { type: input, value: oracle }
109+
values: { publication_slot: $slot, publication_time: $unix_ms }
110+
```
111+
112+
| `address` | Writes |
113+
|---|---|
114+
| `{ type: override }` | the account the importing override writes |
115+
| `{ type: input, value: oracle }` | the pubkey given in that `input` property (`value_type: pubkey`, never written) |
116+
| `{ type: pubkey, value: <address> }` | a fixed account |
117+
| `{ type: pda, program_id, seeds }` | a derived account; seeds resolve against the override's values |
118+
119+
`$slot`, `$slot±N` and `$unix_s`/`ms`/`us`/`ns` in `values` are filled from the slot and its Clock
120+
time; other values are written as given.
121+
122+
Keep-alive starts in the slot the importing override plays and rewrites its fields every slot, after
123+
that slot's overrides, until the network is reset. An override of one of those fields therefore
124+
never takes effect. An account not yet in the surfnet is fetched from the remote first, unless it,
125+
or its owner with its owned accounts, is marked offline. Keep-alive is kept in memory only: after a restart on a persistent database it stops
126+
until an importing override plays again.
127+
85128
### Override Templates
86129
Directly using the `surfnet_registerScenario` endpoint requires building out a map of account keys that are specific to the schema of the account that is being written to.
87130
This is a cumbersome process in most cases.
@@ -104,6 +147,7 @@ The following steps can be followed to natively support a protocol:
104147
1. This file is what will populate Surfpool Studio's UI with the protocol details. The Pyth override file linked above produces the following in the UI:
105148
![Pyth Overrides](../../../..//doc/assets/pyth-overrides.png)
106149
4. Update the [registry.rs](./registry.rs) file. A small amount of code has to be written to wire together the template registry, the `overrides.yaml`, and the `idl.json`. See the `load_pyth_overrides` and `load_jupiter_overrides` functions for examples.
150+
5. If the protocol's own off-chain actor rewrites accounts every slot, add a keep-alive file with the templates it writes, load it with `load_keep_alive`, and import them from the override templates. See [Keep-alive](#keep-alive).
107151

108152
If any part of these instructions are beyond your skill level or availability, but you'd like to see a specific protocol supported, feel free to [Open an Issue to Support a new Protocol](https://github.com/solana-foundation/surfpool/issues/new?template=native-scenario-support-for-protocol.md)!
109153
Opening an issue to signal interest is a big help.
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
//! Keep-alive covers what a protocol's own off-chain actor rewrites every slot, such as a market
2+
//! maker republishing its quote. Nobody runs those actors against a surfnet, so once a scenario's
3+
//! override touches an account, the surfnet applies the keep-alive templates its template imports
4+
//! every slot, as ordinary overrides, until the network is reset.
5+
6+
use std::collections::HashMap;
7+
8+
use solana_pubkey::Pubkey;
9+
10+
/// An account a scenario's override wrote through a template that imports keep-alive.
11+
#[derive(Clone, Debug)]
12+
pub struct KeepAliveSource {
13+
pub template: String,
14+
/// The address the override wrote.
15+
pub address: Pubkey,
16+
/// The override's values, which input and PDA addresses resolve against.
17+
pub values: HashMap<String, serde_json::Value>,
18+
}
19+
20+
/// Binds a template's keep-alive import to the account it rewrites every slot, resolved when an
21+
/// override of that template first touched it.
22+
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
23+
pub struct KeepAliveBinding {
24+
/// The importing template's ID.
25+
pub template: String,
26+
/// The import's index in that template's `keep_alive` list.
27+
pub import: usize,
28+
/// The address the import rewrites.
29+
pub address: Pubkey,
30+
}

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
pub mod keep_alive;
12
pub mod protocols;
23
pub mod registry;
34

0 commit comments

Comments
 (0)