@folks-finance/xchain-sdk 0.0.1

package/src/chains/evm/spoke/modules/index.ts

@@ -0,0 +1,3 @@
+export * as FolksEvmAccount from "./folks-evm-account.js";
+export * as FolksEvmGmp from "./folks-evm-gmp.js";
+export * as FolksEvmLoan from "./folks-evm-loan.js";

package/src/chains/evm/spoke/types/pool.ts

@@ -0,0 +1,7 @@
+export type TokenRateLimit = {
+  periodLength: bigint;
+  periodOffset: bigint;
+  periodLimit: bigint;
+  currentCapacity: bigint;
+  nextPeriodReset: bigint;
+};

package/src/chains/evm/spoke/utils/contract.ts

@@ -0,0 +1,74 @@
+import { getContract } from "viem";
+
+import { ChainType } from "../../../../common/types/chain.js";
+import { convertFromGenericAddress } from "../../../../common/utils/address.js";
+import { BridgeRouterSpokeAbi } from "../constants/abi/bridge-router-spoke-abi.js";
+import { SpokeCommonAbi } from "../constants/abi/spoke-common-abi.js";
+import { SpokeTokenAbi } from "../constants/abi/spoke-token-abi.js";
+
+import type { GenericAddress } from "../../../../common/types/address.js";
+import type { GetReadContractReturnType } from "../../common/types/contract.js";
+import type { GetContractReturnType, Client, WalletClient } from "viem";
+
+export function getSpokeCommonContract(
+  provider: Client,
+  address: GenericAddress,
+): GetReadContractReturnType<typeof SpokeCommonAbi>;
+export function getSpokeCommonContract(
+  provider: Client,
+  address: GenericAddress,
+  signer: WalletClient,
+): GetContractReturnType<typeof SpokeCommonAbi, Client>;
+export function getSpokeCommonContract(
+  provider: Client,
+  address: GenericAddress,
+  signer?: WalletClient,
+): GetReadContractReturnType<typeof SpokeCommonAbi> | GetContractReturnType<typeof SpokeCommonAbi, Client> {
+  return getContract({
+    abi: SpokeCommonAbi,
+    address: convertFromGenericAddress<ChainType.EVM>(address, ChainType.EVM),
+    client: { wallet: signer, public: provider },
+  });
+}
+
+export function getBridgeRouterSpokeContract(
+  provider: Client,
+  address: GenericAddress,
+): GetReadContractReturnType<typeof BridgeRouterSpokeAbi>;
+export function getBridgeRouterSpokeContract(
+  provider: Client,
+  address: GenericAddress,
+  signer: WalletClient,
+): GetContractReturnType<typeof BridgeRouterSpokeAbi, Client>;
+export function getBridgeRouterSpokeContract(
+  provider: Client,
+  address: GenericAddress,
+  signer?: WalletClient,
+): GetReadContractReturnType<typeof BridgeRouterSpokeAbi> {
+  return getContract({
+    abi: BridgeRouterSpokeAbi,
+    address: convertFromGenericAddress<ChainType.EVM>(address, ChainType.EVM),
+    client: { wallet: signer, public: provider },
+  });
+}
+
+export function getSpokeTokenContract(
+  provider: Client,
+  address: GenericAddress,
+): GetReadContractReturnType<typeof SpokeTokenAbi>;
+export function getSpokeTokenContract(
+  provider: Client,
+  address: GenericAddress,
+  signer: WalletClient,
+): GetContractReturnType<typeof SpokeTokenAbi, Client>;
+export function getSpokeTokenContract(
+  provider: Client,
+  address: GenericAddress,
+  signer?: WalletClient,
+): GetReadContractReturnType<typeof SpokeTokenAbi> | GetContractReturnType<typeof SpokeTokenAbi, Client> {
+  return getContract({
+    abi: SpokeTokenAbi,
+    address: convertFromGenericAddress<ChainType.EVM>(address, ChainType.EVM),
+    client: { wallet: signer, public: provider },
+  });
+}

package/src/common/constants/adapter.ts

@@ -0,0 +1,5 @@
+import { AdapterType } from "../types/message.js";
+
+export const TOKEN_ADAPTERS = [AdapterType.WORMHOLE_CCTP, AdapterType.CCIP_TOKEN];
+export const DATA_ADAPTERS = [AdapterType.WORMHOLE_DATA, AdapterType.CCIP_DATA];
+export const HUB_ADAPTERS = [AdapterType.HUB];

