@whetstone-research/doppler-sdk 0.0.1-alpha.1

package/README.md

@@ -0,0 +1,432 @@
+# Doppler SDK
+
+A unified TypeScript SDK for interacting with the Doppler Protocol - enabling fair token launches through Dutch auction mechanisms on Uniswap.
+
+## Overview
+
+The Doppler SDK consolidates functionality from the previous `doppler-v3-sdk` and `doppler-v4-sdk` packages into a single, intuitive interface. It provides comprehensive support for creating and managing token auctions on Ethereum and EVM-compatible chains.
+
+### Key Features
+
+- **Static Auctions**: Fixed price range liquidity bootstrapping using Uniswap V3
+- **Dynamic Auctions**: Gradual Dutch auctions using Uniswap V4 hooks
+- **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
+- **Chain Support**: Works with Base, Unichain, Ink, and other EVM chains
+
+## Installation
+
+```bash
+npm install @doppler/sdk viem
+# or
+yarn add @doppler/sdk viem
+# or
+pnpm add @doppler/sdk viem
+```
+
+## Quick Start
+
+```typescript
+import { DopplerSDK } from '@doppler/sdk';
+import { createPublicClient, createWalletClient, http } from 'viem';
+import { base } from 'viem/chains';
+
+// Set up viem clients
+const publicClient = createPublicClient({
+  chain: base,
+  transport: http(),
+});
+
+const walletClient = createWalletClient({
+  chain: base,
+  transport: http(),
+  account: '0x...', // Your wallet address
+});
+
+// Initialize the SDK
+const sdk = new DopplerSDK({
+  publicClient,
+  walletClient,
+  chainId: base.id,
+});
+```
+
+## Creating Auctions
+
+### Static Auction (Fixed Price Range)
+
+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);
+```
+
+### Dynamic Auction (Dutch Auction)
+
+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: {
+    type: 'uniswapV4',
+    fee: 3000,
+    tickSpacing: 60,
+    streamableFees: {
+      lockDuration: 365 * 24 * 60 * 60, // 1 year
+      beneficiaries: [
+        { address: '0x...', percentage: 5000 }, // 50%
+        { address: '0x...', percentage: 5000 }, // 50%
+      ],
+    },
+  },
+  userAddress: '0x...',
+});
+
+console.log('Hook address:', result.hookAddress);
+console.log('Token address:', result.tokenAddress);
+```
+
+### Simplified Creation with Defaults
+
+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
+    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...',
+});
+```
+
+## Interacting with Auctions
+
+### Static Auction Interactions
+
+```typescript
+// Get a static auction instance
+const auction = await sdk.getStaticAuction(poolAddress);
+
+// Get pool information
+const poolInfo = await auction.getPoolInfo();
+console.log('Current price:', poolInfo.sqrtPriceX96);
+console.log('Liquidity:', poolInfo.liquidity);
+
+// Check if ready for migration
+const hasGraduated = await auction.hasGraduated();
+
+// Get current price
+const price = await auction.getCurrentPrice();
+```
+
+### Dynamic Auction Interactions
+
+```typescript
+// Get a dynamic auction instance
+const auction = await sdk.getDynamicAuction(hookAddress);
+
+// Get comprehensive hook information
+const hookInfo = await auction.getHookInfo();
+console.log('Total proceeds:', hookInfo.state.totalProceeds);
+console.log('Tokens sold:', hookInfo.state.totalTokensSold);
+
+// Check auction status
+const hasEndedEarly = await auction.hasEndedEarly();
+const currentEpoch = await auction.getCurrentEpoch();
+```
+
+## Token Management
+
+### DERC20 Tokens
+
+The SDK includes full support for DERC20 tokens with vesting functionality:
+
+```typescript
+import { Derc20 } from '@doppler/sdk';
+
+const token = new Derc20(publicClient, walletClient, tokenAddress);
+
+// Read token information
+const name = await token.getName();
+const symbol = await token.getSymbol();
+const balance = await token.getBalanceOf(address);
+
+// Vesting functionality
+const vestingData = await token.getVestingData(address);
+console.log('Total vested:', vestingData.totalAmount);
+console.log('Released:', vestingData.releasedAmount);
+
+// Release vested tokens
+await token.release(amountToRelease);
+```
+
+### Native ETH
+
+The SDK also provides an ETH wrapper with ERC20-like interface:
+
+```typescript
+import { Eth } from '@doppler/sdk';
+
+const eth = new Eth(publicClient, walletClient);
+const balance = await eth.getBalanceOf(address);
+```
+
+## Price Quotes
+
+Get price quotes across Uniswap V2, V3, and V4:
+
+```typescript
+const quoter = sdk.quoter;
+
+// Quote on Uniswap V3
+const quote = await quoter.quoteV3ExactInputSingle({
+  tokenIn: tokenAddress,
+  tokenOut: wethAddress,
+  amountIn: parseEther('1000'),
+  fee: 3000,
+  sqrtPriceLimitX96: 0n,
+});
+
+console.log('Expected output:', quote.amountOut);
+console.log('Price after swap:', quote.sqrtPriceX96After);
+```
+
+## Migration Configuration
+
+The SDK supports flexible migration paths after auction completion:
+
+### Migrate to Uniswap V2
+```typescript
+migration: {
+  type: 'uniswapV2',
+}
+```
+
+### Migrate to Uniswap V3
+```typescript
+migration: {
+  type: 'uniswapV3',
+  fee: 3000,        // 0.3%
+  tickSpacing: 60,  // Standard for 0.3% pools
+}
+```
+
+### Migrate to Uniswap V4
+```typescript
+migration: {
+  type: 'uniswapV4',
+  fee: 3000,
+  tickSpacing: 60,
+  streamableFees: {
+    lockDuration: 365 * 24 * 60 * 60, // 1 year
+    beneficiaries: [
+      { address: '0x...', percentage: 10000 }, // 100%
+    ],
+  },
+}
+```
+
+## Supported Chains
+
+The SDK currently supports:
+- Base (8453)
+- Unichain (1301)
+- Ink Sepolia (763373)
+
+## Advanced Usage
+
+### Custom Vesting Configuration
+
+```typescript
+vesting: {
+  duration: 180 * 24 * 60 * 60, // 180 days
+  recipients: [
+    { address: '0x...', amount: parseEther('100000') },
+    { address: '0x...', amount: parseEther('50000') },
+  ],
+}
+```
+
+### Hook Address Mining (V4)
+
+For optimal gas efficiency with Uniswap V4, you can mine hook addresses:
+
+```typescript
+// This feature is coming soon
+const minedAddress = await sdk.mineHookAddress({
+  prefix: '0x00', // Target prefix for gas optimization
+  deployer: '0x...', // Doppler deployer address
+});
+```
+
+## API Reference
+
+### DopplerSDK
+
+The main SDK class providing access to all functionality.
+
+```typescript
+class DopplerSDK {
+  constructor(config: DopplerSDKConfig)
+  
+  // Properties
+  factory: DopplerFactory
+  quoter: Quoter
+  
+  // Methods
+  getStaticAuction(poolAddress: Address): Promise<StaticAuction>
+  getDynamicAuction(hookAddress: Address): Promise<DynamicAuction>
+  getPoolInfo(poolAddress: Address): Promise<PoolInfo>
+  getHookInfo(hookAddress: Address): Promise<HookInfo>
+}
+```
+
+### Types
+
+Key types are exported for use in your applications:
+
+```typescript
+import type {
+  CreateStaticAuctionParams,
+  CreateDynamicAuctionParams,
+  MigrationConfig,
+  PoolInfo,
+  HookInfo,
+  VestingConfig,
+} from '@doppler/sdk';
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the SDK
+pnpm build
+
+# Run tests
+pnpm test
+
+# Development mode with watch
+pnpm dev
+```
+
+## Migration from Previous SDKs
+
+If you're migrating from `doppler-v3-sdk` or `doppler-v4-sdk`, see our [Migration Guide](./docs/migration-guide.md).
+
+## Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.
+
+## License
+
+MIT License - see [LICENSE](../../LICENSE) for details.

package/dist/DopplerSDK.d.mts

@@ -0,0 +1,56 @@
+import { Address, PublicClient, WalletClient } from 'viem';
+import { DopplerSDKConfig, PoolInfo, HookInfo } from './types.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';
+
+declare class DopplerSDK {
+    private publicClient;
+    private walletClient?;
+    private chainId;
+    private _factory?;
+    private _quoter?;
+    constructor(config: DopplerSDKConfig);
+    /**
+     * Get the factory instance for creating auctions
+     */
+    get factory(): DopplerFactory;
+    /**
+     * Get the quoter instance for price queries
+     */
+    get quoter(): Quoter;
+    /**
+     * Get a StaticAuction instance for interacting with a static auction pool
+     * @param poolAddress The address of the Uniswap V3 pool
+     */
+    getStaticAuction(poolAddress: Address): Promise<StaticAuction>;
+    /**
+     * Get a DynamicAuction instance for interacting with a dynamic auction hook
+     * @param hookAddress The address of the Uniswap V4 hook
+     */
+    getDynamicAuction(hookAddress: Address): Promise<DynamicAuction>;
+    /**
+     * Get information about a static auction pool
+     * @param poolAddress The address of the pool
+     */
+    getPoolInfo(poolAddress: Address): Promise<PoolInfo>;
+    /**
+     * Get information about a dynamic auction hook
+     * @param hookAddress The address of the hook
+     */
+    getHookInfo(hookAddress: Address): Promise<HookInfo>;
+    /**
+     * Get the current chain ID
+     */
+    getChainId(): number;
+    /**
+     * Get the underlying clients
+     */
+    getClients(): {
+        publicClient: PublicClient;
+        walletClient?: WalletClient;
+    };
+}
+
+export { DopplerSDK };

package/dist/DopplerSDK.d.ts

@@ -0,0 +1,56 @@
+import { Address, PublicClient, WalletClient } from 'viem';
+import { DopplerSDKConfig, PoolInfo, HookInfo } from './types.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';
+
+declare class DopplerSDK {
+    private publicClient;
+    private walletClient?;
+    private chainId;
+    private _factory?;
+    private _quoter?;
+    constructor(config: DopplerSDKConfig);
+    /**
+     * Get the factory instance for creating auctions
+     */
+    get factory(): DopplerFactory;
+    /**
+     * Get the quoter instance for price queries
+     */
+    get quoter(): Quoter;
+    /**
+     * Get a StaticAuction instance for interacting with a static auction pool
+     * @param poolAddress The address of the Uniswap V3 pool
+     */
+    getStaticAuction(poolAddress: Address): Promise<StaticAuction>;
+    /**
+     * Get a DynamicAuction instance for interacting with a dynamic auction hook
+     * @param hookAddress The address of the Uniswap V4 hook
+     */
+    getDynamicAuction(hookAddress: Address): Promise<DynamicAuction>;
+    /**
+     * Get information about a static auction pool
+     * @param poolAddress The address of the pool
+     */
+    getPoolInfo(poolAddress: Address): Promise<PoolInfo>;
+    /**
+     * Get information about a dynamic auction hook
+     * @param hookAddress The address of the hook
+     */
+    getHookInfo(hookAddress: Address): Promise<HookInfo>;
+    /**
+     * Get the current chain ID
+     */
+    getChainId(): number;
+    /**
+     * Get the underlying clients
+     */
+    getClients(): {
+        publicClient: PublicClient;
+        walletClient?: WalletClient;
+    };
+}
+
+export { DopplerSDK };

package/dist/DopplerSDK.js

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

package/dist/DopplerSDK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"DopplerSDK.js"}

package/dist/DopplerSDK.mjs

@@ -0,0 +1,14 @@
+export { DopplerSDK } from './chunk-BYR4WWCZ.mjs';
+import './chunk-QSQGLWNY.mjs';
+import './chunk-BYK425DD.mjs';
+import './chunk-AZLFJNTG.mjs';
+import './chunk-6REZA4TU.mjs';
+import './chunk-O55NMSZK.mjs';
+import './chunk-IPW2I4JJ.mjs';
+import './chunk-2LPOXGKT.mjs';
+import './chunk-T644D54P.mjs';
+import './chunk-XJGF77WN.mjs';
+import './chunk-NDWBEGEN.mjs';
+import './chunk-LOROXNH3.mjs';
+//# sourceMappingURL=DopplerSDK.mjs.map
+//# sourceMappingURL=DopplerSDK.mjs.map

package/dist/DopplerSDK.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"DopplerSDK.mjs"}

package/dist/__tests__/mocks/addresses.d.mts

@@ -0,0 +1,46 @@
+import { Address } from 'viem';
+import { ChainAddresses } from '../../addresses.mjs';
+
+declare const mockAddresses: ChainAddresses;
+declare const mockTokenAddress: Address;
+declare const mockPoolAddress: Address;
+declare const mockHookAddress: Address;
+declare const mockGovernanceAddress: Address;
+declare const mockTimelockAddress: Address;
+declare const mockV2PoolAddress: Address;
+declare const mockAddressesWithExtras: {
+    token: `0x${string}`;
+    hook: `0x${string}`;
+    governance: `0x${string}`;
+    timelock: `0x${string}`;
+    v2Pool: `0x${string}`;
+    user: Address;
+    airlock: Address;
+    tokenFactory: Address;
+    v3Initializer: Address;
+    v3Quoter: Address;
+    lockableV3Initializer?: Address;
+    v4Initializer: Address;
+    doppler: Address;
+    dopplerLens: Address;
+    dopplerDeployer: Address;
+    poolManager: Address;
+    stateView: Address;
+    v4Quoter?: Address;
+    v2Migrator: Address;
+    v3Migrator: Address;
+    v4Migrator: Address;
+    v4MigratorHook?: Address;
+    governanceFactory: Address;
+    noOpGovernanceFactory?: Address;
+    streamableFeesLocker?: Address;
+    universalRouter: Address;
+    univ2Router02?: Address;
+    permit2: Address;
+    bundler?: Address;
+    weth: Address;
+    uniswapV2Factory?: Address;
+    uniswapV3Factory?: Address;
+};
+
+export { mockAddresses, mockAddressesWithExtras, mockGovernanceAddress, mockHookAddress, mockPoolAddress, mockTimelockAddress, mockTokenAddress, mockV2PoolAddress };

package/dist/__tests__/mocks/addresses.d.ts

@@ -0,0 +1,46 @@
+import { Address } from 'viem';
+import { ChainAddresses } from '../../addresses.js';
+
+declare const mockAddresses: ChainAddresses;
+declare const mockTokenAddress: Address;
+declare const mockPoolAddress: Address;
+declare const mockHookAddress: Address;
+declare const mockGovernanceAddress: Address;
+declare const mockTimelockAddress: Address;
+declare const mockV2PoolAddress: Address;
+declare const mockAddressesWithExtras: {
+    token: `0x${string}`;
+    hook: `0x${string}`;
+    governance: `0x${string}`;
+    timelock: `0x${string}`;
+    v2Pool: `0x${string}`;
+    user: Address;
+    airlock: Address;
+    tokenFactory: Address;
+    v3Initializer: Address;
+    v3Quoter: Address;
+    lockableV3Initializer?: Address;
+    v4Initializer: Address;
+    doppler: Address;
+    dopplerLens: Address;
+    dopplerDeployer: Address;
+    poolManager: Address;
+    stateView: Address;
+    v4Quoter?: Address;
+    v2Migrator: Address;
+    v3Migrator: Address;
+    v4Migrator: Address;
+    v4MigratorHook?: Address;
+    governanceFactory: Address;
+    noOpGovernanceFactory?: Address;
+    streamableFeesLocker?: Address;
+    universalRouter: Address;
+    univ2Router02?: Address;
+    permit2: Address;
+    bundler?: Address;
+    weth: Address;
+    uniswapV2Factory?: Address;
+    uniswapV3Factory?: Address;
+};
+
+export { mockAddresses, mockAddressesWithExtras, mockGovernanceAddress, mockHookAddress, mockPoolAddress, mockTimelockAddress, mockTokenAddress, mockV2PoolAddress };