@steerprotocol/sdk 4.0.0-next.12 → 4.0.0-next.14

package/README.md

@@ -2194,8 +2194,9 @@ empty filtered page can still have nextCursor. Listing candidates still require
 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.
+Strict original-storage/Multicall compatibility remains available. Dedicated getUserRewards and
+prepareClaimRewards methods now expose caller-owned reward reads and unsigned claims; see the
+[standalone reward qualification](benchmarks/standalone-rewards-qualification-2026-11-08.md).
 
 ```ts
 const withdrawal = await vault.previewWithdraw({ account, shares, receiver });
@@ -2273,6 +2274,49 @@ is an error, not a fabricated key. Pool browsing remains separate and requires a
 Base retains its existing indexed adapter by default. BNB combines indexed browsing with RPC key
 resolution; Robinhood uses RPC key resolution without indexed pool browsing.
 
+### BNB Thena Fusion
+
+`MultiPositionThena` resolves through `AmmProtocol.Thena` / `ThenaVersion.Fusion`
+and the exact qualified symmetric legacy Algebra deployment. Single/bulk snapshots use
+15% aggregate fee rounding and two native pinned RPC requests, with per-member failures.
+Pool browsing uses the verified Graph endpoint, including pagination and token searches.
+Swap quotes simulate the original pool, verify actual input consumption, and require deployless
+calls or code overrides. They never decode the published two-word V1 quoter as V2.
+
+Wallet discovery, user positions, ERC20 deposit/withdrawal, native BNB wrapping and separate WBNB
+unwrapping have read-only simulation coverage. Both WBNB vaults use WBNB as token1. Execute and
+confirm an exit before preparing an unwrap from actual received WBNB. Classic, Static Stable and
+Channel Multiplier run through the installed loaders with their actual registered WASM, including
+Channel Multiplier's real data connector. These claims apply to the qualified Fusion v1
+implementation, not Thena Integral or arbitrary future implementations.
+See [Thena qualification](src/vault/adapters/algebra-legacy/thena-qualification.md) for evidence,
+provider requirements, request budgets and verification limits.
+
+### Base Hydrex Integral vault snapshots
+
+`getVaultSnapshots(ChainId.Base, addresses)` supports the exact qualified `MultiPositionHydrex`
+implementation through the existing Integral reader. Hydrex and QuickSwap retain separate exact
+identities and factories on Base. Native snapshots use two pinned RPC requests and preserve ordered
+per-member failures. Independent original post-poke accounting, retained responses and fallback
+costs are documented in [Hydrex qualification](src/vault/adapters/algebra-integral/hydrex-qualification.md).
+AMM selection uses `AmmProtocol.Hydrex` and `HydrexVersion.Integral`.
+
+The funded representative also has qualified wallet discovery, user positions, ERC20 deposit
+quotes/previews/preparation and partial/full withdrawal preparation. Live rolled-back simulations
+verify real share mint/burn and token movements. Pool browsing/search, both swap quote directions and tick/chart reads have representative live
+qualification. Native ETH deposits prepare WETH wrapping before approvals/deposit; unused input
+remains WETH. After a confirmed withdrawal, use `AlgebraIntegralVault.prepareUnwrapNative` with
+an actual WETH balance for a separate unwrap. The registered WASM strategy also runs locally
+with its actual configuration and empty connector list. Nonempty Hydrex connector manifests and
+other implementations still need qualification. See the qualification document for exact evidence
+and limits.
+
+### BSC SushiSwap and Uniswap V3 snapshots
+
+The exact qualified `MultiPositionSushi` and `MultiPositionUniswapV3` implementations now support vault resolution, single/bulk snapshots and direct pool reads. They reuse the fixed-fee V3 reader with 15% aggregate fee rounding. Normal bulk snapshot pages use two pinned RPC requests and preserve per-member failures with `allowFailure: true`.
+
+AMM-filtered Steer vault listing works. Underlying AMM pool browsing remains unqualified: both inherited subgraphs returned pool rows without the expected factory identity and the SDK rejects those responses. Deposit/withdrawal flows were not newly qualified by this snapshot work. Base Sushi is separately qualified after the 30-vault migration, using its exact upgraded FeeManager/helper implementation; see [Base Sushi qualification](src/vault/adapters/uniswap-v3/base-sushi-qualification.md). See [source and live qualification](src/vault/adapters/uniswap-v3/bsc-qualification.md).
+
 ### BSC PancakeSwap V3 vault snapshots
 
 `MultiPositionPancake` vaults on BSC use the shared `UniswapV3Vault` implementation and
@@ -2321,7 +2365,7 @@ and position-level `nftTokensOwed` diagnostics excluded from LP entitlement. Wal
 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
+withdrawal confirmation. Dedicated getUserRewards and prepareClaimRewards methods expose standalone reward reads and claims. Vault reads use bounded
 compatibility calls, without a two-RPC guarantee.
 
 See [qualification](src/vault/adapters/blackhole/qualification.md) for exact identities and evidence.
@@ -2431,3 +2475,182 @@ to the current fee identifiers after a fee-policy replacement. These remain part
 `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.