package/src/common/constants/bytes.ts

@@ -0,0 +1,6 @@
+export const UINT8_LENGTH = 1;
+export const UINT16_LENGTH = 2;
+export const UINT256_LENGTH = 32;
+export const BYTES32_LENGTH = 32;
+
+export const EVM_ADDRESS_BYTES_LENGTH = 20;

package/src/common/constants/chain.ts

@@ -0,0 +1,227 @@
+import { avalancheFuji, baseSepolia, sepolia } from "viem/chains";
+
+import { MAINNET_EVM_FOLKS_CHAIN_ID, TESTNET_EVM_FOLKS_CHAIN_ID } from "../../chains/evm/common/constants/chain.js";
+import { NetworkType, ChainType } from "../types/chain.js";
+import { AdapterType } from "../types/message.js";
+import { FolksTokenId, TokenType } from "../types/token.js";
+import { convertToGenericAddress } from "../utils/address.js";
+
+import { TESTNET_POOLS } from "./pool.js";
+
+import type { EvmAddress } from "../types/address.js";
+import type { FolksChainId, FolksChain, SpokeChain, FolksChainName } from "../types/chain.js";
+
+export const MAINNET_FOLKS_CHAIN_ID = {
+  ...MAINNET_EVM_FOLKS_CHAIN_ID,
+} as const;
+
+export const TESTNET_FOLKS_CHAIN_ID = {
+  ...TESTNET_EVM_FOLKS_CHAIN_ID,
+} as const;
+
+export const FOLKS_CHAIN_ID = {
+  ...MAINNET_FOLKS_CHAIN_ID,
+  ...TESTNET_FOLKS_CHAIN_ID,
+} as const satisfies Record<FolksChainName, number>;
+
+export const FOLKS_CHAIN: Record<NetworkType, Partial<Record<FolksChainId, FolksChain>>> = {
+  [NetworkType.MAINNET]: {},
+  [NetworkType.TESTNET]: {
+    [FOLKS_CHAIN_ID.AVALANCHE_FUJI]: {
+      chainType: ChainType.EVM,
+      folksChainId: FOLKS_CHAIN_ID.AVALANCHE_FUJI,
+      chainName: avalancheFuji.name,
+      chainId: avalancheFuji.id,
+      network: NetworkType.TESTNET,
+    },
+    [FOLKS_CHAIN_ID.ETHEREUM_SEPOLIA]: {
+      chainType: ChainType.EVM,
+      folksChainId: FOLKS_CHAIN_ID.ETHEREUM_SEPOLIA,
+      chainName: sepolia.name,
+      chainId: sepolia.id,
+      network: NetworkType.TESTNET,
+    },
+    [FOLKS_CHAIN_ID.BASE_SEPOLIA]: {
+      chainType: ChainType.EVM,
+      folksChainId: FOLKS_CHAIN_ID.BASE_SEPOLIA,
+      chainName: baseSepolia.name,
+      chainId: baseSepolia.id,
+      network: NetworkType.TESTNET,
+    },
+  },
+} as const;
+
+export const SPOKE_CHAIN: Record<NetworkType, Partial<Record<FolksChainId, SpokeChain>>> = {
+  [NetworkType.MAINNET]: {},
+  [NetworkType.TESTNET]: {
+    [FOLKS_CHAIN_ID.AVALANCHE_FUJI]: {
+      folksChainId: FOLKS_CHAIN_ID.AVALANCHE_FUJI,
+      spokeCommonAddress: convertToGenericAddress(
+        "0x6628cE08b54e9C8358bE94f716D93AdDcca45b00" as EvmAddress,
+        ChainType.EVM,
+      ),
+      bridgeRouterAddress: convertToGenericAddress(
+        "0x0f91d914E058d0588Cc1bf35FA3736A627C3Ba81" as EvmAddress,
+        ChainType.EVM,
+      ),
+      adapters: {
+        [AdapterType.HUB]: convertToGenericAddress(
+          "0xf472ab58969709De9FfEFaeFFd24F9e90cf8DbF9" as EvmAddress,
+          ChainType.EVM,
+        ),
+      },
+      tokens: {
+        [FolksTokenId.USDC]: {
+          token: {
+            type: TokenType.CIRCLE,
+            address: convertToGenericAddress("0x5425890298aed601595a70ab815c96711a31bc65" as EvmAddress, ChainType.EVM),
+            decimals: 6,
+          },
+          folksTokenId: FolksTokenId.USDC,
+          poolId: TESTNET_POOLS[FolksTokenId.USDC],
+          spokeAddress: convertToGenericAddress(
+            "0x89df7db4af48Ec7A84DE09F755ade9AF1940420b" as EvmAddress,
+            ChainType.EVM,
+          ),
+        },
+        [FolksTokenId.AVAX]: {
+          token: {
+            type: TokenType.NATIVE,
+            decimals: 18,
+          },
+          folksTokenId: FolksTokenId.AVAX,
+          poolId: TESTNET_POOLS[FolksTokenId.AVAX],
+          spokeAddress: convertToGenericAddress(
+            "0xBFf8b4e5f92eDD0A5f72b4b0E23cCa2Cc476ce2a" as EvmAddress,
+            ChainType.EVM,
+          ),
+        },
+      },
+    },
+    [FOLKS_CHAIN_ID.ETHEREUM_SEPOLIA]: {
+      folksChainId: FOLKS_CHAIN_ID.ETHEREUM_SEPOLIA,
+      spokeCommonAddress: convertToGenericAddress(
+        "0x16Eecb8CeB2CE4Ec542634d7525191dfce587C85" as EvmAddress,
+        ChainType.EVM,
+      ),
+      bridgeRouterAddress: convertToGenericAddress(
+        "0xBeF7aB7C5e6CeFF384cde460dd20C862047CDFa5" as EvmAddress,
+        ChainType.EVM,
+      ),
+      adapters: {
+        [AdapterType.WORMHOLE_DATA]: convertToGenericAddress(
+          "0xC0CFfA934598E655DC8D25Cd1774F249FFCF5e59" as EvmAddress,
+          ChainType.EVM,
+        ),
+        [AdapterType.WORMHOLE_CCTP]: convertToGenericAddress(
+          "0x7cdB014Bc73C74Da5b3830eDE6a4494ec52C3738" as EvmAddress,
+          ChainType.EVM,
+        ),
+        [AdapterType.CCIP_DATA]: convertToGenericAddress(
+          "0xa51cA34831CEB2F8BafE4ADEf032286E067EF2ad" as EvmAddress,
+          ChainType.EVM,
+        ),
+        [AdapterType.CCIP_TOKEN]: convertToGenericAddress(
+          "0x0100F7f027EC3B4B4Fd8bB739efd8BDDBa3bF847" as EvmAddress,
+          ChainType.EVM,
+        ),
+      },
+      tokens: {
+        [FolksTokenId.USDC]: {
+          token: {
+            type: TokenType.CIRCLE,
+            address: convertToGenericAddress("0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238" as EvmAddress, ChainType.EVM),
+            decimals: 6,
+          },
+          folksTokenId: FolksTokenId.USDC,
+          poolId: TESTNET_POOLS[FolksTokenId.USDC],
+          spokeAddress: convertToGenericAddress(
+            "0x40C77F8cc70DF8F6D7A91ebb5291d38d42540455" as EvmAddress,
+            ChainType.EVM,
+          ),
+        },
+        [FolksTokenId.ETH_eth_sep]: {
+          token: {
+            type: TokenType.NATIVE,
+            decimals: 18,
+          },
+          folksTokenId: FolksTokenId.ETH_eth_sep,
+          poolId: TESTNET_POOLS[FolksTokenId.ETH_eth_sep],
+          spokeAddress: convertToGenericAddress(
+            "0x9ecfD854F4F8BD2275930Cc51d45d7817EF6CeE3" as EvmAddress,
+            ChainType.EVM,
+          ),
+        },
+        [FolksTokenId.LINK_eth_sep]: {
+          token: {
+            type: TokenType.ERC20,
+            address: convertToGenericAddress("0x779877A7B0D9E8603169DdbD7836e478b4624789" as EvmAddress, ChainType.EVM),
+            decimals: 18,
+          },
+          folksTokenId: FolksTokenId.LINK_eth_sep,
+          poolId: TESTNET_POOLS[FolksTokenId.LINK_eth_sep],
+          spokeAddress: convertToGenericAddress(
+            "0x8Aac7fA5B2d0c7Ca4f1610bB43CF0d62A670Fa14" as EvmAddress,
+            ChainType.EVM,
+          ),
+        },
+      },
+    },
+    [FOLKS_CHAIN_ID.BASE_SEPOLIA]: {
+      folksChainId: FOLKS_CHAIN_ID.BASE_SEPOLIA,
+      spokeCommonAddress: convertToGenericAddress(
+        "0x993C9a918B145B90E69A8D22B7e3b6d3413e3755" as EvmAddress,
+        ChainType.EVM,
+      ),
+      bridgeRouterAddress: convertToGenericAddress(
+        "0x92051Ad708C4e5FCcC7322c111F63440D638312e" as EvmAddress,
+        ChainType.EVM,
+      ),
+      adapters: {
+        [AdapterType.WORMHOLE_DATA]: convertToGenericAddress(
+          "0x56d9a6e25E9e31080A3Ab1bd4a6f7bd0B4C884Da" as EvmAddress,
+          ChainType.EVM,
+        ),
+        [AdapterType.WORMHOLE_CCTP]: convertToGenericAddress(
+          "0x8c8E4Eb83138D2625a14F0517E0106D26F9c23f3" as EvmAddress,
+          ChainType.EVM,
+        ),
+        [AdapterType.CCIP_DATA]: convertToGenericAddress(
+          "0x08447025BB3D7249cb6566E579b1d309679c7720" as EvmAddress,
+          ChainType.EVM,
+        ),
+        [AdapterType.CCIP_TOKEN]: convertToGenericAddress(
+          "0x22644D46e5aE39Fa6b9d9706AaA1d398E5EB8aBc" as EvmAddress,
+          ChainType.EVM,
+        ),
+      },
+      tokens: {
+        [FolksTokenId.USDC]: {
+          token: {
+            type: TokenType.CIRCLE,
+            address: convertToGenericAddress("0x036CbD53842c5426634e7929541eC2318f3dCF7e" as EvmAddress, ChainType.EVM),
+            decimals: 6,
+          },
+          folksTokenId: FolksTokenId.USDC,
+          poolId: TESTNET_POOLS[FolksTokenId.USDC],
+          spokeAddress: convertToGenericAddress(
+            "0x7cdB014Bc73C74Da5b3830eDE6a4494ec52C3738" as EvmAddress,
+            ChainType.EVM,
+          ),
+        },
+        [FolksTokenId.ETH_base_sep]: {
+          token: {
+            type: TokenType.NATIVE,
+            decimals: 18,
+          },
+          folksTokenId: FolksTokenId.ETH_base_sep,
+          poolId: TESTNET_POOLS[FolksTokenId.ETH_base_sep],
+          spokeAddress: convertToGenericAddress(
+            "0xa51cA34831CEB2F8BafE4ADEf032286E067EF2ad" as EvmAddress,
+            ChainType.EVM,
+          ),
+        },
+      },
+    },
+  },
+};

