@whetstone-research/doppler-sdk 0.0.1-alpha.4 → 0.0.1-alpha.41

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Whetstone Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,6 +10,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
 - **Token Management**: Built-in support for DERC20 tokens with vesting
 - **Type Safety**: Full TypeScript support with discriminated unions
@@ -108,6 +109,16 @@ const params = new DynamicAuctionBuilder()
       ],
     },
   })
+  // Optional: override module addresses instead of chain defaults
+  .withAirlock('0xAirlock...')
+  .withPoolManager('0xPoolMgr...')
+  .withDopplerDeployer('0xDeployer...')
+  .withTokenFactory('0xFactory...')
+  .withV4Initializer('0xInitializer...')
+  .withGovernanceFactory('0xGovFactory...') // used for both standard and no‑op governance
+  // .withV2Migrator('0xV2Migrator...')
+  // .withV3Migrator('0xV3Migrator...')
+  // .withV4Migrator('0xV4Migrator...')
   .withUserAddress('0x...')
   .build()
 
@@ -116,6 +127,54 @@ console.log('Hook address:', result.hookAddress)
 console.log('Token address:', result.tokenAddress)
 ```
 
+### Multicurve Auction (V4 Multicurve Initializer)
+
+Multicurve auctions use a Uniswap V4-style initializer that seeds liquidity across multiple curves in a single pool. This enables richer distributions and can be combined with any supported migration path (V2, V3, or V4).
+
+```typescript
+import { MulticurveBuilder } from '@whetstone-research/doppler-sdk'
+import { parseEther } from 'viem'
+
+const params = new MulticurveBuilder(base.id)
+  .tokenConfig({ name: 'My Token', symbol: 'MTK', tokenURI: 'https://example.com/metadata.json' })
+  .saleConfig({ initialSupply: parseEther('1000000'), numTokensToSell: parseEther('900000'), numeraire: '0x...' })
+  .withMulticurveAuction({
+    fee: 0,
+    tickSpacing: 8,
+    curves: [
+      { tickLower: 0, tickUpper: 240000, numPositions: 10, shares: parseEther('0.5') },
+      { tickLower: 16000, tickUpper: 240000, numPositions: 10, shares: parseEther('0.5') },
+    ],
+    // Optional: lock fee revenue to beneficiaries (shares in WAD)
+    lockableBeneficiaries: [
+      { beneficiary: '0x...', shares: parseEther('0.05') },
+    ],
+  })
+  .withGovernance({ type: 'default' })
+  // Choose a migration path (V2, V3, or V4). Example uses V2
+  .withMigration({ type: 'uniswapV2' })
+  // Optional address overrides if not provided by chain config
+  // .withV4MulticurveInitializer('0xInitializer...')
+  .withUserAddress('0x...')
+  .build()
+
+const result = await sdk.factory.createMulticurve(params)
+console.log('Pool address:', result.poolAddress)
+console.log('Token address:', result.tokenAddress)
+
+// Or simulate to preview addresses and gas without sending a transaction
+const { asset, pool, gasEstimate } = await sdk.factory.simulateCreateMulticurve(params)
+console.log('Estimated gas:', gasEstimate?.toString() ?? 'not available')
+```
+
+#### Transaction gas override
+- You can pass a gas limit to factory create calls via the `gas` field on `CreateStaticAuctionParams` / `CreateDynamicAuctionParams` / `CreateMulticurveParams`.
+- If omitted, the SDK uses the simulation's gas estimate when available, falling back to 13,500,000 gas for the `create()` transaction.
+- `simulateCreate*` helpers now return `gasEstimate` so you can tune overrides before sending.
+- Builders expose `.withGasLimit(gas: bigint)` so you can set overrides fluently.
+
+
+
 ### Builder Pattern (Recommended)
 
 Prefer using the builders to construct `CreateStaticAuctionParams` and `CreateDynamicAuctionParams` fluently and safely. Builders apply sensible defaults and can compute ticks and gamma for you.
@@ -229,9 +288,8 @@ const currentEpoch = await auction.getCurrentEpoch();
 The SDK includes full support for DERC20 tokens with vesting functionality:
 
 ```typescript
-import { Derc20 } from '@whetstone-research/doppler-sdk';
-
-const token = new Derc20(publicClient, walletClient, tokenAddress);
+// Get a DERC20 instance from the SDK (uses its clients)
+const token = sdk.getDerc20(tokenAddress);
 
 // Read token information
 const name = await token.getName();
