A TypeScript SDK for interacting with Eclipse Lending contracts on the Aleo blockchain.
npm install @eclipse/lending-sdkAll services (PoolService, VaultService, StablecoinService, AuctionService) can be initialized in a similar way. You can pass an AleoLendingClient instance or an ApiClientConfig object to the service constructor if you need to customize the API endpoint or network. If no arguments are provided, a default AleoLendingClient will be used.
import {
PoolService,
AleoLendingClient,
type ApiClientConfig,
} from "@eclipse/lending-sdk";
// Option 1: Default client
const poolServiceDefault = new PoolService();
// Option 2: With a custom API configuration
const customConfig: ApiClientConfig = {
baseUrl: "https://api.explorer.provable.com/v1", // Default, but can be changed
network: "testnet", // Default, can be "mainnet"
};
const poolServiceWithConfig = new PoolService(customConfig);
// Option 3: With an existing AleoLendingClient instance
const client = new AleoLendingClient(customConfig);
const poolServiceWithClient = new PoolService(client);
// You can also specify a custom program ID if you are interacting with a cloned program:
const specificPoolService = new PoolService(
client,
"my_custom_pool_program.aleo"
);To retrieve data related to lending pools (default program ID: eclipse_lending_pair_template.aleo):
import { PoolService } from "@eclipse/lending-sdk";
const poolService = new PoolService(); // Uses default client and program ID
// Example: Get the state of an asset pool using its collateral token ID
async function fetchPoolState(collateralTokenId: string) {
try {
const poolState = await poolService.getAssetPoolState(collateralTokenId);
if (poolState) {
console.log(`Pool State for token ${collateralTokenId}:`, poolState);
} else {
console.log(`Could not fetch pool state for token ${collateralTokenId}.`);
}
} catch (error) {
console.error("Error fetching pool state:", error);
}
}
// Example: Get a user's position in a pool
async function fetchUserPoolPosition(userAddress: string) {
try {
const userPosition = await poolService.getUserPoolPosition(userAddress);
if (userPosition) {
console.log(`User ${userAddress} position:`, userPosition);
} else {
console.log(`Could not fetch position for user ${userAddress}.`);
}
} catch (error) {
console.error("Error fetching user position:", error);
}
}
// Example: Get combined pool data
async function fetchFullPoolData(collateralTokenId: string) {
try {
const fullPoolData = await poolService.getPoolData(collateralTokenId);
if (fullPoolData) {
console.log(
`Full Pool Data for token ${collateralTokenId}:`,
fullPoolData
);
} else {
console.log(
`Could not fetch full pool data for token ${collateralTokenId}.`
);
}
} catch (error) {
console.error("Error fetching full pool data:", error);
}
}
// --- Call example functions ---
// Replace with actual token IDs and addresses
// fetchPoolState("12345field");
// fetchUserPoolPosition("aleo1youraddresshere...");
// fetchFullPoolData("12345field");Usage for VaultService, StablecoinService, and AuctionService follows the same pattern as PoolService. Instantiate the service, then call its methods.
Example with VaultService (default program ID: eclipse_lending_usda_vault.aleo):
import { VaultService } from "@eclipse/lending-sdk";
const vaultService = new VaultService();
async function fetchVaultPosition(positionId: string) {
try {
const positionMeta = await vaultService.getPositionMeta(positionId);
if (positionMeta) {
console.log(`Vault Position ${positionId} Metadata:`, positionMeta);
} else {
console.log(`Could not fetch metadata for vault position ${positionId}.`);
}
} catch (error) {
console.error("Error fetching vault position metadata:", error);
}
}
// fetchVaultPosition("1"); // Replace with an actual position IDYou can also use the AleoLendingClient to call specific mapping getters if needed.
import { AleoLendingClient } from "@eclipse/lending-sdk";
// Create a client (can be configured with baseUrl and network)
const client = new AleoLendingClient();
const POOL_PROGRAM_ID = "eclipse_lending_pair_template.aleo"; // Or your specific cloned program ID
// Example: Get total supply for a specific token in a pool
async function getTotalSupplyExample(tokenId: string) {
try {
const totalSupply = await client.getTotalSupply(POOL_PROGRAM_ID, tokenId);
if (totalSupply !== null) {
console.log(`Total supply for token ${tokenId}:`, totalSupply);
} else {
console.log(`Could not fetch total supply for token ${tokenId}.`);
}
} catch (error) {
console.error("Error fetching total supply:", error);
}
}
// getTotalSupplyExample("12345field"); // Replace with an actual token IDThe SDK also exports utility functions:
import {
convertAddressToField,
parseUint,
parseAddress,
parseBool,
parseField,
} from "@eclipse/lending-sdk";
// Convert an Aleo address to a field element
const fieldRepresentation = convertAddressToField("aleo1youraddresshere...");
// Note: convertAddressToField returns a BigInt, use .toString() for display or further processing as a string.
console.log("Field representation:", fieldRepresentation.toString());
// Parsing functions are used internally by the services but can be used directly if needed.This section provides a summary of the main classes and methods. For detailed parameter types, return types, and descriptions, please refer to the JSDoc comments in the source code or the generated TypeDoc documentation.
Low-level client for interacting with Aleo lending contracts via an Aleo Explorer API.
constructor(config?: ApiClientConfig)getMappingValue(program: string, mapping: string, key: string): Promise<string | null>: Generic method to fetch a raw mapping value.
(Default Program: eclipse_lending_pair_template.aleo)
getTotalSupply(programId: string, tokenId: string): Promise<number | null>getTotalBorrow(programId: string, tokenId: string): Promise<number | null>getIndexSupply(programId: string, tokenId: string): Promise<number | null>getIndexBorrow(programId: string, tokenId: string): Promise<number | null>getLastBlock(programId: string, tokenId: string): Promise<number | null>getPrincipalSupply(programId: string, userAddress: string): Promise<number | null>getSnapshotSupply(programId: string, userAddress: string): Promise<number | null>getPrincipalBorrow(programId: string, userAddress: string): Promise<number | null>getSnapshotBorrow(programId: string, userAddress: string): Promise<number | null>
(Default Program: eclipse_lending_usda_vault.aleo)
getPrivCommit(programId: string, positionId: string): Promise<string | null>getIsLiquidated(programId: string, positionId: string): Promise<boolean | null>getPositionMeta(programId: string, positionId: string): Promise<VaultPositionMeta | null>getNextPositionId(programId: string, keyField?: string): Promise<number | null>getLiquidationRefund(programId: string, positionId: string): Promise<number | null>getLiquidationCollateral(programId: string, positionId: string): Promise<number | null>
(Default Program: floflo_stablecoin_vault.aleo)
getCollateralBalance(programId: string, userAddress: string): Promise<number | null>getDebtBalance(programId: string, userAddress: string): Promise<number | null>
(Default Program: eclipse_lending_auction.aleo)
getAuction(programId: string, auctionId: string): Promise<AuctionData | null>getNextAuctionId(programId: string, keyField?: string): Promise<number | null>
Service for retrieving data related to lending pools.
constructor(clientOrConfig?: AleoLendingClient | ApiClientConfig, programId?: string)getAssetPoolState(tokenId: string): Promise<AssetPoolState | null>getUserPoolPosition(userAddress: string): Promise<UserPoolPosition | null>getPoolData(collateralTokenId: string): Promise<PoolData | null>
Service for retrieving data related to lending vaults.
constructor(clientOrConfig?: AleoLendingClient | ApiClientConfig, programId?: string)getPositionMeta(positionId: string): Promise<VaultPositionMeta | null>isPositionLiquidated(positionId: string): Promise<boolean | null>getUserVault(positionId: string, owner?: string): Promise<UserVault | null>getLiquidationInfo(positionId: string): Promise<VaultLiquidationInfo | null>getNextPositionId(nextIdKey?: string): Promise<number | null>getGlobalVaultState(nextIdKey?: string): Promise<GlobalVaultState | null>getPrivCommit(positionId: string): Promise<string | null>
Service for retrieving data related to a stablecoin contract.
constructor(clientOrConfig?: AleoLendingClient | ApiClientConfig, programId?: string)getUserBalances(userAddress: string): Promise<UserStablecoinBalances | null>getStablecoinInfo(): Promise<StablecoinInfo | null>: (Placeholder - data typically from contract constants, not readable from mappings).
Service for retrieving data related to lending auctions.
constructor(clientOrConfig?: AleoLendingClient | ApiClientConfig, programId?: string)getAuctionData(auctionId: string): Promise<AuctionData | null>getNextAuctionId(nextIdKey?: string): Promise<number | null>getGlobalAuctionState(nextIdKey?: string): Promise<GlobalAuctionState | null>
convertAddressToField(address: string): bigint: Converts an Aleo address string to itsfieldrepresentation as a BigInt.parseUint(raw: string | null, type: "u128" | "u64" | ...): number: Parses various uint types from string.parseBool(raw: string | null): boolean | null: Parses boolean from string.parseField(raw: string | null): string | null: Parses field from string.parseAddress(raw: string | null): string | null: Parses Aleo address from string.
ISC