@steerprotocol/sdk 4.0.0-next.11 → 4.0.0-next.13

package/README.md

@@ -37,7 +37,11 @@ Consumers use these accessors (lending still needs an integration):
 
 ```ts
 const vault = await steer.getVault(ChainId.Base, vaultAddress);
-const amm = steer.getAmm({ chainId: ChainId.Base, protocol: AmmProtocol.Uniswap, version: UniswapVersion.V3 });
+const amm = steer.getAmm({
+  chainId: ChainId.Base,
+  protocol: AmmProtocol.Uniswap,
+  version: UniswapVersion.V3,
+});
 const lending = steer.getLending(aaveV3Base);
 
 steer.getSubgraphUrl(ChainId.Base);
@@ -50,18 +54,156 @@ Base V3/Integral and Polygon V3/Legacy/Integral vault reads are implemented belo
 implementations. The Steer catalog supplies network metadata and indexed vault discovery. Networks without resolver bindings report `NotConfigured` when loading a vault. Consumers don't assemble a chain or pass a `steer: steerBase` setting.
 SDK integration code owns Steer's per-network contracts and data adapters.
 
+## Development tooling
+
+Run these commands from `next/`:
+
+- `npm run fix`: Biome formatting, import organization, and safe lint fixes.
+- `npm run check:code`: non-mutating Biome CI checks.
+- `npm run check`: code checks, generated ABI/reader verification, types, tests, build and package guards.
+- `npm run check:consumer`: packed ESM, CJS, TypeScript and Next.js consumer verification after the build.
+
+Biome is pinned to `2.6.6`, with recommended lint rules, standard formatting defaults and
+two-space indentation. Open `next/` as the VS Code folder to use its formatter, save actions,
+and Biome extension recommendation. The repository's legacy package has separate tooling.
+
+Dependencies, build output, generated reader/ABI artifacts, retained benchmark JSON and
+lockfiles are excluded from routine code formatting. The existing generators format their own
+output, and reproducibility checks verify it. No unsafe fixes are included in `npm run fix`.
+
+Tests allow non-null assertions for fixed fixtures and decoded tuples; making those accesses
+optional can weaken test assertions. Production non-null exceptions are limited to accesses
+whose bounds were already checked or whose source guarantees a nonempty list. Local bigint
+min/max exceptions preserve arithmetic that cannot use JavaScript's number-only Math functions.
+Each production exception includes its invariant beside the expression.
+
+## Steer ABI sources
+
+Complete Steer ABIs are generated using the development-only, exact dependency
+`@steerprotocol/contracts@3.1.7` into `src/generated/vault/steer-abis.ts`. The generator selects explicit
+chain/contract/function entries, preserves input/output types and names, and removes only Solidity
+`internalType` metadata. Runtime consumers do not load the contracts package or its deployment JSON.
+
+Run `npm run build:abis` to regenerate and `npm run check:abis` to verify. The normal
+`npm run check` includes this verification. Updating the package version requires reviewing the
+generator's source selections and all qualified ABI compatibility exceptions.
+
+The npm package does not include the qualified standalone V4, Aerodrome staking, or Blackhole
+farming implementations. Their missing methods are explicit compatibility entries in the ABI
+generator, with references to each family's qualification evidence. Callers import complete ABIs.
+Shared deposit encoding retains an explicit payable adjustment for qualified native V4 deposits; the package's older deposit ABI
+is nonpayable. External AMM, gauge, NFT and wrapped-token interfaces remain independently maintained.
+SDK reader ABIs continue to be generated from their Solidity reader sources.
+
+ABI generation does not generate addresses, change chain support, or update deployment registrations.
+The SDK catalog, contract maps, implementation identities, and manual deployment additions are
+preserved independently of the package's deployment inventory.
+
 ## App and data-connector loader dependencies
 
 The SDK installs exact runtime dependencies `@steerprotocol/app-loader@3.2.6` and
-`@steerprotocol/data-connector-loader@4.1.0`. Their APIs remain separate from `SteerClient`;
+`@steerprotocol/data-connector-loader@5.0.0-next.7`. Their APIs remain separate from `SteerClient`;
 they are not re-exported from the SDK root.
 
-Both loader packages support ESM imports. The published connector loader's CommonJS entry
-fails because its CommonJS `.js` files are inside a package marked `type: module`; use its
-ESM entry. The app loader supports both ESM and CommonJS. The connector loader declares a
-stable 3.x SDK dependency (3.8.1 in this lockfile), used for its execution-context types;
-its emitted JavaScript does not import SDK readers. The SDK's portable root does not import
-either loader.
+Both loader packages support ESM and CommonJS. The connector loader owns the execution-context
+types and no longer depends on the stable SDK. The SDK's portable root does not import either
+loader at runtime.
+
+## IPFS content and vault configuration
+
+`IpfsClient` reads JSON and bytes through `https://ipfs.io/ipfs/` by default. Bare CIDs,
+`ipfs://` references and gateway URLs with an `/ipfs/` path are resolved through the configured
+gateways. Construction performs no requests. JSON is `unknown` until validated by the caller.
+
+```ts
+import { IpfsClient, SteerClient } from "@steerprotocol/sdk";
+
+const ipfs = new IpfsClient();
+const steer = new SteerClient({ ipfs });
+const vault = await steer.getLiquidityVault(chainId, vaultAddress);
+const config = await vault.getConfig();
+const json = await ipfs.getJson(cid);
+const bytes = await ipfs.getBytes(wasmCid); // Uint8Array with an ArrayBuffer backing store.
+
+if (config.strategy) {
+  const wasm = await ipfs.getBytes(config.strategy.execBundle);
+  const { chainId, tokenId } = config.strategy; // Strategy registry identity.
+}
+```
+
+`vault.getConfig()` fetches `vault.metadata.payloadIpfs` and validates the stored manifest.
+`VaultConfig` preserves strategy-specific `strategyConfigData` and `vaultPayload` objects,
+including empty objects and nested configuration. `dataConnectorsData` can be empty; each entry
+has a `bundleHash` and its own `configData` object. The optional `strategy` object contains
+`chainId`, `execBundle` (the strategy WASM IPFS reference) and decimal-string `tokenId` (the
+strategy registry token ID). Older manifests without `strategy` remain readable. Validation
+checks this envelope, leaving individual configuration schemas to their strategy or connector.
+The method does not add the loader's runtime `vaultAddress` or `epochTimestamp`.
+Missing references and invalid manifests throw. Indexed
+metadata selects the reference; this read does not revalidate that reference onchain.
+
+Configure fallback gateways in order with `new IpfsClient({ gateways: [...] })`. Each attempt
+uses the existing fetch transport with a 15-second default timeout, optional headers and fetch
+override, and caller cancellation. A caller abort stops fallback. `timeoutMs: 0` disables the
+timeout. `maxResponseBytes` defaults to 16 MiB and is enforced while streaming the decoded body.
+These settings can also be passed per call, including to `vault.getConfig()`. IPFS settings are
+separate from the client's indexer `http` settings. Gateway responses are not cryptographically
+verified against the CID. Uploading, pinning and executing downloaded bundles are separate tasks.
+
+## Running vault strategies and data connectors
+
+Liquidity vaults own their manifests. Callers pass one loader-native context through both
+execution stages:
+
+```ts
+const config = await vault.getConfig(); // Optional inspection; warms the instance cache.
+const context = await vault.getExecutionContext({
+  blockNumber,
+  epochTimestamp,
+  epochLength,
+});
+const connectorData = await vault.executeDataConnectors(context);
+const output = await vault.executeStrategy(context, connectorData);
+```
+
+`getConfig()` caches the in-flight promise and resolved manifest per vault instance and payload
+CID. Failed loads are removed so a later call can retry. Cached manifests are deeply frozen.
+The first request's transport settings govern a shared download. Each execution stage verifies
+the RPC chain and reads VaultRegistry and StrategyRegistry at `context.blockNumber`, selecting
+the registered payload CID and execution bundle independently of indexed metadata. A new CID
+gets a separate cache entry, including for historical reads. An embedded manifest `strategy`
+object must agree with the registration.
+
+The SDK validates and captures the supplied context and connector results before asynchronous
+reads. It does not recompute caller-supplied financial fields; use `getExecutionContext()` for
+verified same-block vault accounting. A stored `epochLength`, when present, must agree with the
+context. Empty strategy settings use the caller's context epoch length.
+
+`executeDataConnectors()` delegates v1 request loops and v2 execute/transform dispatch to the
+data connector loader in manifest order, returning an
+empty array when no connectors are configured. Each connector initializes with its own
+`configData` and nested `executionContext`. Versionless connectors follow the loader's v1 path,
+and chain reads use the SDK RPC client at the supplied block. `executeStrategy()` uses the
+loader's `ExecutionApp.executeWithContext()` with the manifest, flattened
+strategy settings and context fields taking precedence, then supplies one serialized argument
+per connector. The result count must match the manifest. It returns decoded JSON as `unknown`
+or the exact `"continue"` sentinel, without preparing or submitting a transaction. The loader owns
+result decoding; other non-JSON output remains an error.
+
+Supplied-context execution passes only the vault and chain identity plus optional host credentials.
+It does not require pool-type placeholders or a discovery subgraph endpoint.
+
+WASM loading is lazy and each call gets fresh module instances. Initialization, malformed JSON,
+transport and execution failures reject the call. Manifests are never mutated to construct runtime
+inputs. Request options apply to IPFS downloads; connector HTTP uses the loader's host runtime
+and is not guaranteed to reflect the selected historical block. No hard CPU deadline or process
+isolation is provided by these portable methods.
+
+Offline regression tests exercise retained public Static Stable, Liquid Arc and Robinhood
+connector binaries, including a complete connector-to-strategy run with a synthetic HTTP quote.
+The sampled No-op registration's empty manifest is readable, but its binary rejects those empty
+settings; execution reports that initialization failure rather than inventing defaults. This is
+execution-path verification, not qualification of real-time data feeds or transaction outcomes.
 
 ## Vault execution context
 
