@wireio/stake 2.7.4 → 3.0.0

package/README.md

@@ -6,13 +6,14 @@ chain‑specific power features (Outpost, pretokens, SquadsX, validator tools, e
 
 ## What this SDK does
 - One `Staker` that selects the right chain client by `chainId`.
-- Deposit / withdraw native → LIQ tokens (SOL→liqSOL, ETH→liqETH).
-- Stake / unstake LIQ into yield pools (Solana Outpost; Ethereum staking manager).
+- Deposit / withdraw native → LIQ tokens (SOL→liqSOL, ETH→liqETH today; LiqMON/LiqPOL as those deployments arrive).
+- Stake / unstake LIQ into yield pools (Solana Outpost; EVM staking manager).
 - Pre-launch WIRE pretokens purchase helpers.
 - Rich `getPortfolio` view (native, liq, staked, $WIRE, yield, extras).
 - Gas / fee helpers (`getDepositFee`, `getDepositBuffer`, `getSystemAPY`).
 - Solana extras: balance correction + registration, Outpost state, multisig (SquadsX) flows.
-- Ethereum extras: withdrawal receipts, validator deposit/lock, tranche snapshots.
+- EVM extras: withdrawal receipts, validator deposit/lock, tranche snapshots.
+- Public instaswap execution clients for EVM and Solana outpost swaps, bridge deposits, faucet helpers, and artifact-backed chain reads used by Hub.
 
 ## SquadsX (Solana multisig) at a glance
 - Pass `extras.squadsX` when constructing a Solana `StakerConfig`:
@@ -35,16 +36,17 @@ chain‑specific power features (Outpost, pretokens, SquadsX, validator tools, e
 - **Snapshots:** `getTrancheSnapshot(chainId)` powers price ladders, liquidity/utilization charts, and native USD hints.
 
 ## Supported networks (today)
-- **Solana**: `SolChainID.Mainnet`, `SolChainID.Devnet`.
-- **EVM**: `EvmChainID.Ethereum`, `EvmChainID.Hoodi` (testnet).
+- **Solana full clients**: `SolChainID.Mainnet`, `SolChainID.Devnet` for public devnet, and `SOL_WIRE_DEVNET_CHAIN_ID` (`devnet-wire`) for the Wire Solana devnet.
+- **EVM contract service chains**: `EvmChainID.Ethereum`, `EvmChainID.Hoodi`, and `EVM_WIRE_DEVNET_CHAIN_ID` (`31337`). Hoodi currently aliases the mainnet ABI artifact/address bundle in `EvmContractService`; switch that alias to `src/assets/evm/hoodi` and a Hoodi address book when Hoodi-specific artifacts or deployments diverge.
+- **Registered connect/read-only chains**: Monad Testnet (`MONAD_TESTNET_CHAIN_ID`, LiqMON) and Polygon Amoy (`POLYGON_AMOY_CHAIN_ID`). They are in the chain registry now but intentionally do not instantiate staking clients until the full contract suite/artifacts are deployed.
 
-The unified interface is chain-id driven: `new Staker(configs, selectedChainId)` builds per-chain clients behind the scenes, and `staker.setChain(chainId)` swaps the active client. Adding future chains (e.g., Sui) only requires implementing `IStakingClient` and wiring its `chainId` into the router—no API changes for consuming apps.
+The unified interface is chain-id driven: `new Staker(configs, selectedChainId)` builds per-chain clients behind the scenes, and `staker.setChain(chainId)` swaps the active client when one exists while still recording read-only selections. Adding future chains requires extending `SDK_CHAIN_REGISTRY` first, then wiring a full `IStakingClient` only when staking contracts/programs are deployed.
 
 ## Installation
 ```bash
 npm install @wireio/stake
 ```
-Peer requirement: `@wireio/core >=0.1.0 <0.4.0`.
+Peer requirement: `@wireio/core >=0.1.0 <0.6.0`.
 
 ## Quick start: pick a chain, then call through `client`
 
@@ -60,7 +62,7 @@ const solCfg: StakerConfig = {
   provider: solAdapter,
   network: {
     chainId: SolChainID.Devnet,
-    name: 'Wire Solana Devnet',
+    name: 'Solana Devnet',
     rpcUrls: ['https://...', 'wss://...'],
     nativeCurrency: { symbol: 'SOL', decimals: 9 },
   },
@@ -68,7 +70,7 @@ const solCfg: StakerConfig = {
   extras: { squadsX: { multisigPDA: '<base58>', vaultIndex: 0 } }, // optional
 };
 
-// ---- Ethereum example (browser provider) ----
+// ---- EVM example (browser provider) ----
 const ethProvider = new ethers.providers.Web3Provider(window.ethereum);
 const ethCfg: StakerConfig = {
   provider: ethProvider,
@@ -103,7 +105,7 @@ const portfolio = await client?.getPortfolio(); // unified balance snapshot
 - Multisig: if `extras.squadsX` is set, write calls become Squads proposals (`sendSquadsIxs`).
 - Portfolio extras include key PDAs (vault, reserve pool, user ATA) plus Outpost index/shares math.
 
-### Ethereum flow (what happens)
+### EVM flow (what happens)
 - `deposit(amountWei)`: via `ConvertClient.performDeposit`; returns tx hash.
 - `withdraw(amountWei)`: burns liqETH and enqueues withdrawal; receipts are NFTs.
 - `getPendingWithdraws()` / `claimWithdraw(tokenId)`: manage withdrawal queue.
@@ -111,6 +113,7 @@ const portfolio = await client?.getPortfolio(); // unified balance snapshot
 - `buy(amountWei)`: pretokens via `PretokenClient.purchasePretokensWithLiqETH`.
 - `validatorDeposit()`: validator bond/lock helper.
 - Portfolio includes native/liq/staked/$WIRE and yield (index/shares) when contracts expose them.
+- Depositor-backed ETH writes keep a `callStatic` preflight and fall back to an explicit `gasLimit` when `estimateGas` breaks on ETH Wire Devnet, so valid stake / instaswap / pretoken submits can still reach the wallet prompt.
 
 ## Solana specifics
 - **Clients composed under the hood**: `DepositClient`, `DistributionClient`, `OutpostClient`,
@@ -119,21 +122,37 @@ const portfolio = await client?.getPortfolio(); // unified balance snapshot
   transactions (`sendSquadsIxs`).
 - **Outpost / Yield**: `getPortfolio()` returns `yield` (index-scale math) and `staked` amounts; `wire`
   reports pretokens (1e8 scale).
+- **Fresh-wallet reads**: missing liqSOL Token-2022 ATAs are treated as zero-balance on read paths, so
+  first-time wallets can connect before their first liqSOL receive. Write flows that need to mint to the
+  user ATA should still rely on on-chain `init_if_needed` account constraints or an explicit ATA-create
+  instruction in the submitted transaction. The Solana staking client now auto-prepends that ATA create
+  step for receive-side `claimLiqsolRewards`, `unstake`, and `unstakeAndWithdraw` writes when needed.
 - **Helpers**: `getDepositBuffer`, `getDepositFee`, `getSystemAPY`, tranche snapshots via
   `getTrancheSnapshot(chainId)`.
 
-## Ethereum specifics
+## EVM specifics
 - Uses `ethers` provider/signer; falls back to JSON RPC for read-only.
 - Modules used: `ConvertClient` (deposit/withdraw), `StakeClient`, `PretokenClient`, `OPPClient`,
   `ReceiptClient` (withdrawal NFTs), `ValidatorClient`.
+- The checked-in `31337` devnet addresses in `src/networks/evm/contract.ts` are a Wire EVM devnet deployment snapshot and must be refreshed whenever that devnet is redeployed.
 - Additional endpoints:
   - `getPendingWithdraws()` → pending withdrawal receipts.
   - `claimWithdraw(tokenId)` → claim queued withdrawal by NFT id.
   - `unstakePrelaunch(tokenId, recipient)` → prelaunch unstake path.
   - `validatorDeposit()` → validator bond/lock flow.
-  - `getTrancheSnapshot(chainId)` → pretoken ladder view with price/supply growth.
+- `getTrancheSnapshot(chainId)` → pretoken ladder view with price/supply growth.
   - `getOPPMessages(address?)` and `getEthStats()` for operator/pay-rate data.
 
+## Cross-chain instaswap execution
+- `EvmStakingClient.instaswapClient.submitCrossChain(...)` handles LIQETH approval, depositor preflight, recoverable OPP epoch reconciliation, and `instaswapCrossChain` submission.
+- `SolanaStakingClient.instaswapClient.submitCrossChain(...)` handles LIQSOL outpost account assembly using the bridge/OPP account set required by the current Solana IDL, `instaswapCrossChain` submission, timeout recovery, and generic OPP epoch finalization retries.
+- `EvmStakingClient.instaswapClient.depositToWire(...)` and `SolanaStakingClient.instaswapClient.depositToWire(...)` own bridge deposit account wiring, submission, and OPP recovery.
+- `SolanaStakingClient.stake(...)` / `OutpostClient.buildStakeIx(...)` use the same bridge/OPP account set for `syndicateLiqsolToWire`; `desynd` remains pool-based on the current devnet IDL.
+- Native ETH/SOL faucet requests stay in Hub. The SDK owns the artifact-backed deposit/mint and bridge/outpost execution paths that consume those balances.
+- Solana native deposits retry through `registerUser` when the program reports `LegacyUserRecordMigrationRequired`, so legacy distribution user records do not block LIQSOL minting flows.
+- `getOutpostAddresses()` and `getConnectedBalances(...)` expose lightweight artifact-backed reads so consuming apps do not instantiate contracts/program PDAs directly.
+- Keep product concerns such as route selection, quote math, wallet network UX, and native-token top-up policy outside the SDK. The Hub swap service is the reference consumer for that split.
+
 ## Portfolio shape (all chains)
 ```ts
 type Portfolio = {
@@ -150,7 +169,7 @@ type Portfolio = {
 
 ## Error handling
 - All write methods throw on failure; wrap with `try/catch`.
-- Solana transaction failures include logs; Ethereum methods surface tx hashes for inspection.
+- Solana transaction failures include logs; EVM methods surface tx hashes for inspection.
 - Passing `provider` is required for writes; read-only is supported for many getters.
 
 ## Using from a service (pattern)
@@ -198,7 +217,7 @@ Hub-specific extras you can reuse:
 ```bash
 npm ci            # install
 npm run prepare   # build to lib/ via rollup
-npm test          # full test suite (make targets exist for sol/eth split)
+npm test          # full test suite (make targets exist for sol/evm split)
 npm run docs      # generate typedoc to docs/ (gh-pages ready)
 ```
 
@@ -206,7 +225,7 @@ npm run docs      # generate typedoc to docs/ (gh-pages ready)
 - `staker.ts` – chain router / façade.
 - `types.ts` – shared interfaces (IStakingClient, Portfolio, tranche snapshots).
 - `networks/solana/*` – clients, IDL wiring, constants, utils.
-- `networks/ethereum/*` – contract service, clients, tranche math.
+- `networks/evm/*` – contract service, clients, tranche math.
 - `assets/` – IDLs, ABIs, artifacts.
 
 ## Versioning & license