package/src/common/constants/gmp.ts

@@ -0,0 +1,38 @@
+import { ChainType } from "../types/chain.js";
+import { convertToGenericAddress } from "../utils/address.js";
+
+import { FOLKS_CHAIN_ID } from "./chain.js";
+
+import type { EvmAddress } from "../types/address.js";
+import type { FolksChainId } from "../types/chain.js";
+import type { CCIPData, WormholeData } from "../types/gmp.js";
+
+export const WORMHOLE_DATA: Partial<Record<FolksChainId, WormholeData>> = {
+  [FOLKS_CHAIN_ID.AVALANCHE_FUJI]: {
+    wormholeChainId: 6,
+    wormholeRelayer: convertToGenericAddress("0xA3cF45939bD6260bcFe3D66bc73d60f19e49a8BB" as EvmAddress, ChainType.EVM),
+  },
+  [FOLKS_CHAIN_ID.ETHEREUM_SEPOLIA]: {
+    wormholeChainId: 10002,
+    wormholeRelayer: convertToGenericAddress("0x7B1bD7a6b4E61c2a123AC6BC2cbfC614437D0470" as EvmAddress, ChainType.EVM),
+  },
+  [FOLKS_CHAIN_ID.BASE_SEPOLIA]: {
+    wormholeChainId: 10004,
+    wormholeRelayer: convertToGenericAddress("0x93BAD53DDfB6132b0aC8E37f6029163E63372cEE" as EvmAddress, ChainType.EVM),
+  },
+};
+
+export const CCIP_DATA: Partial<Record<FolksChainId, CCIPData>> = {
+  [FOLKS_CHAIN_ID.AVALANCHE_FUJI]: {
+    ccipChainId: BigInt("14767482510784806043"),
+    ccipRouter: convertToGenericAddress("0xF694E193200268f9a4868e4Aa017A0118C9a8177" as EvmAddress, ChainType.EVM),
+  },
+  [FOLKS_CHAIN_ID.ETHEREUM_SEPOLIA]: {
+    ccipChainId: BigInt("16015286601757825753"),
+    ccipRouter: convertToGenericAddress("0x0BF3dE8c5D3e8A2B34D2BEeB17ABfCeBaf363A59" as EvmAddress, ChainType.EVM),
+  },
+  [FOLKS_CHAIN_ID.BASE_SEPOLIA]: {
+    ccipChainId: BigInt("10344971235874465080"),
+    ccipRouter: convertToGenericAddress("0xD3b06cEbF099CE7DA4AcCf578aaebFDBd6e88a93" as EvmAddress, ChainType.EVM),
+  },
+};

