docs: create loan, deposit, borrowing and linking address examples

.changeset/wild-olives-smell.md

@@ -0,0 +1,5 @@
+---
+"@folks-finance/xchain-sdk": patch
+---
+
+Added more examples

README.md

@@ -171,6 +171,8 @@ const createAccount = async (sourceFolksChainId: FolksChainId) => {
 
 Remember that any changes made to `FolksCore` (like changing the network or signer) will affect all subsequent module calls. This design allows for flexible and context-aware interactions with the Folks Finance protocol across different chains and environments.
 
+More examples provided in [`./examples`](./examples) folder.
+
 ### React Usage
 
 When using the SDK with React, there are a few additional considerations to ensure proper initialization and synchronization. Here's how to set up and use the SDK in a React environment:

examples/borrow-stable-rate.ts

@@ -0,0 +1,100 @@
+import { multiply, divide } from "dnum";
+import { createClient, createWalletClient, http, parseUnits } from "viem";
+import { mnemonicToAccount } from "viem/accounts";
+
+import {
+  NetworkType,
+  FolksCore,
+  FolksLoan,
+  FolksPool,
+  FOLKS_CHAIN_ID,
+  getSupportedMessageAdapters,
+  Action,
+  MessageAdapterParamsType,
+  CHAIN_VIEM,
+  TESTNET_FOLKS_TOKEN_ID,
+} from "../src/index.js";
+
+import type { FolksCoreConfig, MessageAdapters, AccountId, LoanId } from "../src/index.js";
+
+async function main() {
+  const chain = FOLKS_CHAIN_ID.BSC_TESTNET;
+  const tokenId = TESTNET_FOLKS_TOKEN_ID.BNB;
+  const jsonRpcAddress = "https://my-rpc.avax-testnet.network/<API_KEY>";
+
+  const folksConfig: FolksCoreConfig = {
+    network: NetworkType.TESTNET,
+    provider: {
+      evm: {
+        [chain]: createClient({
+          chain: CHAIN_VIEM[chain],
+          transport: http(jsonRpcAddress),
+        }),
+      },
+    },
+  };
+
+  FolksCore.init(folksConfig);
+  FolksCore.setNetwork(NetworkType.TESTNET);
+
+  const MNEMONIC = "your mnemonic here";
+  const account = mnemonicToAccount(MNEMONIC);
+
+  const signer = createWalletClient({
+    account,
+    chain: CHAIN_VIEM[chain],
+    transport: http(jsonRpcAddress),
+  });
+
+  const { adapterIds, returnAdapterIds } = getSupportedMessageAdapters({
+    action: Action.Borrow,
+    messageAdapterParamType: MessageAdapterParamsType.ReceiveToken,
+    network: NetworkType.TESTNET,
+    sourceFolksChainId: chain,
+    destFolksChainId: chain,
+    folksTokenId: tokenId,
+  });
+
+  const adapters: MessageAdapters = {
+    adapterId: adapterIds[0],
+    returnAdapterId: returnAdapterIds[0],
+  };
+
+  FolksCore.setFolksSigner({ signer, folksChainId: chain });
+
+  const accountId = "0x7d6...b66" as AccountId; // Your xChainApp account id
+  const loanId = "0x166...c12" as LoanId; // Your loan id
+  const amountToBorrow = parseUnits("0.0005", 18); // 0.0005 BNB (BNB has 18 decimals)
+  const poolInfo = await FolksPool.read.poolInfo(tokenId);
+  const interestRate = poolInfo.stableBorrowData.interestRate[0];
+  const stableRateSlippagePercent = 5; // 5% max deviation from current rate
+  const [maxStableRate] = divide(multiply(interestRate, 100 + stableRateSlippagePercent), 100);
+
+  const prepareBorrowCall = await FolksLoan.prepare.borrow(
+    accountId,
+    loanId,
+    tokenId,
+    amountToBorrow,
+    maxStableRate,
+    chain,
+    adapters,
+  );
+  const createBorrowCallRes = await FolksLoan.write.borrow(
+    accountId,
+    loanId,
+    tokenId,
+    amountToBorrow,
+    maxStableRate,
+    chain,
+    prepareBorrowCall,
+  );
+  console.log(`Transaction ID: ${createBorrowCallRes}`);
+}
+
+main()
+  .then(() => {
+    console.log("done");
+  })
+  .catch((error: unknown) => {
+    console.error(error);
+  });

examples/borrow-variable-rate.ts

@@ -0,0 +1,94 @@
+import { createClient, createWalletClient, http, parseUnits } from "viem";
+import { mnemonicToAccount } from "viem/accounts";
+
+import {
+  NetworkType,
+  FolksCore,
+  FolksLoan,
+  FOLKS_CHAIN_ID,
+  getSupportedMessageAdapters,
+  Action,
+  MessageAdapterParamsType,
+  CHAIN_VIEM,
+  TESTNET_FOLKS_TOKEN_ID,
+} from "../src/index.js";
+
+import type { FolksCoreConfig, MessageAdapters, AccountId, LoanId } from "../src/index.js";
+
+async function main() {
+  const chain = FOLKS_CHAIN_ID.AVALANCHE_FUJI;
+  const tokenId = TESTNET_FOLKS_TOKEN_ID.USDC;
+  const jsonRpcAddress = "https://my-rpc.avax-testnet.network/<API_KEY>";
+
+  const folksConfig: FolksCoreConfig = {
+    network: NetworkType.TESTNET,
+    provider: {
+      evm: {
+        [chain]: createClient({
+          chain: CHAIN_VIEM[chain],
+          transport: http(jsonRpcAddress),
+        }),
+      },
+    },
+  };
+
+  FolksCore.init(folksConfig);
+  FolksCore.setNetwork(NetworkType.TESTNET);
+
+  const MNEMONIC = "your mnemonic here";
+  const account = mnemonicToAccount(MNEMONIC);
+
+  const signer = createWalletClient({
+    account,
+    chain: CHAIN_VIEM[chain],
+    transport: http(jsonRpcAddress),
+  });
+
+  const { adapterIds, returnAdapterIds } = getSupportedMessageAdapters({
+    action: Action.Borrow,
+    messageAdapterParamType: MessageAdapterParamsType.ReceiveToken,
+    network: NetworkType.TESTNET,
+    sourceFolksChainId: chain,
+    destFolksChainId: chain,
+    folksTokenId: tokenId,
+  });
+
+  const adapters: MessageAdapters = {
+    adapterId: adapterIds[0],
+    returnAdapterId: returnAdapterIds[0],
+  };
+
+  FolksCore.setFolksSigner({ signer, folksChainId: chain });
+
+  const accountId = "0x7d6...b66" as AccountId; // Your xChainApp account id
+  const loanId = "0x166...c12" as LoanId; // Your loan id
+  const amountToBorrow = parseUnits("1", 6); // 1 USDC (USDC has 6 decimals)
+
+  const prepareBorrowCall = await FolksLoan.prepare.borrow(
+    accountId,
+    loanId,
+    tokenId,
+    amountToBorrow,
+    BigInt(0),
+    chain,
+    adapters,
+  );
+  const createBorrowCallRes = await FolksLoan.write.borrow(
+    accountId,
+    loanId,
+    tokenId,
+    amountToBorrow,
+    BigInt(0),
+    chain,
+    prepareBorrowCall,
+  );
+  console.log(`Transaction ID: ${createBorrowCallRes}`);
+}
+
+main()
+  .then(() => {
+    console.log("done");
+  })
+  .catch((error: unknown) => {
+    console.error(error);
+  });

examples/create-loan.ts

@@ -0,0 +1,91 @@
+import { createClient, createWalletClient, http } from "viem";
+import { mnemonicToAccount } from "viem/accounts";
+
+import { convertStringToLoanName } from "../src/common/utils/lending.js";
+import {
+  NetworkType,
+  FolksCore,
+  getRandomBytes,
+  FolksLoan,
+  FOLKS_CHAIN_ID,
+  BYTES4_LENGTH,
+  getSupportedMessageAdapters,
+  Action,
+  MessageAdapterParamsType,
+  LoanTypeId,
+  CHAIN_VIEM,
+} from "../src/index.js";
+
+import type { FolksCoreConfig, MessageAdapters, Nonce, AccountId } from "../src/index.js";
+
+async function main() {
+  const chain = FOLKS_CHAIN_ID.AVALANCHE_FUJI;
+  const jsonRpcAddress = "https://my-rpc.avax-testnet.network/<API_KEY>";
+
+  const folksConfig: FolksCoreConfig = {
+    network: NetworkType.TESTNET,
+    provider: {
+      evm: {
+        [chain]: createClient({
+          chain: CHAIN_VIEM[chain],
+          transport: http(jsonRpcAddress),
+        }),
+      },
+    },
+  };
+
+  FolksCore.init(folksConfig);
+  FolksCore.setNetwork(NetworkType.TESTNET);
+
+  const nonce: Nonce = getRandomBytes(BYTES4_LENGTH) as Nonce;
+
+  const MNEMONIC = "your mnemonic here";
+  const account = mnemonicToAccount(MNEMONIC);
+
+  const signer = createWalletClient({
+    account,
+    chain: CHAIN_VIEM[chain],
+    transport: http(jsonRpcAddress),
+  });
+
+  const { adapterIds, returnAdapterIds } = getSupportedMessageAdapters({
+    action: Action.CreateLoan,
+    messageAdapterParamType: MessageAdapterParamsType.Data,
+    network: NetworkType.TESTNET,
+    sourceFolksChainId: chain,
+  });
+
+  const adapters: MessageAdapters = {
+    adapterId: adapterIds[0],
+    returnAdapterId: returnAdapterIds[0],
+  };
+
+  FolksCore.setFolksSigner({ signer, folksChainId: chain });
+
+  const accountId = "0x7d6...b66" as AccountId; //Your xChainApp account id
+  const loanName = convertStringToLoanName("Test Loan");
+
+  const prepareCreateLoanCall = await FolksLoan.prepare.createLoan(
+    accountId,
+    nonce,
+    LoanTypeId.GENERAL, // LoanTypeId.DEPOSIT for deposits
+    loanName,
+    adapters,
+  );
+  const createLoanCallRes = await FolksLoan.write.createLoan(
+    accountId,
+    nonce,
+    LoanTypeId.GENERAL, // LoanTypeId.DEPOSIT for deposits
+    loanName,
+    prepareCreateLoanCall,
+  );
+  console.log(`Transaction ID: ${createLoanCallRes}`);
+}
+
+main()
+  .then(() => {
+    console.log("done");
+  })
+  .catch((error: unknown) => {
+    console.error(error);
+  });

examples/deposit-collateralise.ts

@@ -0,0 +1,91 @@
+import { createClient, createWalletClient, http, parseUnits } from "viem";
+import { mnemonicToAccount } from "viem/accounts";
+
+import {
+  NetworkType,
+  FolksCore,
+  FolksLoan,
+  FOLKS_CHAIN_ID,
+  getSupportedMessageAdapters,
+  Action,
+  MessageAdapterParamsType,
+  LoanTypeId,
+  CHAIN_VIEM,
+  TESTNET_FOLKS_TOKEN_ID,
+} from "../src/index.js";
+
+import type { FolksCoreConfig, MessageAdapters, AccountId, LoanId } from "../src/index.js";
+
+async function main() {
+  const chain = FOLKS_CHAIN_ID.AVALANCHE_FUJI;
+  const tokenId = TESTNET_FOLKS_TOKEN_ID.AVAX;
+  const jsonRpcAddress = "https://my-rpc.avax-testnet.network/<API_KEY>";
+
+  const folksConfig: FolksCoreConfig = {
+    network: NetworkType.TESTNET,
+    provider: {
+      evm: {
+        [chain]: createClient({
+          chain: CHAIN_VIEM[chain],
+          transport: http(jsonRpcAddress),
+        }),
+      },
+    },
+  };
+
+  FolksCore.init(folksConfig);
+  FolksCore.setNetwork(NetworkType.TESTNET);
+
+  const MNEMONIC = "your mnemonic here";
+  const account = mnemonicToAccount(MNEMONIC);
+
+  const signer = createWalletClient({
+    account,
+    chain: CHAIN_VIEM[chain],
+    transport: http(jsonRpcAddress),
+  });
+
+  const { adapterIds, returnAdapterIds } = getSupportedMessageAdapters({
+    action: Action.Deposit,
+    messageAdapterParamType: MessageAdapterParamsType.SendToken,
+    network: NetworkType.TESTNET,
+    sourceFolksChainId: chain,
+    folksTokenId: tokenId,
+  });
+
+  const adapters: MessageAdapters = {
+    adapterId: adapterIds[0],
+    returnAdapterId: returnAdapterIds[0],
+  };
+
+  FolksCore.setFolksSigner({ signer, folksChainId: chain });
+
+  const accountId = "0x7d6...b66" as AccountId; // Your xChainApp account id
+  const loanId = "0x166...c12" as LoanId; // Your loan id
+  const amountToDeposit = parseUnits("0.1", 18); // 0.1 AVAX (AVAX has 18 decimals)
+
+  const prepareDepositCall = await FolksLoan.prepare.deposit(
+    accountId,
+    loanId,
+    LoanTypeId.GENERAL, // LoanTypeId.DEPOSIT for deposits
+    tokenId,
+    amountToDeposit,
+    adapters,
+  );
+  const createDepositCallRes = await FolksLoan.write.deposit(
+    accountId,
+    loanId,
+    amountToDeposit,
+    false,
+    prepareDepositCall,
+  );
+  console.log(`Transaction ID: ${createDepositCallRes}`);
+}
+
+main()
+  .then(() => {
+    console.log("done");
+  })
+  .catch((error: unknown) => {
+    console.error(error);
+  });