auctionflow-sdk 2.0.1 → 3.0.0

package/README.md

@@ -17,7 +17,7 @@ pnpm add auctionflow-sdk viem
 ## Quick start
 
 ```typescript
-import { AuctionFlowSDK, parseCurvePrice } from "auctionflow-sdk";
+import { AuctionFlowSDK, parseCurvePrice, USDC_ADDRESSES } from "auctionflow-sdk";
 import { createWalletClient, http, parseUnits } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { baseSepolia } from "viem/chains";
@@ -66,12 +66,15 @@ Without it, constructing on a chain that has no built-in deployment throws.
 ## Launch a token (one click)
 
 ```typescript
-const hash = await sdk.launch("My Token", "MTK", "ipfs://<metadata-json>");
+const hash = await sdk.launch("My Token", "MTK", "ipfs://<metadata-json>");                 // priced in ETH
+const usdc = await sdk.launch("My Token", "MTK", "ipfs://<metadata-json>", USDC_ADDRESSES[84532]); // priced in USDC
 ```
 
-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.
+The creator picks the name, symbol, metadata (such as the token image) and the
+payment token: WETH by default, so the token trades in plain ETH, or USDC.
+Everything else comes from the protocol's standard launch preset for that
+token: supply, curve, graduation threshold and liquidity share. Read it with
+`getLaunchPreset(paymentToken)`, which returns `null` for a token with no preset.
 
 ## Create an auction with custom parameters
 
@@ -153,6 +156,24 @@ 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.
 
+## Pay in ETH
+
+A token priced in WETH can be bought and sold with plain ETH, in one
+transaction and with no token approval. The contract wraps and unwraps it.
+
+```typescript
+if (await sdk.isPricedInETH(0n)) {
+  await sdk.buyTokensWithETH(0n, parseUnits("1000000", 18));   // sends the quote plus 1% as ETH
+  await sdk.sellTokensForETH(0n, parseUnits("400000", 18));    // paid out in ETH
+}
+```
+
+`buyTokensWithETH` sends the most the purchase may cost as the transaction's
+value (the same `maxCost` / `slippageBps` options as `buyTokens`), and the
+contract refunds whatever the purchase doesn't use. `sellTokensForETH` takes
+the same options as `sellTokens`. A creator's proceeds, pool fees and claims
+for such a token are paid in WETH.
+
 ## Read state & quotes
 
 ```typescript
@@ -186,8 +207,11 @@ if (!(await sdk.hasWithdrawnProceeds(0n))) {
   await sdk.withdrawProceeds(0n);
 }
 
-// 3. Later, collect the pool's trading fees.
+// 3. Later, collect the pool's trading fees. The creator's share is
+//    credited to them, and they withdraw it (in both tokens) with claim.
 await sdk.collectFees(0n);
+await sdk.claim(usdcAddress);
+await sdk.claim(tokenAddress);
 ```
 
 **Migration** pairs the auction's liquidity share of the raise with newly
@@ -195,13 +219,16 @@ 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.
+Tokens Uniswap doesn't use are burned, and leftover funds are credited to the
+creator to `claim`.
 
 **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.
+**Trading fees** from the pool are credited to the creator, minus the
+protocol's share (`lpFeeShareBps`, at most 50%), fixed when the auction is
+created. Payouts are claimed rather than sent, so no recipient (for example an
+address USDC has blacklisted) can block a trade or a migration.
 
 ## How the bonding curve works
 
@@ -231,10 +258,14 @@ 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. |
+| `launch(name, symbol, metadataURI?, paymentToken?)` | One-click launch with the protocol's standard preset for `paymentToken` (default WETH). Requires a wallet client. |
+| `getLaunchPreset(paymentToken)` | The standard launch for `paymentToken`, or `null` if none is configured. |
 | `buildAuction()` | Returns an `AuctionBuilder` (fluent config builder). |
 | `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. |
+| `buyTokensWithETH(auctionId, amount, { maxCost?, slippageBps? })` | `buyTokens` for a WETH-priced token, paid in plain ETH; the unused part of the value is refunded. Requires a wallet client. |
+| `sellTokensForETH(auctionId, amount, { minProceeds?, slippageBps? })` | `sellTokens` for a WETH-priced token, paid out in plain ETH. Requires a wallet client. |
+| `isPricedInETH(auctionId)` | Whether the auction is priced in WETH, so it trades in plain ETH. |
 | `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. |
@@ -245,8 +276,14 @@ Early buyers pay less; later buyers pay more.
 | `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. |
+| `collectFees(auctionId)` | Collect the pool's trading fees: the protocol's share accrues to the protocol and the rest is credited to the creator. Anyone may call. |
+| `claim(token)` | Withdraw everything credited to the connected account in `token`: a creator's share of pool fees, and any reserve migration couldn't place. |
+| `getClaimable(token, account)` | How much of `token` is credited to `account`. |
+| `claimProtocolFees(token)` | Send the protocol's unclaimed fees in `token` to the fee recipient. Anyone may call. |
+| `getProtocolFees(token)` | The protocol's unclaimed fees in `token`. |
+| `isPaymentTokenAllowed(token)` | Whether new auctions may be priced in `token`. Only owner-approved tokens (USDC and WETH) can be used. |
 | `hasWithdrawnProceeds(auctionId)` | Whether the creator has already claimed the proceeds. |
+| `isPaused()` | Whether the protocol is paused. While paused, `launch`, `createAuction`, `buyTokens` and `buyTokensWithETH` revert; selling back, migration, withdrawals, fee collection and claims still work. |
 
 ## License