@@ -69,18 +211,36 @@ Liquidity vaults expose strategy inputs through the existing vault object:
 
 ```ts
 const blockNumber = 12345678n; // Caller-selected operation block.
-const vault = await steer.getLiquidityVault(chainId, vaultAddress, { blockNumber });
+const vault = await steer.getLiquidityVault(chainId, vaultAddress, {
+  blockNumber,
+});
 const context = await vault.getExecutionContext({
   blockNumber,
   epochTimestamp: 1793577600n, // Explicit Unix seconds, independent of the wall clock.
+  epochLength: 60, // Strategy epoch duration in seconds.
 });
 ```
 
-The immutable, JSON-safe `VaultExecutionContext` contains vault/beacon/AMM identity,
-address-based or V4 key/ID/manager pool identity, current tick/spacing, configured strategy
-ranges with relative weights, original contract totals as decimal strings, and indexed
-last-execution/elapsed seconds. It has no `provenance` field. V4 never fabricates a pool address;
-unused pool identity fields are `null`. Configured ranges are independent of active NFT inventory.
+The return type is `SmartPoolExecutionContext`, imported directly from the installed npm
+package. The SDK does not define or re-export its own execution-context output type:
+
+```ts
+import type {
+  ExecutionContext,
+  SmartPoolExecutionContext,
+} from "@steerprotocol/data-connector-loader";
+
+const smartPool: SmartPoolExecutionContext = context;
+const execution: ExecutionContext = smartPool;
+```
+
+The result uses the loader's native field names: `chainId`, numeric block/epoch values,
+`executionTimestamp` in milliseconds, `epochLength` in seconds, `blockTime: 0` for the
+explicitly pinned path, positions as `{ startTick, endTick, weight }`, decimal-string token
+totals, and numeric `lastExecutionTime` in seconds. It contains no `provenance` or extra
+vault/pool identity fields beyond `chainId` and `vaultAddress`. Those identities are verified
+internally before returning data.
+Configured ranges are independent of active NFT inventory.
 
 Each call revalidates the native vault binding and dispatches registered vault/AMM overrides.
 All onchain reads use the explicit block. `totalAmount0`/`totalAmount1` come from the original
@@ -89,9 +249,9 @@ they are not aliases for the fee-adjusted `getSnapshot().total` accounting field
 
 The Steer data adapter queries the latest indexed `vaultSnapshot` at that block, bounded by
 the earlier of the block timestamp and execution epoch. Its timestamp is the history source,
-not proof that the indexer has captured every execution. An empty history returns `null`
-for both history fields. Unsupported history adapters, unavailable blocks, indexing errors,
-malformed responses and RPC/HTTP failures throw instead of fabricating zero elapsed time.
+not proof that the indexer has captured every execution. An empty history maps to
+`lastExecutionTime: 0`, matching the loader contract. Unsupported history adapters,
+unavailable blocks, indexing errors, malformed responses and RPC/HTTP failures throw.
 Block numbers must fit the indexer's nonnegative GraphQL Int range. The optional second
 argument accepts the existing per-request HTTP overrides for the history query.
 
