@lombard.finance/sdk 3.7.4 → 4.0.0

package/src/contracts/abis/index.ts

@@ -0,0 +1,29 @@
+/**
+ * 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

@@ -0,0 +1,63 @@
+/**
+ * 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';

package/src/contracts/types.ts

@@ -0,0 +1,143 @@
+/**
+ * Contract-related types for the Lombard SDK.
+ *
+ * These types define how to interact with smart contracts,
+ * separate from the asset catalog which defines what assets exist where.
+ */
+
+import type { Abi } from 'viem';
+
+import type { ChainId } from '../common/chains';
+import type {
+  ASSET_ROUTER_ABI,
+  BRIDGE_TOKEN_ADAPTER_ABI,
+  BTCK_ABI,
+  LBTC_ABI,
+  NATIVE_LBTC_ABI,
+  STLBTC_ABI,
+} from './abis';
+
+/**
+ * Address kinds for tokens that have multiple contract addresses.
+ *
+ * **BTC.b Integration Architecture:**
+ *
+ * BTC.b on Avalanche uses a dual-contract architecture with both a token contract
+ * and an adapter contract serving different purposes:
+ *
+ * **When to use Token vs Adapter:**
+ *
+ * - **Token** (`AddressKind.Token`):
+ *   - Use for EIP-2612 `permit()` signatures (Stake and Bake)
+ *   - Use for querying token balance, symbol, decimals
+ *   - Use for standard ERC20 operations (allowance checks, balance queries)
+ *   - This is the actual BTC.b ERC20 token contract
+ *
+ * - **Adapter** (`AddressKind.Adapter`):
+ *   - Use for burn/mint/transfer operations via BridgeTokenAdapter
+ *   - Use for bridge deposit/withdrawal operations
+ *   - Use as spender address when approving tokens for bridge operations
+ *   - This adapter serves as an intermediary between BridgeToken and both AssetRouter and Bridge
+ *
+ * **Important Notes:**
+ *
+ * 1. **Permit Signatures**: Always use `AddressKind.Token` as the `verifyingContract` in
+ *    EIP-2612 permit signatures. The token contract implements the `permit()` function,
+ *    not the adapter.
+ *
+ * 2. **Approvals**: For bridge and redemption operations, users must grant allowance to
+ *    the **BridgeTokenAdapter** address, not the vault or bridge contract.
+ *
+ * 3. **Deposit Address**: For Ledger integration, the token address includes the adapter
+ *    address when tweaking deposit addresses.
+ */
+export enum AddressKind {
+  /**
+   * The bridge adapter contract address (BridgeTokenAdapter).
+   * Used for burn/mint/transfer operations and as the spender for bridge approvals.
+   */
+  Adapter = 'adapter',
+
+  /**
+   * The token contract address (standard ERC20).
+   * Used for permit signatures, balance queries, and standard ERC20 operations.
+   */
+  Token = 'token',
+}
+
+/**
+ * Address structure for tokens with both token and adapter addresses.
+ * Currently only used by BTC.b on Avalanche chains.
+ */
+export interface BridgeTokenAddresses {
+  /** The bridge adapter contract address (BridgeTokenAdapter) */
+  [AddressKind.Adapter]: `0x${string}`;
+  /** The token contract address (standard ERC20) */
+  [AddressKind.Token]: `0x${string}`;
+}
+
+/**
+ * Contract version indicating which ABI to use.
+ */
+export enum ContractVersion {
+  /** Legacy LBTC contract (pre-AssetRouter) */
+  Legacy = 'legacy',
+  /** Upgraded contract with AssetRouter support */
+  Upgraded = 'upgraded',
+}
+
+/**
+ * Contract types supported by the SDK.
+ */
+export enum ContractType {
+  /** LBTC token contract */
+  LBTC = 'lbtc',
+  /** Native LBTC variant (BTCb on non-Avalanche chains) */
+  NativeLBTC = 'native_lbtc',
+  /** BTCK legacy contract */
+  BTCK = 'btck',
+  /** Bridge Token Adapter (BTCb on Avalanche) */
+  BridgeTokenAdapter = 'bridge_token_adapter',
+  /** Asset Router contract */
+  AssetRouter = 'asset_router',
+  /** Standard ERC20 */
+  ERC20 = 'erc20',
+}
+
+/**
+ * ABI type mapping for contract types.
+ */
+export type ContractAbiMap = {
+  [ContractType.LBTC]: typeof LBTC_ABI | typeof STLBTC_ABI;
+  [ContractType.NativeLBTC]: typeof NATIVE_LBTC_ABI;
+  [ContractType.BTCK]: typeof BTCK_ABI | typeof NATIVE_LBTC_ABI;
+  [ContractType.BridgeTokenAdapter]: typeof BRIDGE_TOKEN_ADAPTER_ABI;
+  [ContractType.AssetRouter]: typeof ASSET_ROUTER_ABI;
+  [ContractType.ERC20]: Abi;
+};
+
+/**
+ * Information about a contract including its ABI and address.
+ */
+export interface ContractInfo<T extends ContractType = ContractType> {
+  /** The contract ABI */
+  abi: ContractAbiMap[T];
+  /** The contract address */
+  address: `0x${string}`;
+  /** The chain ID */
+  chainId: ChainId;
+  /** The contract type */
+  type: T;
+  /** The contract version (for upgradeable contracts) */
+  version?: ContractVersion;
+}
+
+/**
+ * Options for getting contract information.
+ */
+export interface GetContractInfoOptions {
+  /** Which address to use for dual-address tokens (default: Token) */
+  addressKind?: AddressKind;
+  /** Custom RPC URL for upgrade detection */
+  rpcUrl?: string;
+}

