auctionflow-sdk 1.2.0 → 2.0.0

package/README.md

@@ -17,7 +17,7 @@ pnpm add auctionflow-sdk viem
 ## Quick start
 
 ```typescript
-import { AuctionFlowSDK } from "auctionflow-sdk";
+import { AuctionFlowSDK, parseCurvePrice } from "auctionflow-sdk";
 import { createWalletClient, http, parseUnits } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { baseSepolia } from "viem/chains";
@@ -53,10 +53,31 @@ const sdk = new AuctionFlowSDK({
 
 Without it, constructing on a chain that has no built-in deployment throws.
 
-## Create an auction
+## How a launch works
 
-The builder validates required fields and basic invariants (`startTime < endTime`,
-positive `basePrice` / `maxSupply` / `maxRaise`) before producing a config.
+1. **Launch.** A token is created and trading starts immediately on a bonding
+   curve: every buy raises the price, every sell lowers it.
+2. **Trade.** Anyone can buy, and sell back to the curve, until the auction has
+   raised its **graduation threshold** (`maxRaise`). Tokens can't be transferred
+   in the meantime; selling back is how you exit.
+3. **Graduate.** The purchase that reaches the threshold closes the curve, and
+   the token migrates to a Uniswap v3 pool where it trades freely.
+
+## Launch a token (one click)
+
+```typescript
+const hash = await sdk.launch("My Token", "MTK", "ipfs://<metadata-json>");
+```
+
+Everything except the name, symbol and metadata (such as the token image) comes
+from the protocol's standard launch preset: the payment token, supply, curve,
+graduation threshold and liquidity share.
+
+## Create an auction with custom parameters
+
+The builder validates required fields and basic invariants (positive
+`basePrice` / `maxSupply` / `maxRaise`, a liquidity share between 20% and 100%)
+before producing a config.
 
 ```typescript
 const config = sdk
@@ -64,25 +85,74 @@ const config = sdk
   .withToken("MyToken", "MTK", parseUnits("1000000", 18))
   .withPaymentToken("0x036CbD53842c5426634e7929541eC2318f3dCF7e") // USDC Sepolia
   .withBondingCurve(
-    parseUnits("0.01", 6), // base price: 0.01 USDC
-    parseUnits("0.000001", 6) // slope
-  )
-  .withMaxRaise(parseUnits("50000", 6))
-  .withSchedule(
-    BigInt(Math.floor(Date.now() / 1000) + 3600),
-    BigInt(Math.floor(Date.now() / 1000) + 3600 * 72)
+    parseCurvePrice("0.01", 6), // base price: 0.01 USDC per token
+    parseCurvePrice("0.000001", 6) // slope: +0.000001 USDC per token sold
   )
+  .withMaxRaise(parseUnits("50000", 6)) // graduation threshold
+  .withLiquidity(5_000) // 50% of the raise seeds the Uniswap pool (the default)
+  .withMetadata("ipfs://<metadata-json>")
   .build();
 
 const hash = await sdk.createAuction(config);
 ```
 
+Prices are per whole token, stored with 18 extra decimals so a curve can rise
+by far less than one USDC unit per token, as a billion-token memecoin needs.
+`parseCurvePrice(price, paymentDecimals)` converts a human price into those
+units, and `formatCurvePrice` converts back (for example, a `getSpotPrice`
+result for display).
+
+`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. Holders
+can always exit before then by selling back to the curve.
+
 ## 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.
+
+## Sell tokens
+
+Until graduation, anyone can sell tokens back to the curve at the curve price,
+minus the protocol fee. The tokens are burned and the seller is paid from the
+raise, so the price falls by exactly what the purchase raised it.
+
+```typescript
+const quote = await sdk.getSellQuote(0n, parseUnits("400", 18));
+console.log(quote.proceeds, quote.fee, quote.netProceeds);
+
+await sdk.sellTokens(0n, parseUnits("400", 18));                       // 1% below the quote
+await sdk.sellTokens(0n, parseUnits("400", 18), { slippageBps: 50 });  // 0.5% tolerance
+await sdk.sellTokens(0n, parseUnits("400", 18), { minProceeds: 4_000_000n });
+```
+
+Like `buyTokens`, the contract reverts if the price moved past your bound before
+the transaction landed. Purchases round up and sales round down, so a round
+trip can never profit, and the contract always holds enough to buy back every
+outstanding token.
+
 ## Read state & quotes
 
 ```typescript
@@ -98,23 +168,40 @@ console.log(quote.cost, quote.fee, quote.totalCost, quote.spotPriceAfter);
 The bonding-curve helpers are also exported directly for UI/preview use:
 
 ```typescript
