auctionflow-sdk 1.1.0 → 1.3.0

package/README.md

@@ -56,7 +56,8 @@ Without it, constructing on a chain that has no built-in deployment throws.
 ## Create an auction
 
 The builder validates required fields and basic invariants (`startTime < endTime`,
-positive `basePrice` / `maxSupply` / `maxRaise`) before producing a config.
+positive `basePrice` / `maxSupply` / `maxRaise`, a liquidity share between 20% and
+100%) before producing a config.
 
 ```typescript
 const config = sdk
@@ -68,6 +69,7 @@ const config = sdk
     parseUnits("0.000001", 6) // slope
   )
   .withMaxRaise(parseUnits("50000", 6))
+  .withLiquidity(5_000) // 50% of the raise seeds the Uniswap pool (the default)
   .withSchedule(
     BigInt(Math.floor(Date.now() / 1000) + 3600),
     BigInt(Math.floor(Date.now() / 1000) + 3600 * 72)
@@ -77,12 +79,36 @@ const config = sdk
 const hash = await sdk.createAuction(config);
 ```
 
+`withLiquidity` sets the share of the raise, in basis points, that is paired
+with newly minted tokens to open a Uniswap pool when the auction ends; the
+creator receives the rest. The token supply must leave room for those tokens on
+top of a sold-out sale, so the contract rejects a `maxSupply` that is too small.
+
+Auction tokens can't be transferred until the auction migrates. That stops any
+holder from creating or pricing the Uniswap pool ahead of the auction.
+
 ## Buy tokens
 
 ```typescript
 const hash = await sdk.buyTokens(0n, parseUnits("1000", 18));
 ```
 
+Every purchase raises the price, so another buyer can move it between your
+quote and your transaction. `buyTokens` sends a maximum total cost (cost plus
+fee) and the contract reverts if the price moved past it. By default the SDK
+quotes the purchase and allows 1% above that quote. To change the tolerance, or
+set the bound yourself:
+
+```typescript
+await sdk.buyTokens(0n, amount, { slippageBps: 50 });        // 0.5% tolerance
+await sdk.buyTokens(0n, amount, { maxCost: 11_000_000n });   // exact bound, in USDC units
+```
+
+A purchase that would take the auction past its `maxRaise` is filled with what
+the remaining budget buys, and closes the auction. `getQuote` reports this up
+front: `quote.amount` is what you'll actually receive and `quote.fillsAuction`
+says whether your purchase completes the sale.
+
 ## Read state & quotes
 
 ```typescript
@@ -101,20 +127,38 @@ The bonding-curve helpers are also exported directly for UI/preview use:
 import { calculateBuyQuote, spotPrice } from "auctionflow-sdk";
 ```
 
-## Withdraw proceeds
+## After the auction: migrate, withdraw, collect fees
 
-Once an auction reaches `COMPLETED` — either by hitting `maxRaise` or via
-`completeAuction` after `endTime` — its creator claims the raised payment
-tokens. Callable once, by the creator only.
+Once an auction completes, by filling up or via `completeAuction` after
+`endTime`, three things happen. Each can be called by anyone except the
+withdrawal, which only the creator can make.
 
 ```typescript
+// 1. Open the Uniswap v3 pool and unlock the token for trading.
+await sdk.migrate(0n);
+const { pool, positionId } = await sdk.getMigration(0n);
+
+// 2. The creator claims their share of the raise.
 if (!(await sdk.hasWithdrawnProceeds(0n))) {
-  const hash = await sdk.withdrawProceeds(0n);
+  await sdk.withdrawProceeds(0n);
 }
+
+// 3. Later, collect the pool's trading fees.
+await sdk.collectFees(0n);
 ```
 
-Protocol fees are routed to the fee recipient at buy time, so the amount paid
-out is exactly the auction's `totalRaised`.
+**Migration** pairs the auction's liquidity share of the raise with newly
+minted tokens and opens a 1% Uniswap v3 pool **at the auction's final price**,
+so there is no price jump to arbitrage. If someone initialised the pool
+beforehand at a different price, migration corrects it first. The position NFT
+stays in the auction contract forever, so the liquidity can never be pulled.
+Tokens Uniswap doesn't use are burned, and leftover funds go to the creator.
+
+**Withdrawal** pays the creator everything not reserved for liquidity: with the
+default 50% share, half the raise. It works before or after migration.
+
+**Trading fees** from the pool go to the creator, minus the protocol's share
+(`lpFeeShareBps`, at most 50%), fixed when the auction is created.
 
 ## How the bonding curve works
 
