@lombard.finance/sdk 4.0.0 → 4.1.0

package/src/metrics/get-lbtc-apy.ts

@@ -1,74 +0,0 @@
-import axios from 'axios';
-import BigNumber from 'bignumber.js';
-import { Address, zeroAddress } from 'viem';
-
-import { getApiConfig } from '../common/api-config';
-import { IEnvParam } from '../common/parameters';
-
-type Response = {
-  lbtc_base_apy: number;
-  lbtc_effective_apy: number;
-};
-
-export type LbtcApy = {
-  /**
-   * The base APY for LBTC, representing the nominal yield without any bonuses
-   * or adjustments.
-   */
-  baseApy: BigNumber;
-  /**
-   * The effective APY for LBTC, including any additional rewards,
-   * compounding effects, or protocol-specific incentives.
-   */
-  effectiveApy: BigNumber;
-};
-
-/** Returns the current APY (annual percentage yield) for LBTC. */
-export async function getApy({
-  account,
-  env,
-}: {
-  /** The optional account address. Pass it for more accurate APY data. */
-  account?: Address;
-} & IEnvParam) {
-  const { baseApiUrl } = getApiConfig(env);
-
-  const url = `${baseApiUrl}/api/v1/analytics/${account || zeroAddress}/apy`;
-  const { data } = await axios.get<Response>(url);
-
-  const apy: LbtcApy = {
-    baseApy: BigNumber(data.lbtc_base_apy),
-    effectiveApy: BigNumber(data.lbtc_effective_apy),
-  };
-
-  return apy;
-}
-
-type EstimatedApyResponse = { lbtc_estimated_apy: number };
-export type LbtcEstimatedApy = {
-  /**
-   * The estimated APY for LBTC based on the specified partner context.
-   *
-   * This value reflects a projected annual percentage yield that may vary
-   * depending on the `partnerId`, taking into account potential partner-specific
-   * incentives, compounding assumptions, or estimated future rewards.
-   */
-  estimatedApy: BigNumber;
-};
-
-/** Returns the estimated APY for LBTC. */
-export async function getEstimatedApy({
-  partnerId,
-  env,
-}: { partnerId?: string } & IEnvParam) {
-  const { baseApiUrl } = getApiConfig(env);
-
-  const url = `${baseApiUrl}/api/v1/analytics/estimated-apy?partner_id=${partnerId || ''}`;
-  const { data } = await axios.get<EstimatedApyResponse>(url);
-
-  const apy: LbtcEstimatedApy = {
-    estimatedApy: BigNumber(data.lbtc_estimated_apy),
-  };
-
-  return apy;
-}

package/src/metrics/get-lbtc-stats.stories.tsx

@@ -1,57 +0,0 @@
-import { DEFAULT_ENV } from '@lombard.finance/sdk-common';
-import type { Meta, StoryObj } from '@storybook/react';
-
-import { envSelector } from '../stories/arg-types';
-import { Button } from '../stories/components/Button';
-import { CodeBlock } from '../stories/components/CodeBlock';
-import { functionType, wagmiDecorator } from '../stories/components/decorators';
-import { ErrorBlock } from '../stories/components/error-block';
-import useQuery from '../stories/hooks/useQuery';
-import { getLBTCStats } from './get-lbtc-stats';
-
-const meta = {
-  title: 'metrics/getLBTCStats',
-  component: StoryView,
-  tags: ['autodocs'],
-  decorators: [wagmiDecorator, functionType('api-get')],
-  argTypes: { ...envSelector },
-} satisfies Meta<typeof StoryView>;
-
-export default meta;
-
-type Story = StoryObj<typeof meta>;
-
-export const WithParams: Story = {
-  args: {
-    env: DEFAULT_ENV,
-  },
-};
-
-type SignNetworkFeeProps = Parameters<typeof getLBTCStats>[0];
-
-export function StoryView(props: SignNetworkFeeProps) {
-  const request = async () => {
-    return getLBTCStats({
-      ...props,
-    });
-  };
-
-  const { data, error, isLoading, refetch } = useQuery(request, [], false);
-
-  return (
-    <>
-      <p>This function returns the total supply of the LBTC.</p>
-
-      <Button
-        onClick={refetch}
-        disabled={isLoading}
-        isLoading={isLoading}
-        actionName={getLBTCStats.name}
-      />
-
-      <ErrorBlock>{error}</ErrorBlock>
-
-      <CodeBlock text={data} />
-    </>
-  );
-}

