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 Phoenix Eternal scenario templates, typed state patching, live account validation, and a dedicated MCP collateral-scenario builder.

• Registers Phoenix Eternal protocol metadata and editor templates.
• Adds collateral, direct-mark, and reference-price account preparation.
• Integrates Phoenix materialization into the Surfnet SVM.
• Adds MCP and behavioral coverage for Phoenix scenario creation.

Confidence Score: 4/5

The PR is not yet safe to merge because MCP scenario staging still fails whenever Studio is bound exclusively away from IPv4 loopback or runs on a non-default port.

The shared stage_scenario path remains fixed to 127.0.0.1:18488, while Studio supports configurable bind hosts and ports and standalone MCP has no endpoint configuration path; the new Phoenix builder delegates directly to this staging method.

Files Needing Attention: crates/mcp/src/surfpool/mod.rs, crates/cli/src/http/mod.rs

Important Files Changed

Filename	Overview
crates/core/src/scenarios/protocols/phoenix-eternal/v1/state_builder.rs	Adds typed Phoenix account discovery, validation, scenario construction, and byte-constrained collateral and price patching.
crates/core/src/surfnet/svm.rs	Routes Phoenix-owned accounts through the typed patcher and preserves cumulative same-slot account changes.
crates/mcp/src/surfpool/mod.rs	Adds the Phoenix collateral builder, but the shared staging path still targets a fixed loopback host and port.
crates/core/src/scenarios/protocols/phoenix-eternal/v1/overrides.yaml	Defines Phoenix collateral, direct-mark, and reference-divergence templates and their market metadata.
crates/core/src/scenarios/registry.rs	Registers the Phoenix protocol schema and templates with the scenario catalog.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Client[MCP client] --> Builder[Phoenix scenario builder]
  Builder --> Surfnet[Read and validate live Surfnet account]
  Surfnet --> Scenario[Build declarative scenario]
  Scenario --> Stage[POST /v1/scenarios]
  Stage --> Studio[Studio scenario service]
  Studio --> SVM[Materialize Phoenix account override]

Loading

_{Reviews (17): Last reviewed commit: "feat(phoenix): add Eternal state prepara..." | Re-trigger Greptile}

Context used:

• Knowledge Base — Scenario execution
• Knowledge Base — MCP server integration

[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.

[92Infinitus92]

@greptileai

[greptile-apps]

Standalone staging ignores configured port

When standalone surfpool mcp is used with a Studio server on a non-default --studio-port, Surfpool::new() still targets 127.0.0.1:18488, causing Phoenix scenario staging to post to the wrong server and fail.

Knowledge Base Used: MCP server integration

Prompt To Fix With AI

This is a comment left during a code review.
Path: crates/mcp/src/surfpool/mod.rs
Line: 179-184

Comment:
**Standalone staging ignores configured port**

When standalone `surfpool mcp` is used with a Studio server on a non-default `--studio-port`, `Surfpool::new()` still targets `127.0.0.1:18488`, causing Phoenix scenario staging to post to the wrong server and fail.

**Knowledge Base Used:** [MCP server integration](https://app.greptile.com/limechain/-/custom-context/knowledge-base/limechain/surfpool/-/docs/mcp-server.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

IPv6 staging URL is malformed

When Studio binds to a specific unbracketed IPv6 address such as ::1, this interpolation produces http://::1:<port> instead of a bracketed URL, causing Phoenix MCP builders to fail before reaching the scenario endpoint.

Knowledge Base Used:

• Command-line operations
• MCP server integration

Prompt To Fix With AI

This is a comment left during a code review.
Path: crates/cli/src/http/mod.rs
Line: 79-84

Comment:
**IPv6 staging URL is malformed**

When Studio binds to a specific unbracketed IPv6 address such as `::1`, this interpolation produces `http://::1:<port>` instead of a bracketed URL, causing Phoenix MCP builders to fail before reaching the scenario endpoint.

**Knowledge Base Used:**
- [Command-line operations](https://app.greptile.com/limechain/-/custom-context/knowledge-base/limechain/surfpool/-/docs/command-line-operations.md)
- [MCP server integration](https://app.greptile.com/limechain/-/custom-context/knowledge-base/limechain/surfpool/-/docs/mcp-server.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[92Infinitus92]

@greptileai This axis is intentionally reverted to the established team convention: the MCP tools use the shared default-port constant inline, exactly as the pump tool on the base branch does. The constant's own name (CHANGE_TO_DEFAULT_STUDIO_PORT_ONCE_SUPERVISOR_MERGED) is the tracked follow-up — runtime addresses arrive with the supervisor work, for every tool at once, rather than piecemeal per PR. A non-default Studio port is not a supported configuration today anyway: the dashboard's own /config fetch breaks on it, independent of MCP. Standalone surfpool mcp has no configuration channel at all (the command takes no flags), so the constant is that mode's contract by construction. So please check your score as I believe is unproper 4/5

[greptile-apps]

That context is valid. Given the current contract, the inline CHANGE_TO_DEFAULT_STUDIO_PORT_ONCE_SUPERVISOR_MERGED usage is intentional and consistent with the existing Pump MCP tool; a non-default Studio listener is not a supported configuration today, and runtime endpoint plumbing is deliberately deferred to the supervisor work. I’m withdrawing this finding for the current PR rather than treating the fixed default port as a merge blocker.