feat(scenarios): add HumidiFi state preparation

[92Infinitus92]

HumidiFi markets can now be discovered and prepared through the existing scenario and MCP paths. Adds fair-value, persistent-freshness, stale-quote and liquidity scenarios, with an explicitly selected market and guarded raw-layout writes. Fair-value scenarios fetch the market before Play, then keep its quote fresh locally.

Stacked on #15 (feat/scenarios/raw-layout). Reuses its raw-layout materializer and registry loader, adding an optional eight-byte XOR mask for HumidiFi account fields.

Validation:

• cargo fmt --all -- --check
• cargo test --offline --workspace --features surfpool-core/ignore_tests_ci -- --test-threads=1: 943 passed, 0 failed, 66 ignored.
• cargo test --offline -p surfpool-core --features integration-tests tests::humidifi -- --test-threads=1 --nocapture: 10 passed, including deployed-program swap and exact account-byte checks.
• cargo clippy --offline --workspace --all-targets: exit 0, existing warnings.
• cargo build --offline --release --features supervisor_ui: exit 0.

The live integration tests execute the deployed HumidiFi program in the test VM through the documented DFlow test wrapper.

Greptile Summary

Adds HumidiFi market discovery and scenario preparation through the existing scenario, HTTP, and MCP paths.

• Introduces guarded raw-layout templates for fair value, freshness, and stale quotes, including XOR-masked account fields.
• Adds market validation and discovery plus fair-value and vault-liquidity scenario builders.
• Adds live and unit coverage for account layouts, scenario materialization, and swap behavior.
• Aligns HumidiFi MCP request fields with the established camelCase tool contract.
• The two previous findings were manually resolved after Greptile accepted the author’s explanation of the hydration contract; neither remains outstanding.

Confidence Score: 5/5

The PR appears safe to merge, with no unresolved correctness, security, contract, or repository-rule findings.

The latest changes consistently expose HumidiFi MCP parameters in camelCase across deserialization, generated schemas, tests, and documentation. Both previous findings were resolved after Greptile conceded that caller-side reads hydrate the relevant accounts before Play, so neither remains outstanding.

Important Files Changed

Filename	Overview
crates/core/src/scenarios/protocols/humidifi/v1/fair_value.rs	Implements validated HumidiFi market metadata parsing and integer fair-value scenario construction.
crates/core/src/scenarios/protocols/humidifi/v1/liquidity.rs	Builds liquidity-stress scenarios from validated market vaults while maintaining quote freshness.
crates/core/src/scenarios/protocols/humidifi/v1/markets.rs	Discovers compatible HumidiFi markets and validates their referenced mint metadata.
crates/core/src/scenarios/protocols/humidifi/v1/overrides.yaml	Defines guarded XOR-aware fair-value, freshness, and stale-quote raw-layout templates.
crates/mcp/src/surfpool/mod.rs	Exposes HumidiFi discovery and scenario creation with consistent camelCase request parameters.
crates/types/src/scenarios.rs	Extends raw-layout property representation to support optional XOR masks.
crates/core/src/tests/humidifi/mod.rs	Adds focused live validation for layouts, materialization, staleness boundaries, and swap behavior.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Client[MCP or scenario client] --> Discover[list_humidifi_markets]
    Discover --> RPC[Surfnet RPC]
    RPC --> Validate[Validate owner, layout tag, schema, and mints]
    Validate --> Select[Explicit market selection]
    Select --> FairValue[Build fair-value scenario]
    Select --> Liquidity[Build liquidity scenario]
    FairValue --> Overrides[Raw-layout price and persistent freshness overrides]
    Liquidity --> Overrides2[Vault balance and persistent freshness overrides]
    Overrides --> Play[Scenario Play]
    Overrides2 --> Play

Loading

_{Reviews (4): Last reviewed commit: "fix(mcp): take camelCase tool arguments ..." | Re-trigger Greptile}