-import { calculateBuyQuote, spotPrice } from "auctionflow-sdk";
+import { calculateBuyQuote, calculateSellProceeds, spotPrice, formatCurvePrice } from "auctionflow-sdk";
 ```
 
-## Withdraw proceeds
+## After graduation: 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 graduates, 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
 
@@ -144,13 +231,21 @@ Early buyers pay less; later buyers pay more.
 | Member | Description |
 | --- | --- |
 | `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. |
+| `launch(name, symbol, metadataURI?)` | One-click launch with the protocol's standard preset. Requires a wallet client. |
 | `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. |
+| `createAuction(config)` | Launch with custom parameters. 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. |
+| `sellTokens(auctionId, amount, { minProceeds?, slippageBps? })` | Sell back to the curve before graduation, with a minimum payout; defaults to the quote minus 1%. Requires a wallet client. |
+| `getSellQuote(auctionId, amount)` | Proceeds, fee, net payout, and post-trade spot price for a sale. |
+| `applySellSlippage(netProceeds, slippageBps)` | The minimum payout `sellTokens` would send for a quoted sale. |
+| `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

@@ -13,9 +13,15 @@ interface AuctionConfig {
     paymentToken: Address;
     basePrice: bigint;
     slope: bigint;
+    /** Graduation threshold: once this much is raised, trading moves to Uniswap. */
     maxRaise: bigint;
-    startTime: bigint;
-    endTime: bigint;
+    /** Off-chain metadata for the token, such as its image (e.g. an IPFS URI). */
+    metadataURI?: string;
+    /**
+     * Share of the raise seeded into Uniswap at migration, in basis points
+     * (2000..10000). Defaults to 5000 (50%).
+     */
+    liquidityBps?: bigint;
 }
 interface AuctionData {
     id: bigint;
@@ -25,18 +31,37 @@ interface AuctionData {
     basePrice: bigint;
     slope: bigint;
     maxRaise: bigint;
-    startTime: bigint;
-    endTime: bigint;
     state: AuctionState;
     totalRaised: bigint;
     totalSold: bigint;
     protocolFeeBps: bigint;
+    liquidityBps: bigint;
+    /** Protocol's share of the Uniswap pool's trading fees, in basis points. */
+    lpFeeShareBps: bigint;
+}
+interface SellQuote {
+    /** Curve value of the tokens being sold, before the protocol fee. */
+    proceeds: bigint;
+    fee: bigint;
+    /** What the seller receives: proceeds minus fee. */
+    netProceeds: bigint;
+    spotPriceAfter: 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;
@@ -48,8 +73,16 @@ declare class AuctionBuilder {
     withToken(name: string, symbol: string, maxSupply: bigint): this;
     withPaymentToken(address: Address): this;
     withBondingCurve(basePrice: bigint, slope: bigint): this;
+    /** Graduation threshold: once this much is raised, trading moves to Uniswap. */
     withMaxRaise(maxRaise: bigint): this;
-    withSchedule(startTime: bigint, endTime: 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;
+    /** Off-chain metadata for the token, such as its image (e.g. an IPFS URI). */
+    withMetadata(metadataURI: string): this;
     build(): AuctionConfig;
 }
 
@@ -67,12 +100,55 @@ 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.
+     * One-click launch: a token with the protocol's standard curve, threshold
+     * and liquidity share. Trading starts immediately.
+     */
+    launch(name: string, symbol: string, metadataURI?: string): Promise<Hash>;
+    /**
+     * Sell `amount` tokens (in token wei) back to the curve before graduation.
+     * The contract reverts if the price fell below the bound before the
+     * transaction landed: pass `minProceeds` to set it exactly, or `slippageBps`
+     * to derive it from a fresh quote (default 100 = 1% below it).
+     */
+    sellTokens(auctionId: bigint, amount: bigint, options?: {
+        minProceeds?: bigint;
+        slippageBps?: number;
+    }): Promise<Hash>;
+    /** What selling `amount` tokens back to the curve would pay right now. */
+    getSellQuote(auctionId: bigint, amount: bigint): Promise<SellQuote>;
+    /**
+     * 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,7 +159,28 @@ declare class AuctionFlowSDK {
 declare const AUCTION_ADDRESSES: Record<SupportedChainId, Address>;
 declare const USDC_ADDRESSES: Record<SupportedChainId, Address>;
 
+/** 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;
+
+/** Fixed-point scale of `basePrice`, `slope` and spot prices. */
+declare const PRICE_SCALE: bigint;
+/**
+ * A human-readable price per whole token, in curve units.
+ * `parseCurvePrice("0.01", 6)` is 0.01 USDC per token.
+ */
+declare function parseCurvePrice(price: string, paymentDecimals: number): bigint;
+/** A curve price (e.g. from `getSpotPrice`) as a human-readable price per whole token. */
+declare function formatCurvePrice(price: bigint, paymentDecimals: number): string;
 declare function calculateBuyCost(currentSupply: bigint, amount: bigint, basePrice: bigint, slope: bigint): bigint;
+/**
+ * Proceeds from selling `amount` tokens back to the curve when `currentSupply`
+ * are outstanding. Mirrors BondingCurve.calculateSellProceeds: the same
+ * integral as a purchase, but rounded down, so a round trip never profits.
+ */
+declare function calculateSellProceeds(currentSupply: bigint, amount: bigint, basePrice: bigint, slope: bigint): bigint;
+/** Price of the next whole token, in curve units (payment units × 1e18). */
 declare function spotPrice(currentSupply: bigint, basePrice: bigint, slope: bigint): bigint;
 declare function calculateBuyQuote(currentSupply: bigint, amount: bigint, basePrice: bigint, slope: bigint, feeBps: bigint): {
     cost: bigint;
@@ -91,5 +188,33 @@ declare function calculateBuyQuote(currentSupply: bigint, amount: bigint, basePr
     total: bigint;
     spotPriceAfter: bigint;
 };
+/** Default slippage tolerance for `buyTokens` and `sellTokens`, 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;
+};
+/**
+ * Least a seller will accept for a quoted amount, given a tolerance in basis
+ * points. Rounds down so a tolerance never comes out tighter than asked.
+ */
+declare function applySellSlippage(netProceeds: bigint, slippageBps: number): bigint;
 
-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, PRICE_SCALE, type SellQuote, type SupportedChainId, type TransactionResult, USDC_ADDRESSES, applySellSlippage, applySlippage, calculateBuyCost, calculateBuyQuote, calculateSellProceeds, fillPurchase, formatCurvePrice, maxBuyable, parseCurvePrice, spotPrice };

package/dist/index.d.ts

@@ -13,9 +13,15 @@ interface AuctionConfig {
     paymentToken: Address;
     basePrice: bigint;
     slope: bigint;
+    /** Graduation threshold: once this much is raised, trading moves to Uniswap. */
     maxRaise: bigint;
-    startTime: bigint;
-    endTime: bigint;
+    /** Off-chain metadata for the token, such as its image (e.g. an IPFS URI). */
+    metadataURI?: string;
+    /**
+     * Share of the raise seeded into Uniswap at migration, in basis points
+     * (2000..10000). Defaults to 5000 (50%).
+     */
+    liquidityBps?: bigint;
 }
 interface AuctionData {
     id: bigint;
@@ -25,18 +31,37 @@ interface AuctionData {
     basePrice: bigint;
     slope: bigint;
     maxRaise: bigint;
-    startTime: bigint;
-    endTime: bigint;
     state: AuctionState;
     totalRaised: bigint;
     totalSold: bigint;
     protocolFeeBps: bigint;
+    liquidityBps: bigint;
+    /** Protocol's share of the Uniswap pool's trading fees, in basis points. */
+    lpFeeShareBps: bigint;
+}
+interface SellQuote {
+    /** Curve value of the tokens being sold, before the protocol fee. */
+    proceeds: bigint;
+    fee: bigint;
+    /** What the seller receives: proceeds minus fee. */
+    netProceeds: bigint;
+    spotPriceAfter: 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;
@@ -48,8 +73,16 @@ declare class AuctionBuilder {
     withToken(name: string, symbol: string, maxSupply: bigint): this;
     withPaymentToken(address: Address): this;
     withBondingCurve(basePrice: bigint, slope: bigint): this;
+    /** Graduation threshold: once this much is raised, trading moves to Uniswap. */
     withMaxRaise(maxRaise: bigint): this;
-    withSchedule(startTime: bigint, endTime: 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;
+    /** Off-chain metadata for the token, such as its image (e.g. an IPFS URI). */
+    withMetadata(metadataURI: string): this;
     build(): AuctionConfig;
 }
 
@@ -67,12 +100,55 @@ 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.
+     * One-click launch: a token with the protocol's standard curve, threshold
+     * and liquidity share. Trading starts immediately.
+     */
+    launch(name: string, symbol: string, metadataURI?: string): Promise<Hash>;
+    /**
+     * Sell `amount` tokens (in token wei) back to the curve before graduation.
+     * The contract reverts if the price fell below the bound before the
+     * transaction landed: pass `minProceeds` to set it exactly, or `slippageBps`
+     * to derive it from a fresh quote (default 100 = 1% below it).
+     */
+    sellTokens(auctionId: bigint, amount: bigint, options?: {
+        minProceeds?: bigint;
+        slippageBps?: number;
+    }): Promise<Hash>;
+    /** What selling `amount` tokens back to the curve would pay right now. */
+    getSellQuote(auctionId: bigint, amount: bigint): Promise<SellQuote>;
+    /**
+     * 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,7 +159,28 @@ declare class AuctionFlowSDK {
 declare const AUCTION_ADDRESSES: Record<SupportedChainId, Address>;
 declare const USDC_ADDRESSES: Record<SupportedChainId, Address>;
 
+/** 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;
+
+/** Fixed-point scale of `basePrice`, `slope` and spot prices. */
+declare const PRICE_SCALE: bigint;
+/**
+ * A human-readable price per whole token, in curve units.
+ * `parseCurvePrice("0.01", 6)` is 0.01 USDC per token.
+ */
+declare function parseCurvePrice(price: string, paymentDecimals: number): bigint;
+/** A curve price (e.g. from `getSpotPrice`) as a human-readable price per whole token. */
+declare function formatCurvePrice(price: bigint, paymentDecimals: number): string;
 declare function calculateBuyCost(currentSupply: bigint, amount: bigint, basePrice: bigint, slope: bigint): bigint;
+/**
+ * Proceeds from selling `amount` tokens back to the curve when `currentSupply`
+ * are outstanding. Mirrors BondingCurve.calculateSellProceeds: the same
+ * integral as a purchase, but rounded down, so a round trip never profits.
+ */
+declare function calculateSellProceeds(currentSupply: bigint, amount: bigint, basePrice: bigint, slope: bigint): bigint;
+/** Price of the next whole token, in curve units (payment units × 1e18). */
 declare function spotPrice(currentSupply: bigint, basePrice: bigint, slope: bigint): bigint;
 declare function calculateBuyQuote(currentSupply: bigint, amount: bigint, basePrice: bigint, slope: bigint, feeBps: bigint): {
     cost: bigint;
@@ -91,5 +188,33 @@ declare function calculateBuyQuote(currentSupply: bigint, amount: bigint, basePr
     total: bigint;
     spotPriceAfter: bigint;
 };
+/** Default slippage tolerance for `buyTokens` and `sellTokens`, 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;
+};
+/**
+ * Least a seller will accept for a quoted amount, given a tolerance in basis
+ * points. Rounds down so a tolerance never comes out tighter than asked.
+ */
+declare function applySellSlippage(netProceeds: bigint, slippageBps: number): bigint;
 
-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, PRICE_SCALE, type SellQuote, type SupportedChainId, type TransactionResult, USDC_ADDRESSES, applySellSlippage, applySlippage, calculateBuyCost, calculateBuyQuote, calculateSellProceeds, fillPurchase, formatCurvePrice, maxBuyable, parseCurvePrice, spotPrice };