lending-sdk/README.md

Interact with ease with the eclipse lending contracts

# Eclipse Lending SDK for Aleo

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

## Installation

```bash
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.

```typescript
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`):

```typescript
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`):

```typescript
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.

```typescript
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:

```typescript
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