@liquidium/client 0.6.0 → 0.7.0

package/dist/index.cjs

@@ -1055,8 +1055,11 @@ function normalizeEvmAddress(address) {
 // src/core/utils/time.ts
 var MILLISECONDS_PER_SECOND = 1e3;
 var SIGNATURE_VALIDITY_5_MINUTES_IN_SECONDS = 5n * 60n;
+function getCurrentUnixTimestampSeconds() {
+  return BigInt(Math.floor(Date.now() / MILLISECONDS_PER_SECOND));
+}
 function computeExpiryTimestampFromNow(signatureValidityInSeconds = SIGNATURE_VALIDITY_5_MINUTES_IN_SECONDS) {
-  return BigInt(Math.floor(Date.now() / MILLISECONDS_PER_SECOND)) + signatureValidityInSeconds;
+  return getCurrentUnixTimestampSeconds() + signatureValidityInSeconds;
 }
 
 // src/core/utils/variant.ts
@@ -1276,6 +1279,31 @@ var AccountsModule = class {
       throw mapCanisterCallErrorToLiquidiumError("get_wallet_profile", error);
     }
   }
+  /**
+   * Checks whether a profile is registered with the protocol.
+   *
+   * Production profile registration always links an initial wallet, and the
+   * protocol prevents removal of a profile's final wallet. This method uses
+   * that invariant because the current canister API has no direct existence
+   * query.
+   *
+   * @param profileId - The Liquidium profile principal text.
+   * @returns `true` when the profile has at least one linked wallet.
+   */
+  async profileExists(profileId) {
+    try {
+      const profilePrincipal = parseProfilePrincipal(profileId);
+      const wallets = await createLendingActor(
+        this.canisterContext
+      ).get_profile_wallets(profilePrincipal);
+      return wallets.length > 0;
+    } catch (error) {
+      if (error instanceof LiquidiumError) {
+        throw error;
+      }
+      throw mapCanisterCallErrorToLiquidiumError("get_profile_wallets", error);
+    }
+  }
   /**
    * Returns the current nonce for a wallet address.
    *
@@ -1381,6 +1409,17 @@ var AccountsModule = class {
 function normalizeProfileAccount(account) {
   return normalizeEvmAddress(account);
 }
+function parseProfilePrincipal(profileId) {
+  try {
+    return principal.Principal.fromText(profileId);
+  } catch (error) {
+    throw new LiquidiumError(
+      LiquidiumErrorCode.VALIDATION_ERROR,
+      `Invalid profile id: ${profileId}`,
+      error
+    );
+  }
+}
 function createInitializeAccountMessage(expiryTimestamp, nonce) {
   return `Liquidium: Initialize Account
 
@@ -1744,19 +1783,24 @@ var SdkApiQueryParam = {
   to: "to"
 };
 var ACTIVITIES = `${SDK_API_V2_PATH}/activities`;
+var HISTORY_ACTIVITIES = `${SDK_API_V2_PATH}/history/activities`;
 var HISTORY_USERS = `${SDK_API_V2_PATH}/history/users`;
 var INFLOW = `${SDK_API_V2_PATH}/inflow`;
 var SIMPLE_LOANS = `${SDK_API_V1_PATH}/instant-loans`;
-function buildHistoryUserTransactionsPath(user, query) {
-  const base = `${HISTORY_USERS}/${encodeURIComponent(user)}/transactions`;
+function buildHistoryUserTransactionsPath(profileId, query) {
+  const base = `${HISTORY_USERS}/${encodeURIComponent(profileId)}/transactions`;
   const qs = query.toString();
   return qs ? `${base}?${qs}` : base;
 }
-function buildHistoryUserLiquidationsPath(user, query) {
-  const base = `${HISTORY_USERS}/${encodeURIComponent(user)}/liquidations`;
+function buildHistoryUserLiquidationsPath(profileId, query) {
+  const base = `${HISTORY_USERS}/${encodeURIComponent(profileId)}/liquidations`;
   const qs = query.toString();
   return qs ? `${base}?${qs}` : base;
 }
+function buildProtocolActivityPath(query) {
+  const qs = query.toString();
+  return qs ? `${HISTORY_ACTIVITIES}?${qs}` : HISTORY_ACTIVITIES;
+}
 function buildActivitiesPath(request) {
   const query = new URLSearchParams({
     [SdkApiQueryParam.profileId]: request.profileId
@@ -2055,6 +2099,9 @@ function mapActivityTopUp(wire) {
 }
 
 // src/modules/history/history.ts
+var MIN_HISTORY_LIMIT = 1;
+var MAX_USER_HISTORY_LIMIT = 200;
+var MAX_PROTOCOL_ACTIVITY_LIMIT = 100;
 var HistoryModule = class {
   constructor(apiClient) {
     this.apiClient = apiClient;
@@ -2072,11 +2119,11 @@ var HistoryModule = class {
   /**
    * Returns transaction history for a user.
    *
-   * @param user - The Liquidium profile principal text.
+   * @param profileId - The Liquidium profile principal text.
    * @param filters - Optional pool, operation, state, time range, and pagination filters.
    * @returns Paginated user history entries.
    */
