@steerprotocol/sdk 4.0.0-next.7 → 4.0.0-next.9

package/README.md

@@ -90,7 +90,8 @@ interface VaultMetadata {
   readonly beaconName: string;
   readonly createdAt: string;
   readonly state: string | null;
-  readonly pool: Address | 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;
@@ -102,6 +103,7 @@ interface VaultMetadata {
 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.
 
@@ -1274,9 +1276,9 @@ resolution for both declaration formats, and a Next.js production build with ser
 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.1 and 26.12.1.
+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.1 runtime.
+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),
@@ -1750,10 +1752,24 @@ This initial family implementation uses original contract reads and the existing
 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
-listing is unavailable without a qualified indexer. ID-only and full-key reads work through
-the configured onchain data adapter; missing historical key-index entries need archival RPC.
-Steer indexed V4 beacon candidates are available, but token metadata is incomplete and
-V4 token search is not qualified. Direct address-based reads are independently verified.
+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.
+
+```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).
 
 ### Aerodrome Slipstream on Base
@@ -1902,7 +1918,8 @@ Pools absent from that contract's key index are recovered from their original in
 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 and Robinhood use RPC key resolution.
+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
@@ -1915,8 +1932,9 @@ are checked at the operation block. Only the exact qualified deployment is suppo
 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 bulk vault reads retain bounded compatibility
-orchestration; this addition does not introduce a two-RPC bulk optimization.
+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
@@ -1935,7 +1953,8 @@ A directional override reader preserves both pool swap fees and community shares
 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 snapshots use bounded existing orchestration.
+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.
@@ -1995,6 +2014,32 @@ repeats actual-contract deposits/withdrawals and balance-based discovery at reta
 It uses pinned public indexer responses and paces live RPC calls by 1.5 seconds. No Graph API
 credentials or Base RPC are needed for this isolated runner. Full historical state and temporary
 EOA code overrides must be supported. Native BNB/ETH wrapping helpers remain separate work.
+### Bulk vault execution coverage
+
+Accepting an array does not imply optimized execution. In `4.0.0-next.8`, BSC and Arbitrum
+accepted both bulk methods but used individual-vault reads with concurrency four. This change
+adds native bulk readers for their exact qualified deployments.
+
+| Chain / qualified vaults | Bulk API | Efficient execution in `4.0.0-next.8` | Efficient execution after this change |
+| --- | --- | --- | --- |
+| Base: V3, Integral, Aerodrome | Yes | Yes | Yes |
+| Polygon: registered V3, Legacy, Integral | Yes | Yes | Yes |
+| BSC: Pancake V3 and Reserve V4 | Yes | No | Yes |
+| Arbitrum: Camelot legacy | Yes | No | Yes |
+| Robinhood: NoOracle V4 | Yes | No | Bounded individual reads |
+| Avalanche: Blackhole | Yes | No | Bounded individual reads |
+
+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: