@everstake/wallet-sdk-hysp-solana 1.0.0

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2
+}

package/License

@@ -0,0 +1,43 @@
+Copyright (c) 2025, Everstake.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+
+modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this
+
+list of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright notice,
+
+this list of conditions and the following disclaimer in the documentation
+
+and/or other materials provided with the distribution.
+
+Neither the name of the copyright holder nor the names of its
+
+contributors may be used to endorse or promote products derived from
+
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,59 @@
+# Everstake Wallet SDK - HYSP Solana Vault 
+
+## Getting Started
+
+### Step 1: Installing the library
+
+```sh
+$ npm install @everstake/wallet-sdk-hysp-solana
+```
+
+or you can also use yarn
+
+```sh
+$ yarn add @everstake/wallet-sdk-hysp-solana
+```
+
+or you can use pnpm
+
+```sh
+$ pnpm add @everstake/wallet-sdk-hysp-solana
+```
+
+## Step 2: Importing the library
+
+After installing the package, you can import the module and use the SDK:
+
+#### Import ES6
+
+```ts
+// import module
+import { HyspSolana } from '@everstake/wallet-sdk-hysp-solana';
+```
+
+#### Import ES5
+
+```ts
+// import module
+const { HyspSolana } = require('@everstake/wallet-sdk-hysp-solana');
+```
+
+## Step 3: Using the library
+
+Initialize vault object:
+
+```ts
+const hysp = new HyspSolana('USDC');
+```
+
+### 3.1 Depositing to Vault
+
+Use `deposit` method to create deposit to vault transaction instructions.
+
+### 3.2 Withdrawing from Vault
+
+Use `withdraw` method to create withdraw from vault transaction instructions.
+
+### 3.3 Checking Balance
+
+Use `getUserShares` method to get user's vault shares balance.

package/dist/index.d.mts

