feat: add BisonFi override templates

[bakasura980]

BisonFi publishes no IDL and is not an Anchor program, so this adds a raw byte-layout write path guarded by account size and magic, plus four templates on it: price, depth, spread and freshness.

Also introduces optional IDLs on templates, so a program without one no longer needs a reconstructed IDL in the repo.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains within the eligible follow-up review scope.

Summary

The PR adds four BisonFi v3 scenario templates backed by guarded raw byte-layout writes, allowing account overrides without an Anchor IDL.

• Registers price, depth, spread, and freshness templates in the built-in registry.
• Guards writes using the pool account size, magic bytes, and layout version.
• Adds protocol documentation and feature-gated mainnet integration coverage.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Scenario[Scenario override] --> Registry[Template registry]
    Registry --> Template[BisonFi raw-layout template]
    Template --> Guard{Size, magic, and version valid?}
    Guard -->|No| Reject[Reject override]
    Guard -->|Yes| Encode[Encode configured fields at byte offsets]
    Encode --> Account[Updated pool account]
    Account --> SVM[Later SVM transactions observe override]

Loading

_{Reviews (18) · Last reviewed commit: "Merge branch 'feat/scenarios/raw-layout'..."}

[github-actions]

• svm.rs:3015: Raw-layout overrides validate size/magic but not account ownership. A caller can target any matching 2,048-byte account, unlike the IDL path which selects by owner program. Include BisonFi’s program ID in RawLayout and reject accounts owned by another program before writing.

[github-actions]

• .github/workflows/openai-review.yml:2: Using pull_request means OPENAI_API_KEY is unavailable for PRs from forks, so the Codex step will fail for external contributors. Add a fork-aware condition or document/use a secure alternative trigger.

Tests couldn’t run because Rustup attempted to write outside the permitted workspace. No other actionable issues found.

[github-actions]

• P1 – Raw writes do not verify account ownership (svm.rs): An override can supply any account address; the raw path validates only size and magic. A matching account owned by another program could be corrupted. Include the expected owner/program ID in RawLayout and validate account.owner() before writing.

• P2 – Slot encoding truncates large u64 slots (scenarios.rs): Casting target_slot to i64 turns values above i64::MAX negative, causing them to encode as zero. Use checked u64 addition/subtraction based on the lead’s sign.

[github-actions]

• svm.rs:3047: Raw-layout overrides validate only size/magic, not account ownership. Because callers may replace the template’s address, any 2048-byte account beginning with the same header can be modified—even if it is not owned by BisonFi. Add the expected program owner to the raw-layout guard and verify account.owner() before writing.

[github-actions]

• [P2] svm.rs:3082: Raw writes validate only size and magic, not account owner. Because callers can override the target address, any 2048-byte account with matching header could be modified. Add the expected BisonFi program ID to RawLayout and verify account.owner() before writing.

[github-actions]

• P2 — Incorrect freshness recipe: README.md:82 supplies <current slot>, but RawEncoding::Slot adds the supplied value to the executing slot. Following this recipe timestamps the quote far into the future. Use last_update_slot: 0 and update the number-format table to describe a relative offset.

• P2 — Review workflow fails on fork PRs: openai-review.yml:38 requires OPENAI_API_KEY, which GitHub withholds from fork-triggered pull_request workflows. Gate the job to supported PR sources or provide a secure fork-review mechanism.

Tests could not run because Rustup attempted to write outside the permitted filesystem.