@whetstone-research/doppler-sdk 1.0.40 → 1.0.42

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, 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
 
@@ -324,76 +324,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.
@@ -459,8 +389,7 @@ const salt =
   '0x1111111111111111111111111111111111111111111111111111111111111111' satisfies Hex;
 
 const deterministicParams = { ...params, salt };
-const preview =
-  await sdk.factory.simulateCreateMulticurve(deterministicParams);
+const preview = await sdk.factory.simulateCreateMulticurve(deterministicParams);
 ```
 
 Persist and reuse the salt with otherwise identical inputs for a later
@@ -469,7 +398,6 @@ independent create operation. Builder users can call `.withSalt(salt)` before
 preserves the generated-salt behavior. Explicit salts must be `0x` followed by
 exactly 64 hexadecimal characters.
 
-
 **Market Cap Presets (Low / Medium / High):**
 
 ```typescript
@@ -984,7 +912,7 @@ For a runnable release-focused example covering legacy DERC20, DERC20 V2 schedul
 
 DopplerERC20V1 is the default token template when `type` is omitted. Set `type: 'dopplerERC20V1'` to make that choice explicit, or set `type: 'standard'` to use the legacy token path, where cliff/allocation vesting routes to the legacy DERC20 template. The SDK uses the configured `dopplerERC20V1Factory` by default; `withTokenFactory(address)` takes precedence but must point to a factory compatible with the selected token path and token data ABI. `controller` is optional and defaults to the zero address, so set it only if early balance-limit disable should be possible.
 
-When balance limiting is enabled on the default DopplerERC20V1 integration, the SDK encodes user exclusions plus determinable protocol recipients for the selected auction path into deployment-time `excludedFromBalanceLimit`, including initializers, hooks, PoolManager, migrators, known migration pools, no-op governance, launchpad governance multisigs, and standard GovernanceFactory timelocks for `default` or `custom` governance. Custom `withTokenFactory(address)` paths receive only the `excludedFromBalanceLimit` entries supplied in `tokenConfig`, so custom token factory users must provide any required deployment-time exclusions themselves. Custom `withGovernanceFactory(address)` paths skip standard-governance timelock auto-exclusion, so custom governance factory users must provide any required timelock exclusions themselves. Exclusions cannot be added later through the controller or governance.
+When balance limiting is enabled on the default DopplerERC20V1 integration, the SDK encodes user exclusions plus determinable protocol recipients for the selected auction path into deployment-time `excludedFromBalanceLimit`, including initializers, hooks, PoolManager, migrators, known migration pools, no-op governance, and launchpad governance multisigs. It cannot safely predict the nonce-based timelock created by `default` or `custom` governance. For those governance modes, the SDK rejects configurations where `initialSupply - numTokensToSell - vesting allocations` exceeds `maxBalanceLimit`, because Airlock would transfer that excess to the non-excluded timelock and revert. Allocate enough tokens to the sale or vesting, increase the limit, or use no-op or launchpad governance. Custom `withTokenFactory(address)` paths receive only the `excludedFromBalanceLimit` entries supplied in `tokenConfig`, so custom token factory users must provide required deployment-time protocol exclusions themselves. Exclusions cannot be added later through the controller or governance.
 
 DopplerERC20V1 supports vesting through `withVesting` while staying on the DopplerERC20V1 factory path: use `duration` with optional `cliffDuration` for a shared schedule, or `allocations` for per-beneficiary schedules.
 
