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.

Confidence Score: 5/5

The PR appears safe to merge.

Summary

The PR adds GoonFi market discovery and scenario preparation using the shared raw-layout engine.

• Adds coupled oracle-price, reference-band, freshness, and stale-quote templates.
• Adds price and liquidity scenario builders with market, oracle, and vault relationship validation.
• Exposes GoonFi catalog, price-scenario, and liquidity-scenario MCP tools.
• Extends raw slot encoding to support the oracle’s four-byte freshness field.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  RPC[Surfnet RPC] --> Discovery[GoonFi market discovery]
  Discovery --> Market[Validated market]
  Market --> Price[Price scenario builder]
  Market --> Liquidity[Liquidity scenario builder]
  Price --> Oracle[Oracle price and freshness overrides]
  Price --> Band[Market reference-band override]
  Liquidity --> Base[Base-vault balance override]
  Liquidity --> Quote[Quote-vault balance override]
  Liquidity --> Fresh[Oracle freshness override]

Loading

_{Reviews (14) · Last reviewed commit: "docs(goonfi): say that the freshness ove..."}

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

[92Infinitus92]

@greptileai The address is checked before the bytes are used: vault_amount rejects a vault whose address differs from the market's pointer, and GoonfiMarket::validate does the same for the base vault and the oracle (tests: rejects_unrelated_vault_with_matching_mint_and_authority, rejects_unrelated_base_vault_with_target_market_authority). What remains is a caller labelling one account's bytes with another account's address. A pure builder cannot verify that; the reading layer can, and the MCP tools read every account by address from the surfnet. Same contract as the pump graduation builder, documented in the README.

[greptile-apps]

You're right on the core point. vault_amount and GoonfiMarket::validate reject every address mismatch the builder can observe, but once an Account is supplied separately from its Pubkey, a pure builder cannot authenticate that the bytes originated at that address. That would require changing the API to fetch accounts itself or passing a keyed/account type that preserves provenance.

Given the documented library contract, the MCP path reads each account by address and passes the paired values, matching the existing pump graduation builder pattern. The remaining risk is caller misuse rather than an actionable defect in these builders. I would withdraw the P2 merge blocker; an API redesign could be considered separately if provenance must be enforced for all direct callers.

[92Infinitus92]

@greptileai