package/src/common/constants/lending.ts

@@ -0,0 +1,3 @@
+import { getAccountIdBytes } from "../utils/bytes.js";
+
+export const NULL_ACCOUNT_ID = getAccountIdBytes("");

package/src/common/constants/message.ts

@@ -0,0 +1,4 @@
+export const FINALITY = {
+  IMMEDIATE: BigInt(0),
+  FINALISED: BigInt(1),
+} as const;

package/src/common/constants/pool.ts

@@ -0,0 +1,11 @@
+import { FolksTokenId } from "../types/token.js";
+
+export const MAINNET_POOLS = {} as const satisfies Partial<Record<FolksTokenId, number>>;
+
+export const TESTNET_POOLS = {
+  [FolksTokenId.USDC]: 128,
+  [FolksTokenId.AVAX]: 129,
+  [FolksTokenId.ETH_eth_sep]: 130,
+  [FolksTokenId.ETH_base_sep]: 131,
+  [FolksTokenId.LINK_eth_sep]: 132,
+} as const satisfies Partial<Record<FolksTokenId, number>>;

package/src/common/constants/token.ts

@@ -0,0 +1,3 @@
+import { FolksTokenId } from "../types/token.js";
+
+export const CIRCLE_FOLKS_TOKEN_ID = [FolksTokenId.USDC];

