@steerprotocol/sdk 3.8.1 → 4.0.0-next.11

package/README.md

@@ -1,509 +1,2158 @@
-# Steer Protocol SDK
+# Next SDK scaffold
 
-A TypeScript SDK for interacting with Steer Protocol services.
+`SteerClient` is the SDK entry point. Chains describe where Steer and its integrations run; they
+don't own a selectable protocol. The built-in catalog contains all 53 chains registered by the prior
+SDK, with their effective Steer contract addresses, start blocks, and subgraph URLs.
+Uniswap V3 on Base supports verified pool reads, pool discovery by family and factory, and single-pool exact-input quotes, plus indexed pool listing. Steer
+vault resolution and position/accounting reads are available for mapped Base and Polygon implementations.
+Deposit and withdrawal previews and unsigned preparation are available for supported liquidity vaults.
+Transaction execution is application-owned.
 
-## Installation
+## Use Steer
 
-```bash
-npm install @steerprotocol/sdk viem
-# or
-yarn add @steerprotocol/sdk viem
-# or
-pnpm add @steerprotocol/sdk viem
-```
+Initialization takes options; consumers don't pass a deployment catalog as a positional argument:
 
-## Usage
+```ts
+const steer = new SteerClient({
+  transports: { [ChainId.Base]: rpcTransport },
+});
+```
 
-```typescript
-import { createPublicClient, createWalletClient, http } from 'viem';
-import { mainnet } from 'viem/chains';
-import { VaultClient, StakingClient } from '@steerprotocol/sdk';
+Chain metadata is available immediately, without an RPC transport:
 
-// Create viem clients
-const publicClient = createPublicClient({
-  chain: mainnet,
-  transport: http(),
-});
+```ts
+const steer = new SteerClient();
 
-const walletClient = createWalletClient({
-  chain: mainnet,
-  transport: http(),
-});
+const chains = steer.getChains(); // All 53 registered networks, including legacy testnets.
+const subgraphUrl = steer.getSubgraphUrl(ChainId.Base);
+const vaultRegistry = steer.getDeployment(ChainId.Base).contracts.VaultRegistry;
+// vaultRegistry.address and vaultRegistry.startBlock (bigint when known)
+```
 
-// Initialize clients
-const vaultClient = new VaultClient(publicClient, walletClient, 'production');
-const stakingClient = new StakingClient(publicClient, walletClient);
+`ChainId.Ethereum` and the legacy name `ChainId.Mainnet` both select chain 1. Each network appears
+only once in `getChains()`. Chain metadata also retains transaction type and wrapped native token
+address, plus its symbol and wrapping flag where the prior SDK supplied them.
 
-// Use vault operations (including single-asset deposits)
-const vaults = await vaultClient.getVaults({ chainId: 1 });
+Consumers use these accessors (lending still needs an integration):
 
-// Use staking operations
-const pools = await stakingClient.getStakingPools();
+```ts
+const vault = await steer.getVault(ChainId.Base, vaultAddress);
+const amm = steer.getAmm({ chainId: ChainId.Base, protocol: AmmProtocol.Uniswap, version: UniswapVersion.V3 });
+const lending = steer.getLending(aaveV3Base);
+
+steer.getSubgraphUrl(ChainId.Base);
+steer.getDeployment(ChainId.Base).contracts.VaultRegistry;
+amm.subgraphUrl;
+lending.subgraphUrl;
 ```
 
-## Supported Chains, Subgraphs, and Protocols
+Base V3/Integral and Polygon V3/Legacy/Integral vault reads are implemented below. Lending loaders still need their integration
+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.
+
+## 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`;
+they are not re-exported from the SDK root.
 
-The SDK exposes a capabilities registry so integrators can discover supported chains and the relevant configuration (subgraph URLs, protocol availability, deployments) without enumerating enums.
+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.
+
+## Vault execution context
+
+Liquidity vaults expose strategy inputs through the existing vault object:
 
 ```ts
-import { getSupportedChains, getSupportedChainIds } from '@steerprotocol/sdk';
+const blockNumber = 12345678n; // Caller-selected operation block.
+const vault = await steer.getLiquidityVault(chainId, vaultAddress, { blockNumber });
+const context = await vault.getExecutionContext({
+  blockNumber,
+  epochTimestamp: 1793577600n, // Explicit Unix seconds, independent of the wall clock.
+});
+```
+
+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.
+
+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
+vault's `getTotalAmounts()` without poke, matching the prior execution-context semantics;
+they are not aliases for the fee-adjusted `getSnapshot().total` accounting fields.
+
+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.
+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.
+
+Custom Steer data adapters can implement `getLastVaultExecution(request, options)` to supply
+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.
+
+Read-only live verification on November 2, 2026 passed 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
+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.
+
+Reproduce with the explicit RPC/indexer settings in `.env.integration`:
+
+```sh
+npm run test:integration -- tests/integration/vault/execution-context.multichain.test.ts --reporter=verbose
+```
+
+## Vault discovery
 
-// Most lightweight: chains that have Steer subgraph config
-const supportedChainIds = getSupportedChainIds();
+List indexed vault metadata, then load a result through the identity-verified resolver:
 