package/src/metrics/get-lbtc-stats.ts

@@ -1,59 +0,0 @@
-import axios from 'axios';
-import BigNumber from 'bignumber.js';
-
-import { getApiConfig } from '../common/api-config';
-import { IEnvParam } from '../common/parameters';
-
-type LBTCStatsResponse = { price: number; supply: number; tvl: number }[];
-
-type LBTCHoldersResponse = number;
-
-type Stats = {
-  /** The BTC price  */
-  price: BigNumber;
-  /** The LBTC supply */
-  supply: BigNumber;
-  /** The LBTC TVL (supply * price) */
-  tvl: BigNumber;
-  /** The number of LBTC holders */
-  holders: BigNumber;
-  /** The total (historical) number of LBTC holders */
-  historicalHolders: BigNumber;
-};
-
-/** Gets the Lombard's TVL. */
-export async function getLBTCStats(
-  parameters?: { partnerId?: string; accountAddress?: string } & IEnvParam,
-) {
-  const env = parameters?.env;
-  const partnerId = parameters?.partnerId;
-
-  const { bffApiUrl } = getApiConfig(env);
-  if (!bffApiUrl) {
-    throw new Error(
-      `Could not determine API endpoint for provided environment: ${env}`,
-    );
-  }
-
-  const { data } = await axios.get<LBTCStatsResponse>(
-    `${bffApiUrl}/dune-api/query/getLBTCStats?partnerId=${partnerId || ''}`,
-  );
-
-  const { data: holders } = await axios.get<LBTCHoldersResponse>(
-    `${bffApiUrl}/dune-api/query/lbtc-holders?partnerId=${partnerId || ''}`,
-  );
-
-  const { data: historicalHolders } = await axios.get<LBTCHoldersResponse>(
-    `${bffApiUrl}/dune-api/query/getTotalLBTCUsers?partnerId=${partnerId || ''}`,
-  );
-
-  const stats: Stats = {
-    price: BigNumber(data[0].price),
-    supply: BigNumber(data[0].supply),
-    tvl: BigNumber(data[0].tvl),
-    holders: BigNumber(holders),
-    historicalHolders: BigNumber(historicalHolders),
-  };
-
-  return stats;
-}

package/src/metrics/get-positions-summary.stories.tsx

@@ -1,58 +0,0 @@
-import { Env } from '@lombard.finance/sdk-common';
-import type { Meta, StoryObj } from '@storybook/react';
-
-import { envSelector } from '../stories/arg-types';
-import { Button } from '../stories/components/Button';
-import { CodeBlock } from '../stories/components/CodeBlock';
-import { functionType, wagmiDecorator } from '../stories/components/decorators';
-import { ErrorBlock } from '../stories/components/error-block';
-import { EXAMPLE_EVM_ADDRESS } from '../stories/constants';
-import useQuery from '../stories/hooks/useQuery';
-import { getPositionsSummary } from './get-positions-summary';
-
-const meta = {
-  title: 'metrics/getPositionsSummary',
-  component: StoryView,
-  tags: ['autodocs'],
-  decorators: [wagmiDecorator, functionType('api-get')],
-  argTypes: { ...envSelector },
-} satisfies Meta<typeof StoryView>;
-
-export default meta;
-
-type Story = StoryObj<typeof meta>;
-
-export const WithParams: Story = {
-  args: { account: EXAMPLE_EVM_ADDRESS, env: Env.stage },
-};
-
-type SignNetworkFeeProps = Parameters<typeof getPositionsSummary>[0];
-
-export function StoryView(props: SignNetworkFeeProps) {
-  const request = async () => {
-    return getPositionsSummary({
-      ...props,
-    });
-  };
-
-  const { data, error, isLoading, refetch } = useQuery(request, [], false);
-
-  return (
-    <>
-      <p>
-        This function returns the rewards info for provided account address.
-      </p>
-
-      <Button
-        onClick={refetch}
-        disabled={isLoading}
-        isLoading={isLoading}
-        actionName={getPositionsSummary.name}
-      />
-
-      <ErrorBlock>{error}</ErrorBlock>
-
-      <CodeBlock text={data} />
-    </>
-  );
-}

