@lombard.finance/sdk-solana 1.2.2 → 2.0.0

package/src/web3Sdk/getTokenFeeConfig/getTokenFeeConfig.stories.tsx

@@ -0,0 +1,166 @@
+import { Env } from '@lombard.finance/sdk-common';
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { envToNetwork, getConfig } from '../../const/getConfig';
+import {
+  Button,
+  CodeBlock,
+  ErrorDisplay,
+} from '../../stories/components';
+import { functionType } from '../../stories/decorators/function-type';
+import useQuery from '../../stories/hooks/useQuery';
+import {
+  getMinRedeemAmountSolana,
+  getMinRedeemAmountWithFeeSolana,
+  getMintingFeeSolana,
+  getRedeemFeeSolana,
+  getTokenFeeConfig,
+} from './getTokenFeeConfig';
+
+type TokenChoice = 'LBTC' | 'BTC.b';
+
+interface StoryArgs {
+  environment: Env;
+  token: TokenChoice;
+}
+
+function resolveTokenMint(
+  token: TokenChoice,
+  env: Env,
+): string | undefined {
+  const config = getConfig(env);
+  return token === 'LBTC'
+    ? config.lbtcTokenMint
+    : config.btcbTokenMint ?? undefined;
+}
+
+export function StoryView({ environment, token }: StoryArgs) {
+  const network = envToNetwork[environment];
+  const tokenMint = resolveTokenMint(token, environment);
+
+  const params = { network, env: environment, tokenMint };
+
+  const configQuery = useQuery(
+    () => getTokenFeeConfig(params),
+    [environment, token],
+    false,
+  );
+  const redeemFeeQuery = useQuery(
+    () => getRedeemFeeSolana(params),
+    [environment, token],
+    false,
+  );
+  const mintingFeeQuery = useQuery(
+    () => getMintingFeeSolana(params),
+    [environment, token],
+    false,
+  );
+  const minRedeemQuery = useQuery(
+    () => getMinRedeemAmountSolana(params),
+    [environment, token],
+    false,
+  );
+  const minRedeemWithFeeQuery = useQuery(
+    () => getMinRedeemAmountWithFeeSolana(params),
+    [environment, token],
+    false,
+  );
+
+  const isLoading =
+    configQuery.isLoading ||
+    redeemFeeQuery.isLoading ||
+    mintingFeeQuery.isLoading ||
+    minRedeemQuery.isLoading ||
+    minRedeemWithFeeQuery.isLoading;
+
+  const fetchAll = () => {
+    configQuery.refetch();
+    redeemFeeQuery.refetch();
+    mintingFeeQuery.refetch();
+    minRedeemQuery.refetch();
+    minRedeemWithFeeQuery.refetch();
+  };
+
+  const error =
+    configQuery.error ||
+    redeemFeeQuery.error ||
+    mintingFeeQuery.error ||
+    minRedeemQuery.error ||
+    minRedeemWithFeeQuery.error;
+
+  const summary = configQuery.data
+    ? {
+        redeemFee: configQuery.data.redeemFee.toFormat(),
+        redeemForBtcMinAmount:
+          configQuery.data.redeemForBtcMinAmount.toFormat(),
+        maxMintCommission: configQuery.data.maxMintCommission.toFormat(),
+        toNativeCommission:
+          configQuery.data.toNativeCommission.toFormat(),
+        'getRedeemFeeSolana (toNative + redeem)':
+          redeemFeeQuery.data?.toFormat(),
+        'getMintingFeeSolana': mintingFeeQuery.data?.toFormat(),
+        'getMinRedeemAmountSolana': minRedeemQuery.data?.toFormat(),
+        'getMinRedeemAmountWithFeeSolana':
+          minRedeemWithFeeQuery.data?.toFormat(),
+      }
+    : undefined;
+
+  return (
+    <div>
+      <p>
+        <strong>Network:</strong> {network} | <strong>Token:</strong>{' '}
+        {token}
+        {tokenMint ? ` (${tokenMint})` : ' — not configured'}
+      </p>
+
+      <Button
+        primary
+        size="large"
+        onClick={fetchAll}
+        isLoading={isLoading}
+        actionName={getTokenFeeConfig.name}
+      />
+
+      {summary && <CodeBlock text={summary} />}
+      {error && <ErrorDisplay error={error} title="Error" />}
+    </div>
+  );
+}
+
+const meta: Meta<typeof StoryView> = {
+  title: 'read/getTokenFeeConfig (Asset Router)',
+  component: StoryView,
+  tags: ['autodocs'],
+  decorators: [functionType('read')],
+  parameters: {
+    docs: {
+      description: {
+        component: `Reads the Asset Router \`TokenConfig\` account for a given token mint on Solana.
+
+Returns protocol fee parameters: **redeem fee**, **min redeem amount**, **max mint commission**, and **native commission**.
+
+Also demonstrates the convenience wrappers: \`getRedeemFeeSolana\`, \`getMintingFeeSolana\`, \`getMinRedeemAmountSolana\`, \`getMinRedeemAmountWithFeeSolana\`.`,
+      },
+    },
+  },
+  args: {
+    environment: Env.stage,
+    token: 'LBTC',
+  },
+  argTypes: {
+    environment: {
+      control: { type: 'select' },
+      options: Object.values(Env),
+    },
+    token: {
+      control: { type: 'select' },
+      options: ['LBTC', 'BTC.b'] satisfies TokenChoice[],
+    },
+  },
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Stage: Story = {
+  args: { environment: Env.stage, token: 'LBTC' },
+};

package/src/web3Sdk/getTokenFeeConfig/getTokenFeeConfig.test.ts

@@ -0,0 +1,224 @@
+import { PublicKey } from '@solana/web3.js';
+import BigNumber from 'bignumber.js';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { IConfig } from '../../const/getConfig';
+import { SolanaNetwork } from '../../types';
+import { ErrorCode, SolanaSdkError } from '../../utils';
+
+// ── Constants ──
+
+const MOCK_LBTC_MINT = 'LBTCojyVJ63rsEED2DLEGWMzSxWJyQynXE91LMLgV1J';
+const MOCK_BTCB_MINT = 'BTCB3ripBAut19jM8kDPVbJHb2ZdR2GcZvGZkCmFPtV8';
+const MOCK_ASSET_ROUTER = 'LomVyJDZ91jeVbNnTupJXKJTQFakJVMc87CmwDHYt95';
+
+const fullConfig: IConfig = {
+  lbtcTokenMint: MOCK_LBTC_MINT,
+  btcbTokenMint: MOCK_BTCB_MINT,
+  assetRouter: MOCK_ASSET_ROUTER,
+  mailbox: 'LomJw912MoUd7iiAesTQAgz1paLcTqi6ndG3w3pnKH9',
+  solanaRoutingChainId:
+    '0259db5080fc2c6d3bcf7ca90712d3c2e5e6c28f27f0dfbb9953bdb0894c03ab',
+  bitcoinRoutingChainId:
+    'ff000008819873e925422c1ff0f99f7cc9bbb232af63a077a480a3633bee1ef6',
+  ledgerChainId:
+    '031f51c4e4cc1dae1c752d2f8fe2ae045da668a13f2e47a465964d630f5ed22e',
+  lbtcProgramId: 'HEY7PCJe3GB27UWdopuYb1xDbB5SNtTcYPxRjntvfBSA',
+  treasuryAddress: 'ByHNGi4zPJw5StyWZoLQJ9n2wT12oupJF2pTSNKMnnAZ',
+  bascule: null,
+  basculeData: null,
+  admin: '6MKjyWZnkSMitJYAixvJzqhJiVsjTA3hYHX8aP9qNioj',
+  lzOftAdapter: 'AEFwQgaSNhQcZhAcGZGM9iTyGML3fsJC2aBvYmzV81FE',
+  lzOftStore: '3SG3oyrG3KSvJ9bbxPDu7ZXEe5o1TW1QkgudkKvK6FK4',
+  lzMultisig: 'GfYV1f1bR9vy41mSyQ8quxYbds121kijSBj5A3nG8oDQ',
+  lzEscrow: 'GRq2yasTvWWPPqSwxCZvqfCTfDhP3MswDH4nW2v6F5To',
+  consortium: null,
+  ratioOracle: null,
+  bridge: null,
+  lombardTokenPool: null,
+};
+
+// ── Helpers ──
+
+/**
+ * Build a fake TokenConfig account buffer.
+ *
+ * Layout (Anchor): discriminator(8) + redeem_fee(u64) +
+ *   redeem_for_btc_min_amount(u64) + max_mint_commission(u64) +
+ *   to_native_commission(u64) + ledger_redeem_handler([u8; 32])
+ */
+function buildTokenConfigData(fields: {
+  redeemFee: bigint;
+  redeemForBtcMinAmount: bigint;
+  maxMintCommission: bigint;
+  toNativeCommission: bigint;
+}): Buffer {
+  const buf = Buffer.alloc(8 + 8 + 8 + 8 + 8 + 32, 0);
+  buf.writeBigUInt64LE(fields.redeemFee, 8);
+  buf.writeBigUInt64LE(fields.redeemForBtcMinAmount, 16);
+  buf.writeBigUInt64LE(fields.maxMintCommission, 24);
+  buf.writeBigUInt64LE(fields.toNativeCommission, 32);
+  return buf;
+}
+
+// ── Mocks ──
+
+const mockConnection = {
+  getAccountInfo: vi.fn(),
+};
+
+vi.mock('../../const/getConfig', () => ({
+  DEFAULT_ENV: 'dev' as const,
+  getConfig: vi.fn(() => fullConfig),
+}));
+
+vi.mock('../../const/rpcUrls', () => ({
+  getConnection: vi.fn(() => mockConnection),
+}));
+
+// ── Tests ──
+
+describe('getTokenFeeConfig', () => {
+  let getTokenFeeConfigFn: typeof import('./getTokenFeeConfig').getTokenFeeConfig;
+  let getRedeemFeeSolanaFn: typeof import('./getTokenFeeConfig').getRedeemFeeSolana;
+  let getMintingFeeSolanaFn: typeof import('./getTokenFeeConfig').getMintingFeeSolana;
+  let getMinRedeemAmountSolanaFn: typeof import('./getTokenFeeConfig').getMinRedeemAmountSolana;
+  let getMinRedeemAmountWithFeeSolanaFn: typeof import('./getTokenFeeConfig').getMinRedeemAmountWithFeeSolana;
+
+  const defaultFields = {
+    redeemFee: 1000n,
+    redeemForBtcMinAmount: 2000n,
+    maxMintCommission: 500n,
+    toNativeCommission: 300n,
+  };
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+
+    mockConnection.getAccountInfo.mockResolvedValue({
+      data: buildTokenConfigData(defaultFields),
+    });
+
+    const mod = await import('./getTokenFeeConfig');
+    getTokenFeeConfigFn = mod.getTokenFeeConfig;
+    getRedeemFeeSolanaFn = mod.getRedeemFeeSolana;
+    getMintingFeeSolanaFn = mod.getMintingFeeSolana;
+    getMinRedeemAmountSolanaFn = mod.getMinRedeemAmountSolana;
+    getMinRedeemAmountWithFeeSolanaFn = mod.getMinRedeemAmountWithFeeSolana;
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const baseParams = { network: SolanaNetwork.devnet };
+
+  // ── getTokenFeeConfig ──
+
+  it('should parse all token config fields correctly', async () => {
+    const result = await getTokenFeeConfigFn(baseParams);
+
+    expect(result.redeemFee).toEqual(new BigNumber('0.00001'));
+    expect(result.redeemForBtcMinAmount).toEqual(new BigNumber('0.00002'));
+    expect(result.maxMintCommission).toEqual(new BigNumber('0.000005'));
+    expect(result.toNativeCommission).toEqual(new BigNumber('0.000003'));
+  });
+
+  it('should derive PDA from LBTC mint by default', async () => {
+    await getTokenFeeConfigFn(baseParams);
+
+    const mint = new PublicKey(MOCK_LBTC_MINT);
+    const assetRouter = new PublicKey(MOCK_ASSET_ROUTER);
+    const [expectedPDA] = PublicKey.findProgramAddressSync(
+      [Buffer.from('token_config'), mint.toBuffer()],
+      assetRouter,
+    );
+
+    expect(mockConnection.getAccountInfo).toHaveBeenCalledWith(expectedPDA);
+  });
+
+  it('should use custom tokenMint when provided', async () => {
+    await getTokenFeeConfigFn({ ...baseParams, tokenMint: MOCK_BTCB_MINT });
+
+    const mint = new PublicKey(MOCK_BTCB_MINT);
+    const assetRouter = new PublicKey(MOCK_ASSET_ROUTER);
+    const [expectedPDA] = PublicKey.findProgramAddressSync(
+      [Buffer.from('token_config'), mint.toBuffer()],
+      assetRouter,
+    );
+
+    expect(mockConnection.getAccountInfo).toHaveBeenCalledWith(expectedPDA);
+  });
+
+  it('should throw when Asset Router is not configured', async () => {
+    const { getConfig } = await import('../../const/getConfig');
+    vi.mocked(getConfig).mockReturnValueOnce({
+      ...fullConfig,
+      assetRouter: null,
+    });
+
+    await expect(getTokenFeeConfigFn(baseParams)).rejects.toThrow(
+      'Asset Router not configured',
+    );
+  });
+
+  it('should throw when account is not found', async () => {
+    mockConnection.getAccountInfo.mockResolvedValueOnce(null);
+
+    try {
+      await getTokenFeeConfigFn(baseParams);
+      expect.unreachable('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(SolanaSdkError);
+      expect((err as SolanaSdkError).code).toBe(ErrorCode.RPC_ERROR);
+    }
+  });
+
+  it('should throw when account data is too short', async () => {
+    mockConnection.getAccountInfo.mockResolvedValueOnce({
+      data: Buffer.alloc(10, 0),
+    });
+
+    try {
+      await getTokenFeeConfigFn(baseParams);
+      expect.unreachable('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(SolanaSdkError);
+      expect((err as SolanaSdkError).code).toBe(ErrorCode.RPC_ERROR);
+    }
+  });
+
+  it('should use env override when provided', async () => {
+    const { getConfig } = await import('../../const/getConfig');
+
+    await getTokenFeeConfigFn({ ...baseParams, env: 'stage' });
+
+    expect(getConfig).toHaveBeenCalledWith('stage');
+  });
+
+  // ── Convenience wrappers ──
+
+  it('getRedeemFeeSolana should return toNativeCommission + redeemFee', async () => {
+    const result = await getRedeemFeeSolanaFn(baseParams);
+    // 300 + 1000 = 1300 satoshi = 0.000013
+    expect(result).toEqual(new BigNumber('0.000013'));
+  });
+
+  it('getMintingFeeSolana should return maxMintCommission', async () => {
+    const result = await getMintingFeeSolanaFn(baseParams);
+    // 500 satoshi = 0.000005
+    expect(result).toEqual(new BigNumber('0.000005'));
+  });
+
+  it('getMinRedeemAmountSolana should return redeemForBtcMinAmount', async () => {
+    const result = await getMinRedeemAmountSolanaFn(baseParams);
+    // 2000 satoshi = 0.00002
+    expect(result).toEqual(new BigNumber('0.00002'));
+  });
+
+  it('getMinRedeemAmountWithFeeSolana should return total of all fees + min amount', async () => {
+    const result = await getMinRedeemAmountWithFeeSolanaFn(baseParams);
+    // 300 + 1000 + 2000 = 3300 satoshi = 0.000033
+    expect(result).toEqual(new BigNumber('0.000033'));
+  });
+});

package/src/web3Sdk/getTokenFeeConfig/getTokenFeeConfig.ts

@@ -0,0 +1,154 @@
+import { Env } from '@lombard.finance/sdk-common';
+import { PublicKey } from '@solana/web3.js';
+import BigNumber from 'bignumber.js';
+
+import { DEFAULT_ENV, getConfig } from '../../const/getConfig';
+import { getConnection } from '../../const/rpcUrls';
+import { SolanaNetwork } from '../../types';
+import { ErrorCode, SolanaSdkError } from '../../utils';
+
+const BTC_DECIMALS = 8;
+const SATOSHI_SCALE = new BigNumber(10).pow(BTC_DECIMALS);
+const ANCHOR_DISCRIMINATOR_SIZE = 8;
+
+/**
+ * Anchor account layout for Asset Router's `TokenConfig`:
+ *   discriminator (8) | redeem_fee (u64) | redeem_for_btc_min_amount (u64)
+ *   | max_mint_commission (u64) | to_native_commission (u64)
+ *   | ledger_redeem_handler ([u8; 32])
+ */
+const TOKEN_CONFIG_MIN_SIZE = ANCHOR_DISCRIMINATOR_SIZE + 8 + 8 + 8 + 8 + 32;
+
+function fromSatoshi(amount: bigint): BigNumber {
+  return new BigNumber(amount.toString()).dividedBy(SATOSHI_SCALE);
+}
+
+function readU64LE(buf: Buffer, offset: number): bigint {
+  return buf.readBigUInt64LE(offset);
+}
+
+export interface GetTokenFeeConfigParams {
+  /** SPL token mint address. Defaults to LBTC mint from config. */
+  tokenMint?: string;
+  network: SolanaNetwork;
+  env?: Env;
+  rpcUrl?: string;
+}
+
+export interface TokenFeeConfigResult {
+  redeemFee: BigNumber;
+  redeemForBtcMinAmount: BigNumber;
+  maxMintCommission: BigNumber;
+  toNativeCommission: BigNumber;
+}
+
+/**
+ * Fetches the Asset Router `TokenConfig` account for a given token mint.
+ *
+ * The account holds protocol fee parameters set by governance:
+ * redeem fee, min redeem amount, max mint commission, and native commission.
+ */
+export async function getTokenFeeConfig(
+  params: GetTokenFeeConfigParams,
+): Promise<TokenFeeConfigResult> {
+  const { network, env: envOverride, rpcUrl, tokenMint } = params;
+  const env = envOverride ?? DEFAULT_ENV;
+  const config = getConfig(env);
+
+  if (!config.assetRouter) {
+    throw new SolanaSdkError(
+      `Asset Router not configured for env: ${env}`,
+      ErrorCode.INVALID_PARAMS,
+    );
+  }
+
+  const mintAddress = tokenMint ?? config.lbtcTokenMint;
+  const mint = new PublicKey(mintAddress);
+  const assetRouterProgramId = new PublicKey(config.assetRouter);
+
+  const connection = getConnection(network, rpcUrl);
+
+  const [tokenConfigPDA] = PublicKey.findProgramAddressSync(
+    [Buffer.from('token_config'), mint.toBuffer()],
+    assetRouterProgramId,
+  );
+
+  try {
+    const accountInfo = await connection.getAccountInfo(tokenConfigPDA);
+
+    if (!accountInfo) {
+      throw new Error(
+        `TokenConfig account not found for mint ${mintAddress}`,
+      );
+    }
+
+    if (accountInfo.data.length < TOKEN_CONFIG_MIN_SIZE) {
+      throw new Error(
+        `TokenConfig account data too short: expected >= ${TOKEN_CONFIG_MIN_SIZE} bytes, got ${accountInfo.data.length}`,
+      );
+    }
+
+    const buf = accountInfo.data;
+    const off = ANCHOR_DISCRIMINATOR_SIZE;
+
+    return {
+      redeemFee: fromSatoshi(readU64LE(buf, off)),
+      redeemForBtcMinAmount: fromSatoshi(readU64LE(buf, off + 8)),
+      maxMintCommission: fromSatoshi(readU64LE(buf, off + 16)),
+      toNativeCommission: fromSatoshi(readU64LE(buf, off + 24)),
+    };
+  } catch (error) {
+    throw SolanaSdkError.wrap(
+      error,
+      ErrorCode.RPC_ERROR,
+      `Failed to fetch token config for mint ${mintAddress}`,
+    );
+  }
+}
+
+/**
+ * Total redeem fee for burning tokens back to BTC on Solana.
+ * Equivalent to EVM `getRedeemFee`: `toNativeCommission + redeemFee`.
+ */
+export async function getRedeemFeeSolana(
+  params: GetTokenFeeConfigParams,
+): Promise<BigNumber> {
+  const cfg = await getTokenFeeConfig(params);
+  return cfg.toNativeCommission.plus(cfg.redeemFee);
+}
+
+/**
+ * Max minting commission on Solana.
+ * Equivalent to EVM `getMintingFee`.
+ */
+export async function getMintingFeeSolana(
+  params: GetTokenFeeConfigParams,
+): Promise<BigNumber> {
+  const cfg = await getTokenFeeConfig(params);
+  return cfg.maxMintCommission;
+}
+
+/**
+ * Minimum redeem amount (excluding fee) on Solana.
+ * Equivalent to EVM `getMinRedeemAmount`.
+ */
+export async function getMinRedeemAmountSolana(
+  params: GetTokenFeeConfigParams,
+): Promise<BigNumber> {
+  const cfg = await getTokenFeeConfig(params);
+  return cfg.redeemForBtcMinAmount;
+}
+
+/**
+ * Minimum transfer amount the user must provide for a successful redemption.
+ * Equals `redeemFee + toNativeCommission + redeemForBtcMinAmount`.
+ * Equivalent to EVM `getMinRedeemAmountWithFee`.
+ */
+export async function getMinRedeemAmountWithFeeSolana(
+  params: GetTokenFeeConfigParams,
+): Promise<BigNumber> {
+  const cfg = await getTokenFeeConfig(params);
+  return cfg.toNativeCommission
+    .plus(cfg.redeemFee)
+    .plus(cfg.redeemForBtcMinAmount);
+}

package/src/web3Sdk/getTokenFeeConfig/index.ts

@@ -0,0 +1,11 @@
+export type {
+  GetTokenFeeConfigParams,
+  TokenFeeConfigResult,
+} from './getTokenFeeConfig';
+export {
+  getMinRedeemAmountSolana,
+  getMinRedeemAmountWithFeeSolana,
+  getMintingFeeSolana,
+  getRedeemFeeSolana,
+  getTokenFeeConfig,
+} from './getTokenFeeConfig';

package/src/web3Sdk/index.ts

@@ -1,14 +1,13 @@
 export * from './detectWallet';
 export * from './getBalance';
+export * from './getTokenFeeConfig';
 export * from './getUnifiedChainId';
 export * from './signLbtcDestinationAddrSolana';
 export * from './signMessage';
 export * from './signTermsOfService';
 
-// LBTC operations
-export * from './claimLBTC';
-export * from './unstakeLBTC';
-
 // Asset Router operations (Ledger v2)
 export * from './claimToken';
+export * from './deposit';
+export * from './redeem';
 export * from './redeemToken';

package/src/web3Sdk/redeem/index.ts

@@ -0,0 +1 @@
+export { redeem, type RedeemParams } from './redeem';