Repository navigation
feat(scenarios): add Save support - state templates - #35
92Infinitus92 wants to merge 13 commits into
Conversation
There was a problem hiding this comment.
Overview. This PR adds six raw-layout Save (Solend) templates: reserve risk, rates, limits and liquidity, plus obligation position and owner. It also adds a collection-level llm_context that is prepended to each template's own context. Live tests pin each offset against mainnet accounts, and LiteSVM tests run the deployed program. The YAML offsets match the deployed pack_into_slice layout, and the tests check them against independent constants and live accounts, so I trust them. The llm_context merge in scenarios.rs and the diff_indices dedup are clean.
Main concern: the Pyth refresh in register_scenario. It changes global state as a side effect, and that deserves more scrutiny than the rest of the PR:
- Undoes earlier scenarios. It runs on every scenario registration, including scenarios with nothing to do with Pyth or Save. Say an earlier scenario made a feed stale on purpose. When an unrelated scenario is registered later, that feed is quietly "refreshed" again. The new test only covers a stale time written by the same scenario.
- Fires once, at registration only. Save's age limit is 120 s, so feeds go stale again about 300 slots after registration. Two cases suffer: an override scheduled at a large
scenario_relative_slot, and a scenario registered with a future baseslot. Transactions sent more than 2 minutes after Play hit the same problem. The README and PR body describe this as "prices at Play", which overstates what it does. - Undocumented in the YAML guidance. Only
publish_timechanges.prev_publish_timeandposted_slotkeep their old values. That's harmless for Save, but the guidance should say so.
Consider moving this into its own PR, as the description already suggests. Possible fixes are an opt-in flag, or refreshing feeds when overrides are materialized rather than at registration.
Minor:
save-obligation-positionleaves stale obligation-level fields from the original account, such asborrowing_isolated_assetandcloseable, plus the cached market values.refresh_obligationfixes the cached values but not the flags. Worth a sentence inllm_context.- The
.github/workflows/claude-review.ymladdition looks unrelated to Save and should probably not ship in this PR.
| ); | ||
|
|
||
| let current_slot = self.latest_epoch_info.absolute_slot; | ||
| match refresh_stale_price_updates(self, current_slot) { |
There was a problem hiding this comment.
This runs for every scenario registration, not just ones touching Pyth/Save, and rewrites every stale PriceUpdateV2 in the VM. Two consequences:
- A previous scenario that intentionally made a feed stale gets silently undone when any later scenario is registered (the unit test only covers a stale time written by the same scenario).
- It runs once at registration using
current_slot, ignoringbase_slot/scenario_relative_slot. With Save's 120 s window, overrides scheduled ~300+ slots out (or a futureslotarg) will still see stale prices.
Consider making this opt-in, or doing it at materialization time per slot, or at least only for feeds referenced by the scenario.
| /// published now, keeping its price. Nothing posts Pyth updates to the local VM, so a feed loaded | ||
| /// earlier would otherwise fail its readers' age checks once a scenario plays. Overrides applied | ||
| /// afterwards still write their own `publish_time`. | ||
| pub fn refresh_stale_price_updates(svm: &mut SurfnetSvm, slot: Slot) -> SurfpoolResult<usize> { |
There was a problem hiding this comment.
posted_slot and prev_publish_time are left as-is while publish_time jumps forward. That's fine for get_price_no_older_than, but any reader that checks posted_slot freshness, or the publish_time > prev_publish_time monotonicity, still sees the old feed. Worth documenting here, or bumping posted_slot to the current slot as well.
| the reserve's price account (the lookup above returns it). One feed can price several | ||
| reserves. Move price and ema_price together and scale conf and ema_conf with them: Save | ||
| rejects a price whose conf x 10 exceeds it. Save accepts a Pyth price for 120 seconds, so | ||
| keep fetchBeforeUse: true and leave publish_time unset; upstream's current value arrives when |
There was a problem hiding this comment.
This tells the model to keep fetchBeforeUse: true and leave publish_time unset so the price passes the 120 s check. But fetchBeforeUse pulls upstream's publish_time, and the override can be applied many slots after registration. The price still goes stale 120 s of local clock time after it's applied, so any later transaction (e.g. a liquidation) can fail with a stale-oracle error. Suggest saying this explicitly and recommending a fresh override (or a re-Play) right before acting.
| USDC is "500000000000000000000000000" | ||
| llm_context: | | ||
| Builds a position of exactly ONE collateral deposit and ONE borrow. Set every property: | ||
| the account's old entries are not cleared, so a field left out keeps whatever was there. |
There was a problem hiding this comment.
Besides the old deposit and borrow entries, obligation-level fields keep their old values too: borrowing_isolated_asset, closeable, and the cached *_value fields. refresh_obligation recomputes the values but not the flags. When this template runs over an obligation that had an isolated-asset borrow or was marked closeable, the result can behave unexpectedly. Consider writing those flags as fixed values, or calling them out here.
There was a problem hiding this comment.
Summary
Adds six raw-layout Save (Solend) templates (reserve risk/rates/limits/liquidity, obligation position/owner), a collection-level llm_context that gets merged into each template's own, a longer MCP params description, and a Pyth "refresh stale PriceUpdateV2" step that runs on every register_scenario. The tests are thorough. Offsets are pinned against mainnet in a separate LAYOUT table, and the program runs in LiteSVM. I hand-checked the reserve and obligation offsets (e.g. config at 299, super_max_borrow_rate u64 at 471, deposit entry 88 bytes, so borrow 0 is at 292) and the Pyth publish_time offsets (93 for Full, 94 for Partial). They match the upstream pack layouts.
Main concern
The Pyth refresh is shared, global behaviour hidden inside scenario registration (see the inline comments). It mutates every stale feed in the VM on every scenario registration, including scenarios that have nothing to do with Pyth. It also runs at registration time, not when the overrides play, so with a future base slot or later relative slots the "fresh" price can already be past Save's 120 s window. As the description says, I'd split it into its own PR, or at least limit when it runs.
Minor
.github/workflows/claude-review.yml(commit 5019f0f) has nothing to do with Save support and should land separately.- The
save-obligation-positiondeposit and borrowmarket_valuefields and the cached health values keep their old values untilrefresh_obligation. The doc says this, but a reader that skips the refresh (e.g. an off-chain UI) will see inconsistent data.
| ); | ||
|
|
||
| let current_slot = self.latest_epoch_info.absolute_slot; | ||
| match refresh_stale_price_updates(self, current_slot) { |
There was a problem hiding this comment.
This runs on every register_scenario and rewrites publish_time on every stale Pyth feed in the VM, even when the scenario has no Pyth or Save overrides. That changes global state (and emits geyser updates) without the user asking for it. It also runs at registration, not at base_slot + relative_slot when overrides materialize. If a caller passes a future slot, or overrides are scheduled later, the refreshed price can already be stale (>120 s) by the time it matters. Consider running it in materialize_overrides_for_slot when the first override of the scenario applies, or only when the scenario touches a Save or Pyth template, or putting it behind an explicit option.
| /// earlier would otherwise fail its readers' age checks once a scenario plays. Overrides applied | ||
| /// afterwards still write their own `publish_time`. `posted_slot` and `prev_publish_time` keep | ||
| /// their values, so readers that age a feed in slots are not refreshed. | ||
| pub fn refresh_stale_price_updates(svm: &mut SurfnetSvm, slot: Slot) -> SurfpoolResult<usize> { |
There was a problem hiding this comment.
get_account_owned_by over both receiver programs on every scenario registration scans every loaded feed. That's fine for small VMs, but it scales with the number of loaded feeds. Also, posted_slot is deliberately left alone, so consumers that check slot age (e.g. get_price_no_older_than variants that use posted_slot) still see the feed as stale. The refresh only half-solves staleness, and it should probably be logged or documented beyond the doc comment.
| // After the write authority, `verification_level` is `Partial { num_signatures: u8 }` (0) or | ||
| // `Full` (1); `publish_time` follows feed_id, price, conf and exponent in the price message. | ||
| let publish_time = match data.get(40) { | ||
| Some(0) => 42 + 52, |
There was a problem hiding this comment.
The verification-level match only ever checks byte 40. A future VerificationLevel variant, or a different account version, would just be skipped silently, which is safe. But nothing checks the account length, which you know (134 for PriceUpdateV2), the way the test fixture does. Adding data.len() == 134 (or >=) would protect against writing into a differently shaped account that happens to share the discriminator.
| Always 1. This template writes exactly one deposit entry | ||
| - path: borrows_len | ||
| offset: 203 | ||
| encoding: u8 |
There was a problem hiding this comment.
deposits_len/borrows_len are exposed as editable properties, but the template only writes the entry at index 0. If a user or LLM sets them to anything other than 1, the program will read leftover bytes as extra entries, or misplace the borrow, because the flat data offset depends on deposits_len. Consider making these fixed values (constants) and not user inputs, or validating them.
There was a problem hiding this comment.
Summary
This PR adds six raw-layout Save (Solend) templates: reserve risk, rates, limits and liquidity, obligation position and obligation owner. It also adds a collection-level llm_context that is prepended to each template's own context, and it moves the shared diff_indices test helper into tests/helpers.rs. Finally, it adds a Pyth "refresh stale PriceUpdateV2 on scenario registration" hook.
The template work is careful:
- The tests pin every offset against mainnet accounts.
- Each template is checked to write only its own bytes.
- The obligation layout's dependency on
deposits_len(borrows packed at204 + 88·deposits_len) is handled by forcing both lengths to 1. - The
PriceUpdateV2offsets check out: tag at byte 40;publish_timeat 93 forFulland 94 forPartial.
Main concerns
- The Pyth refresh is a global side effect on every
register_scenario. It rewrites every local Pyth feed, even when the scenario has nothing to do with Pyth or Save, and emits geyser updates for each one. A user who made a feed stale on purpose (viasurfnet_setAccountor an earlier scenario) silently gets it refreshed when they register an unrelated scenario. Consider gating it: only for scenarios that touch a Pyth feed or a Save template, or behind a flag. As the PR body suggests, a separate PR would make this easier to review. - The refresh only happens once, at registration. It runs before overrides with
scenario_relative_slot > 0apply, and it runs even whenbase_slotis in the future. A feed refreshed at registration can be stale again by the time a later override or transaction runs. The 120 s window is documented inllm_context, but this timing should be acknowledged in the code comment too. - Unrelated CI change.
.github/workflows/claude-review.ymlis unrelated to Save and should go in its own PR. The workflow itself looks reasonable: read-only tools, only runs for PRs from the same repo, and pins actions by SHA.
Minor
- Byte-for-byte duplication with other open protocol PRs (collection
llm_context, MCPparamsdescription,diff_indices) will cause merge conflicts. Whichever lands second should rebase rather than re-add these.
| ); | ||
|
|
||
| let current_slot = self.latest_epoch_info.absolute_slot; | ||
| match refresh_stale_price_updates(self, current_slot) { |
There was a problem hiding this comment.
This runs unconditionally on every scenario registration and rewrites every local PriceUpdateV2 it finds. That has two side effects:
- Registering an unrelated scenario silently un-stales a feed the user deliberately made stale outside that scenario (e.g. via
setAccount). - Every refreshed feed emits a geyser/account update.
Consider scoping it to scenarios that reference a Pyth feed or a Save template, or putting it behind an opt-in flag.
| base_slot | ||
| ); | ||
|
|
||
| let current_slot = self.latest_epoch_info.absolute_slot; |
There was a problem hiding this comment.
The refresh uses the current slot and clock even when slot (the base slot) is in the future, and it runs only once. Overrides scheduled at base_slot + relative_slot can therefore find the feed already older than Save's 120 s limit. Two options: run the refresh when the scenario's first override materializes (in materialize_overrides_for_slot) rather than at registration, or document this timing here.
| } | ||
|
|
||
| fn mark_published_at(data: &mut [u8], unix_timestamp: i64) -> bool { | ||
| if data.get(..8) != Some(PRICE_UPDATE_V2_DISCRIMINATOR.as_slice()) { |
There was a problem hiding this comment.
Only publish_time is bumped; posted_slot and prev_publish_time are left as they were. That is fine for Save. However, any reader that checks publish_time >= prev_publish_time monotonicity together with slot-based age will now see a feed that looks fresh by time and old by slot. You already mention this in the doc comment, so it is probably acceptable, but it is worth stating in the README as well, since this changes behaviour every protocol shares.
| reserves. Move price and ema_price together and scale conf and ema_conf with them: Save | ||
| rejects a price whose conf x 10 exceeds it. Save accepts a Pyth price for 120 seconds, so | ||
| keep fetchBeforeUse: true and leave publish_time unset; upstream's current value arrives when | ||
| the override plays. The price then stays valid for 120 s of Surfnet clock; play the scenario |
There was a problem hiding this comment.
"leave publish_time unset; upstream's current value arrives when the override plays" assumes the Surfnet clock is close to wall-clock time. After a time-travel forward, upstream's publish_time is behind the Surfnet clock. The Pyth refresh does not help either, because it runs before the fetchBeforeUse fetch overwrites the account, so Save rejects the price as stale. Two options: tell the LLM to set price_message.publish_time explicitly when the clock has been moved, or re-apply the refresh after a fetched Pyth account is materialized.
| USDC is "500000000000000000000000000" | ||
| llm_context: | | ||
| Builds a position of exactly ONE collateral deposit and ONE borrow. Set every property: | ||
| the account's old entries are not cleared, so a field left out keeps whatever was there. |
There was a problem hiding this comment.
Only entry 0 of each list is rewritten. Per-entry cached fields (market_value, attributed_borrow_value) and obligation flags such as borrowing_isolated_asset and closeable keep the old account's values. refresh_obligation recomputes the values, but the flags may not be recomputed. If an inherited flag changes behaviour, say so here, or have the template write those fields too.
…acle or lending templates
There was a problem hiding this comment.
Overview
The PR adds six raw-layout Save (formerly Solend) templates covering reserve risk, rates, limits and liquidity, plus obligation position and owner. It adds a shared collection-level llm_context, a longer MCP params description, and a Pyth "refresh stale feeds on registration" hook. Live and LiteSVM tests come with it.
Assessment
The templates are well documented and the offsets are pinned by live tests. I checked the PriceUpdateV2 publish_time math by hand and it is correct: 41 or 42 for the verification-level enum, plus 52. The shared/own llm_context merge is simple and has a test.
Points worth discussing
- Global side effect of the Pyth refresh. Registering any scenario with an enabled
oracleorlendingtemplate rewrites every loadedPriceUpdateV2, not only the feeds that scenario touches. That includes Kamino and Drift scenarios that have nothing to do with Save. Anyone who loaded a stale feed on purpose, outside a scenario, will see it silently refreshed. The PR body already suggests moving this to its own PR, and I'd agree: it changes behaviour for every protocol, and a protocol-specific PR shouldn't carry that. - The refresh timing doesn't match when overrides apply. Feeds are refreshed when the scenario is registered, using the clock at that moment. Overrides with a large
scenario_relative_slot(more than about 300 slots, roughly 120 s) apply after the refreshed price has already expired again. This is worth a note in the docs. Better still, run the refresh when the first override of the scenario is materialized. - Unrelated file.
.github/workflows/claude-review.yml(commit5019f0f) has nothing to do with Save and should go in a separate PR. - The refresh lists every account owned by both receiver programs on each registration. That's fine for now, but the cost grows with the number of loaded feeds.
| .store(absolute_slot, slot_overrides)?; | ||
| } | ||
|
|
||
| if reads_prices { |
There was a problem hiding this comment.
This refreshes every loaded Pyth feed at registration time, using the clock as it is now. Two consequences:
- A scenario whose price-reading overrides sit at a later
scenario_relative_slot(more than ~300 slots) gets feeds that have already aged past Save's 120 s by the time they matter. - Every scenario tagged
oracle/lendingrewrites feeds it never references, which is a cross-protocol behaviour change.
Consider refreshing during materialize_overrides_for_slot for the scenario's first slot. Or narrow it to the oracle accounts the scenario's reserves actually read, or make it opt-in.
| ## Keep the price fresh | ||
|
|
||
| Save accepts a Pyth price for **120 seconds** after its `publish_time`, measured against the Surfnet | ||
| clock, not the real one. Playing a scenario with an enabled Save or Pyth override marks every Pyth |
There was a problem hiding this comment.
This is inaccurate: the refresh triggers for any enabled template tagged oracle or lending, which includes Kamino, Drift and others, not just Save and Pyth overrides. Suggested wording: "Playing a scenario with an enabled override of a template tagged oracle or lending…"
| /// afterwards still write their own `publish_time`. `posted_slot` and `prev_publish_time` keep | ||
| /// their values, so readers that age a feed in slots are not refreshed. | ||
| pub fn refresh_stale_price_updates(svm: &mut SurfnetSvm, slot: Slot) -> SurfpoolResult<usize> { | ||
| let clock = svm.inner.get_sysvar::<Clock>(); |
There was a problem hiding this comment.
publish_time is bumped, but posted_slot and prev_publish_time stay as they were, as the doc comment says. A consumer that checks publish_time - prev_publish_time or slot-based staleness will see a large gap or an old slot. That's fine for Save, but this lives under a shared pyth module, so it's worth saying in the scenarios README that only publish_time-based age checks are satisfied.
| /// Returns the byte indices whose values differ between two buffers. | ||
| pub(super) fn diff_indices(left: &[u8], right: &[u8]) -> Vec<usize> { | ||
| left.iter() | ||
| .zip(right.iter()) |
There was a problem hiding this comment.
zip stops at the shorter buffer, so a length mismatch, such as a template that resized the account, reports no differing bytes. Consider assert_eq!(left.len(), right.len()) here, since the callers use this to prove a template wrote only its own bytes.
…ols/save # Conflicts: # crates/core/src/scenarios/registry.rs # crates/core/src/surfnet/svm.rs
There was a problem hiding this comment.
Summary
This PR adds six raw-layout templates for Save (formerly Solend): reserve risk, rates, limits and liquidity, plus obligation position and obligation owner. It also adds a collection-level llm_context that is placed before each template's own, moves diff_indices into a shared test helper, and makes the MCP params description longer.
I checked the offsets by hand against Solend's pack_into_slice (Reserve 619 bytes, Obligation 1300 bytes, deposit entries 88 bytes so borrow 0 starts at 292). They are consistent. The live tests also pin them independently of the YAML, which is a good safeguard for a program with no IDL. The llm_context merge in crates/types/src/scenarios.rs is simple, and it has a unit test.
Issues
- The PR description is out of date. Commit c1390a8 removed the Pyth refresh at Play ("drop the Pyth refresh"), but the description still lists it as a shared behaviour change. The YAML guidance now relies on
fetchBeforeUse: trueand leavespublish_timeunset instead. Please update the body so reviewers of the Studio PR don't expect a refresh. - The workflow file is out of scope.
.github/workflows/claude-review.yml(commit 5019f0f) has nothing to do with Save support. It should go in its own PR, or be dropped if it is only scaffolding for this review. - The tests depend on specific mainnet positions.
OBLIGATION_1D1BandOBLIGATION_3D2Bare real user positions that can be repaid, closed or liquidated at any time. When that happens these tests fail for reasons that have nothing to do with surfpool. The panic message infetchcovers deletion, but not a change in shape (e.g.tidy[202..204] != (1,1)). Consider choosing the positions at runtime with getProgramAccounts, or making the failure messages explain that the fixture needs replacing. - Token cost. The shared
llm_context(about 25 lines) is copied into all six templates. That is fine for one template, but anything that lists every Save template with its context to the model pays for it six times. - The MCP
paramsdescription is long. It is now a long string sent with everycall_surfnet_rpctool schema. It is useful, but it's worth checking it doesn't crowd out other tool descriptions for smaller models.
Overall the templates are well documented and carefully tested. The main asks are to fix the PR description and split out the CI workflow.
| the reserve's price account (the lookup above returns it). One feed can price several | ||
| reserves. Move price and ema_price together and scale conf and ema_conf with them: Save | ||
| rejects a price whose conf x 10 exceeds it. Save accepts a Pyth price for 120 seconds, so | ||
| keep fetchBeforeUse: true and leave publish_time unset; upstream's current value arrives when |
There was a problem hiding this comment.
This guidance assumes upstream's publish_time is within 120 s of the Surfnet clock when the override plays. The Play-time Pyth refresh was removed in c1390a8, so this only holds if the surfnet clock follows wall time closely. If the clock has drifted, or time-travel was used, the price is already stale. In that case the advice should be to set price_message.publish_time explicitly to the current clock, as the LiteSVM tests do in prepare_position. Consider describing that fallback here.
| rejects a price whose conf x 10 exceeds it. Save accepts a Pyth price for 120 seconds, so | ||
| keep fetchBeforeUse: true and leave publish_time unset; upstream's current value arrives when | ||
| the override plays. The price then stays valid for 120 s of Surfnet clock; play the scenario | ||
| again before acting later. Every other reserve the obligation lists needs a price under 120 s |
There was a problem hiding this comment.
"Every other reserve the obligation lists needs a price under 120 s old as well": for an obligation with several entries (like OBLIGATION_3D2B), that means one pyth-price-feed-v2 override per oracle in the same scenario. Say this explicitly so the LLM adds those overrides, instead of only the one for the collateral feed.
| USDC is "500000000000000000000000000" | ||
| llm_context: | | ||
| Builds a position of exactly ONE collateral deposit and ONE borrow. Set every property: | ||
| the account's old entries are not cleared, so a field left out keeps whatever was there. |
There was a problem hiding this comment.
The old entries past index 0 are harmless, because unpack only reads deposits_len/borrows_len entries. The cached health fields (deposited_value, borrowed_value, last_update.stale, …) still hold the old values until refresh_obligation runs. Anything that reads the account directly (Studio, indexers, getAccountInfo) shows inconsistent health right after this template plays. Consider either writing last_update.stale = 1 (offset 9) or mentioning this here.
| const OBLIGATION_1D1B_OWNER: &str = "6cPZda7Qt7RK8HfYtz2rjiAEeh3ztR6fQ5o2G2Frb36z"; | ||
| /// Three deposits and two borrows, with non-zero bytes past its last entry. The fixed-shape | ||
| /// template must work over an account like this, not only over a tidy one. | ||
| const OBLIGATION_3D2B: &str = "8XBi1bNjZScafhk5XrunTEW7BQCMjfx4q13xP5Lks7Qo"; |
There was a problem hiding this comment.
These are live user obligations. If one is repaid, liquidated or closed, these tests break for reasons that have nothing to do with surfpool. Consider finding a matching obligation at runtime (getProgramAccounts with dataSize 1300 plus a market memcmp, then picking one with the right deposits_len/borrows_len), or at least making the shape assertions at L229-231 say that the fixture address needs replacing.
| @@ -0,0 +1,141 @@ | |||
| name: Perform a code review when a pull request is created. | |||
There was a problem hiding this comment.
This CI workflow has nothing to do with Save support. Please split it into its own PR so it can be reviewed and reverted separately.
There was a problem hiding this comment.
Summary
This PR adds six raw-layout templates for Save (formerly Solend) v2.0.2: four for reserves (risk, rates, limits, liquidity) and two for obligations (position, owner). It also adds a collection-level llm_context that is placed before each template's own context. There is a Save README, mainnet-pinned layout tests and LiteSVM behavioural tests.
I checked the reserve offsets by hand against the Reserve::pack_into_slice layout, and they line up (oracle 107, available_amount 171, cumulative_borrow_rate 195, config 299–305, deposit/borrow limit 323/331, added_borrow_weight 445, max_util/super_max/max_liq at 470/471/479/480). The obligation offsets also follow the 88-byte deposit stride (deposit at 204, borrow at 292). The llm_context merge in scenarios.rs is simple and has a test. Overall this is solid work and well documented.
Points to address
- Stale per-entry cached fields in
save-obligation-position. The template writes only the reserve, amount and rate fields. The deposit'smarket_value/attributed_borrow_valueand the borrow'smarket_valuekeep the bytes of whatever entry was there before.refresh_obligationrecomputes market values. As far as I recall, though, the borrow-attribution logic subtracts the oldcollateral.attributed_borrow_valuefrom the deposit reserve'sattributed_borrow_valuebefore adding the new one. If so, leftover bytes from a different reserve would quietly shift that reserve's attributed total and could trip the attributed-borrow limits. Please either zero these fields (for example with extra properties) or confirm the program ignores them. If they are ignored, say so in thellm_context. deposits_len/borrows_lenare user-settable even though the template only works when both are 1. Suppose a caller leaves them out on an obligation that had 2 deposits. The program then reads the new borrow (at 292) as deposit #2, and the borrow entries from 380 onward. That is garbage, not a clean error. The engine apparently can't pin a fixed value, so consider rejecting other values, or at least make the description stronger than "Always 1".- Unrelated file:
.github/workflows/claude-review.ymlis CI infrastructure and has nothing to do with Save. It probably belongs in its own PR. - Weak registry test:
save_templates_require_caller_selected_accountschecks that each template'sllm_contextcontains the program id. Every template now inherits the collection context, which contains the program id, so this assertion is always true and doesn't test anything per template. - Fragile MCP
paramsdescription: the new text incrates/mcp/src/surfpool/mod.rsdocuments the serde externally-taggedJsonValuewire shape ({"String":...},{"Number":...}) inline in the description. That is correct for the current type but brittle. IfJsonValueis ever swapped forserde_json::Value, the description will be wrong without any error. A short comment linking the description to the type would help.
| description: >- | ||
| Market the reserves belong to. The main pool is | ||
| 4UpD2fh7xH3VP9QQaXtsS1YY3bxzWhtfpks7FatyKvdY | ||
| - path: deposits_len |
There was a problem hiding this comment.
deposits_len/borrows_len are optional properties, but the template only works when both are 1. On an obligation that had 2 deposits, leaving these out makes the program read the borrow written at 292 as deposit #2 and the borrow entries from 380 onward, which is garbage. If the engine can't pin a fixed value, consider validating this in the template or the Studio form instead of relying on the description.
| Debt in the debt token's smallest unit, times 10^18, as a decimal string. Example: 500 | ||
| USDC is "500000000000000000000000000" | ||
| llm_context: | | ||
| Builds a position of exactly ONE collateral deposit and ONE borrow. Set every property: |
There was a problem hiding this comment.
"Set every property" still leaves the deposit's market_value/attributed_borrow_value (offsets 244/260) and the borrow's market_value (356+) holding the old entry's bytes. Market values get recomputed. But if refresh_obligation subtracts the old collateral.attributed_borrow_value from the new deposit reserve's attributed_borrow_value before adding the fresh value, those leftover bytes would corrupt that reserve's attributed total. Please zero these fields as part of the template, or confirm the program ignores them and say so here.
There was a problem hiding this comment.
Summary
This PR adds six raw-layout override templates for Save (formerly Solend): four reserve templates (risk, rates, limits, liquidity) and two obligation templates (position, owner). It also adds a collection-level llm_context that goes in front of each template's own context, moves diff_indices into the shared test helpers, expands the MCP params description, and adds live and LiteSVM tests.
I checked the offsets by hand against Solend 2.0.x pack_into_slice and they match:
- Reserve: config bytes 299–305,
deposit_limit/borrow_limit323/331,added_borrow_weight_bps445 after the 56-byte rate limiter, and 470/471/479/480 for the newer fields. - Obligation: each deposit entry is 88 bytes, so the borrow entry starts at 292. The tests also pin these offsets against mainnet.
The llm_context merge in scenarios.rs is correct. The docs are thorough and spell out the 120 s Pyth staleness limit on a fork.
Issues
- The obligation template depends on
deposits_lenandborrows_lenboth being 1, but they are ordinary editable properties. Deposits and borrows sit back to back indata_flat, so the borrow at offset 292 is only read as a borrow whendeposits_len == 1. If a caller leaves a property out (for example an LLM, or a user in Studio) or sets another count, the program reads the wrong bytes. See the inline comment. - Unrelated workflow file.
.github/workflows/claude-review.yml(commit5019f0f ci: claude code review) is part of this diff but has nothing to do with Save. It should go in its own PR or be dropped here. - Test reliability.
find_obligationsrunsgetProgramAccountswith memcmp filters against the public mainnet endpoint by default. Public RPCs often throttle or refusegetProgramAccounts, and unlikefetchthis path has no retry, so the suite can fail for reasons unrelated to the code. Consider adding the same retry loop, or saying in the doc comment thatSURFPOOL_TEST_RPC_URLis effectively required. - Minor: the "liquidate above 50% LTV" example lowers
liquidation_thresholdbelow the SOL reserve'sloan_to_value_ratio. Save's config validation normally forbids that, and the override bypasses the check. This works for forcing a liquidation, but thellm_contextcould say that new borrows up to the LTV are then liquidatable straight away.
| description: >- | ||
| Market the reserves belong to. The main pool is | ||
| 4UpD2fh7xH3VP9QQaXtsS1YY3bxzWhtfpks7FatyKvdY | ||
| - path: deposits_len |
There was a problem hiding this comment.
deposits_len and borrows_len have to be exactly 1. Deposits and borrows are packed back to back in data_flat, so borrows.0 at offset 292 is only a borrow when deposits_len == 1. Because both counts are regular editable properties, a caller can leave one out, which keeps the old count (e.g. 3 on a 3×2 obligation), or set another value. The program then reads the borrow bytes this template wrote as a second deposit. Could these two be fixed values the template always writes, or at least rejected unless they equal 1? Otherwise the template's correctness depends on the caller reading the description.
| @@ -0,0 +1,141 @@ | |||
| name: Perform a code review when a pull request is created. | |||
There was a problem hiding this comment.
This CI workflow has nothing to do with Save support. It should go in its own PR (or be dropped here) so the protocol change can be reviewed and reverted on its own.
There was a problem hiding this comment.
Summary
Adds six raw-layout override templates for Save (formerly Solend) v2.0.2: reserve risk, rates, limits and liquidity, obligation position and obligation owner. It also adds a collection-level llm_context that is prepended to each template's own context, moves diff_indices into a shared test helper, and makes the MCP params description longer. The tests are thorough. They pin every offset to an independent layout table, check that each template writes only its own bytes, run the llm_context lookups against mainnet, and run the deployed program in LiteSVM to show that the threshold and price levers make a position liquidatable.
I checked the Reserve and Obligation offsets by hand against Solend's pack_into_slice. All of them match, including rate_limiter ending at 445, super_max_borrow_rate at 471 as a u64, deposits at 204 with a stride of 88, and the first borrow at 292. The llm_context merge in scenarios.rs handles all four Option combinations correctly.
Overall the PR looks solid. The issues below are minor.
Points that aren't tied to one line
- Unrelated file:
.github/workflows/claude-review.ymlhas nothing to do with Save support. It probably belongs in its own PR, or should be dropped if it is already onmain. - Duplicated lookup text: the collection
llm_context, which contains the reserve and obligation lookup steps, is now prepended to every Save template,save-obligation-ownerincluded. The obligation-address paragraph then appears again insave-obligation-position's own context. This makes the AI context bigger and repeats itself. Consider removing the duplicate in the template. Nullnot covered: the new MCPparamsdescription lists everyJsonValuevariant exceptNull. A model that needs to passnullhas no example to follow.
|
|
||
| assert_eq!(health.sol_market_price, pyth_price, "SOL priced from Pyth"); | ||
| let ratio = health.borrowed_value as f64 / health.unhealthy_borrow_value as f64; | ||
| assert!((0.8..0.87).contains(&ratio), "borrowed/unhealthy {ratio}"); |
There was a problem hiding this comment.
This test can break when mainnet settings change. The 0.8..0.87 band only holds while SOL's mainnet liquidation_threshold is 72, because 0.6/0.72 ≈ 0.833. If governance moves it to 75 (giving 0.80) or to 70 (giving 0.857, still inside), the test passes or fails for reasons unrelated to the template. Derive the expected ratio from the fetched reserve instead, e.g. BORROW_SHARE * 100 / sol[302], and allow a small tolerance.
| for reserve in [&accounts[1].data, &accounts[2].data] { | ||
| let (ltv, threshold, max_threshold) = (reserve[300], reserve[302], reserve[480]); | ||
| assert!( | ||
| ltv < threshold && threshold <= max_threshold && max_threshold <= 100, |
There was a problem hiding this comment.
ltv < threshold is a strict inequality on live governance values. A reserve configured with LTV equal to the threshold is valid in Save, and it would fail this layout test even though no offset is wrong. <= is enough to catch a shifted offset.
| serde_json::json!({ | ||
| "price_message.price": price / 2, | ||
| "price_message.ema_price": ema / 2, | ||
| }), |
There was a problem hiding this comment.
The README and the reserve-risk llm_context both say to scale conf and ema_conf along with the price, because Save rejects a price when conf × 10 > price. This test halves only price and ema_price, so it passes only because SOL's current conf is small. Halving conf and ema_conf here as well would make the test follow the documented recipe and stop it depending on live confidence values.
| description: >- | ||
| Share of the collateral's value that can be borrowed against, in whole percent. | ||
| Example: 65 | ||
| - path: config.liquidation_threshold |
There was a problem hiding this comment.
Minor: the properties are listed out of offset order, with liquidation_threshold (302) before liquidation_bonus (301). If this ordering is deliberate for the UI, ignore this. Otherwise, ordering by offset makes the YAML easier to compare with LAYOUT in the tests.
| encoding: u8 | ||
| label: Number of deposits | ||
| description: >- | ||
| Must be 1: this template writes exactly one deposit entry, and any other count makes the |
There was a problem hiding this comment.
The description says deposits_len and borrows_len must be 1, but nothing enforces it. A user can enter 2, and the program will then read stale entries left in the account. If the raw-layout schema supports a constant or a fixed value, use it here. If not, consider removing these two fields from the template and writing 1 as a fixed value, so no one can set the wrong count by mistake.
There was a problem hiding this comment.
It has been changed long time ago I believe, there are a lot of integration tests, so please update accordingly
| @@ -0,0 +1,193 @@ | |||
| # Save | |||
There was a problem hiding this comment.
Do we have any moving parts like with Phoenix, that one change affects the entire protocol and we should update it?
Adds Save (formerly Solend,
So1endDq2YkqhipRh3WViPa8hdiSpxWy6z3Z6tMCpAo) state prep.Save publishes no IDL and its accounts carry no discriminator, so the six templates use raw layouts with offsets from the deployed build's
pack_into_slice: reserve risk, rates, limits and liquidity, obligation position (one deposit and one borrow) and obligation owner. Prices move with the existingpyth-price-feed-v2.llm_context, the MCPparamsdescription and thediff_indicestest helper.Prices on a fork: nothing publishes Pyth prices on a surfnet, and Save accepts a price for 120 seconds of Surfnet clock with no setting for it. A price override with
fetchBeforeUse: trueloads the current price when it plays; the README's "Prices on a fork" section covers the other reserves an obligation reads and how to reload them. Once keep-alive (solana-foundation#906) lands, a follow-up will keep the prices published instead.Tests: live tests pin every offset against real mainnet reserves and obligations, check that each template writes only its own bytes, and run the
llm_contextreserve and obligation lookups against mainnet. Behavioural tests run the deployed program in LiteSVM: the threshold and price levers make a position liquidatable. Verified in Studio with real transactions through the editor, AI prompts and the chip.Studio: LimeChain/surfpool-web-ui#29