@lombard.finance/sdk 4.0.0 → 4.1.2

package/src/contract-functions/signStakeAndBake/validation.ts

@@ -1,124 +0,0 @@
-/**
- * Validation utilities for stake and bake operations.
- * Provides early validation with descriptive error messages.
- */
-
-import { Env } from '@lombard.finance/sdk-common';
-
-import type { ChainId } from '../../common/chains';
-import {
-  DEFI_REGISTRY,
-  DefiProtocol,
-  StakeAndBakeStrategy,
-  StakeAndBakeToken,
-} from '../../defi/defi-registry';
-
-/**
- * Custom error for stake and bake validation failures.
- * Includes error code and context for better debugging.
- */
-export class StakeAndBakeValidationError extends Error {
-  constructor(
-    public readonly code: string,
-    message: string,
-    public readonly context?: Record<string, unknown>,
-  ) {
-    super(message);
-    this.name = 'StakeAndBakeValidationError';
-  }
-}
-
-/**
- * Validates stake and bake parameters and returns the strategy for the requested combo.
- * Throws StakeAndBakeValidationError for invalid combinations.
- *
- * @param vaultKey - The vault to stake into
- * @param token - The token to stake
- * @param chainId - The chain ID
- * @param env - The environment (prod, testnet, etc.)
- * @returns TokenApprovalConfig and spenderContract
- * @throws {StakeAndBakeValidationError} If vault/token/chain/env combination is invalid
- */
-export function getStakeAndBakeConfig(
-  protocol: DefiProtocol,
-  token: StakeAndBakeToken,
-  chainId: ChainId,
-  env: Env,
-): StakeAndBakeStrategy {
-  // Get token approval config from DeFi registry
-  const protocolRegistry = DEFI_REGISTRY[protocol];
-  if (!protocolRegistry) {
-    throw new StakeAndBakeValidationError(
-      'UNSUPPORTED_VAULT',
-      `Vault ${protocol} not found in DeFi registry`,
-      { protocol },
-    );
-  }
-
-  const tokenRegistry = protocolRegistry[token as keyof typeof protocolRegistry];
-  if (!tokenRegistry) {
-    throw new StakeAndBakeValidationError(
-      'UNSUPPORTED_TOKEN',
-      `Token ${token} is not supported for stake and bake on vault ${protocol}. ` +
-        `Supported tokens: ${Object.keys(protocolRegistry).join(', ')}`,
-      { protocol, token, supportedTokens: Object.keys(protocolRegistry) },
-    );
-  }
-
-  const envRegistry = tokenRegistry[env];
-  if (!envRegistry) {
-    throw new StakeAndBakeValidationError(
-      'UNSUPPORTED_ENV',
-      `Environment ${env} is not supported for token ${token} on vault ${protocol}`,
-      { protocol, token, env },
-    );
-  }
-
-  const registryEntry = envRegistry[chainId as keyof typeof envRegistry];
-  if (!registryEntry) {
-    throw new StakeAndBakeValidationError(
-      'UNSUPPORTED_TOKEN_CHAIN',
-      `Token ${token} is not supported on chain ${chainId} for vault ${protocol} in ${env}. ` +
-        `Supported chains: ${Object.keys(envRegistry).join(', ')}`,
-      {
-        protocol,
-        token,
-        chainId,
-        env,
-        supportedChains: Object.keys(envRegistry),
-      },
-    );
-  }
-
-  return {
-    protocol: protocol,
-    token,
-    env,
-    chainId,
-    ...registryEntry,
-  };
-}
-
-/**
- * Checks if a token approval config exists for a given vault/token/chain/env combination.
- * Useful for determining if config-driven logic should be used.
- *
- * @param protocol - The vault to check
- * @param token - The token to check
- * @param chainId - The chain ID to check
- * @param env - The environment to check
- * @returns true if config exists, false otherwise
- */
-export function hasTokenApprovalConfig(
-  protocol: DefiProtocol,
-  token: StakeAndBakeToken,
-  chainId: ChainId,
-  env: Env,
-): boolean {
-  try {
-    const config = getStakeAndBakeConfig(protocol, token, chainId, env);
-    return config !== undefined;
-  } catch {
-    return false;
-  }
-}

