@whetstone-research/doppler-sdk 1.0.21 → 1.0.23

package/README.md

@@ -10,6 +10,7 @@ The Doppler SDK exposes network-specific entrypoints for creating, managing, and
 
 - **EVM Auctions**: Static auctions, dynamic auctions, and multicurve launches across Uniswap V3/V4 paths
 - **EVM Migration Paths**: Support for V2, V2 split, V4, V4 split, DopplerHook, and no-op migration
+- **EVM Multicurve Fees**: Single-token and batched pending-fee previews plus beneficiary fee claiming for locked multicurve pools
 - **Solana Launches**: Initializer, CPMM, migrator, hook, oracle, and Token-2022-compatible instruction helpers
 - **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
@@ -554,7 +555,7 @@ For decay pools, `pool.fee` is always the terminal fee (`endFee`) of the schedul
 When you want fee revenue to flow to specific addresses without migrating liquidity after the auction, use lockable beneficiaries with NoOp migration:
 
 ```typescript
-import { WAD } from '@whetstone-research/doppler-sdk/evm';
+import { MulticurveFees, WAD } from '@whetstone-research/doppler-sdk/evm';
 
 // Define beneficiaries with shares that sum to WAD (1e18 = 100%)
 // IMPORTANT: Protocol owner must be included with at least 5% shares
@@ -603,21 +604,30 @@ const result = await sdk.factory.createMulticurve(params);
 const assetAddress = result.tokenAddress; // SAVE THIS - you'll need it to collect fees!
 console.log('Asset address:', assetAddress);
 
-// Later, to collect fees (works before and after migration):
+// Later, to preview and claim fees while the pool is locked:
 // const pool = await sdk.getMulticurvePool(assetAddress)
+// const pending = await pool.getPendingFees('0xBeneficiary...')
 // await pool.collectFees()
+//
+// To preview many locked multicurve tokens at once:
+// const fees = new MulticurveFees(publicClient, walletClient, tokenAddresses)
+// const pendingByToken = await fees.getPendingFees('0xBeneficiary...')
 ```
 
 **Important Notes:**
 
 - Set `fee` > 0 (e.g., 3000 for 0.3%) to accumulate trading fees for beneficiaries
 - **Save the asset address** (token address) returned from creation - you need it to collect fees later
-- Beneficiaries receive fees proportional to their shares when `collectFees()` is called
+- Use `MulticurvePool.getPendingFees(beneficiary)` to preview a beneficiary's claimable token0/token1 fees for one pool
+- Use `MulticurveFees.getPendingFees(beneficiary)` to preview pending fees for multiple tokens with one multicall by default
+- Pass `tokenBatchSize` to `MulticurveFees` when an RPC provider needs large pending-fee previews split into smaller token batches
+- `collectFees()` claims a payout for the calling account only when the caller is a configured beneficiary
 - Pool enters "Locked" status (status = 2) and liquidity cannot be migrated
 - Beneficiaries are immutable and set at pool creation time
 - The SDK automatically handles PoolKey construction and PoolId computation for you
 
 See [examples/multicurve-lockable-beneficiaries.ts](./examples/multicurve-lockable-beneficiaries.ts) for a complete example.
+See [docs/multicurve-fees.md](./docs/multicurve-fees.md) for single-token and multi-token pending-fee previews, claiming, batching, and current migrated-launch limitations.
 
 #### Transaction gas override
 
@@ -773,9 +783,12 @@ const currentEpoch = await auction.getCurrentEpoch();
 
 ### Multicurve Pool Interactions
 
