@folks-finance/xchain-sdk 0.0.1

package/src/common/utils/formulae.ts

@@ -0,0 +1,124 @@
+import * as dn from "dnum";
+
+import { SECONDS_IN_YEAR, expBySquaring, unixTime } from "./math-lib.js";
+
+import type { Dnum } from "dnum";
+
+export function calcPeriodNumber(offset: bigint, length: bigint): bigint {
+  return (BigInt(unixTime()) + offset) / length;
+}
+
+export function calcNextPeriodReset(periodNumber: bigint, offset: bigint, length: bigint): bigint {
+  return (periodNumber + BigInt(1)) * length - offset;
+}
+
+export function calcDepositInterestIndex(dirt1: Dnum, diit1: Dnum, latestUpdate: bigint): Dnum {
+  const dt = BigInt(unixTime()) - latestUpdate;
+  return dn.mul(
+    diit1,
+    dn.add(
+      dn.from(1, 18),
+      dn.div(dn.mul(dirt1, dt, { rounding: "ROUND_DOWN" }), SECONDS_IN_YEAR, {
+        rounding: "ROUND_DOWN",
+      }),
+    ),
+    { rounding: "ROUND_DOWN" },
+  );
+}
+
+export function calcBorrowInterestIndex(birt1: Dnum, biit1: Dnum, latestUpdate: bigint): Dnum {
+  const dt = BigInt(unixTime()) - latestUpdate;
+  return dn.mul(
+    biit1,
+    expBySquaring(dn.add(dn.from(1, 18), dn.div(birt1, SECONDS_IN_YEAR, { rounding: "ROUND_DOWN" })), dt),
+    { rounding: "ROUND_DOWN" },
+  );
+}
+
+export function calcRewardIndex(used: bigint, ma: bigint, rit1: Dnum, rs: Dnum, latestUpdate: bigint): Dnum {
+  if (used <= ma) return rit1;
+  const dt = BigInt(unixTime()) - latestUpdate;
+  return dn.add(
+    rit1,
+    dn.div(dn.mul(rs, dt, { rounding: "ROUND_DOWN" }), used, {
+      rounding: "ROUND_DOWN",
+    }),
+  );
+}
+
+export function toFAmount(underlyingAmount: bigint, diit: Dnum): bigint {
+  const [fAmount] = dn.div([underlyingAmount, 0], diit, { rounding: "ROUND_DOWN" });
+  return fAmount;
+}
+
+export function toUnderlyingAmount(fAmount: bigint, diit: Dnum): bigint {
+  const [underlyingAmount] = dn.mul([fAmount, 0], diit, { rounding: "ROUND_DOWN" });
+  return underlyingAmount;
+}
+
+function calcAssetDollarValue(amount: bigint, tokenPrice: Dnum, tokenDecimals: number): Dnum {
+  return dn.mul([amount, tokenDecimals], tokenPrice, {
+    rounding: "ROUND_DOWN",
+  });
+}
+
+export function calcCollateralAssetLoanValue(
+  amount: bigint,
+  tokenPrice: Dnum,
+  tokenDecimals: number,
+  collateralFactor: Dnum,
+): Dnum {
+  return dn.mul(calcAssetDollarValue(amount, tokenPrice, tokenDecimals), collateralFactor, { rounding: "ROUND_DOWN" });
+}
+
+export function calcBorrowAssetLoanValue(
+  amount: bigint,
+  tokenPrice: Dnum,
+  tokenDecimals: number,
+  borrowFactor: Dnum,
+): Dnum {
+  return dn.mul(calcAssetDollarValue(amount, tokenPrice, tokenDecimals), borrowFactor, { rounding: "ROUND_UP" });
+}
+
+export function calcBorrowBalance(bbtn1: bigint, biit: Dnum, biitn1: Dnum): bigint {
+  const [borrowBalance] = dn.mul([bbtn1, 0], dn.div(biit, biitn1, { rounding: "ROUND_UP" }), {
+    rounding: "ROUND_UP",
+  });
+  return borrowBalance;
+}
+
+export function calcStableInterestRate(bbt: bigint, amount: bigint, sbirtn1: Dnum, sbirt1: Dnum): Dnum {
+  return dn.div(dn.add(dn.mul(sbirtn1, [bbt, 0]), dn.mul(sbirt1, [amount, 0])), dn.add([bbt, 0], [amount, 0]));
+}
+
+export function calcLtvRatio(totalBorrowBalanceValue: Dnum, totalCollateralBalanceValue: Dnum): Dnum {
+  const [, decimals] = totalBorrowBalanceValue;
+  if (dn.equal(totalCollateralBalanceValue, 0)) return dn.from(0, decimals);
+  return dn.div(totalBorrowBalanceValue, totalCollateralBalanceValue, {
+    rounding: "ROUND_UP",
+  });
+}
+
+export function calcBorrowUtilisationRatio(
+  totalEffectiveBorrowBalanceValue: Dnum,
+  totalEffectiveCollateralBalanceValue: Dnum,
+): Dnum {
+  const [, decimals] = totalEffectiveBorrowBalanceValue;
+  if (dn.equal(totalEffectiveCollateralBalanceValue, 0)) return dn.from(0, decimals);
+  return dn.div(totalEffectiveBorrowBalanceValue, totalEffectiveCollateralBalanceValue, { rounding: "ROUND_UP" });
+}
+
+export function calcLiquidationMargin(
+  totalEffectiveBorrowBalanceValue: Dnum,
+  totalEffectiveCollateralBalanceValue: Dnum,
+): Dnum {
+  const [, decimals] = totalEffectiveBorrowBalanceValue;
+  if (dn.equal(totalEffectiveCollateralBalanceValue, 0)) return dn.from(0, decimals);
+  return dn.div(
+    dn.sub(totalEffectiveCollateralBalanceValue, totalEffectiveBorrowBalanceValue),
+    totalEffectiveCollateralBalanceValue,
+    {
+      rounding: "ROUND_DOWN",
+    },
+  );
+}