@@ -99,20 +259,21 @@ Custom Steer data adapters can implement `getLastVaultExecution(request, options
 history without a subgraph. The request contains `vaultAddress`, `blockNumber` and the bounded
 `timestamp`; return a nonnegative bigint no later than that timestamp, or `null`.
 
-The installed connector loader's runtime mapper accepts this provenance-free shape. Its
-published TypeScript declarations still require the legacy SDK's context, including legacy
-protocol types and `provenance`. Updating that upstream type contract is required for direct
-typed `executeWithContext` integration; this SDK does not invent provenance or cast away that
-mismatch. The offline test verifies runtime mapping, not a full WASM strategy execution.
+Pass this result to the loader's `initializeStrategyWithContext` or
+`initializeDataConnectorWithContext` methods. `ExecutionApp.executeWithContext` also accepts
+`SmartPoolExecutionContext` directly; `DataConnectorExecution.executeWithContext` accepts its
+base `ExecutionContext`. No SDK-specific wrapper or mapping is required. Full WASM strategy
+execution requires separate qualification.
 
-Read-only live verification on November 2, 2026 passed 13 fixtures across six chains:
+The underlying read path was verified live on November 2, 2026 using 13 fixtures across six chains:
 Base Uniswap V3, Base QuickSwap Integral, all three Base Aerodrome generations, Polygon
 QuickSwap Legacy, Arbitrum Camelot, Avalanche Blackhole, BSC Pancake V3, and ERC20/native
-standalone V4 vaults on both BSC and Robinhood. Each context was compared with independent
+standalone V4 vaults on both BSC and Robinhood. The prior wrapper was compared with independent
 same-block original contract totals, configured ranges, registry/beacon identity, pool
-tick/spacing and identity, and a separate indexed history query. This qualifies those
-fixtures, not every deployment or full WASM strategy execution. Blackhole execution pool
-reads retain the custom deployer from the verified vault layout.
+tick/spacing and identity, and a separate indexed history query. The updated native loader
+shape also passed new live Base V3 and Robinhood native ETH checks, plus the offline suite.
+These results qualify those fixtures and reads, not every deployment or full WASM strategy
+execution. Blackhole execution pool reads retain the custom deployer from the verified vault layout.
 
 Reproduce with the explicit RPC/indexer settings in `.env.integration`:
 
@@ -138,7 +299,10 @@ for (const metadata of page.items) {
 }
 
 // Load a page or any explicit address list through the same resolver.
-const vaults = await steer.getVaults(ChainId.Base, page.items.map((metadata) => metadata.id));
+const vaults = await steer.getVaults(
+  ChainId.Base,
+  page.items.map((metadata) => metadata.id),
+);
 
 if (page.nextCursor) {
   const next = await steer.listVaults({
@@ -215,10 +379,14 @@ its onchain identity checks remain the loading path.
 When catalog records are already available, supply them through the optional `VaultLoadOptions.metadata` field:
 
 ```ts
-const vaults = await steer.getVaults(ChainId.Base, records.map((record) => record.id), {
-  blockNumber: 100000n,
-  metadata: records,
-});
+const vaults = await steer.getVaults(
+  ChainId.Base,
+  records.map((record) => record.id),
+  {
+    blockNumber: 100000n,
+    metadata: records,
+  },
+);
 ```
 
 This skips metadata subgraph requests while retaining all onchain registration, implementation,
@@ -260,9 +428,10 @@ already checked by that reader and adds no RPC calls. Custom bindings without a
 `implementationCodeHash` omit the metadata. `beaconName` reuses the indexed descriptive name from
 the vault metadata, not onchain identity evidence. It does not assert fee-event completeness.
 
-
 ```ts
-const supported: boolean = steer.getDeployment(chainId).supportsVaultSnapshots(beaconName);
+const supported: boolean = steer
+  .getDeployment(chainId)
+  .supportsVaultSnapshots(beaconName);
 ```
 
 This synchronous check performs no RPC or HTTP requests. It matches an exact indexed beacon name
@@ -292,7 +461,8 @@ const results = await steer.getVaultSnapshots(ChainId.Base, vaultAddresses, {
   allowFailure: true,
 });
 for (const [index, result] of results.entries()) {
-  if (result.status === "success") consume(vaultAddresses[index], result.snapshot);
+  if (result.status === "success")
+    consume(vaultAddresses[index], result.snapshot);
   else report(vaultAddresses[index], result.error);
 }
 ```
@@ -348,7 +518,9 @@ const amm = steer.getAmm({
   protocol: AmmProtocol.Uniswap,
   version: UniswapVersion.V3,
 });
