feat: initial implementation of Lending SDK

Author: UnMars

.gitignore

@@ -1 +1,2 @@
-node_modules
+node_modules
+dist

README.md

@@ -0,0 +1,285 @@
+# 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