@fepvenancio/stela-sdk 0.8.1 → 0.9.0

package/dist/index.d.cts

@@ -360,6 +360,8 @@ interface TokenInfo {
     decimals: number;
     addresses: Partial<Record<Network, string>>;
     logoUrl?: string;
+    /** Asset type — defaults to ERC20 if omitted */
+    assetType?: 'ERC20' | 'ERC721' | 'ERC1155' | 'ERC4626';
 }
 
 /**
@@ -367,6 +369,8 @@ interface TokenInfo {
  * Addresses sourced from official deployments.
  */
 declare const TOKENS: TokenInfo[];
+/** Get NFT collections (ERC721) available on a specific network */
+declare function getNFTCollections(network: string): TokenInfo[];
 /** Get tokens available on a specific network */
 declare function getTokensForNetwork(network: string): TokenInfo[];
 /** Find a token by its address (any network) */
@@ -380,6 +384,128 @@ declare function scaleByPercentage(value: bigint, percentage: bigint): bigint;
 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;
+/** Ceiling integer division: ceil(a / b). Matches Cairo div_ceil. */
+declare function divCeil(a: bigint, b: bigint): bigint;
+/**
+ * Pro-rata interest for early repayment. Matches Cairo pro_rata_interest().
+ * Rounds UP (ceiling) to protect lenders — borrower never underpays.
+ *
+ * @param amount - Full interest amount
+ * @param elapsed - Seconds elapsed since loan signed
+ * @param duration - Total loan duration in seconds
+ * @returns ceil(amount * elapsed / duration), capped at amount
+ */
+declare function proRataInterest(amount: bigint, elapsed: bigint, duration: bigint): bigint;
+
+/** Default dust buffer: 60 seconds of extra interest accrual to account for tx confirmation delay */
+declare const DEFAULT_DUST_BUFFER_SECONDS = 60n;
+/** Value breakdown for a single asset in a position */
+interface AssetValue {
+    /** The asset definition */
+    asset: Asset;
+    /** The share-proportional amount of this asset */
+    proportionalValue: bigint;
+}
+/** Accrued interest for a single asset in a position */
+interface AccruedInterestEntry {
+    /** The interest asset definition */
+    asset: Asset;
+    /** Full interest amount (before pro-rata) scaled to share proportion */
+    fullInterest: bigint;
+    /** Pro-rata accrued interest at the given elapsed time */
+    accruedInterest: bigint;
+}
+/** Complete position valuation at a point in time */
+interface PositionValue {
+    /** Inscription ID */
+    inscriptionId: string;
+    /** Shares held */
+    shares: bigint;
+    /** Total supply of shares for this inscription */
+    totalSupply: bigint;
+    /** Share proportion as a fraction of MAX_BPS (10000) */
+    shareBps: bigint;
+    /** Debt asset values (proportional to shares held) */
+    debt: AssetValue[];
+    /** Interest asset values (full and accrued) */
+    interest: AccruedInterestEntry[];
+    /** Collateral asset values (proportional to shares held) */
+    collateral: AssetValue[];
+    /** Suggested floor price: sum of proportional debt + accrued interest (per asset) */
+    accrued: AccruedInterestEntry[];
+    /** Elapsed seconds since loan signed */
+    elapsed: bigint;
+    /** Total loan duration */
+    duration: bigint;
+}
+/**
+ * Compute the share proportion in BPS for a given share amount.
+ * Returns how many basis points (out of 10000) the shares represent.
+ */
+declare function shareProportionBps(shares: bigint, totalSupply: bigint): bigint;
+/**
+ * Compute the proportional value of an asset for a given share amount.
+ * This is the amount the share holder would receive on redemption.
+ *
+ * Matches the contract: `tracked_balance * shares / total_supply`
+ */
+declare function proportionalAssetValue(assetValue: bigint, shares: bigint, totalSupply: bigint): bigint;
+/**
+ * Compute the full position valuation at a point in time.
+ *
+ * @param params.inscriptionId - The inscription ID
+ * @param params.shares - Shares held by the position owner
+ * @param params.totalSupply - Total shares for this inscription
+ * @param params.debtAssets - Debt asset definitions with values
+ * @param params.interestAssets - Interest asset definitions with values
+ * @param params.collateralAssets - Collateral asset definitions with values
+ * @param params.elapsed - Seconds elapsed since signed_at
+ * @param params.duration - Total loan duration in seconds
+ */
+declare function computePositionValue(params: {
+    inscriptionId: string;
+    shares: bigint;
+    totalSupply: bigint;
+    debtAssets: Asset[];
+    interestAssets: Asset[];
+    collateralAssets: Asset[];
+    elapsed: bigint;
+    duration: bigint;
+}): PositionValue;
+/**
+ * Compute accrued interest with a dust buffer to account for transaction confirmation delay.
+ *
+ * Between computing the price and the transaction landing on-chain, interest continues
+ * to accrue. This adds a configurable buffer (default 60s) of extra interest so the
+ * buyer's approval doesn't fail due to a tiny increase.
+ *
+ * @param amount - Full interest amount for the position
+ * @param elapsed - Current elapsed seconds since signed_at
+ * @param duration - Total loan duration in seconds
+ * @param bufferSeconds - Extra seconds to add (default: 60)
+ * @returns Accrued interest at (elapsed + buffer), capped at full amount
+ */
+declare function accruedInterestWithBuffer(amount: bigint, elapsed: bigint, duration: bigint, bufferSeconds?: bigint): bigint;
+/**
+ * Compute a safe minimum price for buying a lending position.
+ * Includes proportional debt + accrued interest + dust buffer for each interest asset.
+ *
+ * Use this when the buyer needs to know how much to approve for payment tokens.
+ *
+ * @returns Array of { asset, safeAmount } for debt assets and interest assets respectively
+ */
+declare function computeSafePositionFloor(params: {
+    shares: bigint;
+    totalSupply: bigint;
+    debtAssets: Asset[];
+    interestAssets: Asset[];
+    elapsed: bigint;
+    duration: bigint;
+    bufferSeconds?: bigint;
+}): {
+    debtFloor: AssetValue[];
+    interestFloor: AssetValue[];
+};
 
 /** Event selectors for all Stela protocol events */
 declare const SELECTORS: {
@@ -795,13 +921,19 @@ declare class InscriptionClient {
 interface ShareClientOptions {
     stelaAddress: string;
     provider: RpcProvider;
+    account?: Account;
 }
 /**
- * Client for reading ERC1155 share balances on the Stela contract.
+ * Client for ERC1155 share operations on the Stela contract.
  * Inscription IDs are token IDs — each lender receives shares as ERC1155 tokens.
+ *
+ * Shares are freely transferable via standard ERC1155 safeTransferFrom.
+ * Any address holding shares can call redeem() after repayment/liquidation.
  */
 declare class ShareClient {
     private contract;
+    private address;
+    private account?;
     constructor(opts: ShareClientOptions);
     /** Get share balance for an account on a specific inscription */
     balanceOf(account: string, inscriptionId: bigint): Promise<bigint>;
@@ -809,6 +941,33 @@ declare class ShareClient {
     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>;
+    /**
+     * Build a call to transfer shares (ERC1155 safeTransferFrom).
+     * This enables secondary market trading of lending positions.
+     *
+     * @param from - Current share holder
+     * @param to - Recipient address
+     * @param inscriptionId - The inscription (token ID)
+     * @param amount - Number of shares to transfer
+     * @param data - Optional calldata (empty array by default)
+     */
+    buildTransferShares(from: string, to: string, inscriptionId: bigint, amount: bigint, data?: string[]): Call;
+    /**
+     * Build a call to approve an operator for all ERC1155 tokens.
+     * Required before a marketplace contract can transfer shares on your behalf.
+     *
+     * @param operator - The address to approve (e.g., marketplace contract)
+     * @param approved - Whether to approve or revoke
+     */
+    buildSetApprovalForAll(operator: string, approved: boolean): Call;
+    /** Transfer shares to another address */
+    transferShares(from: string, to: string, inscriptionId: bigint, amount: bigint, data?: string[]): Promise<{
+        transaction_hash: string;
+    }>;
+    /** Approve or revoke an operator for all ERC1155 tokens */
+    setApprovalForAll(operator: string, approved: boolean): Promise<{
+        transaction_hash: string;
+    }>;
 }
 
 declare class LockerClient {
@@ -930,4 +1089,4 @@ declare class StelaSdk {
     constructor(opts: StelaSdkOptions);
 }
 
-export { ASSET_TYPE_ENUM, ASSET_TYPE_NAMES, AUCTION_DURATION, AUCTION_PENALTY_BPS, AUCTION_RESERVE_BPS, ApiClient, type ApiClientOptions, type ApiDetailResponse, ApiError, type ApiListResponse, type Asset, type AssetRow, type AssetType, type AuctionBidEvent, type AuctionStartedEvent, type BatchEntry, CHAIN_ID, type Call, 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 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, addressesEqual, calculateFeeShares, computeStatus, convertToShares, deserializeSignature, findTokenByAddress, formatAddress, formatDuration, formatTimestamp, formatTokenValue, fromU256, getBatchLendOfferTypedData, getCollateralSaleOfferTypedData, getCollectionBorrowAcceptanceTypedData, getCollectionLendOfferTypedData, getInscriptionOrderTypedData, getLendOfferTypedData, getRefinanceApprovalTypedData, getRefinanceOfferTypedData, getRenegotiationProposalTypedData, getTokensForNetwork, hashAssets, hashBatchEntries, inscriptionIdToHex, normalizeAddress, parseAmount, parseEvent, parseEvents, resolveNetwork, scaleByPercentage, serializeSignature, sharesToPercentage, toHex, toU256 };
+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 };

package/dist/index.d.ts

@@ -360,6 +360,8 @@ interface TokenInfo {
     decimals: number;
     addresses: Partial<Record<Network, string>>;
     logoUrl?: string;
+    /** Asset type — defaults to ERC20 if omitted */
+    assetType?: 'ERC20' | 'ERC721' | 'ERC1155' | 'ERC4626';
 }
 
 /**
@@ -367,6 +369,8 @@ interface TokenInfo {
  * Addresses sourced from official deployments.
  */
 declare const TOKENS: TokenInfo[];
+/** Get NFT collections (ERC721) available on a specific network */
+declare function getNFTCollections(network: string): TokenInfo[];
 /** Get tokens available on a specific network */
 declare function getTokensForNetwork(network: string): TokenInfo[];
 /** Find a token by its address (any network) */
@@ -380,6 +384,128 @@ declare function scaleByPercentage(value: bigint, percentage: bigint): bigint;
 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;
+/** Ceiling integer division: ceil(a / b). Matches Cairo div_ceil. */
+declare function divCeil(a: bigint, b: bigint): bigint;
+/**
+ * Pro-rata interest for early repayment. Matches Cairo pro_rata_interest().
+ * Rounds UP (ceiling) to protect lenders — borrower never underpays.
+ *
+ * @param amount - Full interest amount
+ * @param elapsed - Seconds elapsed since loan signed
+ * @param duration - Total loan duration in seconds
+ * @returns ceil(amount * elapsed / duration), capped at amount
+ */
+declare function proRataInterest(amount: bigint, elapsed: bigint, duration: bigint): bigint;
+
+/** Default dust buffer: 60 seconds of extra interest accrual to account for tx confirmation delay */
+declare const DEFAULT_DUST_BUFFER_SECONDS = 60n;
+/** Value breakdown for a single asset in a position */
+interface AssetValue {
+    /** The asset definition */
+    asset: Asset;
+    /** The share-proportional amount of this asset */
+    proportionalValue: bigint;
+}
+/** Accrued interest for a single asset in a position */
+interface AccruedInterestEntry {
+    /** The interest asset definition */
+    asset: Asset;
+    /** Full interest amount (before pro-rata) scaled to share proportion */
+    fullInterest: bigint;
+    /** Pro-rata accrued interest at the given elapsed time */
+    accruedInterest: bigint;
+}
+/** Complete position valuation at a point in time */
+interface PositionValue {
+    /** Inscription ID */
+    inscriptionId: string;
+    /** Shares held */
+    shares: bigint;
+    /** Total supply of shares for this inscription */
+    totalSupply: bigint;
+    /** Share proportion as a fraction of MAX_BPS (10000) */
+    shareBps: bigint;
+    /** Debt asset values (proportional to shares held) */
+    debt: AssetValue[];
+    /** Interest asset values (full and accrued) */
+    interest: AccruedInterestEntry[];
+    /** Collateral asset values (proportional to shares held) */
+    collateral: AssetValue[];
+    /** Suggested floor price: sum of proportional debt + accrued interest (per asset) */
+    accrued: AccruedInterestEntry[];
+    /** Elapsed seconds since loan signed */
+    elapsed: bigint;
+    /** Total loan duration */
+    duration: bigint;
+}
+/**
+ * Compute the share proportion in BPS for a given share amount.
+ * Returns how many basis points (out of 10000) the shares represent.
+ */
+declare function shareProportionBps(shares: bigint, totalSupply: bigint): bigint;
+/**
+ * Compute the proportional value of an asset for a given share amount.
+ * This is the amount the share holder would receive on redemption.
+ *
+ * Matches the contract: `tracked_balance * shares / total_supply`
+ */
+declare function proportionalAssetValue(assetValue: bigint, shares: bigint, totalSupply: bigint): bigint;
+/**
+ * Compute the full position valuation at a point in time.
+ *
+ * @param params.inscriptionId - The inscription ID
+ * @param params.shares - Shares held by the position owner
+ * @param params.totalSupply - Total shares for this inscription
+ * @param params.debtAssets - Debt asset definitions with values
+ * @param params.interestAssets - Interest asset definitions with values
+ * @param params.collateralAssets - Collateral asset definitions with values
+ * @param params.elapsed - Seconds elapsed since signed_at
+ * @param params.duration - Total loan duration in seconds
+ */
+declare function computePositionValue(params: {
+    inscriptionId: string;
+    shares: bigint;
+    totalSupply: bigint;
+    debtAssets: Asset[];
+    interestAssets: Asset[];
+    collateralAssets: Asset[];
+    elapsed: bigint;
+    duration: bigint;
+}): PositionValue;
+/**
+ * Compute accrued interest with a dust buffer to account for transaction confirmation delay.
+ *
+ * Between computing the price and the transaction landing on-chain, interest continues
+ * to accrue. This adds a configurable buffer (default 60s) of extra interest so the
+ * buyer's approval doesn't fail due to a tiny increase.
+ *
+ * @param amount - Full interest amount for the position
+ * @param elapsed - Current elapsed seconds since signed_at
+ * @param duration - Total loan duration in seconds
+ * @param bufferSeconds - Extra seconds to add (default: 60)
+ * @returns Accrued interest at (elapsed + buffer), capped at full amount
+ */
+declare function accruedInterestWithBuffer(amount: bigint, elapsed: bigint, duration: bigint, bufferSeconds?: bigint): bigint;
+/**
+ * Compute a safe minimum price for buying a lending position.
+ * Includes proportional debt + accrued interest + dust buffer for each interest asset.
+ *
+ * Use this when the buyer needs to know how much to approve for payment tokens.
+ *
+ * @returns Array of { asset, safeAmount } for debt assets and interest assets respectively
+ */
+declare function computeSafePositionFloor(params: {
+    shares: bigint;
+    totalSupply: bigint;
+    debtAssets: Asset[];
+    interestAssets: Asset[];
+    elapsed: bigint;
+    duration: bigint;
+    bufferSeconds?: bigint;
+}): {
+    debtFloor: AssetValue[];
+    interestFloor: AssetValue[];
+};
 
 /** Event selectors for all Stela protocol events */
 declare const SELECTORS: {
@@ -795,13 +921,19 @@ declare class InscriptionClient {
 interface ShareClientOptions {
     stelaAddress: string;
     provider: RpcProvider;
+    account?: Account;
 }
 /**
- * Client for reading ERC1155 share balances on the Stela contract.
+ * Client for ERC1155 share operations on the Stela contract.
  * Inscription IDs are token IDs — each lender receives shares as ERC1155 tokens.
+ *
+ * Shares are freely transferable via standard ERC1155 safeTransferFrom.
+ * Any address holding shares can call redeem() after repayment/liquidation.
  */
 declare class ShareClient {
     private contract;
+    private address;
+    private account?;
     constructor(opts: ShareClientOptions);
     /** Get share balance for an account on a specific inscription */
     balanceOf(account: string, inscriptionId: bigint): Promise<bigint>;
@@ -809,6 +941,33 @@ declare class ShareClient {
     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>;
+    /**
+     * Build a call to transfer shares (ERC1155 safeTransferFrom).
+     * This enables secondary market trading of lending positions.
+     *
+     * @param from - Current share holder
+     * @param to - Recipient address
+     * @param inscriptionId - The inscription (token ID)
+     * @param amount - Number of shares to transfer
+     * @param data - Optional calldata (empty array by default)
+     */
+    buildTransferShares(from: string, to: string, inscriptionId: bigint, amount: bigint, data?: string[]): Call;
+    /**
+     * Build a call to approve an operator for all ERC1155 tokens.
+     * Required before a marketplace contract can transfer shares on your behalf.
+     *
+     * @param operator - The address to approve (e.g., marketplace contract)
+     * @param approved - Whether to approve or revoke
+     */
+    buildSetApprovalForAll(operator: string, approved: boolean): Call;
+    /** Transfer shares to another address */
+    transferShares(from: string, to: string, inscriptionId: bigint, amount: bigint, data?: string[]): Promise<{
+        transaction_hash: string;
+    }>;
+    /** Approve or revoke an operator for all ERC1155 tokens */
+    setApprovalForAll(operator: string, approved: boolean): Promise<{
+        transaction_hash: string;
+    }>;
 }
 
 declare class LockerClient {
@@ -930,4 +1089,4 @@ declare class StelaSdk {
     constructor(opts: StelaSdkOptions);
 }
 
-export { ASSET_TYPE_ENUM, ASSET_TYPE_NAMES, AUCTION_DURATION, AUCTION_PENALTY_BPS, AUCTION_RESERVE_BPS, ApiClient, type ApiClientOptions, type ApiDetailResponse, ApiError, type ApiListResponse, type Asset, type AssetRow, type AssetType, type AuctionBidEvent, type AuctionStartedEvent, type BatchEntry, CHAIN_ID, type Call, 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 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, addressesEqual, calculateFeeShares, computeStatus, convertToShares, deserializeSignature, findTokenByAddress, formatAddress, formatDuration, formatTimestamp, formatTokenValue, fromU256, getBatchLendOfferTypedData, getCollateralSaleOfferTypedData, getCollectionBorrowAcceptanceTypedData, getCollectionLendOfferTypedData, getInscriptionOrderTypedData, getLendOfferTypedData, getRefinanceApprovalTypedData, getRefinanceOfferTypedData, getRenegotiationProposalTypedData, getTokensForNetwork, hashAssets, hashBatchEntries, inscriptionIdToHex, normalizeAddress, parseAmount, parseEvent, parseEvents, resolveNetwork, scaleByPercentage, serializeSignature, sharesToPercentage, toHex, toU256 };
+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 };

package/dist/index.js

@@ -256,11 +256,35 @@ var TOKENS = [
     addresses: {
       sepolia: "0x04f2345306bf8ef1c8c1445661354ef08421aa092459445a5d6b46641237e943"
     }
+  },
+  // NFT Collections (ERC721)
+  {
+    symbol: "GENESIS",
+    name: "Stela Genesis",
+    decimals: 0,
+    assetType: "ERC721",
+    addresses: {
+      sepolia: "0x0265ea52ffbf1b7e1a029b94fe1a2023899dd0bc02eb1f11c9b04ea90e957d28"
+    }
+  },
+  {
+    symbol: "MockNFT",
+    name: "Mock ERC721",
+    decimals: 0,
+    assetType: "ERC721",
+    addresses: {
+      sepolia: "0x032bfd52134ad92beae1bc5018a3748e1d1240efd627220e314c07e4c63433d5"
+    }
   }
 ];
 function normalizeHex(addr) {
   return "0x" + addr.replace(/^0x0*/i, "").toLowerCase();
 }
+function getNFTCollections(network) {
+  return TOKENS.filter(
+    (t) => t.assetType === "ERC721" && t.addresses[network] !== void 0
+  );
+}
 function getTokensForNetwork(network) {
   return TOKENS.filter((t) => t.addresses[network] !== void 0);
 }
@@ -286,6 +310,74 @@ function sharesToPercentage(shares, totalSupply, currentIssuedPercentage) {
 function calculateFeeShares(shares, feeBps) {
   return shares * feeBps / MAX_BPS;
 }
+function divCeil(a, b) {
+  if (a === 0n) return 0n;
+  return (a + b - 1n) / b;
+}
+function proRataInterest(amount, elapsed, duration) {
+  if (amount === 0n || elapsed === 0n) return 0n;
+  if (elapsed >= duration) return amount;
+  return divCeil(amount * elapsed, duration);
+}
+
+// src/math/position.ts
+var DEFAULT_DUST_BUFFER_SECONDS = 60n;
+function shareProportionBps(shares, totalSupply) {
+  if (totalSupply === 0n) return 0n;
+  return shares * MAX_BPS / totalSupply;
+}
+function proportionalAssetValue(assetValue, shares, totalSupply) {
+  if (totalSupply === 0n || shares === 0n) return 0n;
+  return assetValue * shares / totalSupply;
+}
+function computePositionValue(params) {
+  const { shares, totalSupply, elapsed, duration } = params;
+  const shareBps = shareProportionBps(shares, totalSupply);
+  const debt = params.debtAssets.map((asset) => ({
+    asset,
+    proportionalValue: proportionalAssetValue(asset.value, shares, totalSupply)
+  }));
+  const interest = params.interestAssets.map((asset) => {
+    const fullInterest = proportionalAssetValue(asset.value, shares, totalSupply);
+    const accruedInterest = duration === 0n ? fullInterest : proRataInterest(fullInterest, elapsed, duration);
+    return { asset, fullInterest, accruedInterest };
+  });
+  const collateral = params.collateralAssets.map((asset) => ({
+    asset,
+    proportionalValue: proportionalAssetValue(asset.value, shares, totalSupply)
+  }));
+  return {
+    inscriptionId: params.inscriptionId,
+    shares,
+    totalSupply,
+    shareBps,
+    debt,
+    interest,
+    collateral,
+    accrued: interest,
+    elapsed,
+    duration
+  };
+}
+function accruedInterestWithBuffer(amount, elapsed, duration, bufferSeconds = DEFAULT_DUST_BUFFER_SECONDS) {
+  if (duration === 0n) return amount;
+  const bufferedElapsed = elapsed + bufferSeconds;
+  return proRataInterest(amount, bufferedElapsed, duration);
+}
+function computeSafePositionFloor(params) {
+  const { shares, totalSupply, elapsed, duration } = params;
+  const buffer = params.bufferSeconds ?? DEFAULT_DUST_BUFFER_SECONDS;
+  const debtFloor = params.debtAssets.map((asset) => ({
+    asset,
+    proportionalValue: proportionalAssetValue(asset.value, shares, totalSupply)
+  }));
+  const interestFloor = params.interestAssets.map((asset) => {
+    const fullInterest = proportionalAssetValue(asset.value, shares, totalSupply);
+    const safeAccrued = accruedInterestWithBuffer(fullInterest, elapsed, duration, buffer);
+    return { asset, proportionalValue: safeAccrued };
+  });
+  return { debtFloor, interestFloor };
+}
 var SELECTORS = {
   InscriptionCreated: hash.getSelectorFromName("InscriptionCreated"),
   InscriptionSigned: hash.getSelectorFromName("InscriptionSigned"),
@@ -3468,9 +3560,14 @@ function extractFieldU256(val) {
 }
 var ShareClient = class {
   contract;
+  address;
+  account;
   constructor(opts) {
+    this.address = opts.stelaAddress;
     this.contract = new Contract(stela_default, opts.stelaAddress, opts.provider);
+    this.account = opts.account;
   }
+  // ── Read Methods ───────────────────────────────────────────────────
   /** Get share balance for an account on a specific inscription */
   async balanceOf(account, inscriptionId) {
     const result = await this.contract.call("balance_of", [account, ...toU256(inscriptionId)]);
@@ -3494,6 +3591,53 @@ var ShareClient = class {
     const result = await this.contract.call("is_approved_for_all", [owner, operator]);
     return Boolean(result[0]);
   }
+  // ── Call Builders ──────────────────────────────────────────────────
+  /**
+   * Build a call to transfer shares (ERC1155 safeTransferFrom).
+   * This enables secondary market trading of lending positions.
+   *
+   * @param from - Current share holder
+   * @param to - Recipient address
+   * @param inscriptionId - The inscription (token ID)
+   * @param amount - Number of shares to transfer
+   * @param data - Optional calldata (empty array by default)
+   */
+  buildTransferShares(from, to, inscriptionId, amount, data = []) {
+    return {
+      contractAddress: this.address,
+      entrypoint: "safe_transfer_from",
+      calldata: [from, to, ...toU256(inscriptionId), ...toU256(amount), String(data.length), ...data]
+    };
+  }
+  /**
+   * Build a call to approve an operator for all ERC1155 tokens.
+   * Required before a marketplace contract can transfer shares on your behalf.
+   *
+   * @param operator - The address to approve (e.g., marketplace contract)
+   * @param approved - Whether to approve or revoke
+   */
+  buildSetApprovalForAll(operator, approved) {
+    return {
+      contractAddress: this.address,
+      entrypoint: "set_approval_for_all",
+      calldata: [operator, approved ? "1" : "0"]
+    };
+  }
+  // ── Execute Methods ────────────────────────────────────────────────
+  /** Transfer shares to another address */
+  async transferShares(from, to, inscriptionId, amount, data = []) {
+    if (!this.account) throw new Error("Account required for write operations");
+    const result = await this.account.execute([
+      this.buildTransferShares(from, to, inscriptionId, amount, data)
+    ]);
+    return { transaction_hash: result.transaction_hash };
+  }
+  /** Approve or revoke an operator for all ERC1155 tokens */
+  async setApprovalForAll(operator, approved) {
+    if (!this.account) throw new Error("Account required for write operations");
+    const result = await this.account.execute([this.buildSetApprovalForAll(operator, approved)]);
+    return { transaction_hash: result.transaction_hash };
+  }
 };
 function extractBigInt(result) {
   const arr = result;
@@ -3778,7 +3922,8 @@ var StelaSdk = class {
     });
     this.shares = new ShareClient({
       stelaAddress: this.stelaAddress,
-      provider: opts.provider
+      provider: opts.provider,
+      account: opts.account
     });
     const stelaContract = new Contract(stela_default, this.stelaAddress, opts.provider);
     this.locker = new LockerClient(stelaContract, opts.provider, opts.account);
@@ -3786,6 +3931,6 @@ var StelaSdk = class {
   }
 };
 
-export { ASSET_TYPE_ENUM, ASSET_TYPE_NAMES, AUCTION_DURATION, AUCTION_PENALTY_BPS, AUCTION_RESERVE_BPS, ApiClient, ApiError, CHAIN_ID, EXPLORER_TX_URL, GRACE_PERIOD, InscriptionClient, LockerClient, MAX_BPS, SELECTORS, STATUS_LABELS, STELA_ADDRESS, ShareClient, StelaSdk, TOKENS, VALID_STATUSES, VIRTUAL_SHARE_OFFSET, addressesEqual, calculateFeeShares, computeStatus, convertToShares, deserializeSignature, findTokenByAddress, formatAddress, formatDuration, formatTimestamp, formatTokenValue, fromU256, getBatchLendOfferTypedData, getCollateralSaleOfferTypedData, getCollectionBorrowAcceptanceTypedData, getCollectionLendOfferTypedData, getInscriptionOrderTypedData, getLendOfferTypedData, getRefinanceApprovalTypedData, getRefinanceOfferTypedData, getRenegotiationProposalTypedData, getTokensForNetwork, hashAssets, hashBatchEntries, inscriptionIdToHex, normalizeAddress, parseAmount, parseEvent, parseEvents, resolveNetwork, scaleByPercentage, serializeSignature, sharesToPercentage, toHex, toU256 };
+export { ASSET_TYPE_ENUM, ASSET_TYPE_NAMES, AUCTION_DURATION, AUCTION_PENALTY_BPS, AUCTION_RESERVE_BPS, ApiClient, ApiError, CHAIN_ID, DEFAULT_DUST_BUFFER_SECONDS, EXPLORER_TX_URL, GRACE_PERIOD, InscriptionClient, LockerClient, MAX_BPS, SELECTORS, STATUS_LABELS, STELA_ADDRESS, ShareClient, StelaSdk, TOKENS, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map