@@ -0,0 +1,241 @@
+import { Address, Blockhash, Instruction, TransactionMessageWithLifetime } from '@solana/kit';
+import { VaultHoldings, APY } from '@kamino-finance/klend-sdk';
+import { Decimal } from 'decimal.js';
+
+/**
+ * Copyright (c) 2025, Everstake.
+ * Licensed under the BSD-3-Clause License. See LICENSE file for details.
+ */
+/**
+ * `WalletSDKError` is a custom error class that extends the built-in `Error` class.
+ * It provides additional properties for error handling within the Wallet SDK.
+ *
+ * @remarks
+ * This class is needed to provide additional context for errors, such as a code
+ * and the original error, if any.
+ *
+ * @public
+ *
+ * @param message - The error message.
+ * @param code - A string representing the error code.
+ * @param originalError - The original error that caused this error, if any.
+ */
+declare class WalletSDKError extends Error {
+    code: string;
+    originalError?: Error | undefined;
+    constructor(message: string, code: string, originalError?: Error | undefined);
+}
+/**
+ * `Blockchain` is an abstract class that provides a structure for blockchain-specific classes.
+ * It includes methods for error handling and throwing errors.
+ *
+ * @remarks
+ * This class should be extended by classes that implement blockchain-specific functionality.
+ * The extending classes should provide their own `ERROR_MESSAGES` and `ORIGINAL_ERROR_MESSAGES`.
+ *
+ * @property ERROR_MESSAGES - An object that maps error codes to error messages.
+ * @property ORIGINAL_ERROR_MESSAGES - An object that maps original error messages to user-friendly error messages.
+ *
+ *
+ * **/
+declare abstract class Blockchain {
+    protected abstract ERROR_MESSAGES: {
+        [key: string]: string;
+    };
+    protected abstract ORIGINAL_ERROR_MESSAGES: {
+        [key: string]: string;
+    };
+    /**
+     * 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: keyof typeof this.ERROR_MESSAGES, originalError: Error | WalletSDKError | unknown): void;
+    /**
+     * 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: keyof typeof this.ERROR_MESSAGES, ...values: string[]): void;
+    /**
+     * Check if the URL is valid
+     *
+     * @param {string} url - URL
+     * @returns a bool type result.
+     *
+     */
+    isValidURL(url: string): boolean;
+}
+
+/**
+ * Copyright (c) 2025, Everstake.
+ * Licensed under the BSD-3-Clause License. See LICENSE file for details.
+ */
+declare const ERROR_MESSAGES: {
+    INITIALIZATION_ERROR: string;
+    DEPOSIT_ERROR: string;
+    WITHDRAW_ERROR: string;
+    GET_SHARES_ERROR: string;
+    GET_BALANCE_ERROR: string;
+    VAULT_LOAD_ERROR: string;
+    VAULT_NOT_FOUND_ERROR: string;
+};
+
+/**
+ * Copyright (c) 2025, Everstake.
+ * Licensed under the BSD-3-Clause License. See LICENSE file for details.
+ */
+
+type SupportedToken = 'USDC';
+type VaultsMap = {
+    [K in SupportedToken]: Address;
+};
+declare const VAULTS: VaultsMap;
+
+/**
+ * Copyright (c) 2025, Everstake.
+ * Licensed under the BSD-3-Clause License. See LICENSE file for details.
+ */
+
+interface ApiResponse<T> {
+    result: T;
+}
+type Params = {
+    сomputeUnitPrice?: bigint;
+    computeUnitLimit?: number;
+    finalLatestBlockhash?: {
+        /** a Hash as base-58 encoded string */
+        blockhash: Blockhash;
+        /** last block height at which the blockhash will be valid */
+        lastValidBlockHeight: bigint;
+    };
+    /** Instructions to be added after the main instructions  created by SDK */
+    afterInstructions?: Instruction[];
+};
+
+/**
+ * Copyright (c) 2025, Everstake.
+ * Licensed under the BSD-3-Clause License. See LICENSE file for details.
+ */
+
+/**
+ * The `HyspSolana` class extends the `Blockchain` class and provides methods for interacting with vaults on Solana.
+ *
+ * This SDK allows users to perform vault operations such as deposits, withdrawals, and retrieving vault information.
+ *
+ * @property connection - The connection to the Solana blockchain.
+ * @property vault - The KaminoVault instance for vault operations.
+ * @property tokenSymbol - The supported token symbol for the vault.
+ * @property ERROR_MESSAGES - The error messages for the HYSP class.
+ * @property ORIGINAL_ERROR_MESSAGES - The original error messages for the HYSP class.
+ *
+ */
+declare class HyspSolana extends Blockchain {
+    protected ERROR_MESSAGES: {
+        INITIALIZATION_ERROR: string;
+        DEPOSIT_ERROR: string;
+        WITHDRAW_ERROR: string;
+        GET_SHARES_ERROR: string;
+        GET_BALANCE_ERROR: string;
+        VAULT_LOAD_ERROR: string;
+        VAULT_NOT_FOUND_ERROR: string;
+    };
+    protected ORIGINAL_ERROR_MESSAGES: {
+        INITIALIZATION_ERROR: string;
+        DEPOSIT_ERROR: string;
+        WITHDRAW_ERROR: string;
+        GET_SHARES_ERROR: string;
+        GET_BALANCE_ERROR: string;
+        VAULT_LOAD_ERROR: string;
+        VAULT_NOT_FOUND_ERROR: string;
+    };
+    private connection;
+    private 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: SupportedToken, rpcUrl?: string);
+    private getVaultAddress;
+    private convertToDecimal;
+    /**
+     * 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.
+     */
+    getVaultHoldings(): Promise<ApiResponse<VaultHoldings>>;
+    /**
+     * 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.
+     */
+    getVaultAPYs(): Promise<ApiResponse<APY>>;
+    /**
+     * 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.
+     */
+    getExchangeRate(): Promise<ApiResponse<Decimal>>;
+    /**
+     * 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.
+     */
+    getUserShares(userAddress: Address): Promise<ApiResponse<Decimal>>;
+    /**
+     * 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.
+     */
+    getUserBalance(userAddress: Address): Promise<ApiResponse<Decimal>>;
+    /**
+     * 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.
+     */
+    deposit(userAddress: Address, amount: number | string | bigint | Decimal, params?: Params): Promise<ApiResponse<TransactionMessageWithLifetime>>;
+    /**
+     * 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.
+     */
+    withdraw(userAddress: Address, sharesAmount: number | string | bigint | Decimal, params?: Params): Promise<ApiResponse<TransactionMessageWithLifetime>>;
+    private buildTx;
+}
+
+export { type ApiResponse, Blockchain, ERROR_MESSAGES, HyspSolana, type Params, type SupportedToken, VAULTS, type VaultsMap, WalletSDKError };

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+import { Address, Blockhash, Instruction, TransactionMessageWithLifetime } from '@solana/kit';
+import { VaultHoldings, APY } from '@kamino-finance/klend-sdk';
+import { Decimal } from 'decimal.js';
+
+/**
+ * Copyright (c) 2025, Everstake.
+ * Licensed under the BSD-3-Clause License. See LICENSE file for details.
+ */
+/**
+ * `WalletSDKError` is a custom error class that extends the built-in `Error` class.
+ * It provides additional properties for error handling within the Wallet SDK.
+ *
+ * @remarks
+ * This class is needed to provide additional context for errors, such as a code
+ * and the original error, if any.
+ *
+ * @public
+ *
+ * @param message - The error message.
+ * @param code - A string representing the error code.
+ * @param originalError - The original error that caused this error, if any.
+ */
+declare class WalletSDKError extends Error {
+    code: string;
+    originalError?: Error | undefined;
+    constructor(message: string, code: string, originalError?: Error | undefined);
+}
+/**
+ * `Blockchain` is an abstract class that provides a structure for blockchain-specific classes.
+ * It includes methods for error handling and throwing errors.
+ *
+ * @remarks
+ * This class should be extended by classes that implement blockchain-specific functionality.
+ * The extending classes should provide their own `ERROR_MESSAGES` and `ORIGINAL_ERROR_MESSAGES`.
+ *
+ * @property ERROR_MESSAGES - An object that maps error codes to error messages.
+ * @property ORIGINAL_ERROR_MESSAGES - An object that maps original error messages to user-friendly error messages.
+ *
+ *
+ * **/
+declare abstract class Blockchain {
+    protected abstract ERROR_MESSAGES: {
+        [key: string]: string;
+    };
+    protected abstract ORIGINAL_ERROR_MESSAGES: {
+        [key: string]: string;
+    };
+    /**
+     * 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: keyof typeof this.ERROR_MESSAGES, originalError: Error | WalletSDKError | unknown): void;
+    /**
+     * 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: keyof typeof this.ERROR_MESSAGES, ...values: string[]): void;
+    /**
+     * Check if the URL is valid
+     *
+     * @param {string} url - URL
+     * @returns a bool type result.
+     *
+     */
+    isValidURL(url: string): boolean;
+}
+
+/**
+ * Copyright (c) 2025, Everstake.
+ * Licensed under the BSD-3-Clause License. See LICENSE file for details.
+ */
+declare const ERROR_MESSAGES: {
+    INITIALIZATION_ERROR: string;
+    DEPOSIT_ERROR: string;
+    WITHDRAW_ERROR: string;
+    GET_SHARES_ERROR: string;
+    GET_BALANCE_ERROR: string;
+    VAULT_LOAD_ERROR: string;
+    VAULT_NOT_FOUND_ERROR: string;
+};
+
+/**
+ * Copyright (c) 2025, Everstake.
+ * Licensed under the BSD-3-Clause License. See LICENSE file for details.
+ */
+
+type SupportedToken = 'USDC';
+type VaultsMap = {
+    [K in SupportedToken]: Address;
+};
+declare const VAULTS: VaultsMap;
+
+/**
+ * Copyright (c) 2025, Everstake.
+ * Licensed under the BSD-3-Clause License. See LICENSE file for details.
+ */
+
+interface ApiResponse<T> {
+    result: T;
+}
+type Params = {
+    сomputeUnitPrice?: bigint;
+    computeUnitLimit?: number;
+    finalLatestBlockhash?: {
+        /** a Hash as base-58 encoded string */
+        blockhash: Blockhash;
+        /** last block height at which the blockhash will be valid */
+        lastValidBlockHeight: bigint;
+    };
+    /** Instructions to be added after the main instructions  created by SDK */
+    afterInstructions?: Instruction[];
+};
+
+/**
+ * Copyright (c) 2025, Everstake.
+ * Licensed under the BSD-3-Clause License. See LICENSE file for details.
+ */
+
+/**
+ * The `HyspSolana` class extends the `Blockchain` class and provides methods for interacting with vaults on Solana.
+ *
+ * This SDK allows users to perform vault operations such as deposits, withdrawals, and retrieving vault information.
+ *
+ * @property connection - The connection to the Solana blockchain.
+ * @property vault - The KaminoVault instance for vault operations.
+ * @property tokenSymbol - The supported token symbol for the vault.
+ * @property ERROR_MESSAGES - The error messages for the HYSP class.
+ * @property ORIGINAL_ERROR_MESSAGES - The original error messages for the HYSP class.
+ *
+ */
+declare class HyspSolana extends Blockchain {
+    protected ERROR_MESSAGES: {
+        INITIALIZATION_ERROR: string;
+        DEPOSIT_ERROR: string;
+        WITHDRAW_ERROR: string;
+        GET_SHARES_ERROR: string;
+        GET_BALANCE_ERROR: string;
+        VAULT_LOAD_ERROR: string;
+        VAULT_NOT_FOUND_ERROR: string;
+    };
+    protected ORIGINAL_ERROR_MESSAGES: {
+        INITIALIZATION_ERROR: string;
+        DEPOSIT_ERROR: string;
+        WITHDRAW_ERROR: string;
+        GET_SHARES_ERROR: string;
+        GET_BALANCE_ERROR: string;
+        VAULT_LOAD_ERROR: string;
+        VAULT_NOT_FOUND_ERROR: string;
+    };
+    private connection;
+    private 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: SupportedToken, rpcUrl?: string);
+    private getVaultAddress;
+    private convertToDecimal;
+    /**
+     * 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.
+     */
+    getVaultHoldings(): Promise<ApiResponse<VaultHoldings>>;
+    /**
+     * 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.
+     */
+    getVaultAPYs(): Promise<ApiResponse<APY>>;
+    /**
+     * 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.
+     */
+    getExchangeRate(): Promise<ApiResponse<Decimal>>;
+    /**
+     * 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.
+     */
+    getUserShares(userAddress: Address): Promise<ApiResponse<Decimal>>;
+    /**
+     * 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.
+     */
+    getUserBalance(userAddress: Address): Promise<ApiResponse<Decimal>>;
+    /**
+     * 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.
+     */
+    deposit(userAddress: Address, amount: number | string | bigint | Decimal, params?: Params): Promise<ApiResponse<TransactionMessageWithLifetime>>;
+    /**
+     * 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.
+     */
+    withdraw(userAddress: Address, sharesAmount: number | string | bigint | Decimal, params?: Params): Promise<ApiResponse<TransactionMessageWithLifetime>>;
+    private buildTx;
+}
+
+export { type ApiResponse, Blockchain, ERROR_MESSAGES, HyspSolana, type Params, type SupportedToken, VAULTS, type VaultsMap, WalletSDKError };