lending-sdk

Eclipse Lending SDK for Aleo

A TypeScript SDK for interacting with Eclipse Lending contracts on the Aleo blockchain.

Installation

npm install @eclipse/lending-sdk

Usage

Initializing Services

All 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"
);

Using the PoolService

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");

Using other Services (Vault, Stablecoin, Auction)

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 ID

Using the AleoLendingClient Directly

You 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 ID

Utilities

The 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.

API Reference

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.

AleoLendingClient

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.

Pool Mappings (on AleoLendingClient)

(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>

Vault Mappings (on AleoLendingClient)

(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>

Stablecoin Mappings (on AleoLendingClient)

(Default Program: floflo_stablecoin_vault.aleo)

• getCollateralBalance(programId: string, userAddress: string): Promise<number | null>
• getDebtBalance(programId: string, userAddress: string): Promise<number | null>

Auction Mappings (on AleoLendingClient)

(Default Program: eclipse_lending_auction.aleo)

• getAuction(programId: string, auctionId: string): Promise<AuctionData | null>
• getNextAuctionId(programId: string, keyField?: string): Promise<number | null>

PoolService

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>

VaultService

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>

StablecoinService

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).

AuctionService

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>

Utility Functions

• convertAddressToField(address: string): bigint: Converts an Aleo address string to its field representation 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.

License

ISC