package/src/metrics/get-positions-summary.ts

@@ -1,132 +0,0 @@
-import axios from 'axios';
-import BigNumber from 'bignumber.js';
-import { Address } from 'viem';
-
-import { getApiConfig } from '../common/api-config';
-import { IEnvParam } from '../common/parameters';
-import { Token } from '../tokens/token-addresses';
-
-type PositionAsset = 'ASSET_LBTC' | 'ASSET_UNSPECIFIED';
-type PositionType = 'BALANCE_TYPE_HOLDING' | 'BALANCE_TYPE_DEFI';
-
-type Response = {
-  btc_price_usd: { price: number; timestamp: string };
-  btc_value: number;
-  btc_pnl: number;
-  snapshot: [
-    {
-      asset: PositionAsset;
-      type: PositionType;
-      balance: number;
-      pnl: number;
-      rate: number;
-    },
-  ];
-  last_updated: string;
-  in_progress: boolean;
-};
-
-function mapRewardAssetToToken(asset: PositionAsset) {
-  switch (asset) {
-    case 'ASSET_LBTC':
-      return Token.LBTC;
-    default:
-      return undefined;
-  }
-}
-
-export type PositionsSummary = {
-  /**
-   * The current BTC price in USD, along with the timestamp
-   * when the price was last fetched.
-   */
-  btcPrice: {
-    /** The price of 1 BTC in USD. */
-    price: BigNumber;
-    /** Timestamp of the price data. */
-    timestamp: Date;
-  };
-  /**
-   * Total value of all holdings, denominated in BTC.
-   */
-  btcValue: BigNumber;
-  /**
-   * Total profit or loss across all assets, represented in BTC.
-   */
-  btcPnl: BigNumber;
-  /**
-   * A detailed snapshot of position data used in PnL calculation.
-   */
-  snapshot: {
-    /**
-     * The token associated with this position (e.g., `Token.LBTC`).
-     * Can be `undefined` if unspecified.
-     */
-    token: Token | undefined;
-    /**
-     * The classification or source of the position.
-     */
-    type: PositionType;
-    /**
-     * The quantity of the token held.
-     */
-    balance: BigNumber;
-    /**
-     * The profit or loss for this specific position, in BTC.
-     */
-    pnl: BigNumber;
-    /**
-     * The conversion rate used to determine the BTC value of the balance.
-     * `balance * rate = BTC equivalent`
-     */
-    rate: BigNumber;
-  }[];
-  /**
-   * The timestamp when the PnL data was last updated.
-   */
-  lastUpdated: Date;
-  /**
-   * Indicates whether the backend is currently processing the PnL calculation.
-   *
-   * - `true`: A new calculation request was received, but the backend is experiencing high load
-   *   or processing is not yet complete. The latest data is not yet available.
-   *
-   * - `false`: The most recent calculation has been completed and cached.
-   *   Use `lastUpdated` to understand how fresh the data is:
-   *   - If `lastUpdated` is recent (e.g., within the last few seconds), you're seeing the latest data.
-   *   - If `lastUpdated` is up to 30 minutes old, you're seeing cached data from a recent request.
-   *     The backend avoids recalculating within this caching window.
-   */
-  inProgress: boolean;
-};
-
-/** Retrieves the yield positions summary for the specified account address. */
-export async function getPositionsSummary({
-  account,
-  env,
-}: { account: Address } & IEnvParam) {
-  const { baseApiUrl } = getApiConfig(env);
-
-  const url = `${baseApiUrl}/api/v1/analytics/${account}/summary`;
-  const { data } = await axios.get<Response>(url);
-
-  const info: PositionsSummary = {
-    btcPrice: {
-      price: BigNumber(data.btc_price_usd.price || 0),
-      timestamp: new Date(data.btc_price_usd.timestamp),
-    },
-    btcValue: BigNumber(data.btc_value || 0),
-    btcPnl: BigNumber(data.btc_pnl || 0),
-    snapshot: data.snapshot?.map(ds => ({
-      token: mapRewardAssetToToken(ds.asset),
-      type: ds.type,
-      balance: BigNumber(ds.balance || 0),
-      pnl: BigNumber(ds.pnl || 0),
-      rate: BigNumber(ds.rate || 0),
-    })),
-    lastUpdated: new Date(data.last_updated),
-    inProgress: Boolean(data.in_progress),
-  };
-
-  return info;
-}

