@hammerock/cca-sdk 0.1.0

package/dist/erc20-C3yff839.d.ts

@@ -0,0 +1,231 @@
+import { PublicClient, Chain, Address, Hex } from 'viem';
+
+interface BeaconClientConfig {
+    /** JSON-RPC endpoint used for state reads (eth_call, multicall). */
+    rpcUrl: string;
+    /**
+     * Optional separate endpoint for `eth_getLogs`.
+     *
+     * State reads and log scanning have different provider requirements, and one
+     * endpoint is often bad at one of them. Alchemy's free tier serves eth_call
+     * beautifully but caps eth_getLogs at a 10-block range, which makes a
+     * historical backfill impossible; public wide-range endpoints allow the range
+     * but can silently return empty results. Defaults to `rpcUrl`.
+     */
+    logsRpcUrl?: string;
+    /** Chain id. Must be a supported testnet - mainnet is rejected. */
+    chainId: number;
+    /** Override the factory address. Defaults to the cross-chain singleton. */
+    factoryAddress?: Address;
+    /**
+     * Address of a deployed `AuctionStateLens`.
+     *
+     * Optional. When omitted, reads run the lens via an `eth_call` state
+     * override instead, so no deployment is required. See `read.ts`.
+     */
+    lensAddress?: Address;
+    /** Override the block the factory was deployed at. */
+    factoryDeployBlock?: bigint;
+}
+interface BeaconClient {
+    publicClient: PublicClient;
+    /** Client used for `eth_getLogs`. Same as `publicClient` unless overridden. */
+    logsClient: PublicClient;
+    chain: Chain;
+    chainId: number;
+    factoryAddress: Address;
+    lensAddress?: Address;
+    factoryDeployBlock: bigint;
+    /** Approximate seconds per block, for time-remaining estimates. */
+    blockTimeSeconds: number;
+}
+/**
+ * Throw unless `chainId` is a testnet Beacon supports.
+ *
+ * This is the choke point that keeps every Beacon surface off mainnet. The
+ * bidding agent layers its own guard on top before it broadcasts anything.
+ */
+declare function assertSupportedChain(chainId: number): Chain;
+/** Build a Beacon client. Throws immediately on a non-testnet chain id. */
+declare function createBeaconClient(config: BeaconClientConfig): BeaconClient;
+/**
+ * Confirm the RPC is actually serving the chain we were configured for.
+ *
+ * Cheap insurance against a copy-pasted RPC URL silently pointing at the wrong
+ * network - which otherwise shows up as "no auctions found".
+ */
+declare function assertChainMatches(client: BeaconClient): Promise<void>;
+
+/**
+ * Types mirrored from Uniswap/continuous-clearing-auction @ v1.1.0.
+ *
+ * Field names follow the contracts, with an explicit `Q96` / `X7` suffix added
+ * where the contract encodes a fixed-point value, so callers cannot mistake a
+ * Q96 price for a plain integer. Use the helpers in `q96.ts` to convert.
+ */
+
+/**
+ * A checkpoint of auction state at a given block.
+ * Mirrors `struct Checkpoint` in `libraries/CheckpointLib.sol`.
+ */
+interface Checkpoint {
+    /** Price the auction is currently clearing at, Q96-encoded. */
+    clearingPriceQ96: bigint;
+    /** Currency raised so far at the clearing price. Q96, then X7-scaled. */
+    currencyRaisedAtClearingPriceQ96X7: bigint;
+    /** Running sum of the ratio between mps and price. */
+    cumulativeMpsPerPrice: bigint;
+    /**
+     * How much of the auction's supply SCHEDULE has been released so far, in
+     * milli-bips out of `MPS` (1e7).
+     *
+     * This is emphatically NOT "tokens sold": an auction that ended with zero
+     * bids still reports `cumulativeMps == MPS`, because the schedule fully
+     * elapsed. Use `totalCleared` / `currencyRaised` for what actually sold.
+     */
+    cumulativeMps: number;
+    /** Block number of the previous checkpoint. */
+    prevBlock: bigint;
+    /** Block number of the next checkpoint. */
+    nextBlock: bigint;
+}
+/**
+ * The auction's live state.
+ * Mirrors `struct AuctionState` returned by `AuctionStateLens.state()`.
+ */
+interface AuctionState {
+    checkpoint: Checkpoint;
+    /** Total currency raised, in the currency's smallest unit. */
+    currencyRaised: bigint;
+    /** Total token supply cleared so far, in the token's smallest unit. */
+    totalCleared: bigint;
+    /** Whether the auction raised enough to seed the pool. */
+    isGraduated: boolean;
+}
+/**
+ * Immutable-ish configuration of an auction, read once and safe to cache.
+ */
+interface AuctionInfo {
+    auction: Address;
+    /** The token being sold. */
+    token: Address;
+    /** The currency bids are denominated in. `address(0)` means native ETH. */
+    currency: Address;
+    /** Total token supply offered by the auction. */
+    totalSupply: bigint;
+    /** Block the auction opens for bids. */
+    startBlock: bigint;
+    /** Block the auction closes. */
+    endBlock: bigint;
+    /** Lowest price the auction will clear at, Q96-encoded. */
+    floorPriceQ96: bigint;
+    /** Spacing between initialised price ticks. */
+    tickSpacing: bigint;
+}
+/** Lifecycle position of an auction relative to the current block. */
+type AuctionStatus = "pending" | "live" | "ended";
+/**
+ * Everything a UI needs about one auction: static config, live state, and the
+ * derived values that would otherwise be recomputed in four places.
+ */
+interface AuctionSummary {
+    info: AuctionInfo;
+    state: AuctionState;
+    /** Block this summary was read at. */
+    blockNumber: bigint;
+    status: AuctionStatus;
+    /** Clearing price as a display string. */
+    clearingPrice: string;
+    /**
+     * Fraction of the supply schedule released so far, in [0, 1].
+     * Not the fraction sold - see `Checkpoint.cumulativeMps`.
+     */
+    supplyScheduleProgress: number;
+    /** Whether anything has actually cleared. `totalCleared > 0`. */
+    hasClearedSupply: boolean;
+    /**
+     * Blocks until the auction ends. `0n` once ended, and counts down to the
+     * START block while the auction is still pending.
+     */
+    blocksRemaining: bigint;
+    /** Estimated seconds remaining, from `blocksRemaining` and the chain's block time. */
+    secondsRemaining: number;
+}
+/**
+ * One `AuctionCreated` event from the factory.
+ * Mirrors `event AuctionCreated(address indexed auction, address indexed token, uint256 amount, bytes configData)`.
+ */
+interface DiscoveredAuction {
+    /** The newly created ContinuousClearingAuction. */
+    auction: Address;
+    /** The token being auctioned. */
+    token: Address;
+    /** Token amount supplied to the auction. */
+    amount: bigint;
+    /** ABI-encoded `AuctionParameters` the auction was configured with. */
+    configData: Hex;
+    blockNumber: bigint;
+    transactionHash: Hex;
+    logIndex: number;
+}
+
+/** ERC-20 reads Beacon needs. Hand-written because it is the standard, not a CCA ABI. */
+declare const erc20MetadataAbi: readonly [{
+    readonly type: "function";
+    readonly name: "symbol";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "name";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "decimals";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint8";
+    }];
+    readonly stateMutability: "view";
+}];
+interface TokenMetadata {
+    address: Address;
+    symbol: string;
+    name: string;
+    decimals: number;
+    /** True when this is the chain's native currency rather than an ERC-20. */
+    isNative: boolean;
+}
+/**
+ * Read a currency's symbol, name and decimals.
+ *
+ * `address(0)` is the CCA sentinel for native currency, and resolves to the
+ * chain's own native currency rather than an on-chain call.
+ *
+ * Tolerant by design: a token that omits `symbol`/`name` (or returns bytes32
+ * instead of string) still yields usable metadata rather than throwing, because
+ * failing to render an alert is worse than rendering a shortened address.
+ */
+declare function getTokenMetadata(client: BeaconClient, address: Address): Promise<TokenMetadata>;
+/** Read metadata for several currencies at once, de-duplicated by address. */
+declare function getTokenMetadataBatch(client: BeaconClient, addresses: readonly Address[]): Promise<Map<Address, TokenMetadata>>;
+/**
+ * Render a raw token amount with its symbol, e.g. `"1,000 BEACON"`.
+ *
+ * A nonzero amount is NEVER rendered as "0". Real CCA test auctions raise
+ * amounts like 52 wei, and truncating those to "0 ETH" makes a live auction
+ * look dead. When an amount is too small for `maxFractionDigits`, the output
+ * widens to show four significant digits instead.
+ *
+ * @param maxFractionDigits Fractional digits to keep for ordinary amounts.
+ */
+declare function formatTokenAmount(amount: bigint, token: Pick<TokenMetadata, "symbol" | "decimals">, maxFractionDigits?: number): string;
+
+export { type AuctionInfo as A, type BeaconClient as B, type Checkpoint as C, type DiscoveredAuction as D, type TokenMetadata as T, type AuctionStatus as a, type AuctionState as b, type AuctionSummary as c, type BeaconClientConfig as d, assertChainMatches as e, assertSupportedChain as f, createBeaconClient as g, erc20MetadataAbi as h, formatTokenAmount as i, getTokenMetadata as j, getTokenMetadataBatch as k };