package/src/common/utils/gmp.ts

@@ -0,0 +1,16 @@
+import { CCIP_DATA, WORMHOLE_DATA } from "../constants/gmp.js";
+
+import type { FolksChainId } from "../types/chain.js";
+import type { CCIPData, WormholeData } from "../types/gmp.js";
+
+export function getWormholeData(folksChainId: FolksChainId): WormholeData {
+  const wormholeData = WORMHOLE_DATA[folksChainId];
+  if (wormholeData) return wormholeData;
+  throw new Error(`Wormhole data not found for folksChainId: ${folksChainId}`);
+}
+
+export function getCcipData(folksChainId: FolksChainId): CCIPData {
+  const ccipData = CCIP_DATA[folksChainId];
+  if (ccipData) return ccipData;
+  throw new Error(`CCIP data not found for folksChainId: ${folksChainId}`);
+}

package/src/common/utils/math-lib.ts

@@ -0,0 +1,46 @@
+import * as dn from "dnum";
+
+import type { Dnum } from "dnum";
+
+export const SECONDS_IN_YEAR = BigInt(365 * 24 * 60 * 60);
+export const HOURS_IN_YEAR = BigInt(365 * 24);
+
+export function unixTime(): number {
+  return Math.floor(Date.now() / 1000);
+}
+
+export function expBySquaring(x: Dnum, n: bigint): Dnum {
+  const [, decimals] = x;
+  const one = dn.from(1, decimals);
+
+  if (n === BigInt(0)) return one;
+
+  let y = one;
+  while (n > BigInt(1)) {
+    if (n % BigInt(2)) {
+      y = dn.mul(x, y, { rounding: "ROUND_DOWN" });
+      n = (n - BigInt(1)) / BigInt(2);
+    } else {
+      n = n / BigInt(2);
+    }
+    x = dn.mul(x, x, { rounding: "ROUND_DOWN" });
+  }
+  return dn.mul(x, y, { rounding: "ROUND_DOWN" });
+}
+
+function compound(rate: Dnum, period: bigint): Dnum {
+  const [, decimals] = rate;
+  const one = dn.from(1, decimals);
+  return dn.sub(expBySquaring(dn.add(one, dn.div(rate, period)), period), one);
+}
+
+export function compoundEverySecond(rate: Dnum): Dnum {
+  return compound(rate, SECONDS_IN_YEAR);
+}
+
+export function compoundEveryHour(rate: Dnum): Dnum {
+  return compound(rate, HOURS_IN_YEAR);
+}
+
+export const bigIntMax = (...args: Array<bigint>) => args.reduce((m, e) => (e > m ? e : m));
+export const bigIntMin = (...args: Array<bigint>) => args.reduce((m, e) => (e < m ? e : m));