-  async getUserTransactionHistory(user, filters = {}) {
+  async getUserTransactionHistory(profileId, filters = {}) {
     const apiClient = this.requireApi();
     const query = new URLSearchParams();
     if (filters.cursor) {
@@ -2104,9 +2151,10 @@ var HistoryModule = class {
       query.set(SdkApiQueryParam.to, filters.to);
     }
     if (filters.limit !== void 0) {
+      validateHistoryLimit(filters.limit, MAX_USER_HISTORY_LIMIT);
       query.set(SdkApiQueryParam.limit, String(filters.limit));
     }
-    const requestPath = buildHistoryUserTransactionsPath(user, query);
+    const requestPath = buildHistoryUserTransactionsPath(profileId, query);
     const response = await apiClient.get(requestPath);
     return {
       items: response.items.map(mapUserTransactionHistoryEntry),
@@ -2116,11 +2164,11 @@ var HistoryModule = class {
   /**
    * Returns liquidation history for a user.
    *
-   * @param user - The Liquidium profile principal text.
+   * @param profileId - The Liquidium profile principal text.
    * @param filters - Optional pool, time range, and pagination filters.
    * @returns Paginated liquidation history entries.
    */
-  async getLiquidationHistory(user, filters = {}) {
+  async getLiquidationHistory(profileId, filters = {}) {
     const apiClient = this.requireApi();
     const query = new URLSearchParams();
     if (filters.cursor) {
@@ -2139,16 +2187,52 @@ var HistoryModule = class {
       query.set(SdkApiQueryParam.to, filters.to);
     }
     if (filters.limit !== void 0) {
+      validateHistoryLimit(filters.limit, MAX_USER_HISTORY_LIMIT);
       query.set(SdkApiQueryParam.limit, String(filters.limit));
     }
-    const requestPath = buildHistoryUserLiquidationsPath(user, query);
+    const requestPath = buildHistoryUserLiquidationsPath(profileId, query);
     const response = await apiClient.get(requestPath);
     return {
       items: response.items.map(mapUserLiquidationHistoryEntry),
       nextCursor: response.nextCursor
     };
   }
+  /**
+   * Returns recent protocol-wide lending activity across all users.
+   *
+   * @param filters - Optional pool, operation, and limit filters.
+   * @returns Recent confirmed lending activity entries.
+   */
+  async getProtocolActivity(filters = {}) {
+    const apiClient = this.requireApi();
+    const query = new URLSearchParams();
+    if (filters.poolId) {
+      query.set(SdkApiQueryParam.poolId, filters.poolId);
+    }
+    if (filters.operations?.length) {
+      query.set(SdkApiQueryParam.operations, filters.operations.join(","));
+    }
+    if (filters.limit !== void 0) {
+      validateHistoryLimit(filters.limit, MAX_PROTOCOL_ACTIVITY_LIMIT);
+      query.set(SdkApiQueryParam.limit, String(filters.limit));
+    }
+    const requestPath = buildProtocolActivityPath(query);
+    const response = await apiClient.get(requestPath);
+    return response.items.map(mapProtocolActivityEntry);
+  }
 };
+function mapProtocolActivityEntry(item) {
+  return {
+    id: item.id,
+    operation: item.operation,
+    poolId: item.poolId,
+    asset: item.asset,
+    decimals: item.decimals,
+    amount: parseBigInt(item.amount, "protocol activity amount"),
+    timestamp: item.timestamp,
+    txids: item.txids
+  };
+}
 function mapUserTransactionHistoryEntry(item) {
   return {
     id: item.id,
@@ -2171,7 +2255,12 @@ function mapUserLiquidationHistoryEntry(item) {
     amount: parseBigInt(item.amount, "history user amount"),
     poolId: item.poolId,
     timestamp: item.timestamp,
-    status: item.status,
+    status: {
+      operation: "liquidation",
+      state: "completed",
+      confirmations: null,
+      requiredConfirmations: null
+    },
     txids: item.txids
   };
 }
@@ -2196,6 +2285,15 @@ function validateHistoryStateFilter(state) {
       );
   }
 }
+function validateHistoryLimit(limit, maximumLimit) {
+  if (Number.isInteger(limit) && limit >= MIN_HISTORY_LIMIT && limit <= maximumLimit) {
+    return;
+  }
+  throw new LiquidiumError(
+    LiquidiumErrorCode.VALIDATION_ERROR,
+    `History limit must be an integer between ${MIN_HISTORY_LIMIT} and ${maximumLimit}`
+  );
+}
 
 // src/core/utils/inflow-subaccount.ts
 var INFLOW_DEPOSIT_PREFIX = 1;
@@ -5151,9 +5249,78 @@ function mapOutflowTypeToStatusOperation(outflowType) {
   return outflowType;
 }
 
+// src/core/asset-metadata.ts
+var ASSET_METADATA = {
+  [Asset.BTC]: {
+    symbol: Asset.BTC,
+    displayName: "Bitcoin"
+  },
+  [Asset.ETH]: {
+    symbol: Asset.ETH,
+    displayName: "Ethereum"
+  },
+  [Asset.ICP]: {
+    symbol: Asset.ICP,
+    displayName: "Internet Computer"
+  },
+  [Asset.USDC]: {
+    symbol: Asset.USDC,
+    displayName: "USD Coin"
+  },
+  [Asset.USDT]: {
+    symbol: Asset.USDT,
+    displayName: "Tether USD"
+  }
+};
+function getAssetMetadata(asset) {
+  return ASSET_METADATA[asset];
+}
+
 // src/core/rates.ts
 var RATE_SCALE = 1000000000000000000000000000n;
 var RATE_DECIMALS = BigInt(RATE_SCALE.toString().length - 1);
+var INTEREST_YEAR_365_DAYS_SECONDS = 31536000n;
+var SUPPLY_COMPOUNDING_INTERVAL_15_SECONDS = 15n;
+function estimateBorrowApy(borrowApr) {
+  return estimateCompoundedApy(borrowApr, 1n);
+}
+function estimateSupplyApy(supplyApr) {
+  return estimateCompoundedApy(
+    supplyApr,
+    SUPPLY_COMPOUNDING_INTERVAL_15_SECONDS
+  );
+}
+function estimateCompoundedApy(apr, compoundingIntervalSeconds) {
+  if (apr < 0n) {
+    throw new RangeError("APR cannot be negative");
+  }
+  if (apr === 0n) {
+    return 0n;
+  }
+  const periodsPerYear = INTEREST_YEAR_365_DAYS_SECONDS / compoundingIntervalSeconds;
+  const ratePerPeriod = apr * compoundingIntervalSeconds / INTEREST_YEAR_365_DAYS_SECONDS;
+  const annualGrowth = fixedPointPow(
+    RATE_SCALE + ratePerPeriod,
+    periodsPerYear
+  );
+  return annualGrowth - RATE_SCALE;
+}
+function fixedPointPow(base, exponent) {
+  let remainingExponent = exponent;
+  let currentBase = base;
+  let result = RATE_SCALE;
+  while (remainingExponent > 0n) {
+    if (remainingExponent % 2n === 1n) {
+      result = fixedPointMultiply(result, currentBase);
+    }
+    currentBase = fixedPointMultiply(currentBase, currentBase);
+    remainingExponent /= 2n;
+  }
+  return result;
+}
+function fixedPointMultiply(left, right) {
+  return (left * right + RATE_SCALE / 2n) / RATE_SCALE;
+}
 
 // src/core/utils/asset-decimals.ts
 var ASSET_NATIVE_DECIMALS = {
@@ -5180,12 +5347,14 @@ var DECIMAL_BASE = 10;
 var PAIR_SEPARATOR = "_";
 var USDT_SYMBOL = "USDT";
 function mapDecodedPoolToPool(pool, rate) {
+  const assetMetadata = getAssetMetadata(pool.asset);
   const totalSupply = pool.total_supply_at_last_sync * pool.lending_index / RATE_SCALE;
   const totalDebt = pool.total_debt_at_last_sync * pool.borrow_index / RATE_SCALE;
   const availableLiquidity = totalSupply > totalDebt ? totalSupply - totalDebt : 0n;
   return {
     id: pool.principal.toString(),
     asset: pool.asset,
+    displayName: assetMetadata.displayName,
     chain: pool.chain,
     decimals: getAssetNativeDecimals(pool.asset),
     frozen: pool.frozen,
@@ -5201,7 +5370,9 @@ function mapDecodedPoolToPool(pool, rate) {
     reserveFactor: pool.reserve_factor,
     rateDecimals: RATE_DECIMALS,
     lendingRate: rate[1],
+    estimatedLendingApy: estimateSupplyApy(rate[1]),
     borrowingRate: rate[0],
+    estimatedBorrowingApy: estimateBorrowApy(rate[0]),
     utilizationRate: rate[2],
     baseRate: pool.base_rate,
     optimalUtilizationRate: pool.optimal_utilization_rate,
@@ -5235,7 +5406,9 @@ function mapGetPoolRateResponseToPoolRate(rate) {
   return {
     rateDecimals: RATE_DECIMALS,
     borrowRate: rate[0],
+    estimatedBorrowApy: estimateBorrowApy(rate[0]),
     lendRate: rate[1],
+    estimatedLendApy: estimateSupplyApy(rate[1]),
     utilizationRate: rate[2]
   };
 }
@@ -5289,15 +5462,32 @@ var MarketModule = class {
     }
   }
   /**
-   * Returns the latest asset prices reported by the protocol.
+   * Returns the current cached asset prices reported by the protocol.
    *
-   * @returns The latest protocol price map keyed by market asset symbol.
+   * @returns The current protocol price map keyed by market asset symbol.
    */
   async getAssetPrices() {
+    return (await this.getAssetPriceSnapshot()).prices;
+  }
+  /**
+   * Returns protocol prices with the time at which the SDK completed the fetch.
+   *
+   * `fetchedAt` is an SDK retrieval time, not an oracle observation timestamp.
+   * The current lending canister price response does not expose the underlying
+   * oracle timestamp.
+   *
+   * @returns Protocol prices and their SDK fetch timestamp.
+   */
+  async getAssetPriceSnapshot() {
     try {
-      return mapGetPricesResponseToAssetPrices(
+      const prices = mapGetPricesResponseToAssetPrices(
         await createLendingActor(this.canisterContext).get_prices()
       );
+      const fetchedAtUnixSeconds = getCurrentUnixTimestampSeconds();
+      return {
+        prices,
+        fetchedAt: fetchedAtUnixSeconds
+      };
     } catch (error) {
       if (error instanceof LiquidiumError) {
         throw error;
@@ -5399,6 +5589,10 @@ function decodeSupportedFlexiblePools(rawPools) {
   return decodedPools;
 }
 
+// src/modules/positions/health-factor.ts
+var HEALTH_FACTOR_SCALE = 1000n;
+var HEALTH_FACTOR_DECIMALS = 3n;
+
 // src/modules/positions/mappers.ts
 var USD_VALUE_SCALE_DECIMALS = 27n;
 function mapDecodedPositionViewToPosition(view) {
@@ -5527,11 +5721,13 @@ var PositionsModule = class {
       const [healthFactor, userStatsRecord] = await createFlexibleLendingActor(
         this.canisterContext
       ).get_health_factor(principal.Principal.fromText(profileId));
+      const userStats = mapDecodedUserStatsToUserStats(
+        decodeFlexibleUserStats(userStatsRecord)
+      );
       return {
-        healthFactor,
-        userStats: mapDecodedUserStatsToUserStats(
-          decodeFlexibleUserStats(userStatsRecord)
-        )
+        healthFactor: userStats.debt === 0n ? null : healthFactor,
+        healthFactorDecimals: HEALTH_FACTOR_DECIMALS,
+        userStats
       };
     } catch (error) {
       if (error instanceof LiquidiumError) {
@@ -5571,7 +5767,7 @@ var PositionsModule = class {
    * @returns Derived position summary for the requested profile.
    */
   async getUserPositionSummary(profileId) {
-    const { healthFactor, userStats } = await this.getHealthFactor(profileId);
+    const { healthFactor, healthFactorDecimals, userStats } = await this.getHealthFactor(profileId);
     const collateral = userStats.collateral;
     const debt = userStats.debt;
     const maxBorrowableUsd = userStats.borrowingPower.maxBorrowableUsd;
@@ -5587,7 +5783,8 @@ var PositionsModule = class {
       currentLtvBps,
       weightedMaxLtvBps: userStats.borrowingPower.weightedMaxLtv,
       weightedLiquidationThresholdBps: userStats.weightedLiquidationThreshold,
-      healthFactor
+      healthFactor,
+      healthFactorDecimals
     };
   }
   /**
@@ -6871,9 +7068,9 @@ function isSimpleLoanDepositExpired(input) {
   if (input.expiryTimestamp === null) {
     return false;
   }
-  return input.expiryTimestamp <= getCurrentUnixTimestampSeconds();
+  return input.expiryTimestamp <= getCurrentUnixTimestampSeconds2();
 }
-function getCurrentUnixTimestampSeconds() {
+function getCurrentUnixTimestampSeconds2() {
   return BigInt(Math.floor(Date.now() / MILLISECONDS_PER_SECOND3));
 }
 function deriveDepositExpiryTimestamp(input) {
@@ -7474,6 +7671,7 @@ function resolveEvmReadClient(config) {
   });
 }
 
+exports.ASSET_METADATA = ASSET_METADATA;
 exports.AccountsModule = AccountsModule;
 exports.ActivitiesModule = ActivitiesModule;
 exports.ActivityFilter = ActivityFilter;
@@ -7482,7 +7680,10 @@ exports.CK_ETH_DEPOSIT_CONTRACT_ADDRESS = CK_ETH_DEPOSIT_CONTRACT_ADDRESS;
 exports.Chain = Chain;
 exports.Environment = Environment;
 exports.EvmSupplyApprovalStrategy = EvmSupplyApprovalStrategy;
+exports.HEALTH_FACTOR_DECIMALS = HEALTH_FACTOR_DECIMALS;
+exports.HEALTH_FACTOR_SCALE = HEALTH_FACTOR_SCALE;
 exports.HistoryModule = HistoryModule;
+exports.INTEREST_YEAR_365_DAYS_SECONDS = INTEREST_YEAR_365_DAYS_SECONDS;
 exports.LendingModule = LendingModule;
 exports.LiquidiumAccountType = LiquidiumAccountType;
 exports.LiquidiumClient = LiquidiumClient;
@@ -7499,6 +7700,7 @@ exports.QuoteValidationErrorCode = QuoteValidationErrorCode;
 exports.QuoteWarningCode = QuoteWarningCode;
 exports.RATE_DECIMALS = RATE_DECIMALS;
 exports.RATE_SCALE = RATE_SCALE;
+exports.SUPPLY_COMPOUNDING_INTERVAL_15_SECONDS = SUPPLY_COMPOUNDING_INTERVAL_15_SECONDS;
 exports.SimpleLoanCreatedError = SimpleLoanCreatedError;
 exports.SimpleLoansModule = SimpleLoansModule;
 exports.SupplyAction = SupplyAction;
@@ -7508,7 +7710,10 @@ exports.USDT_CONTRACT_ADDRESS = USDT_CONTRACT_ADDRESS;
 exports.WalletActionKind = WalletActionKind;
 exports.WalletExecutionKind = WalletExecutionKind;
 exports.createTransferErc20Transaction = createTransferErc20Transaction;
+exports.estimateBorrowApy = estimateBorrowApy;
+exports.estimateSupplyApy = estimateSupplyApy;
 exports.executeWith = executeWith;
+exports.getAssetMetadata = getAssetMetadata;
 exports.getMinimumBorrowAmount = getMinimumBorrowAmount;
 exports.getMinimumDepositAmount = getMinimumDepositAmount;
 exports.getMinimumWithdrawAmount = getMinimumWithdrawAmount;