auctionflow-sdk 1.3.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,11 +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`, a liquidity share between 20% and
-100%) 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
@@ -65,27 +85,31 @@ 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
+    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))
+  .withMaxRaise(parseUnits("50000", 6)) // graduation threshold
   .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)
-  )
+  .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.
+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
 
@@ -109,6 +133,26 @@ 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
@@ -124,14 +168,13 @@ 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";
 ```
 
-## After the auction: migrate, withdraw, collect fees
+## After graduation: migrate, withdraw, collect fees
 
-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.
+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.
@@ -188,13 +231,17 @@ 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. |
+| `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)` | 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. |

package/dist/index.d.mts

@@ -13,9 +13,10 @@ 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%).
@@ -30,8 +31,6 @@ interface AuctionData {
     basePrice: bigint;
     slope: bigint;
     maxRaise: bigint;
-    startTime: bigint;
-    endTime: bigint;
     state: AuctionState;
     totalRaised: bigint;
     totalSold: bigint;
@@ -40,6 +39,14 @@ interface AuctionData {
     /** 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;
@@ -66,6 +73,7 @@ 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;
     /**
      * Share of the raise, in basis points, seeded into a Uniswap pool when the
@@ -73,7 +81,8 @@ declare class AuctionBuilder {
      * 50%; must be between 20% and 100%.
      */
     withLiquidity(liquidityBps: number): this;
-    withSchedule(startTime: bigint, endTime: bigint): this;
+    /** Off-chain metadata for the token, such as its image (e.g. an IPFS URI). */
+    withMetadata(metadataURI: string): this;
     build(): AuctionConfig;
 }
 
@@ -91,6 +100,23 @@ declare class AuctionFlowSDK {
     });
     buildAuction(): AuctionBuilder;
     createAuction(config: AuctionConfig): Promise<Hash>;
+    /**
+     * 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
@@ -138,7 +164,23 @@ 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;
@@ -146,7 +188,7 @@ declare function calculateBuyQuote(currentSupply: bigint, amount: bigint, basePr
     total: bigint;
     spotPriceAfter: bigint;
 };
-/** Default slippage tolerance for `buyTokens`, in basis points (100 = 1%). */
+/** 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
@@ -169,5 +211,10 @@ declare function fillPurchase(currentSupply: bigint, requested: bigint, basePric
     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, DEFAULT_LIQUIDITY_BPS, DEFAULT_SLIPPAGE_BPS, MIN_LIQUIDITY_BPS, type MigrationInfo, type SupportedChainId, type TransactionResult, USDC_ADDRESSES, applySlippage, calculateBuyCost, calculateBuyQuote, fillPurchase, maxBuyable, 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,10 @@ 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%).
@@ -30,8 +31,6 @@ interface AuctionData {
     basePrice: bigint;
     slope: bigint;
     maxRaise: bigint;
-    startTime: bigint;
-    endTime: bigint;
     state: AuctionState;
     totalRaised: bigint;
     totalSold: bigint;
@@ -40,6 +39,14 @@ interface AuctionData {
     /** 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;
@@ -66,6 +73,7 @@ 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;
     /**
      * Share of the raise, in basis points, seeded into a Uniswap pool when the
@@ -73,7 +81,8 @@ declare class AuctionBuilder {
      * 50%; must be between 20% and 100%.
      */
     withLiquidity(liquidityBps: number): this;
-    withSchedule(startTime: bigint, endTime: bigint): this;
+    /** Off-chain metadata for the token, such as its image (e.g. an IPFS URI). */
+    withMetadata(metadataURI: string): this;
     build(): AuctionConfig;
 }
 
@@ -91,6 +100,23 @@ declare class AuctionFlowSDK {
     });
     buildAuction(): AuctionBuilder;
     createAuction(config: AuctionConfig): Promise<Hash>;
+    /**
+     * 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
@@ -138,7 +164,23 @@ 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;
@@ -146,7 +188,7 @@ declare function calculateBuyQuote(currentSupply: bigint, amount: bigint, basePr
     total: bigint;
     spotPriceAfter: bigint;
 };
-/** Default slippage tolerance for `buyTokens`, in basis points (100 = 1%). */
+/** 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
@@ -169,5 +211,10 @@ declare function fillPurchase(currentSupply: bigint, requested: bigint, basePric
     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, DEFAULT_LIQUIDITY_BPS, DEFAULT_SLIPPAGE_BPS, MIN_LIQUIDITY_BPS, type MigrationInfo, type SupportedChainId, type TransactionResult, USDC_ADDRESSES, applySlippage, calculateBuyCost, calculateBuyQuote, fillPurchase, maxBuyable, 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 };