auctionflow-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sodiq Agunbiade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# auctionflow-sdk
+
+Type-safe TypeScript SDK for the [AuctionFlow](https://github.com/Sodiq-123/AuctionFlow) bonding-curve token auction protocol, built on [viem](https://viem.sh).
+
+Create auctions, buy tokens, and read on-chain state with a fluent builder API and off-chain price quotes that mirror the Solidity bonding-curve math exactly.
+
+## Install
+
+```bash
+npm install auctionflow-sdk viem
+# or
+pnpm add auctionflow-sdk viem
+```
+
+`viem` is a peer of everyday usage — you supply the wallet client.
+
+## Quick start
+
+```typescript
+import { AuctionFlowSDK } from "auctionflow-sdk";
+import { createWalletClient, http, parseUnits } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { baseSepolia } from "viem/chains";
+
+const account = privateKeyToAccount("0x...");
+const walletClient = createWalletClient({
+  account,
+  chain: baseSepolia,
+  transport: http("https://sepolia.base.org"),
+});
+
+const sdk = new AuctionFlowSDK({
+  chainId: 84532, // Base Sepolia
+  rpcUrl: "https://sepolia.base.org",
+  walletClient,
+});
+```
+
+## Create an auction
+
+The builder validates required fields and basic invariants (`startTime < endTime`,
+positive `basePrice` / `maxSupply` / `maxRaise`) before producing a config.
+
+```typescript
+const config = sdk
+  .buildAuction()
+  .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)
+  )
+  .build();
+
+const hash = await sdk.createAuction(config);
+```
+
+## Buy tokens
+
+```typescript
+const hash = await sdk.buyTokens(0n, parseUnits("1000", 18));
+```
+
+## Read state & quotes
+
+```typescript
+// On-chain reads
+const auction = await sdk.getAuction(0n);
+const spot = await sdk.getSpotPrice(0n);
+
+// Off-chain quote — no gas, mirrors BondingCurve.sol
+const quote = await sdk.getQuote(0n, parseUnits("1000", 18));
+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";
+```
+
+## Withdraw proceeds
+
+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.
+
+```typescript
+if (!(await sdk.hasWithdrawnProceeds(0n))) {
+  const hash = await sdk.withdrawProceeds(0n);
+}
+```
+
+Protocol fees are routed to the fee recipient at buy time, so the amount paid
+out is exactly the auction's `totalRaised`.
+
+## How the bonding curve works
+
+Each auction uses a **linear bonding curve** — price rises as tokens are sold:
+
+```text
+price = basePrice + slope × totalSold
+```
+
+The cost to buy `n` tokens from current supply `s` is the integral:
+
+```text
+cost = basePrice × n + slope × n × (2s + n) / 2
+```
+
+Early buyers pay less; later buyers pay more.
+
+## Supported chains
+
+| Chain | Chain ID | Status |
+| --- | --- | --- |
+| Base Sepolia | `84532` | Deployed |
+| Base Mainnet | `8453` | Not yet deployed — the SDK throws on construction |
+
+## API
+
+| Member | Description |
+| --- | --- |
+| `new AuctionFlowSDK({ chainId, rpcUrl, walletClient? })` | Construct against a supported chain. Throws if the chain has no deployment. |
+| `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. |
+| `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. |
+| `hasWithdrawnProceeds(auctionId)` | Whether the creator has already claimed the proceeds. |
+
+## License
+
+[MIT](https://github.com/Sodiq-123/AuctionFlow/blob/main/LICENSE) — Sodiq Agunbiade

package/dist/index.d.mts

@@ -0,0 +1,97 @@
+import { Address, Hash, PublicClient, WalletClient } from 'viem';
+
+declare enum AuctionState {
+    PENDING = 0,
+    ACTIVE = 1,
+    COMPLETED = 2,
+    MIGRATED = 3
+}
+interface AuctionConfig {
+    name: string;
+    symbol: string;
+    maxSupply: bigint;
+    paymentToken: Address;
+    basePrice: bigint;
+    slope: bigint;
+    maxRaise: bigint;
+    startTime: bigint;
+    endTime: bigint;
+}
+interface AuctionData {
+    id: bigint;
+    token: Address;
+    paymentToken: Address;
+    creator: Address;
+    basePrice: bigint;
+    slope: bigint;
+    maxRaise: bigint;
+    startTime: bigint;
+    endTime: bigint;
+    state: AuctionState;
+    totalRaised: bigint;
+    totalSold: bigint;
+    protocolFeeBps: bigint;
+}
+interface BuyQuote {
+    cost: bigint;
+    fee: bigint;
+    totalCost: bigint;
+    spotPriceAfter: bigint;
+}
+interface TransactionResult {
+    hash: Hash;
+}
+type SupportedChainId = 8453 | 84532;
+
+declare class AuctionBuilder {
+    private config;
+    withToken(name: string, symbol: string, maxSupply: bigint): this;
+    withPaymentToken(address: Address): this;
+    withBondingCurve(basePrice: bigint, slope: bigint): this;
+    withMaxRaise(maxRaise: bigint): this;
+    withSchedule(startTime: bigint, endTime: bigint): this;
+    build(): AuctionConfig;
+}
+
+declare class AuctionFlowSDK {
+    readonly publicClient: PublicClient;
+    readonly walletClient?: WalletClient;
+    readonly auctionAddress: Address;
+    readonly chainId: SupportedChainId;
+    private readonly chain;
+    constructor(params: {
+        chainId: SupportedChainId;
+        rpcUrl: string;
+        walletClient?: WalletClient;
+    });
+    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.
+     */
+    withdrawProceeds(auctionId: bigint): Promise<Hash>;
+    hasWithdrawnProceeds(auctionId: bigint): Promise<boolean>;
+    getAuction(auctionId: bigint): Promise<AuctionData>;
+    getQuote(auctionId: bigint, amount: bigint): Promise<BuyQuote>;
+    getSpotPrice(auctionId: bigint): Promise<bigint>;
+    private parseAuctionResult;
+}
+
+declare const AUCTION_ADDRESSES: Record<SupportedChainId, Address>;
+declare const USDC_ADDRESSES: Record<SupportedChainId, Address>;
+
+/**
+ * Off-chain bonding curve calculations (mirrors BondingCurve.sol)
+ */
+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): {
+    cost: bigint;
+    fee: bigint;
+    total: bigint;
+    spotPriceAfter: bigint;
+};
+
+export { AUCTION_ADDRESSES, AuctionBuilder, type AuctionConfig, type AuctionData, AuctionFlowSDK, AuctionState, type BuyQuote, type SupportedChainId, type TransactionResult, USDC_ADDRESSES, calculateBuyCost, calculateBuyQuote, spotPrice };

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+import { Address, Hash, PublicClient, WalletClient } from 'viem';
+
+declare enum AuctionState {
+    PENDING = 0,
+    ACTIVE = 1,
+    COMPLETED = 2,
+    MIGRATED = 3
+}
+interface AuctionConfig {
+    name: string;
+    symbol: string;
+    maxSupply: bigint;
+    paymentToken: Address;
+    basePrice: bigint;
+    slope: bigint;
+    maxRaise: bigint;
+    startTime: bigint;
+    endTime: bigint;
+}
+interface AuctionData {
+    id: bigint;
+    token: Address;
+    paymentToken: Address;
+    creator: Address;
+    basePrice: bigint;
+    slope: bigint;
+    maxRaise: bigint;
+    startTime: bigint;
+    endTime: bigint;
+    state: AuctionState;
+    totalRaised: bigint;
+    totalSold: bigint;
+    protocolFeeBps: bigint;
+}
+interface BuyQuote {
+    cost: bigint;
+    fee: bigint;
+    totalCost: bigint;
+    spotPriceAfter: bigint;
+}
+interface TransactionResult {
+    hash: Hash;
+}
+type SupportedChainId = 8453 | 84532;
+
+declare class AuctionBuilder {
+    private config;
+    withToken(name: string, symbol: string, maxSupply: bigint): this;
+    withPaymentToken(address: Address): this;
+    withBondingCurve(basePrice: bigint, slope: bigint): this;
+    withMaxRaise(maxRaise: bigint): this;
+    withSchedule(startTime: bigint, endTime: bigint): this;
+    build(): AuctionConfig;
+}
+
+declare class AuctionFlowSDK {
+    readonly publicClient: PublicClient;
+    readonly walletClient?: WalletClient;
+    readonly auctionAddress: Address;
+    readonly chainId: SupportedChainId;
+    private readonly chain;
+    constructor(params: {
+        chainId: SupportedChainId;
+        rpcUrl: string;
+        walletClient?: WalletClient;
+    });
+    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.
+     */
+    withdrawProceeds(auctionId: bigint): Promise<Hash>;
+    hasWithdrawnProceeds(auctionId: bigint): Promise<boolean>;
+    getAuction(auctionId: bigint): Promise<AuctionData>;
+    getQuote(auctionId: bigint, amount: bigint): Promise<BuyQuote>;
+    getSpotPrice(auctionId: bigint): Promise<bigint>;
+    private parseAuctionResult;
+}
+
+declare const AUCTION_ADDRESSES: Record<SupportedChainId, Address>;
+declare const USDC_ADDRESSES: Record<SupportedChainId, Address>;
+
+/**
+ * Off-chain bonding curve calculations (mirrors BondingCurve.sol)
+ */
+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): {
+    cost: bigint;
+    fee: bigint;
+    total: bigint;
+    spotPriceAfter: bigint;
+};
+
+export { AUCTION_ADDRESSES, AuctionBuilder, type AuctionConfig, type AuctionData, AuctionFlowSDK, AuctionState, type BuyQuote, type SupportedChainId, type TransactionResult, USDC_ADDRESSES, calculateBuyCost, calculateBuyQuote, spotPrice };