package/src/contract-functions/unstakeLBTC/index.ts

@@ -1 +0,0 @@
-export * from './unstakeLBTC';

package/src/contract-functions/unstakeLBTC/unstakeLBTC.stories.tsx

@@ -1,92 +0,0 @@
-import { DEFAULT_ENV } from '@lombard.finance/sdk-common';
-import type { Meta, StoryObj } from '@storybook/react';
-
-import { makeTokenSelector } from '../../stories/arg-types';
-import { Button } from '../../stories/components/Button';
-import { CodeBlock } from '../../stories/components/CodeBlock';
-import { ConnectButton } from '../../stories/components/ConnectButton';
-import {
-  functionType,
-  wagmiDecorator,
-} from '../../stories/components/decorators';
-import {
-  canPerformAction,
-  useConnection,
-} from '../../stories/hooks/useConnection';
-import useQuery from '../../stories/hooks/useQuery';
-import { Token } from '../../tokens/token-addresses';
-import { redeemToken } from './unstakeLBTC';
-
-const meta = {
-  title: 'write/unstakeLBTC',
-  component: StoryView,
-  tags: ['autodocs'],
-  decorators: [wagmiDecorator, functionType('write')],
-  argTypes: {
-    ...makeTokenSelector([Token.LBTC, Token.BTCK, Token.BTCb]),
-  },
-} satisfies Meta<typeof StoryView>;
-
-export default meta;
-
-type Story = StoryObj<typeof meta>;
-
-export const WithParams: Story = {
-  args: {
-    amount: 0.00001,
-    tokenIn: Token.LBTC,
-    btcAddress: '',
-    env: DEFAULT_ENV,
-  },
-};
-
-type ClaimLBTCProps = Omit<
-  Parameters<typeof redeemToken>[0],
-  'account' | 'chainId' | 'provider'
->;
-
-export function StoryView(props: ClaimLBTCProps) {
-  const connection = useConnection();
-
-  const request = async () => {
-    if (!canPerformAction(connection)) {
-      alert('Not connected');
-      return;
-    }
-
-    return redeemToken({
-      amount: props.amount,
-      btcAddress: props.btcAddress,
-      env: props.env,
-      tokenIn: props.tokenIn,
-
-      account: connection.account.address,
-      chainId: connection.account.chainId,
-      provider: connection.provider,
-    });
-  };
-
-  const { data, error, isLoading, refetch } = useQuery(request, [], false);
-
-  return (
-    <>
-      <p>
-        This function unstakes the specified amount of LBTC and transfers the
-        equivalent amount of BTC to the provided BTC address.
-      </p>
-
-      <div className="mb-4">
-        <ConnectButton />
-      </div>
-
-      <Button
-        onClick={refetch}
-        disabled={isLoading || !connection.account.address}
-        isLoading={isLoading}
-        actionName={redeemToken.name}
-      />
-
-      <CodeBlock text={error || data} />
-    </>
-  );
-}

package/src/contract-functions/unstakeLBTC/unstakeLBTC.ts