package/src/common/types/adapter.ts

@@ -0,0 +1,38 @@
+import type { FolksChainId, NetworkType } from "./chain.js";
+import type { DataAction, ReceiveTokenAction, SendTokenAction } from "./message.js";
+import type { FolksTokenId } from "./token.js";
+
+export enum MessageAdapterParamsType {
+  SendToken,
+  ReceiveToken,
+  Data,
+}
+
+export type SendTokenMessageAdapterParams = {
+  messageAdapterParamType: MessageAdapterParamsType.SendToken;
+  action: SendTokenAction;
+  network: NetworkType;
+  sourceFolksChainId: FolksChainId;
+  folksTokenId: FolksTokenId;
+};
+
+export type ReceiveTokenMessageAdapterParams = {
+  messageAdapterParamType: MessageAdapterParamsType.ReceiveToken;
+  action: ReceiveTokenAction;
+  network: NetworkType;
+  sourceFolksChainId: FolksChainId;
+  destFolksChainId: FolksChainId;
+  folksTokenId: FolksTokenId;
+};
+
+export type DataMessageAdapterParams = {
+  messageAdapterParamType: MessageAdapterParamsType.Data;
+  action: DataAction;
+  network: NetworkType;
+  sourceFolksChainId: FolksChainId;
+};
+
+export type MessageAdapterParams =
+  | SendTokenMessageAdapterParams
+  | ReceiveTokenMessageAdapterParams
+  | DataMessageAdapterParams;

package/src/common/types/address.ts