-const pools = await amm.getPools([poolAddress, anotherPoolAddress], { blockNumber });
+const pools = await amm.getPools([poolAddress, anotherPoolAddress], {
+  blockNumber,
+});
 
 // Let the family discover each pool's registered AMM.
 const discovered = await steer.getPools({
@@ -398,13 +570,22 @@ without a wrapper; install it in the application and use its numeric debug level
 
 ```ts
 import { createConsola } from "consola";
-import { AmmProtocol, ChainId, SteerClient, UniswapVersion } from "@steerprotocol/sdk";
+import {
+  AmmProtocol,
+  ChainId,
+  SteerClient,
+  UniswapVersion,
+} from "@steerprotocol/sdk";
 
 const steer = new SteerClient({
   logger: createConsola({ level: 4 }),
   indexers: { theGraph: { proxyUrl: "/api/the-graph" } },
 });
-const amm = steer.getAmm({ chainId: ChainId.Base, protocol: AmmProtocol.Uniswap, version: UniswapVersion.V3 });
+const amm = steer.getAmm({
+  chainId: ChainId.Base,
+  protocol: AmmProtocol.Uniswap,
+  version: UniswapVersion.V3,
+});
 
 await amm.listPools({ token: { symbol: "USDC" } });
 ```
@@ -477,7 +658,13 @@ new catalog as additional chains.
 ## Uniswap V3 on Base
 
 ```ts
-import { AmmFamily, ChainId, SteerClient, AmmProtocol, UniswapVersion } from "@steerprotocol/sdk";
+import {
+  AmmFamily,
+  ChainId,
+  SteerClient,
+  AmmProtocol,
+  UniswapVersion,
+} from "@steerprotocol/sdk";
 
 const steer = new SteerClient({ transports: { [ChainId.Base]: rpcTransport } });
 const pool = await steer.getPool({
@@ -496,23 +683,32 @@ pool.token0Decimals;
 pool.token1Decimals;
 pool.price?.currency0InCurrency1; // Whole token1 per whole token0, as a decimal string.
 pool.price?.currency1InCurrency0; // Whole token0 per whole token1.
-pool.fees.swapFeePercent;           // "0.05" for raw fee 500.
-pool.balances.token0.raw;       // bigint from token0.balanceOf(pool.address).
+pool.fees.swapFeePercent; // "0.05" for raw fee 500.
+pool.balances.token0.raw; // bigint from token0.balanceOf(pool.address).
 pool.balances.token0.formatted; // Exact decimal string using token0Decimals.
 pool.balances.token1.raw;
 pool.balances.token1.formatted;
 
-const amm = steer.getAmm({ chainId: ChainId.Base, protocol: AmmProtocol.Uniswap, version: UniswapVersion.V3 });
+const amm = steer.getAmm({
+  chainId: ChainId.Base,
+  protocol: AmmProtocol.Uniswap,
+  version: UniswapVersion.V3,
+});
 amm.contracts.factory.address;
 amm.subgraphUrl;
-const state = await amm.getPool(pool.address, { blockNumber: pool.blockNumber });
+const state = await amm.getPool(pool.address, {
+  blockNumber: pool.blockNumber,
+});
 // Also exposes token0, token1, fees.swapFeePips, tickSpacing, factory, and sqrtPriceX96.
-const quote = await amm.quote({
-  pool: pool.address,
-  inputCurrency: state.token0,
-  outputCurrency: state.token1,
-  amountIn: 1_000_000_000_000_000n,
-}, { blockNumber: state.blockNumber });
+const quote = await amm.quote(
+  {
+    pool: pool.address,
+    inputCurrency: state.token0,
+    outputCurrency: state.token1,
+    amountIn: 1_000_000_000_000_000n,
+  },
+  { blockNumber: state.blockNumber },
+);
 ```
 
 `rpcTransport` implements `request(method, params): Promise<unknown>` and returns the JSON-RPC
@@ -560,13 +756,20 @@ indexed listing.
 
 ### List indexed pools
 
-Configure The Graph once on the client, using an API key in server code:
+Configure Graph and Sentio keys once on the client in server code. They are reused by SDK indexer requests and vault data connectors. Connector execution keeps both keys in host-side loader settings, outside WASM configuration. The loader attaches Graph authorization only to recognized HTTPS gateway requests after resolving their actual destination, and scopes Sentio authentication to its HTTPS endpoints. It does not change the stored IPFS manifest. Graph proxy configuration continues to apply to SDK indexer requests, not WASM connector requests.
 
 ```ts
 const steer = new SteerClient({
-  indexers: { theGraph: { apiKey: theGraphApiKey } },
+  indexers: {
+    theGraph: { apiKey: theGraphApiKey },
+    sentio: { apiKey: sentioApiKey },
+  },
+});
+const amm = steer.getAmm({
+  chainId: ChainId.Base,
+  protocol: AmmProtocol.Uniswap,
+  version: UniswapVersion.V3,
 });
-const amm = steer.getAmm({ chainId: ChainId.Base, protocol: AmmProtocol.Uniswap, version: UniswapVersion.V3 });
 const first = await amm.listPools({ limit: 100, token: { symbol: "USDC" } });
 
 first.items; // Pool addresses; load one with amm.getPool(address) for verified RPC state.
@@ -588,7 +791,11 @@ For browser applications, configure a server proxy instead of putting a private
 const steer = new SteerClient({
   indexers: { theGraph: { proxyUrl: "/api/the-graph" } },
 });
-const amm = steer.getAmm({ chainId: ChainId.Base, protocol: AmmProtocol.Uniswap, version: UniswapVersion.V3 });
+const amm = steer.getAmm({
+  chainId: ChainId.Base,
+  protocol: AmmProtocol.Uniswap,
+  version: UniswapVersion.V3,
+});
 const pools = await amm.listPools({ token: { symbol: "USDC" } });
 ```
 
@@ -605,10 +812,13 @@ the canonical indexer URL; API keys and proxy settings never become public deplo
 Per-request overrides remain available:
 
 ```ts
-await amm.listPools({ token: { symbol: "USDC" } }, {
-  headers: { Authorization: `Bearer ${otherApiKey}` },
-  timeoutMs: 5_000,
-});
+await amm.listPools(
+  { token: { symbol: "USDC" } },
+  {
+    headers: { Authorization: `Bearer ${otherApiKey}` },
+    timeoutMs: 5_000,
+  },
+);
 ```
 
 An explicit authorization header overrides the client key, using case-insensitive header matching.
@@ -657,11 +867,11 @@ Bearer authentication follows [The Graph API-key documentation](https://thegraph
 
 Successful Uniswap V3 operations currently make these calls through the configured `RpcTransport`:
 
-| Operation | Select latest block | Explicit block |
-| --- | ---: | ---: |
-| `amm.getPool()` | 3 | 2 |
-| `steer.getPool()` with discovery | 4 | 3 |
-| `amm.quote()` | 6 | 5 |
+| Operation                        | Select latest block | Explicit block |
+| -------------------------------- | ------------------: | -------------: |
+| `amm.getPool()`                  |                   3 |              2 |
+| `steer.getPool()` with discovery |                   4 |              3 |
+| `amm.quote()`                    |                   6 |              5 |
 
 Discovery reads the factory, selects an exact registered adapter, and dispatches to that adapter's
 `getPool()` method before any snapshot reads. Custom adapters can handle nonstandard metadata
@@ -710,9 +920,13 @@ batching remains a separate transport concern.
 
 ### Solidity reader development
 
+Generated TypeScript lives under `src/generated/`, mirroring the AMM, vault and RPC paths.
+This includes reader ABIs/bytecode, batch/tick limits and the package-sourced Steer ABIs.
+The generators create their output directories; routine formatting excludes these files.
+
 The sources are `src/amm/adapters/uniswap-v3/reader/V3PoolReader.sol` and `src/vault/adapters/uniswap-v3/reader/V3VaultReader.sol`; their internal ABIs and
-creation/runtime bytecode are checked in under `src/amm/adapters/uniswap-v3/reader/artifact.ts` and
-`src/vault/adapters/uniswap-v3/reader/artifact.ts`. `npm run build:reader` regenerates both artifacts with
+creation/runtime bytecode are checked in under `src/generated/amm/adapters/uniswap-v3/reader/artifact.ts` and
+`src/generated/vault/adapters/uniswap-v3/reader/artifact.ts`. `npm run build:reader` regenerates both artifacts with
 the pinned development-only Solidity compiler, optimizer settings, and Paris EVM target.
 `npm run check:reader`, included in `npm run check`, detects stale artifacts. Consumers receive
 compiled JavaScript and bytecode and do not need Solidity tools.
@@ -786,6 +1000,12 @@ code identities; `rpc.ts` and `reader/` hold internal reads. Shared models and e
 `vault/types.ts` and `vault/enums.ts`. The Steer data-adapter scaffold lives in
 `vault/data-adapter.ts`; built-in indexed listing supports optional AMM/version and token filters.
 
+Shared vault operations are grouped by responsibility: `vault/accounting/` contains snapshot
+validation, fee/reward accounting and user positions; `vault/transactions/` contains deposit
+quotes, deposit math, RPC reads and withdrawal preparation; `vault/resolution/` contains the
+resolver and its internal models; `vault/execution/` contains execution context and WASM orchestration.
+Family-specific operations stay with their adapters, and shared Solidity readers stay in `vault/reader/`.
+
 ## Automatic vault resolution
 
 `getVault(chainId, address, { blockNumber })` uses the network's SDK-owned `vaultResolver` configuration. Consumers
@@ -825,7 +1045,10 @@ Use the same automatic resolver and snapshot API. Consumers do not select a vaul
 ```ts
 const vault = await steer.getLiquidityVault(ChainId.Polygon, vaultAddress);
 const snapshot = await vault.getSnapshot();
-const snapshots = await steer.getVaultSnapshots(ChainId.Polygon, vaultAddresses);
+const snapshots = await steer.getVaultSnapshots(
+  ChainId.Polygon,
+  vaultAddresses,
+);
 
 const page = await steer.listVaults({
   chainId: ChainId.Polygon,
@@ -836,13 +1059,13 @@ const page = await steer.listVaults({
 
 Polygon mappings cover these exact beacon deployments:
 
-| Indexed beacon | Underlying AMM | Accounting policy |
-| --- | --- | --- |
-| `MultiPositionUniswapV3` | Uniswap V3 | Vault `TOTAL_FEE` and accrued Steer/strategist reserves |
-| `MultiPositionSushi` | SushiSwap V3 | Same fixed-fee V3 layout |
-| `MultiPositionRetro` | Retro V3 | Same fixed-fee V3 layout |
-| `MultiPositionQuickSwap` | QuickSwap V3 / Legacy Algebra | Fixed fees; packed position key and six-field pool position ABI |
-| `MultiPositionQuickSwapIntegral` | QuickSwap V4 / Algebra Integral | Existing Integral fee-manager reader |
+| Indexed beacon                   | Underlying AMM                  | Accounting policy                                               |
+| -------------------------------- | ------------------------------- | --------------------------------------------------------------- |
+| `MultiPositionUniswapV3`         | Uniswap V3                      | Vault `TOTAL_FEE` and accrued Steer/strategist reserves         |
+| `MultiPositionSushi`             | SushiSwap V3                    | Same fixed-fee V3 layout                                        |
+| `MultiPositionRetro`             | Retro V3                        | Same fixed-fee V3 layout                                        |
+| `MultiPositionQuickSwap`         | QuickSwap V3 / Legacy Algebra   | Fixed fees; packed position key and six-field pool position ABI |
+| `MultiPositionQuickSwapIntegral` | QuickSwap V4 / Algebra Integral | Existing Integral fee-manager reader                            |
 
 The SDK verifies actual registry membership, stored beacon/registry, exact implementation and original
 proxy/implementation runtime hashes, factory registration and token ordering. Indexed names only filter
@@ -892,32 +1115,36 @@ vault.amm.subgraphUrl;
 vault.steer.subgraphUrl;
 snapshot.blockNumber;
 snapshot.pool;
-snapshot.idle.token0.formatted;        // Available idle tokens after fee reserves.
-snapshot.balances.token0.raw;           // Full vault ERC-20 holdings.
-snapshot.reservedFees.token0.raw;       // Already collected protocol/strategist fees.
-snapshot.principal.token0.formatted;   // Sum of deployed position principal.
-snapshot.fees.gross.token0.formatted;  // All uncollected position fees.
-snapshot.fees.net.token0.formatted;    // LP portion after the vault fee cut.
-snapshot.fees.recorded.token0.raw;     // Sum of pool-checkpointed fees across positions.
+snapshot.idle.token0.formatted; // Available idle tokens after fee reserves.
+snapshot.balances.token0.raw; // Full vault ERC-20 holdings.
+snapshot.reservedFees.token0.raw; // Already collected protocol/strategist fees.
+snapshot.principal.token0.formatted; // Sum of deployed position principal.
+snapshot.fees.gross.token0.formatted; // All uncollected position fees.
+snapshot.fees.net.token0.formatted; // LP portion after the vault fee cut.
+snapshot.fees.recorded.token0.raw; // Sum of pool-checkpointed fees across positions.
 snapshot.feeRateBps;
-snapshot.total.token0.formatted;       // idle + principal + net fees.
+snapshot.total.token0.formatted; // idle + principal + net fees.
 // Every amount pair also includes token1. Raw amounts are bigint; formatted amounts are strings.
 
 for (const position of snapshot.positions) {
-  position.positionId;                 // keccak256(vault address, lowerTick, upperTick).
+  position.positionId; // keccak256(vault address, lowerTick, upperTick).
   position.lowerTick;
   position.upperTick;
-  position.relativeWeight;             // Contract-configured units, not basis points.
-  position.weightPercent;              // Normalized percentage string, not a value allocation.
+  position.relativeWeight; // Contract-configured units, not basis points.
+  position.weightPercent; // Normalized percentage string, not a value allocation.
   position.liquidity;
   position.principal.token0.formatted;
-  position.fees.gross.token0.formatted;       // Gross collectible fees, including accrued growth.
+  position.fees.gross.token0.formatted; // Gross collectible fees, including accrued growth.
   position.fees.net.token0.formatted;
-  position.fees.recorded.token0.raw;     // Pool checkpoint tokensOwed, before new fee growth.
+  position.fees.recorded.token0.raw; // Pool checkpoint tokensOwed, before new fee growth.
 }
 
-const positions = await vault.getPositions({ blockNumber: snapshot.blockNumber });
-const shares = await vault.getShareBalance(accountAddress, { blockNumber: snapshot.blockNumber });
+const positions = await vault.getPositions({
+  blockNumber: snapshot.blockNumber,
+});
+const shares = await vault.getShareBalance(accountAddress, {
+  blockNumber: snapshot.blockNumber,
+});
 ```
 
 Omit `blockNumber` to choose the current RPC block, or pin it on resolution and each read. Each
@@ -986,10 +1213,10 @@ own `getTotalAmounts()` after a sequential `poke()` simulation in `eth_call`. No
 const vault = await steer.getLiquidityVault(chainId, vaultAddress);
 const position = await vault.getUserPosition(accountAddress);
 
-position.shares;           // Raw share balance (bigint)
-position.totalSupply;      // Raw share supply (bigint)
+position.shares; // Raw share balance (bigint)
+position.totalSupply; // Raw share supply (bigint)
 position.ownershipPercent; // Decimal string, e.g. "12.5"
-position.amounts.token0;   // { raw: bigint, formatted: string }
+position.amounts.token0; // { raw: bigint, formatted: string }
 position.amounts.token1;
 position.blockNumber;
 ```
@@ -1025,7 +1252,12 @@ const positions = await steer.getVaultUserPositions(
 );
 
 for (const { vault, position } of positions) {
-  console.log(vault, position.shares, position.ownershipPercent, position.amounts);
+  console.log(
+    vault,
+    position.shares,
+    position.ownershipPercent,
+    position.amounts,
+  );
 }
 ```
 
@@ -1097,19 +1329,19 @@ const request = {
 };
 const preview = await vault.previewDeposit(request, { blockNumber });
 preview.blockNumber;
-preview.shares;          // Expected raw share units
+preview.shares; // Expected raw share units
 preview.token0;
 preview.token1;
-preview.amounts.token0;  // Accepted input: { raw: bigint, formatted: string }
+preview.amounts.token0; // Accepted input: { raw: bigint, formatted: string }
 preview.amounts.token1;
-preview.unusedAmounts;   // Requested inputs which remain in the wallet
+preview.unusedAmounts; // Requested inputs which remain in the wallet
 
 const plan = await vault.prepareDeposit({ ...request, slippageBps: 50 });
 plan.account;
 plan.chainId;
 plan.preview;
 plan.minimumAmounts; // Minimum accepted amounts in token0/token1 order
-plan.transactions;   // Required capped approvals, then the unsigned deposit
+plan.transactions; // Required capped approvals, then the unsigned deposit
 ```
 
 Both methods accept `{ blockNumber }` as the second argument. Omitting it pins one latest block.
@@ -1126,9 +1358,9 @@ const quote = await vault.quoteDeposit({
   amount: 100_000000n,
 });
 
-quote.assets;        // Maxima for both tokens, already in token0/token1 order
-quote.shares;        // Expected raw shares
-quote.amounts;       // Expected accepted amounts, raw and formatted
+quote.assets; // Maxima for both tokens, already in token0/token1 order
+quote.shares; // Expected raw shares
+quote.amounts; // Expected accepted amounts, raw and formatted
 quote.unusedAmounts; // Any unused input caused by contract rounding
 quote.blockNumber;
 
@@ -1209,11 +1441,11 @@ preview.amounts.token0; // { raw: bigint, formatted: string }
 preview.amounts.token1;
 
 const plan = await vault.prepareWithdraw({ ...request, slippageBps: 50 });
-plan.account;        // Must submit the transaction: this account owns the shares
+plan.account; // Must submit the transaction: this account owns the shares
 plan.chainId;
 plan.preview;
 plan.minimumAmounts; // Raw and formatted minimum outputs for both tokens
-plan.transactions;   // Unsigned { to, data, value } requests
+plan.transactions; // Unsigned { to, data, value } requests
 ```
 
 Both methods accept `{ blockNumber }` as their optional second argument; omitting it pins one
@@ -1250,12 +1482,12 @@ const vault = await steer.getLiquidityVault(ChainId.Base, integralVaultAddress);
 const snapshot = await vault.getSnapshot();
 
 vault.amm.protocol; // AmmProtocol.QuickSwap
-vault.amm.version;  // QuickSwapVersion.V4
+vault.amm.version; // QuickSwapVersion.V4
 vault.amm.subgraphUrl;
 snapshot.positions;
 snapshot.idle;
 snapshot.principal;
-snapshot.fees;      // gross, net, recorded, each with token0/token1 raw and formatted amounts.
+snapshot.fees; // gross, net, recorded, each with token0/token1 raw and formatted amounts.
 snapshot.feeRateBps;
 snapshot.total;
 ```
@@ -1296,16 +1528,16 @@ No Graph credentials are required for vault reads.
 
 ## Extension points
 
-| Base | Responsibility |
-| --- | --- |
-| `UniswapV3Adapter` | Address-based pool reads and V3 quote interface |
-| `UniswapV4Adapter` | Reusable V4 pool-key/ID reads and quote implementation |
-| `AaveV3Adapter` | Reserve reads and supply transaction preparation interface |
-| `PoolDataAdapter`, `LendingDataAdapter` | Indexed protocol discovery |
-| `SteerClient` | SDK entry point, network routing, and typed integration lookup |
-| `SteerNetwork`, `SteerDataAdapter` | Verified vault loading and indexed vault discovery |
-| `VaultResolver`, `VaultIdentityReader` | Exact implementation resolution and pinned identity reads |
-| `SteerVault` | Identity, shares, and strategy positions |
+| Base                                    | Responsibility                                                 |
+| --------------------------------------- | -------------------------------------------------------------- |
+| `UniswapV3Adapter`                      | Address-based pool reads and V3 quote interface                |
+| `UniswapV4Adapter`                      | Reusable V4 pool-key/ID reads and quote implementation         |
+| `AaveV3Adapter`                         | Reserve reads and supply transaction preparation interface     |
+| `PoolDataAdapter`, `LendingDataAdapter` | Indexed protocol discovery                                     |
+| `SteerClient`                           | SDK entry point, network routing, and typed integration lookup |
+| `SteerNetwork`, `SteerDataAdapter`      | Verified vault loading and indexed vault discovery             |
+| `VaultResolver`, `VaultIdentityReader`  | Exact implementation resolution and pinned identity reads      |
+| `SteerVault`                            | Identity, shares, and strategy positions                       |
 
 Vault categories describe strategy exposure, not an ERC-4626 or multi-asset ABI. Every vault has
 consistent direct methods: `previewDeposit`, `prepareDeposit`, and `prepareWithdraw`. Deposits use
@@ -1418,7 +1650,8 @@ as V3. Standalone V4 vault operations are qualified separately on BNB Chain belo
 ```ts
 const amm = steer.getAmm({
   chainId: ChainId.Base,
-  protocol: AmmProtocol.Uniswap, version: UniswapVersion.V4,
+  protocol: AmmProtocol.Uniswap,
+  version: UniswapVersion.V4,
 });
 
 const page = await amm.listPools({ token: { symbol: "USDC" }, limit: 20 });
@@ -1427,10 +1660,10 @@ await amm.listPools({ token: { address: usdcAddress } });
 await amm.listPools({ token: { name: "USD Coin" } });
 
 for (const key of page.items) {
-  const id = amm.getPoolId(key);       // Pure ABI encoding and hashing; no network request.
+  const id = amm.getPoolId(key); // Pure ABI encoding and hashing; no network request.
   const recovered = await amm.getPoolKey(id); // Verified indexed metadata lookup.
   const pool = await amm.getPool(key); // Complete keys require RPC only.
-  await amm.getPool({ poolId: id });   // Resolves metadata, then verifies onchain state.
+  await amm.getPool({ poolId: id }); // Resolves metadata, then verifies onchain state.
 
   const quote = await amm.quote({
     pool: recovered,
@@ -1533,7 +1766,11 @@ const options = { blockNumber }; // Omit to pin the latest block once for the op
 const specific = await amm.getTicks(reference, [-120, 0, 120], options);
 const range = { lowerTick: lowerVisibleTick, upperTick: upperVisibleTick };
 const window = await amm.getSurroundingTicks(reference, range, options);
-const distribution = await amm.getLiquidityDistribution(reference, range, options);
+const distribution = await amm.getLiquidityDistribution(
+  reference,
+  range,
+  options,
+);
 
 // Reuse an already fetched window without another RPC call.
 const sameDistribution = buildLiquidityDistribution(window);
@@ -1583,7 +1820,8 @@ This is fee-free geometric liquidity depth, not an executable swap quote or hook
 ```ts
 const amm = steer.getAmm({
   chainId: ChainId.Base,
-  protocol: AmmProtocol.QuickSwap, version: QuickSwapVersion.V4,
+  protocol: AmmProtocol.QuickSwap,
+  version: QuickSwapVersion.V4,
 });
 
 const page = await amm.listPools({ token: { symbol: "USDC" } });
@@ -1597,10 +1835,14 @@ const quote = await amm.quote({
   outputCurrency: pool.token1,
   amountIn: 10n ** BigInt(pool.token0Decimals), // One whole token0.
 });
-const ticks = await amm.getSurroundingTicks(reference, {
-  lowerTick: pool.tick - 100,
-  upperTick: pool.tick + 100,
-}, { blockNumber: pool.blockNumber });
+const ticks = await amm.getSurroundingTicks(
+  reference,
+  {
+    lowerTick: pool.tick - 100,
+    upperTick: pool.tick + 100,
+  },
+  { blockNumber: pool.blockNumber },
+);
 ```
 
 Ordinary pools accept an address. Custom pools use `{ address, deployer }`; listings return the
@@ -1635,11 +1877,13 @@ suite. This qualifies the deployed Integral interface, without inferring a versi
 ```ts
 const quickswap = steer.getAmm({
   chainId: ChainId.Polygon,
-  protocol: AmmProtocol.QuickSwap, version: QuickSwapVersion.V3,
+  protocol: AmmProtocol.QuickSwap,
+  version: QuickSwapVersion.V3,
 });
 const camelot = steer.getAmm({
   chainId: ChainId.Arbitrum,
-  protocol: AmmProtocol.Camelot, version: CamelotVersion.V3,
+  protocol: AmmProtocol.Camelot,
+  version: CamelotVersion.V3,
 });
 const page = await camelot.listPools({ token: { symbol: "USDC" } });
 const address = page.items[0];
@@ -1704,12 +1948,12 @@ Pool fee data lives under `pool.fees`. Directional fields consistently use
 `currency0ToCurrency1` and `currency1ToCurrency0`, including pools with native currencies.
 Rates retain explicit units and meanings:
 
-| Family | Swap/LP fee fields | Additional fields |
-| --- | --- | --- |
-| Uniswap V3 | `fees.swapFeePips`, `fees.swapFeePercent` | Fixed swap fee, including any protocol share deducted from it |
-| Uniswap V4 | `fees.lpFeePips`, `fees.lpFeePercent` | Configured key fee, packed protocol fee and per-direction protocol fee rates |
-| Algebra Legacy | `fees.currency0ToCurrency1.lastFeePips/lastFeePercent` and the reverse direction | Token-specific community shares in permille and percentage |
-| Algebra Integral | `fees.lastFeePips`, `fees.lastFeePercent` | Community share in permille and percentage |
+| Family           | Swap/LP fee fields                                                               | Additional fields                                                            |
+| ---------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Uniswap V3       | `fees.swapFeePips`, `fees.swapFeePercent`                                        | Fixed swap fee, including any protocol share deducted from it                |
+| Uniswap V4       | `fees.lpFeePips`, `fees.lpFeePercent`                                            | Configured key fee, packed protocol fee and per-direction protocol fee rates |
+| Algebra Legacy   | `fees.currency0ToCurrency1.lastFeePips/lastFeePercent` and the reverse direction | Token-specific community shares in permille and percentage                   |
+| Algebra Integral | `fees.lastFeePips`, `fees.lastFeePercent`                                        | Community share in permille and percentage                                   |
 
 Stored dynamic fees are not promises of the next swap's execution fee. V4's LP fee and protocol
 fees remain separate; Algebra community shares are cuts of collected swap fees. The new SDK uses
@@ -1731,22 +1975,30 @@ const steer = new SteerClient({
 });
 const pancake = steer.getAmm({
   chainId: ChainId.BSC,
-  protocol: AmmProtocol.PancakeSwap, version: PancakeSwapVersion.V3,
+  protocol: AmmProtocol.PancakeSwap,
+  version: PancakeSwapVersion.V3,
 });
 const infinity = steer.getAmm({
   chainId: ChainId.BSC,
-  protocol: AmmProtocol.PancakeSwap, version: PancakeSwapVersion.InfinityCL,
+  protocol: AmmProtocol.PancakeSwap,
+  version: PancakeSwapVersion.InfinityCL,
 });
 
 const pool = await pancake.getPool(poolAddress);
-const indexed = await infinity.listPools({ token: { symbol: "USDT" }, limit: 10 });
+const indexed = await infinity.listPools({
+  token: { symbol: "USDT" },
+  limit: 10,
+});
 // Infinity listings return { poolId }; canonical keys resolve directly from the manager.
 const reference = indexed.items[0];
 if (!reference) throw new Error("No matching Infinity CL pools");
 const infinityPool = await infinity.getPool(reference);
 const key = await infinity.getPoolKey(infinityPool.poolId);
 const id = infinity.getPoolId(key);
-const ticks = await infinity.getSurroundingTicks(key, { lowerTick: -100, upperTick: 100 });
+const ticks = await infinity.getSurroundingTicks(key, {
+  lowerTick: -100,
+  upperTick: 100,
+});
 ```
 
 `getPoolKey` needs RPC, while
@@ -1762,12 +2014,12 @@ quotes accept optional `hookData` and reject input amounts outside positive `int
 Snapshots expose decoded prices, raw fees and percentages, and the shared `dynamicFee` flag.
 Infinity's Vault holds shared reserves; its snapshot does not expose those as pool balances.
 
-| Pinned read | Pancake V3 | Infinity CL |
-| --- | --- | --- |
-| Snapshot | 2 / 3 / 7 | 2 / 3 / 5 |
-| Specific ticks, one page | 2 / 3 / 8 | 2 / 3 / 6 |
-| Nonempty initialized range, one page | 2 / 3 / 9 | 2 / 3 / 7 |
-| Exact-input quote | 5 | 4 |
+| Pinned read                          | Pancake V3 | Infinity CL |
+| ------------------------------------ | ---------- | ----------- |
+| Snapshot                             | 2 / 3 / 7  | 2 / 3 / 5   |
+| Specific ticks, one page             | 2 / 3 / 8  | 2 / 3 / 6   |
+| Nonempty initialized range, one page | 2 / 3 / 9  | 2 / 3 / 7   |
+| Exact-input quote                    | 5          | 4           |
 
 Counts show deployless / override / Multicall compatibility, including rejected feature probes.
 Latest-block reads add one RPC. Infinity ID and full-key references use the same budgets;
@@ -1813,7 +2065,10 @@ if (vault instanceof UniswapV4Vault) {
 const holdings = await vault.getUserPosition(account);
 const quote = await vault.quoteDeposit({ asset: snapshot.token0, amount });
 const plan = await vault.prepareDeposit({
-  account, receiver: account, assets: quote.assets, slippageBps: 50,
+  account,
+  receiver: account,
+  assets: quote.assets,
+  slippageBps: 50,
 });
 ```
 
@@ -1856,10 +2111,19 @@ const amm = steer.getAmm({
   version: AerodromeVersion.SlipstreamV3,
 });
 const pool = await amm.getPool(poolAddress);
-const ticks = await amm.getSurroundingTicks(poolAddress, { lowerTick, upperTick });
-const quote = await amm.quote({
-  pool: poolAddress, inputCurrency: pool.token0, outputCurrency: pool.token1, amountIn,
-}, { account }); // Optional caller for fee-module discounts.
+const ticks = await amm.getSurroundingTicks(poolAddress, {
+  lowerTick,
+  upperTick,
+});
+const quote = await amm.quote(
+  {
+    pool: poolAddress,
+    inputCurrency: pool.token0,
+    outputCurrency: pool.token1,
+    amountIn,
+  },
+  { account },
+); // Optional caller for fee-module discounts.
 ```
 
 Use Slipstream, SlipstreamV2 or SlipstreamV3 explicitly; omitting version is ambiguous. All three
@@ -1913,7 +2177,10 @@ snapshot.rewards; // Separate reward asset, unclaimed rewards and unpaid Steer/s
 
 const page = await steer.listVaults({
   chainId: ChainId.Base,
-  amm: { protocol: AmmProtocol.Aerodrome, version: AerodromeVersion.SlipstreamV2 },
+  amm: {
+    protocol: AmmProtocol.Aerodrome,
+    version: AerodromeVersion.SlipstreamV2,
+  },
   token: { symbol: "USDC" },
 });
 ```
@@ -1935,7 +2202,12 @@ const withdrawal = await vault.previewWithdraw({ account, shares, receiver });
 withdrawal.amounts; // Raw/formatted token0 and token1 proceeds paid to receiver.
 withdrawal.rewards; // Aerodrome: { token, recipient: account, amount: { raw, formatted } }.
 
-const plan = await vault.prepareWithdraw({ account, shares, receiver, slippageBps: 50 });
+const plan = await vault.prepareWithdraw({
+  account,
+  shares,
+  receiver,
+  slippageBps: 50,
+});
 // Submit plan.transactions from plan.account on plan.chainId using your wallet integration.
 ```
 
@@ -1949,10 +2221,17 @@ quote, preview and unsigned preparation API is supported:
 
 ```ts
 const quote = await vault.quoteDeposit({ asset: token0, amount });
-const deposit = await vault.previewDeposit({ account, receiver, assets: quote.assets });
+const deposit = await vault.previewDeposit({
+  account,
+  receiver,
+  assets: quote.assets,
+});
 deposit.rewards; // Aerodrome: existing receiver rewards, settled before new shares are minted.
 const depositPlan = await vault.prepareDeposit({
-  account, receiver, assets: quote.assets, slippageBps: 50,
+  account,
+  receiver,
+  assets: quote.assets,
+  slippageBps: 50,
 });
 ```
 
@@ -1967,7 +2246,6 @@ Aerodrome's qualified helper accepts one raw initial share. One-sided vaults quo
 
 See [vault qualification, accounting and budgets](src/vault/adapters/aerodrome/qualification.md).
 
-
 ### Robinhood standalone Uniswap V4 snapshots
 
 `MultiPositionUniswapV4NoOracle` uses the same standalone V4 snapshot reader as the qualified
@@ -1983,7 +2261,6 @@ Live tests cover BSC Reserve and Robinhood NoOracle holders for both ERC20 and n
 including pagination and compatibility reads. Follow every `nextCursor`, even when `items`
 is empty. Incomplete indexed token metadata still limits token-filtered discovery.
 
-
 ### V4 pool-ID lookup without a pool indexer
 
 `amm.getPool({ poolId })`, `amm.getPoolKey(poolId)` and client/bulk ID getters share the
@@ -1996,6 +2273,11 @@ is an error, not a fabricated key. Pool browsing remains separate and requires a
 Base retains its existing indexed adapter by default. BNB combines indexed browsing with RPC key
 resolution; Robinhood uses RPC key resolution without indexed pool browsing.
 
+### BSC SushiSwap and Uniswap V3 snapshots
+
+The exact qualified `MultiPositionSushi` and `MultiPositionUniswapV3` implementations now support vault resolution, single/bulk snapshots and direct pool reads. They reuse the fixed-fee V3 reader with 15% aggregate fee rounding. Normal bulk snapshot pages use two pinned RPC requests and preserve per-member failures with `allowFailure: true`.
+
+AMM-filtered Steer vault listing works. Underlying AMM pool browsing remains unqualified: both inherited subgraphs returned pool rows without the expected factory identity and the SDK rejects those responses. Deposit/withdrawal flows were not newly qualified by this snapshot work. Base Sushi is separately qualified after the 30-vault migration, using its exact upgraded FeeManager/helper implementation; see [Base Sushi qualification](src/vault/adapters/uniswap-v3/base-sushi-qualification.md). See [source and live qualification](src/vault/adapters/uniswap-v3/bsc-qualification.md).
 
 ### BSC PancakeSwap V3 vault snapshots
 
@@ -2015,7 +2297,6 @@ See [Pancake vault qualification](src/vault/adapters/uniswap-v3/pancake-qualific
 identities, funded fixtures, retained-response regressions and live test coverage. Separate funded user-flow qualification now covers deposit quotes/preparation, partial/full
 withdrawals, user positions and indexed wallet balance scanning.
 
-
 ### Camelot legacy vault snapshots on Arbitrum
 
 `MultiPositionCamelot` vaults on Arbitrum use the shared `AlgebraLegacyVault` implementation.
@@ -2034,7 +2315,6 @@ See [Camelot qualification](src/vault/adapters/algebra-legacy/camelot-qualificat
 Funded simulations now also verify deposit quotes/preparation, partial/full withdrawals, user
 positions and wallet discovery. Arbitrum deposit accounting uses the verified Multicall3 deployment.
 
-
 ### Blackhole CL on Avalanche
 
 Select pools with `{ protocol: AmmProtocol.Blackhole, version: BlackholeVersion.CL }`.
@@ -2053,7 +2333,6 @@ compatibility calls, without a two-RPC guarantee.
 See [qualification](src/vault/adapters/blackhole/qualification.md) for exact identities and evidence.
 Run `npm run test:integration:blackhole` with `AVALANCHE_RPC_URL` for the paced historical live suite.
 
-
 #### Blackhole AVAX deposit and exit
 
 Use the zero address as the native AVAX input when the vault holds WAVAX:
@@ -2081,7 +2360,6 @@ This prepares a separate WAVAX withdrawal transaction that pays AVAX to `recipie
 checking its balance. Use actual received amounts rather than the earlier withdrawal preview.
 Both stages are separate wallet operations; preparation sends nothing.
 
-
 ### Pancake V3 and Camelot user-flow verification
 
 Run `npm run test:integration:vault-flows` with BSC and Arbitrum archival RPC URLs. This suite
@@ -2089,20 +2367,21 @@ repeats actual-contract deposits/withdrawals and balance-based discovery at reta
 It uses pinned public indexer responses and paces live RPC calls by 1.5 seconds. No Graph API
 credentials or Base RPC are needed for this isolated runner. Full historical state and temporary
 EOA code overrides must be supported. Native BNB/ETH wrapping helpers remain separate work.
+
 ### Bulk vault execution coverage
 
 Accepting an array does not imply optimized execution. In `4.0.0-next.8`, BSC and Arbitrum
 accepted both bulk methods but used individual-vault reads with concurrency four. This change
 adds native bulk readers for their exact qualified deployments.
 
-| Chain / qualified vaults | Bulk API | Efficient execution in `4.0.0-next.8` | Efficient execution after this change |
-| --- | --- | --- | --- |
-| Base: V3, Integral, Aerodrome | Yes | Yes | Yes |
-| Polygon: registered V3, Legacy, Integral | Yes | Yes | Yes |
-| BSC: Pancake V3 and Reserve V4 | Yes | No | Yes |
-| Arbitrum: Camelot legacy | Yes | No | Yes |
-| Robinhood: NoOracle V4 | Yes | No | Bounded individual reads |
-| Avalanche: Blackhole | Yes | No | Bounded individual reads |
+| Chain / qualified vaults                 | Bulk API | Efficient execution in `4.0.0-next.8` | Efficient execution after this change |
+| ---------------------------------------- | -------- | ------------------------------------- | ------------------------------------- |
+| Base: V3, Integral, Aerodrome            | Yes      | Yes                                   | Yes                                   |
+| Polygon: registered V3, Legacy, Integral | Yes      | Yes                                   | Yes                                   |
+| BSC: Pancake V3 and Reserve V4           | Yes      | No                                    | Yes                                   |
+| Arbitrum: Camelot legacy                 | Yes      | No                                    | Yes                                   |
+| Robinhood: NoOracle V4                   | Yes      | No                                    | Bounded individual reads              |
+| Avalanche: Blackhole                     | Yes      | No                                    | Bounded individual reads              |
 
 On providers supporting code-only overrides, optimized resolution uses two pinned RPC calls per
 64-vault page. Snapshots use one original-code/position-count preflight per 16-vault page and one
@@ -2130,7 +2409,10 @@ for (const result of vaults) {
   else console.log(result.error);
 }
 
-const pools = await amm.getPools(references, { blockNumber, allowFailure: true });
+const pools = await amm.getPools(references, {
+  blockNumber,
+  allowFailure: true,
+});
 for (const result of pools) {
   if (result.status === "success") console.log(result.pool);
   else console.log(result.error);
@@ -2145,7 +2427,6 @@ malformed shared RPC responses, and shared vault metadata request failures still
 `SteerClient.getPools(request)` discovery remains strict; partial pool reads use the selected
 AMM's `getPools(references, options)`.
 
-
 V4 partial ID reads isolate `V4PoolKeyNotFoundError` for a verified absent indexed key or
 uninitialized onchain pool. Shared indexer, JSON/schema, RPC, and unexpected key-adapter errors
 reject the request, including through registered adapter overrides. Custom V4 data adapters