@everstake/wallet-sdk-hysp-solana 1.0.0

package/dist/index.mjs

@@ -0,0 +1,372 @@
+// src/hysp.ts
+import {
+  createSolanaRpc,
+  createNoopSigner,
+  address as address2,
+  pipe,
+  createTransactionMessage,
+  setTransactionMessageFeePayer,
+  setTransactionMessageLifetimeUsingBlockhash,
+  appendTransactionMessageInstruction,
+  prependTransactionMessageInstruction
+} from "@solana/kit";
+import {
+  getSetComputeUnitLimitInstruction,
+  getSetComputeUnitPriceInstruction
+} from "@solana-program/compute-budget";
+import { KaminoVault } from "@kamino-finance/klend-sdk";
+import { Decimal } from "decimal.js";
+
+// ../utils/constants/errors.ts
+var COMMON_ERROR_MESSAGES = {
+  UNKNOWN_ERROR: "An unknown error occurred",
+  TOKEN_ERROR: "Please create or use correct token"
+};
+
+// ../utils/index.ts
+var WalletSDKError = class extends Error {
+  constructor(message, code, originalError) {
+    super(message);
+    this.code = code;
+    this.originalError = originalError;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var Blockchain = class {
+  /**
+   * Handles errors that occur within the Ethereum class.
+   *
+   * @param {keyof typeof ERROR_MESSAGES} code - The error code associated with the error.
+   * @param {Error | WalletSDKError | unknown} originalError - The original error that was thrown.
+   *
+   * If the original error is an instance of WalletSDKError, it is thrown as is.
+   * If the original error is an instance of the built-in Error class, a new WalletSDKError is thrown with the original error as the cause.
+   * If the original error is not an instance of WalletSDKError or Error, a new WalletSDKError is thrown with a generic message and code.
+   */
+  handleError(code, originalError) {
+    const message = this.ERROR_MESSAGES[code];
+    if (originalError instanceof WalletSDKError || !message || !code) {
+      throw originalError;
+    }
+    if (originalError instanceof Error) {
+      const newMessage = Object.entries(this.ORIGINAL_ERROR_MESSAGES).find(
+        ([originalMessage]) => originalError.message.includes(originalMessage)
+      )?.[1];
+      const errorMessage = newMessage || this.ERROR_MESSAGES[code] || COMMON_ERROR_MESSAGES["UNKNOWN_ERROR"];
+      throw new WalletSDKError(errorMessage, String(code), originalError);
+    }
+    throw new WalletSDKError(
+      COMMON_ERROR_MESSAGES["UNKNOWN_ERROR"],
+      "UNKNOWN_ERROR"
+    );
+  }
+  /**
+   * Throws a WalletSDKError with a specified error code and message.
+   *
+   * @param {keyof typeof ERROR_MESSAGES} code - The error code associated with the error.
+   * @param {...string[]} values - The values to be inserted into the error message.
+   *
+   * The method retrieves the error message template associated with the provided code from the ERROR_MESSAGES object.
+   * It then replaces placeholders in the message template with provided values and throws a WalletSDKError with the final message and the provided code.
+   */
+  throwError(code, ...values) {
+    let message = this.ERROR_MESSAGES[code];
+    values.forEach((value, index) => {
+      message = message?.replace(`{${index}}`, value);
+    });
+    if (!message) {
+      throw new WalletSDKError(
+        COMMON_ERROR_MESSAGES["UNKNOWN_ERROR"],
+        "UNKNOWN_ERROR"
+      );
+    }
+    throw new WalletSDKError(message, String(code));
+  }
+  /**
+   * Check if the URL is valid
+   *
+   * @param {string} url - URL
+   * @returns a bool type result.
+   *
+   */
+  isValidURL(url) {
+    let urlClass;
+    try {
+      urlClass = new URL(url);
+    } catch (_) {
+      return false;
+    }
+    return urlClass.protocol === "http:" || urlClass.protocol === "https:";
+  }
+};
+
+// src/constants/errors.ts
+var ERROR_MESSAGES = {
+  INITIALIZATION_ERROR: "An error occurred while initializingSDK",
+  DEPOSIT_ERROR: "An error occurred while creating vault deposit transaction",
+  WITHDRAW_ERROR: "An error occurred while creating vault withdraw transaction",
+  GET_SHARES_ERROR: "An error occurred while fetching vault balance",
+  GET_BALANCE_ERROR: "An error occurred while fetching user token balance",
+  VAULT_LOAD_ERROR: "An error occurred while loading vault info",
+  VAULT_NOT_FOUND_ERROR: "Vault not found for token: {0}"
+};
+
+// src/constants/index.ts
+import { address } from "@solana/kit";
+var VAULTS = {
+  USDC: address("HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E")
+};
+
+// src/hysp.ts
+var HyspSolana = class extends Blockchain {
+  ERROR_MESSAGES = ERROR_MESSAGES;
+  ORIGINAL_ERROR_MESSAGES = ERROR_MESSAGES;
+  connection;
+  vault;
+  /**
+   * Creates a new instance of the KaminoSDK.
+   *
+   * @param rpcUrl - Optional custom RPC URL. If not provided, uses the default Solana mainnet RPC.
+   *
+   * @throws Throws an error if the token symbol is not supported.
+   * @throws Throws an error if there's an issue during SDK initialization.
+   */
+  constructor(tokenSymbol, rpcUrl) {
+    super();
+    const vaultAddress = this.getVaultAddress(tokenSymbol);
+    try {
+      const connectionUrl = rpcUrl || "https://api.mainnet-beta.solana.com";
+      this.connection = createSolanaRpc(connectionUrl);
+      this.vault = new KaminoVault(this.connection, vaultAddress);
+    } catch (error) {
+      throw this.handleError("INITIALIZATION_ERROR", error);
+    }
+  }
+  getVaultAddress(tokenSymbol) {
+    const vaultAddress = VAULTS[tokenSymbol];
+    if (!vaultAddress) {
+      throw this.throwError("VAULT_NOT_FOUND_ERROR", tokenSymbol);
+    }
+    return vaultAddress;
+  }
+  convertToDecimal(amount) {
+    return new Decimal(amount.toString());
+  }
+  /**
+   * Fetches the vault holdings data.
+   *
+   * @throws Throws an error if there's an issue loading vault holdings.
+   *
+   * @returns Returns a promise that resolves with the vault holdings.
+   */
+  async getVaultHoldings() {
+    try {
+      const holdings = await this.vault.getVaultHoldings();
+      return { result: holdings };
+    } catch (error) {
+      throw this.handleError("VAULT_LOAD_ERROR", error);
+    }
+  }
+  /**
+   * Fetches the vault APY data.
+   *
+   * @throws Throws an error if there's an issue loading vault APYs.
+   *
+   * @returns Returns a promise that resolves with the vault actual APY information.
+   */
+  async getVaultAPYs() {
+    try {
+      const apys = await this.vault.getAPYs();
+      return { result: apys.actualAPY };
+    } catch (error) {
+      throw this.handleError("VAULT_LOAD_ERROR", error);
+    }
+  }
+  /**
+   * Fetches the current vault exchange rate (tokens per share).
+   *
+   * @throws Throws an error if there's an issue loading exchange rate.
+   *
+   * @returns Returns a promise that resolves with the exchange rate as Decimal.
+   */
+  async getExchangeRate() {
+    try {
+      const rate = await this.vault.getExchangeRate();
+      return { result: rate };
+    } catch (error) {
+      throw this.handleError("VAULT_LOAD_ERROR", error);
+    }
+  }
+  /**
+   * Fetches a user's raw share balance in the current vault.
+   *
+   * @param userAddress - The public key of the user account.
+   * @throws Throws an error if there's an issue fetching user shares.
+   * @returns Returns a promise that resolves with the user's shares amount.
+   */
+  async getUserShares(userAddress) {
+    try {
+      const shares = await this.vault.getUserShares(userAddress);
+      return {
+        result: shares.totalShares
+      };
+    } catch (error) {
+      throw this.handleError("GET_SHARES_ERROR", error);
+    }
+  }
+  /**
+   * Fetches a user's token balance in the current vault: shares * exchange rate.
+   *
+   * @param userAddress - The public key of the user account.
+   * @throws Throws an error if there's an issue fetching user balance.
+   * @returns Returns a promise that resolves with the user's token balance amount.
+   */
+  async getUserBalance(userAddress) {
+    try {
+      const balance = await this.vault.getUserShares(userAddress);
+      const exchangeRate = await this.vault.getExchangeRate();
+      const tokenBalance = balance.totalShares.mul(exchangeRate);
+      return {
+        result: tokenBalance
+      };
+    } catch (error) {
+      throw this.handleError("GET_BALANCE_ERROR", error);
+    }
+  }
+  /**
+   * Creates a deposit transaction to the vault.
+   *
+   * @param userAddress - The public key of the user account.
+   * @param amount - The amount to deposit.
+   * @param params - Optional transaction parameters.
+   *
+   * @throws Throws an error if there's an issue creating the deposit transaction.
+   *
+   * @returns Returns a promise that resolves with the deposit transaction response.
+   */
+  async deposit(userAddress, amount, params) {
+    try {
+      const signer = createNoopSigner(userAddress);
+      let decimalAmount;
+      if (amount instanceof Decimal) {
+        decimalAmount = amount;
+      } else {
+        decimalAmount = this.convertToDecimal(amount);
+      }
+      const depositIxs = await this.vault.depositIxs(signer, decimalAmount);
+      const mergedDepositIxs = [];
+      depositIxs.depositIxs.forEach((instruction) => {
+        mergedDepositIxs.push(instruction);
+      });
+      depositIxs.stakeInFarmIfNeededIxs.forEach((instruction) => {
+        mergedDepositIxs.push(instruction);
+      });
+      const transactionMessage = await this.buildTx(
+        userAddress.toString(),
+        mergedDepositIxs,
+        params
+      );
+      return {
+        result: transactionMessage
+      };
+    } catch (error) {
+      throw this.handleError("DEPOSIT_ERROR", error);
+    }
+  }
+  /**
+   * Creates a withdraw transaction from the vault.
+   *
+   * @param userAddress - The public key of the user account.
+   * @param sharesAmount - The amount of shares to withdraw.
+   * @param params - Optional transaction parameters.
+   *
+   * @throws Throws an error if there's issue creating the withdraw transaction.
+   *
+   * @returns Returns a promise that resolves with the withdraw transaction response.
+   */
+  async withdraw(userAddress, sharesAmount, params) {
+    try {
+      const signer = createNoopSigner(userAddress);
+      let sharesDecimal;
+      if (sharesAmount instanceof Decimal) {
+        sharesDecimal = sharesAmount;
+      } else {
+        sharesDecimal = this.convertToDecimal(sharesAmount);
+      }
+      const withdrawIxs = await this.vault.withdrawIxs(signer, sharesDecimal);
+      const mergedWithdrawIxs = [];
+      withdrawIxs.unstakeFromFarmIfNeededIxs.forEach((instruction) => {
+        mergedWithdrawIxs.push(instruction);
+      });
+      withdrawIxs.withdrawIxs.forEach((instruction) => {
+        mergedWithdrawIxs.push(instruction);
+      });
+      withdrawIxs.postWithdrawIxs.forEach((instruction) => {
+        mergedWithdrawIxs.push(instruction);
+      });
+      const transactionMessage = await this.buildTx(
+        userAddress.toString(),
+        mergedWithdrawIxs,
+        params
+      );
+      return {
+        result: transactionMessage
+      };
+    } catch (error) {
+      throw this.handleError("WITHDRAW_ERROR", error);
+    }
+  }
+  async buildTx(sender, instructions, params) {
+    let transactionMessage = pipe(
+      createTransactionMessage({ version: 0 }),
+      (tx) => setTransactionMessageFeePayer(address2(sender), tx)
+    );
+    if (params?.computeUnitLimit !== void 0 && params?.computeUnitLimit > 0) {
+      const unitLimitInstruction = getSetComputeUnitLimitInstruction({
+        /** Transaction compute unit limit used for prioritization fees. */
+        units: params?.computeUnitLimit
+      });
+      transactionMessage = prependTransactionMessageInstruction(
+        unitLimitInstruction,
+        transactionMessage
+      );
+    }
+    if (params?.\u0441omputeUnitPrice !== void 0 && params?.\u0441omputeUnitPrice > 0) {
+      const unitPriceInstruction = getSetComputeUnitPriceInstruction({
+        /** Transaction compute unit price used for prioritization fees. */
+        microLamports: params?.\u0441omputeUnitPrice
+      });
+      transactionMessage = prependTransactionMessageInstruction(
+        unitPriceInstruction,
+        transactionMessage
+      );
+    }
+    for (const instruction of instructions) {
+      transactionMessage = appendTransactionMessageInstruction(
+        instruction,
+        transactionMessage
+      );
+    }
+    if (params?.afterInstructions) {
+      for (const instruction of params.afterInstructions) {
+        transactionMessage = appendTransactionMessageInstruction(
+          instruction,
+          transactionMessage
+        );
+      }
+    }
+    const finalLatestBlockhash = params?.finalLatestBlockhash || (await this.connection.getLatestBlockhash().send()).value;
+    const txMessageWithBlockhashLifetime = setTransactionMessageLifetimeUsingBlockhash(
+      finalLatestBlockhash,
+      transactionMessage
+    );
+    return txMessageWithBlockhashLifetime;
+  }
+};
+export {
+  Blockchain,
+  ERROR_MESSAGES,
+  HyspSolana,
+  VAULTS,
+  WalletSDKError
+};

package/eslint.config.mjs

@@ -0,0 +1,21 @@
+import globals from 'globals';
+import pluginJs from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
+
+export default [
+  { files: ['**/*.{js,mjs,cjs,ts}'] },
+  { languageOptions: { globals: globals.browser } },
+  pluginJs.configs.recommended,
+  ...tseslint.configs.strict,
+  eslintPluginPrettierRecommended,
+  {
+    rules: {
+      'padding-line-between-statements': [
+        'error',
+        { blankLine: 'always', prev: '*', next: 'return' },
+      ],
+      '@typescript-eslint/unified-signatures': 'off',
+    },
+  },
+];

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@everstake/wallet-sdk-hysp-solana",
+  "version": "1.0.0",
+  "description": "HYSP Solana - Everstake Wallet SDK",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "pnpm run prebuild && tsup src/index.ts --format cjs,esm --dts",
+    "type-check": "tsc",
+    "lint": "eslint 'src/**/*.{ts,tsx}'",
+    "prettier": "prettier --write 'src/**/*.{ts,tsx}'",
+    "test": "jest",
+    "prebuild": "pnpm run type-check && pnpm run lint"
+  },
+  "keywords": [
+    "hysp",
+    "solana",
+    "vault",
+    "blockchain",
+    "everstake",
+    "wallet sdk"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/everstake/wallet-sdk.git"
+  },
+  "author": "Everstake",
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/everstake/wallet-sdk/issues"
+  },
+  "homepage": "https://github.com/everstake/wallet-sdk#readme",
+  "dependencies": {
+    "@kamino-finance/klend-sdk": "^7.2.4",
+    "@solana-program/compute-budget": "^0.7.0",
+    "@solana/kit": "^3.0.3",
+    "decimal.js": "^10.6.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.7.0",
+    "@jest/types": "^29.6.3",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.14.10",
+    "@typescript-eslint/eslint-plugin": "^7.16.0",
+    "@typescript-eslint/parser": "^7.16.0",
+    "eslint": "^9.7.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "globals": "^16.5.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.3.2",
+    "ts-jest": "^29.2.2",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.1.0",
+    "typescript": "^5.5.3",
+    "typescript-eslint": "^8.46.2"
+  }
+}

package/src/constants/errors.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2025, Everstake.
+ * Licensed under the BSD-3-Clause License. See LICENSE file for details.
+ */
+
+export const ERROR_MESSAGES = {
+  INITIALIZATION_ERROR: 'An error occurred while initializingSDK',
+  DEPOSIT_ERROR: 'An error occurred while creating vault deposit transaction',
+  WITHDRAW_ERROR: 'An error occurred while creating vault withdraw transaction',
+  GET_SHARES_ERROR: 'An error occurred while fetching vault balance',
+  GET_BALANCE_ERROR: 'An error occurred while fetching user token balance',
+  VAULT_LOAD_ERROR: 'An error occurred while loading vault info',
+  VAULT_NOT_FOUND_ERROR: 'Vault not found for token: {0}',
+};

package/src/constants/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2025, Everstake.
+ * Licensed under the BSD-3-Clause License. See LICENSE file for details.
+ */
+
+import { address, Address } from '@solana/kit';
+
+export type SupportedToken = 'USDC';
+
+export type VaultsMap = {
+  [K in SupportedToken]: Address;
+};
+
+export const VAULTS: VaultsMap = {
+  USDC: address('HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E'),
+};
+
+export * from './errors';