@@ -1,396 +0,0 @@
-import { getOutputScript } from '@lombard.finance/sdk-common';
-import BigNumber from 'bignumber.js';
-import { Address, erc20Abi, Hex, parseGwei } from 'viem';
-
-import { makePublicClient } from '../../clients/public-client';
-import { makeWalletClient } from '../../clients/wallet-client';
-import {
-  CHAIN_ID_TO_VIEM_CHAIN_MAP,
-  ChainId,
-  isKatanaChain,
-} from '../../common/chains';
-import {
-  CommonSignerWriteParameters,
-  CommonWriteParameters,
-  isProviderFlow,
-} from '../../common/parameters';
-import ASSET_ROUTER_ABI from '../../tokens/abi/ASSET_ROUTER_ABI';
-import { AddressKind, Token } from '../../tokens/token-addresses';
-import {
-  fromBaseDenomination,
-  getTokenContractInfo,
-  isUpgradedAbi,
-  retrieveTokenProperties,
-  toBaseDenomination,
-} from '../../tokens/tokens';
-import { UnsupportedTokenFlow } from '../../utils/err';
-import { estimateGasFees } from '../../utils/gas';
-import toBigInt from '../../utils/numbers';
-import {
-  executeContractTransaction,
-  waitForTransactionReceipt,
-} from '../../utils/transaction-executor';
-
-/**
- * Supported redemption flows.
- *
- * - If `tokenOut` is `undefined`, the redemption defaults to **BTC**
- *   and requires a BTC address as the destination.
- * - Otherwise, redemption will return the specified output token.
- */
-const AVAILABLE_FLOWS: Array<{
-  /** The token being redeemed */
-  tokenIn: Token;
-  /** The token received after redemption (or `undefined` for BTC) */
-  tokenOut?: Token;
-}> = [
-  // Redeem to BTC
-  { tokenIn: Token.LBTC }, // -> BTC
-  { tokenIn: Token.BTCb }, // -> BTC
-  { tokenIn: Token.BTCK }, // -> BTC
-
-  // Redeem to wrapped tokens
-  { tokenIn: Token.LBTC, tokenOut: Token.BTCb }, // -> Native LBTC
-  { tokenIn: Token.LBTC, tokenOut: Token.BTCK }, // -> Native LBTC
-];
-
-type RedeemTokenParameters = {
-  /**
-   * The amount to redeem, expressed in human-readable format.
-   *
-   * For example, use `"1.23"` to represent 1.23 LBTC.
-   */
-  amount: BigNumber.Value;
-  /**
-   * (Optional) Destination BTC address for redemption.
-   *
-   * Required if {@link tokenOut} is omitted (since the default
-   * redemption flow sends BTC).
-   */
-  btcAddress?: string;
-  /**
-   * The token to be redeemed.
-   *
-   * Defaults to {@link Token.LBTC}.
-   */
-  tokenIn: Token;
-  /**
-   * (Optional) The token to receive after redemption.
-   *
-   * - If provided, redemption will return the specified token.
-   * - If omitted, redemption defaults to BTC and a {@link btcAddress}
-   *   must be supplied.
-   */
-  tokenOut?: Token;
-};
-
-/**
- * Union type for redeem token parameters supporting both provider and signer flows.
- */
-type RedeemTokenParams =
-  | (RedeemTokenParameters & CommonWriteParameters)
-  | (RedeemTokenParameters & CommonSignerWriteParameters);
-
-/**
- * Parameters required to unstake (redeem) LBTC into BTC.
- *
- * Overrides {@link RedeemTokenParameters} to make `btcAddress` required,
- * since unstaking always goes to BTC.
- */
-export type IUnstakeLBTCParams =
-  | (RedeemTokenParameters & CommonWriteParameters & { btcAddress: string })
-  | (RedeemTokenParameters &
-      CommonSignerWriteParameters & { btcAddress: string });
-
-/**
- * Redeems a token into **BTC** or another supported token.
- *
- * @remarks
- * This is the **preferred** API for all redemption flows.
- * - If `tokenOut` is `undefined`, redemption sends BTC and requires a valid BTC address.
- * - If `tokenOut` is provided, redemption swaps to the target token
- *   (requires an upgraded token contract ABI).
- *
- * Supports two execution modes:
- * 1. **Provider flow** (legacy): Pass `provider: EIP1193Provider`
- * 2. **Signer flow** (unified bridge): Pass `signer: SignerAdapter`
- *
- * @param params - Parameters including the source token, amount, and either provider or signer.
- * @returns Transaction hash of the executed redemption transaction.
- *
- * @throws {UnsupportedTokenFlow} If the requested flow is not supported.
- * @throws {Error} If balances are insufficient or required parameters are missing.
- * @throws {SignerError} If transaction execution fails (with detailed context).
- *
- * @example
- * ```ts
- * // Provider flow (legacy)
- * const txHash = await redeemToken({
- *   provider,
- *   account: '0x...',
- *   amount: '1.5',
- *   btcAddress: 'bc1q...',
- *   chainId: ChainId.ethereum,
- *   env: Env.prod,
- *   tokenIn: Token.LBTC,
- * });
- *
- * // Signer flow (unified bridge)
- * const txHash = await redeemToken({
- *   signer: evmSigner,
- *   account: '0x...',
- *   amount: '1.5',
- *   btcAddress: 'bc1q...',
- *   chainId: ChainId.avalancheFuji,
- *   env: Env.testnet,
- *   tokenIn: Token.BTCb,
- * });
- * ```
- */
-export async function redeemToken(params: RedeemTokenParams): Promise<Hex> {
-  const {
-    account: accountAddress,
-    amount: amountRaw,
-    btcAddress,
-    chainId,
-    env,
-    rpcUrl,
-    tokenIn = Token.LBTC,
-    tokenOut,
-  } = params;
-  const flow = AVAILABLE_FLOWS.find(
-    af => af.tokenIn === tokenIn && af.tokenOut === tokenOut,
-  );
-  if (!flow) {
-    throw new UnsupportedTokenFlow(tokenIn, tokenOut || 'BTC', chainId, env);
-  }
-
-  const publicClient = makePublicClient({ chainId, rpcUrl, env });
-
-  // Create wallet client only for provider flow
-  const walletClient = isProviderFlow(params)
-    ? makeWalletClient({ provider: params.provider, chainId })
-    : undefined;
-
-  const tokenInContractInfo = await getTokenContractInfo(
-    tokenIn,
-    chainId,
-    env,
-    AddressKind.Token, // get the token contract, not adapter
-  );
-  const IN = await retrieveTokenProperties(publicClient, tokenInContractInfo);
-  if (!IN) {
-    throw new Error(
-      `Could not retrieve the properties of ${tokenIn} on ${chainId}`,
-    );
-  }
-
-  const amount = toBaseDenomination(amountRaw, IN.decimals);
-
-  const tokenInBalanceRaw = await publicClient.readContract({
-    address: IN.address,
-    abi: IN.abi as typeof erc20Abi,
-    functionName: 'balanceOf',
-    args: [accountAddress],
-  });
-  const tokenInBalance = fromBaseDenomination(tokenInBalanceRaw, IN.decimals);
-  if (amount.isGreaterThan(tokenInBalanceRaw)) {
-    throw new Error(
-      `Unable to redeem ${String(amountRaw)} ${IN.symbol} because the amount exceeds the account's balance of ${tokenInBalance.toString()} ${IN.symbol}`,
-    );
-  }
-
-  // -> BTC
-  if (!tokenOut) {
-    if (!btcAddress) {
-      throw new Error('Missing parameter: `btcAddress`.');
-    }
-    const outputScript = getOutputScript(btcAddress, env);
-
-    // The redemption of BTC.b -> BTC on Avalanche requires extra steps
-    if (
-      tokenIn === Token.BTCb &&
-      (chainId === ChainId.avalanche || chainId === ChainId.avalancheFuji)
-    ) {
-      // 0. `IN` is a token contract (BTC.b)
-      // 1. Get the adapter and asset route contracts
-      const adapter = await getTokenContractInfo(
-        tokenIn,
-        chainId,
-        env,
-        AddressKind.Adapter,
-      );
-      const assetRouterContractAddress = (await publicClient.readContract({
-        address: adapter.address,
-        abi: adapter.abi,
-        functionName: 'getAssetRouter',
-      })) as Address;
-
-      // 2. Check allowance
-      const allowance = await publicClient.readContract({
-        address: IN.address,
-        abi: IN.abi,
-        functionName: 'allowance',
-        args: [accountAddress, adapter.address],
-      });
-
-      if (amount.isGreaterThan(allowance)) {
-        const { txHash } = await executeContractTransaction({
-          params,
-          publicClient,
-          walletClient,
-          simulateArgs: {
-            address: IN.address,
-            abi: IN.abi,
-            account: accountAddress as `0x${string}` | undefined,
-            functionName: 'approve',
-            args: [adapter.address, toBigInt(amount)],
-          },
-          operation: 'BTC.b approval',
-        });
-
-        const receipt = await waitForTransactionReceipt(
-          publicClient,
-          txHash,
-          'BTC.b approval',
-        );
-
-        console.info(
-          `Approved adapter (${adapter.address}) for ${new BigNumber(amountRaw).toString()} ${IN.symbol}`,
-          receipt.transactionHash,
-          receipt.status,
-        );
-      }
-
-      // 3. Run `redeemForBtc` on AssetRouter
-      const { txHash } = await executeContractTransaction({
-        params,
-        publicClient,
-        walletClient,
-        simulateArgs: {
-          address: assetRouterContractAddress,
-          abi: ASSET_ROUTER_ABI,
-          account: accountAddress as `0x${string}` | undefined,
-          functionName: 'redeemForBtc',
-          args: [
-            accountAddress,
-            adapter.address,
-            outputScript,
-            toBigInt(amount),
-          ],
-        },
-        operation: 'BTC.b redeemForBtc',
-      });
-
-      return txHash;
-    }
-
-    // 0. IN is BTC.b token contract.
-    const callData = {
-      abi: IN.abi,
-      address: IN.address,
-      account: accountAddress,
-      chain: CHAIN_ID_TO_VIEM_CHAIN_MAP[chainId],
-      functionName:
-        isUpgradedAbi(IN.abi) || tokenIn === Token.BTCb
-          ? 'redeemForBtc' // upgraded
-          : 'redeem', // legacy
-      args: [outputScript, toBigInt(amount)],
-    } as const;
-
-    const gasEstimationData = isKatanaChain(chainId)
-      ? await estimateGasFees(publicClient, callData, parseGwei('1'))
-      : {};
-
-    const { txHash } = await executeContractTransaction({
-      params,
-      publicClient,
-      walletClient,
-      simulateArgs: {
-        ...callData,
-        account: accountAddress as `0x${string}` | undefined,
-        ...gasEstimationData,
-      },
-      operation: `${tokenIn} redeem to BTC`,
-    });
-
-    return txHash;
-  }
-
-  // -> tokenOut
-  if (!isUpgradedAbi(IN.abi)) {
-    throw new Error(
-      `The ${tokenIn} contract (${IN.address}) doesn't support redemptions to ${tokenOut}.`,
-    );
-  }
-
-  const callData = {
-    abi: IN.abi,
-    address: IN.address,
-    account: accountAddress,
-    chain: CHAIN_ID_TO_VIEM_CHAIN_MAP[chainId],
-    functionName: 'redeem',
-    args: [toBigInt(amount)],
-  } as const;
-
-  const gasEstimationData = isKatanaChain(chainId)
-    ? await estimateGasFees(publicClient, callData, parseGwei('1'))
-    : {};
-
-  const { txHash } = await executeContractTransaction({
-    params,
-    publicClient,
-    walletClient,
-    simulateArgs: {
-      ...callData,
-      account: accountAddress as `0x${string}` | undefined,
-      ...gasEstimationData,
-    },
-    operation: `${tokenIn} redeem to ${tokenOut}`,
-  });
-
-  return txHash;
-}
-
-/**
- * Convenience wrapper around {@link redeemToken} for redeeming **LBTC → BTC**.
- *
- * @remarks
- * This is a helper for the common "unstake LBTC" flow.
- * For more flexible redemptions (e.g. LBTC → BTCK), use {@link redeemToken} directly.
- *
- * Supports both provider and signer flows.
- *
- * @param params - See {@link IUnstakeLBTCParams}.
- * @returns Transaction hash of the redemption transaction.
- *
- * @example
- * ```ts
- * // Provider flow
- * const txHash = await unstakeLBTC({
- *   provider,
- *   account: '0x...',
- *   btcAddress: 'bc1q...',
- *   amount: '1.5',
- *   chainId: ChainId.ethereum,
- *   env: Env.prod,
- * });
- *
- * // Signer flow
- * const txHash = await unstakeLBTC({
- *   signer: evmSigner,
- *   account: '0x...',
- *   btcAddress: 'bc1q...',
- *   amount: '1.5',
- *   chainId: ChainId.ethereum,
- *   env: Env.prod,
- * });
- * ```
- */
-export async function unstakeLBTC(params: IUnstakeLBTCParams): Promise<Hex> {
-  return redeemToken({
-    ...params,
-    tokenIn: Token.LBTC,
-    tokenOut: undefined,
-  });
-}

