@whetstone-research/doppler-sdk 0.0.1-alpha.2 → 0.0.1-alpha.20

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

@@ -59,42 +59,20 @@ const sdk = new DopplerSDK({
 Static auctions use Uniswap V3 pools with concentrated liquidity in a fixed price range. They're ideal for simple, predictable price discovery.
 
 ```typescript
-const result = await sdk.factory.createStaticAuction({
-  token: {
-    name: 'My Token',
-    symbol: 'MTK',
-    tokenURI: 'https://example.com/metadata.json',
-    totalSupply: parseEther('1000000000'), // 1 billion tokens
-  },
-  sale: {
-    numTokensToSell: parseEther('900000000'), // Sell 900 million
-    numeraire: '0x...', // WETH address
-  },
-  pool: {
-    startTick: -92103, // ~0.0001 ETH per token
-    endTick: -69080,   // ~0.001 ETH per token
-    fee: 10000,        // 1%
-    numPositions: 15,  // Number of liquidity positions
-  },
-  vesting: {
-    duration: BigInt(365 * 24 * 60 * 60), // 1 year
-    recipients: [
-      { address: '0x...', amount: parseEther('50000000') }, // 50M tokens
-      { address: '0x...', amount: parseEther('50000000') }, // 50M tokens
-    ],
-  },
-  migration: {
-    type: 'uniswapV2', // Migrate to V2 after auction
-  },
-  governance: {
-    maxShareToBeSold: parseEther('0.35'), // 35% max
-    yearlyMintRate: parseEther('0.02'),   // 2% annual
-  },
-  userAddress: '0x...', // Your address
-});
-
-console.log('Pool address:', result.poolAddress);
-console.log('Token address:', result.tokenAddress);
+import { StaticAuctionBuilder } from '@whetstone-research/doppler-sdk'
+
+const params = new StaticAuctionBuilder()
+  .tokenConfig({ name: 'My Token', symbol: 'MTK', tokenURI: 'https://example.com/metadata.json' })
+  .saleConfig({ initialSupply: parseEther('1000000000'), numTokensToSell: parseEther('900000000'), numeraire: '0x...' })
+  .poolByTicks({ startTick: -92103, endTick: -69080, fee: 10000, numPositions: 15 })
+  .withVesting({ duration: BigInt(365 * 24 * 60 * 60) })
+  .withMigration({ type: 'uniswapV2' })
+  .withUserAddress('0x...')
+  .build()
+
+const result = await sdk.factory.createStaticAuction(params)
+console.log('Pool address:', result.poolAddress)
+console.log('Token address:', result.tokenAddress)
 ```
 
 ### Dynamic Auction (Dutch Auction)
@@ -102,55 +80,92 @@ console.log('Token address:', result.tokenAddress);
 Dynamic auctions use Uniswap V4 hooks to implement gradual Dutch auctions where the price moves over time.
 
 ```typescript
-const result = await sdk.factory.createDynamicAuction({
-  token: {
-    name: 'My Token',
-    symbol: 'MTK',
-    tokenURI: 'https://example.com/metadata.json',
-    totalSupply: parseEther('1000000'), // 1M tokens
-  },
-  sale: {
-    numTokensToSell: parseEther('900000'), // Sell 900k
-    numeraire: '0x...', // WETH address
-    minProceeds: parseEther('100'), // Min 100 ETH
-    maxProceeds: parseEther('1000'), // Max 1000 ETH
-  },
-  auction: {
-    duration: 7, // 7 days
-    epochLength: 3600, // 1 hour epochs
-    startTick: -92103, // ~0.0001 ETH per token
-    endTick: -69080,   // ~0.01 ETH per token
-    gamma: parseEther('0.998'), // Price decrease rate
-    numPdSlugs: 5, // Price discovery slugs
-  },
-  pool: {
-    fee: 3000,       // 0.3%
-    tickSpacing: 60, // Standard for 0.3% pools
-  },
-  vesting: {
-    duration: BigInt(365 * 24 * 60 * 60), // 1 year
-    recipients: [
-      { address: '0x...', amount: parseEther('50000') },
-      { address: '0x...', amount: parseEther('50000') },
-    ],
-  },
-  migration: {
+import { DynamicAuctionBuilder } from '@whetstone-research/doppler-sdk'
+
+const params = new DynamicAuctionBuilder()
+  .tokenConfig({ name: 'My Token', symbol: 'MTK', tokenURI: 'https://example.com/metadata.json' })
+  .saleConfig({ initialSupply: parseEther('1000000'), numTokensToSell: parseEther('900000'), numeraire: '0x...' })
+  .poolConfig({ fee: 3000, tickSpacing: 60 })
+  .auctionByTicks({
+    durationDays: 7,
+    epochLength: 3600,
+    startTick: -92103,
+    endTick: -69080,
+    minProceeds: parseEther('100'),
+    maxProceeds: parseEther('1000'),
+    numPdSlugs: 5,
+  })
+  .withVesting({ duration: BigInt(365 * 24 * 60 * 60) })
+  .withMigration({
     type: 'uniswapV4',
     fee: 3000,
     tickSpacing: 60,
     streamableFees: {
-      lockDuration: 365 * 24 * 60 * 60, // 1 year
+      lockDuration: 365 * 24 * 60 * 60,
       beneficiaries: [
-        { address: '0x...', percentage: 5000 }, // 50%
-        { address: '0x...', percentage: 5000 }, // 50%
+        { address: '0x...', percentage: 5000 },
+        { address: '0x...', percentage: 5000 },
       ],
     },
-  },
-  userAddress: '0x...',
-});
+  })
+  // 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()
+
+const result = await sdk.factory.createDynamicAuction(params)
+console.log('Hook address:', result.hookAddress)
+console.log('Token address:', result.tokenAddress)
+```
+
+#### Transaction gas override
+- You can pass a gas limit to factory create calls via the `gas` field on `CreateStaticAuctionParams`/`CreateDynamicAuctionParams`.
+- If omitted, the SDK uses a default gas limit of 13,500,000 for the `create()` transaction.
+
+
 
-console.log('Hook address:', result.hookAddress);
-console.log('Token address:', result.tokenAddress);
+### 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.
+
+```typescript
+import { StaticAuctionBuilder, DynamicAuctionBuilder } from '@whetstone-research/doppler-sdk'
+import { parseEther } from 'viem'
+
+// Dynamic auction via builder
+const dynamicParams = new DynamicAuctionBuilder()
+  .tokenConfig({ name: 'My Token', symbol: 'MTK', tokenURI: 'https://example.com/metadata.json' })
+  .saleConfig({ initialSupply: parseEther('1000000'), numTokensToSell: parseEther('500000'), numeraire: wethAddress })
+  .poolConfig({ fee: 3000, tickSpacing: 60 })
+  .auctionByPriceRange({
+    priceRange: { startPrice: 0.0001, endPrice: 0.001 },
+    minProceeds: parseEther('100'),
+    maxProceeds: parseEther('1000'),
+  })
+  .withMigration({ type: 'uniswapV2' })
+  .withUserAddress('0x...')
+  .build()
+
+const dyn = await sdk.factory.createDynamicAuction(dynamicParams)
+
+// Static auction via builder
+const staticParams = new StaticAuctionBuilder()
+  .tokenConfig({ name: 'My Token', symbol: 'MTK', tokenURI: 'https://example.com/metadata.json' })
+  .saleConfig({ initialSupply: parseEther('1000000000'), numTokensToSell: parseEther('900000000'), numeraire: wethAddress })
+  .poolByPriceRange({ priceRange: { startPrice: 0.0001, endPrice: 0.001 }, fee: 3000 })
+  .withMigration({ type: 'uniswapV2' })
+  .withUserAddress('0x...')
+  .build()
+
+const stat = await sdk.factory.createStaticAuction(staticParams)
 ```
 
 ### Simplified Creation with Defaults
@@ -158,52 +173,33 @@ console.log('Token address:', result.tokenAddress);
 The SDK intelligently applies defaults when parameters are omitted. Here are examples with minimal configuration:
 
 ```typescript
-// Minimal static auction
-const result = await sdk.factory.createStaticAuction({
-  token: {
-    name: 'My Token',
-    symbol: 'MTK',
-    tokenURI: 'https://example.com/metadata.json',
-    // totalSupply defaults to 1 billion
-  },
-  sale: {
-    // numTokensToSell defaults to 90% of total supply
-    numeraire: '0x...', // WETH address (required)
-  },
-  pool: {
-    // Defaults: fee=10000 (1%), numPositions=15
-    // Start/end ticks calculated from reasonable price range
-  },
-  migration: {
-    type: 'uniswapV2', // Required
-  },
-  userAddress: '0x...', // Required
-});
-
-// Minimal dynamic auction
-const result = await sdk.factory.createDynamicAuction({
-  token: {
-    name: 'My Token',
-    symbol: 'MTK',
-    tokenURI: 'https://example.com/metadata.json',
-  },
-  sale: {
-    numeraire: '0x...', // WETH address
+// Minimal static auction via builder
+const staticMinimal = new StaticAuctionBuilder()
+  .tokenConfig({ name: 'My Token', symbol: 'MTK', tokenURI: 'https://example.com/metadata.json' })
+  .saleConfig({ initialSupply: parseEther('1000000000'), numTokensToSell: parseEther('900000000'), numeraire: '0x...' })
+  .poolByTicks({ fee: 10000 }) // uses default tick range and numPositions
+  .withMigration({ type: 'uniswapV2' })
+  .withUserAddress('0x...')
+  .build()
+
+const staticResult = await sdk.factory.createStaticAuction(staticMinimal)
+
+// Minimal dynamic auction via builder
+const dynamicMinimal = new DynamicAuctionBuilder()
+  .tokenConfig({ name: 'My Token', symbol: 'MTK', tokenURI: 'https://example.com/metadata.json' })
+  .saleConfig({ initialSupply: parseEther('1000000'), numTokensToSell: parseEther('900000'), numeraire: '0x...' })
+  .poolConfig({ fee: 3000, tickSpacing: 60 })
+  .auctionByTicks({
+    startTick: -92103,
+    endTick: -69080,
     minProceeds: parseEther('100'),
     maxProceeds: parseEther('1000'),
-  },
-  auction: {
-    // Defaults: duration=7 days, epochLength=1 hour
-    // gamma and numPdSlugs auto-calculated
-  },
-  pool: {
-    // Defaults: fee=3000 (0.3%), tickSpacing=60
-  },
-  migration: {
-    type: 'uniswapV4',
-  },
-  userAddress: '0x...',
-});
+  }) // duration/epoch defaults applied; gamma computed automatically
+  .withMigration({ type: 'uniswapV4' })
+  .withUserAddress('0x...')
+  .build()
+
+const dynamicResult = await sdk.factory.createDynamicAuction(dynamicMinimal)
 ```
 
 ## Interacting with Auctions
@@ -298,6 +294,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:
@@ -429,4 +437,4 @@ Contributions are welcome! Please see our [Contributing Guide](../../CONTRIBUTIN
 
 ## License
 
-MIT License - see [LICENSE](../../LICENSE) for details.
+MIT License - see [LICENSE](../../LICENSE) for details.

package/dist/DopplerSDK.d.mts

@@ -1,21 +1,24 @@
-import { Address, PublicClient, WalletClient } from 'viem';
-import { DopplerSDKConfig, PoolInfo, HookInfo } from './types.mjs';
+import { Address, WalletClient } from 'viem';
+import { DopplerSDKConfig, PoolInfo, HookInfo, SupportedPublicClient } 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 { StaticAuctionBuilder, DynamicAuctionBuilder } 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);
+    constructor(config: DopplerSDKConfig<C>);
     /**
      * Get the factory instance for creating auctions
      */
-    get factory(): DopplerFactory;
+    get factory(): DopplerFactory<C>;
     /**
      * Get the quoter instance for price queries
      */
@@ -40,15 +43,23 @@ 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>;
     /**
      * Get the current chain ID
      */
-    getChainId(): number;
+    getChainId(): C;
     /**
      * Get the underlying clients
      */
     getClients(): {
-        publicClient: PublicClient;
+        publicClient: SupportedPublicClient;
         walletClient?: WalletClient;
     };
 }

package/dist/DopplerSDK.d.ts

@@ -1,21 +1,24 @@
-import { Address, PublicClient, WalletClient } from 'viem';
-import { DopplerSDKConfig, PoolInfo, HookInfo } from './types.js';
+import { Address, WalletClient } from 'viem';
+import { DopplerSDKConfig, PoolInfo, HookInfo, SupportedPublicClient } 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 { StaticAuctionBuilder, DynamicAuctionBuilder } 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);
+    constructor(config: DopplerSDKConfig<C>);
     /**
      * Get the factory instance for creating auctions
      */
