@whetstone-research/doppler-sdk 1.0.9 → 1.0.10

package/README.md

@@ -11,7 +11,7 @@ The Doppler SDK consolidates functionality from the previous `doppler-v3-sdk` an
 - **Static Auctions**: Fixed price range liquidity bootstrapping using Uniswap V3
 - **Dynamic Auctions**: Gradual Dutch auctions using Uniswap V4 hooks
 - **Multicurve Initializer**: Seed Uniswap V4 pools across multiple curves
-- **Flexible Migration**: Support for migrating to Uniswap V2, V3, or V4
+- **Flexible Migration**: Support for V2, V2 split, V4, V4 split, DopplerHook, and no-op migration paths
 - **Token Management**: Built-in support for DERC20 tokens with vesting
 - **Type Safety**: Full TypeScript support with discriminated unions
 - **Chain Support**: Works with Base, Unichain, Ink, and other EVM chains
@@ -65,8 +65,9 @@ Static auctions use Uniswap V3 pools with concentrated liquidity in a fixed pric
 
 ```typescript
 import { StaticAuctionBuilder } from '@whetstone-research/doppler-sdk/evm';
+import { base } from 'viem/chains';
 
-const params = new StaticAuctionBuilder()
+const params = new StaticAuctionBuilder(base.id)
   .tokenConfig({
     name: 'My Token',
     symbol: 'MTK',
@@ -186,8 +187,9 @@ import {
   DynamicAuctionBuilder,
   DAY_SECONDS,
 } from '@whetstone-research/doppler-sdk/evm';
+import { base } from 'viem/chains';
 
-const params = new DynamicAuctionBuilder()
+const params = new DynamicAuctionBuilder(base.id)
   .tokenConfig({
     name: 'My Token',
     symbol: 'MTK',
@@ -232,7 +234,7 @@ const params = new DynamicAuctionBuilder()
   .withDopplerDeployer('0xDeployer...')
   .withTokenFactory('0xFactory...')
   .withV4Initializer('0xInitializer...')
-  .withGovernanceFactory('0xGovFactory...') // used for both standard and no‑op governance
+  .withGovernanceFactory('0xGovFactory...') // used for standard, no-op, or launchpad governance overrides
   // .withV2Migrator('0xV2Migrator...')
   // .withV3Migrator('0xV3Migrator...')
   // .withV4Migrator('0xV4Migrator...')
@@ -354,7 +356,7 @@ const params = new MulticurveBuilder(base.id)
     ],
   })
   .withGovernance({ type: 'default' })
-  // Choose a migration path (V2, V3, or V4)
+  // Choose a migration path (V2, V2 split, V4, V4 split, DopplerHook, or noOp)
   .withMigration({ type: 'uniswapV2' })
   .withUserAddress('0x...')
   .build();
@@ -598,9 +600,10 @@ import {
   DynamicAuctionBuilder,
 } from '@whetstone-research/doppler-sdk/evm';
 import { parseEther } from 'viem';
+import { base } from 'viem/chains';
 
 // Dynamic auction via builder
-const dynamicParams = new DynamicAuctionBuilder()
+const dynamicParams = new DynamicAuctionBuilder(base.id)
   .tokenConfig({
     name: 'My Token',
     symbol: 'MTK',
@@ -624,7 +627,7 @@ const dynamicParams = new DynamicAuctionBuilder()
 const dyn = await sdk.factory.createDynamicAuction(dynamicParams);
 
 // Static auction via builder
-const staticParams = new StaticAuctionBuilder()
+const staticParams = new StaticAuctionBuilder(base.id)
   .tokenConfig({
     name: 'My Token',
     symbol: 'MTK',
@@ -652,7 +655,7 @@ The SDK intelligently applies defaults when parameters are omitted. Here are exa
 
 ```typescript
 // Minimal static auction via builder