package/src/contracts/abis/index.ts

@@ -1,29 +0,0 @@
-/**
- * Contract ABIs for interacting with Lombard smart contracts.
- *
- * These ABIs are bundled with the SDK (not in S3) because:
- * - They're code dependencies that generate TypeScript types
- * - They're versioned with the SDK (contract upgrades = new SDK release)
- * - They rarely change independently of code changes
- *
- * For asset addresses and metadata, see `core/assets/` which can be
- * hosted in S3 for dynamic updates without SDK releases.
- */
-
-// Legacy LBTC contract ABI (pre-upgrade)
-export { LBTC_ABI } from '../../tokens/abi/LBTC_ABI';
-
-// Upgraded LBTC contract ABI (stLBTC with AssetRouter support)
-export { default as STLBTC_ABI } from '../../tokens/abi/STLBTC_ABI';
-
-// Native LBTC ABI (for cross-chain LBTC variants like BTCb on non-Avalanche chains)
-export { default as NATIVE_LBTC_ABI } from '../../tokens/abi/NATIVE_LBTC_ABI';
-
-// BTCK ABI (legacy Katana native LBTC)
-export { default as BTCK_ABI } from '../../tokens/abi/BTCK_ABI';
-
-// Bridge Token Adapter ABI (for BTC.b on Avalanche)
-export { default as BRIDGE_TOKEN_ADAPTER_ABI } from '../../tokens/abi/BRIDGE_TOKEN_ADAPTER_ABI';
-
-// Asset Router ABI (for MARS architecture deposits/redeems)
-export { default as ASSET_ROUTER_ABI } from '../../tokens/abi/ASSET_ROUTER_ABI';

