@fepvenancio/stela-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,496 @@
+import { RpcProvider, Account, Contract } from 'starknet';
+
+/** Supported StarkNet networks */
+type Network = 'sepolia' | 'mainnet';
+/** Token standard types supported by the Stela protocol */
+type AssetType = 'ERC20' | 'ERC721' | 'ERC1155' | 'ERC4626';
+/** Possible states of an inscription */
+type InscriptionStatus = 'open' | 'partial' | 'filled' | 'repaid' | 'liquidated' | 'expired' | 'cancelled';
+/** All valid inscription statuses as an array */
+declare const VALID_STATUSES: readonly InscriptionStatus[];
+/** Human-readable labels for each inscription status */
+declare const STATUS_LABELS: Record<InscriptionStatus, string>;
+/** A single StarkNet call (matches starknet.js Call type) */
+interface Call {
+    contractAddress: string;
+    entrypoint: string;
+    calldata: string[];
+}
+
+/** An asset within an inscription (matches the Cairo Asset struct) */
+interface Asset {
+    /** Contract address of the token */
+    asset_address: string;
+    /** Token standard */
+    asset_type: AssetType;
+    /** Token amount (ERC20/ERC1155/ERC4626) */
+    value: bigint;
+    /** Token ID (ERC721/ERC1155) */
+    token_id: bigint;
+}
+/** Parameters for creating a new inscription (matches Cairo InscriptionParams) */
+interface InscriptionParams {
+    is_borrow: boolean;
+    debt_assets: Asset[];
+    interest_assets: Asset[];
+    collateral_assets: Asset[];
+    /** Duration in seconds */
+    duration: bigint;
+    /** Deadline as unix timestamp (seconds) */
+    deadline: bigint;
+    multi_lender: boolean;
+}
+/** Raw inscription data as stored on-chain (matches Cairo StoredInscription) */
+interface StoredInscription {
+    borrower: string;
+    lender: string;
+    duration: bigint;
+    deadline: bigint;
+    signed_at: bigint;
+    issued_debt_percentage: bigint;
+    is_repaid: boolean;
+    liquidated: boolean;
+    multi_lender: boolean;
+    debt_asset_count: number;
+    interest_asset_count: number;
+    collateral_asset_count: number;
+}
+/** Parsed inscription with computed status and ID */
+interface Inscription extends StoredInscription {
+    id: string;
+    status: InscriptionStatus;
+}
+
+/** Row shape returned by the /api/inscriptions list endpoint */
+interface InscriptionRow {
+    id: string;
+    creator: string;
+    borrower: string | null;
+    lender: string | null;
+    status: string;
+    issued_debt_percentage: string;
+    multi_lender: boolean;
+    duration: string;
+    deadline: string;
+    signed_at: string | null;
+    debt_asset_count: number;
+    interest_asset_count: number;
+    collateral_asset_count: number;
+    created_at_ts: string;
+    assets: AssetRow[];
+}
+/** Asset row shape from the inscription_assets table */
+interface AssetRow {
+    inscription_id: string;
+    asset_role: 'debt' | 'interest' | 'collateral';
+    asset_index: number;
+    asset_address: string;
+    asset_type: string;
+    value: string | null;
+    token_id: string | null;
+}
+/** Standard API response envelope for list endpoints */
+interface ApiListResponse<T> {
+    data: T[];
+    meta: {
+        page: number;
+        limit: number;
+        total: number;
+    };
+}
+/** Standard API response envelope for detail endpoints */
+interface ApiDetailResponse<T> {
+    data: T;
+}
+/** Treasury asset balance info */
+interface TreasuryAsset {
+    asset_address: string;
+    asset_type: string;
+    balance: string;
+}
+/** ERC1155 share balance for a lender on an inscription */
+interface ShareBalance {
+    inscription_id: string;
+    holder: string;
+    balance: string;
+}
+/** Locker account info for an inscription */
+interface LockerInfo {
+    inscription_id: string;
+    locker_address: string;
+    is_unlocked: boolean;
+}
+
+/** Raw event as returned from StarkNet RPC */
+interface RawEvent {
+    keys: string[];
+    data: string[];
+    transaction_hash: string;
+    block_number: number;
+}
+/** InscriptionCreated event */
+interface InscriptionCreatedEvent {
+    type: 'InscriptionCreated';
+    inscription_id: bigint;
+    creator: string;
+    is_borrow: boolean;
+    transaction_hash: string;
+    block_number: number;
+}
+/** InscriptionSigned event */
+interface InscriptionSignedEvent {
+    type: 'InscriptionSigned';
+    inscription_id: bigint;
+    borrower: string;
+    lender: string;
+    issued_debt_percentage: bigint;
+    shares_minted: bigint;
+    transaction_hash: string;
+    block_number: number;
+}
+/** InscriptionCancelled event */
+interface InscriptionCancelledEvent {
+    type: 'InscriptionCancelled';
+    inscription_id: bigint;
+    creator: string;
+    transaction_hash: string;
+    block_number: number;
+}
+/** InscriptionRepaid event */
+interface InscriptionRepaidEvent {
+    type: 'InscriptionRepaid';
+    inscription_id: bigint;
+    repayer: string;
+    transaction_hash: string;
+    block_number: number;
+}
+/** InscriptionLiquidated event */
+interface InscriptionLiquidatedEvent {
+    type: 'InscriptionLiquidated';
+    inscription_id: bigint;
+    liquidator: string;
+    transaction_hash: string;
+    block_number: number;
+}
+/** SharesRedeemed event */
+interface SharesRedeemedEvent {
+    type: 'SharesRedeemed';
+    inscription_id: bigint;
+    redeemer: string;
+    shares: bigint;
+    transaction_hash: string;
+    block_number: number;
+}
+/** TransferSingle (ERC1155) event from the Stela contract */
+interface TransferSingleEvent {
+    type: 'TransferSingle';
+    operator: string;
+    from: string;
+    to: string;
+    id: bigint;
+    value: bigint;
+    transaction_hash: string;
+    block_number: number;
+}
+/** Discriminated union of all Stela protocol events */
+type StelaEvent = InscriptionCreatedEvent | InscriptionSignedEvent | InscriptionCancelledEvent | InscriptionRepaidEvent | InscriptionLiquidatedEvent | SharesRedeemedEvent | TransferSingleEvent;
+
+/** State of a locker account */
+interface LockerState {
+    /** Contract address of the deployed locker */
+    address: string;
+    /** Whether the locker restrictions have been removed */
+    isUnlocked: boolean;
+}
+/** A call to be executed through the locker account */
+interface LockerCall extends Call {
+}
+
+/** Deployed Stela protocol contract addresses per network */
+declare const STELA_ADDRESS: Record<Network, string>;
+/** Validate and return a Network value, defaulting to 'sepolia' */
+declare function resolveNetwork(raw?: string): Network;
+
+/** Maximum basis points (100%) */
+declare const MAX_BPS = 10000n;
+/** Virtual share offset used in share calculations (1e16) */
+declare const VIRTUAL_SHARE_OFFSET = 10000000000000000n;
+/** Numeric enum values for asset types (matches Cairo contract) */
+declare const ASSET_TYPE_ENUM: Record<AssetType, number>;
+/** Reverse mapping: numeric enum value to AssetType name */
+declare const ASSET_TYPE_NAMES: Record<number, AssetType>;
+
+/** 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 */
+declare const fromU256: (u: {
+    low: bigint;
+    high: bigint;
+}) => bigint;
+/** Convert a u256 { low, high } to a 0x-prefixed 64-char hex string (for DB keys) */
+declare const inscriptionIdToHex: (u: {
+    low: bigint;
+    high: bigint;
+}) => string;
+
+/** Convert any address-like value (string, bigint, number) to a hex string */
+declare function toHex(value: unknown): string;
+/** Truncate an address for display: 0x1a2b...3c4d */
+declare function formatAddress(address: unknown): string;
+/** Normalize an address to a fully-padded, checksummed hex string */
+declare function normalizeAddress(address: unknown): string;
+/** Compare two addresses for equality (handles different padding/casing) */
+declare function addressesEqual(a: unknown, b: unknown): boolean;
+
+/** Convert human-readable amount (e.g. "1.5") to on-chain value using decimals */
+declare function parseAmount(humanAmount: string, decimals: number): bigint;
+/** Format a raw token value (string) given its decimals */
+declare function formatTokenValue(raw: string | null, decimals: number): string;
+
+/** Format duration in seconds to human-readable (e.g. "7d 0h", "2h", "30m") */
+declare function formatDuration(seconds: number | bigint): string;
+/** Format a unix timestamp (seconds) to locale string */
+declare function formatTimestamp(ts: bigint): string;
+
+/** Input shape for computeStatus — accepts both bigint and number fields */
+interface StatusInput {
+    signed_at: number | bigint;
+    duration: number | bigint;
+    issued_debt_percentage: number | bigint;
+    is_repaid: boolean;
+    liquidated: boolean;
+    deadline?: number | bigint;
+    status?: string;
+}
+/** Compute the inscription status from on-chain fields */
+declare function computeStatus(a: StatusInput, nowSeconds?: number): InscriptionStatus;
+
+interface TokenInfo {
+    symbol: string;
+    name: string;
+    decimals: number;
+    addresses: Partial<Record<Network, string>>;
+    logoUrl?: string;
+}
+
+/**
+ * Curated StarkNet token list.
+ * Addresses sourced from official deployments.
+ */
+declare const TOKENS: TokenInfo[];
+/** Get tokens available on a specific network */
+declare function getTokensForNetwork(network: string): TokenInfo[];
+/** Find a token by its address (any network) */
+declare function findTokenByAddress(address: string): TokenInfo | undefined;
+
+/** Convert a fill percentage to shares, matching the contract's share math */
+declare function convertToShares(percentage: bigint, totalSupply: bigint, currentIssuedPercentage: bigint): bigint;
+/** Scale a value by a percentage in basis points */
+declare function scaleByPercentage(value: bigint, percentage: bigint): bigint;
+/** Convert shares back to a percentage of the inscription */
+declare function sharesToPercentage(shares: bigint, totalSupply: bigint, currentIssuedPercentage: bigint): bigint;
+/** Calculate the fee portion of shares given a fee in basis points */
+declare function calculateFeeShares(shares: bigint, feeBps: bigint): bigint;
+
+/** Event selectors for all Stela protocol events */
+declare const SELECTORS: {
+    readonly InscriptionCreated: string;
+    readonly InscriptionSigned: string;
+    readonly InscriptionCancelled: string;
+    readonly InscriptionRepaid: string;
+    readonly InscriptionLiquidated: string;
+    readonly SharesRedeemed: string;
+    readonly TransferSingle: string;
+};
+
+/** Parse a single raw event into a typed StelaEvent. Returns null if unrecognized. */
+declare function parseEvent(raw: RawEvent): StelaEvent | null;
+/** Parse an array of raw events, skipping unrecognized ones. */
+declare function parseEvents(rawEvents: RawEvent[]): StelaEvent[];
+
+interface InscriptionClientOptions {
+    stelaAddress: string;
+    provider: RpcProvider;
+    account?: Account;
+}
+declare class InscriptionClient {
+    private contract;
+    private address;
+    private account?;
+    constructor(opts: InscriptionClientOptions);
+    getInscription(inscriptionId: bigint): Promise<StoredInscription>;
+    getLocker(inscriptionId: bigint): Promise<string>;
+    getInscriptionFee(): Promise<bigint>;
+    convertToShares(inscriptionId: bigint, percentage: bigint): Promise<bigint>;
+    buildCreateInscription(params: InscriptionParams): Call;
+    buildSignInscription(inscriptionId: bigint, bps: bigint): Call;
+    buildCancelInscription(inscriptionId: bigint): Call;
+    buildRepay(inscriptionId: bigint): Call;
+    buildLiquidate(inscriptionId: bigint): Call;
+    buildRedeem(inscriptionId: bigint, shares: bigint): Call;
+    /**
+     * Execute one or more calls via the connected account.
+     * Pass approval calls to bundle ERC20 approve + protocol call atomically.
+     */
+    execute(calls: Call[]): Promise<{
+        transaction_hash: string;
+    }>;
+    createInscription(params: InscriptionParams, approvals?: Call[]): Promise<{
+        transaction_hash: string;
+    }>;
+    signInscription(inscriptionId: bigint, bps: bigint, approvals?: Call[]): Promise<{
+        transaction_hash: string;
+    }>;
+    cancelInscription(inscriptionId: bigint): Promise<{
+        transaction_hash: string;
+    }>;
+    repay(inscriptionId: bigint, approvals?: Call[]): Promise<{
+        transaction_hash: string;
+    }>;
+    liquidate(inscriptionId: bigint): Promise<{
+        transaction_hash: string;
+    }>;
+    redeem(inscriptionId: bigint, shares: bigint): Promise<{
+        transaction_hash: string;
+    }>;
+}
+
+interface ShareClientOptions {
+    stelaAddress: string;
+    provider: RpcProvider;
+}
+/**
+ * Client for reading ERC1155 share balances on the Stela contract.
+ * Inscription IDs are token IDs — each lender receives shares as ERC1155 tokens.
+ */
+declare class ShareClient {
+    private contract;
+    constructor(opts: ShareClientOptions);
+    /** Get share balance for an account on a specific inscription */
+    balanceOf(account: string, inscriptionId: bigint): Promise<bigint>;
+    /** Get share balances for multiple account/inscription pairs */
+    balanceOfBatch(accounts: string[], inscriptionIds: bigint[]): Promise<bigint[]>;
+    /** Check if an operator is approved for all tokens of an owner */
+    isApprovedForAll(owner: string, operator: string): Promise<boolean>;
+}
+
+declare class LockerClient {
+    private stelaContract;
+    private provider;
+    private account?;
+    constructor(stelaContract: Contract, provider: RpcProvider, account?: Account | undefined);
+    /** Get the Locker TBA address for an inscription */
+    getLockerAddress(inscriptionId: bigint): Promise<string>;
+    /** Check if a locker is unlocked */
+    isUnlocked(inscriptionId: bigint): Promise<boolean>;
+    /** Get full locker state */
+    getLockerState(inscriptionId: bigint): Promise<LockerState>;
+    /** Read ERC20 balance held by a locker */
+    getLockerBalance(inscriptionId: bigint, tokenAddress: string): Promise<bigint>;
+    /** Read multiple ERC20 balances held by a locker */
+    getLockerBalances(inscriptionId: bigint, tokenAddresses: string[]): Promise<Map<string, bigint>>;
+    /**
+     * Build a Call to execute an arbitrary call through the Locker TBA.
+     * The Locker's __execute__ function proxies calls from the locker's address.
+     * This is how a DAO retains governance power over locked collateral.
+     *
+     * The locker uses SNIP-6 account standard (__execute__). The calldata
+     * encodes an array of Call structs, each with:
+     *   - to: felt252 (ContractAddress)
+     *   - selector: felt252
+     *   - calldata: Array<felt252> (length-prefixed)
+     */
+    buildLockerExecute(lockerAddress: string, innerCalls: Call[]): Call;
+    /**
+     * Execute a governance call through the Locker.
+     * Requires account to be the inscription's borrower (NFT owner).
+     */
+    executeThrough(inscriptionId: bigint, innerCall: Call): Promise<{
+        transaction_hash: string;
+    }>;
+    /**
+     * Execute multiple governance calls through the Locker in a single tx.
+     */
+    executeThroughBatch(inscriptionId: bigint, innerCalls: Call[]): Promise<{
+        transaction_hash: string;
+    }>;
+}
+
+interface ApiClientOptions {
+    baseUrl?: string;
+}
+interface ListInscriptionsParams {
+    status?: string;
+    address?: string;
+    page?: number;
+    limit?: number;
+}
+/**
+ * HTTP client for the Stela indexer API.
+ * Provides typed access to indexed inscription data, treasury views, and locker info.
+ */
+declare class ApiClient {
+    private baseUrl;
+    constructor(opts?: ApiClientOptions);
+    /** List inscriptions with optional filters */
+    listInscriptions(params?: ListInscriptionsParams): Promise<ApiListResponse<InscriptionRow>>;
+    /** Get a single inscription by ID */
+    getInscription(id: string): Promise<ApiDetailResponse<InscriptionRow>>;
+    /** Get events for a specific inscription */
+    getInscriptionEvents(id: string): Promise<ApiListResponse<InscriptionEventRow>>;
+    /** Get treasury asset balances for an address */
+    getTreasuryView(address: string): Promise<ApiListResponse<TreasuryAsset>>;
+    /** Get locker info for inscriptions of an address */
+    getLockers(address: string): Promise<ApiListResponse<LockerInfo>>;
+    /** Get share balances for an address */
+    getShareBalances(address: string): Promise<ApiListResponse<ShareBalance>>;
+    private get;
+}
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly url: string;
+    constructor(status: number, message: string, url: string);
+}
+/** Shape of an inscription event row from the API */
+interface InscriptionEventRow {
+    id: number;
+    inscription_id: string;
+    event_type: string;
+    tx_hash: string;
+    block_number: number;
+    timestamp: string | null;
+    data: Record<string, unknown> | null;
+}
+
+interface StelaSdkOptions {
+    /** StarkNet RPC provider */
+    provider: RpcProvider;
+    /** Connected account for write operations (optional for read-only) */
+    account?: Account;
+    /** Network name or auto-detect from provider */
+    network?: Network | string;
+    /** Custom API base URL */
+    apiBaseUrl?: string;
+    /** Override the contract address (for custom deployments) */
+    stelaAddress?: string;
+}
+/**
+ * Main SDK facade that wires together all clients.
+ *
+ * ```ts
+ * const sdk = new StelaSdk({ provider, account, network: 'sepolia' })
+ * const inscription = await sdk.inscriptions.getInscription(1n)
+ * const shares = await sdk.shares.balanceOf(myAddress, 1n)
+ * ```
+ */
+declare class StelaSdk {
+    readonly inscriptions: InscriptionClient;
+    readonly shares: ShareClient;
+    readonly locker: LockerClient;
+    readonly api: ApiClient;
+    readonly network: Network;
+    readonly stelaAddress: string;
+    constructor(opts: StelaSdkOptions);
+}
+
+export { ASSET_TYPE_ENUM, ASSET_TYPE_NAMES, ApiClient, type ApiClientOptions, type ApiDetailResponse, ApiError, type ApiListResponse, type Asset, type AssetRow, type AssetType, type Call, 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 RawEvent, SELECTORS, STATUS_LABELS, STELA_ADDRESS, type ShareBalance, ShareClient, type ShareClientOptions, type SharesRedeemedEvent, type StatusInput, type StelaEvent, StelaSdk, type StelaSdkOptions, type StoredInscription, TOKENS, type TokenInfo, type TransferSingleEvent, type TreasuryAsset, VALID_STATUSES, VIRTUAL_SHARE_OFFSET, addressesEqual, calculateFeeShares, computeStatus, convertToShares, findTokenByAddress, formatAddress, formatDuration, formatTimestamp, formatTokenValue, fromU256, getTokensForNetwork, inscriptionIdToHex, normalizeAddress, parseAmount, parseEvent, parseEvents, resolveNetwork, scaleByPercentage, sharesToPercentage, toHex, toU256 };