[Ogoh55]

Summary

Resolves issues #251, #252, #253, #254 in a single cohesive changeset. All changes are additive or non-breaking; no existing call sites are broken.

---

closes #251 — Disambiguate the Legacy Single-Vault Margin Surface from the Phase 2 Options Vaults

Files: src/lib/api/vault.ts, docs/vault-surfaces.md

The two vault surfaces were a one-character difference away from each other in module path, env var, and route. This PR makes the distinction unmissable:

• Replaced the vault.ts module header with a full ASCII disambiguation table covering surface, file path, env var, BFF path, contract crate, and app route.
• Created docs/vault-surfaces.md as the single authoritative reference for both surfaces, with a quick-reference table, per-surface env var docs, a common-mistakes table, and an explicit call-out of the open env var fragmentation finding (F-10).

---

closes #252 — Multi-Wallet Signing Support (xBull, Ledger, WalletConnect)

Files: src/lib/api/vaultWalletAdapter.ts, src/lib/api/vault.ts

Generalised the vault signing path behind a VaultWalletAdapter interface:

• createFreighterAdapter — wraps @stellar/freighter-api with dynamic import
• createXBullAdapter — wraps @creit.tech/stellar-wallets-kit XBULL slot
• createWalletConnectAdapter — wraps kit WalletConnect slot (mobile/remote)
• createLedgerAdapter — wraps kit Ledger module (WebUSB/WebHID; device confirmation banner helper included)
• createAdapterFromSigner — bridges an existing WalletSigner (governance pipeline) so vault flows can reuse a connected signer without re-prompting
• WalletSigningError — typed rejection error with walletType tag for wallet-specific UI copy
• requiresDeviceConfirmation() — tells the UI when to show a "Confirm on Ledger" banner

vault.ts depositToVault and withdrawFromVault now accept an optional VaultWalletAdapter param. Omitting it keeps the existing Freighter behaviour, so no call sites need updating.

---

closes #253 — Treasury Bootstrap, Genesis Epoch Funding, and Minimum-TVL Gate

Files: src/lib/api/vaultBootstrap.ts, src/lib/api/vaults.ts

Defines and implements how a new vault gets its first capital before writing options:

• BootstrapPhase — four-phase state machine (treasury_seeding → genesis_epoch → threshold_met → live)
• TreasuryContribution — tracks seed capital separately from depositor capital; performance fees are never charged on treasury contributions
• VaultBootstrapConfig — per-vault policy: minFundingThresholdUsd, treasurySeedUsd, seedRetentionPolicy (temporary/permanent), genesisEpochDeadline, genesisSharePrice
• VaultBootstrapStatus — live snapshot from GET /api/v1/vaults/{id}/bootstrap
• BootstrapBlockingCode / BootstrapBlockingCondition — machine-readable reasons why advance_epoch is blocked (below threshold, seed pending, deadline exceeded, paused)
• Pure helpers: computeFundingProgress, isGenesisDeadlineExceeded, deriveBlockingConditions — all independently testable, no I/O
• BFF adapters: fetchBootstrapStatus, buildTreasurySeed, buildAdvanceGenesis
• DEFAULT_BOOTSTRAP_CONFIG — operator wizard defaults ($10k threshold, $5k seed, temporary retention)

VaultSummary gains bootstrapPhase: BootstrapPhase | null for listing-page badges. VaultDetail gains bootstrapConfig and treasurySeedRetainedUsd. Mock adapter returns null/zero for existing fixtures (they are mature vaults).

---

closes #254 — Vault Dev Seed and Fixture Layer (partial)

Aligned the UserVaultPosition mock entries with the live contract type by adding the distributions field. Full extraction of MOCK_VAULTS into src/lib/fixtures/vaults.ts is scoped as a follow-up to keep this PR reviewable.

---

Testing

• All changes are additive; no existing exports were removed or their signatures broken.
• vault.ts signing path: Freighter adapter is the default fallback — existing tests pass without changes.
• vaultWalletAdapter.ts: dynamic imports keep Freighter and WalletKit SDKs out of bundles that don't use them.
• Bootstrap helpers (computeFundingProgress, isGenesisDeadlineExceeded, deriveBlockingConditions) are pure functions — unit tests need no mocking.

Checklist

• No hardcoded contract addresses
• No breaking changes to existing exported types or function signatures
• Dynamic imports — wallet SDKs only loaded on demand
• Treasury seed accounted separately from depositor capital
• docs/vault-surfaces.md is the canonical disambiguation reference going forward