@upshiftfinance/sdk 0.0.0-stage → 0.2.0

package/lib/modules/vaults/utils.d.ts

@@ -0,0 +1,153 @@
+import type { IAddress, IContractRunner, INormalizedNumber, IPoolFunctions, ITokenizedVault, IVault, IVaultFreshness, IVaultVersion } from '../../types';
+import { ethers } from 'ethers';
+import type { WalletClient } from 'viem';
+/**
+ * @param walletClient a wagmi-derived client (from useWalletClient)
+ * @returns An ethers JsonRpcSigner object used in sdk.evm.setSigner
+ */
+export declare function walletClientToSigner(walletClient: WalletClient): Promise<ethers.JsonRpcSigner>;
+/**
+ * Calculates the reward multiplier based on the vault and optional timestamp.
+ * Returns the applicable multiplier for a given vault at a specific timestamp,
+ * or the latest multiplier if no timestamp is provided.
+ * @param foundPool The vault to get the multiplier for
+ * @param timestamp Optional timestamp to get historical multiplier
+ * @returns The reward multiplier value
+ */
+export declare const getRewardMultiplierByTimestamp: (foundPool: IVault, timestamp?: number) => number;
+/**
+ * Get the rewards for the vault.
+ *
+ * Builds the display-facing rewards summary from the raw tokenized-vault
+ * rewards array. In addition to the legacy `additionalPoints` string list, it
+ * emits `additionalPointsDetailed`, which pairs each label with its
+ * backend-provided `img_url`. Consumers (e.g. the Upshift app) resolve a
+ * reward's logo from this `imgUrl` first, falling back to a bundled asset only
+ * when it is absent — so a newly-added reward with a backend logo (e.g.
+ * "Cores") renders its icon without any client-side keyword mapping.
+ *
+ * @param tokenizedVault - The tokenized vault.
+ * @returns The rewards summary, including `additionalPointsDetailed`.
+ */
+export declare function getVaultRewards(tokenizedVault: ITokenizedVault): {
+    points: string;
+    multiplier: number;
+    multipliers: {
+        timestamp: number;
+        value: number;
+    }[];
+    additionalPoints: string[];
+    additionalPointsDetailed: {
+        id: string;
+        label: string;
+        text: string;
+        imgUrl: string;
+        multiplier: number;
+    }[];
+};
+/**
+ * Get the idle assets for the vault
+ * @param provider - The provider
+ * @param vaultAddress - The vault address
+ * @param totalAssets - The total assets of the vault
+ * @param knownVersion - Optional pre-resolved vault version. Callers that
+ *   already hold the backend row (e.g. `buildFormattedVault`) pass it so this
+ *   function doesn't re-fetch `GET /tokenized_vault/{address}` — and with the
+ *   API's default load flags at that, a heavier payload on a different cache
+ *   key than the caller's own fetch — just to dispatch on the version.
+ * @returns The idle assets
+ */
+export declare function getIdleAssets(provider: IContractRunner, vaultAddress: IAddress, underlying: IAddress, totalAssets: INormalizedNumber, knownVersion?: IVaultVersion): Promise<bigint>;
+export declare function getYieldLastRealizedOn(provider: IContractRunner, vaultAddress: IAddress): Promise<number>;
+/**
+ * Format APY data from backend tokenized vault into the unified IVaultApy shape.
+ * Shared across all chain adapters (EVM, Solana, Stellar).
+ */
+export declare function formatVaultApy(tokenizedVault: ITokenizedVault): IVault['apy'];
+/**
+ * Map the backend `freshness` object onto the camelCased {@link IVaultFreshness}
+ * shape carried on `IVault`. Shared across all chain adapters (EVM, Solana,
+ * Stellar) so every surface reports provenance identically.
+ *
+ * Each of the three stamps is passed through independently: a missing member
+ * becomes `null` and is never defaulted from one of the others. That is the point
+ * of the object — `apy_computed_at` and `share_ratio_snapshot_at` describe two
+ * different pipelines, and collapsing them would erase the very staleness signal
+ * (snapshot newer than APY) the field exists to expose.
+ *
+ * @param tokenizedVault - Backend tokenized-vault payload. `freshness` is absent on
+ *   responses predating the backend change, and may be explicitly null.
+ * @returns The mapped freshness object, or `null` when the backend reported none.
+ *   Values are the backend's RFC 3339 UTC strings verbatim — no reformatting, so
+ *   the trailing `Z` is preserved.
+ */
+export declare function mapVaultFreshness(tokenizedVault: ITokenizedVault | undefined | null): IVaultFreshness | null;
+/**
+ * Map a wrapper vault's link to the vault it wraps.
+ *
+ * @param tokenizedVault - Backend tokenized-vault payload.
+ * @returns The underlying vault address (casing preserved) and chain id, both
+ *   null for a non-wrapper vault. A chain id without an address is dropped.
+ */
+export declare function mapUnderlyingVault(tokenizedVault: ITokenizedVault | undefined | null): Pick<IVault, 'underlyingVaultAddress' | 'underlyingChainId'>;
+/**
+ * Map strategists from backend subaccounts or hardcoded list.
+ * Shared across all chain adapters.
+ */
+export declare function mapStrategists(tokenizedVault: ITokenizedVault): {
+    address: IAddress;
+    logo: string;
+    name: string;
+    type: string;
+    website_url: string;
+}[];
+/**
+ * Map composability integrations from backend format to vault format.
+ * Shared across all chain adapters.
+ */
+export declare function mapComposabilityIntegrations(tokenizedVault: ITokenizedVault): IVault['composabilityIntegrations'];
+/**
+ * Convert a backend-reported TVL (whole token units) to a NormalizedBn.
+ * Handles null, undefined, and non-finite values (NaN, Infinity) safely, defaulting to 0.
+ * Shared between non-EVM adapters (Solana, Stellar) and the module-level getVaultTvl handler.
+ */
+export declare function backendTvlToNormalizedBn(tvl: number | null | undefined, decimals: number): INormalizedNumber;
+/**
+ * Build a base IVault from backend data, shared across non-EVM adapters (Solana, Stellar).
+ * Chain-specific fields (chainId, version, name, totalAssets, totalSupply, depositAssets, receipt)
+ * must be provided via the overrides parameter.
+ */
+export declare function buildBackendVault(tokenizedVault: ITokenizedVault, overrides: Pick<IVault, 'chainId' | 'version' | 'name' | 'totalAssets' | 'totalSupply' | 'depositAssets' | 'receipt'> & Pick<Partial<IVault>, 'programId' | 'enabled_historical_price_horizons' | 'defaultApyHorizon' | 'latest_reported_tvl' | 'isDepositPaused' | 'isWithdrawalPaused'>): IVault;
+/**
+ * Build the formatted vault
+ * @param provider - The provider
+ * @param tokenizedVault - The tokenized vault
+ * @param contractCalls - The contract calls
+ * @returns The formatted vault
+ */
+export declare function buildFormattedVault(provider: IContractRunner, tokenizedVault: ITokenizedVault, contractCalls: Record<IPoolFunctions, string | number | INormalizedNumber | boolean | IAddress[]>): Promise<IVault>;
+export declare const ERC_20_PERMIT_HASH = "0x6e71edae12b1b97f4d1f60370fef10105fa2faae0126114a169c64845d6126c9";
+export interface PermitSignature {
+    r: string;
+    s: string;
+    v: number;
+    deadline: number;
+}
+/**
+ * Generate an ERC2612 permit signature
+ * @param token - The ERC20 token contract address
+ * @param owner - The token owner's address (signer)
+ * @param spender - The address that will be approved to spend (your pool contract)
+ * @param value - The amount to approve
+ * @param deadline - Unix timestamp for when the permit expires
+ * @param signer - The ethers.js Signer (wallet)
+ * @param provider - The ethers.js Provider
+ * @returns The signature components (v, r, s) and deadline
+ */
+export declare function generatePermitSignature(token: string, owner: string, spender: string, value: string | bigint, deadline: number, signer: ethers.Signer, chainId: number): Promise<PermitSignature>;
+/**
+ * Helper to create a deadline (current time + offset in seconds)
+ * @param offsetSeconds - Number of seconds from now (default: 20 minutes)
+ * @returns Unix timestamp
+ */
+export declare function createDeadline(offsetSeconds?: number): number;