package/src/modules/CapabilityRegistry.ts

@@ -1,125 +0,0 @@
-/**
- * Capability Registry
- *
- * Manages optional module services and provides dependency injection for actions.
- * Works exclusively with LombardConfig, never requiring the full SDK instance.
- *
- * @module modules/CapabilityRegistry
- */
-
-import type {
-  AnyModule,
-  ModuleId,
-  ProviderFor,
-  ProviderKey,
-  RegisterContext,
-  SdkModule,
-  ServiceOf,
-  SharedToken,
-} from '@lombard.finance/sdk-common';
-
-import type { LombardConfig } from '../config/types';
-import { getProviderGetter } from '../config/types';
-import { LombardError } from '../shared/errors';
-
-/**
- * Capability Registry
- *
- * Manages optional module services (BTC, EVM, API, Solana, Sui, Starknet, etc.)
- * and provides lazy loading with descriptive error messages.
- *
- * Services are internal implementations for action DI.
- * Public APIs should call underlying functions directly for rich types.
- *
- * @example
- * ```typescript
- * const registry = new CapabilityRegistry(config.modules, config);
- * const btcService = registry.require('btc');
- * const solanaService = registry.optional('solana'); // null if not installed
- * ```
- */
-export class CapabilityRegistry<
-  TModules extends readonly AnyModule[] = readonly AnyModule[],
-> {
-  private readonly modules = new Map<string, AnyModule>();
-  private readonly services = new Map<string, unknown>();
-  private readonly shared = new Map<SharedToken<unknown>, unknown>();
-
-  constructor(
-    modules: readonly AnyModule[],
-    private readonly config: LombardConfig,
-  ) {
-    modules.forEach(mod => this.modules.set(mod.id, mod));
-  }
-
-  /**
-   * Require a module service
-   *
-   * Throws LombardError.moduleMissing if module not installed.
-   *
-   * @param id - Module identifier
-   * @returns Module service
-   */
-  require<TId extends ModuleId<TModules[number]>>(
-    id: TId,
-  ): ServiceOf<TModules[number] & SdkModule<TId, unknown>, TId> {
-    const mod = this.modules.get(id as string);
-    if (!mod) {
-      throw LombardError.moduleMissing(id as string);
-    }
-    if (!this.services.has(mod.id)) {
-      this.services.set(mod.id, mod.register(this.createContext()));
-    }
-    return this.services.get(mod.id) as ServiceOf<
-      TModules[number] & SdkModule<TId, unknown>,
-      TId
-    >;
-  }
-
-  /**
-   * Optionally get a module service
-   *
-   * Returns null if module not installed (no error thrown).
-   *
-   * @param id - Module identifier
-   * @returns Module service or null
-   */
-  optional<TId extends ModuleId<TModules[number]>>(
-    id: TId,
-  ): ServiceOf<TModules[number] & SdkModule<TId, unknown>, TId> | null {
-    const mod = this.modules.get(id as string);
-    if (!mod) {
-      return null;
-    }
-    if (!this.services.has(mod.id)) {
-      this.services.set(mod.id, mod.register(this.createContext()));
-    }
-    return this.services.get(mod.id) as ServiceOf<
-      TModules[number] & SdkModule<TId, unknown>,
-      TId
-    >;
-  }
-
-  /**
-   * Create registration context for modules
-   *
-   * Provides modules with access to config-based services.
-   */
-  private createContext(): RegisterContext {
-    return {
-      env: this.config.env,
-      getProvider: async <TKey extends ProviderKey>(key: TKey) => {
-        const getter = getProviderGetter(this.config.providers, key);
-        if (!getter) {
-          return undefined as unknown as ProviderFor<TKey>;
-        }
-        return (await getter()) as ProviderFor<TKey>;
-      },
-      getShared: <T>(token: SharedToken<T>) =>
-        this.shared.get(token as SharedToken<unknown>) as T | undefined,
-      setShared: <T>(token: SharedToken<T>, value: T) => {
-        this.shared.set(token as SharedToken<unknown>, value);
-      },
-    };
-  }
-}

