@steerprotocol/sdk 4.0.0-next.6 → 4.0.0-next.8

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;
@@ -101,6 +102,8 @@ 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.
 
@@ -206,6 +209,26 @@ snapshots[0]?.total.token0.formatted;
 snapshots[0]?.fees.net.token1.raw;
 ```
 
+Opt in to independent vault failures with `allowFailure: true`:
+
+```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);
+}
+```
+
+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()`
@@ -1346,9 +1369,11 @@ for (const key of page.items) {
 
 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 require the
-configured indexer to recover metadata and verify the complete key against its ID. Missing keys
-fail clearly; supplying a complete key avoids that dependency. Per-request HTTP overrides are
+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`.
 
@@ -1727,9 +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/ID lookup is explicitly unavailable without a qualified indexer; full-key reads work.
-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
@@ -1851,3 +1891,165 @@ standalone claim, signing or broadcasting occurs. Empty vaults require explicit
 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 bulk vault reads retain bounded compatibility
+orchestration; this addition does not introduce a two-RPC bulk optimization.
+
+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 snapshots use bounded existing orchestration.
+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
+
+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.
+
+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.
+### 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);
+}
+```
+
+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.