-// Opt in to additional details (deployments, protocol subgraphs, etc)
-const supported = getSupportedChains({
-  include: {
-    subgraph: true,
-    deployments: true,
-    protocols: true,
-    singleAssetDeposit: true,
-  },
-  // Used for protocol-specific subgraph discovery (The Graph / Studio)
-  theGraphApiKey: process.env.SUBGRAPH_STUDIO_KEY ?? '',
+```ts
+const page = await steer.listVaults({
+  chainId: ChainId.Base,
+  amm: { protocol: AmmProtocol.Uniswap, version: UniswapVersion.V3 },
+  token: { symbol: "USDC" },
+  limit: 20,
 });
 
-for (const chain of supported) {
-  console.log({
-    chainId: chain.chainId,
-    chain: chain.chain,
-    subgraphUrl: chain.subgraphUrl,
-    protocolCount: chain.protocols?.length ?? 0,
-    features: chain.features,
+for (const metadata of page.items) {
+  const vault = await steer.getVault(ChainId.Base, metadata.id);
+  vault.metadata.name; // Complete indexed metadata, separate from verified accounting.
+}
+
+// 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));
+
+if (page.nextCursor) {
+  const next = await steer.listVaults({
+    chainId: ChainId.Base,
+    cursor: page.nextCursor,
+    limit: 20,
   });
 }
 ```
 
-### Available Features
-
-- **Vault Operations**: Traditional vault deposits, withdrawals, and balance checking
-- **Single-Asset Deposits**: Deposit one token and automatically balance for LP provision
-- **Staking**: Interact with staking pools for rewards
-- **Pool Data**: Fetch pool information and statistics
-- **Smart Rewards**: Manage reward campaigns and claims
+`listVaults()` returns `Page<VaultMetadata>` with immutable indexed records:
 
-## Pool Creation and Initialization
+```ts
+interface VaultMetadata {
+  readonly id: Address;
+  readonly name: string | null;
+  readonly symbol: string | null;
+  readonly decimals: string | null;
+  readonly beaconName: string;
+  readonly createdAt: string;
+  readonly state: string | null;
+  /** Contract address or 32-byte V4 pool ID. */
+  readonly pool: Hex | null;
+  readonly poolKey?: string | null;
+  readonly token0: Address | null;
+  readonly token1: Address | null;
+  readonly payloadIpfs: string | null;
+  readonly strategyToken: { readonly id: string } | null;
+}
+```
 
-Pool lifecycle support is exposed as signer-neutral primitives rather than methods on `PoolClient`. Lifecycle capability is explicit and fail-closed; protocol discovery alone never enables a write path.
+This replaces address-only pages. Use `item.id` when passing a listed result to a vault getter.
+`decimals` and `createdAt` retain their indexed string representation. Null fields remain null;
+Unavailable indexed pool/token address fields represented by empty strings become `null`; the native zero address remains unchanged.
+`pool` preserves either a contract address or a 32-byte V4 pool ID.
+`poolKey` is omitted when the subgraph schema does not expose it. Only an explicit rejection of
+that optional field permits querying without it; other GraphQL and transport errors propagate.
+
+For native-currency vault searches, pass the zero address as `token.address` to `listVaults`
+or `listUserVaults`. Native ETH/BNB remain distinct from WETH/WBNB. Pagination retains the
+native filter, and combined address/symbol/name criteria must match the same token. This
+does not permit zero vault IDs or wallet accounts and does not change deposit wrapping behavior.
+
+Every loaded `SteerVault` exposes the same model as `vault.metadata`. Vault construction loads
+indexed metadata once per resolution/snapshot batch, preserving input order and duplicates.
+Loading a vault, including internal construction during bulk snapshots, now requires indexed
+metadata in addition to RPC identity verification. Missing records and indexer failures propagate.
+Existing resolved vault operations retain that metadata snapshot. It reflects the indexer's head
+at construction, independently of an explicitly selected RPC block; state, pool and token hints
+never replace the verified underlying references or accounting used by vault methods.
+Custom Steer data adapters implement `getVaultMetadata(addresses, options)` as well as listing;
+custom vault constructors pass `context.metadata` to the base constructor.
+
+`amm` and `token` are optional. Token filters accept `address`, `symbol`, and `name`;
+symbol and token name use case-insensitive substring matches. Combined criteria must match
+the same token on either side. `name` refers to the underlying token, not the vault's name.
+AMM selection uses the same typed protocol/version/deployment selectors and ambiguity rules as
+`getAmm()`. Qualified AMM discovery mappings currently cover Uniswap V3 and QuickSwap Integral
+on Base, plus Polygon Uniswap V3, SushiSwap V3, Retro V3, QuickSwap V3 and QuickSwap V4.
+Other AMM filters fail explicitly until their exact indexed beacon mappings are qualified.
+
+Unfiltered listing costs zero RPC requests: two HTTP requests for the first page (snapshot and vaults),
+then one per continuation. An older schema without poolKey adds one HTTP request for field negotiation.
+AMM filters with factory qualification also perform RPC checks at the indexed block. Cursors retain filters and pin every page to the indexed block and
+subgraph deployment. If supplied again, filters must agree with the cursor. Results contain indexed metadata for
+candidates, which may include implementations unsupported by `getVault()`; listing does not
+establish current onchain identity or add resolver support. Indexing, HTTP, and GraphQL errors propagate.
+
+`steer.getDeployment(chainId).listVaults(request, options)` uses the same listing path. Both
+entry points honor client `indexers`/`http` configuration and accept per-request `fetch`, headers,
+timeout, and cancellation overrides as the second argument. The existing `getVault()` API and
+its onchain identity checks remain the loading path.
+
+When catalog records are already available, supply them through the optional `VaultLoadOptions.metadata` field:
 
-The explicit lifecycle registry covers all currently configured Uniswap V3-compatible, Uniswap V4, and Algebra-family chain/protocol pairs: 104 deployments in total. It includes exact bigint price encoding, block-pinned preflight inspection, family-specific unsigned builders, sender-aware simulation, and receipt/postcondition verification. V3 factory-only and Algebra standard-pool flows remain explicitly two-step where no atomic initializer is proven.
+```ts
+const vaults = await steer.getVaults(ChainId.Base, records.map((record) => record.id), {
+  blockNumber: 100000n,
+  metadata: records,
+});
+```
 
-See the [detailed pool-lifecycle guide](https://github.com/SteerProtocol/sdk/blob/master/src/pool-lifecycle/README.md) for the complete flow and API boundaries.
+This skips metadata subgraph requests while retaining all onchain registration, implementation,
+protocol and pool checks. Records are matched by address case-insensitively and copied before IO.
+Supply one complete record per unique requested address. Missing, duplicate, unrequested or malformed
+records fail without a metadata fetch. Results preserve requested order and duplicate addresses.
+Omit `metadata` to retain the existing subgraph lookup. The same options work on `getVault`, typed
+vault getters and the connected-network loading methods. Metadata remains descriptive and is never
+forwarded to viem/RPC or used to establish verified identity. Snapshot/accounting options are unchanged.
+
+`getVaults(chainId, addresses, options)` returns the same resolved vault objects as `getVault()`
+in input order, including duplicate inputs. Base V3/Integral resolution uses a bulk Solidity reader:
+**two RPC requests per page of at most 64 vaults** at a pinned block. Latest reads add one shared
+head lookup for the entire invocation. The first call verifies original proxy and implementation
+code hashes; the second uses code-only vault-address overrides to verify private beacon/registry
+storage, exact implementations, pool registration and token ordering. It does not fetch accounting snapshots.
+
+Single `getVault()` and `getLiquidityVault()` lookups use the same reader with one input: **2 pinned
+RPCs or 3 for latest** on supported Base and Polygon deployments. Kind checks, adapter instances,
+custom underlying readers and constructors are preserved. If the provider explicitly rejects bulk
+overrides, resolution falls back directly to the original single reader, with no recursive bulk
+probe. Base V3/Integral compatibility costs 15/13 pinned RPCs after first-stage rejection, or 16/14
+after second-stage rejection. Latest adds one. These fallback counts include rejected probes.
+
+Registered adapters and constructors remain in use. Custom underlying readers still execute and
+may add RPC requests. Providers explicitly rejecting state overrides use the existing single-vault
+resolver, with at most four active loads and no repeated bulk probe during that invocation.
+Reverts, identity failures, malformed responses, timeouts and rate limits propagate without fallback.
+For a pinned V3 + Integral pair, compatibility uses 27 calls after preflight rejection or 28 after
+second-stage rejection, including probes. Empty input returns an empty array without IO. A failed
+resolution rejects the batch without partial results or starting later pages. The deployment-level
+equivalent is `steer.getDeployment(chainId).getVaults(addresses, options)`.
+
+## Bulk vault accounting snapshots
+
+Bulk snapshots include optional `implementation: { address, codeHash, beacon, beaconName }` metadata from the
+registered native reader's verified identity at `blockNumber`. This reuses the implementation hash
+already checked by that reader and adds no RPC calls. Custom bindings without a registered verified
+`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.
 
-## Staking Client
 
-The StakingClient provides functionality for interacting with Steer Protocol staking pools. It supports both single and dual reward staking pools.
+```ts
+const supported: boolean = steer.getDeployment(chainId).supportsVaultSnapshots(beaconName);
+```
 
-### Features
+This synchronous check performs no RPC or HTTP requests. It matches an exact indexed beacon name
+against the network's registered liquidity implementation bindings with a snapshot reader.
+Discovery eligibility alone does not establish support. Custom bindings can supply optional
+`beaconNames`; missing names, missing readers and deployments without a resolver return `false`.
+The result describes expected registered support, not a particular vault's current implementation
+or provider compatibility. Actual snapshot reads retain their onchain identity and implementation
+checks and can still fail. Existing batch limits continue to apply.
 
-- Fetch available staking pools
-- Stake and withdraw tokens
-- Claim rewards
-- Check earned rewards and balances
-- Calculate APR for staking pools
-- Support for both single and dual reward pools
+```ts
+const snapshots = await steer.getVaultSnapshots(
+  ChainId.Base,
+  vaultAddresses,
+  { blockNumber }, // Optional; latest selects one shared block for the entire invocation.
+);
 
-### Example Usage
+snapshots[0]?.total.token0.formatted;
+snapshots[0]?.fees.net.token1.raw;
+```
 
-```typescript
-// Initialize the staking client
-const stakingClient = steerClient.staking;
+Opt in to independent vault failures with `allowFailure: true`:
 
-// Get all staking pools
-const pools = await stakingClient.getStakingPools();
+```ts
+const results = await steer.getVaultSnapshots(ChainId.Base, vaultAddresses, {
+  blockNumber,
+  allowFailure: true,
+});
+for (const [index, result] of results.entries()) {
+  if (result.status === "success") consume(vaultAddresses[index], result.snapshot);
+  else report(vaultAddresses[index], result.error);
+}
+```
 
-// Get pools for a specific chain
-const polygonPools = await stakingClient.getStakingPools(137); // Polygon chain ID
+This mode preserves an outcome for every input, including duplicates. Preflight and snapshot
+reverts, decoding errors and vault validation failures stay with that vault. Registered readers
+and overrides still run their original identity checks. Shared RPC/HTTP failures, malformed batch
+responses and invalid shared contexts still reject the call. Provider feature rejection alone
+selects the existing compatibility path. Ordinary bounded override pages still use two RPCs;
+there is no batch splitting to locate a failed vault. Calls without this option remain atomic.
+
+The deployment-level `steer.getDeployment(chainId).getVaultSnapshots(addresses, options)` is
+identical. Results use the same `LiquidityVaultSnapshot` model as `vault.getSnapshot()`, in input
+order, including duplicates. This method resolves identity and reads accounting; `getVaults()`
+continues to return vault objects without accounting. Supported built-in mappings are Base V3/Integral and the Polygon deployments described below.
+Other vault categories and implementations fail explicitly.
+
+Small pinned pages use **two RPC requests for up to 16 vaults**, including resolution. The first
+code-only coordinator override verifies original proxy and implementation code against exact
+beacon mappings and counts configured positions through original vault views. The second installs
+family-local code at the verified vault addresses and reads stored identities, pool registration,
+token decimals, weights, idle/reserved balances, principal and fees at the same block. Only code is
+overridden; storage, balances, implementations, pools, tokens and registry code remain untouched.
+
+Preflight position counts split execution into subbatches with a **128-position soft budget**.
+Each page costs one preflight plus one request per subbatch. A vault exceeding that position budget
+runs alone through the existing family reader, retaining support for large configurations. This is
+scheduling, not a protocol position limit. Latest adds one head lookup for the entire invocation.
+The measured batch-size rationale and coverage limits are in [the snapshot benchmark](benchmarks/vault-snapshots.md).
+
+The actual implementation bindings, custom underlying readers, constructors, vault `getSnapshot()`
+methods and AMM `getPool()` overrides still execute. Both paths first obtain family accounting, then
+validate the registered vault method's output against that snapshot's block, pool, token identity/decimals
+and configured position count. AMM overrides retain their existing semantics. Calling the default vault
+method reuses the already verified snapshot without another RPC; an override without `super` still
+receives the same identity checks. Raw-reader and completed-snapshot reuse stay internal to the
+invocation; retained options expire on success/failure and concurrent calls remain isolated.
+
+Only an explicit unsupported-override rejection selects compatibility, using the existing single-vault
+resolver and snapshot paths with at most four active loads. Unsupported bulk mode is probed once per
+invocation. Required reverts, identity/accounting errors, malformed responses and transport failures
+propagate without retrying individual members. Empty input does no IO; malformed addresses fail
+before RPC. A failure rejects the whole call and does not schedule later pages. These are accounting
+snapshots, not withdrawal quotes; no Graph credentials or transactions are involved.
+
+## Bulk pool snapshots
+
+Read multiple pools using the same references accepted by `getPool()`:
 
-// Stake tokens
-await stakingClient.stake({
-  stakingPool: '0x...', // staking pool address
-  amount: 1000000000000000000n, // amount in wei
+```ts
+const amm = steer.getAmm({
+  chainId: ChainId.Base,
+  protocol: AmmProtocol.Uniswap,
+  version: UniswapVersion.V3,
+});
+const pools = await amm.getPools([poolAddress, anotherPoolAddress], { blockNumber });
+
+// Let the family discover each pool's registered AMM.
+const discovered = await steer.getPools({
+  chainId: ChainId.Base,
+  family: AmmFamily.UniswapV3,
+  addresses: [poolAddress, anotherPoolAddress],
+  blockNumber,
 });
+discovered[0]?.amm;
+```
 
-// Check earned rewards
-const earned = await stakingClient.earned('0x...', '0x...'); // pool address, account address
-console.log('Earned rewards:', earned.data);
+`getPools()` returns full snapshots in input order, including duplicates. It reads one block
+for the whole invocation, returns an immutable result array, and rejects the batch if any
+required read fails. Empty input requires no RPC. `listPools()` still performs indexed search;
+use `amm.getPools(page.items)` to load a listing page.
 
-// Calculate APR
-const apr = stakingClient.calculateAPR(pool, rewardTokenPriceUSD, totalStakedUSD);
-```
+All implemented AMMs support bulk snapshots: Uniswap V3/V4, PancakeSwap V3/Infinity CL,
+QuickSwap Integral, symmetric Legacy Algebra and directional Legacy Algebra. V3 and Legacy
+client discovery use `addresses`; Integral, V4 and Infinity use `references`, preserving
+custom deployers and pool keys/IDs. V4 ID references still need indexed key lookup, with
+per-request HTTP overrides supported; duplicate IDs share one lookup within the invocation, including compatibility fallback.
+Infinity IDs resolve onchain within the Solidity reader.
 
-### Available Methods
+On supported providers, direct `amm.getPools()` uses one chain check plus one Solidity call
+per page of at most 32 pools: **2 RPCs pinned for up to 32 pools**, 3 for 33 pools. Latest reads
+add one head lookup. Readers inherit the existing single-pool identity checks and formatting;
+only ephemeral helper code is overridden, never pool/token code, storage or balances.
 
-- `getStakingPools(chainId?: number, protocol?: string)`: Fetch available staking pools
-- `stake(params: StakeParams)`: Stake tokens in a pool
-- `withdraw(params: WithdrawParams)`: Withdraw tokens from a pool
-- `getReward(params: GetRewardParams)`: Claim rewards
-- `earned(stakingPool: Address, account: Address)`: Get earned rewards
-- `totalSupply(stakingPool: Address)`: Get total staked tokens
-- `balanceOf(stakingPool: Address, account: Address)`: Get staked balance
-- `calculateAPR(pool: StakingPool, rewardTokenPriceUSD: number, totalStakedUSD: number)`: Calculate current pool APR
+Discovery has additional identity costs. On Base, a factory-based page using one AMM takes
+3 pinned RPCs; V4 manager discovery takes 2. Other chains can use direct factory reads when no
+qualified Multicall deployment is configured. Each result retains its registered `amm`.
 
-## Single-Asset Deposit
+The reader tries deployless execution, then helper-code overrides after explicit feature
+rejection. If both are unsupported, the rest of that invocation uses compatibility reads
+with at most four active pool loads. Custom `getPool()` overrides execute through that bounded
+path and retain their normal behavior and additional RPC costs. Reverts, malformed responses,
+identity errors, network failures and rate limits propagate without compatibility retries.
 
-The Single-Asset Deposit feature allows users to deposit only one token (token0 or token1) into a liquidity vault, while the contract internally performs a swap to balance the token pair before depositing into the vault. This eliminates the need for users to provide both tokens in the correct ratio.
+The [batch-size benchmarks](benchmarks/README.md) explain the 32-pool/64-vault defaults.
+Execution fallback and V4 key reuse live only for one invocation, including nested discovery
+pages. Retained options and failed/concurrent calls cannot retain that state.
 
-### Features
+## Optional logging
 
-- **Single Token Input**: Deposit only token0 or token1 instead of both
-- **Automatic Balancing**: Internal swap to achieve the correct token ratio
-- **Slippage Protection**: Configurable slippage limits for both swap and deposit
-- **Preview Functionality**: Simulate the entire process before execution
-- **Modular Architecture**: Each step is separately testable and reusable
-- **Multiple AMM Support**: Currently supports UniswapV3, extensible for other AMMs
-- **Comprehensive Error Handling**: Detailed error messages and validation
+Pass an application-owned logger when you want structured pool-listing events. Consola works
+without a wrapper; install it in the application and use its numeric debug level:
 
-### How It Works
+```ts
+import { createConsola } from "consola";
+import { AmmProtocol, ChainId, SteerClient, UniswapVersion } from "@steerprotocol/sdk";
 
-The single-asset deposit process follows these steps:
+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 });
 
-1. **Calculate Swap Amount**: Determine how much of the input token needs to be swapped
-2. **Calculate Limit Price**: Apply slippage protection using current pool price
-3. **Simulate Swap**: Preview the swap results without executing
-4. **Estimate LP Tokens**: Calculate expected LP token output
-5. **Execute Deposit**: Submit the transaction with all parameters
+await amm.listPools({ token: { symbol: "USDC" } });
+```
 
-### Quick Start
+The application still provides the proxy route. Node applications need an absolute proxy URL.
+You can also pass any logger implementing the exported `Logger` interface. The SDK doesn't bundle
+Consola, set logging levels, or configure reporters. Without a logger, it emits nothing.
 
-```typescript
-import { VaultClient, AMMType } from '@steerprotocol/sdk';
-import { createPublicClient, createWalletClient, http, parseEther } from 'viem';
-import { mainnet } from 'viem/chains';
+Each `amm.listPools()` call gets an independent operation ID. Debug events describe query stages,
+indexer provider/routing, and HTTP response headers. Each response includes a request ID, status,
+and `headersDurationMs`. The info-level `amm.pools.list.completed` event includes `resultCount`
+and total `durationMs`, including response body reading and parsing. A failure produces one
+error-level `amm.pools.list.failed` event; caller cancellation produces a debug-level
+`amm.pools.list.cancelled` event. Deadlines report `TIMEOUT` and caller cancellation reports
+`CANCELLED`, including cancellation with a custom reason. An overlapping abort does not reclassify
+an unrelated HTTP, network, or parsing failure. Public listing methods keep the two-argument
+`listPools(request, options)` signature; operation context stays internal.
 
-// Setup clients
-const publicClient = createPublicClient({
-  chain: mainnet,
-  transport: http(),
-});
+Events contain SDK-selected fields only. They exclude URLs, keys, headers, query bodies, token
+filters, cursors, and raw error messages, stacks, and causes. Failures retain their original thrown
+error for the caller. Synchronous logger errors and rejected logger promises don't affect SDK
+results; the SDK doesn't wait for reporters or flush them. Events are shallow-frozen primitive
+records. Reporters control their own formatting, filtering, storage, and delivery.
 
-const walletClient = createWalletClient({
-  chain: mainnet,
-  transport: http(),
-});
+Logging currently covers the AMM pool-listing path through its data adapter, indexer, and HTTP
+transport. Direct data-adapter calls, RPC reads/quotes, and vault operations don't emit operation
+events yet.
 
-// Initialize vault client
-const vaultClient = new VaultClient(publicClient, walletClient, 'production');
+## Import contracts directly
 
-// Preview single-asset deposit
-const preview = await vaultClient.previewSingleAssetDeposit(
-  {
-    assets: parseEther('100'), // 100 tokens to deposit
-    receiver: userAddress, // Address to receive LP tokens
-    vault: vaultAddress, // Vault contract address
-    isToken0: true, // Depositing token0
-    depositSlippagePercent: 5n, // 5% max slippage for deposit
-    swapSlippageBP: 500, // 5% slippage for internal swap (in basis points)
-    ammType: AMMType.UniswapV3, // AMM type
-    singleAssetDepositContract: contractAddress, // Single-asset deposit contract
-  },
-  poolAddress
-);
+For contract metadata alone, use a named export from the package root:
 
-if (preview.success) {
-  console.log('Expected LP tokens:', preview.data.lpEstimation.lpTokens);
-  console.log('Amount to be swapped:', preview.data.swapAmount);
-  console.log('Final token0 amount:', preview.data.lpEstimation.finalAmount0);
-  console.log('Final token1 amount:', preview.data.lpEstimation.finalAmount1);
-
-  // Execute the deposit
-  const result = await vaultClient.singleAssetDeposit({
-    assets: parseEther('100'),
-    receiver: userAddress,
-    vault: vaultAddress,
-    isToken0: true,
-    depositSlippagePercent: 5n,
-    swapSlippageBP: 500,
-    ammType: AMMType.UniswapV3,
-    singleAssetDepositContract: contractAddress,
-  });
+```ts
+import { baseContracts } from "@steerprotocol/sdk";
 
-  if (result.success) {
-    console.log('Transaction hash:', result.data);
-  }
-}
+baseContracts.VaultRegistry.address;
+baseContracts.VaultRegistry.startBlock;
 ```
 
-## Block-pinned vault execution context
+Each chain has a deeply frozen contract map, such as `arbitrumContracts`, `polygonContracts`,
+`bscContracts`, and `ethereumContracts`. `mainnetContracts` aliases `ethereumContracts`. These maps
+are the source for the client catalog too; they don't construct a client or require an RPC transport.
 
-Strategy execution consumers can read a normalized, JSON-safe vault context without selecting
-protocol adapters or assembling pool state themselves:
+ESM consumer bundlers can remove unused chains and client code. The Base-only browser fixture
+currently measures about 1.34 kB minified / 554 bytes gzipped. `npm run check:bundle` verifies the built
+package root import, excludes other-chain addresses, endpoints, and client code, and enforces a 3 kB
+minified budget. It runs as part of `npm run check` after building. Sizes vary with bundler settings.
 
-```typescript
-import { getVaultExecutionContext } from '@steerprotocol/sdk';
+`new SteerClient()` still includes the complete catalog so it can inventory and select all networks.
+The savings above apply to bundled ESM consumers; a Node import or CommonJS `require` loads the
+published module, and the npm installation still contains the complete package.
 
-const context = await getVaultExecutionContext({
-  publicClient,
-  vaultAddress: '0x666805942995ff8494294720a1dadb7cd2348750',
-  blockNumber: 49_251_269n,
-  epochTimestamp: 1_800_000_000n, // Unix seconds; explicit, never wall-clock time
-});
+## Chain inventory provenance
+
+`src/catalog/` and `src/contracts/` snapshot the effective values from the prior SDK's `src/const/network.ts` and
+`src/const/subgraph.ts`, keyed by `src/const/chain.ts`. It includes all 455 contract entries after
+network overrides and the FeeManager overlay, with numeric start blocks converted to bigint.
+Missing optional fields remain absent. Tests compare every entry against the prior SDK directly;
+the published package has no dependency on that implementation.
 
-if (!context.success) throw new Error(context.error);
+This inventory preserves legacy testnets and 32 archive subgraph URLs. Addresses and endpoints have
+not been verified live. Catalog presence does not establish current deployment health, usable
+indexing, AMM or lending support, or transaction feature support. No RPC URLs or credentials are
+bundled.
 
-console.log(context.data.protocol, context.data.currentTick);
-console.log(context.data.totalAmount0, context.data.lastExecutionTimeSeconds);
+The old deployment files `goerli`, `optimismgoerli`, `arbitrumgoerli`, `mumbai`, `localhost`,
+`bartiotest`, and `pyzkevm` were not registered networks in the prior SDK. They are not added to the
+new catalog as additional chains.
+
+## Uniswap V3 on Base
+
+```ts
+import { AmmFamily, ChainId, SteerClient, AmmProtocol, UniswapVersion } from "@steerprotocol/sdk";
+
+const steer = new SteerClient({ transports: { [ChainId.Base]: rpcTransport } });
+const pool = await steer.getPool({
+  chainId: ChainId.Base,
+  address: "0xd0b53D9277642d899DF5C87A3966A349A798F224",
+  family: AmmFamily.UniswapV3,
+});
+
+pool.amm.protocol;
+pool.amm.family;
+pool.amm.subgraphUrl;
+pool.tick;
+pool.liquidity;
+pool.blockNumber;
+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.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 });
+amm.contracts.factory.address;
+amm.subgraphUrl;
+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 });
 ```
 
-The same capability is available as `vaultClient.getExecutionContext(...)`. The SDK resolves the
-vault's beacon name, beacon address, and protocol through the deployed `VaultRegistry`, verifies
-non-v4 pool factories against SDK protocol configuration, and reads positions, totals, tick spacing,
-and pool state at the exact supplied block. Uniswap v4 uses the vault's complete `poolKey()`, derives
-its pool ID, and reads state through the configured `StateView`; an optional `poolKey` input acts as
-an assertion and must match exactly.
+`rpcTransport` implements `request(method, params): Promise<unknown>` and returns the JSON-RPC
+`result`, throwing RPC errors. The SDK verifies `eth_chainId`, chooses one block number (or accepts
+an explicit `blockNumber`, including zero), and pins the operation's contract reads to that block.
+This pins the block number; it does not guarantee finality or protect against a block reorganization.
+
+Pool reads include ERC-20 `decimals()` and `balanceOf(pool.address)` calls for both tokens at that
+same block. Missing or invalid
+decimals fail the read; the SDK never assumes 18. The token addresses and raw `sqrtPriceX96`, `fees.swapFeePips`,
+`tick`, `tickSpacing`, and `liquidity` remain available.
+
+`price` contains decimal-adjusted spot prices in both directions, computed with bigint arithmetic
+and formatted with up to 36 significant digits, rounded down. Strings have no scientific notation or
+unnecessary trailing fractional zeros; each direction derives from the raw ratio independently.
+Very small nonzero prices remain nonzero. An uninitialized pool (`sqrtPriceX96 === 0n`) returns
+`price: undefined`. `fees.swapFeePercent` is an exact percentage string without a percent sign.
+
+The calculation follows [Uniswap's V3 math primer](https://blog.uniswap.org/uniswap-v3-math-primer):
+`currency0InCurrency1 = sqrtPriceX96² / 2¹⁹² × 10^(token0Decimals - token1Decimals)`.
+These are pool spot prices. Liquidity stays in its raw mathematical units; it isn't a token balance
+or TVL, and spot prices don't include a trade's fees or price impact.
+
+`balances.token0` and `balances.token1` each contain the raw bigint and an exact formatted decimal
+string, without rounding or scientific notation. These are the tokens held by the pool contract,
+including any fees or donated tokens. They don't convert `liquidity`, calculate a particular LP's
+position amounts, or assign fee ownership. Balance reads use the same pinned block as the rest of
+the snapshot. If either read fails, the SDK propagates the error instead of returning partial or
+invented zero balances. The snapshot and its nested balance objects are frozen.
+
+Family discovery matches the pool's factory address to exactly one registered deployment. The
+adapter additionally checks the factory's `getPool(token0, token1, fee)` result, rejecting an address
+that impersonates a registered pool. Unknown or ambiguous mappings fail without a default protocol.
+Reads and quotes propagate RPC/decode errors, and no method signs or submits transactions.
+
+Reusable V3 reads and QuoterV2 behavior live in `RpcUniswapV3Adapter`; `UniswapV3` supplies protocol
+identity. Other compatible protocols can subclass that implementation and register their own
+contracts and data adapter. Current family-based discovery supports only V3 address references;
+V4 discovery is not implemented. The deployment uses the addresses in the
+[official Base deployment list](https://developers.uniswap.org/docs/protocols/v3/deployments/v3-base-deployments).
+
+The Uniswap subgraph URL retains the prior SDK's subgraph ID in a gateway URL without credentials.
+Gateway queries require consumer authentication. Pool reads and quotes use RPC independently of
+indexed listing.
+
+### List indexed pools
+
+Configure The Graph once on the client, using an API key in server code:
+
+```ts
+const steer = new SteerClient({
+  indexers: { theGraph: { apiKey: theGraphApiKey } },
+});
+const amm = steer.getAmm({ chainId: ChainId.Base, protocol: AmmProtocol.Uniswap, version: UniswapVersion.V3 });
+const first = await amm.listPools({ limit: 100, token: { symbol: "USDC" } });
 