package/src/modules/apiModule.ts

@@ -1,51 +0,0 @@
-/**
- * API Module
- *
- * Provides Lombard backend API service for internal use by actions.
- * Uses Service-First pattern: module is a thin factory that instantiates the service.
- *
- * Note: This is an internal service for dependency injection into actions.
- * For public APIs, use the SDK namespace methods (e.g., sdk.deposits.getByAddress())
- * which call the underlying functions directly and return rich types.
- *
- * @module modules/apiModule
- */
-
-import type {
-  ApiService as IApiService,
-  SdkModule,
-} from '@lombard.finance/sdk-common';
-
-import { ApiService } from '../services/ApiService';
-
-/**
- * Create API module
- *
- * Internal module that provides ApiService. Automatically included by createLombardSDK().
- *
- * @example
- * ```ts
- * const sdk = await createLombardSDK({
- *   env: Env.prod,
- *   providers: { evm: () => window.ethereum },
- * });
- * const deposits = await sdk.api.deposits('0x...');
- * ```
- */
-export function apiModule(): SdkModule<'api', IApiService> {
-  return {
-    id: 'api',
-    register(ctx) {
-      return new ApiService(ctx.env);
-    },
-  };
-}
-
-// Re-export service class and interface type
-export { ApiService };
-export type { IApiService as ApiServiceInterface };
-export type {
-  DepositInfo,
-  GenerateDepositAddressParams,
-  GetDepositAddressParams,
-} from '@lombard.finance/sdk-common';

package/src/modules/btcModule.ts

@@ -1,43 +0,0 @@
-/**
- * BTC Module
- *
- * Provides Bitcoin chain service for deposit monitoring and address operations.
- * Uses Service-First pattern: module is a thin factory that instantiates the service.
- *
- * @module modules/btcModule
- */
-
-import type {
-  BtcService as IBtcService,
-  ChainModule,
-} from '@lombard.finance/sdk-common';
-
-import { BtcService } from '../services/BtcService';
-
-/**
- * Create BTC module
- *
- * Built-in module that provides BtcService. Automatically included by createLombardSDK().
- *
- * @example
- * ```ts
- * const sdk = await createLombardSDK({
- *   env: Env.prod,
- *   providers: { evm: () => window.ethereum },
- * });
- * const stake = sdk.chain.btc.stake({ ... });
- * ```
- */
-export function btcModule(): ChainModule<'btc', IBtcService> {
-  return {
-    id: 'btc',
-    chain: 'btc',
-    register() {
-      return new BtcService();
-    },
-  };
-}
-
-// Re-export service class and interface type
-export { BtcService };
-export type { IBtcService as BtcServiceInterface };

package/src/modules/evmModule.ts

@@ -1,48 +0,0 @@
-/**
- * EVM Module
- *
- * Provides EVM chain service for contract interactions and fee authorization.
- * Uses Service-First pattern: module is a thin factory that instantiates the service.
- *
- * @module modules/evmModule
- */
-
-import type {
-  ChainModule,
-  EvmService as IEvmService,
-} from '@lombard.finance/sdk-common';
-
-import { EvmService } from '../services/EvmService';
-
-/**
- * Create EVM module
- *
- * Built-in module that provides EvmService. Automatically included by createLombardSDK().
- *
- * @example
- * ```ts
- * const sdk = await createLombardSDK({
- *   env: Env.prod,
- *   providers: { evm: () => window.ethereum },
- * });
- * const unstake = sdk.chain.evm.unstake({ ... });
- * ```
- */
-export function evmModule(): ChainModule<'evm', IEvmService> {
-  return {
-    id: 'evm',
-    chain: 'evm',
-    register(ctx) {
-      return new EvmService(ctx.env);
-    },
-  };
-}
-
-// Re-export service class and interface type
-export { EvmService };
-export type { IEvmService as EvmServiceInterface };
-export type {
-  EvmChainId,
-  FeeAuthorizationResult,
-  StoredFeeSignature,
-} from '@lombard.finance/sdk-common';