-    get factory(): DopplerFactory;
+    get factory(): DopplerFactory<C>;
     /**
      * Get the quoter instance for price queries
      */
@@ -40,15 +43,23 @@ 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>;
     /**
      * Get the current chain ID
      */
-    getChainId(): number;
+    getChainId(): C;
     /**
      * Get the underlying clients
      */
     getClients(): {
-        publicClient: PublicClient;
+        publicClient: SupportedPublicClient;
         walletClient?: WalletClient;
     };
 }

package/dist/DopplerSDK.js

@@ -1,23 +1,23 @@
 'use strict';
 
-var chunk5B7IYSVK_js = require('./chunk-5B7IYSVK.js');
-require('./chunk-P7CHGWY7.js');
-require('./chunk-SIVXK7WY.js');
+var chunk4ES2NJPN_js = require('./chunk-4ES2NJPN.js');
 require('./chunk-KRN3ROUE.js');
-require('./chunk-DLL6MEJA.js');
-require('./chunk-R3YCKIM4.js');
-require('./chunk-IGLVXIHA.js');
-require('./chunk-K7BWQVAX.js');
+require('./chunk-NF24E36D.js');
+require('./chunk-EJDXU66H.js');
+require('./chunk-P7CHGWY7.js');
+require('./chunk-KZ72ODWA.js');
+require('./chunk-WORNH3RO.js');
+require('./chunk-ROUB6IPW.js');
 require('./chunk-ER42VG7H.js');