-All integer values that may exceed JavaScript's safe range are returned as decimal strings. The
-`provenance` object identifies block-pinned contract data. Last execution comes from the established
-Steer `vaultSnapshots` entity, queried below both the explicit epoch and pinned-block timestamp; its
-provenance is marked `timestamp-bounded` because the entity does not expose a block number. When no
-earlier snapshot exists, both last-execution fields are `null`; lookup or historical consistency
-failures return an unsuccessful `SteerResponse` rather than falling back to latest state.
+first.items; // Pool addresses; load one with amm.getPool(address) for verified RPC state.
 
-### Advanced Usage
+await amm.listPools({ token: { address: tokenAddress } });
+await amm.listPools({ token: { name: "USD Coin" } });
 
-#### Using Individual Functions
+if (first.nextCursor) {
+  const next = await amm.listPools({ limit: 100, cursor: first.nextCursor });
+}
 
-Each step can be used independently for testing or custom implementations:
+amm.dataAdapter; // UniswapV3DataAdapter behind the listing operation.
+amm.dataAdapter.subgraphUrl;
+```
 
-```typescript
-import {
-  calculateSwapAmount,
-  calculateLimitPrice,
-  simulateSwap,
-  estimateLpTokens,
-  AMMType,
-} from '@steerprotocol/sdk';
+For browser applications, configure a server proxy instead of putting a private API key in the client:
 
-// Step 1: Calculate swap amount
-const swapResult = await calculateSwapAmount(publicClient, {
-  depositAmount: parseEther('100'),
-  isToken0: true,
-  vault: vaultAddress,
-  pool: poolAddress,
-  ammType: AMMType.UniswapV3,
-  singleAssetDepositContract: contractAddress,
+```ts
+const steer = new SteerClient({
+  indexers: { theGraph: { proxyUrl: "/api/the-graph" } },
 });
+const amm = steer.getAmm({ chainId: ChainId.Base, protocol: AmmProtocol.Uniswap, version: UniswapVersion.V3 });
+const pools = await amm.listPools({ token: { symbol: "USDC" } });
+```
+
+Choose either `apiKey` or `proxyUrl`. A proxy receives a POST to
+`/api/the-graph?subgraphId=<id>` with the original GraphQL query and variables. Existing URL query
+parameters are preserved. Your application implements that route, validates the intended subgraph,
+and forwards the request using its server-side key. Use an absolute HTTP(S) proxy URL in Node;
+browser applications can use an absolute URL or a path starting with `/`.
 
-// Step 2: Calculate price limit for slippage protection
-const limitPrice = await calculateLimitPrice(publicClient, {
-  pool: poolAddress,
-  slippageBP: 500,
-  zeroForOne: true,
-  ammType: AMMType.UniswapV3,
+Configuration is snapshotted per client. The SDK applies the key or proxy only to recognized The
+Graph gateway subgraph URLs. Other providers and RPC operations are unaffected. `subgraphUrl` remains
+the canonical indexer URL; API keys and proxy settings never become public deployment metadata.
+
+Per-request overrides remain available:
+
+```ts
+await amm.listPools({ token: { symbol: "USDC" } }, {
+  headers: { Authorization: `Bearer ${otherApiKey}` },
+  timeoutMs: 5_000,
 });
+```
 
-// Step 3: Simulate the swap
-const simulation = await simulateSwap(
-  publicClient,
-  {
-    pool: poolAddress,
-    recipient: userAddress,
-    zeroForOne: true,
-    amountSpecified: parseEther('10'),
-    sqrtPriceLimitX96: limitPrice,
-    ammType: AMMType.UniswapV3,
-    tokenIn: '0x...', // Token being swapped from
-    tokenOut: '0x...', // Token being swapped to
-    fee: 3000, // Pool fee in basis points
-  },
-  137
-); // Chain ID (e.g., 137 for Polygon)
+An explicit authorization header overrides the client key, using case-insensitive header matching.
+Other request headers are preserved. A custom `fetch` overrides the HTTP implementation while still
+receiving the configured destination and headers, including client authentication in API-key mode.
+Proxy mode does not add an SDK API-key header. Optional `SteerClient({ http: { headers, fetch,
+timeoutMs, signal } })` defaults apply to indexed HTTP requests and are snapshotted per client.
+Per-request settings override those defaults; headers merge case-insensitively. RPC transports remain
+independent. Adapter-defined headers (such as JSON content type) override client defaults, while
+explicit per-request headers take precedence over both.
+
+HTTP requests default to a 15-second timeout. An explicit cancellation signal and the timeout both
+remain active; `timeoutMs: 0` disables the timeout. Per-request signals override a client default
+signal. HTTP failures throw the root-exported `HttpError` with a numeric `status`; failed response bodies
+are cancelled without replacing that error if cleanup fails. Network, timeout, and cancellation
+errors propagate.
+Client construction never makes requests.
+
+The internal native-fetch transport handles HTTP settings, request sending, deadlines, cancellation,
+and HTTP status failures, returning the response without parsing it. The indexer layer selects the
+destination and provider authentication. Data adapters serialize GraphQL queries, parse response
+bodies and GraphQL errors, and own filtering and pagination. No additional HTTP dependency is used.
+
+A token filter matches either token in the pool. Addresses match exactly (ignoring address case);
+symbols and names use case-insensitive substring matching. Multiple supplied fields must match the
+same token. Blank filters and empty search text are rejected. Symbols and names are indexed metadata,
+so they can match multiple unrelated token contracts; use an address to select a particular token.
+
+Listing returns up to 1000 addresses per page (100 by default), ordered by address. The opaque cursor
+retains the endpoint, factory, token filter, subgraph deployment, and indexed block number from the first page.
+Later pages use `id_gt` at that block, without offset pagination. Token filters are restored from the
+cursor when omitted; supplying different filters with an existing cursor is rejected. Treat cursors as opaque and restart
+listing if the subgraph deployment changes. A full final page can produce a cursor whose next page
+is empty. Indexed blocks remain subject to chain reorganizations and indexer availability.
+
+The adapter checks the indexed factory and rejects indexing errors, partial GraphQL errors, HTTP
+failures, malformed data, and repeated or unsorted addresses. Indexed results remain discovery data;
+`getPool` performs the independent RPC ownership checks. Lending and Steer listing implementations
+remain outside this change.
+
+The query follows the [Uniswap V3 schema](https://github.com/Uniswap/v3-subgraph/blob/main/src/v3/schema.graphql)
+and [The Graph pagination and historical-query API](https://thegraph.com/docs/en/subgraphs/querying/graphql-api/).
+Bearer authentication follows [The Graph API-key documentation](https://thegraph.com/docs/en/subgraphs/providers/subgraph-studio/managing-api-keys/).
+
+### RPC request counts
+
+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 |
+
+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
+through their own read path. The standard adapter then loads and verifies its snapshot. This costs
+one more RPC request than a direct adapter read. Chain, block, and discovered factory context are
+shared internally; no snapshot is preloaded or passed through discovery. Each operation validates
+the RPC chain, with no cross-operation identity cache or additional consumer options.
+
+Quotes read pool identity, the token pair and fee, verify factory registration, and call QuoterV2.
+V3 and Aerodrome Slipstream quotes reject results at either default price boundary because
+QuoterV2 does not establish the consumed input there. Requests that cannot establish full input
+consumption fail explicitly.
+They don't load token decimals, balances, ticks, or liquidity. Discovering a pool and then quoting
+at its block uses 9 RPC calls in total. Counts exclude retries and provider-specific transport
+behavior.
+
+Pool snapshots use a small internal Solidity reader to follow all dependencies within one
+`eth_call`. The reader checks the pool's factory against the configured allowlist and verifies
+factory registration before reading token metadata or balances. JavaScript keeps decimal formatting
+and returns the same public snapshot shape. No contract is deployed, no transaction is submitted,
+and no consumer configuration changes are needed.
+
+The SDK prefers viem's deployless bytecode execution. If the provider explicitly rejects that
+feature, it tries a temporary code override at an internal helper address. The override supplies
+helper code only; pool and token code, storage, and balances remain untouched. Both mechanisms have
+been verified against the configured Base RPC and produce identical same-block snapshots.
+
+If both execution features are explicitly rejected, pool reads retain viem's native Multicall3
+path: one aggregate for pool state and another for metadata/balances, after direct factory checks.
+The two rejected feature attempts add two requests to this compatibility path: 8 total for latest,
+or 7 for an explicit Base block with Multicall3. A provider supporting only overrides uses 4 or 3
+for direct pool reads, and 5 or 4 for discovery.
+There is no global provider capability or identity cache. Reverts, identity failures, malformed
+responses, rate limits, and network errors fail without silently choosing another execution path.
+Structured revert evidence anywhere in the error chain takes precedence over feature-like wording;
+explicit unsupported-feature messages can put the feature name before or after the rejection.
+
+Quotes continue using Multicall3 for the token pair and fee, with factory checks and QuoterV2 calls
+kept direct. Every reader, aggregate, and direct call uses the operation's explicit block and the
+same injected `RpcTransport`. Required member failures reject the operation without partial values.
+
+Base Multicall3 metadata matches viem's deployment at block 5022. Where Multicall3 is unavailable,
+the compatibility path uses direct reads instead: pool reads/discovery use 14 calls for latest or
+13 for an explicit block, plus the two rejected reader attempts; quotes use 8 or 7. HTTP JSON-RPC
+batching remains a separate transport concern.
+
+### Solidity reader development
+
+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
+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.
+
+Offline tests execute the real reader bytecode in a development-only EVM with mock pools,
+factories, and tokens. Live tests exercise deployless execution, code overrides, and the Multicall
+compatibility path against the configured RPC and compare with independent same-block reads.
+
+## Register integrations
+
+Implement a family adapter and its data adapter, then define an internal `Deployment` object whose factory
+constructs that adapter. The factory receives the chain context and deployment metadata.
+SDK catalog entries bind a network's own Steer deployment to its AMM and lending integrations.
+SDK integration code and tests can supply `new SteerClient({ catalog, transports })` to override the
+catalog. `ChainDefinition` contains network identity and transaction/wrapped-token metadata. `SteerNetwork` is a
+connected Steer deployment with one resolver-backed loading path. Steer deployment factories create
+data adapters, so they don't need to implement unused vault loaders. Constructing a client must not
+perform network calls.
+
+`tests/fixtures/composition.ts` contains local fakes that exercise the extension contracts; don't
+use their addresses or responses in an app.
+
+AMM consumers select the protocol brand and its version with enums. Versions use public product
+names: QuickSwap V3 selects Algebra Legacy, while QuickSwap V4 selects Algebra Integral. Family
+selection comes from explicit adapter/deployment configuration, never a name substring or ABI probe.
 
-// Step 4: Estimate LP tokens
-const estimation = await estimateLpTokens(publicClient, {
-  vault: vaultAddress,
-  originalAssets: parseEther('100'),
-  swapAmount: swapResult.data.swapAmount,
-  swapResult: simulation.data,
-  isToken0: true,
+```ts
+const polygon = steer.getAmm({
+  chainId: ChainId.Polygon,
+  protocol: AmmProtocol.QuickSwap,
+  version: QuickSwapVersion.V3,
+});
+const base = steer.getAmm({
+  chainId: ChainId.Base,
+  protocol: AmmProtocol.QuickSwap,
+  version: QuickSwapVersion.V4,
 });
 ```
 
-#### Using the SingleAssetDepositClient Directly
+`UniswapVersion` offers V3/V4, `QuickSwapVersion` offers V3/V4, `CamelotVersion` offers V3, and
+`PancakeSwapVersion` offers V3/InfinityCL. These enumerate implemented adapters, not every product
+published by each brand. Only qualified chain deployments are registered.
 
-```typescript
-import { SingleAssetDepositClient } from '@steerprotocol/sdk';
+Lookup infers the concrete adapter type from protocol and version, including its direct methods
+and `contracts` accessor. Omitting version is allowed only when the remaining selectors identify
+one deployment; its static return type includes the protocol's supported versions. Base Uniswap
+and BNB PancakeSwap require a version because each has two registered versions. Ambiguity errors
+list the available versions and deployment IDs. There is no implicit latest version.
 
-const client = new SingleAssetDepositClient(publicClient, walletClient);
+When multiple deployments of the same version exist, use the optional named selector:
 
-// Preview deposit
-const preview = await client.previewDeposit(params, poolAddress);
+```ts
+const amm = steer.getAmm({
+  chainId: ChainId.Base,
+  protocol: AmmProtocol.Uniswap,
+  version: UniswapVersion.V3,
+  deployment: AmmDeployment.UniswapV3Base,
+});
+```
 
-// Prepare transaction (without executing)
-const preparedTx = await client.prepareDepositTx(params);
+Named selectors do not bypass chain, protocol, version or family validation. Each adapter exposes
+`amm.protocol`, `amm.version`, and `amm.family` separately. Pool discovery and vault resolution
+continue to select adapters by exact factory/manager or beacon/implementation mappings; consumers
+need not supply a version to those resolution flows. AMM deployment objects stay internal and are not root exports. Registries reject
+cross-chain deployments, duplicate IDs, and unregistered objects. Each lookup constructs a fresh
+adapter; there is no global registry or shared client cache. Use `amm.contracts.factory.address` and `amm.subgraphUrl` for direct metadata access.
+
+Vault implementation files live under `src/vault/adapters/uniswap-v3/`: `vault.ts` owns vault
+operations; `deployment.ts` owns exact Base resolver/underlying mappings; `identity.ts` holds pinned
+code identities; `rpc.ts` and `reader/` hold internal reads. Shared models and enums live in
+`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.
+
+## Automatic vault resolution
+
+`getVault(chainId, address, { blockNumber })` uses the network's SDK-owned `vaultResolver` configuration. Consumers
+don't select a vault family or pass an AMM adapter. Resolution selects a block, reads the registered
+vault identity, and matches an exact beacon-address and implementation-address pair. The resolver
+checks the requested chain, vault and registry addresses, and agreement between the registry's
+beacon and the proxy's actual beacon.
+
+Each implementation binding supplies an ABI-specific `readUnderlying` function and vault
+constructor. The reader reports configured pool or market references and their factory, PoolManager,
+or lending contract addresses. It doesn't require active positions, balances, or an existing deposit.
+Exact address and contract-role bindings select registered adapters. The constructor must retain the
+resolved references in `vault.underlying`, including every integration used by a composite vault.
+A liquidity or lending vault also retains its corresponding adapter as `amm` or `lending`.
+
+The specialized getters call this same resolver and reject a result of the wrong kind. Unknown
+implementations, unknown underlying contracts, duplicate mappings, and mismatched identities produce
+`VaultResolutionError` with an enum-backed code. RPC errors propagate. No loader uses substring
+matching or guesses a default family. A network without resolver configuration reports
+`NotConfigured` rather than falling back to another loader.
+
+Identity and configured-reference reads receive the same block number. Every load reads identity again, so an
+upgrade must match a supported implementation binding before the SDK constructs a new vault.
+Adapters are reused within a single resolution, without retaining an identity cache across loads.
+
+Base includes an onchain reader and an exact mapping for the `MultiPositionUniswapV3` beacon
+`0xDf0b9Ef4d7C4E294A74efB4407129bd66e4f82f0` and implementation
+`0xBDDe75BBf4a580c5E564B5f9aC7B12007dD307C6`. It verifies registry membership, the actual
+proxy beacon slot, proxy/implementation runtime hashes, and the vault's stored registry. It also
+verifies the underlying factory, factory registration, and token ordering. Indexed metadata alone
+isn't enough. Unsupported upgrades fail explicitly. Other vault implementations remain unmapped.
+
+### Polygon liquidity vaults
+
+Use the same automatic resolver and snapshot API. Consumers do not select a vault family:
 
-// Validate parameters
-client.validateDepositParams(params);
+```ts
+const vault = await steer.getLiquidityVault(ChainId.Polygon, vaultAddress);
+const snapshot = await vault.getSnapshot();
+const snapshots = await steer.getVaultSnapshots(ChainId.Polygon, vaultAddresses);
+
+const page = await steer.listVaults({
+  chainId: ChainId.Polygon,
+  amm: { protocol: AmmProtocol.QuickSwap, version: QuickSwapVersion.V3 },
+  token: { symbol: "USDC" },
+});
 ```
 
-### SingleAssetDepositClient Supported AMM Types
+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 |
+
+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
+discovery. V3 readers reuse the existing pool/position math with a fixed-fee policy subclass; Integral
+reuses its existing reader. Legacy keeps its pool ABI, reader and compatibility path in its adapter folder.
+SushiSwap and Retro retain their own typed protocol identities while sharing the V3 family. Their
+optional AMM listing endpoints retain prior SDK metadata and have not been qualified by the vault benchmark;
+no quoter is configured for those deployments.
+
+Polygon also qualifies the newer Solidity 0.8.26 proxy by its exact runtime hash and supports the
+historical QuickSwap beacon `0x50cb5e8ae49a7457e2a15acb429b86c86f2f8fc2`. Historical resolution
+checks the actual stored beacon, exact implementation/hash, registry membership, current name mapping
+and the registry's reverse name for the old beacon. Unknown histories still fail. See the
+[identity qualification](benchmarks/polygon-vault-identity-qualification-2026-10-19.json).
+
+The historical implementation deducts fees after aggregating positions. Its position net fees allocate
+rounding carry cumulatively so their sum matches the snapshot and original vault accounting. These
+allocations describe snapshot accounting, not independent position withdrawal entitlements. Current
+implementations retain their existing per-position rounding.
+
+Both QuickSwap versions are now registered on Polygon, so `getAmm` and AMM-filtered `listVaults`
+require a version (or an exact deployment selector). Neither chooses an implicit latest version.
+Unfiltered vault listing remains available without RPC configuration.
+
+Bulk snapshots retain the 16-vault / 128-position budgets, same-block accounting, registered adapter
+and vault overrides, and strict compatibility fallback. Scheduled/dynamic jobs, single-position vaults,
+test implementations, unknown proxy runtimes and conflicting registry/proxy identities remain explicit
+failures. A bulk call is atomic; it does not silently omit rejected addresses. See the
+[deployment qualification](benchmarks/polygon-vault-deployments-2026-10-19.json) and
+[full-list benchmark](benchmarks/polygon-vault-snapshots.md) for measured coverage and timing.
+
+### Read a Base V3 vault
+
+```ts
+import { ChainId, SteerClient } from "@steerprotocol/sdk";
 
-```typescript
-enum AMMType {
-  UniswapV3 = 0, // ✅ Fully implemented
-  Algebra = 1, // 🚧 Planned
-  AlgebraDirectional = 2, // 🚧 Planned
-  AlgebraVE33 = 3, // 🚧 Planned
-  AlgebraIntegral = 4, // 🚧 Planned
+const steer = new SteerClient({ transports: { [ChainId.Base]: rpcTransport } });
+// Same automatic resolution as getVault(), with a liquidity-kind assertion.
+const vault = await steer.getLiquidityVault(
+  ChainId.Base,
+  "0x022480ee800f4aad2d12099d5a87e4d1c16a975f",
+);
+const snapshot = await vault.getSnapshot();
+
+vault.amm.protocol;
+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.feeRateBps;
+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.lowerTick;
+  position.upperTick;
+  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.net.token0.formatted;
+  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 });
 ```
 
-Within `SingleAssetDepositClient`, only **UniswapV3** is fully implemented. This does not limit the separate pool-lifecycle APIs described above. Other single-asset-deposit AMM types will be added in future releases.
+Omit `blockNumber` to choose the current RPC block, or pin it on resolution and each read. Each
+snapshot pins identity, ranges, fee configuration, token metadata, balances and pool state to one
+block number. Each read revalidates identity; an existing object cannot silently use an upgraded
+implementation or a changed pool. Pool state goes through the registered adapter's `getPool()`
+method, including overrides. Vault reads need RPC only, without a Graph API key.
+
+Snapshot reads prefer the internal `V3VaultAddressReader` through a code-only override at the
+vault address. First, `eth_getCode` verifies the original proxy runtime at the selected block.
+The overridden reader checks `block.chainid`, reads the actual beacon/registry/fee-manager/helper
+slots with SLOAD, and verifies registry membership, exact beacon/implementation mappings and
+unchanged implementation/helper runtime hashes. Original vault view selectors are forwarded to the
+verified implementation through delegatecall, retaining the vault's address and storage context.
+Pool registration, token ordering, balances, ranges and fee-growth reads remain independent of
+adapter overrides. No storage, balances, pool/token code or implementation code is overridden.
+Everything runs in eth_call; deployed code and state are unchanged.
+
+A pinned snapshot uses **2 RPC requests**: original proxy code plus one overridden snapshot.
+Latest adds one block-number request. These counts exclude resolution, which now uses **2**
+pinned requests; a cold pinned resolve plus snapshot therefore uses **4** requests. Both the
+V3 address reader and the existing helper reader feed the same TypeScript accounting code.
+
+Only explicit unsupported-override responses activate the existing helper reader. That fallback
+uses four same-block storage reads, then deployless execution, then helper-address code override,
+and finally Multicall compatibility after explicit feature rejections. Including the new proxy
+preflight and rejected address-override probe, those pinned snapshot paths use **8**, **9**, and
+**27** requests respectively for one or two ranges; ten ranges add one compatibility batch.
+Reverts, malformed results, identity/accounting failures, network errors and rate limits propagate.
+There is no cross-call provider capability cache and no fallback after an actual reader failure.
+
+Every path dispatches the registered adapter's `getPool()` override. The default adapter reuses
+an immutable copy of verified raw pool data only within that invocation, bound to chain, transport,
+pool and block. The returned adapter identity is checked against the independently verified reader
+result. Retained options expire on success and failure; concurrent invocations remain isolated.
+Internal raw data and execution modes are absent from public options and declarations.
+
+`getPositions()` returns configured LP ranges, including zero-liquidity ranges; idle tokens live in
+`getSnapshot().idle`. Weights come directly from the vault and describe its configured distribution,
+not current dollar-value allocations. Percentages round down to 18 decimal places and are undefined
+when all weights are zero. Duplicate ranges fail explicitly to prevent counting one pool position
+twice. An empty position array still retains `vault.underlying` and `vault.amm`.
+
+V3 principal and fee-growth calculations use bigint math, exact tick ratios and contract rounding.
+Position and snapshot `fees` both use `{ gross, net, recorded }`; snapshot values sum the
+corresponding position amounts. `feeRateBps` is a vault-level field on the snapshot. Recorded fees
+are already included in gross, so they must not be added again. Gross fees include both recorded
+`tokensOwed` and fees accrued since the last pool checkpoint,
+including uint256 fee-growth wraparound. Net fees apply the vault's fee-manager rate per position,
+rounded down, matching its verified helper. The reader uses the vault's stored fee manager and
+helper for this exact implementation, verifies helper code, and rejects invalid rates or reserves
+that exceed token holdings. It never substitutes the registry's current fee manager for the vault's.
+`total` is an accounting snapshot, not a withdrawal quote. Use `previewWithdraw()` for the
+contract-calculated exit amounts. Deposit quotes use original post-poke totals and the qualified share formula.
+
+The storage layout and accounting are verified against exact-match Sourcify sources for the
+[Base vault implementation](https://sourcify.dev/server/v2/contract/8453/0xBDDe75BBf4a580c5E564B5f9aC7B12007dD307C6?fields=all)
+and its [helper](https://sourcify.dev/server/v2/contract/8453/0xa98376572375692455172f6750c67339667974fe?fields=all).
+Offline tests retain public runtime bytecode in `tests/fixtures/v3-vault-code.json` to check these
+hashes. Live tests independently read the contracts with viem and reconcile totals with the vault's
+own `getTotalAmounts()` after a sequential `poke()` simulation in `eth_call`. No transaction is sent.
+
+### Read a user's proportional vault position
 
-### Error Handling
+```ts
+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.ownershipPercent; // Decimal string, e.g. "12.5"
+position.amounts.token0;   // { raw: bigint, formatted: string }
+position.amounts.token1;
+position.blockNumber;
+```
 
-All functions return a consistent `SteerResponse<T>` format:
+Pass `{ blockNumber }` to read a specific block; otherwise the operation pins one latest block.
+The verified family snapshot, share balance, total supply and token decimals all use that block.
+Each call performs native family verification before dispatching the resolved vault's snapshot override.
+Overrides with or without `super` must retain the verified block, pool, token ordering, decimals and
+position count; invalid results fail before share reads. `super` reuses the verified snapshot without
+additional RPCs. The original binding and connected AMM adapter instances are retained.
+The validation boundary copies and freezes snapshot values, including nested amounts and positions,
+so later changes to an override's cached objects cannot change a pending user-position calculation.
+Connected AMM adapters retain their original references and the override's objects remain untouched.
+Amounts are each LP total multiplied by shares / total supply, rounded down in raw token units.
+They include available idle, position principal and net uncollected fees, and exclude protocol and
+strategist reserves. They are proportional accounting amounts, not executable withdrawal quotes.
+Ownership percentages round down to 18 decimal places. A zero share balance returns zero amounts;
+zero supply returns zero ownership and amounts. A share balance exceeding supply fails explicitly.
+
+The normal address-reader path takes three pinned RPCs: proxy code verification, the existing family
+snapshot reader, and one required Multicall for share balance and supply. Latest adds one head lookup;
+compatibility snapshot paths retain their existing costs. Before Multicall deployment, or on an
+unconfigured chain, the two share reads execute directly at the same block. Required failures propagate.
+
+### Read user positions for multiple vaults
 
-```typescript
-interface SteerResponse<T> {
-  data: T | null;
-  status: number;
-  success: boolean;
-  error?: string;
-}
+```ts
+const positions = await steer.getVaultUserPositions(
+  ChainId.Polygon,
+  vaultAddresses,
+  accountAddress,
+  { blockNumber }, // Optional; otherwise pin one latest block for the entire request.
+);
 
-// Example error handling
-const result = await vaultClient.previewSingleAssetDeposit(params, poolAddress);
-if (!result.success) {
-  console.error('Preview failed:', result.error);
-  return;
+for (const { vault, position } of positions) {
+  console.log(vault, position.shares, position.ownershipPercent, position.amounts);
 }
+```
+
+Results preserve input order and duplicates, including zero-balance positions. The bulk path uses
+the same verified snapshots, registered vault/AMM overrides and proportional accounting as
+`vault.getUserPosition()`. Unsupported implementations, identity mismatches and required RPC
+failures reject the whole request. No partial portfolio is silently returned.
+
+On providers supporting vault-address overrides, ordinary small snapshots use two RPCs per
+snapshot batch (up to 16 vaults and 128 positions), plus one required share/supply Multicall per
+64 requested vaults. Latest adds one head lookup for the whole request. Larger position sets and
+compatibility paths retain their existing snapshot costs. Before Multicall deployment, or without
+configured Multicall metadata, share reads use bounded direct calls. These limits bound requests;
+they are not onchain vault limits. No cross-request identity or balance cache is introduced.
+
+### Discover wallet-held vaults
+
+```ts
+const page = await steer.listUserVaults({
+  chainId: ChainId.Polygon,
+  account,
+  limit: 1000, // Maximum candidates scanned per page; default 1,000.
+  // Optional: amm, token, cursor
+});
+const positions = await steer.getVaultUserPositions(
+  ChainId.Polygon,
+  page.items,
+  account,
+  { blockNumber: page.indexedBlock },
+);
+```
+
+Discovery scans real `balanceOf(account)` values for the indexed vault inventory, including shares
+received by transfer. It does not trust `Depositor.shares`. All candidate pages and their balance
+reads use one indexed block, returned as `indexedBlock`. Cursors bind the account, chain, endpoint,
+registry, AMM/version and token filters to that snapshot. HTTP/indexer configuration and request
+options work as for `listVaults()`. An RPC transport is required.
+
+Each page scans at most `limit` candidates and returns only positive balances. **A page can be empty
+and still have `nextCursor`; continue until the cursor is absent.** This bounds work even when most
+vaults have zero shares. Smaller limits reduce provider payload/gas requirements. Recognized
+`ScheduledJobs` and `DynamicJobs` records are excluded by exact name because they are not share
+vaults. Unknown deployments stay candidates; failed/malformed balances reject the entire page,
+without silently dropping addresses or inventing zeros.
+
+A nonempty page normally costs one deployless Solidity `eth_call`; explicit unsupported execution
+selects helper code overrides (two requests including the rejected probe), then Multicall (four
+requests including both probes and chain validation). Without deployed Multicall metadata, fallback
+uses bounded direct calls. Empty pages need no RPC. The first indexer page normally needs two HTTP
+requests (metadata and candidates); continuations need one. No snapshots are loaded during discovery.
+
+Results are ownership candidates, not verified implementation identities. Load details through
+`getVault()` or `getVaultUserPositions()`, which retain identity checks and adapter overrides and
+reject unsupported holdings explicitly. Inventory completeness depends on the indexer including all
+relevant vaults. Holdings created or transferred after the indexed block are outside that snapshot;
+staked and custodial shares are separate. No provider capability or balance cache is retained.
+
+### Preview and prepare a liquidity vault deposit
+
+```ts
+const vault = await steer.getLiquidityVault(chainId, vaultAddress);
+const request = {
+  account,
+  receiver: account, // Receives the shares; account supplies the tokens
+  assets: [
+    { asset: usdcAddress, amount: 100_000000n },
+    { asset: wethAddress, amount: 50_000000000000000n },
+  ],
+};
+const preview = await vault.previewDeposit(request, { blockNumber });
+preview.blockNumber;
+preview.shares;          // Expected raw share units
+preview.token0;
+preview.token1;
+preview.amounts.token0;  // Accepted input: { raw: bigint, formatted: string }
+preview.amounts.token1;
+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
+```
+
+Both methods accept `{ blockNumber }` as the second argument. Omitting it pins one latest block.
+Inputs are raw uint256 token units and represent maxima. Address order is arbitrary; the SDK maps
+assets to the verified vault tokens. One omitted token has a zero maximum. Unknown/duplicate tokens,
+negative amounts and all-zero inputs fail. These direct deposits do not swap tokens or wrap native
+currency. A two-sided vault usually requires both inputs in its current holdings ratio.
+
+For a UI where the user enters one amount, ask the vault to infer the other token maximum:
+
+```ts
+const quote = await vault.quoteDeposit({
+  asset: usdcAddress,
+  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.unusedAmounts; // Any unused input caused by contract rounding
+quote.blockNumber;
+
+const plan = await vault.prepareDeposit({
+  account,
+  receiver: account,
+  assets: quote.assets,
+  slippageBps: 50,
+});
+```
 
-// Use result.data safely
-console.log('LP tokens:', result.data.lpEstimation.lpTokens);
+`quoteDeposit` needs no account or approvals. Pass `{ blockNumber }` as its optional second argument,
+or omit it to pin one latest block. The selected input is a positive raw uint256 token maximum.
+The other maximum is rounded up from the original vault's LP-owned holdings ratio, using bigint
+arithmetic. This is not the pool's spot-price ratio and performs no swap. The quote uses the same
+identity checks, registered snapshot/AMM overrides, original post-poke accounting and contract share
+calculation as `previewDeposit`; it also takes three pinned/four latest RPCs. Unknown tokens, dust,
+invalid backing and non-executable arithmetic reject explicitly.
+
+An empty vault (zero share supply) has no established ratio, even if someone donated tokens. Its
+one-token quote rejects with guidance to choose explicit maxima through `previewDeposit`, preserving
+the implementation's first-mint rules. A funded one-sided vault quotes zero for the absent token
+when the selected token is the accepted side; selecting the absent side rejects. The contract can
+leave a small unused amount after rounding a one-sided deposit's share mint. Quote assets and all
+returned amounts are immutable. Preparation re-reads state, so refresh quotes when conditions change
+or explicitly pin both operations to the same block when comparing them.
+
+Previews work without balances or approvals. Native family identity checks and validated snapshot/AMM
+overrides run first. The SDK then calls the original vault's `poke()` and `getTotalAmounts()` sequentially
+in one Multicall `eth_call`, with supply, pause and registry-state reads pinned to that block. The fee
+checkpoint is discarded after the call. Share pricing uses these original contract totals, never
+custom snapshot totals. Token decimals come from the detached, identity-validated snapshot.
+
+The shared bigint formula follows the exact deployed `getShares`/`_calcSharesAndAmounts` code,
+including token rounding up, share rounding down, checked cross-product/FullMath bounds and first
+share minting. Qualified older Polygon Uniswap/Sushi/Retro V3 implementations permit any positive
+first share mint; Base V3, Integral and Legacy require 1,000,000 raw initial shares. The exact
+implementation addresses and runtime hashes remain in the family identity files. Sources were
+verified using Sourcify for all eight mapped implementations, including the
+[Base V3 implementation](https://sourcify.dev/server/v2/contract/8453/0xBDDe75BBf4a580c5E564B5f9aC7B12007dD307C6?fields=all),
+[older Polygon V3 implementation](https://sourcify.dev/server/v2/contract/137/0x434bf4902C0dcd515BC76A302f20C9c45b844b1b?fields=all),
+and [historical QuickSwap implementation](https://sourcify.dev/server/v2/contract/137/0x4603E812Ef2454E72E57661f0aA39D7d20e9A968?fields=all).
+
+Paused vaults and registry states other than PendingThreshold/Active reject deposits. Bootstrap
+minimums, zero-share quotes, invalid backing and arithmetic overflow fail explicitly. A preview is
+a contract-compatible quote, not confirmation of wallet funding or token transfer readiness.
+
+Preparation obtains its own quote and reads both allowances in the same aggregate. It reuses
+sufficient approvals; otherwise it encodes approvals capped at the requested maxima, resetting a
+nonzero insufficient allowance first. Submit transactions in order from `plan.account` on
+`plan.chainId`, confirming approvals before submitting the deposit. The SDK signs and submits nothing.
+The application supplies gas, fee and nonce settings through its wallet.
+
+`slippageBps` is required, from 0 through 10,000. Each minimum is the accepted raw amount discounted
+by that tolerance and rounded down. The ABI protects minimum accepted token amounts, not minimum
+shares; these are not equivalent protections. At 10,000 both minima are zero. Values describe the
+quoted block; execution can fail after state or wallet balances change.
+
+Both methods use **3 pinned RPCs**, or **4** for latest, on the normal reader path. Allowances are
+included only for preparation, without adding a round trip. Snapshot compatibility paths keep their
+existing costs plus one original-accounting Multicall. That aggregate must be deployed at the selected
+block; required failures propagate without retries or invented accounting. Results, captured inputs
+and unsigned requests are immutable. Live tests verify unfunded quotes and execute original approvals
+and deposits with real funded accounts through rolled-back `eth_call` simulations only.
+
+### Preview and prepare a liquidity vault withdrawal
+
+```ts
+const vault = await steer.getLiquidityVault(chainId, vaultAddress);
+const request = { account, shares: 1000n, receiver: account };
+const preview = await vault.previewWithdraw(request, { blockNumber });
+
+preview.blockNumber;
+preview.shares;
+preview.token0;
+preview.token1;
+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.chainId;
+plan.preview;
+plan.minimumAmounts; // Raw and formatted minimum outputs for both tokens
+plan.transactions;   // Unsigned { to, data, value } requests
 ```
 
-### Common Error Cases
+Both methods accept `{ blockNumber }` as their optional second argument; omitting it pins one
+latest block. Shares are positive raw uint256 units. `account` and `receiver` must be nonzero
+addresses. The vault burns the sender's shares, so a different account cannot submit this payload
+on the holder's behalf. `slippageBps` is required for preparation and must be an integer from 0
+through 10,000; minimum token amounts round down in raw units. At 10,000 both minima are zero.
+Small amounts can also round to zero. The application chooses its tolerance and submission time;
+a preview describes its block, and later execution can revert if conditions change.
+
+V3, Legacy Algebra (including the qualified historical QuickSwap beacon) and Integral vaults use
+their original deployed `withdraw()` through `eth_call`, with the real account and receiver. This
+simulates burns, collection, fees and token transfers, rather than estimating a proportion of the
+accounting snapshot. Insufficient shares, transfer failures and contract reverts propagate. No wallet,
+approval, balance override, signature or transaction submission is needed for simulation.
+
+Each method independently verifies native vault identity and dispatches registered snapshot/AMM
+overrides at the same block. Overridden snapshots retain the existing identity validation and detached
+metadata capture. Preparation obtains its own native simulation and does not reuse an earlier preview
+or call a public `previewWithdraw` override. Results and unsigned requests are immutable.
+
+The normal path uses **3 pinned RPC requests**, or **4** for latest: proxy code verification, the
+existing verified snapshot reader and one original withdrawal simulation. Resolution is separate.
+Snapshot compatibility fallbacks remain available with one additional withdrawal call; simulation
+errors never trigger fallback or an alternative accounting estimate. Live tests simulate both the
+preview and prepared calldata without broadcasting, and verify the holder's shares stay unchanged.
 
-- **Invalid AMM Type**: `SingleAssetDepositClient` currently supports only UniswapV3
-- **Insufficient Liquidity**: Pool doesn't have enough liquidity for the swap
-- **Slippage Too High**: Price moved beyond acceptable limits
-- **Invalid Addresses**: Zero addresses or invalid contract addresses
-- **Amount Too Small**: Deposit amount too small to process
+### QuickSwap Integral liquidity vaults on Base
 
-### Testing
+The same consumer getters automatically resolve the mapped Integral vault and connect its AMM:
 
-Each function is designed to be independently testable:
+```ts
+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.subgraphUrl;
+snapshot.positions;
+snapshot.idle;
+snapshot.principal;
+snapshot.fees;      // gross, net, recorded, each with token0/token1 raw and formatted amounts.
+snapshot.feeRateBps;
+snapshot.total;
+```
 
-```typescript
-import { calculateSwapAmount, AMMType } from '@steerprotocol/sdk';
+This qualifies Base beacon `0x532654AbC884b4FA00Ffd5c29bbd40eC4669473B` and implementation
+`0x391cf3047db983caB8dD95B16c4e6C3918d72d23`. Registry membership, actual proxy beacon,
+proxy/implementation runtime hashes, stored registry, factory/pool-deployer registration and
+vault/pool token ordering are checked at the selected block. Snapshots independently verify
+pool identity even when an AMM adapter overrides `getPool()`. Each invocation reads fresh state.
+
+Integral uses packed owner/lower/upper position keys, rather than V3 hashes. Historical ranges do
+not need to align to the pool's current mint spacing. Position liquidity is checked against the
+uint128 accounting bound, despite the Integral position ABI exposing uint256. Global fee growth
+is read once and shared tick boundaries are deduplicated. Required failures propagate.
+
+The verified implementation stores its registry at slot 251 and fee manager at slot 257; it does
+not use V3's accounting helper. Fee cuts round down per position, and recorded fees are already
+included in gross. The shared snapshot accounting returns idle + principal + net fees as `total`.
+Live tests reconcile these totals against the funded three-position vault
+`0x2cf9fb4eeb424e4a0160fc44857cfcf5cd09a93b` using `poke()` followed by `getTotalAmounts()`
+in a single ephemeral `eth_call`. No transaction is submitted.
+
+Vault snapshots prefer `IntegralVaultAddressReader`: original proxy code verification followed by
+one code-only override at the vault address. Chain/registry/beacon/implementation, exact layout,
+factory/pool-deployer registration, tokens, accounting and lock checks happen inside the reader.
+Original getters delegate to the verified implementation; storage and implementation code stay
+unchanged. The default AMM adapter consumes invocation-bound verified pool data; registered
+getPool overrides always run and their returned identity is checked independently.
+
+A pinned snapshot uses **2 RPC requests**, or **3** for latest. Separate pinned resolution uses
+**2**, making a cold pinned resolve plus snapshot **4**. If address overrides are explicitly
+unsupported, bounded Multicall and the existing AMM reader remain available. Including the proxy
+preflight and rejected override probe, fallback snapshots use **20** requests with a deployless pool
+reader, **21** with a helper override, or **25** through full compatibility. Large fallback
+configurations add bounded position/tick batches. Empty ranges skip position/tick/growth reads.
+Deposit and withdrawal previews and unsigned preparation use the same API as V3 and Legacy above.
+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 |
+
+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
+`{ account, assets: [{ asset, amount }], receiver }`; liquidity previews also return block, token and amount details. Withdrawals use shares,
+account, and receiver. Concrete implementations enforce accepted assets and map these requests to
+actual contracts. For example, an ERC-4626 implementation maps a share-denominated exit to redeem,
+not to the ABI's asset-denominated withdraw amount. Supported liquidity vaults implement withdrawal
+encoding; lending and composite transaction operations remain scaffolds.
+
+A vault's `underlying` field contains the configured protocol references from loading time, while
+`getPositions()` queries actual positions. Empty vaults can still have configured underlyings. Mixed
+positions use `PositionKind` to distinguish liquidity, lending, and idle assets. A composite vault
+has no single `amm` property. There are no capability objects or capability checks.
+
+## Validation
+
+Prerelease branch, version calculation and npm authorization setup are documented in
+[RELEASING.md](RELEASING.md). Local version previews do not publish or verify publishing credentials.
+
+Tests follow the SDK areas, with separate directories for offline and live suites:
+
+```text
+tests/
+  unit/           # amm, catalog, core, data, http, observability, vault, and runner config
+  integration/
+    amm/uniswap-v3.base.test.ts
+  fixtures/       # shared offline deployment/adapter/vault fixtures
+  support/        # runner configuration helpers
+  consumer/       # isolated packed-package Node, TypeScript, and Next.js fixture
+```
 
-describe('Single-Asset Deposit', () => {
-  it('should calculate correct swap amount', async () => {
-    const result = await calculateSwapAmount(publicClient, {
-      depositAmount: parseEther('100'),
-      isToken0: true,
-      vault: vaultAddress,
-      pool: poolAddress,
-      ammType: AMMType.UniswapV3,
-      singleAssetDepositContract: contractAddress,
-    });
+Both suites use `.test.ts`. `vitest.config.ts` selects only `tests/unit/`, while
+`vitest.integration.config.ts` selects only `tests/integration/`. New tests go beside tests for the
+same SDK area; shared fixtures and runner helpers stay outside the discovery paths.
+
+Run `npm run check` and `npm run format:check` from this directory. The default tests run offline
+with fake RPC/HTTP responses; live tests don't run during `test`, `test:watch`, `test:coverage`,
+`check`, or packaging.
+
+After `npm run check` builds the package, run `npm run check:consumer` to verify the npm tarball
+from a temporary consumer project. It checks ESM imports, CJS requires, strict TypeScript NodeNext
+resolution for both declaration formats, and a Next.js production build with server and client
+components. It also checks the rendered SDK chain metadata. The fixture has its own pinned
+dependencies and lockfile; it does not use the legacy SDK or repository module resolution.
+This command requires npm registry access to install consumer dependencies, but no RPC or indexer
+credentials. The dedicated Next SDK CI workflow runs both commands on Node 22.23.4, 24.22.2 and 26.13.0.
+
+Use `nvm install` and `nvm use` from the repository root to select the default Node 24.22.2 runtime.
+Both consumer and tooling requirements accept Node ^22.23.4, ^24.22.1 or ^26.12.1; older patches
+and unsupported major lines fall outside the declared runtime support. These minimums follow the
+[October 21, 2026 Node security release](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases),
+which includes CA-certificate and TLS fixes. Keep the actual deployed application runtime patched;
+package metadata does not upgrade Node for consumers.
+
+Run the live suite separately from `next/`. Put local credentials in `.env.integration`, using
+`.env.integration.example` as the template, then run:
+
+```sh
+npm run test:integration
+```
 
-    expect(result.success).toBe(true);
-    expect(result.data.swapAmount).toBeGreaterThan(0n);
+The command uses Node's built-in `--env-file-if-exists` support; it doesn't need dotenv. Git ignores
+`.env.integration`. The example contains empty values for `BASE_RPC_URL`, `THE_GRAPH_API_KEY`, and
+`THE_GRAPH_PROXY_URL`; fill in the RPC URL and exactly one Graph setting. Don't commit credentials.
+
+Exported shell variables and CI-injected variables take precedence over file values. CI can run
+the same command without a local file. If neither source provides valid configuration, the command
+still fails before making requests.
+
+For an application-owned proxy, unset `THE_GRAPH_API_KEY` and set `THE_GRAPH_PROXY_URL` to an
+absolute HTTP(S) URL. The route must implement the existing `subgraphId` query-parameter contract
+and provide its own Graph authentication. Relative browser paths such as `/api/the-graph` won't
+work in the Node test runner. When switching authentication modes, clear the other setting in both
+the file and environment so exactly one remains nonempty. The command loads only `.env.integration`;
+it doesn't automatically load other `.env` files.
+
+The command requires `BASE_RPC_URL` and exactly one Graph setting. Missing, conflicting, or invalid
+configuration fails before tests start; there are no automatic skips or public endpoint fallbacks.
+Use a Base mainnet RPC that supports `eth_call` at a recent explicit block. Tests pin RPC reads and
+quotes to the block selected at suite startup. The subgraph retains its own indexed snapshot;
+it need not have caught up to the RPC head.
+
+Live tests verify Multicall3 routing and RPC counts through the configured transport, WETH/USDC
+pool discovery, direct reads, decoded prices and fee percentage against
+independent same-block viem reads, both pool token balances with exact decimal formatting, and a
+small QuoterV2 quote. They list pools
+by token address, symbol, and name, check token matches onchain, verify duplicate-free pagination
+at one indexed block, and inspect structured events from real indexer/HTTP calls. They perform
+reads and `eth_call` simulations only. Tests don't sign or submit transactions, and they assert
+the SDK quote against an independent viem QuoterV2 simulation at the same block, without
+hard-coding a price. Independent viem token reads check that both pagination pages still contain
+USDC when the second request supplies only a cursor. Test providers must serve the configured
+Uniswap V3 Base subgraph and have indexed enough USDC pools for two pages.
+
+The live harness omits provider error details that might echo credentials. HTTP failures retain
+their status; inspect the provider privately when a live call fails. Credential redaction assertions
+compare booleans so test failures don't print secret values. Live runs can fail because of provider
+outages, rate limits, indexer changes, or deployment changes, independently of offline tests.
+
+Default tests also cover typed lookup, family reference types, registration errors, endpoint URLs,
+vault composition, logging, and parity with the prior SDK's chain inventory. See `AGENTS.md` for
+portability rules and the separate consumer and tooling Node requirements.
+
+## Uniswap V4 on Base
+
+The V4 AMM adapter supports pool reads, indexed pool search, pool-key utilities and single-pool
+exact-input quotes. Use the same client transport, `indexers`, HTTP defaults and optional logger
+as V3. Standalone V4 vault operations are qualified separately on BNB Chain below.
+
+```ts
+const amm = steer.getAmm({
+  chainId: ChainId.Base,
+  protocol: AmmProtocol.Uniswap, version: UniswapVersion.V4,
+});
+
+const page = await amm.listPools({ token: { symbol: "USDC" }, limit: 20 });
+// Address and name searches work too, including the zero address for native ETH.
+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 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.
+
+  const quote = await amm.quote({
+    pool: recovered,
+    inputCurrency: key.currency0,
+    outputCurrency: key.currency1,
+    amountIn, // Raw units of inputCurrency.
+    hookData: "0x", // Supply the hook's required bytes when applicable.
   });
+}
+```
+
+A pool key contains `currency0`, `currency1`, `fee`, `tickSpacing`, and `hooks`. Currencies must be
+sorted numerically. Key validation includes V4 fee flags and hook permission relationships.
+Pool IDs are `keccak256(abi.encode(key))`; the hash cannot be reversed. ID-only reads use the
+configured data adapter to recover metadata and verify the complete key against its ID. Indexed
+adapters query their configured endpoint; RPC adapters use the onchain key index or initialization
+event recovery with an archival provider. Missing evidence fails clearly; a complete key avoids
+that dependency. Per-request HTTP overrides are
+accepted by `getPoolKey`, ID-based `getPool`, `quote`, and `listPools`, including
+ID-based family discovery through `steer.getPool`.
+
+Listings return complete immutable keys, with snapshot-bound, strictly ordered, duplicate-free
+pagination. Token address matches are exact; symbols and names use case-insensitive substring
+matching. Combined filters match the same token. The two token sides are queried independently
+in one GraphQL request, then merged in ID order. The indexer's `feeTier` may contain the latest
+swap fee rather than the key's original fee. Dynamic flags are verified by hash; other changed
+fees are recovered from immutable PoolManager Initialize logs at the indexed creation block.
+Recovery requires the configured RPC transport, verifies its chain, and groups up to 50 pool IDs
+per log query at the same block. It verifies every event address, block and key hash; missing or
+conflicting events fail clearly. Ordinary indexed listings still require no RPC calls.
+
+Snapshots expose `key`, `poolId`, `poolManager`, raw price/tick/liquidity, currency
+decimals, native-currency flags, decoded decimal-string prices, fees and `blockNumber`. Price
+field `currency0InCurrency1` corresponds to currency0 in currency1, including native ETH. Native ETH
+has 18 decimals on Base; ERC-20 decimals are read at the snapshot block. Fees retain the configured
+key fee, dynamic flag, current stored LP fee and packed protocol fees with each direction decoded.
+`lpFeePercent` describes the stored LP fee, not a guaranteed total swap charge. Hooks may override
+fees or alter accounting during execution, so use the actual Quoter simulation for swap amounts.
+Hook failures propagate; a quote is not a guarantee that every caller can execute a swap.
+
+V4 pools do not have individual contract addresses. PoolManager token balances cover many pools,
+so V4 snapshots intentionally do not expose V3-style pool balances or invent per-pool reserves.
+The adapter verifies chain identity, StateView/Quoter manager bindings, pool initialization and
+returned adapter identities at the selected block. The internal Solidity reader at
+`src/amm/adapters/uniswap-v4/reader/V4PoolReader.sol` combines StateView state, manager validation and
+ERC-20 decimals in one ephemeral execution. Native ETH uses 18 decimals without a token call.
+It tries deployless execution, then a helper-code override only after explicit unsupported-feature
+rejection, and uses Multicall3 only when both modes explicitly reject support. Identity failures,
+reverts, invalid responses and provider errors propagate without fallback. No transaction is sent
+and no code/storage is persisted or replaced on target contracts.
+Pinned complete-key reads and family discovery use 2 RPC requests, including chain validation.
+An override-only provider uses 3; full Multicall compatibility uses 5, including both rejected
+reader attempts. Pinned quotes remain at 4, without reader or token-metadata calls. Latest reads add one block-number request. Indexer lookups
+are HTTP requests and do not change these RPC counts unless static fee recovery needs initialization
+logs. Recovery adds one chain check and one log request per group of at most 50 IDs in a creation block.
+
+Family discovery remains available when choosing between configured V4 deployments:
+
+```ts
+const pool = await steer.getPool({
+  chainId: ChainId.Base,
+  family: AmmFamily.UniswapV4,
+  reference: { poolId }, // A complete key is also accepted.
+  // poolManager: managerAddress, // Required if multiple configured managers are ambiguous.
 });
 ```
 
-### Configuration Parameters
+`UniswapV4Adapter` is the reusable family base: extend it for compatible protocols or override
+methods for behavioral differences. `UniswapV4` supplies the protocol identity. Chain support comes
+from deployment configuration; neither class hard-codes a chain allowlist. The AMM and data-adapter
+classes and V4 models live together in `src/amm/adapters/uniswap-v4/`.
+
+`fees` uses explicit units: `configuredFee` retains the PoolKey fee/flag, `lpFeePips` and
+`lpFeePercent` describe the stored LP fee, and `protocolFeePacked` preserves the raw packed value.
+Each direction exposes `protocolFeePips` and `protocolFeePercent`. One pip is one millionth.
+`PoolPrice`, `V4PoolFees`, and `V4DirectionalFees` are named public models.
 
-| Parameter                    | Type      | Description                               |
-| ---------------------------- | --------- | ----------------------------------------- |
-| `assets`                     | `bigint`  | Amount of input token to deposit          |
-| `receiver`                   | `Address` | Address to receive LP tokens              |
-| `vault`                      | `Address` | Vault contract address                    |
-| `isToken0`                   | `boolean` | `true` for token0, `false` for token1     |
-| `depositSlippagePercent`     | `bigint`  | Max slippage for deposit (in %)           |
-| `swapSlippageBP`             | `number`  | Slippage for internal swap (basis points) |
-| `ammType`                    | `AMMType` | Type of AMM (currently UniswapV3)         |
-| `singleAssetDepositContract` | `Address` | Single-asset deposit contract address     |
+V4 contracts are registered on Base only. Deployment sources:
+[Uniswap deployments](https://developers.uniswap.org/docs/protocols/v4/deployments),
+[PoolIdLibrary](https://github.com/Uniswap/v4-core/blob/main/src/types/PoolId.sol),
+[StateView](https://github.com/Uniswap/v4-periphery/blob/main/src/lens/StateView.sol), and
+[V4 subgraph mappings](https://github.com/Uniswap/v4-subgraph/tree/main/src/mappings).
 
-### Architecture
+V3 and V4 prices share `PoolPrice` with `currency0InCurrency1` and `currency1InCurrency0`.
+V3 may return `price: undefined` for an uninitialized pool; successful V4 reads always include a price.
 
-The module is built with a modular architecture where each step is a separate, testable function:
+All pool snapshots share `PoolState.dynamicFee`. Canonical Uniswap V3 reports `false`.
+Uniswap V4 derives it from the PoolKey's `0x800000` flag, including when the current LP fee is zero.
+A hook alone does not imply dynamic fees. The hook address remains available as `pool.key.hooks`.
+Other protocol adapters must derive the flag from their own fee mechanism; protocol-fee changes
+alone do not make a pool's LP fee dynamic. V4's previous `fees.dynamic` field is now `pool.dynamicFee`.
 
+## Pool ticks and liquidity distribution
+
+Both AMM adapters expose the same tick API. V3 uses its pool address; V4 accepts a PoolKey or
+`{ poolId }`, with the existing indexer configuration and per-request HTTP overrides for ID lookup.
+
+```ts
+const options = { blockNumber }; // Omit to pin the latest block once for the operation.
+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);
+
+// Reuse an already fetched window without another RPC call.
+const sameDistribution = buildLiquidityDistribution(window);
+const depth = calculateLiquidityDepth(distribution, {
+  fromPrice: "1.25",
+  toPrice: "1.50",
+});
+depth.amount0; // { raw: bigint, formatted: string }
+depth.amount1;
 ```
-src/base/vault/single-asset/
-├── types.ts                    # TypeScript interfaces and enums
-├── calculateSwapAmount.ts      # Step 1: Calculate swap amount
-├── calculateLimitPrice.ts      # Step 2: Calculate slippage protection
-├── simulateSwap.ts            # Step 3: Simulate swap execution
-├── estimateLpTokens.ts        # Step 4: Estimate LP token output
-├── singleAssetDeposit.ts      # Main orchestrator client
-└── index.ts                   # Exports everything
+
+`getTicks` accepts 1 to 1024 tick indices, deduplicates and sorts them, and returns an entry for
+each requested tick. Uninitialized ticks have `initialized: false` and zero gross/net liquidity.
+`getSurroundingTicks` returns all initialized ticks within the inclusive bounds, including
+initialized ticks with zero net liquidity. Ranges must cover at most 64 bitmap words. Ticks are
+integers from -887272 through 887272. Neither method fabricates empty words after failed reads.
+
+Both results contain `pool` with the operation's tick, Q96 square-root price, active liquidity,
+shared `dynamicFee` flag,
+tick spacing, currency decimals and block number. This is a minimal mathematical snapshot; it
+does not fetch balances. Tick and pool state reads share one block. Family readers preserve V3
+factory allowlists/registration and V4 StateView manager/key validation before reading tick data.
+
+Small pinned reads use 2 RPC requests: chain validation and one ephemeral Solidity execution.
+Each execution scans at most four bitmap words and returns at most 128 tick records, keeping
+return data below the deployless EVM code-size limit. Larger requests continue automatically at
+the same block without repeating chain validation. Latest reads add one block-number request.
+An override-only provider adds one rejected deployless attempt. Providers rejecting both reader
+modes use batched bitmap and tick calls through the existing compatibility path; errors and
+reverts do not trigger fallback. V4 ID resolution can additionally need indexer requests and
+initialization logs, as documented above. There is no cross-operation transport capability cache.
+
+Distribution ranges must include the stored current tick. Intervals retain exact Q96 bounds,
+bigint active liquidity and reciprocal decimal-string prices. Liquidity is added when crossing
+initialized ticks to the right and removed when crossing to the left; inconsistent negative
+liquidity fails instead of being clamped. Empty initialized-tick windows can still have constant
+active liquidity. Rendering, numeric chart conversion, inversion, labels and overlays stay in the UI.
+
+Depth prices are positive decimal strings in currency1 per whole currency0, without exponent
+notation. Calculations intersect the entire selected range with the distribution and return both
+asset amounts, rounded down per interval. The SDK's published endpoint prices restore their exact
+Q96 boundaries. Requests outside fetched coverage fail instead of returning a partial amount.
+This is fee-free geometric liquidity depth, not an executable swap quote or hook simulation.
+
+### QuickSwap Integral on Base
+
+```ts
+const amm = steer.getAmm({
+  chainId: ChainId.Base,
+  protocol: AmmProtocol.QuickSwap, version: QuickSwapVersion.V4,
+});
+
+const page = await amm.listPools({ token: { symbol: "USDC" } });
+const reference = page.items[0];
+if (!reference) throw new Error("No matching pools");
+
+const pool = await amm.getPool(reference);
+const quote = await amm.quote({
+  pool: reference,
+  inputCurrency: pool.token0,
+  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 });
 ```
 
-This design allows for:
+Ordinary pools accept an address. Custom pools use `{ address, deployer }`; listings return the
+appropriate reference so it can be passed directly to reads, quotes and tick methods. The adapter
+verifies the factory, its pool deployer and the matching base/custom registration at the selected
+block. Quotes also verify the quoter's factory and pool-deployer bindings.
+
+Pool snapshots retain raw state and add decoded prices, token balances and explicit fee units.
+`fees.lastFeePips` is the stored fee and can be stale when dynamic fees are enabled; it is not a
+promise of the fee used by a future swap. `dynamicFee` comes from Integral's configuration bit,
+not plugin presence. Quotes use the deployed QuoterV2 and reject partial input consumption.
+
+Integral tick tables use raw tick indexes. Existing ticks remain valid when mint spacing changes;
+Integral tick totals use uint256. The normalized chart types and distribution/depth utilities are
+shared with V3/V4, whose stricter tick checks remain in their family readers. Scans retain the
+64-word range limit and 4-word/128-record pages. A pinned snapshot or one-page tick read uses
+2 RPC requests with deployless execution, 3 with override-only support. Full compatibility uses
+7 for snapshots, 8 for specific ticks and 9 for a nonempty one-page range. Quotes use 5.
+Latest-block selection adds one request; larger scans add bounded pages.
+
+Deployment qualification used the [published QuickSwap Base addresses](https://docs.quickswap.exchange/overview/contracts-and-addresses)
+and live checks at Base block 52733010: factory `0xC5396866754799B9720125B104AE01d935Ab9C7b`,
+pool deployer `0xE08026Fd8537d67C501199610c42D08bB34eAa75`, and QuoterV2
+`0x23E0583a3a000d567bB3848115065c1890D87fb5`. The WETH/USDC pool is
+`0x5a9Ad2BB92B0B3E5C571FDD5125114E04E02be1a`. Its six-field `globalState`, six-field tick tuple,
+quoter return layout, factory registrations and bytecode hashes are covered by the separate live
+suite. This qualifies the deployed Integral interface, without inferring a version from QuickSwap's
+"V4" branding. Additional Algebra deployments and vault implementations require separate qualification. QuickSwap Integral Base vault reads are qualified below.
+
+### Legacy Algebra: QuickSwap on Polygon and Camelot on Arbitrum
 
-- **Individual Testing**: Each function can be unit tested separately
-- **Reusability**: Functions can be used in different contexts
-- **Maintainability**: Easy to update or extend individual components
-- **Debugging**: Easy to isolate issues to specific steps
+```ts
+const quickswap = steer.getAmm({
+  chainId: ChainId.Polygon,
+  protocol: AmmProtocol.QuickSwap, version: QuickSwapVersion.V3,
+});
+const camelot = steer.getAmm({
+  chainId: ChainId.Arbitrum,
+  protocol: AmmProtocol.Camelot, version: CamelotVersion.V3,
+});
+const page = await camelot.listPools({ token: { symbol: "USDC" } });
+const address = page.items[0];
+if (!address) throw new Error("No matching pools");
+const pool = await camelot.getPool(address);
+const fee0To1 = pool.fees.currency0ToCurrency1.lastFeePercent;
+const fee1To0 = pool.fees.currency1ToCurrency0.lastFeePercent;
+
+// Resolve the protocol from the pool's registered factory within the known family.
+const discovered = await steer.getPool({
+  chainId: ChainId.Arbitrum,
+  family: AmmFamily.AlgebraLegacy,
+  address,
+});
+```
 
-## Requirements
+Both protocols use address references and expose `getPool`, `listPools`, `quote`, `getTicks`,
+`getSurroundingTicks` and `getLiquidityDistribution`. Listings support token address, symbol and
+name, with snapshot pagination and the same client `indexers` and per-request HTTP overrides.
+Snapshots include raw state, decimal-string prices, and raw/formatted balances at the same block.
+
+`AlgebraLegacyAdapter` implements the qualified QuickSwap V1 interface. `AlgebraDirectionalAdapter`
+extends it for Camelot's directional V1.9 interface, and `Camelot` selects that implementation.
+`QuickSwap` selects symmetric V1. Deployment bindings select the implementation explicitly;
+no runtime version detection or protocol-name matching is performed. Integral retains its existing
+classes and public API. Shared Algebra contracts, pool fields, RPC batching and invocation-local
+discovery live in `amm/adapters/algebra/`; ABIs, fee decoding and readers stay in the family folders.
+
+Legacy snapshots expose stored fees for **both swap directions**. They are equal for symmetric
+QuickSwap pools and can differ for Camelot. `dynamicFee: true` identifies these deployments'
+adaptive fee mechanism. Stored fees can differ from the next swap's fee. Community fee shares
+are reported separately for token0 and token1 in permille and percentage units. QuoterV2 is checked
+against the configured factory and pool deployer. Its four-value ABI does not return consumed
+input; quotes reject results at the default price boundaries where full consumption is uncertain.
+
+QuickSwap V1 bitmaps compress ticks by the fixed spacing of 60. Camelot uses raw tick indexes,
+so historical ticks need not align with its current mint spacing. Both readers preserve uint128
+legacy tick liquidity, bounded bitmap pages and the shared chart/depth API. This distinction is
+implemented by subclass overrides, without adding consumer configuration.
+
+Pinned snapshots use 2 RPC requests with deployless execution, 3 with overrides and 8 with full
+compatibility fallback. One-page specific tick reads use 2/3/9; nonempty range scans use 2/3/10.
+Quotes use 5 requests. Latest-block selection adds one request, discovery adds one factory read,
+and larger tick reads add bounded pages. Identity checks remain active on every invocation.
+
+Qualification uses [QuickSwap's published contracts](https://docs.quickswap.exchange/overview/contracts-and-addresses)
+and [Camelot's legacy AMMv3 contracts](https://docs.camelot.exchange/contracts/arbitrum/one-mainnet/).
+Independent live tests verify factory/deployer/quoter bindings, code hashes, registration, both
+fee layouts, token accounting, quotes in both directions, bitmap parity, chart depth and listing.
+Camelot's newer Integral AMMv4 factory is a separate deployment and is not registered here.
+Set `POLYGON_RPC_URL` and `ARBITRUM_RPC_URL` in `.env.integration` or CI; they share the existing
+Graph API-key or proxy configuration. SDK runtime configuration never reads this file.
+
+### Common quoting and fee terminology
+
+Every AMM exposes `quote(request, options)` through `AmmAdapter<TPoolRef>`. The request carries
+`pool`, `inputCurrency`, `outputCurrency` and `amountIn`; the result contains raw bigint
+`amountIn` and `amountOut`. Concrete V4 adapters additionally accept optional `hookData`.
+Quotes keep their family-specific routing, identity checks, read options and RPC budgets.
+
+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 |
+
+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
+these names directly: V3's former top-level `fee`/`feePercent` and the former directional names
+are replaced without compatibility aliases. Raw onchain values remain available in the fee fields.
+
+## PancakeSwap on BNB Chain
+
+The built-in BNB Chain catalog registers `AmmProtocol.PancakeSwap` with
+`PancakeSwapVersion.V3` and `PancakeSwapVersion.InfinityCL`. V3 reuses the V3 family, including the wider Pancake
+`slot0` protocol-fee field. Infinity CL has a separate family and implementation under
+`src/amm/adapters/pancakeswap-infinity-cl/`. Infinity Bin and Pancake vault support are outside
+this implementation.
 
-- Node.js >= 18.0.0
-- viem >= 2.22.0
+```ts
+const steer = new SteerClient({
+  transports: { [ChainId.BSC]: rpcTransport },
+  indexers: { theGraph: { apiKey: graphApiKey } },
+});
+const pancake = steer.getAmm({
+  chainId: ChainId.BSC,
+  protocol: AmmProtocol.PancakeSwap, version: PancakeSwapVersion.V3,
+});
+const infinity = steer.getAmm({
+  chainId: ChainId.BSC,
+  protocol: AmmProtocol.PancakeSwap, version: PancakeSwapVersion.InfinityCL,
+});
 
-## Development
+const pool = await pancake.getPool(poolAddress);
+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 });
+```
 
-1. Install dependencies:
+`getPoolKey` needs RPC, while
+`getPoolId` and `createPoolKey` are local utilities. `createPoolKey` accepts `currency0`,
+`currency1`, `hooks`, `poolManager`, `fee`, `tickSpacing`, and optional `hookPermissions`,
+and packs Infinity's `parameters` field. Currency ordering is validated, never silently changed.
+Infinity keys hash all six protocol fields, including manager and parameters. Native BNB uses
+the zero address and stays distinct from WBNB.
+
+Both adapters support snapshots, exact-input quotes, specific ticks, initialized tick ranges,
+liquidity distributions, and indexed pool listing by token address, symbol, or name. Infinity
+quotes accept optional `hookData` and reject input amounts outside positive `int128` range.
+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 |
+
+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;
+the reader resolves and verifies the canonical key within its existing call. V3 discovery
+adds one factory read; Infinity discovery shares its context with the selected adapter. Larger
+scans add bounded pages. No reader reverts or required-member failures trigger a compatibility retry.
+
+Deployments come from [Pancake V3 addresses](https://developer.pancakeswap.finance/contracts/v3/addresses)
+and [Infinity addresses](https://developer.pancakeswap.finance/contracts/infinity/resources/addresses).
+V3 uses the public [grafted V3 repair deployment](https://thegraph.com/explorer/subgraphs/G4vqYZxFaL7driMegHynL9RywXgbdWEVwR1Y7gb9YSLD).
+Its Messari schema exposes `liquidityPools` and `inputTokens`. The family-local
+`PancakeSwapV3DataAdapter` maps that schema to the existing address listing API, validates protocol
+identity against the configured factory, and keeps token address/symbol/name filters, pinned
+pagination, client indexer configuration, and request overrides. Listings require no RPC reads;
+onchain pool reads still independently verify factory registration.
+
+The configured [Infinity CL subgraph](https://thegraph.com/explorer/subgraphs/8jFYxwKP8tNGSDisucpHRK1ojUchZd7ELd8zh2ugHGDN)
+is used only for listings and currently reports indexing errors. Listing rejects these failures
+explicitly; contract operations do not depend on indexer availability. A configured data-adapter
+override can supply another compatible indexer.
+
+Set `BSC_RPC_URL` in `.env.integration` or CI to run the BNB live tests. The existing Graph API key
+or proxy configuration is reused. Live listing tests remain enabled and fail when their indexers
+are unhealthy.
+
+## Standalone Uniswap V4 vaults on BNB Chain
+
+The qualified `MultiPositionReserveV4` deployment supports the existing liquidity-vault
+methods, including same-block positions, idle balances, fees, wallet shares, bulk reads,
+deposit quotes/previews, and unsigned deposit/withdrawal preparation. Hook and parking
+vaults and other standalone implementations remain unsupported.
 
-```bash
-npm install
+```ts
+const vault = await steer.getLiquidityVault(
+  ChainId.BSC,
+  "0x0700dc95d5f17438b2e3e1a5fd2b085a648d91ba",
+);
+const snapshot = await vault.getSnapshot();
+if (vault instanceof UniswapV4Vault) {
+  const { key, poolId, poolManager } = vault.pool;
+  const pool = await vault.amm.getPool(key);
+}
+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,
+});
 ```
 
-2. Build the package:
+V4 snapshot `pool` is `{ key, poolId, poolManager }`; existing V3/Algebra snapshot pools
+remain addresses. Concrete family classes preserve those types in snapshots, positions
+and user holdings; heterogeneous client/bulk results keep the union. Native currency uses address zero, 18 decimals and real native balances.
+Native deposits carry the requested maximum as transaction value and skip native approvals.
+Unused value is refunded by the original vault. All returned transactions are unsigned.
+
+This initial family implementation uses original contract reads and the existing V4 AMM
+reader with its deployless/override/Multicall fallback. A pinned resolved snapshot takes
+16 RPCs normally or 19 through compatibility; latest adds one. Bulk reads use bounded
+compatibility orchestration, not the optimized two-RPC V3/Algebra vault readers. BNB AMM
+pool browsing and token filtering use the configured Uniswap V4 subgraph with the client's
+Graph API key or proxy. ID-only reads retain the onchain key resolver independently of indexer
+availability; missing historical key-index entries need archival RPC. Indexed keys whose mutable
+fees no longer match their IDs require RPC initialization logs to recover the original key.
+Steer indexed V4 token metadata is populated, and ERC-20 address, symbol and name searches are
+live-verified for the registered Reserve vaults. Direct address-based reads remain independently verified.
 
-```bash
-npm run build
+```ts
+const amm = steer.getAmm({
+  chainId: ChainId.BSC,
+  protocol: AmmProtocol.Uniswap,
+  version: UniswapVersion.V4,
+});
+const pools = await amm.listPools({ token: { symbol: "USDC" }, limit: 25 });
+const nextPools = pools.nextCursor
+  ? await amm.listPools({ cursor: pools.nextCursor, limit: 25 })
+  : undefined;
 ```
+See [deployment qualification and budgets](src/vault/adapters/uniswap-v4/qualification.md).
 
-3. Run tests:
+### Aerodrome Slipstream on Base
 
-```bash
-npm test
+```ts
+const amm = steer.getAmm({
+  chainId: ChainId.Base,
+  protocol: AmmProtocol.Aerodrome,
+  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.
 ```
 
-4. Format code:
+Use Slipstream, SlipstreamV2 or SlipstreamV3 explicitly; omitting version is ambiguous. All three
+support pool snapshots/batches, direct quotes, specific/surrounding ticks and liquidity charts.
+Pool references are addresses. Identity is verified using token pair plus tick spacing, not swap fee.
+Snapshots include raw/formatted pool balances, prices, observed swap fees, unstaked-fee allocation,
+gauge and NFT-manager addresses, and stakedLiquidity as a subset of total liquidity. dynamicFee is
+true because Slipstream uses mutable fee mechanisms; an observed fee is not a later execution guarantee.
 
-```bash
-npm run format
+All three generations use the public Steer catalog for discovery. No Graph API key is required.
+The call stays the same:
+
+```ts
+const page = await amm.listPools({ token: { symbol: "USDC" }, limit: 100 });
+page.items; // Pool addresses, still candidates until verified by getPool().
+page.freshness; // { revision, generatedAt, blockNumber, blockHash?, source }
+const next = page.nextCursor
+  ? await amm.listPools({ cursor: page.nextCursor, limit: 100 })
+  : undefined;
 ```
 
-5. Lint code:
+Token address, symbol and name filters match either side; combined fields match the same token.
+Pages are address-ordered, with limits from 1 to 1000. Cursors bind endpoint, chain, factory,
+filters and catalog revision. A publication between pages causes an explicit restart error,
+not mixed revisions. Each page costs one HTTP request and zero RPCs. getPool independently
+verifies factory registration using the existing reader and its unchanged RPC budget.
+
+Freshness reports the collection time/block and whether data came from KV (`stored`), a retained
+KV result (`retained`), or the bundled snapshot (`bundled`). Block/hash refer to catalog collection,
+not a promise that every cached fee or token field was refreshed then. Sugar can omit pools with
+no token0 liquidity; this is discovery coverage, not every factory-created address. No live fee,
+volume ranking or complete inventory is implied. subgraphUrl is undefined for these API adapters.
+Client HTTP defaults and per-request fetch/header/cancellation overrides remain supported.
 
-```bash
-npm run lint
+The production app API supports operation `listPools` at `/api/aerodrome/pools`. All seven
+Aerodrome live tests passed against production and Base RPC on 2026-10-20. Older API responses
+fail explicitly. For local or preview live tests, set `STEER_CATALOG_URL` to the updated app
+endpoint; it affects tests only.
+AMM deployment details are in [qualification](src/amm/adapters/aerodrome/qualification.md).
+
+### Aerodrome liquidity vaults on Base
+
+```ts
+const vault = await steer.getLiquidityVault(ChainId.Base, vaultAddress);
+const snapshot = await vault.getSnapshot();
+
+snapshot.positions; // Actual staked NFT IDs, ranges, weights, principal and recorded pair fees.
+snapshot.configuredPositions; // Strategy ranges, including currently empty ranges.
+snapshot.reservedRewards; // Collected rewards excluded from LP idle when AERO overlaps the pair.
+snapshot.rewards; // Separate reward asset, unclaimed rewards and unpaid Steer/strategist fees.
+
+const page = await steer.listVaults({
+  chainId: ChainId.Base,
+  amm: { protocol: AmmProtocol.Aerodrome, version: AerodromeVersion.SlipstreamV2 },
+  token: { symbol: "USDC" },
+});
 ```
 
-## Troubleshooting
+The original, V2 and V3 AMMs resolve automatically from exact beacon/implementation mappings and
+actual pool factories. One beacon supports both original and V2 factories. Version-filtered listing
+therefore checks vault pool factories at the indexed block, adding one RPC per candidate page on
+the normal path. Unfiltered listing remains HTTP-only. Limits apply to scanned candidates, so an
+empty filtered page can still have nextCursor. Listing candidates still require getVault identity checks.
 
-### CommonJS/ESM Import Issues
+LP totals exclude collected reward reserves and keep gauge rewards separate from the token pair.
+Snapshots preserve actual NFT tokensOwed without inventing V3 swap-fee accrual for staked NFTs.
+Small pinned resolutions, resolved snapshots and bulk snapshots each take two RPCs; latest adds one.
+Strict original-storage/Multicall compatibility remains available. Standalone claims and reward-debt
+user-read APIs remain unqualified.
 
-If you encounter the following error:
+```ts
+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 } }.
 
-```typescript
-import { SteerClient } from "@steerprotocol/sdk";
-         ^^^^^^^^^^^
-SyntaxError: Named export 'SteerClient' not found. The requested module '@steerprotocol/sdk' is a CommonJS module...
+const plan = await vault.prepareWithdraw({ account, shares, receiver, slippageBps: 50 });
+// Submit plan.transactions from plan.account on plan.chainId using your wallet integration.
 ```
 
-Add the following to your `tsconfig.json`:
+Withdrawals pay all accrued shareholder rewards, including when only some shares are burned.
+Rewards remain separate from LP proceeds even when AERO is a pool token. Preparation simulates
+original execution again and returns one unsigned withdrawal. Slippage protects the LP amounts;
+the contract has no reward-minimum parameter. Previews/preparation each cost three pinned RPCs,
+or four with latest block selection; original-contract failures remain explicit.
+Deposits use the original pre-settlement totals and the exact verified helper. The same one-token
+quote, preview and unsigned preparation API is supported:
 
-```json
-{
-  "compilerOptions": {
-    "esModuleInterop": true,
-    "allowSyntheticDefaultImports": true
-  }
-}
+```ts
+const quote = await vault.quoteDeposit({ asset: token0, amount });
+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,
+});
 ```
 
-## License
+The token owner supplies the assets; pre-existing rewards go to the share receiver. New shares do
+not earn past rewards. Quotes have no receiver and omit rewards. Preview/preparation return a
+separate raw/formatted reward payout, even when AERO is a deposited asset. They use three pinned
+RPCs or four for latest, without requiring wallet funding for the quote. Preparation checks
+allowances, adds capped approvals/reset approvals when needed, and appends one unsigned deposit.
+Slippage protects accepted token amounts, not minimum minted shares or reward amounts. No swap,
+standalone claim, signing or broadcasting occurs. Empty vaults require explicit asset maxima;
+Aerodrome's qualified helper accepts one raw initial share. One-sided vaults quote only the held asset.
+
+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
+BNB Reserve deployment. The oracle difference belongs to tend validation, not snapshot accounting.
+Use `steer.getVaultSnapshots(ChainId.Robinhood, addresses, { blockNumber })` or a resolved vault's
+`getSnapshot()`. Exact proxy/beacon/implementation/helper identities, stored registry, pool routing
+and fees are checked at the selected block. Full pool keys are read from vault contracts; indexed
+pool listing remains unavailable; ID-only lookup uses the shared onchain key resolver. See the [deployment qualification](src/vault/adapters/uniswap-v4/qualification.md#robinhood-shared-snapshot-deployment).
+
+V4 wallet discovery uses `listUserVaults()` with indexed candidates and onchain share balances,
+including shares acquired by transfer. Transfer-aware subgraph holdings are not required.
+Live tests cover BSC Reserve and Robinhood NoOracle holders for both ERC20 and native pairs,
+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
+family data adapter's key resolution. The RPC adapter is reusable on any configured canonical
+Uniswap V4 deployment. It verifies the configured PositionManager and the full key hash.
+Pools absent from that contract's key index are recovered from their original initialization
+event using historical RPC state. Recovery searches recent history first; older pools require
+an archival provider. Missing history
+is an error, not a fabricated key. Pool browsing remains separate and requires an indexed adapter.
+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 PancakeSwap V3 vault snapshots
+
+`MultiPositionPancake` vaults on BSC use the shared `UniswapV3Vault` implementation and
+existing fixed-fee reader. Resolve by address with `getLiquidityVault(ChainId.BSC, address)`
+or use `getVaultSnapshots`. Pool factory, registry, beacon, implementation and proxy runtime
+are checked at the operation block. Only the exact qualified deployment is supported.
+
+This implementation reserves accrued Steer and strategist fees separately and takes a fixed
+30% cut of earned fees. Its fee cut is rounded once over all ranges, matching original
+`poke()` followed by `getTotalAmounts()` in a single read-only simulation. Other V3 deployments
+keep their existing rounding policy. BSC now uses optimized bulk resolution and snapshot readers
+for both Pancake V3 and Reserve V4, with bounded compatibility only after an explicit
+unsupported-override response. See the bulk execution matrix below.
+
+See [Pancake vault qualification](src/vault/adapters/uniswap-v3/pancake-qualification.md) for
+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.
+Resolve with `getLiquidityVault(ChainId.Arbitrum, address)` or call `getVaultSnapshots`.
+The exact beacon/implementation, proxy code, stored registry, pool factory/deployer and
+currencies are checked at the snapshot block. This covers the qualified legacy directional
+Algebra deployment; Camelot Integral and other beacon types are separate registrations.
+
+A directional override reader preserves both pool swap fees and community shares while
+reusing existing position/fee accounting. Vault fees are fixed at 15% with aggregate rounding.
+Normal resolved snapshots take two RPC calls. Unsupported overrides use original-contract
+compatibility reads and the AMM's existing pool-reader fallbacks. Live checks cover funded
+three-range and five-range vaults. Bulk resolution and snapshots now use the shared coordinator
+with a directional family reader; compatibility remains bounded after explicit feature rejection.
+See [Camelot qualification](src/vault/adapters/algebra-legacy/camelot-qualification.md).
+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
 
-MIT
+Select pools with `{ protocol: AmmProtocol.Blackhole, version: BlackholeVersion.CL }`.
+Blackhole uses Integral-compatible pool reads with custom-deployer identity preserved.
+Pool and vault searches support token addresses, symbols, names and pagination.
 
-## Pancake v4 / Sushi Infinity on Robinhood
+The exact qualified `MultiPositionBlackHole` deployment resolves to `BlackholeVault` through
+`getLiquidityVault(ChainId.Avalanche, address)`. Snapshots include separate immutable `rewardAssets`
+and position-level `nftTokensOwed` diagnostics excluded from LP entitlement. Wallet discovery uses
+indexed vault candidates plus on-chain share balances. User positions and prepared ERC20 deposit
+and withdrawal flows have passed live simulations, including partial/full withdrawal rewards.
+AVAX inputs use an explicit WAVAX wrap before deposit. Native exits use a separate unwrap after
+withdrawal confirmation; standalone reward claims are not exposed. Vault reads use bounded
+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:
+
+```ts
+const plan = await vault.prepareDeposit({
+  account,
+  receiver,
+  assets: [
+    { asset: zeroAddress, amount: avaxMaximum },
+    { asset: otherToken, amount: otherMaximum },
+  ],
+  slippageBps: 50,
+});
+```
+
+The ordered unsigned transactions wrap AVAX, approve tokens if necessary, then deposit.
+Submit them in order from `account`. Only the wrap transaction carries AVAX. Unused input
+remains WAVAX, as shown in the preview's underlying-token `unusedAmounts`. Other assets are
+not swapped. Avoid providing both AVAX and WAVAX in the same request.
+
+Withdraw normally with `prepareWithdraw`. After confirmation, the WAVAX recipient can call
+`prepareUnwrapNative({ account: recipient, amount: actualWavaxReceived })` on `BlackholeVault`.
+This prepares a separate WAVAX withdrawal transaction that pays AVAX to `recipient` after
+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
+repeats actual-contract deposits/withdrawals and balance-based discovery at retained pinned blocks.
+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 |
+
+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
+execution call per position-budget chunk (soft budget: 128 ranges). Latest reads add one shared
+head lookup. These are operating limits, not protocol vault limits. Metadata HTTP requests are
+separate. Explicit override rejection selects compatibility; provider failures do not select
+fallback or become individual failed vaults.
+
+The read-only [BSC/Arbitrum benchmark](tests/integration/benchmarks/vault-bulk.bsc-arbitrum.test.ts)
+retains RPC/HTTP counts, payload sizes, failures, pinned blocks and sampled single-reader parity.
+See [benchmark results](benchmarks/README.md#bsc-and-arbitrum-vault-bulk-execution).
+
+### Partial vault loading and pool reads
+
+Strict calls still reject the whole batch. Opt in to ordered, immutable per-input outcomes:
+
+```ts
+const vaults = await steer.getVaults(chainId, addresses, {
+  blockNumber,
+  metadata, // optional complete indexed VaultMetadata records
+  allowFailure: true,
+});
+for (const result of vaults) {
+  if (result.status === "success") console.log(result.vault.address);
+  else console.log(result.error);
+}
+
+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);
+}
+```
 
-Use `Protocol.SushiV4` with protocol family `pancake-v4` for the Infinity CL deployment and `SushiV4DynamicFeeALM` beacon. The app supplies a hardcoded Infinity pool list; pool state is read onchain through the CL manager. The configured Goldsky endpoint currently indexes Sushi v3 data.
+These methods preserve input order and duplicates. Unsupported implementations, absent V4 keys,
+and contract member failures do not discard successful members or trigger recursive splitting.
+Native readers retain their page sizes and RPC counts. Explicitly unsupported provider execution
+uses the existing bounded compatibility path. Shared RPC failures, invalid request context,
+malformed shared RPC responses, and shared vault metadata request failures still reject the call.
+`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
+can throw `V4PoolKeyNotFoundError` to report an absent key explicitly.
+
+Blackhole reward assets expose `unattributedReservedFees`: stored fee reserves not attributed
+to the current fee identifiers after a fee-policy replacement. These remain part of
+`reservedFees`, fully excluded from LP holdings. Current-recipient unpaid fees plus
+`unattributedReservedFees` reconcile to the stored reserve; current unclaimed fee cuts still
+reconcile exactly to the current policy.