feat(scenarios): add GoonFi state preparation

[92Infinitus92]

Stacked on #8 — GoonFi is the same mechanism class as BisonFi and Tessera (PMM, no IDL) and reuses the raw-layout engine BisonFi introduced.

• Two raw-layout accounts per market: a 32-byte external price oracle (bid, ask, freshness, decay) and the 2048-byte market holding the reference band that guards it. Four templates over the pair — price, reference band, freshness, stale quote — plus a live catalog read from program accounts and validated at creation.
• Two builders. Price moves the oracle bid and ask together with the market's reference band and a persistent freshness stamp, since the deployed program rejects a decoupled move with 0x24. Liquidity resolves both token vaults from the market's own pointers and scales their balances through the generic spl-token-account-balance template.
• Three MCP tools on the generic scenario path: list_goonfi_markets, create_goonfi_price_scenario and create_goonfi_liquidity_scenario. No protocol HTTP endpoints and no custom RPC methods.
• The Slot raw encoding now takes a width, so GoonFi's 4-byte freshness field no longer clobbers the decay multiplier stored beside it. Existing 8-byte slot fields are unchanged.
• The oracle carries no discriminator, so the raw-layout owner predicate is what keeps a write out of a foreign 32-byte account, and every builder resolves the oracle through the market's own pointer rather than trusting a caller-supplied address.
• Verified against the deployed program on a fork: drained vaults reject with 0x1, a dislocated quote with a coupled band fills at the prepared price, an aged oracle rejects with 0x15, and a price moved out of its band rejects with 0x24.
• The shared live-test helper duplicates the Tessera branch's on purpose; they fold together when the branches converge.

Greptile Summary

The PR adds GoonFi market discovery and price/liquidity scenario preparation using raw account layouts, together with MCP tools and protocol tests.

• Adds validated market, oracle, mint, and vault discovery.
• Adds coupled price, reference-band, freshness, and liquidity overrides.
• Adds GoonFi MCP tools, registry integration, documentation, and live-test coverage.
• Updates raw slot encoding to support width-specific freshness fields.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
crates/core/src/scenarios/protocols/goonfi/v1/price.rs	Adds coupled GoonFi price preparation and now binds the supplied market, base-vault, and oracle tuples through pointer and authority checks.
crates/core/src/scenarios/protocols/goonfi/v1/liquidity.rs	Adds vault-balance scaling while validating each supplied address against market-derived pointers, mints, token owners, and market authority.
crates/core/src/scenarios/protocols/goonfi/v1/markets.rs	Adds live market discovery with per-market decoding and validation failures isolated from independently valid catalog entries.
crates/mcp/src/surfpool/mod.rs	Exposes GoonFi catalog, price, and liquidity tools using accounts resolved from the selected market.
crates/types/src/scenarios.rs	Extends raw slot encoding with an explicit width so four-byte freshness writes preserve adjacent fields.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  U[MCP request] --> M[Fetch selected market]
  M --> P[Resolve oracle and vault pointers]
  P --> V[Validate owners, layouts, addresses, mints, and authorities]
  V -->|Price| PS[Build price, reference-band, and freshness overrides]
  V -->|Liquidity| LS[Scale selected vault balances and add freshness override]
  PS --> S[Register scenario]
  LS --> S

Loading

_{Reviews (7): Last reviewed commit: "fix(goonfi): bind account inputs to mark..." | Re-trigger Greptile}

[github-actions]

Two improvements in the PR:

• markets.rs:146: One missing oracle/mint or invalid market aborts the entire catalog. Skip invalid entries and report diagnostics so an obsolete market cannot hide all valid markets.
• liquidity.rs:178: Vault validation accepts any token-program-owned account with at least 72 bytes—including an 82-byte mint. Unpack a token account and verify its mint matches the corresponding market mint before reading its balance.

Tests could not run: Rustup attempted to write into a read-only toolchain directory.

[github-actions]

• [P2] Validated market/oracle pairing remains mutable — price.rs:65. #[non_exhaustive] prevents external struct literals, but callers can still assign market.oracle = another_oracle after validation. The builder then modifies that oracle alongside the original market’s reference band, producing an inconsistent scenario. Make both fields private and expose read-only getters.

The catalog isolation issue from the earlier review is fixed in the latest commit. Review was static; tests were not run.

[github-actions]

• [P2] Account validation still lacks address binding — price.rs:90. validate checks the supplied oracle’s layout but cannot establish that it belongs to the market’s oracle pointer. Private fields do not close this gap for direct library callers. Accept keyed accounts and compare addresses, or fetch the referenced account within validation.

• [P2] Liquidity scaling can use another vault’s balance — liquidity.rs:99. Any token account with the expected mint passes validation. Passing another market’s vault calculates the percentage from its balance, then writes that amount to this market’s vault—potentially increasing liquidity during a requested drain. Validate supplied vault addresses against the market pointers and add a mismatch regression test.

Tests could not run: rustup attempted to write to a read-only directory.