@whetstone-research/doppler-sdk 1.0.41 → 1.0.43

package/README.md

@@ -15,7 +15,7 @@ The Doppler SDK exposes network-specific entrypoints for creating, managing, and
 - **Solana Clients and React**: Read clients, PDA helpers, generated codecs, and optional React bindings
 - **Token Management**: Built-in EVM support for DERC20 tokens with vesting
 - **Type Safety**: Full TypeScript support across EVM and Solana entrypoints
-- **Network Support**: EVM deployments on Base, Arbitrum One, BNB Smart Chain (BSC), Unichain, Ink, and other supported chains; Solana/SVM support via explicit Solana program deployments
+- **Network Support**: EVM deployments on Ethereum, BNB Smart Chain (BSC), Monad, Robinhood Chain, Arc, Base, and Arbitrum; Solana/SVM support via explicit Solana program deployments
 
 ## Installation
 
@@ -101,7 +101,9 @@ For runnable Solana flows, configure `examples/.env` and run with `pnpm tsx`, fo
 - [examples/solana-cosigner-gated-buy.ts](./examples/solana-cosigner-gated-buy.ts)
 - [examples/solana-usdc-e2e-launch.ts](./examples/solana-usdc-e2e-launch.ts)
 - [examples/solana-usdc-cosigner-gated-buy.ts](./examples/solana-usdc-cosigner-gated-buy.ts)
-- [examples/solana-prediction-market.ts](./examples/solana-prediction-market.ts)
+- [Prediction markets guide](./docs/solana-prediction-markets.md): complete lifecycle helpers, six executable scenarios, payout accounting, and [ABI migration](./docs/solana-prediction-migration.md).
+- Concise prediction examples: [create](./examples/solana-prediction-create.ts), [buy](./examples/solana-prediction-buy.ts), [resolve and settle](./examples/solana-prediction-resolve.ts), [claim or refund](./examples/solana-prediction-claim.ts).
+- [Full prediction scenario runner](./test/solana/integration/prediction/run.ts)
 - [examples/solana-swap.ts](./examples/solana-swap.ts)
 - [examples/solana-vesting-launch.ts](./examples/solana-vesting-launch.ts)
 - [examples/solana-vesting-claim.ts](./examples/solana-vesting-claim.ts)