@@ -243,10 +301,100 @@ const vestingData = await token.getVestingData(address);
 console.log('Total vested:', vestingData.totalAmount);
 console.log('Released:', vestingData.releasedAmount);
 
-// Release vested tokens
-await token.release(amountToRelease);
+// Release currently available vested tokens
+await token.release();
 ```
 
+Alternatively, you can instantiate directly if needed:
+```typescript
+import { Derc20 } from '@whetstone-research/doppler-sdk'
+const tokenDirect = new Derc20(publicClient, walletClient, tokenAddress)
+```
+
+### 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.
+
+Basics:
+```ts
+import { Derc20 } from '@whetstone-research/doppler-sdk'
+
+const token = sdk.getDerc20(tokenAddress)
+
+// Read: who an account delegates to, and current voting power
+const currentDelegate = await token.getDelegates(userAddress)
+const votes = await token.getVotes(userAddress)
+
+// Self‑delegate to activate vote tracking
+await token.delegate(userAddress)
+
+// Or delegate to another address
+await token.delegate('0xDelegatee...')
+```
+
+Historical votes:
+```ts
+// OZ v5 uses timepoints (block numbers for block‑based clocks)
+const blockNumber = await publicClient.getBlockNumber()
+const pastVotes = await token.getPastVotes(userAddress, blockNumber - 1n)
+```
+
+Signature‑based delegation (delegateBySig):
+```ts
+// Signs an EIP‑712 message and submits a transaction calling delegateBySig
+// Note: This still submits a transaction from the connected wallet.
+const expiry = BigInt(Math.floor(Date.now() / 1000) + 3600) // 1h
+await token.delegateBySig('0xDelegatee...', expiry)
+```
+
+Advanced: gasless delegation via relayer
+- The token supports `delegateBySig(delegatee, nonce, expiry, v, r, s)`. A relayer can submit this on behalf of the user if it holds ETH for gas.
+- To do this, have the user sign typed data, then send the signature to your backend that calls the contract.
+
+Client (sign only):
+```ts
+const [nonce, name] = await Promise.all([
+  publicClient.readContract({ address: tokenAddress, abi: derc20Abi, functionName: 'nonces', args: [userAddress] }),
+  token.getName(),
+])
+const chainId = await publicClient.getChainId()
+const domain = { name, version: '1', chainId, verifyingContract: tokenAddress } as const
+const types = { Delegation: [
+  { name: 'delegatee', type: 'address' },
+  { name: 'nonce', type: 'uint256' },
+  { name: 'expiry', type: 'uint256' },
+] } as const
+const message = { delegatee: '0xDelegatee...', nonce, expiry } as const
+
+const signature = await walletClient.signTypedData({
+  domain, types, primaryType: 'Delegation', message, account: userAddress,
+})
+// POST { signature, delegatee, nonce, expiry } to your relayer
+```
+
+Relayer (submit tx):
+```ts
+function splitSig(sig: `0x${string}`) {
+  const r = `0x${sig.slice(2, 66)}` as `0x${string}`
+  const s = `0x${sig.slice(66, 130)}` as `0x${string}`
+  let v = parseInt(sig.slice(130, 132), 16); if (v < 27) v += 27
+  return { v, r, s }
+}
+
+const { v, r, s } = splitSig(signature)
+await relayerWallet.writeContract({
+  address: tokenAddress,
+  abi: derc20Abi,
+  functionName: 'delegateBySig',
+  args: ['0xDelegatee...', nonce, expiry, v, r, s],
+})
+```
+
+Notes
+- Users must delegate (even to themselves) before votes appear in `getVotes`.
+- `getPastVotes`/`getPastTotalSupply` expect a timepoint; for block‑based clocks, pass a block number that has already been mined.
+- Events you may track: `DelegateChanged` and `DelegateVotesChanged` for live updates.
+
 ### Native ETH
 
 The SDK also provides an ETH wrapper with ERC20-like interface:
@@ -278,6 +426,18 @@ console.log('Expected output:', quote.amountOut);
 console.log('Price after swap:', quote.sqrtPriceX96After);
 ```
 
+## Atomic Create + Pre‑Buy (Bundle)
+
+For static auctions, you can create the pool and execute a pre‑buy in a single transaction via the Bundler.
+
+High‑level flow:
+- Simulate create to get `CreateParams` and the predicted token address
+- Decide `amountOut` to buy, simulate `amountIn` with `simulateBundleExactOutput(...)`
+- Build Universal Router commands (e.g., via `doppler-router`)
+- Call `factory.bundle(createParams, commands, inputs, { value })`
+
+See docs/quotes-and-swaps.md for a full example.
+
 ## Migration Configuration
 
 The SDK supports flexible migration paths after auction completion:
@@ -313,12 +473,67 @@ migration: {
 }
 ```
 
+To make configuring the first beneficiary simpler, the SDK now exposes helpers for resolving the
+airlock owner and creating the default 5% entry:
+
+```ts
+import { DopplerSDK, createAirlockBeneficiary, getAirlockOwner } from '@whetstone-research/doppler-sdk'
+
+const sdk = new DopplerSDK({ publicClient, chainId })
+
+// Get the owner and construct the beneficiary entry (5% by default)
+const airlockBeneficiary = await sdk.getAirlockBeneficiary()
+
+// Or build the entry manually if you do not have an SDK instance handy
+// (airlockEntry will be equivalent to airlockBeneficiary above)
+const owner = await getAirlockOwner(publicClient)
+const airlockEntry = createAirlockBeneficiary(owner)
+
+const migration = {
+  type: 'uniswapV4' as const,
+  fee: 3000,
+  tickSpacing: 60,
+  streamableFees: {
+    lockDuration: 365 * 24 * 60 * 60,
+    beneficiaries: [
+      airlockEntry, // or airlockBeneficiary
+      { address: '0xYourDAO...', percentage: 9500 },
+    ],
+  },
+}
+```
+
+ 
+
 ## Supported Chains
 
-The SDK currently supports:
-- Base (8453)
-- Unichain (1301)
-- Ink Sepolia (763373)
+The SDK exposes runtime constants and TypeScript types for supported chains:
+
+```ts
+import {
+  CHAIN_IDS,
+  SUPPORTED_CHAIN_IDS,
+  getAddresses,
+  isSupportedChainId,
+  type SupportedChainId,
+  type ChainAddresses,
+} from '@whetstone-research/doppler-sdk'
+
+// Validate and narrow a chain ID
+function ensureSupported(id: number): SupportedChainId {
+  if (!isSupportedChainId(id)) throw new Error('Unsupported chain')
+  return id
+}
+
+const chainId = ensureSupported(CHAIN_IDS.BASE)
+const addresses: ChainAddresses = getAddresses(chainId)
+console.log('Airlock for Base:', addresses.airlock)
+
+// Iterate supported chains
+for (const id of SUPPORTED_CHAIN_IDS) {
+  console.log('Supported chain id:', id)
+}
+```
 
 ## Advanced Usage
 
@@ -363,6 +578,8 @@ class DopplerSDK {
   // Methods
   getStaticAuction(poolAddress: Address): Promise<StaticAuction>
   getDynamicAuction(hookAddress: Address): Promise<DynamicAuction>
+  // Multicurve helper
+  buildMulticurveAuction(): MulticurveBuilder
   getPoolInfo(poolAddress: Address): Promise<PoolInfo>
   getHookInfo(hookAddress: Address): Promise<HookInfo>
 }
@@ -376,6 +593,7 @@ Key types are exported for use in your applications:
 import type {
   CreateStaticAuctionParams,
   CreateDynamicAuctionParams,
+  CreateMulticurveParams,
   MigrationConfig,
   PoolInfo,
   HookInfo,

package/dist/DopplerSDK.d.mts

@@ -1,21 +1,25 @@
-import { Address, PublicClient, WalletClient } from 'viem';
-import { DopplerSDKConfig, PoolInfo, HookInfo } from './types.mjs';
+import { Address, WalletClient } from 'viem';
+import { DopplerSDKConfig, PoolInfo, HookInfo, SupportedPublicClient, BeneficiaryData } from './types.mjs';
+import { SupportedChainId } from './addresses.mjs';
 import { DopplerFactory } from './entities/DopplerFactory.mjs';
 import { StaticAuction } from './entities/auction/StaticAuction.mjs';
 import { DynamicAuction } from './entities/auction/DynamicAuction.mjs';
 import { Quoter } from './entities/quoter/Quoter.mjs';
+import { Derc20 } from './entities/token/derc20/Derc20.mjs';
+import { StaticAuctionBuilder, DynamicAuctionBuilder, MulticurveBuilder } from './builders.mjs';
+import 'viem/chains';
 
-declare class DopplerSDK {
+declare class DopplerSDK<C extends SupportedChainId = SupportedChainId> {
     private publicClient;
     private walletClient?;
-    private chainId;
+    chainId: C;
     private _factory?;
     private _quoter?;
     constructor(config: DopplerSDKConfig);
     /**
      * Get the factory instance for creating auctions
      */
-    get factory(): DopplerFactory;
+    get factory(): DopplerFactory<C>;
     /**
      * Get the quoter instance for price queries
      */
@@ -30,6 +34,11 @@ declare class DopplerSDK {
      * @param hookAddress The address of the Uniswap V4 hook
      */
     getDynamicAuction(hookAddress: Address): Promise<DynamicAuction>;
+    /**
+     * Get a DERC20 token instance for interacting with a token
+     * @param tokenAddress The address of the DERC20 token
+     */
+    getDerc20(tokenAddress: Address): Derc20;
     /**
      * Get information about a static auction pool
      * @param poolAddress The address of the pool
@@ -40,17 +49,37 @@ declare class DopplerSDK {
      * @param hookAddress The address of the hook
      */
     getHookInfo(hookAddress: Address): Promise<HookInfo>;
+    /**
+     * Create a new static auction builder
+     */
+    buildStaticAuction(): StaticAuctionBuilder<C>;
+    /**
+     * Create a new dynamic auction builder
+     */
+    buildDynamicAuction(): DynamicAuctionBuilder<C>;
+    /**
+     * Create a new multicurve (V4 initializer) auction builder
+     */
+    buildMulticurveAuction(): MulticurveBuilder<C>;
     /**
      * Get the current chain ID
      */
-    getChainId(): number;
+    getChainId(): C;
     /**
      * Get the underlying clients
      */
     getClients(): {
-        publicClient: PublicClient;
+        publicClient: SupportedPublicClient;
         walletClient?: WalletClient;
     };
+    /**
+     * Get the airlock owner address for the configured chain
+     */
+    getAirlockOwner(): Promise<Address>;
+    /**
+     * Convenience helper for building the airlock beneficiary entry with the default 5%
+     */
+    getAirlockBeneficiary(percentage?: number): Promise<BeneficiaryData>;
 }
 
 export { DopplerSDK };

package/dist/DopplerSDK.d.ts

@@ -1,21 +1,25 @@
-import { Address, PublicClient, WalletClient } from 'viem';
-import { DopplerSDKConfig, PoolInfo, HookInfo } from './types.js';
+import { Address, WalletClient } from 'viem';
+import { DopplerSDKConfig, PoolInfo, HookInfo, SupportedPublicClient, BeneficiaryData } from './types.js';
+import { SupportedChainId } from './addresses.js';
 import { DopplerFactory } from './entities/DopplerFactory.js';
 import { StaticAuction } from './entities/auction/StaticAuction.js';
 import { DynamicAuction } from './entities/auction/DynamicAuction.js';
 import { Quoter } from './entities/quoter/Quoter.js';
+import { Derc20 } from './entities/token/derc20/Derc20.js';
+import { StaticAuctionBuilder, DynamicAuctionBuilder, MulticurveBuilder } from './builders.js';
+import 'viem/chains';
 
-declare class DopplerSDK {
+declare class DopplerSDK<C extends SupportedChainId = SupportedChainId> {
     private publicClient;
     private walletClient?;
-    private chainId;
+    chainId: C;
     private _factory?;
     private _quoter?;
     constructor(config: DopplerSDKConfig);
     /**
      * Get the factory instance for creating auctions
      */
-    get factory(): DopplerFactory;
+    get factory(): DopplerFactory<C>;
     /**
      * Get the quoter instance for price queries
      */
@@ -30,6 +34,11 @@ declare class DopplerSDK {
      * @param hookAddress The address of the Uniswap V4 hook
      */
     getDynamicAuction(hookAddress: Address): Promise<DynamicAuction>;
+    /**
+     * Get a DERC20 token instance for interacting with a token
+     * @param tokenAddress The address of the DERC20 token
+     */
+    getDerc20(tokenAddress: Address): Derc20;
     /**
      * Get information about a static auction pool
      * @param poolAddress The address of the pool
@@ -40,17 +49,37 @@ declare class DopplerSDK {
      * @param hookAddress The address of the hook
      */
     getHookInfo(hookAddress: Address): Promise<HookInfo>;
+    /**
+     * Create a new static auction builder
+     */
+    buildStaticAuction(): StaticAuctionBuilder<C>;
+    /**
+     * Create a new dynamic auction builder
+     */
+    buildDynamicAuction(): DynamicAuctionBuilder<C>;
+    /**
+     * Create a new multicurve (V4 initializer) auction builder
+     */
+    buildMulticurveAuction(): MulticurveBuilder<C>;
     /**
      * Get the current chain ID
      */
-    getChainId(): number;
+    getChainId(): C;
     /**
      * Get the underlying clients
      */
     getClients(): {
-        publicClient: PublicClient;
+        publicClient: SupportedPublicClient;
         walletClient?: WalletClient;
     };
+    /**
+     * Get the airlock owner address for the configured chain
+     */
+    getAirlockOwner(): Promise<Address>;
+    /**
+     * Convenience helper for building the airlock beneficiary entry with the default 5%
+     */
+    getAirlockBeneficiary(percentage?: number): Promise<BeneficiaryData>;
 }
 
 export { DopplerSDK };

package/dist/DopplerSDK.js

@@ -1,23 +1,33 @@
 'use strict';
 
-var chunkCEBZTG4L_js = require('./chunk-CEBZTG4L.js');
+var chunkXYBEODKJ_js = require('./chunk-XYBEODKJ.js');
 require('./chunk-KRN3ROUE.js');
 require('./chunk-P7CHGWY7.js');
-require('./chunk-EMXBYWZR.js');
-require('./chunk-K7ZUQXWH.js');
-require('./chunk-376RZEND.js');
-require('./chunk-G4X44AWK.js');
-require('./chunk-UYYQHQRJ.js');
-require('./chunk-ER42VG7H.js');
-require('./chunk-JHKPKTCV.js');
-require('./chunk-OMN7RXR4.js');
-require('./chunk-KEXKKQVW.js');
+require('./chunk-OVSI43QO.js');
+require('./chunk-WQHTNL5L.js');
+require('./chunk-X3UMAHOJ.js');
+require('./chunk-C5EPBZOZ.js');
+require('./chunk-VEIVYUYF.js');
+require('./chunk-LS4TK6SX.js');
+require('./chunk-73SOFTOX.js');
+require('./chunk-V2DF2GUE.js');
+require('./chunk-ITN5EO2T.js');
+require('./chunk-4HM3ERBU.js');
+require('./chunk-KPBCG4X2.js');
+require('./chunk-XG7K4R56.js');
+require('./chunk-EFTJVQHS.js');
+require('./chunk-KMGO45KZ.js');
+require('./chunk-Z7ZKBAUR.js');
+require('./chunk-45OJGXN4.js');
+require('./chunk-YSDTNI6S.js');
+require('./chunk-E4OANJ7J.js');
+require('./chunk-CIRZKWLL.js');
 
 
 
 Object.defineProperty(exports, "DopplerSDK", {
   enumerable: true,
-  get: function () { return chunkCEBZTG4L_js.DopplerSDK; }
+  get: function () { return chunkXYBEODKJ_js.DopplerSDK; }
 });
 //# sourceMappingURL=DopplerSDK.js.map
 //# sourceMappingURL=DopplerSDK.js.map

package/dist/DopplerSDK.mjs

@@ -1,14 +1,24 @@
-export { DopplerSDK } from './chunk-THNQAO5Y.mjs';
+export { DopplerSDK } from './chunk-65BSFCKK.mjs';
 import './chunk-AZLFJNTG.mjs';
 import './chunk-QSQGLWNY.mjs';
-import './chunk-65NYPZFH.mjs';
-import './chunk-IZH2Z3KC.mjs';
-import './chunk-JSJSYBHG.mjs';
-import './chunk-677KDMY7.mjs';
-import './chunk-DEFXRGPD.mjs';
-import './chunk-T644D54P.mjs';
-import './chunk-XJGF77WN.mjs';
-import './chunk-NDWBEGEN.mjs';
-import './chunk-LOROXNH3.mjs';
+import './chunk-AINJQVZP.mjs';
+import './chunk-FOESYJP3.mjs';
+import './chunk-RV64M4Q6.mjs';
+import './chunk-O2QILOKJ.mjs';
+import './chunk-XNMXN5SZ.mjs';
+import './chunk-PAPXGPJB.mjs';
+import './chunk-44PYMMCH.mjs';
+import './chunk-HGLO5LDS.mjs';
+import './chunk-ADGPGPA3.mjs';
+import './chunk-ECD4FV3A.mjs';
+import './chunk-AYPP5JEQ.mjs';
+import './chunk-4K5GBNQV.mjs';
+import './chunk-WTKJ2OCS.mjs';
+import './chunk-I5K7TMG3.mjs';
+import './chunk-RAFSIZDB.mjs';
+import './chunk-F7U377SD.mjs';
+import './chunk-H6JN7KCJ.mjs';
+import './chunk-YCLVZS7E.mjs';
+import './chunk-7W72MFJO.mjs';
 //# sourceMappingURL=DopplerSDK.mjs.map
 //# sourceMappingURL=DopplerSDK.mjs.map