package/src/common/utils/messages.ts

@@ -0,0 +1,192 @@
+import {
+  buildEvmMessageToSend,
+  estimateEvmCcipDataGasLimit,
+  estimateEvmWormholeDataGasLimit,
+  getSendTokenStateOverride,
+} from "../../chains/evm/common/utils/message.js";
+import { getHubChainAdapterAddress } from "../../chains/evm/hub/utils/chain.js";
+import { exhaustiveCheck } from "../../utils/exhaustive-check.js";
+import { ChainType } from "../types/chain.js";
+import { MessageDirection } from "../types/gmp.js";
+import { Action, AdapterType } from "../types/message.js";
+
+import { convertFromGenericAddress } from "./address.js";
+import { getFolksChain, getSpokeChainAdapterAddress } from "./chain.js";
+import { getCcipData, getWormholeData } from "./gmp.js";
+
+import type { FolksChainId, NetworkType } from "../types/chain.js";
+import type { FolksProvider } from "../types/core.js";
+import type { MessageAdapters, MessageBuilderParams, MessageToSend, OptionalFeeParams } from "../types/message.js";
+import type { Client as EVMProvider, StateOverride } from "viem";
+
+export function buildMessageToSend(
+  chainType: ChainType,
+  messageToSendBuilderParams: MessageBuilderParams,
+  feeParams: OptionalFeeParams = {},
+): MessageToSend {
+  switch (chainType) {
+    case ChainType.EVM: {
+      return buildEvmMessageToSend(messageToSendBuilderParams, feeParams);
+    }
+    default:
+      return exhaustiveCheck(chainType);
+  }
+}
+
+function getAdapterId(messageDirection: MessageDirection, adapters: MessageAdapters): AdapterType {
+  if (messageDirection === MessageDirection.SpokeToHub) return adapters.adapterId;
+  return adapters.returnAdapterId;
+}
+
+function getAdaptersAddresses(
+  messageDirection: MessageDirection,
+  sourceFolksChainId: FolksChainId,
+  destFolksChainId: FolksChainId,
+  network: NetworkType,
+  adapterId: AdapterType,
+) {
+  if (messageDirection === MessageDirection.SpokeToHub)
+    return {
+      sourceAdapterAddress: getSpokeChainAdapterAddress(sourceFolksChainId, network, adapterId),
+      destAdapterAddress: getHubChainAdapterAddress(network, adapterId),
+    };
+  return {
+    sourceAdapterAddress: getHubChainAdapterAddress(network, adapterId),
+    destAdapterAddress: getSpokeChainAdapterAddress(destFolksChainId, network, adapterId),
+  };
+}
+
+export async function estimateAdapterReceiveGasLimit(
+  sourceFolksChainId: FolksChainId,
+  destFolksChainId: FolksChainId,
+  destFolksChainProvider: FolksProvider,
+  network: NetworkType,
+  messageDirection: MessageDirection,
+  messageBuilderParams: MessageBuilderParams,
+  receiverValue = BigInt(0),
+  returnGasLimit = BigInt(0),
+) {
+  const destFolksChain = getFolksChain(destFolksChainId, network);
+
+  const adapterId = getAdapterId(messageDirection, messageBuilderParams.adapters);
+  const { sourceAdapterAddress, destAdapterAddress } = getAdaptersAddresses(
+    messageDirection,
+    sourceFolksChainId,
+    destFolksChainId,
+    network,
+    adapterId,
+  );
+
+  switch (destFolksChain.chainType) {
+    case ChainType.EVM: {
+      let stateOverride: StateOverride = [];
+      if (messageBuilderParams.action === Action.SendToken) {
+        stateOverride = stateOverride.concat(
+          getSendTokenStateOverride(
+            destFolksChainId,
+            messageBuilderParams.data.folksTokenId,
+            messageBuilderParams.extraArgs,
+          ),
+        );
+      }
+      switch (adapterId) {
+        case AdapterType.WORMHOLE_DATA: {
+          const sourceWormholeChainId = getWormholeData(sourceFolksChainId).wormholeChainId;
+          const wormholeRelayer = convertFromGenericAddress(
+            getWormholeData(destFolksChainId).wormholeRelayer,
+            ChainType.EVM,
+          );
+
+          return await estimateEvmWormholeDataGasLimit(
+            // eslint-disable-next-line @typescript-eslint/non-nullable-type-assertion-style
+            destFolksChainProvider as EVMProvider,
+            messageBuilderParams,
+            receiverValue,
+            returnGasLimit,
+            sourceWormholeChainId,
+            wormholeRelayer,
+            destAdapterAddress,
+            sourceAdapterAddress,
+            stateOverride,
+          );
+        }
+        case AdapterType.WORMHOLE_CCTP: {
+          const { sourceAdapterAddress, destAdapterAddress } = getAdaptersAddresses(
+            messageDirection,
+            sourceFolksChainId,
+            destFolksChainId,
+            network,
+            AdapterType.WORMHOLE_DATA,
+          );
+          const sourceWormholeChainId = getWormholeData(sourceFolksChainId).wormholeChainId;
+          const wormholeRelayer = convertFromGenericAddress(
+            getWormholeData(destFolksChainId).wormholeRelayer,
+            ChainType.EVM,
+          );
+
+          // Due to ERC20 transfer and additional checks in the Wormhole CCTP Adapter
+          const increaseGasLimit = BigInt(150000);
+          const gasLimitEstimation = await estimateEvmWormholeDataGasLimit(
+            // eslint-disable-next-line @typescript-eslint/non-nullable-type-assertion-style
+            destFolksChainProvider as EVMProvider,
+            messageBuilderParams,
+            receiverValue,
+            returnGasLimit,
+            sourceWormholeChainId,
+            wormholeRelayer,
+            destAdapterAddress,
+            sourceAdapterAddress,
+            stateOverride,
+          );
+          return gasLimitEstimation + increaseGasLimit;
+        }
+        case AdapterType.HUB: {
+          return 0n;
+        }
+        case AdapterType.CCIP_DATA: {
+          const sourceCcipChainId = getCcipData(sourceFolksChainId).ccipChainId;
+          const ccipRouter = convertFromGenericAddress(getCcipData(destFolksChainId).ccipRouter, ChainType.EVM);
+          return await estimateEvmCcipDataGasLimit(
+            // eslint-disable-next-line @typescript-eslint/non-nullable-type-assertion-style
+            destFolksChainProvider as EVMProvider,
+            messageBuilderParams,
+            returnGasLimit,
+            sourceCcipChainId,
+            ccipRouter,
+            destAdapterAddress,
+            sourceAdapterAddress,
+          );
+        }
+        case AdapterType.CCIP_TOKEN: {
+          const { sourceAdapterAddress, destAdapterAddress } = getAdaptersAddresses(
+            messageDirection,
+            sourceFolksChainId,
+            destFolksChainId,
+            network,
+            AdapterType.CCIP_DATA,
+          );
+          const sourceCcipChainId = getCcipData(sourceFolksChainId).ccipChainId;
+          const ccipRouter = convertFromGenericAddress(getCcipData(destFolksChainId).ccipRouter, ChainType.EVM);
+
+          // Due to ERC20 transfer and additional checks in the CCIP Token Adapter
+          const increaseGasLimit = BigInt(150000);
+          const gasLimitEstimation = await estimateEvmCcipDataGasLimit(
+            // eslint-disable-next-line @typescript-eslint/non-nullable-type-assertion-style
+            destFolksChainProvider as EVMProvider,
+            messageBuilderParams,
+            returnGasLimit,
+            sourceCcipChainId,
+            ccipRouter,
+            destAdapterAddress,
+            sourceAdapterAddress,
+          );
+          return gasLimitEstimation + increaseGasLimit;
+        }
+        default:
+          return exhaustiveCheck(adapterId);
+      }
+    }
+    default:
+      return exhaustiveCheck(destFolksChain.chainType);
+  }
+}