-Multicurve pools support fee collection and distribution to beneficiaries when configured with `lockableBeneficiaries`.
+Multicurve pools support fee collection and beneficiary claims when configured
+with `pool.beneficiaries` and no-op migration.
 
 ```typescript
+import { MulticurveFees } from '@whetstone-research/doppler-sdk/evm';
+
 // Get a multicurve pool instance using the asset address (token address)
 const pool = await sdk.getMulticurvePool(assetAddress);
 
@@ -795,15 +808,37 @@ if (feeSchedule) {
   console.log('Fee schedule:', feeSchedule);
 }
 
-// Collect and distribute fees to beneficiaries
-// This can be called by anyone, but only beneficiaries receive fees
+// Preview pending fees for a beneficiary. This is a read-only call.
+const pendingFees = await pool.getPendingFees(beneficiaryAddress);
+console.log('Pending fees (token0):', pendingFees.fees0);
+console.log('Pending fees (token1):', pendingFees.fees1);
+
+// Preview pending fees for multiple launched tokens. By default this builds
+// one multicall for all requested tokens.
+const multicurveFees = new MulticurveFees(
+  publicClient,
+  walletClient,
+  [assetAddress, anotherAssetAddress],
+  { tokenBatchSize: 25 },
+);
+const pendingFeesByToken =
+  await multicurveFees.getPendingFees(beneficiaryAddress);
+for (const pendingFees of pendingFeesByToken) {
+  console.log('Asset:', pendingFees.tokenAddress);
+  console.log('Pending fees (token0):', pendingFees.fees0);
+  console.log('Pending fees (token1):', pendingFees.fees1);
+}
+
+// Claim fees from a beneficiary wallet while the pool is locked.
+// Any account can call collectFees(), but only a configured beneficiary caller
+// receives their pending share.
 const { fees0, fees1, transactionHash } = await pool.collectFees();
 console.log('Fees collected (token0):', fees0);
 console.log('Fees collected (token1):', fees1);
 console.log('Transaction:', transactionHash);
 
 // Get token addresses
-const tokenAddress = await pool.getTokenAddress();
+const tokenAddress = pool.getTokenAddress();
 const numeraireAddress = await pool.getNumeraireAddress();
 ```
 
@@ -812,33 +847,35 @@ const numeraireAddress = await pool.getNumeraireAddress();
 The SDK handles the complexity of fee collection by:
 
 1. **Retrieving pool configuration** from the multicurve initializer contract
-2. **Detecting migration status** and, if the pool has migrated, resolving the shared `StreamableFeesLockerV2`
-   address via the multicurve migrator (no manual lookup required)
+2. **Detecting pool status** so only locked initializer-side pools proceed
 3. **Computing the PoolId** from the PoolKey using `keccak256(abi.encode(poolKey))`
-4. **Calling the correct contract** (initializer while locked, locker after migration) with the computed PoolId
-5. **Distributing fees** proportionally to all configured beneficiaries
+4. **Previewing pending fees** with a Multicall3 aggregate that simulates collection and reads beneficiary share/checkpoint data
+5. **Calling the initializer** with the computed PoolId when a beneficiary claims via `collectFees()`
 
 **Important Notes:**
 
 - Fees accumulate from swap activity on the pool (only if fee tier > 0)
-- Anyone can call `collectFees()`, but fees are distributed to beneficiaries only
-- Fees are automatically split according to configured beneficiary shares
-- The function returns the total amount collected for both tokens in the pair
-- Works exclusively with pools created using `lockableBeneficiaries` in the multicurve configuration
+- `MulticurvePool.getPendingFees(beneficiary)` returns the beneficiary's pending share for both tokens in one pair
+- `MulticurveFees.getPendingFees(beneficiary)` returns pending fees for each requested token and uses one multicall by default
+- `MulticurveFees` accepts `tokenBatchSize` when large token lists need to be split into smaller multicalls
+- `collectFees()` sends a transaction; the caller needs a wallet client
+- Anyone can call `collectFees()`, but only a configured beneficiary caller receives their pending share
+- The `collectFees()` return values are the newly collected pool fees, not necessarily the caller's beneficiary payout
+- Works exclusively with initializer-side locked pools created with `pool.beneficiaries` and no-op migration
 - Pools in "Locked" status (status = 2) use the multicurve initializer for collection
-- Pools in "Exited" status (status = 3) automatically stream fees through `StreamableFeesLockerV2`; the SDK
-  resolves the locker address and stream data for you
+- Pools in "Exited" status (status = 3) are migrated and are not currently supported by `MulticurvePool.getPendingFees()` or `MulticurvePool.collectFees()`
 - `getFeeSchedule()` returns decay schedule details only for dynamic-fee multicurve pools, otherwise `null`
 - Beneficiaries must be configured at pool creation time and cannot be changed
 
 **Common Use Cases:**
 
+- Preview pending fees for a portfolio or paginated token list
 - Set up periodic fee collection (e.g., daily or weekly)
 - Integrate with a bot that automatically collects fees when threshold is reached
 - Allow any beneficiary to trigger collection after significant trading activity
 - Monitor swap events to determine optimal collection timing
 
-See [examples/multicurve-collect-fees.ts](./examples/multicurve-collect-fees.ts) for a complete example.
+See [docs/multicurve-fees.md](./docs/multicurve-fees.md) for a focused guide, [examples/multicurve-get-pending-fees.ts](./examples/multicurve-get-pending-fees.ts) for batched previews, and [examples/multicurve-collect-fees.ts](./examples/multicurve-collect-fees.ts) for claims.
 
 ## Token Management