@fepvenancio/stela-sdk 0.9.0 → 0.11.0

package/README.md

@@ -211,10 +211,19 @@ import {
 | `getInscriptionOrderTypedData(params)` | Build SNIP-12 typed data for a borrower's InscriptionOrder |
 | `getLendOfferTypedData(params)` | Build SNIP-12 typed data for a lender's LendOffer |
 | `getBatchLendOfferTypedData(params)` | Build SNIP-12 typed data for a lender's BatchLendOffer (multi-order settlement) |
+| `getCollectionLendOfferTypedData(params)` | Build SNIP-12 typed data for a collection-wide lending offer |
+| `getCollectionBorrowAcceptanceTypedData(params)` | Build SNIP-12 typed data for accepting a collection offer |
+| `getRenegotiationProposalTypedData(params)` | Build SNIP-12 typed data for a renegotiation proposal |
+| `getCollateralSaleOfferTypedData(params)` | Build SNIP-12 typed data for a collateral sale offer |
+| `getRefinanceOfferTypedData(params)` | Build SNIP-12 typed data for a refinance offer |
+| `getRefinanceApprovalTypedData(params)` | Build SNIP-12 typed data for approving a refinance |
+| `getTermsAcknowledgmentTypedData(params)` | Build SNIP-12 typed data for terms acknowledgment |
+| `getCancelOrderTypedData(orderId, chainId)` | Build SNIP-12 typed data for off-chain order cancellation |
 | `hashAssets(assets)` | Poseidon hash of an asset array (matches Cairo's `hash_assets()`) |
 | `hashBatchEntries(entries)` | Poseidon hash of BatchEntry array for batch_settle() |
 | `serializeSignature(sig)` | Convert `string[]` signature to `{ r, s }` for storage |
 | `deserializeSignature(stored)` | Convert `{ r, s }` back to `string[]` |
+| `getNonce(provider, stelaAddress, accountAddress)` | Read on-chain nonce via RPC (uses `latest` block) |
 
 ---
 
@@ -228,6 +237,11 @@ import {
   scaleByPercentage,
   sharesToPercentage,
   calculateFeeShares,
+  divCeil,
+  proRataInterest,
+  computeInterestRate,
+  computePositionValue,
+  computeSafePositionFloor,
 } from '@fepvenancio/stela-sdk'
 ```
 
@@ -237,6 +251,14 @@ import {
 | `scaleByPercentage(value, percentage)` | Scale a value by basis points |
 | `sharesToPercentage(shares, totalSupply, currentIssuedPercentage)` | Convert shares back to percentage |
 | `calculateFeeShares(shares, feeBps)` | Calculate fee portion of shares |
+| `divCeil(a, b)` | Ceiling division (rounds up) |
+| `proRataInterest(amount, elapsed, duration)` | Pro-rata interest with ceiling rounding |
+| `computeInterestRate(debtAssets, interestAssets)` | Interest/debt ratio (skips ERC721, returns `null` if zero debt) |
+| `shareProportionBps(shares, totalSupply)` | Share proportion in basis points |
+| `proportionalAssetValue(assetValue, shares, totalSupply)` | Asset value proportional to shares |
+| `computePositionValue(params)` | Full position valuation (debt, interest, collateral) |
+| `accruedInterestWithBuffer(amount, elapsed, duration, buffer?)` | Accrued interest + dust buffer |
+| `computeSafePositionFloor(params)` | Safe minimum price for buying shares |
 
 ---
 
@@ -281,11 +303,16 @@ import {
   toU256, fromU256, inscriptionIdToHex, toHex,
   formatAddress, normalizeAddress, addressesEqual,
   parseAmount, formatTokenValue,
-  formatDuration, formatTimestamp,
-  computeStatus,
+  formatDuration, formatTimestamp, formatDurationHuman,
+  computeStatus, enrichStatus,
+  normalizeOrderData, parseOrderRow,
+  formatSig, parseSigToArray,
+  serializeAssetCalldata, parseAssetArray, parseInscriptionCalldata,
 } from '@fepvenancio/stela-sdk'
 ```
 
+#### Address & Formatting
+
 | Function | Description |
 |----------|-------------|
 | `toU256(value)` | Convert bigint to `[low, high]` string pair for Cairo u256 |
@@ -293,13 +320,49 @@ import {
 | `inscriptionIdToHex(id)` | Format inscription ID as hex string |
 | `toHex(value)` | Convert bigint/number to hex string |
 | `formatAddress(address)` | Shorten an address for display (`0x1234...abcd`) |
-| `normalizeAddress(address)` | Strip leading zeros for consistent comparison |
+| `normalizeAddress(address)` | Pad and checksum an address |
 | `addressesEqual(a, b)` | Case-insensitive address comparison |
 | `parseAmount(value, decimals)` | Parse human-readable amount to bigint |
 | `formatTokenValue(value, decimals)` | Format bigint token value for display |
-| `formatDuration(seconds)` | Format seconds as human-readable duration |
+| `formatDuration(seconds)` | Format seconds as compact duration (`7d 0h`) |
 | `formatTimestamp(timestamp)` | Format unix timestamp as date string |
+| `formatDurationHuman(seconds)` | Format seconds as human-readable (`5 min`, `2 hours`, `7 days`) |
+
+#### Status Computation
+
+| Function | Description |
+|----------|-------------|
 | `computeStatus(input)` | Derive inscription status from on-chain fields |
+| `enrichStatus(row)` | Compute display status — distinguishes `overdue`, `grace_period`, `auctioned` from base `expired` |
+| `getStatusBadgeVariant(status)` | Map any status to a `StatusBadgeVariant` for UI |
+| `getStatusLabel(status)` | Human-readable label for any status (base + extended) |
+| `getOrderStatusBadgeVariant(status)` | Badge variant for off-chain order status |
+| `getOrderStatusLabel(status)` | Human-readable label for order status |
+| `inscriptionMatchesGroup(status, group)` | Check if inscription status belongs to filter group (`open`/`active`/`closed`/`all`) |
+| `orderMatchesGroup(status, group)` | Check if order status belongs to filter group |
+
+#### Order Data Parsing
+
+| Function | Description |
+|----------|-------------|
+| `normalizeOrderData(raw)` | Normalize camelCase/snake_case variants in order_data JSON |
+| `parseOrderRow(row)` | Parse D1 order row — sanitizes assets, strips signature for non-pending orders |
+
+#### Signature Utilities
+
+| Function | Description |
+|----------|-------------|
+| `formatSig(signature)` | Format wallet signature (array or `{r, s}`) to `string[]` — converts bigints to hex |
+| `parseSigToArray(raw)` | Parse stored signature (JSON array, JSON object, CSV, or string array) to `string[]` |
+
+#### Calldata Serialization
+
+| Function | Description |
+|----------|-------------|
+| `serializeAssetCalldata(assets)` | Serialize asset array to Cairo calldata `[len, ...fields]` |
+| `parseAssetArray(calldata, offset)` | Deserialize asset array from RPC calldata |
+| `parseInscriptionCalldata(calldata)` | Extract `{debt, interest, collateral}` from `create_inscription`/`settle` tx calldata |
+| `serializeSignatureCalldata(sig)` | Serialize signature string to calldata `[len, ...parts]` |
 
 ---
 
@@ -307,6 +370,8 @@ import {
 
 All exported types from the SDK:
 
+#### Core Protocol Types
+
 | Type | Description |
 |------|-------------|
 | `Network` | `'sepolia' \| 'mainnet'` |
@@ -319,54 +384,142 @@ All exported types from the SDK:
 | `Inscription` | Parsed inscription with computed status |
 | `SignedOrder` | Signed order for the matching engine |
 | `BatchEntry` | Entry in a batch settle (order hash + fill BPS) |
-| `InscriptionRow` | API response row for inscriptions |
-| `AssetRow` | API response row for assets |
+| `TokenInfo` | Token metadata (symbol, name, decimals, addresses) |
+| `StoredSignature` | Serialized signature for storage (`r:s`) |
+
+#### API / D1 Row Types
+
+| Type | Description |
+|------|-------------|
+| `InscriptionRow` | Inscription row (includes `auction_started`, `auction_start_time`) |
+| `InscriptionDetailResponse` | Detail response extending InscriptionRow |
+| `AssetRow` | Asset row (`debt` / `interest` / `collateral`) |
 | `ApiListResponse<T>` | Paginated list response envelope |
 | `ApiDetailResponse<T>` | Single item response envelope |
 | `TreasuryAsset` | Treasury asset balance |
 | `ShareBalance` | Share balance for an account |
-| `LockerInfo` | Locker information from the API |
-| `LockerState` | Locker address + unlock status |
-| `LockerCall` | Call to execute through a locker |
+| `LockerInfo` | Locker information |
+| `OrderStatus` | `'pending' \| 'matched' \| 'settled' \| 'expired' \| 'cancelled'` |
+| `OrderRow` | Off-chain order row from D1 |
+| `OrderOfferRow` | Lender offer row from D1 |
+| `CollectionOfferRow` | Collection-wide offer row from D1 |
+| `RefinanceRow` | Refinance offer row from D1 |
+| `RenegotiationRow` | Renegotiation proposal row from D1 |
+| `CollateralSaleRow` | Collateral sale offer row from D1 |
+| `ShareListingRow` | Secondary market share listing row |
+
+#### Order Book Types
+
+| Type | Description |
+|------|-------------|
+| `LendingLevel` | Price level in lending order book (APR, amount, orders) |
+| `SwapLevel` | Price level in swap order book (rate, amount, orders) |
+| `TokenDisplay` | Token display info (address, symbol, decimals, logoUrl) |
+| `OrderBookResponse` | Full order book response (pair, lending, swaps, recentFills) |
+| `DurationFilter` | `'all' \| '7d' \| '30d' \| '90d' \| '180d' \| '365d'` |
+
+#### Status & UI Types
+
+| Type | Description |
+|------|-------------|
+| `EnrichedStatus` | `InscriptionStatus \| 'overdue' \| 'grace_period' \| 'auctioned'` |
+| `StatusBadgeVariant` | Union of all inscription + order status strings for badge rendering |
+| `StatusInput` | Input for `computeStatus()` |
+
+#### Order Parsing Types
+
+| Type | Description |
+|------|-------------|
+| `SerializedAsset` | Asset in order_data JSON (string values) |
+| `RawOrderData` | Flexible order_data with camelCase/snake_case variants |
+| `ParsedOrderData` | Normalized order data output |
+| `StoredAsset` | Asset shape for calldata serialization |
+
+#### Preset Types
+
+| Type | Description |
+|------|-------------|
+| `DeadlinePreset` | `{ label: string, seconds: number }` |
+| `DurationPreset` | `{ label: string, seconds: number }` |
+
+#### Event Types
+
+| Type | Description |
+|------|-------------|
 | `RawEvent` | Raw StarkNet event (keys, data, tx_hash, block) |
 | `StelaEvent` | Discriminated union of all protocol events |
-| `InscriptionCreatedEvent` | InscriptionCreated event type |
-| `InscriptionSignedEvent` | InscriptionSigned event type |
-| `InscriptionCancelledEvent` | InscriptionCancelled event type |
-| `InscriptionRepaidEvent` | InscriptionRepaid event type |
-| `InscriptionLiquidatedEvent` | InscriptionLiquidated event type |
-| `SharesRedeemedEvent` | SharesRedeemed event type |
-| `TransferSingleEvent` | ERC1155 TransferSingle event type |
-| `OrderSettledEvent` | OrderSettled event type |
-| `OrderFilledEvent` | OrderFilled event type |
-| `OrderCancelledEvent` | OrderCancelled event type |
-| `OrdersBulkCancelledEvent` | OrdersBulkCancelled event type |
-| `TokenInfo` | Token metadata (symbol, name, decimals, addresses) |
-| `StatusInput` | Input for `computeStatus()` |
-| `StoredSignature` | Serialized signature for storage (`{ r, s }`) |
-| `InscriptionClientOptions` | Options for InscriptionClient constructor |
-| `ShareClientOptions` | Options for ShareClient constructor |
-| `ApiClientOptions` | Options for ApiClient constructor |
+| `InscriptionCreatedEvent` | InscriptionCreated event |
+| `InscriptionSignedEvent` | InscriptionSigned event |
+| `InscriptionCancelledEvent` | InscriptionCancelled event |
+| `InscriptionRepaidEvent` | InscriptionRepaid event |
+| `InscriptionLiquidatedEvent` | InscriptionLiquidated event |
+| `SharesRedeemedEvent` | SharesRedeemed event |
+| `TransferSingleEvent` | ERC1155 TransferSingle event |
+| `OrderSettledEvent` | OrderSettled event |
+| `OrderFilledEvent` | OrderFilled event |
+| `OrderCancelledEvent` | OrderCancelled event |
+| `OrdersBulkCancelledEvent` | OrdersBulkCancelled event |
+| `AuctionStartedEvent` | AuctionStarted event |
+| `AuctionBidEvent` | AuctionBid event |
+
+#### Client Types
+
+| Type | Description |
+|------|-------------|
+| `LockerState` | Locker address + unlock status |
+| `LockerCall` | Call to execute through a locker |
+| `InscriptionClientOptions` | Options for InscriptionClient |
+| `ShareClientOptions` | Options for ShareClient |
+| `ApiClientOptions` | Options for ApiClient |
 | `ListInscriptionsParams` | Parameters for `listInscriptions()` |
-| `InscriptionEventRow` | API response row for inscription events |
-| `StelaSdkOptions` | Options for StelaSdk constructor |
+| `InscriptionEventRow` | API response row for events |
+| `StelaSdkOptions` | Options for StelaSdk |
+| `AssetValue` | Asset with proportional value |
+| `AccruedInterestEntry` | Interest with full + accrued amounts |
+| `PositionValue` | Full position valuation result |
 
 ---
 
 ### Constants
 
+#### Protocol
+
 | Export | Description |
 |--------|-------------|
 | `STELA_ADDRESS` | Contract addresses per network (`{ sepolia, mainnet }`) |
 | `resolveNetwork(raw?)` | Validate/default network string |
-| `CHAIN_ID` | SNIP-12 chain ID shortstrings per network (`{ sepolia: 'SN_SEPOLIA', mainnet: 'SN_MAIN' }`) |
-| `EXPLORER_TX_URL` | Block explorer base URLs per network (for transaction links) |
+| `CHAIN_ID` | SNIP-12 chain ID shortstrings per network |
+| `EXPLORER_TX_URL` | Block explorer base URLs per network |
 | `MAX_BPS` | `10_000n` (100% in basis points) |
 | `VIRTUAL_SHARE_OFFSET` | `1e16n` (share calculation offset) |
 | `ASSET_TYPE_ENUM` | AssetType to numeric enum mapping |
 | `ASSET_TYPE_NAMES` | Numeric enum to AssetType mapping |
+| `GRACE_PERIOD` | `86400n` — 24h grace before auction |
+| `AUCTION_DURATION` | `86400n` — 24h Dutch auction |
+| `AUCTION_PENALTY_BPS` | `500n` — 5% penalty at auction start |
+| `AUCTION_RESERVE_BPS` | `1000n` — 10% auction floor |
+| `DEFAULT_DUST_BUFFER_SECONDS` | `60n` — dust buffer for position floor |
+
+#### Status
+
+| Export | Description |
+|--------|-------------|
 | `VALID_STATUSES` | Array of all valid inscription statuses |
-| `STATUS_LABELS` | Human-readable status labels |
+| `STATUS_LABELS` | Human-readable inscription status labels |
+| `ORDER_STATUS_LABELS` | Human-readable order status labels |
+| `INSCRIPTION_STATUS_GROUPS` | Status → filter group mapping (`open`/`active`/`closed`) |
+| `ORDER_STATUS_GROUPS` | Order status → filter group mapping |
+| `STATUS_DESCRIPTIONS` | Detailed tooltip text for each status |
+| `CONCEPT_DESCRIPTIONS` | Help text for protocol concepts (debt, interest, collateral, etc.) |
+
+#### Trade Presets
+
+| Export | Description |
+|--------|-------------|
+| `SWAP_DEADLINE_PRESETS` | `DeadlinePreset[]` — 5m to 30d |
+| `LEND_DEADLINE_PRESETS` | `DeadlinePreset[]` — 7d to 90d |
+| `DURATION_PRESETS` | `DurationPreset[]` — 1d to 1y |
+| `DURATION_RANGES` | `Record<DurationFilter, [min, max] \| null>` — filter to seconds mapping |
 
 ### Classes