package/src/contracts/index.ts

@@ -1,63 +0,0 @@
-/**
- * Contract module for the Lombard SDK.
- *
- * This module provides everything needed to interact with Lombard smart contracts:
- * - ABIs for all supported contracts
- * - Types for contract interactions
- * - Utilities for determining correct ABIs (handling upgrades, etc.)
- *
- * **Architecture:**
- *
- * The contracts module is separate from the asset catalog (`core/assets/`):
- * - Asset catalog: "What assets exist and where?" (addresses, decimals) - S3-able
- * - Contracts module: "How do I talk to them?" (ABIs, contract types) - bundled
- *
- * **Why ABIs are bundled (not in S3):**
- * - They're code dependencies that generate TypeScript types
- * - Contract upgrades require SDK updates anyway
- * - They're versioned with the SDK
- *
- * @example
- * ```typescript
- * import { getContractInfo, AssetId, Chain } from '@lombard.finance/sdk';
- *
- * // Get contract info (handles upgrade detection)
- * const info = await getContractInfo(AssetId.LBTC, ChainId.ethereum, Env.prod);
- *
- * // Create typed contract
- * const contract = getContract({
- *   address: info.address,
- *   abi: info.abi,
- *   client: publicClient,
- * });
- *
- * // Interact with fully typed methods
- * const balance = await contract.read.balanceOf([userAddress]);
- * ```
- *
- * @module contracts
- */
-
-// ABIs
-export * from './abis';
-
-// Types
-export {
-  AddressKind,
-  type BridgeTokenAddresses,
-  type ContractAbiMap,
-  type ContractInfo,
-  ContractType,
-  ContractVersion,
-  type GetContractInfoOptions,
-} from './types';
-
-// Utilities
-export {
-  getBtckAbi,
-  getContractInfo,
-  getContractType,
-  getLbtcAbi,
-  isUpgradedAbi,
-  isUpgradedContract,
-} from './utils';