+
+### Base SushiManaged and Robinhood V3 snapshots
+
+The exact qualified `MultiPositionSushiManaged` on Base and `MultiPositionSushi` /
+`MultiPositionUniswapV3` on Robinhood now support vault snapshots and native V3 pool routing.
+Each uses its stored FeeManager and helper. Current captured fee rates are 8000, 1500 and 3000
+basis points respectively; these apply to earned fees. Original same-block post-poke accounting
+and actual helper bytecode verify reserve exclusion and stored/fresh fee inclusion.
+
+Managed and ordinary Base Sushi remain separate vault identities on the same AMM deployment.
+Base and Robinhood support two-request native snapshot pages. Robinhood mixes qualified V3 and V4
+vaults in the same batch, preserving individual failures and pinned accounting. All 33 eligible
+Robinhood catalog vaults passed a retained six-request scan.
+
+Real-balance ERC20 deposit/withdrawal simulations, wallet positions and actual registered strategies
+passed for the three added deployments; both Robinhood strategies include their real price connector.
+Robinhood deposit estimates use sequential original contract accounting through an ephemeral helper.
+Robinhood Uniswap V3 pool browsing still requires a verified indexer. Its inherited Celo placeholder
+has been removed; specific pool reads and vault discovery continue to work.
+
+**Robinhood Uniswap V3 pool discovery limitation:** No public subgraph with sufficient coverage
+has been verified. Sentry's live Robinhood subgraph returned no record for either the qualified
+vault's V3 pool (`0xe2b46c905e12ab8e2f864e4821a4325884c1b126`) or the canonical WETH/USDG
+0.05% V3 pool (`0x69bfaf19c9f377bb306a89aed9f6b07e2c1a8d9a`). A healthy indexer alone does
+not establish pool coverage. [Goldsky lists Uniswap as a Robinhood data customer](https://goldsky.com/blog/robinhood-chain-data-live-on-goldsky),
+but that announcement identifies neither a V3 query endpoint nor its coverage. Pool listing/search
+remains explicitly unavailable until a Robinhood V3 indexer is verified; known-pool reads, vault
+listing, snapshots and the qualified user flows remain available.
+
+See [V3 holdings qualification](src/vault/adapters/uniswap-v3/holdings-qualification.md) for exact
+identities, retained/live evidence, request counts and remaining gaps.
+
+### BNB Uniswap V4 ALM
+
+The exact `MultiPositionUniswapV4` beacon/implementation is registered separately from Reserve V4.
+It reuses the source-qualified standalone accounting reader and optimized mixed-family batches.
+All five matching registry vaults currently have zero shares and no liquidity ranges. Native
+snapshots match their original totals; mixed Uniswap/Reserve pages preserve two-request execution
+and individual failures. Controlled original-runtime fee/reserve tests and a real-balance bootstrap
+deposit with partial/full original exits also pass.
+
+Funded shared accounting is verified against six Reserve representatives, including hooked DTF
+vaults. The five newly registered vaults remain empty; exact-runtime controlled tests and bootstrap
+simulations provide separate evidence. All five known pools appear in retained token searches.
+Browsing now checks the configured PositionManager index before falling back to initialization
+logs for inconsistent indexed keys. All 29 inconsistent keys in the tested pages resolved through
+that index, without logs or block receipts.
+
+Registered strategy/connector execution passes with valid manifests. An older Reserve manifest
+lacks required strategy settings and is rejected by the loader; compute-specific overrides remain
+outside the SDK. The oracle-enabled implementation's hooked-pool oracle read currently reverts,
+so original `tend` needs deployment-policy attention. No oracle bypass is introduced.
+See [BNB Uniswap V4 qualification](src/vault/adapters/uniswap-v4/bsc-uniswap-qualification.md).
+
+### Optimism and Arbitrum Uniswap V3
+
+Exact `MultiPositionUniswapV3` deployments on Optimism and Arbitrum reuse the qualified Polygon
+fixed-fee reader. Funded snapshots match original post-poke totals in native and fallback modes.
+Native resolution and snapshot pages retain two pinned RPC requests, including mixed Arbitrum
+Camelot/Uniswap batches and individual unsupported members. Both accrued fee reserves remain
+excluded from LP idle assets; shared provider failures stay fatal.
+
+Vault listing, known-pool reads and pool token searches work on both chains. Optimism uses a
+qualified replacement Graph endpoint covering all 14 known vault pools, with token-filtered
+pagination verified. Deployment-specific user flows and WASM execution are separate verification work. See [qualification and request budgets](src/vault/adapters/uniswap-v3/optimism-arbitrum-qualification.md).
+
+### Group 7 V3 registrations
+
+Optimism Sushi, Arbitrum Sushi/Pancake and Flare SparkDex v3.2 now have exact source-qualified
+vault registrations and optimized two-request native snapshot pages. All four funded
+representatives match original post-poke accounting. Sushi/Pancake retain fixed 15% aggregate
+fee rounding; Spark32 uses its actual FeeManager and the existing qualified helper.
+
+Vault listing and known-pool reads work on all four. Pool searches and pagination pass for
+Sushi and Spark32. Arbitrum Pancake's inherited indexer fails consistent pinned-page queries,
+so its pool browsing remains unqualified. User-flow and WASM qualification remain separate.
+Select Spark32 with `AmmProtocol.Spark` and `SparkVersion.V3_2`. See [exact identities and evidence](src/vault/adapters/uniswap-v3/group7-qualification.md).
+
+### Ethereum Cypher and Flare SparkIntegral
+
+The exact `MultiPositionCypher` and `MultiPositionSparkIntegral` deployments now reuse Algebra
+Integral readers with optimized vault resolution/snapshots. Funded representatives match original
+post-poke holdings in all three reader modes. Native single/bulk snapshots take two pinned RPCs;
+a mixed Flare Spark32/Integral page does too. Pool reads, indexed vault listing and token-filtered
+pool browsing pass retained real-response checks.
+
+Select Cypher with `AmmProtocol.Cypher` / `CypherVersion.V4`, or SparkIntegral with
+`AmmProtocol.Spark` / `SparkVersion.V4`. Spark32 remains `SparkVersion.V3_2`; omitting Spark's
+version is now ambiguous. V4 here is product branding for Algebra Integral.
+
+Deployment-specific user-flow/native-token/WASM verification remains separate. These registrations
+do not qualify every implementation or enable API instrumentation on additional chains. See
+[identities, fee proof, request counts and limits](src/vault/adapters/algebra-integral/multichain-qualification.md).
+
+### Remaining V3 vault registrations
+
+Ethereum Sushi/SushiManaged/Uniswap, Avalanche Sushi, Katana Sushi and Bittensor V3 now have exact
+source-qualified snapshot bindings through the existing FeeManager/helper reader. Funded native,
+deployless and Multicall snapshots match original post-poke holdings. Bittensor's helper matches
+Robinhood's qualified implementation; select its AMM with `AmmProtocol.Bittensor` / `BittensorVersion.V3`.
+
+Vault discovery and direct pool reads pass for all six targets. Pool token search/pagination passes
+for Ethereum Uniswap, Avalanche, Katana and Bittensor; Ethereum Sushi's inherited indexer reports
+indexing errors. Ethereum/Katana/Bittensor native bulk reads use two pinned RPCs per ordinary page.
+Avalanche Sushi now uses two-call native bulk reads; mixed pages keep Sushi batched while
+Blackhole retains its separate farming reader. Deployment-specific user-flow/WASM and API APR acceptance remain separate. See
+[exact identities, manager rates, evidence and gaps](src/vault/adapters/uniswap-v3/remaining-qualification.md).
+
+Local source now registers all 37 chain/beacon snapshot targets in the API rollout matrix.
+This does not enable additional API chains or qualify every SDK feature on every deployment.
+
+Avalanche Sushi snapshot pages now use **2 RPC requests for 16 inputs**, down from 266; 17 inputs
+use 4. Three distinct Sushi vaults also use 2 requests and match original post-poke totals. Mixed
+pages preserve Blackhole rewards/NFT accounting and per-member failures. Blackhole now uses the
+same bulk coordinator: **two shared view requests plus one original farming simulation per active
+NFT**. The three funded one-NFT snapshots each use **3 RPC requests instead of 62**; mixed
+Sushi/Blackhole pages use **3 instead of 63**. Three distinct Blackhole vaults use 5 requests.
+Farming simulations retain the original caller and state. Compatibility reads and fatal provider
+errors are preserved. See the [Sushi benchmark](benchmarks/vault-bulk-avalanche-2026-11-07.json) and
+[Blackhole benchmark](benchmarks/vault-bulk-blackhole-2026-11-07.json).
+
+### November 7 discovery, quote and native-flow completion
+
+- Sushi V3 on BSC/Base/Polygon and Uniswap V3 on BSC now use their indexers' lowercase factory
+  entity IDs. Onchain identities and other deployments' case-sensitive entity IDs are preserved.
+  Live first/continuation pages and retained offline regressions pass.
+- Sushi V3 on BSC/Base/Polygon and Spark32 on Flare now configure verified factory-bound QuoterV2
+  deployments. Positive quotes in both directions match independent same-block contract simulations.
+  The public swap method is `amm.quote(request, options)`.
+- Pancake V3 BSC accepts native BNB, and Camelot legacy Arbitrum accepts native ETH, through the
+  existing wrap/approval/deposit sequence. Real funded-account simulations cover deposits, partial/full
+  exits and a separate balance-checked `prepareUnwrapNative`. Exits return wrapped currency; unwrap
+  after confirmation using the actual received amount. Wrapper identity and native/wrapped ambiguity
+  checks remain explicit. No transactions were broadcast.
+
+See [discovery and quote evidence](src/vault/adapters/uniswap-v3/bsc-qualification.md),
+[Pancake native flows](src/vault/adapters/uniswap-v3/pancake-qualification.md) and
+[Camelot native flows](src/vault/adapters/algebra-legacy/camelot-qualification.md).
+Robinhood Uniswap V3/V4 complete pool catalogs and the separately documented deployment-specific
+user-flow/WASM qualification remain follow-up work. These changes describe local source, not publication.
+
+### Updated representative user-flow qualification (November 7, 2026)
+
+Fresh original-contract simulations now qualify the two Robinhood V4 representatives
+(ERC20 and native ETH) and 16 later deployment representatives. Actual connector and
+strategy WASM execution also passed for 19 representatives, including Bittensor,
+Optimism Uniswap and Arbitrum Sushi. These results supersede the earlier blanket
+user-flow/WASM follow-up statements above for the exact representatives in the
+[qualification report](benchmarks/vault-user-flow-qualification-2026-11-07.md).
+
+Bittensor deposit quotes, previews and preparation now use the existing ephemeral
+accounting path when Multicall deployment metadata is absent. Funded deposit/exit
+execution remains pending. BSC Sushi and Arbitrum Uniswap connector execution are
+verified with data-connector-loader 5.0.0-next.9 and its corrected subgraph routing.
+The Arbitrum fix preserves the original connector configuration and uses the
+consumer credential instead of forwarding the embedded key.
+Historical Robinhood live replays still require RPC history that the public provider
+may prune. These checks establish representative behavior, not all deployments or
+API APR acceptance, and do not enable additional native conveniences or discovery.
+
+### Native currency across registered vault families
+
+Registered V3, Legacy Algebra, Integral and Aerodrome vaults accept the zero address for native inputs when their pair contains the qualified wrapper on Ethereum, Optimism, Flare, BSC, Polygon, Bittensor, Robinhood, Base, Arbitrum, Avalanche or Katana. Use the existing quoteDeposit, previewDeposit and prepareDeposit methods. Prepared transactions wrap the maximum native input before approvals and deposit; unused input remains wrapped. Quotes do not perform swaps. Empty vaults still require explicit two-token maxima.
+
+After a withdrawal confirms, use vault.prepareUnwrapNative({ account, amount }) with the actual received wrapped balance to prepare a separate unwrap. The SDK verifies the wrapper's runtime and, where applicable, proxy implementation at the pinned block. A chain's presence or a token's symbol alone does not enable wrapping. Existing V4 direct-native and Blackhole native AVAX flows retain their own accounting.
+
+Original-contract checks passed for all 11 wrappers and 28 native-funded deposit/exit representatives, including Bittensor TAO. Aerodrome's stored-manager and V3 exit verification encountered inactive gauges: original contracts revert with GK when trying to restake. Those variants are not claimed fully verified for native exits; no matching native V2 candidate was found in the queried sample. See [native-currency qualification](benchmarks/native-currency-qualification-2026-11-08.md) for exact vaults, blocks, limits and reproduction.
+
+### Standalone shareholder rewards
+
+BlackholeVault and AerodromeVault expose getUserRewards(account, options) and prepareClaimRewards(account, options). The read returns account, blockNumber, shares and rewards: an array of { token, decimals, claimable, rewardDebt }, with raw/formatted token amounts. Reward debt is a stored accounting checkpoint preventing double payment, not a user liability. Claims pay the caller and do not burn shares. Blackhole users can still have accrued rewards after transferring all shares.
+
+```ts
+const rewards = await vault.getUserRewards(account, { blockNumber });
+const plan = await vault.prepareClaimRewards(account, { blockNumber });
+// Send plan.transactions with the wallet for plan.account after reviewing plan.preview.
+```
+
+Preparation verifies the original deployment and simulates the original claim at one block. It returns one unsigned zero-value transaction, with no approvals or configurable recipient. Actual rewards can change before confirmation. Errors are surfaced rather than converted into empty rewards. Positive original-contract claims passed on Blackhole and all three registered Aerodrome implementation layouts, including inactive-gauge representatives and overlapping reward tokens. These claims do not establish that Aerodrome withdrawals/rebalances work after gauge deactivation. Exact scope and replay commands are in the [qualification report](benchmarks/standalone-rewards-qualification-2026-11-08.md).