feat(phoenix): add Eternal state preparation

[92Infinitus92]

Adds declarative state preparation for Phoenix Eternal:

• trader collateral stress
• direct mark-price shock
• spot/perp reference-price divergence
• two-stage liquidation cascade scenarios
• live market discovery and account validation
• HTTP and MCP scenario builders
• pinned BTC and SOL behavioral fixtures

The implementation prepares protocol state only. It does not
build or execute trading or liquidation transactions.

Verification

• Phoenix unit and materialization tests
• CLI endpoint tests
• MCP tool tests
• Rust formatting and compilation
• Clippy
• pinned Phoenix Eternal and Hawkeye behavioral verification
• real orderbook transaction against the pinned fixture

Stacking

This PR is stacked on feat/pump-protocol.

Once the Pump PR is merged into develop, this branch will be rebased and retargeted to develop.

Greptile Summary

The PR adds declarative Phoenix Eternal state preparation and exposes it through HTTP and MCP builders. The latest changes also preserve cumulative Phoenix patches within one materialization pass and route MCP builder requests through the configured Studio URL.

• Adds collateral, direct-mark, reference-price, and liquidation-cascade scenario preparation.
• Adds Phoenix market discovery and account validation.
• Adds Phoenix templates, schemas, pinned fixtures, and behavioral verification.
• Integrates Phoenix materialization into the SVM and account-locking paths.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains from the previously reported issues.

No blocking failure remains.

Important Files Changed

Filename	Overview
crates/core/src/scenarios/phoenix.rs	Implements validated Phoenix Eternal account patching and scenario construction for the four preparation modes.
crates/core/src/surfnet/svm.rs	Integrates Phoenix-specific account refresh and materialization while retaining patches applied earlier in the same pass.
crates/cli/src/http/mod.rs	Adds Phoenix discovery and scenario-builder endpoints and passes the configured Studio URL into MCP sessions.
crates/mcp/src/surfpool/mod.rs	Adds Phoenix MCP builders and consistently derives backend endpoints and editor links from the configured Studio URL.
crates/core/src/scenarios/registry.rs	Registers the embedded Phoenix Eternal templates and editor schema.
crates/types/src/scenarios.rs	Extends scenario override write modes for Phoenix account patch operations.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Client[HTTP or MCP client] --> Builder[Phoenix scenario builder]
    Builder --> Remote[Remote account discovery and validation]
    Remote --> Scenario[Declarative scenario overrides]
    Scenario --> Materializer[SVM materialization]
    Materializer --> Refresh[Refresh each Phoenix account once per pass]
    Refresh --> Patch[Apply cumulative account patches]
    Patch --> Prepared[Prepared Phoenix Eternal state]

Loading

_{Reviews (6): Last reviewed commit: "fix(core): reject incomplete Phoenix ref..." | Re-trigger Greptile}

[github-actions]

• P1 — crates/core/src/surfnet/svm.rs:2806: Each Phoenix override refreshes and reinstalls the remote PerpAssetMap. Multiple same-slot overrides targeting that map therefore erase earlier patches. Refresh shared accounts once per materialization batch, or preserve already-modified target accounts.

• P1 — crates/mcp/src/surfpool/mod.rs:1116: Phoenix MCP builders hard-code port 18488, while --studio-port is configurable. All builders fail when the studio uses another port. Pass the configured studio address into the MCP server instead of using the constant.

[github-actions]

• [P1] crates/mcp/src/surfpool/mod.rs:1116: All new Phoenix MCP builders post to the compile-time default port. When --studio-port is configured, requests go to the wrong server and generated editor URLs are also invalid. Pass the runtime Studio address into Surfpool and use it for endpoints and URLs.

[92Infinitus92]

@greptileai

[github-actions]

• High – Phoenix overrides silently use stale state when refresh fails (svm.rs): Missing graph accounts or RPC errors only emit warnings; materialization then patches whatever account is already in the SVM and returns success. This defeats fetchBeforeUse, can produce an invalid Phoenix graph, and consumes the scheduled override without retry. Return an error—or skip/requeue the override—when the required refresh is incomplete.

[github-actions]

• [P1] Make cascade registration/materialization atomic — svm.rs:2733: overrides are removed before fallible Phoenix refresh/patching. If slot-0 collateral preparation fails, the RPC returns an error but the slot-1 mark shock remains scheduled, so a “failed” cascade can later execute only its destructive second stage. Restore/cancel all scenario overrides on failure, or validate/materialize before committing future stages.