@@ -324,76 +326,6 @@ console.log('Hook address:', result.hookAddress);
 console.log('Token address:', result.tokenAddress);
 ```
 
-### Opening Auction (Lifecycle + Bid Management)
-
-Support includes:
-
-- `sdk.buildOpeningAuction()` for `CreateOpeningAuctionParams`
-- `sdk.factory.simulateCreateOpeningAuction(params)` and `sdk.factory.createOpeningAuction(params)`
-- `sdk.getOpeningAuction(hookAddress)` for hook reads + `settleAuction()` / `claimIncentives()`
-- `sdk.factory.simulateCompleteOpeningAuction(...)` and `sdk.factory.completeOpeningAuction(...)` for handoff to Doppler
-- `sdk.getOpeningAuctionLifecycle(initializerAddress?)` for initializer-level state + complete/recover/sweep helpers
-- `sdk.getOpeningAuctionPositionManager(positionManagerAddress?)` for placing/withdrawing opening-auction bids
-  - Resolve the address via `await (await sdk.getOpeningAuctionLifecycle(initializerAddress)).getPositionManager()` when chain defaults are not configured
-  - Resolve `positionId` for incentives via `opening.getPositionId(...)` or `opening.claimIncentivesByPositionKey(...)` (no log parsing required)
-
-> **Base caveat:** on Base mainnet (`chainId = 8453`), `openingAuctionInitializer` and `openingAuctionPositionManager` default to `0x0000000000000000000000000000000000000000` until deployment. Override with `.withOpeningAuctionInitializer('0x...')` / `.withOpeningAuctionPositionManager('0x...')` (or pass explicit addresses) before using opening-auction create/completion/bid flows there.
-
-```typescript
-const params = sdk
-  .buildOpeningAuction()
-  .tokenConfig({
-    name: 'My Token',
-    symbol: 'MTK',
-    tokenURI: 'https://example.com/metadata.json',
-  })
-  .saleConfig({
-    initialSupply: parseEther('1000000'),
-    numTokensToSell: parseEther('900000'),
-    numeraire: '0x...',
-  })
-  .openingAuctionConfig({
-    auctionDuration: 3600,
-    minAcceptableTickToken0: -887220,
-    minAcceptableTickToken1: -887220,
-    incentiveShareBps: 500,
-    tickSpacing: 60,
-    fee: 3000,
-    minLiquidity: 1n,
-    shareToAuctionBps: 8000,
-  })
-  .dopplerConfig({
-    minProceeds: parseEther('10'),
-    maxProceeds: parseEther('100'),
-    startTick: -69080,
-    endTick: -92103,
-  })
-  .withMigration({ type: 'uniswapV4', fee: 3000, tickSpacing: 60 })
-  .withUserAddress('0x...')
-  .withOpeningAuctionInitializer('0x...') // required on Base until deployed
-  .build();
-
-const sim = await sdk.factory.simulateCreateOpeningAuction(params);
-const created = await sim.execute();
-
-const opening = await sdk.getOpeningAuction(created.openingAuctionHookAddress);
-await opening.getPhase();
-
-const lifecycle = await sdk.getOpeningAuctionLifecycle('0x...');
-await lifecycle.getState(created.tokenAddress);
-
-await sdk.factory.completeOpeningAuction({
-  asset: created.tokenAddress,
-  initializerAddress: '0x...',
-});
-```
-
-`completeOpeningAuction` auto-settles and auto-mines `dopplerSalt` when omitted; because completion mining can race with block timestamps/state changes, the SDK may re-mine and retry a few times if needed. `simulateCompleteOpeningAuction` requires the opening auction to already be settled.
-
-Position-manager bid wrappers are available, but bid sizing is still “advanced user”: `liquidity` is Uniswap V4 liquidity units. Use `simulatePlaceBid(...)` / `simulateWithdrawBid(...)` to inspect the `BalanceDelta` (token amounts in/out) and iterate. During the active auction, liquidity withdrawals must be full (no partial removals); use `withdrawFullBid(...)` to read the onchain liquidity and withdraw safely.
-
-See [examples/opening-auction-lifecycle.ts](./examples/opening-auction-lifecycle.ts) for the full builder/factory/lifecycle flow, and [examples/opening-auction-bidding.ts](./examples/opening-auction-bidding.ts) for the bid-management pattern + positionId resolution.
-
 ### Multicurve Auction (V4 Multicurve Initializer)
 
 Multicurve auctions use `DopplerHookInitializer` by default to seed liquidity across multiple curves in a single Uniswap V4 pool. The typed initializer modes are `dopplerHookInitializer`, `standard`, `scheduled`, `decay`, and `rehype`; use `withV4MulticurveInitializer(address)` when explicitly targeting the legacy standard initializer.
@@ -1401,12 +1333,9 @@ for (const id of SUPPORTED_CHAIN_IDS) {
 }
 ```
 
-Arbitrum One is available as `CHAIN_IDS.ARBITRUM` (`42161`) with a viem chain
-definition included in `SupportedChain`.
+Available launch features depend on the contracts deployed on the selected network. Use `getAddresses(chainId)` to inspect its deployment configuration. For native V4 numeraires, use `zeroAddress` and the chain's native currency decimals rather than the decimals of an ERC-20 token with the same symbol.
 
-Robinhood Chain is available as `CHAIN_IDS.ROBINHOOD` (`4663`). The SDK exposes
-addresses and support checks for it, but does not export a viem chain definition;
-use your application's chain/client setup when constructing clients.
+Arc uses native USDC with 18 decimals. Import the SDK's `arc` chain definition and provide an explicit RPC transport; Multicall3 is configured for fee previews. Arc launches with `numeraire: zeroAddress` must stay on Uniswap V4: all V3 static launches (including `LockableUniswapV3Initializer`) and both `uniswapV2` and `uniswapV2Split` migrations reject native USDC. Use a nonzero ERC-20 numeraire for those V2/V3 paths. For native dynamic auctions on Arc, use `dopplerHookMigrator`; locked native multicurve pools can use `noOp`.
 
 ## Advanced Usage
 