package/src/common/utils/token.ts

@@ -0,0 +1,7 @@
+import { CIRCLE_FOLKS_TOKEN_ID } from "../constants/token.js";
+
+import type { FolksTokenId } from "../types/token.js";
+
+export function isCircleToken(folksTokenId: FolksTokenId): boolean {
+  return CIRCLE_FOLKS_TOKEN_ID.includes(folksTokenId);
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+// === CORE ===
+export { FolksCore } from "./xchain/core/folks-core.js";
+
+// === MODULES ===
+export { FolksAccount, FolksLoan, FolksOracle, FolksPool } from "./xchain/modules/index.js";
+
+// === COMMON ===
+export * from "./common/types/adapter.js";
+export * from "./common/types/address.js";
+export * from "./common/types/chain.js";
+export * from "./common/types/core.js";
+export * from "./common/types/gmp.js";
+export * from "./common/types/lending.js";
+export * from "./common/types/message.js";
+export * from "./common/types/module.js";
+export * from "./common/types/token.js";
+
+export * from "./common/constants/bytes.js";
+export * from "./common/constants/chain.js";
+export * from "./common/constants/gmp.js";
+export * from "./common/constants/message.js";
+
+export { getSupportedMessageAdapters } from "./common/utils/adapter.js";
+export { convertFromGenericAddress, convertToGenericAddress } from "./common/utils/address.js";
+export { generateLoanId } from "./common/utils/bytes.js";
+export { getAdapterAddress } from "./common/utils/chain.js";
+export { getCcipData, getWormholeData } from "./common/utils/gmp.js";
+
+// === HUB ===
+export { isHubChain } from "./chains/evm/hub/utils/chain.js";
+
+// === CHAINS ===
+
+// - EVM
+export * from "./chains/evm/common/constants/chain.js";
+
+export * from "./chains/evm/common/types/chain.js";
+
+export { isEvmChainId } from "./chains/evm/common/utils/chain.js";
+
+// - EVM: HUB
+export * from "./chains/evm/hub/types/account.js";
+export * from "./chains/evm/hub/types/chain.js";
+export * from "./chains/evm/hub/types/loan.js";
+export * from "./chains/evm/hub/types/oracle.js";
+export * from "./chains/evm/hub/types/pool.js";
+export * from "./chains/evm/hub/types/token.js";

package/src/utils/exhaustive-check.ts

@@ -0,0 +1,3 @@
+export const exhaustiveCheck = (value: never): never => {
+  throw new Error(`ERROR! Reached forbidden guard function with unexpected value: ${JSON.stringify(value)}`);
+};

package/src/xchain/core/folks-core.ts

@@ -0,0 +1,128 @@
+import { initProviders } from "../../chains/evm/common/utils/provider.js";
+import { getHubChain } from "../../chains/evm/hub/utils/chain.js";
+import { ChainType } from "../../common/types/chain.js";
+import { getFolksChain } from "../../common/utils/chain.js";
+import { exhaustiveCheck } from "../../utils/exhaustive-check.js";
+
+import type { FolksChainId, FolksChain, NetworkType } from "../../common/types/chain.js";
+import type {
+  FolksCoreProvider,
+  FolksSigner,
+  FolksCoreConfig,
+  FolksProviderType,
+  FolksSignerType,
+  FolksProvider,
+} from "../../common/types/core.js";
+import type { Client as EVMProvider } from "viem";
+
+export class FolksCore {
+  private static instance: FolksCore | undefined;
+  private folksCoreProvider: FolksCoreProvider;
+
+  private selectedNetwork: NetworkType;
+  private folksSigner?: FolksSigner;
+
+  private constructor(folksCoreConfig: FolksCoreConfig) {
+    this.selectedNetwork = folksCoreConfig.network;
+    this.folksCoreProvider = { evm: {} as Record<FolksChainId, EVMProvider> };
+    this.folksCoreProvider.evm = initProviders(folksCoreConfig.provider.evm);
+  }
+
+  static init(folksCoreConfig: FolksCoreConfig): FolksCore {
+    if (FolksCore.instance) throw new Error("FolksCore is already initialized");
+    FolksCore.instance = new FolksCore(folksCoreConfig);
+    return FolksCore.instance;
+  }
+
+  static isInitialized(): boolean {
+    return !!FolksCore.instance;
+  }
+
+  static getInstance(): FolksCore {
+    if (FolksCore.instance) return FolksCore.instance;
+    throw new Error("FolksCore is not initialized");
+  }
+
+  static getProvider<T extends ChainType>(folksChainId: FolksChainId): FolksProviderType<T> {
+    const folksChain = getFolksChain(folksChainId, this.getSelectedNetwork());
+    switch (folksChain.chainType) {
+      case ChainType.EVM:
+        return FolksCore.getEVMProvider(folksChainId) as FolksProviderType<T>;
+      default:
+        return exhaustiveCheck(folksChain.chainType);
+    }
+  }
+
+  static getFolksSigner() {
+    const instance = this.getInstance();
+    if (!instance.folksSigner) throw new Error("FolksSigner is not initialized");
+
+    return instance.folksSigner;
+  }
+
+  static getSigner<T extends ChainType>(): FolksSignerType<T> {
+    const { signer } = this.getFolksSigner();
+
+    return signer as FolksSignerType<T>;
+  }
+
+  static getSelectedFolksChain(): FolksChain {
+    const { folksChainId } = this.getFolksSigner();
+
+    return getFolksChain(folksChainId, this.getSelectedNetwork());
+  }
+
+  static getSelectedNetwork() {
+    const instance = this.getInstance();
+    return instance.selectedNetwork;
+  }
+
+  static getHubProvider(): EVMProvider {
+    const instance = this.getInstance();
+    const hubFolksChainId = getHubChain(instance.selectedNetwork).folksChainId;
+
+    const hubProvider = instance.folksCoreProvider.evm[hubFolksChainId];
+    if (!hubProvider) throw new Error(`Hub Provider has not been initialized`);
+
+    return hubProvider;
+  }
+
+  static setProvider(folksChainId: FolksChainId, provider: FolksProvider) {
+    const instance = this.getInstance();
+    const folksChain = getFolksChain(folksChainId, this.getSelectedNetwork());
+    switch (folksChain.chainType) {
+      case ChainType.EVM:
+        // eslint-disable-next-line @typescript-eslint/non-nullable-type-assertion-style -- in the future FolksProvider will contain more than just EVMProvider
+        instance.folksCoreProvider.evm[folksChainId] = provider as EVMProvider;
+        break;
+      default:
+        return exhaustiveCheck(folksChain.chainType);
+    }
+  }
+
+  static setNetwork(network: NetworkType) {
+    const instance = this.getInstance();
+    instance.selectedNetwork = network;
+  }
+
+  static setFolksSigner(folksSigner: FolksSigner) {
+    const instance = this.getInstance();
+    const folksChain = getFolksChain(folksSigner.folksChainId, this.getSelectedNetwork());
+
+    switch (folksChain.chainType) {
+      case ChainType.EVM:
+        instance.folksSigner = folksSigner;
+        break;
+      default:
+        return exhaustiveCheck(folksChain.chainType);
+    }
+  }
+
+  static getEVMProvider(folksChainId: FolksChainId): EVMProvider {
+    const instance = this.getInstance();
+    const evmProvider = instance.folksCoreProvider.evm[folksChainId];
+    if (!evmProvider) throw new Error(`EVM Provider not found for folksChainId: ${folksChainId}`);
+
+    return evmProvider;
+  }
+}