@fepvenancio/stela-sdk 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -98,6 +98,8 @@ interface InscriptionRow {
     interest_asset_count: number;
     collateral_asset_count: number;
     created_at_ts: string;
+    auction_started: number;
+    auction_start_time: string;
     assets: AssetRow[];
 }
 /** Asset row shape from the inscription_assets table */
@@ -141,6 +143,199 @@ interface LockerInfo {
     locker_address: string;
     is_unlocked: boolean;
 }
+/** Response shape for GET /api/inscriptions/[id] */
+interface InscriptionDetailResponse extends InscriptionRow {
+    assets: AssetRow[];
+}
+/** Collection offer row from D1 */
+interface CollectionOfferRow {
+    id: string;
+    lender: string;
+    collection_address: string;
+    order_data: Record<string, unknown>;
+    lender_signature: string;
+    nonce: string;
+    status: string;
+    deadline: string;
+    created_at: string;
+    debt_token: string | null;
+    collateral_token: string | null;
+    acceptance?: {
+        borrower: string;
+        token_id: string;
+        borrower_signature: string;
+        nonce: string;
+    };
+}
+/** Refinance offer row from D1 */
+interface RefinanceRow {
+    id: string;
+    inscription_id: string;
+    new_lender: string;
+    order_data: Record<string, unknown>;
+    lender_signature: string;
+    nonce: string;
+    status: string;
+    deadline: string;
+    created_at: string;
+    approval?: {
+        borrower: string;
+        borrower_signature: string;
+        nonce: string;
+    };
+}
+/** Renegotiation proposal row from D1 */
+interface RenegotiationRow {
+    id: string;
+    inscription_id: string;
+    proposer: string;
+    proposal_data: Record<string, unknown>;
+    proposer_signature: string;
+    nonce: string;
+    status: string;
+    deadline: string;
+    created_at: string;
+}
+/** Collateral sale row from D1 */
+interface CollateralSaleRow {
+    id: string;
+    inscription_id: string;
+    buyer: string;
+    offer_data: Record<string, unknown>;
+    borrower_signature: string;
+    min_price: string;
+    status: string;
+    deadline: string;
+    created_at: string;
+}
+/** Off-chain order status */
+type OrderStatus = 'pending' | 'matched' | 'settled' | 'expired' | 'cancelled';
+/** Off-chain order row from D1 */
+interface OrderRow {
+    id: string;
+    borrower: string;
+    order_data: Record<string, unknown> | string;
+    borrower_signature: string | null;
+    nonce: string;
+    status: string;
+    deadline: string;
+    created_at: string;
+}
+/** Lender offer row from D1 */
+interface OrderOfferRow {
+    id: string;
+    order_id: string;
+    lender: string;
+    bps: number;
+    lender_signature: string | null;
+    nonce: string;
+    status: string;
+    created_at: string;
+    tx_hash: string | null;
+}
+/** Share listing row from D1 (secondary market) */
+interface ShareListingRow {
+    id: string;
+    inscription_id: string;
+    seller: string;
+    shares: string;
+    ask_price: string;
+    ask_token: string;
+    status: string;
+    created_at: string;
+}
+
+/** Order book types — shared between API and UI */
+/** A single price level in the lending order book */
+interface LendingLevel {
+    /** Annualized percentage rate for this level */
+    apr: number;
+    /** Total debt amount available at this APR (raw string for BigInt compat) */
+    totalAmount: string;
+    /** Number of orders at this level */
+    orderCount: number;
+    /** Running cumulative total from best to worst */
+    cumulative: string;
+    /** Individual orders at this level */
+    orders: {
+        id: string;
+        amount: string;
+        creator: string;
+        source: 'offchain' | 'onchain';
+        duration: number;
+        multiLender: boolean;
+        deadline: number;
+        interestAmount: string;
+        interestSymbol: string;
+        interestDecimals: number;
+    }[];
+}
+/** A single price level in the swap order book */
+interface SwapLevel {
+    /** Exchange rate: units of quote per unit of base */
+    rate: number;
+    /** Total base amount available at this rate */
+    totalAmount: string;
+    /** Number of orders at this level */
+    orderCount: number;
+    /** Running cumulative total from best to worst */
+    cumulative: string;
+    /** Individual orders */
+    orders: {
+        id: string;
+        amount: string;
+        creator: string;
+        source: 'offchain' | 'onchain';
+        deadline: number;
+    }[];
+}
+/** Token info for display in order book context */
+interface TokenDisplay {
+    address: string;
+    symbol: string;
+    decimals: number;
+    logoUrl?: string;
+}
+/** Full order book response from API */
+interface OrderBookResponse {
+    pair: {
+        base: TokenDisplay;
+        quote: TokenDisplay;
+    };
+    /** Available duration values for lending orders */
+    durations: number[];
+    /** Lending order book (duration > 0) */
+    lending: {
+        /** Borrow requests — sorted highest APR first (best for lenders) */
+        asks: LendingLevel[];
+        /** Total borrow demand */
+        totalAskVolume: string;
+    };
+    /** Swap order book (duration = 0) */
+    swaps: {
+        /** Sell base (want quote) — sorted lowest rate first */
+        asks: SwapLevel[];
+        /** Buy base (want base, pay quote) — sorted highest rate first */
+        bids: SwapLevel[];
+        totalAskVolume: string;
+        totalBidVolume: string;
+    };
+    /** Recently settled/filled orders */
+    recentFills: {
+        id: string;
+        apr: number;
+        rate: number;
+        amount: string;
+        duration: number;
+        filledAt: number;
+        source: 'offchain' | 'onchain';
+        type: 'lending' | 'swap';
+    }[];
+}
+/** Duration filter options */
+type DurationFilter = 'all' | '7d' | '30d' | '90d' | '180d' | '365d';
+/** Duration filter to seconds mapping */
+declare const DURATION_RANGES: Record<DurationFilter, [number, number] | null>;
 
 /** Raw event as returned from StarkNet RPC */
 interface RawEvent {
@@ -309,6 +504,37 @@ declare const AUCTION_PENALTY_BPS = 500n;
 /** Minimum auction price as percentage of debt (10% floor in BPS) */
 declare const AUCTION_RESERVE_BPS = 1000n;
 
+/**
+ * Trade UI presets for deadlines and durations.
+ *
+ * Shared between frontend (form dropdowns) and backend (validation bounds).
+ * Does NOT import any framework-specific code.
+ */
+interface DeadlinePreset {
+    label: string;
+    seconds: number;
+}
+interface DurationPreset {
+    label: string;
+    seconds: number;
+}
+/** Short-lived deadline options used on the Swap form. */
+declare const SWAP_DEADLINE_PRESETS: DeadlinePreset[];
+/** Longer-lived deadline options used on the Lend / Borrow form. */
+declare const LEND_DEADLINE_PRESETS: DeadlinePreset[];
+/** Loan duration options (how long the borrower has to repay). */
+declare const DURATION_PRESETS: DurationPreset[];
+/**
+ * Convert a duration in seconds to a short human-readable string.
+ *
+ * @example
+ * formatDurationHuman(300)       // "5 min"
+ * formatDurationHuman(7200)      // "2 hours"
+ * formatDurationHuman(86400)     // "1 day"
+ * formatDurationHuman(604800)    // "7 days"
+ */
+declare function formatDurationHuman(seconds: number): string;
+
 /** Convert a bigint to a [low, high] calldata pair for StarkNet u256 */
 declare const toU256: (n: bigint) => [string, string];
 /** Convert a { low, high } u256 pair back to a bigint */
@@ -353,6 +579,140 @@ interface StatusInput {
 }
 /** Compute the inscription status from on-chain fields */
 declare function computeStatus(a: StatusInput, nowSeconds?: number): InscriptionStatus;
+/** Enriched status includes display-only states not in InscriptionStatus */
+type EnrichedStatus = InscriptionStatus | 'overdue' | 'grace_period' | 'auctioned';
+/** Badge variant type for UI — union of inscription + order statuses */
+type StatusBadgeVariant = 'open' | 'partial' | 'filled' | 'repaid' | 'liquidated' | 'expired' | 'overdue' | 'cancelled' | 'pending' | 'matched' | 'settled' | 'auctioned' | 'grace_period';
+/** Map any status string to a valid badge variant, defaulting to 'open'. */
+declare function getStatusBadgeVariant(status: string): StatusBadgeVariant;
+/** Map any status string to its human-readable label. */
+declare function getStatusLabel(status: string): string;
+/** Human-readable labels for off-chain order statuses */
+declare const ORDER_STATUS_LABELS: Record<string, string>;
+/** Map off-chain order status to its own badge variant. */
+declare function getOrderStatusBadgeVariant(status: string): StatusBadgeVariant;
+/** Get the human-readable label for an off-chain order status. */
+declare function getOrderStatusLabel(status: string): string;
+/** Enriched inscription statuses that belong to each filter group. */
+declare const INSCRIPTION_STATUS_GROUPS: Record<string, Set<string>>;
+/** Off-chain order statuses that belong to each filter group. */
+declare const ORDER_STATUS_GROUPS: Record<string, Set<string>>;
+/** Check if an enriched inscription status belongs to a filter group. */
+declare function inscriptionMatchesGroup(enrichedStatus: string, group: string): boolean;
+/** Check if an order status belongs to a filter group. */
+declare function orderMatchesGroup(orderStatus: string, group: string): boolean;
+/** Detailed status descriptions for UI tooltips */
+declare const STATUS_DESCRIPTIONS: Record<string, string>;
+/** Concept descriptions for UI help text */
+declare const CONCEPT_DESCRIPTIONS: Record<string, string>;
+/**
+ * Enrich an InscriptionRow with a client-side computed status.
+ * Distinguishes "overdue" (filled past duration) from "expired" (unfilled past deadline),
+ * and detects "grace_period" and "auctioned" states.
+ */
+declare function enrichStatus(row: {
+    status: string;
+    signed_at: string | null;
+    duration: string;
+    issued_debt_percentage: string;
+    deadline: string;
+    auction_started?: number;
+}): EnrichedStatus;
+
+/**
+ * Shared order data parsing utilities.
+ *
+ * Used by API routes (server) and UI components (client) to normalize
+ * the flexible order_data JSON from D1 into a consistent shape.
+ */
+interface SerializedAsset {
+    asset_address: string;
+    asset_type: string;
+    value: string;
+    token_id: string;
+}
+interface RawOrderData {
+    borrower?: string;
+    debt_assets?: SerializedAsset[];
+    interest_assets?: SerializedAsset[];
+    collateral_assets?: SerializedAsset[];
+    debtAssets?: SerializedAsset[];
+    interestAssets?: SerializedAsset[];
+    collateralAssets?: SerializedAsset[];
+    multi_lender?: boolean;
+    multiLender?: boolean;
+    duration?: string;
+    deadline?: string;
+    nonce?: string;
+    orderHash?: string;
+}
+interface ParsedOrderData {
+    borrower: string;
+    debtAssets: SerializedAsset[];
+    interestAssets: SerializedAsset[];
+    collateralAssets: SerializedAsset[];
+    duration: string;
+    deadline: string;
+    multiLender: boolean;
+}
+/** Normalize camelCase/snake_case variants in order_data JSON. */
+declare function normalizeOrderData(raw: RawOrderData): ParsedOrderData;
+/**
+ * Parse the order_data TEXT column from D1 into a proper object.
+ * Shared between GET /api/orders and GET /api/orders/[id].
+ *
+ * - Parses JSON string or passes through object
+ * - Sanitizes asset arrays
+ * - Only includes borrower_signature for pending orders
+ */
+declare function parseOrderRow(row: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * Shared signature utilities for parsing and formatting StarkNet signatures.
+ *
+ * Used by settlement hooks, API routes, and UI components to normalize
+ * the various wallet signature formats into consistent string arrays.
+ */
+/**
+ * Format a wallet signature response (array or {r, s} object) into a string array.
+ * Converts bigint values to hex strings.
+ */
+declare function formatSig(signature: unknown): string[];
+/**
+ * Parse a stored signature (string, JSON string, or string array) into a string array.
+ * Handles formats: `[r, s]` array, `"[r, s]"` JSON, `"{r, s}"` JSON object, `"r,s"` CSV.
+ */
+declare function parseSigToArray(raw: string | string[]): string[];
+
+/**
+ * Calldata serialization/deserialization for StarkNet transactions.
+ *
+ * Used by the indexer (parsing tx calldata) and settlement bot
+ * (building calldata for create_inscription / settle / batch_settle).
+ */
+
+/** Asset shape used in calldata serialization (string values, not bigint) */
+interface StoredAsset {
+    asset_address: string;
+    asset_type: AssetType;
+    value: string;
+    token_id: string;
+}
+/** Serialize an asset array into calldata: [len, ...per-asset fields] */
+declare function serializeAssetCalldata(assets: StoredAsset[]): string[];
+/** Parse an asset array from raw RPC calldata */
+declare function parseAssetArray(calldata: string[], offset: number): {
+    assets: StoredAsset[];
+    nextOffset: number;
+};
+/** Serialize a signature string "r,s" or JSON [r, s] into calldata: [len, ...parts] */
+declare function serializeSignatureCalldata(sig: string): string[];
+/** Extract and parse inscription assets from transaction calldata */
+declare function parseInscriptionCalldata(calldata: string[]): {
+    debt: StoredAsset[];
+    interest: StoredAsset[];
+    collateral: StoredAsset[];
+} | null;
 
 interface TokenInfo {
     symbol: string;
@@ -507,6 +867,19 @@ declare function computeSafePositionFloor(params: {
     interestFloor: AssetValue[];
 };
 
+/**
+ * Compute interest rate as a ratio of interest value to debt value.
+ * Skips ERC721 assets (no fungible value). Returns null if debt total is zero.
+ * Used by both the settlement bot (priority) and frontend (rank display).
+ */
+declare function computeInterestRate(debtAssets: {
+    asset_type: string;
+    value: string;
+}[], interestAssets: {
+    asset_type: string;
+    value: string;
+}[]): number | null;
+
 /** Event selectors for all Stela protocol events */
 declare const SELECTORS: {
     readonly InscriptionCreated: string;
@@ -552,6 +925,14 @@ declare function hashBatchEntries(entries: BatchEntry[]): string;
  */
 declare function hashAssets(assets: Asset[]): string;
 
+/**
+ * Build SNIP-12 typed data for an order cancellation.
+ *
+ * The borrower signs this to prove they want to cancel their order.
+ * Both client and server must produce the same typed data to agree
+ * on the message hash that gets verified via is_valid_signature.
+ */
+declare function getCancelOrderTypedData(orderId: string, chainId: string): TypedData;
 /**
  * Build SNIP-12 TypedData for a borrower's InscriptionOrder.
  * The borrower signs this off-chain to create an order without gas.
@@ -674,6 +1055,18 @@ declare function getRefinanceApprovalTypedData(params: {
     nonce: bigint;
     chainId: string;
 }): TypedData;
+/**
+ * Build SNIP-12 TypedData for a terms-of-use acknowledgment.
+ * The user signs this off-chain to prove they accepted the protocol terms.
+ * NOT verified on-chain — stored off-chain as proof of consent.
+ */
+declare function getTermsAcknowledgmentTypedData(params: {
+    user: string;
+    termsVersion: string;
+    termsHash: string;
+    agreedAt: bigint;
+    chainId: string;
+}): TypedData;
 
 /**
  * Serialize a starknet.js signature (Signature type) for storage in D1.
@@ -1089,4 +1482,14 @@ declare class StelaSdk {
     constructor(opts: StelaSdkOptions);
 }
 
-export { ASSET_TYPE_ENUM, ASSET_TYPE_NAMES, AUCTION_DURATION, AUCTION_PENALTY_BPS, AUCTION_RESERVE_BPS, type AccruedInterestEntry, ApiClient, type ApiClientOptions, type ApiDetailResponse, ApiError, type ApiListResponse, type Asset, type AssetRow, type AssetType, type AssetValue, type AuctionBidEvent, type AuctionStartedEvent, type BatchEntry, CHAIN_ID, type Call, DEFAULT_DUST_BUFFER_SECONDS, EXPLORER_TX_URL, GRACE_PERIOD, type Inscription, type InscriptionCancelledEvent, InscriptionClient, type InscriptionClientOptions, type InscriptionCreatedEvent, type InscriptionEventRow, type InscriptionLiquidatedEvent, type InscriptionParams, type InscriptionRepaidEvent, type InscriptionRow, type InscriptionSignedEvent, type InscriptionStatus, type ListInscriptionsParams, type LockerCall, LockerClient, type LockerInfo, type LockerState, MAX_BPS, type Network, type OrderCancelledEvent, type OrderFilledEvent, type OrderSettledEvent, type OrdersBulkCancelledEvent, type PositionValue, type RawEvent, SELECTORS, STATUS_LABELS, STELA_ADDRESS, type ShareBalance, ShareClient, type ShareClientOptions, type SharesRedeemedEvent, type SignedOrder, type StatusInput, type StelaEvent, StelaSdk, type StelaSdkOptions, type StoredInscription, type StoredSignature, TOKENS, type TokenInfo, type TransferSingleEvent, type TreasuryAsset, VALID_STATUSES, VIRTUAL_SHARE_OFFSET, accruedInterestWithBuffer, addressesEqual, calculateFeeShares, computePositionValue, computeSafePositionFloor, computeStatus, convertToShares, deserializeSignature, divCeil, findTokenByAddress, formatAddress, formatDuration, formatTimestamp, formatTokenValue, fromU256, getBatchLendOfferTypedData, getCollateralSaleOfferTypedData, getCollectionBorrowAcceptanceTypedData, getCollectionLendOfferTypedData, getInscriptionOrderTypedData, getLendOfferTypedData, getNFTCollections, getRefinanceApprovalTypedData, getRefinanceOfferTypedData, getRenegotiationProposalTypedData, getTokensForNetwork, hashAssets, hashBatchEntries, inscriptionIdToHex, normalizeAddress, parseAmount, parseEvent, parseEvents, proRataInterest, proportionalAssetValue, resolveNetwork, scaleByPercentage, serializeSignature, shareProportionBps, sharesToPercentage, toHex, toU256 };
+/**
+ * Read the on-chain nonce for an address from the Stela contract.
+ *
+ * Uses 'latest' block — Cartridge RPC does not support 'pending'.
+ * All nonce reads (frontend, server verify, API route) MUST use the same
+ * block tag. The server-side processCreateOrder has a grace window to
+ * account for nonces consumed in recent blocks not yet in 'latest'.
+ */
+declare function getNonce(provider: RpcProvider, stelaAddress: string, accountAddress: string): Promise<bigint>;
+
+export { ASSET_TYPE_ENUM, ASSET_TYPE_NAMES, AUCTION_DURATION, AUCTION_PENALTY_BPS, AUCTION_RESERVE_BPS, type AccruedInterestEntry, ApiClient, type ApiClientOptions, type ApiDetailResponse, ApiError, type ApiListResponse, type Asset, type AssetRow, type AssetType, type AssetValue, type AuctionBidEvent, type AuctionStartedEvent, type BatchEntry, CHAIN_ID, CONCEPT_DESCRIPTIONS, type Call, type CollateralSaleRow, type CollectionOfferRow, DEFAULT_DUST_BUFFER_SECONDS, DURATION_PRESETS, DURATION_RANGES, type DeadlinePreset, type DurationFilter, type DurationPreset, EXPLORER_TX_URL, type EnrichedStatus, GRACE_PERIOD, INSCRIPTION_STATUS_GROUPS, type Inscription, type InscriptionCancelledEvent, InscriptionClient, type InscriptionClientOptions, type InscriptionCreatedEvent, type InscriptionDetailResponse, type InscriptionEventRow, type InscriptionLiquidatedEvent, type InscriptionParams, type InscriptionRepaidEvent, type InscriptionRow, type InscriptionSignedEvent, type InscriptionStatus, LEND_DEADLINE_PRESETS, type LendingLevel, type ListInscriptionsParams, type LockerCall, LockerClient, type LockerInfo, type LockerState, MAX_BPS, type Network, ORDER_STATUS_GROUPS, ORDER_STATUS_LABELS, type OrderBookResponse, type OrderCancelledEvent, type OrderFilledEvent, type OrderOfferRow, type OrderRow, type OrderSettledEvent, type OrderStatus, type OrdersBulkCancelledEvent, type ParsedOrderData, type PositionValue, type RawEvent, type RawOrderData, type RefinanceRow, type RenegotiationRow, SELECTORS, STATUS_DESCRIPTIONS, STATUS_LABELS, STELA_ADDRESS, SWAP_DEADLINE_PRESETS, type SerializedAsset, type ShareBalance, ShareClient, type ShareClientOptions, type ShareListingRow, type SharesRedeemedEvent, type SignedOrder, type StatusBadgeVariant, type StatusInput, type StelaEvent, StelaSdk, type StelaSdkOptions, type StoredAsset, type StoredInscription, type StoredSignature, type SwapLevel, TOKENS, type TokenDisplay, type TokenInfo, type TransferSingleEvent, type TreasuryAsset, VALID_STATUSES, VIRTUAL_SHARE_OFFSET, accruedInterestWithBuffer, addressesEqual, calculateFeeShares, computeInterestRate, computePositionValue, computeSafePositionFloor, computeStatus, convertToShares, deserializeSignature, divCeil, enrichStatus, findTokenByAddress, formatAddress, formatDuration, formatDurationHuman, formatSig, formatTimestamp, formatTokenValue, fromU256, getBatchLendOfferTypedData, getCancelOrderTypedData, getCollateralSaleOfferTypedData, getCollectionBorrowAcceptanceTypedData, getCollectionLendOfferTypedData, getInscriptionOrderTypedData, getLendOfferTypedData, getNFTCollections, getNonce, getOrderStatusBadgeVariant, getOrderStatusLabel, getRefinanceApprovalTypedData, getRefinanceOfferTypedData, getRenegotiationProposalTypedData, getStatusBadgeVariant, getStatusLabel, getTermsAcknowledgmentTypedData, getTokensForNetwork, hashAssets, hashBatchEntries, inscriptionIdToHex, inscriptionMatchesGroup, normalizeAddress, normalizeOrderData, orderMatchesGroup, parseAmount, parseAssetArray, parseEvent, parseEvents, parseInscriptionCalldata, parseOrderRow, parseSigToArray, proRataInterest, proportionalAssetValue, resolveNetwork, scaleByPercentage, serializeAssetCalldata, serializeSignature, serializeSignatureCalldata, shareProportionBps, sharesToPercentage, toHex, toU256 };