@@ -1763,49 +1692,40 @@ pnpm dev
 
 The SDK includes comprehensive tests covering:
 
-- **Airlock Whitelisting**: Verifies that all modules are properly whitelisted on Ethereum Mainnet, Arbitrum One, BNB Smart Chain (BSC), Monad Mainnet, Base Mainnet, Base Sepolia, and Robinhood Chain
-- **Multicurve Functionality**: Tests multicurve auction creation and quoting
+- **Airlock Whitelisting**: Verifies that configured modules are whitelisted on the selected networks
+- **Auction Workflows**: Tests dynamic and multicurve creation, quoting, and executed buy/sell round trips on local Anvil forks
 - **Token Address Mining**: Tests for generating optimized token addresses
 
-To run whitelisting tests:
+Configure Alchemy once, then run the whitelist audit:
 
 ```bash
-# Canonical whitelist audit
+export ALCHEMY_API_KEY=your_key_here
 pnpm test:whitelisting
 
-# With Alchemy fallback (faster and more reliable)
-ALCHEMY_API_KEY=your_key_here pnpm test:whitelisting
-
 # Limit to specific whitelist-audit chains when needed
-TEST_CHAINS=mainnet,base,base-sepolia,arbitrum,bsc,monad-mainnet,robinhood pnpm test:whitelisting
+TEST_CHAINS=mainnet,base,base-sepolia,arbitrum,bsc,arc,monad-mainnet,robinhood pnpm test:whitelisting
 ```
 
-The whitelisting suite is scoped to the release-audit chains: Ethereum Mainnet, Arbitrum One, BNB Smart Chain (BSC), Monad Mainnet, Base Mainnet, Base Sepolia, and Robinhood Chain.
+Use `TEST_CHAINS` to select networks by their comma-separated names, or omit it to check all networks configured in the whitelisting suite.
 
-Whitelisting test RPC priority is:
-
-1. Chain-specific RPC URL env var (`ETH_MAINNET_RPC_URL`, `ARBITRUM_RPC_URL`, `BSC_RPC_URL`, `BASE_RPC_URL`, `BASE_SEPOLIA_RPC_URL`)
-2. `ALCHEMY_API_KEY` fallback for supported Alchemy networks, including Monad Mainnet
-3. Public/default RPC URL
+The test harness selects the network endpoint from the chain ID; no per-chain RPC URL setup is needed.
 
 To run fork tests (Anvil):
 
 ```bash
 # all fork tests
-ALCHEMY_API_KEY=your_key_here pnpm test:fork
+pnpm test:fork
 
 # chain-specific fork tests
-ALCHEMY_API_KEY=your_key_here TEST_CHAIN=base pnpm test:fork
-ALCHEMY_API_KEY=your_key_here TEST_CHAIN=base-sepolia pnpm test:fork
-ALCHEMY_API_KEY=your_key_here TEST_CHAIN=mainnet pnpm test:fork
+TEST_CHAIN=base pnpm test:fork
+TEST_CHAIN=base-sepolia pnpm test:fork
+TEST_CHAIN=mainnet pnpm test:fork
+TEST_CHAIN=monad-mainnet pnpm test:fork
+TEST_CHAIN=robinhood pnpm test:fork
+TEST_CHAIN=arc pnpm test:fork
 ```
 
-You can also provide chain-specific RPC URLs directly:
-
-```bash
-ETH_MAINNET_RPC_URL=https://... TEST_CHAIN=mainnet pnpm test:fork
-ARBITRUM_RPC_URL=https://... TEST_CHAIN=arbitrum pnpm test:fork
-```
+The shared mainnet suite buys and partially sells through each newly created dynamic, Rehype, NoOp, and deployed scheduled pool. Arc uses native USDC; other networks use their configured wrapped native token. Checks verify receipts, acquired and sold tokens, and returned numeraire, with gas costs excluded from native sell proceeds. Fork tests do not broadcast to mainnet.
 
 ## Migration from Previous SDKs