@@ -146,11 +190,15 @@ Early buyers pay less; later buyers pay more.
 | `new AuctionFlowSDK({ chainId, rpcUrl, walletClient?, auctionAddress? })` | Construct against a supported chain. `auctionAddress` overrides the built-in deployment; without it, a chain with no canonical deployment throws. |
 | `buildAuction()` | Returns an `AuctionBuilder` (fluent config builder). |
 | `createAuction(config)` | Send the `createAuction` transaction. Requires a wallet client. |
-| `buyTokens(auctionId, amount)` | Send the `buyTokens` transaction. Requires a wallet client. |
+| `buyTokens(auctionId, amount, { maxCost?, slippageBps? })` | Send the `buyTokens` transaction with a maximum total cost; reverts if the price moved past it. Defaults to the quote plus 1%. Requires a wallet client. |
 | `getAuction(auctionId)` | Read the full auction struct. |
 | `getSpotPrice(auctionId)` | Read the current on-chain spot price. |
-| `getQuote(auctionId, amount)` | Off-chain cost + fee + post-trade spot price. |
-| `withdrawProceeds(auctionId)` | Pay a completed auction's `totalRaised` to its creator. Creator-only, once. Requires a wallet client. |
+| `getQuote(auctionId, amount)` | Tokens actually filled, cost, fee, post-trade spot price, and whether the purchase completes the auction. |
+| `applySlippage(total, slippageBps)` | The maximum cost `buyTokens` would send for a quoted total. |
+| `migrate(auctionId)` | Open the Uniswap v3 pool at the final price, lock the liquidity, unlock the token. Anyone may call. |
+| `getMigration(auctionId)` | The pool address and position NFT id, or `null` before migration. |
+| `withdrawProceeds(auctionId)` | Pay the creator their share of the raise (what isn't reserved for liquidity). Creator-only, once. |
+| `collectFees(auctionId)` | Collect the pool's trading fees: protocol share to the protocol, the rest to the creator. Anyone may call. |
 | `hasWithdrawnProceeds(auctionId)` | Whether the creator has already claimed the proceeds. |
 
 ## License

package/dist/index.d.mts

@@ -16,6 +16,11 @@ interface AuctionConfig {
     maxRaise: bigint;
     startTime: bigint;
     endTime: bigint;
+    /**
+     * Share of the raise seeded into Uniswap at migration, in basis points
+     * (2000..10000). Defaults to 5000 (50%).
+     */
+    liquidityBps?: bigint;
 }
 interface AuctionData {
     id: bigint;
@@ -31,12 +36,25 @@ interface AuctionData {
     totalRaised: bigint;
     totalSold: bigint;
     protocolFeeBps: bigint;
+    liquidityBps: bigint;
+    /** Protocol's share of the Uniswap pool's trading fees, in basis points. */
+    lpFeeShareBps: bigint;
+}
+interface MigrationInfo {
+    /** The Uniswap v3 pool, or null if the auction unlocked without one. */
+    pool: Address | null;
+    /** The Uniswap position NFT, held by the auction contract forever. */
+    positionId: bigint | null;
 }
 interface BuyQuote {
+    /** Tokens the purchase would actually deliver: less than requested if it fills the auction. */
+    amount: bigint;
     cost: bigint;
     fee: bigint;
     totalCost: bigint;
     spotPriceAfter: bigint;
+    /** True if this purchase reaches the cap and closes the auction. */
+    fillsAuction: boolean;
 }
 interface TransactionResult {
     hash: Hash;
@@ -49,6 +67,12 @@ declare class AuctionBuilder {
     withPaymentToken(address: Address): this;
     withBondingCurve(basePrice: bigint, slope: bigint): this;
     withMaxRaise(maxRaise: bigint): this;
+    /**
+     * Share of the raise, in basis points, seeded into a Uniswap pool when the
+     * auction migrates (5000 = 50%). The rest goes to the creator. Defaults to
+     * 50%; must be between 20% and 100%.
+     */
+    withLiquidity(liquidityBps: number): this;
     withSchedule(startTime: bigint, endTime: bigint): this;
     build(): AuctionConfig;
 }
@@ -67,12 +91,38 @@ declare class AuctionFlowSDK {
     });
     buildAuction(): AuctionBuilder;
     createAuction(config: AuctionConfig): Promise<Hash>;
-    buyTokens(auctionId: bigint, amount: bigint): Promise<Hash>;
     /**
-     * Withdraw a completed auction's raised payment tokens to its creator.
-     * Only the auction's creator can call this, and only once.
+     * Buy `amount` tokens (in token wei). The price rises with every purchase, so
+     * the contract takes a maximum total cost and reverts if the price moved past
+     * it before the transaction landed.
+     *
+     * Pass `maxCost` to set that bound exactly, or `slippageBps` to derive it
+     * from a fresh quote (default 100 = 1% above the quoted total).
+     */
+    buyTokens(auctionId: bigint, amount: bigint, options?: {
+        maxCost?: bigint;
+        slippageBps?: number;
+    }): Promise<Hash>;
+    /**
+     * Pay a completed auction's creator their share of the raise: everything
+     * not reserved for Uniswap liquidity. Creator only, once, before or after
+     * migration.
      */
     withdrawProceeds(auctionId: bigint): Promise<Hash>;
+    /**
+     * Move a completed auction's liquidity into a Uniswap v3 pool at the
+     * auction's final price, lock it, and unlock the token for trading. Anyone
+     * may call it.
+     */
+    migrate(auctionId: bigint): Promise<Hash>;
+    /**
+     * Collect the migrated pool's trading fees. The protocol takes its share and
+     * the creator receives the rest. Anyone may call it.
+     */
+    collectFees(auctionId: bigint): Promise<Hash>;
+    /** The Uniswap pool and position for a migrated auction. */
+    getMigration(auctionId: bigint): Promise<MigrationInfo>;
+    private write;
     hasWithdrawnProceeds(auctionId: bigint): Promise<boolean>;
     getAuction(auctionId: bigint): Promise<AuctionData>;
     getQuote(auctionId: bigint, amount: bigint): Promise<BuyQuote>;
@@ -83,9 +133,11 @@ declare class AuctionFlowSDK {
 declare const AUCTION_ADDRESSES: Record<SupportedChainId, Address>;
 declare const USDC_ADDRESSES: Record<SupportedChainId, Address>;
 
-/**
- * Off-chain bonding curve calculations (mirrors BondingCurve.sol)
- */
+/** Smallest share of the raise an auction may commit to Uniswap liquidity (20%). Mirrors TokenAuction.MIN_LIQUIDITY_BPS. */
+declare const MIN_LIQUIDITY_BPS = 2000;
+/** Liquidity share the builder uses when none is given (50%). */
+declare const DEFAULT_LIQUIDITY_BPS = 5000;
+
 declare function calculateBuyCost(currentSupply: bigint, amount: bigint, basePrice: bigint, slope: bigint): bigint;
 declare function spotPrice(currentSupply: bigint, basePrice: bigint, slope: bigint): bigint;
 declare function calculateBuyQuote(currentSupply: bigint, amount: bigint, basePrice: bigint, slope: bigint, feeBps: bigint): {
@@ -94,5 +146,28 @@ declare function calculateBuyQuote(currentSupply: bigint, amount: bigint, basePr
     total: bigint;
     spotPriceAfter: bigint;
 };
+/** Default slippage tolerance for `buyTokens`, in basis points (100 = 1%). */
+declare const DEFAULT_SLIPPAGE_BPS = 100;
+/**
+ * Upper bound a buyer will accept for a quoted total, given a tolerance in
+ * basis points. Rounds up so a tolerance never comes out tighter than asked.
+ */
+declare function applySlippage(total: bigint, slippageBps: number): bigint;
+/**
+ * Largest amount (token wei) buyable from `currentSupply` for at most `budget`,
+ * capped at `upperBound`. Mirrors BondingCurve.maxBuyable (binary search).
+ */
+declare function maxBuyable(currentSupply: bigint, budget: bigint, basePrice: bigint, slope: bigint, upperBound: bigint): bigint;
+/**
+ * What a purchase of `requested` tokens actually fills, given how much the
+ * auction has left to raise. Mirrors TokenAuction._fill: a purchase that would
+ * overshoot the cap delivers what the remaining budget buys and closes the
+ * auction.
+ */
+declare function fillPurchase(currentSupply: bigint, requested: bigint, basePrice: bigint, slope: bigint, totalRaised: bigint, maxRaise: bigint): {
+    amount: bigint;
+    cost: bigint;
+    fillsAuction: boolean;
+};
 
-export { AUCTION_ADDRESSES, AuctionBuilder, type AuctionConfig, type AuctionData, AuctionFlowSDK, AuctionState, type BuyQuote, type SupportedChainId, type TransactionResult, USDC_ADDRESSES, calculateBuyCost, calculateBuyQuote, spotPrice };
+export { AUCTION_ADDRESSES, AuctionBuilder, type AuctionConfig, type AuctionData, AuctionFlowSDK, AuctionState, type BuyQuote, DEFAULT_LIQUIDITY_BPS, DEFAULT_SLIPPAGE_BPS, MIN_LIQUIDITY_BPS, type MigrationInfo, type SupportedChainId, type TransactionResult, USDC_ADDRESSES, applySlippage, calculateBuyCost, calculateBuyQuote, fillPurchase, maxBuyable, spotPrice };

package/dist/index.d.ts

@@ -16,6 +16,11 @@ interface AuctionConfig {
     maxRaise: bigint;
     startTime: bigint;
     endTime: bigint;
+    /**
+     * Share of the raise seeded into Uniswap at migration, in basis points
+     * (2000..10000). Defaults to 5000 (50%).
+     */
+    liquidityBps?: bigint;
 }
 interface AuctionData {
     id: bigint;
@@ -31,12 +36,25 @@ interface AuctionData {
     totalRaised: bigint;
     totalSold: bigint;
     protocolFeeBps: bigint;
+    liquidityBps: bigint;
+    /** Protocol's share of the Uniswap pool's trading fees, in basis points. */
+    lpFeeShareBps: bigint;
+}
+interface MigrationInfo {
+    /** The Uniswap v3 pool, or null if the auction unlocked without one. */
+    pool: Address | null;
+    /** The Uniswap position NFT, held by the auction contract forever. */
+    positionId: bigint | null;
 }
 interface BuyQuote {
+    /** Tokens the purchase would actually deliver: less than requested if it fills the auction. */
+    amount: bigint;
     cost: bigint;
     fee: bigint;
     totalCost: bigint;
     spotPriceAfter: bigint;
+    /** True if this purchase reaches the cap and closes the auction. */
+    fillsAuction: boolean;
 }
 interface TransactionResult {
     hash: Hash;
@@ -49,6 +67,12 @@ declare class AuctionBuilder {
     withPaymentToken(address: Address): this;
     withBondingCurve(basePrice: bigint, slope: bigint): this;
     withMaxRaise(maxRaise: bigint): this;
+    /**
+     * Share of the raise, in basis points, seeded into a Uniswap pool when the
+     * auction migrates (5000 = 50%). The rest goes to the creator. Defaults to
+     * 50%; must be between 20% and 100%.
+     */
+    withLiquidity(liquidityBps: number): this;
     withSchedule(startTime: bigint, endTime: bigint): this;
     build(): AuctionConfig;
 }
@@ -67,12 +91,38 @@ declare class AuctionFlowSDK {
     });
     buildAuction(): AuctionBuilder;
     createAuction(config: AuctionConfig): Promise<Hash>;
-    buyTokens(auctionId: bigint, amount: bigint): Promise<Hash>;
     /**
-     * Withdraw a completed auction's raised payment tokens to its creator.
-     * Only the auction's creator can call this, and only once.
+     * Buy `amount` tokens (in token wei). The price rises with every purchase, so
+     * the contract takes a maximum total cost and reverts if the price moved past
+     * it before the transaction landed.
+     *
+     * Pass `maxCost` to set that bound exactly, or `slippageBps` to derive it
+     * from a fresh quote (default 100 = 1% above the quoted total).
+     */
+    buyTokens(auctionId: bigint, amount: bigint, options?: {
+        maxCost?: bigint;
+        slippageBps?: number;
+    }): Promise<Hash>;
+    /**
+     * Pay a completed auction's creator their share of the raise: everything
+     * not reserved for Uniswap liquidity. Creator only, once, before or after
+     * migration.
      */
     withdrawProceeds(auctionId: bigint): Promise<Hash>;
+    /**
+     * Move a completed auction's liquidity into a Uniswap v3 pool at the
+     * auction's final price, lock it, and unlock the token for trading. Anyone
+     * may call it.
+     */
+    migrate(auctionId: bigint): Promise<Hash>;
+    /**
+     * Collect the migrated pool's trading fees. The protocol takes its share and
+     * the creator receives the rest. Anyone may call it.
+     */
+    collectFees(auctionId: bigint): Promise<Hash>;
+    /** The Uniswap pool and position for a migrated auction. */
+    getMigration(auctionId: bigint): Promise<MigrationInfo>;
+    private write;
     hasWithdrawnProceeds(auctionId: bigint): Promise<boolean>;
     getAuction(auctionId: bigint): Promise<AuctionData>;
     getQuote(auctionId: bigint, amount: bigint): Promise<BuyQuote>;
@@ -83,9 +133,11 @@ declare class AuctionFlowSDK {
 declare const AUCTION_ADDRESSES: Record<SupportedChainId, Address>;
 declare const USDC_ADDRESSES: Record<SupportedChainId, Address>;
 
-/**
- * Off-chain bonding curve calculations (mirrors BondingCurve.sol)
- */
+/** Smallest share of the raise an auction may commit to Uniswap liquidity (20%). Mirrors TokenAuction.MIN_LIQUIDITY_BPS. */
+declare const MIN_LIQUIDITY_BPS = 2000;
+/** Liquidity share the builder uses when none is given (50%). */
+declare const DEFAULT_LIQUIDITY_BPS = 5000;
+
 declare function calculateBuyCost(currentSupply: bigint, amount: bigint, basePrice: bigint, slope: bigint): bigint;
 declare function spotPrice(currentSupply: bigint, basePrice: bigint, slope: bigint): bigint;
 declare function calculateBuyQuote(currentSupply: bigint, amount: bigint, basePrice: bigint, slope: bigint, feeBps: bigint): {
@@ -94,5 +146,28 @@ declare function calculateBuyQuote(currentSupply: bigint, amount: bigint, basePr
     total: bigint;
     spotPriceAfter: bigint;
 };
+/** Default slippage tolerance for `buyTokens`, in basis points (100 = 1%). */
+declare const DEFAULT_SLIPPAGE_BPS = 100;
+/**
+ * Upper bound a buyer will accept for a quoted total, given a tolerance in
+ * basis points. Rounds up so a tolerance never comes out tighter than asked.
+ */
+declare function applySlippage(total: bigint, slippageBps: number): bigint;
+/**
+ * Largest amount (token wei) buyable from `currentSupply` for at most `budget`,
+ * capped at `upperBound`. Mirrors BondingCurve.maxBuyable (binary search).
+ */
+declare function maxBuyable(currentSupply: bigint, budget: bigint, basePrice: bigint, slope: bigint, upperBound: bigint): bigint;
+/**
+ * What a purchase of `requested` tokens actually fills, given how much the
+ * auction has left to raise. Mirrors TokenAuction._fill: a purchase that would
+ * overshoot the cap delivers what the remaining budget buys and closes the
+ * auction.
+ */
+declare function fillPurchase(currentSupply: bigint, requested: bigint, basePrice: bigint, slope: bigint, totalRaised: bigint, maxRaise: bigint): {
+    amount: bigint;
+    cost: bigint;
+    fillsAuction: boolean;
+};
 
-export { AUCTION_ADDRESSES, AuctionBuilder, type AuctionConfig, type AuctionData, AuctionFlowSDK, AuctionState, type BuyQuote, type SupportedChainId, type TransactionResult, USDC_ADDRESSES, calculateBuyCost, calculateBuyQuote, spotPrice };
+export { AUCTION_ADDRESSES, AuctionBuilder, type AuctionConfig, type AuctionData, AuctionFlowSDK, AuctionState, type BuyQuote, DEFAULT_LIQUIDITY_BPS, DEFAULT_SLIPPAGE_BPS, MIN_LIQUIDITY_BPS, type MigrationInfo, type SupportedChainId, type TransactionResult, USDC_ADDRESSES, applySlippage, calculateBuyCost, calculateBuyQuote, fillPurchase, maxBuyable, spotPrice };