package/src/contracts/utils.ts

@@ -0,0 +1,288 @@
+/**
+ * Contract utility functions for the Lombard SDK.
+ *
+ * These utilities help determine which ABI to use for a given contract,
+ * handle contract upgrades, and provide typed contract information.
+ */
+
+import { DEFAULT_ENV, Env } from '@lombard.finance/sdk-common';
+import { type Abi, erc20Abi, zeroAddress } from 'viem';
+
+import { makePublicClient } from '../clients/public-client';
+import { ChainId } from '../common/chains';
+import {
+  AssetId,
+  evmChainIdToChain,
+  getAssetAddress,
+  getBridgeAdapter,
+} from '../core';
+import {
+  ASSET_ROUTER_ABI,
+  BRIDGE_TOKEN_ADAPTER_ABI,
+  BTCK_ABI,
+  LBTC_ABI,
+  NATIVE_LBTC_ABI,
+  STLBTC_ABI,
+} from './abis';
+import {
+  AddressKind,
+  type ContractInfo,
+  ContractType,
+  ContractVersion,
+  type GetContractInfoOptions,
+} from './types';
+
+/**
+ * ABI fragment for detecting upgraded contracts.
+ * Upgraded contracts have a `getAssetRouter` function.
+ */
+const UPGRADE_DETECTION_ABI = [
+  {
+    inputs: [],
+    name: 'getAssetRouter',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+] as const;
+
+/**
+ * Checks if a contract has been upgraded to support AssetRouter.
+ *
+ * Upgraded contracts have a `getAssetRouter()` function that returns
+ * a non-zero address when the AssetRouter is configured.
+ *
+ * @param address - Contract address to check
+ * @param chainId - Chain ID
+ * @param env - Environment (default: DEFAULT_ENV)
+ * @param rpcUrl - Optional custom RPC URL
+ * @returns true if contract is upgraded, false otherwise
+ */
+export async function isUpgradedContract(
+  address: `0x${string}`,
+  chainId: ChainId,
+  env: Env = DEFAULT_ENV,
+  rpcUrl?: string,
+): Promise<boolean> {
+  const publicClient = makePublicClient({ chainId, rpcUrl, env });
+
+  try {
+    const assetRouter = await publicClient.readContract({
+      abi: UPGRADE_DETECTION_ABI,
+      address,
+      functionName: 'getAssetRouter',
+    });
+    return assetRouter !== zeroAddress;
+  } catch {
+    // Contract doesn't have getAssetRouter function = not upgraded
+    return false;
+  }
+}
+
+/**
+ * Type guard to check if an ABI is an upgraded contract ABI.
+ */
+export function isUpgradedAbi(
+  abi: unknown,
+): abi is typeof STLBTC_ABI | typeof NATIVE_LBTC_ABI {
+  const hasAssetRouter = (abi as Abi).find(
+    a => a.type === 'function' && a.name === 'getAssetRouter',
+  );
+  return hasAssetRouter != null;
+}
+
+/**
+ * Gets the appropriate ABI for an LBTC contract based on upgrade status.
+ *
+ * @param address - Contract address
+ * @param chainId - Chain ID
+ * @param env - Environment
+ * @param rpcUrl - Optional custom RPC URL
+ * @returns The appropriate ABI and version
+ */
+export async function getLbtcAbi(
+  address: `0x${string}`,
+  chainId: ChainId,
+  env: Env = DEFAULT_ENV,
+  rpcUrl?: string,
+): Promise<{
+  abi: typeof LBTC_ABI | typeof STLBTC_ABI;
+  version: ContractVersion;
+}> {
+  const upgraded = await isUpgradedContract(address, chainId, env, rpcUrl);
+  return {
+    abi: upgraded ? STLBTC_ABI : LBTC_ABI,
+    version: upgraded ? ContractVersion.Upgraded : ContractVersion.Legacy,
+  };
+}
+
+/**
+ * Gets the appropriate ABI for a BTCK contract based on upgrade status.
+ *
+ * @param address - Contract address
+ * @param chainId - Chain ID
+ * @param env - Environment
+ * @param rpcUrl - Optional custom RPC URL
+ * @returns The appropriate ABI and version
+ */
+export async function getBtckAbi(
+  address: `0x${string}`,
+  chainId: ChainId,
+  env: Env = DEFAULT_ENV,
+  rpcUrl?: string,
+): Promise<{
+  abi: typeof BTCK_ABI | typeof NATIVE_LBTC_ABI;
+  version: ContractVersion;
+}> {
+  const upgraded = await isUpgradedContract(address, chainId, env, rpcUrl);
+  return {
+    abi: upgraded ? NATIVE_LBTC_ABI : BTCK_ABI,
+    version: upgraded ? ContractVersion.Upgraded : ContractVersion.Legacy,
+  };
+}
+
+/**
+ * Determines the contract type for an asset on a specific chain.
+ *
+ * @param assetId - Asset identifier
+ * @param chainId - Chain ID
+ * @param addressKind - Which address to use for dual-address tokens
+ * @returns Contract type
+ */
+export function getContractType(
+  assetId: AssetId,
+  chainId: ChainId,
+  addressKind: AddressKind = AddressKind.Token,
+): ContractType {
+  switch (assetId) {
+    case AssetId.LBTC:
+      return ContractType.LBTC;
+
+    case AssetId.BTCK:
+      return ContractType.BTCK;
+
+    case AssetId.BTCb:
+      // On Avalanche chains, BTCb uses dual-contract architecture
+      if (chainId === ChainId.avalanche || chainId === ChainId.avalancheFuji) {
+        return addressKind === AddressKind.Adapter
+          ? ContractType.BridgeTokenAdapter
+          : ContractType.ERC20;
+      }
+      // On other chains, BTCb is NativeLBTC
+      return ContractType.NativeLBTC;
+
+    default:
+      // Supporting tokens (cbBTC, wBTC, etc.) use standard ERC20
+      return ContractType.ERC20;
+  }
+}
+
+/**
+ * Gets contract information including ABI and address for an asset.
+ *
+ * This is the main entry point for getting everything needed to interact
+ * with a contract. It handles:
+ * - Determining the correct contract type
+ * - Detecting contract upgrades
+ * - Returning the appropriate ABI
+ *
+ * @param assetId - Asset identifier
+ * @param chainId - Chain ID
+ * @param env - Environment (default: DEFAULT_ENV)
+ * @param options - Additional options
+ * @returns Contract information including ABI and address
+ *
+ * @example
+ * ```typescript
+ * // Get LBTC contract info
+ * const info = await getContractInfo(AssetId.LBTC, ChainId.ethereum, Env.prod);
+ * const contract = getContract({ ...info, client });
+ * const balance = await contract.read.balanceOf([userAddress]);
+ *
+ * // Get BTCb adapter on Avalanche
+ * const adapterInfo = await getContractInfo(
+ *   AssetId.BTCb,
+ *   ChainId.avalanche,
+ *   Env.prod,
+ *   { addressKind: AddressKind.Adapter }
+ * );
+ * ```
+ */
+export async function getContractInfo(
+  assetId: AssetId,
+  chainId: ChainId,
+  env: Env = DEFAULT_ENV,
+  options: GetContractInfoOptions = {},
+): Promise<ContractInfo> {
+  const { addressKind = AddressKind.Token, rpcUrl } = options;
+
+  // Get address from the asset catalog
+  // For Adapter kind, use getBridgeAdapter; otherwise use getAssetAddress
+  // Convert ChainId (numeric) to Chain (CAIP-2 string like "eip155:1")
+  const chain = evmChainIdToChain(chainId);
+  const addressStr =
+    addressKind === AddressKind.Adapter
+      ? getBridgeAdapter(assetId, env, chain)
+      : getAssetAddress(assetId, env, chain);
+
+  if (!addressStr) {
+    throw new Error(
+      `No address found for ${assetId} on chain ${chainId} in ${env} environment (addressKind: ${addressKind})`,
+    );
+  }
+
+  // Cast to 0x-prefixed address type
+  const address = addressStr as `0x${string}`;
+
+  const contractType = getContractType(assetId, chainId, addressKind);
+
+  // Determine ABI based on contract type and upgrade status
+  let abi: Abi;
+  let version: ContractVersion | undefined;
+
+  switch (contractType) {
+    case ContractType.LBTC: {
+      const result = await getLbtcAbi(address, chainId, env, rpcUrl);
+      abi = result.abi as Abi;
+      version = result.version;
+      break;
+    }
+
+    case ContractType.BTCK: {
+      const result = await getBtckAbi(address, chainId, env, rpcUrl);
+      abi = result.abi as Abi;
+      version = result.version;
+      break;
+    }
+
+    case ContractType.NativeLBTC:
+      abi = NATIVE_LBTC_ABI as Abi;
+      break;
+
+    case ContractType.BridgeTokenAdapter:
+      abi = BRIDGE_TOKEN_ADAPTER_ABI as Abi;
+      break;
+    default:
+      abi = erc20Abi;
+      break;
+  }
+
+  return {
+    abi: abi as ContractInfo['abi'],
+    address,
+    chainId,
+    type: contractType,
+    version,
+  };
+}
+
+/**
+ * Gets the ABI for an Asset Router contract.
+ * Asset Router handles minting/redemption in the MARS architecture.
+ *
+ * @param assetId - Asset identifier (to get the associated router)
+ * @param chainId - Chain ID
+ * @param env - Environment
+ * @returns Asset Router ABI
+ */
+export { ASSET_ROUTER_ABI };