-require('./chunk-JHKPKTCV.js');
-require('./chunk-OMN7RXR4.js');
-require('./chunk-KEXKKQVW.js');
+require('./chunk-W3XY463N.js');
+require('./chunk-KEAGCODJ.js');
+require('./chunk-CIRZKWLL.js');
 
 
 
 Object.defineProperty(exports, "DopplerSDK", {
   enumerable: true,
-  get: function () { return chunk5B7IYSVK_js.DopplerSDK; }
+  get: function () { return chunk4ES2NJPN_js.DopplerSDK; }
 });
 //# sourceMappingURL=DopplerSDK.js.map
 //# sourceMappingURL=DopplerSDK.js.map

package/dist/DopplerSDK.mjs

@@ -1,14 +1,14 @@
-export { DopplerSDK } from './chunk-BYR4WWCZ.mjs';
-import './chunk-QSQGLWNY.mjs';
-import './chunk-BYK425DD.mjs';
+export { DopplerSDK } from './chunk-T536EW7K.mjs';
 import './chunk-AZLFJNTG.mjs';
-import './chunk-6REZA4TU.mjs';
-import './chunk-O55NMSZK.mjs';
-import './chunk-IPW2I4JJ.mjs';
-import './chunk-2LPOXGKT.mjs';
+import './chunk-CTWOTZE3.mjs';
+import './chunk-W6T5VJKW.mjs';
+import './chunk-QSQGLWNY.mjs';
+import './chunk-4HLZEUQL.mjs';
+import './chunk-UNVNLHH6.mjs';
+import './chunk-O2GNGHWO.mjs';
 import './chunk-T644D54P.mjs';
-import './chunk-XJGF77WN.mjs';
-import './chunk-NDWBEGEN.mjs';
-import './chunk-LOROXNH3.mjs';
+import './chunk-4YUXZRXO.mjs';
+import './chunk-IEOMMR3F.mjs';
+import './chunk-7W72MFJO.mjs';
 //# sourceMappingURL=DopplerSDK.mjs.map
 //# sourceMappingURL=DopplerSDK.mjs.map