@@ -1246,7 +1174,7 @@ migration: {
 }
 ```
 
-### Migrate to Uniswap V2 with Proceeds Split + Top-ups
+### Migrate to Uniswap V2 with Proceeds Split
 
 ```typescript
 migration: {
@@ -1259,9 +1187,8 @@ migration: {
 ```
 
 - The split recipient receives the configured share of numeraire proceeds during migration.
-- If the asset/numeraire pair was topped up in `TopUpDistributor` before migration, the split recipient also receives those top-ups automatically.
 
-### Migrate to Uniswap V4 with Proceeds Split + Top-ups
+### Migrate to Uniswap V4 with Proceeds Split
 
 ```typescript
 migration: {
@@ -1284,50 +1211,11 @@ migration: {
 
 - `streamableFees` is required for `uniswapV4Split`.
 - Beneficiaries must sum to `1e18`, and the Airlock owner must be included with at least 5% shares.
-- The split recipient also receives any `TopUpDistributor` funds pulled during migration.
-
-### TopUpDistributor Top-ups
-
-The SDK exposes `sdk.topUpDistributor` and `sdk.getTopUpDistributor(address?)`
-for building, simulating, and submitting `topUp({ asset, numeraire, amount })`
-transactions where `getAddresses(chainId).topUpDistributor` is configured. The helper methods
-accept the same object shape for `buildTopUpTransaction({ asset, numeraire, amount })` and
-`simulateTopUp({ asset, numeraire, amount })`. ETH top-ups use `numeraire = ZERO_ADDRESS` and
-send `value = amount`; ERC20 top-ups send no native value and require the user to approve the
-`TopUpDistributor` before calling `topUp`.
-
-```typescript
-import { ZERO_ADDRESS } from '@whetstone-research/doppler-sdk/evm';
-import { parseEther } from 'viem';
-
-const topUps = sdk.topUpDistributor;
-
-const tx = topUps.buildTopUpTransaction({
-  asset: tokenAddress,
-  numeraire: ZERO_ADDRESS,
-  amount: parseEther('1'),
-});
-
-const simulation = await topUps.simulateTopUp({
-  asset: tokenAddress,
-  numeraire: ZERO_ADDRESS,
-  amount: parseEther('1'),
-});
-
-await topUps.topUp({
-  asset: tokenAddress,
-  numeraire: ZERO_ADDRESS,
-  amount: parseEther('1'),
-});
-```
-
-Split migrators pull any TopUpDistributor balance for the asset/numeraire pair during migration
-and pay it to the configured split recipient.
 
 ### Migrate via DopplerHookMigrator (Dynamic Auctions)
 
-Use this mode when you want rehypothecation / custom hook behavior on the
-migrated V4 pool. This migration type is only supported for dynamic auctions.
+Use this mode when the migrated V4 pool needs an optional generic Doppler hook.
+This migration type is only supported for dynamic auctions.
 
 ```typescript
 const params = sdk
@@ -1357,72 +1245,27 @@ const params = sdk
     lockDuration: 30 * 24 * 60 * 60,
     beneficiaries: [
       { beneficiary: '0xYourBeneficiary...', shares: parseEther('0.95') },
-      await sdk.getAirlockBeneficiary(), // required protocol owner entry (>=5%)
+      await sdk.getAirlockBeneficiary(),
     ],
-    rehype: {
-      buybackDestination: '0xYourBuybackDestination...',
-      customFee: 3000,
-      feeRoutingMode: 'directBuyback',
-      feeDistributionInfo: {
-        assetFeesToAssetBuybackWad: parseEther('0.25'),
-        assetFeesToNumeraireBuybackWad: parseEther('0.25'),
-        assetFeesToBeneficiaryWad: parseEther('0.25'),
-        assetFeesToLpWad: parseEther('0.25'),
-        numeraireFeesToAssetBuybackWad: parseEther('0.25'),
-        numeraireFeesToNumeraireBuybackWad: parseEther('0.25'),
-        numeraireFeesToBeneficiaryWad: parseEther('0.25'),
-        numeraireFeesToLpWad: parseEther('0.25'),
-      },
+    hook: {
+      hookAddress: '0xYourDopplerHook...',
+      onInitializationCalldata: '0x...',
     },
   })
   .withUserAddress('0xYourAddress...')
   .build();
 ```
 
-Note: `dopplerHookMigrator` beneficiaries must include the current Airlock owner
-with at least 5% shares, and total shares must sum to `1e18`.
-Unlike initializer-side Rehype pools, migrator-side Rehype uses a static
-`customFee`; there is no fee decay schedule in this mode.
+`dopplerHookMigrator` beneficiaries must include the current Airlock owner with
+at least 5% shares, and total shares must sum to `1e18`. Omit `hook` for a
+standard migrated pool without custom hook behavior.
+
 For backwards compatibility, the deprecated `DopplerHookMigrationConfig` type
 and its `type: 'dopplerHook'` discriminator remain accepted. New code should use
 `DopplerHookMigratorConfig` with `type: 'dopplerHookMigrator'`. Multicurve
 initializer params similarly accept the deprecated `type: 'dopplerHook'`
 discriminator, which resolves to `dopplerHookInitializer`.
 
-```typescript
-migration: {
-  type: 'dopplerHookMigrator',
-  fee: 3000,
-  useDynamicFee: false,
-  tickSpacing: 10,
-  lockDuration: 30 * 24 * 60 * 60,
-  beneficiaries: [
-    { beneficiary: '0xYourBeneficiary...', shares: parseEther('1') },
-  ],
-  rehype: {
-    // optional; defaults to chain rehypeDopplerHookMigrator address
-    // hookAddress: '0xRehypeMigratorHook...',
-    buybackDestination: '0xYourBuybackDestination...',
-    customFee: 3000,
-    feeRoutingMode: 'directBuyback',
-    feeDistributionInfo: {
-      assetFeesToAssetBuybackWad: parseEther('0.25'),
-      assetFeesToNumeraireBuybackWad: parseEther('0.25'),
-      assetFeesToBeneficiaryWad: parseEther('0.25'),
-      assetFeesToLpWad: parseEther('0.25'),
-      numeraireFeesToAssetBuybackWad: parseEther('0.25'),
-      numeraireFeesToNumeraireBuybackWad: parseEther('0.25'),
-      numeraireFeesToBeneficiaryWad: parseEther('0.25'),
-      numeraireFeesToLpWad: parseEther('0.25'),
-    },
-  },
-  proceedsSplit: {
-    recipient: '0xProceedsRecipient...',
-    share: parseEther('0.1'),
-  },
-}
-```
-
 To make configuring the first beneficiary simpler, the SDK now exposes helpers for resolving the
 airlock owner and creating the default 5% entry:
 
@@ -1488,12 +1331,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
 
@@ -1850,51 +1690,40 @@ pnpm dev
 
 The SDK includes comprehensive tests covering:
 
-- **Airlock Whitelisting**: Verifies that all modules are properly whitelisted on Ethereum Mainnet, Arbitrum One, 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,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, 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`, `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
-ALCHEMY_API_KEY=your_key_here TEST_CHAIN=eth-sepolia 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
-ETH_SEPOLIA_RPC_URL=https://... TEST_CHAIN=eth-sepolia 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