@@ -0,0 +1,11 @@
+import type { Branded } from "./brand.js";
+import type { ChainType } from "./chain.js";
+
+export type GenericAddress = Branded<`0x${string}`, "GenericAddress">;
+export type EvmAddress = Branded<`0x${string}`, "EvmAddress">;
+
+type AddressTypeMap = {
+  [ChainType.EVM]: EvmAddress;
+};
+
+export type AddressType<T extends ChainType> = AddressTypeMap[T];

package/src/common/types/brand.ts

@@ -0,0 +1,3 @@
+declare const __brand: unique symbol;
+type Brand<B> = { [__brand]: B };
+export type Branded<T, B> = T & Brand<B>;

package/src/common/types/chain.ts

@@ -0,0 +1,35 @@
+import type { GenericAddress } from "./address.js";
+import type { AdapterType } from "./message.js";
+import type { FolksTokenId, SpokeTokenData } from "./token.js";
+import type { EvmChainName } from "../../chains/evm/common/types/chain.js";
+import type { FOLKS_CHAIN_ID } from "../constants/chain.js";
+
+export enum ChainType {
+  EVM = "EVM",
+}
+
+export enum NetworkType {
+  MAINNET = "MAINNET",
+  TESTNET = "TESTNET",
+}
+
+export type FolksChainName = EvmChainName;
+export type FolksChainId = (typeof FOLKS_CHAIN_ID)[keyof typeof FOLKS_CHAIN_ID];
+
+export type IFolksChain = {
+  folksChainId: FolksChainId;
+};
+
+export type FolksChain = {
+  chainName: string;
+  chainType: ChainType;
+  chainId: number | string | undefined;
+  network: NetworkType;
+} & IFolksChain;
+
+export type SpokeChain = {
+  spokeCommonAddress: GenericAddress;
+  bridgeRouterAddress: GenericAddress;
+  adapters: Partial<Record<AdapterType, GenericAddress>>;
+  tokens: Partial<Record<FolksTokenId, SpokeTokenData>>;
+} & IFolksChain;

package/src/common/types/core.ts

@@ -0,0 +1,31 @@
+import type { ChainType, NetworkType, FolksChainId } from "./chain.js";
+import type { Client as EVMProvider, WalletClient as EVMSigner } from "viem";
+
+type FolksProviderTypeMap = {
+  [ChainType.EVM]: EVMProvider;
+};
+
+type FolksSignerTypeMap = {
+  [ChainType.EVM]: EVMSigner;
+};
+
+export type FolksProviderType<T extends ChainType> = FolksProviderTypeMap[T];
+export type FolksSignerType<T extends ChainType> = FolksSignerTypeMap[T];
+
+export type FolksProvider = EVMProvider | null;
+export type FolksSigner = { signer: EVMSigner; folksChainId: FolksChainId };
+
+export type FolksCoreProvider = {
+  evm: Partial<Record<FolksChainId, EVMProvider>>;
+};
+export type FolksCoreConfig = {
+  network: NetworkType;
+  provider: FolksCoreProvider;
+};
+
+export type FolksEvmSigner = {
+  signer: EVMSigner;
+  chainType: ChainType.EVM;
+};
+
+export type FolksChainSigner = FolksEvmSigner;

package/src/common/types/gmp.ts

@@ -0,0 +1,22 @@
+import type { GenericAddress } from "./address.js";
+import type { Branded } from "./brand.js";
+import type { AccountId } from "./lending.js";
+
+export enum MessageDirection {
+  SpokeToHub,
+  HubToSpoke,
+}
+
+export type WormholeData = {
+  wormholeChainId: number;
+  wormholeRelayer: GenericAddress;
+};
+
+export type CCIPData = {
+  ccipChainId: bigint;
+  ccipRouter: GenericAddress;
+};
+
+export type MessageId = Branded<`0x${string}`, "MessageId">;
+
+export type ReverseMessageExtraAgrs = "0x" | AccountId;

package/src/common/types/lending.ts

@@ -0,0 +1,5 @@
+import type { Branded } from "./brand.js";
+
+export type AccountId = Branded<`0x${string}`, "AccountId">;
+export type LoanId = Branded<`0x${string}`, "LoanId">;
+export type LoanName = Branded<`0x${string}`, "LoanName">;