-const staticMinimal = new StaticAuctionBuilder()
+const staticMinimal = new StaticAuctionBuilder(base.id)
   .tokenConfig({
     name: 'My Token',
     symbol: 'MTK',
@@ -671,7 +674,7 @@ const staticMinimal = new StaticAuctionBuilder()
 const staticResult = await sdk.factory.createStaticAuction(staticMinimal);
 
 // Minimal dynamic auction via builder
-const dynamicMinimal = new DynamicAuctionBuilder()
+const dynamicMinimal = new DynamicAuctionBuilder(base.id)
   .tokenConfig({
     name: 'My Token',
     symbol: 'MTK',
@@ -832,6 +835,67 @@ import { Derc20 } from '@whetstone-research/doppler-sdk/evm';
 const tokenDirect = new Derc20(publicClient, walletClient, tokenAddress);
 ```
 
+### DopplerERC20V1 Tokens
+
+Use the newer DopplerERC20V1 token template by either setting `type: 'dopplerERC20V1'` explicitly or by passing fields such as `maxBalanceLimit` with `balanceLimitEnd`, `controller`, or `excludedFromBalanceLimit`. When selected, the SDK uses the configured `dopplerERC20V1Factory` by default. `withTokenFactory(address)` is a generic factory override and takes precedence, but it must point to a factory compatible with the selected token path and token data ABI. `controller` is optional and defaults to the zero address, set it only if early balance-limit disable should be possible. Standard configs without the specific fields still use the legacy `standard` path, where cliff/allocation vesting routes to legacy DERC20 V2. Keep explicit `type: 'dopplerERC20V1'` when you want its behavior but have no specific fields to infer from.
+
+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. Custom `withTokenFactory(address)` paths receive only the `excludedFromBalanceLimit` entries supplied in `tokenConfig`, so custom factory users must provide any required deployment-time exclusions themselves. Exclusions cannot be added later through the controller or governance. Default and custom governance timelocks are not precomputed before create, so account for them before deployment or disable strict limits early via the controller when needed.
+
+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.
+
+```typescript
+const params = new StaticAuctionBuilder(base.id)
+  .tokenConfig({
+    name: 'My Doppler Token',
+    symbol: 'MDT',
+    tokenURI: 'ipfs://doppler-token.json',
+    maxBalanceLimit: parseEther('10000'),
+    balanceLimitEnd: Math.floor(Date.now() / 1000) + 30 * DAY_SECONDS,
+    controller: userAddress, // optional; defaults to zero address when omitted
+    excludedFromBalanceLimit: [userAddress], // default DopplerERC20V1 path also adds protocol modules
+  })
+  .saleConfig({
+    initialSupply: parseEther('1000000'),
+    numTokensToSell: parseEther('900000'),
+    numeraire: wethAddress,
+  })
+  .poolByTicks({ startTick: -120000, endTick: -60000, fee: 3000 })
+  .withVesting({
+    duration: 365n * BigInt(DAY_SECONDS),
+    cliffDuration: 30 * DAY_SECONDS,
+    recipients: [userAddress],
+    amounts: [parseEther('100000')],
+  })
+  .withMigration({ type: 'uniswapV2' })
+  .withUserAddress(userAddress)
+  .build();
+```
+
+DopplerERC20V1 token data includes schedule vesting and balance-limit controls, but it intentionally omits `yearlyMintRate`; DopplerERC20V1 tokens do not expose `mintInflation` or mint-rate update helpers.
+
+```typescript
+const token = sdk.getDopplerERC20V1(tokenAddress);
+const scheduleCount = await token.getVestingScheduleCount();
+
+for (let scheduleId = 0n; scheduleId < scheduleCount; scheduleId++) {
+  const schedule = await token.getVestingSchedule(scheduleId);
+  const available = await token.getAvailableVestedAmountForSchedule(
+    userAddress,
+    scheduleId,
+  );
+  console.log(schedule, available);
+
+  // Release half of the available vested amount for one schedule.
+  if (available > 0n) await token.releaseSchedule(scheduleId, available / 2n);
+}
+
+console.log(await token.getMaxBalanceLimit());
+console.log(await token.getBalanceLimitEnd());
+console.log(await token.isBalanceLimitActive());
+```
+
+For a runnable example, see [examples/doppler-erc20-v1.ts](./examples/doppler-erc20-v1.ts).
+
 ### Governance Delegation (ERC20Votes)
 
 DERC20 extends OpenZeppelin's ERC20Votes. Voting power is tracked via checkpoints and only updates once an address delegates voting power (typically to itself). The SDK exposes simple read/write helpers for delegation.
@@ -1031,32 +1095,100 @@ migration: {
 }
 ```
 
-### Migrate to Uniswap V3
+### Migrate to Uniswap V4
 
 ```typescript
 migration: {
-  type: 'uniswapV3',
-  fee: 3000,        // 0.3%
-  tickSpacing: 60,  // Standard for 0.3% pools
+  type: 'uniswapV4',
+  fee: 3000,
+  tickSpacing: 60,
+  streamableFees: {
+    lockDuration: 365 * 24 * 60 * 60, // 1 year
+    beneficiaries: [
+      { beneficiary: '0x...', shares: parseEther('1') }, // 100%
+    ],
+  },
 }
 ```
 
-### Migrate to Uniswap V4
+### Migrate to Uniswap V2 with Proceeds Split + Top-ups
 
 ```typescript
 migration: {
-  type: 'uniswapV4',
+  type: 'uniswapV2Split',
+  proceedsSplit: {
+    recipient: '0xRecipient...',
+    share: parseEther('0.1'), // 10%, capped at 50%
+  },
+}
+```
+
+- 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
+
+```typescript
+migration: {
+  type: 'uniswapV4Split',
   fee: 3000,
-  tickSpacing: 60,
+  tickSpacing: 8,
   streamableFees: {
-    lockDuration: 365 * 24 * 60 * 60, // 1 year
+    lockDuration: 30 * 24 * 60 * 60,
     beneficiaries: [
-      { beneficiary: '0x...', shares: parseEther('1') }, // 100%
+      { beneficiary: '0xAirlockOwner...', shares: parseEther('0.05') },
+      { beneficiary: '0xTeam...', shares: parseEther('0.95') },
     ],
   },
+  proceedsSplit: {
+    recipient: '0xRecipient...',
+    share: parseEther('0.1'),
+  },
 }
 ```
 
+- `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
@@ -1266,7 +1398,7 @@ const builder = new StaticAuctionBuilder(base.id)
   })
   .poolByTicks({ startTick: -92100, endTick: -69060, fee: 3000 })
   .withGovernance({ type: 'default' })
-  .withMigration({ type: 'uniswapV3', fee: 3000, tickSpacing: 60 })
+  .withMigration({ type: 'uniswapV4', fee: 3000, tickSpacing: 60 })
   .withUserAddress('0x...');
 
 const staticParams = builder.build();
@@ -1321,7 +1453,7 @@ import {
 import { parseEther, keccak256, encodePacked, encodeAbiParameters } from 'viem';
 import { base } from 'viem/chains';
 
-const builder = new DynamicAuctionBuilder()
+const builder = new DynamicAuctionBuilder(base.id)
   .tokenConfig({
     name: 'My Token',
     symbol: 'MTK',
@@ -1499,7 +1631,7 @@ Note: Dual-prefix mining takes significantly longer than single-prefix mining. C
 - **Prefix format**: Omit the `0x` prefix (e.g., use `'dead'` not `'0x dead'`)
 - **Case insensitive**: `'DEAD'`, `'dead'`, and `'DeAd'` are equivalent
 - **Iteration limit**: Longer prefixes require more iterations. A 4-character hex prefix takes ~65,000 attempts on average.
-- **Token variants**: Set `tokenVariant: 'doppler404'` for DN404-style tokens
+- **Token variants**: Set `tokenVariant: 'standard-v2'` or `tokenVariant: 'dopplerERC20V1'` with `v2Implementation` for clone templates, or `tokenVariant: 'doppler404'` for DN404-style tokens
 - **Salt preservation**: High-level helpers like `createStaticAuction` and `createDynamicAuction` recompute salts internally to ensure proper token ordering. To use a mined salt, call `encodeCreate*Params` and submit the transaction manually via `publicClient.writeContract`
 - **Hook flags**: The miner automatically ensures V4 hooks have the correct permission flags for Doppler operations
 
@@ -1558,7 +1690,7 @@ pnpm build
 pnpm test
 
 # Run specific test suite
-pnpm test airlock-whitelisting
+pnpm test:whitelisting
 
 # Run tests in watch mode
 pnpm test:watch
@@ -1571,22 +1703,31 @@ pnpm dev
 
 The SDK includes comprehensive tests covering:
 
-- **Airlock Whitelisting**: Verifies that all modules are properly whitelisted on deployed Airlock contracts across all chains
+- **Airlock Whitelisting**: Verifies that all modules are properly whitelisted on Ethereum Mainnet, Monad Mainnet, Base Mainnet, and Base Sepolia
 - **Multicurve Functionality**: Tests multicurve auction creation and quoting
 - **Token Address Mining**: Tests for generating optimized token addresses
 
-See [`test/README.md`](./test/README.md) for detailed testing documentation.
-
 To run whitelisting tests:
 
 ```bash
-# Uses default public RPCs
-pnpm test airlock-whitelisting
+# Canonical whitelist audit
+pnpm test:whitelisting
 
-# Or with Alchemy (faster and more reliable)
-ALCHEMY_API_KEY=your_key_here pnpm test airlock-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,monad-mainnet pnpm test:whitelisting
 ```
 
+The whitelisting suite is scoped to the release-audit chains: Ethereum Mainnet, Monad Mainnet, Base Mainnet, and Base Sepolia.
+
+Whitelisting test RPC priority is:
+
+1. Chain-specific RPC URL env var (`ETH_MAINNET_RPC_URL`, `BASE_RPC_URL`, `BASE_SEPOLIA_RPC_URL`, `MONAD_MAINNET_RPC_URL`)
+2. `ALCHEMY_API_KEY` fallback for supported Alchemy networks, including Monad Mainnet
+3. Public/default RPC URL
+
 To run fork tests (Anvil):
 
 ```bash