@lombard.finance/sdk 0.1.0

package/src/sdk/generateDepositBtcAddress/generateDepositBtcAddress.ts

@@ -0,0 +1,64 @@
+import axios from 'axios';
+import { IEnvParam } from '../../common/types/internalTypes';
+import { TChainId } from '../../common/types/types';
+import { getApiConfig } from '../apiConfig';
+import { getChainNameById } from '../utils/getChainNameById';
+
+const ADDRESS_URL = 'api/v1/address';
+
+interface IGenerateNewAddressResponse {
+  address: string;
+}
+
+export interface IGenerateDepositBtcAddressParams extends IEnvParam {
+  /**
+   * The destination EVM user address where LBTC will be claimed.
+   */
+  address: string;
+  /**
+   * The destination chain ID where LBTC will be claimed.
+   */
+  chainId: TChainId;
+  /**
+   * The signature of the address. The signature is generated by signing the address using EVM wallet.
+   */
+  signature: string;
+  /**
+   * The referral ID.
+   */
+  referralId?: string;
+}
+
+/**
+ * Generates a BTC deposit address.
+ * @param {IGenerateDepositBtcAddressParams} params - The parameters for generating the deposit address.
+ * @returns {Promise<string>} The generated deposit address.
+ */
+export async function generateDepositBtcAddress({
+  address,
+  chainId,
+  signature,
+  referralId,
+  env,
+}: IGenerateDepositBtcAddressParams): Promise<string> {
+  const { depositAddrApiUrl } = getApiConfig(env);
+  const toChain = getChainNameById(chainId);
+
+  const requestParams = {
+    to_address: address,
+    to_address_signature: signature,
+    to_chain: toChain,
+    referral_id: referralId,
+    nonce: 0,
+  };
+
+  const { data } = await axios.post<IGenerateNewAddressResponse>(
+    ADDRESS_URL,
+    requestParams,
+    {
+      baseURL: depositAddrApiUrl,
+    },
+  );
+
+  return data.address;
+}

package/src/sdk/generateDepositBtcAddress/index.ts

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

package/src/sdk/getDepositBtcAddress/getDepositBtcAddress.stories.tsx

@@ -0,0 +1,53 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { defaultEnv } from '../../common/const';
+import { OChainId } from '../../common/types/types';
+import { Button } from '../../stories/components/Button';
+import { CodeBlock } from '../../stories/components/CodeBlock';
+import { exampleEvmAddress } from '../../stories/const';
+import useQuery from '../../stories/hooks/useQuery';
+import { fromCamelCase } from '../../stories/utils/fromCamelCase';
+import {
+  getDepositBtcAddress,
+  IGetDepositBtcAddressParams,
+} from './getDepositBtcAddress';
+
+const { name } = getDepositBtcAddress;
+const nameWithWhitespaces = fromCamelCase(name);
+
+const meta = {
+  title: 'SDK/getDepositBtcAddress',
+  component: StoryView,
+  tags: ['autodocs'],
+} satisfies Meta<typeof StoryView>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const WithParams: Story = {
+  args: {
+    address: exampleEvmAddress,
+    chainId: OChainId.ethereum,
+    env: defaultEnv,
+  },
+};
+
+export function StoryView(props: IGetDepositBtcAddressParams) {
+  const { data, error, isLoading, refetch } = useQuery(
+    () => getDepositBtcAddress(props),
+    [props],
+    false,
+  );
+
+  const test = true;
+
+  return (
+    <>
+      <Button onClick={refetch} disabled={isLoading} isLoading={isLoading}>
+        {nameWithWhitespaces}
+      </Button>
+
+      <CodeBlock text={error || data} />
+    </>
+  );
+}

package/src/sdk/getDepositBtcAddress/getDepositBtcAddress.ts

@@ -0,0 +1,101 @@
+import axios from 'axios';
+import { IEnvParam } from '../../common/types/internalTypes';
+import { TChainId } from '../../common/types/types';
+import { getApiConfig } from '../apiConfig';
+import { TChainName } from '../internalTypes';
+import { getChainNameById } from '../utils/getChainNameById';
+
+// todo: implement case when the address is sanctioned
+/**
+ * The address wich will be returned if the provided BTC address is sanctioned.
+ *
+ * @remarks not implemented yet
+ */
+export const SANCTIONED_ADDRESS = 'sanctioned_address';
+
+const ADDRESS_URL = 'api/v1/address';
+
+interface IDepositAddress {
+  btc_address: string;
+  created_at: string;
+  deprecated?: boolean;
+  type: string;
+  used?: boolean;
+  deposit_metadata: {
+    to_address: string;
+    to_blockchain: TChainName;
+  };
+}
+
+interface IDepositAddressesResponse {
+  addresses: IDepositAddress[];
+  has_more?: boolean;
+}
+
+export interface IGetDepositBtcAddressParams extends IEnvParam {
+  /**
+   * The destination EVM user address where LBTC will be claimed.
+   */
+  address: string;
+  /**
+   * The destination chain ID where LBTC will be claimed.
+   */
+  chainId: TChainId;
+}
+
+/**
+ * Returns the address for depositing BTC.
+ *
+ * @param {IGetDepositBtcAddressParams} params - function parameters
+ *
+ * @returns {Promise<string>} the address for depositing BTC
+ */
+export async function getDepositBtcAddress({
+  address,
+  chainId,
+  env,
+}: IGetDepositBtcAddressParams): Promise<string> {
+  const toBlockchain = getChainNameById(chainId);
+  const addresses = await getDepositBtcAddresses({ address, chainId, env });
+
+  const addressData = addresses.find(
+    addressData => addressData.deposit_metadata.to_blockchain === toBlockchain,
+  );
+
+  if (!addressData) {
+    throw new Error('No address');
+  }
+
+  return addressData.btc_address;
+}
+
+/**
+ * Returns the addresses for depositing BTC.
+ *
+ * @param {IGetDepositBtcAddressParams} params - function parameters
+ *
+ * @returns {Promise<IDepositAddress[]>} the deposit addresses
+ */
+export async function getDepositBtcAddresses({
+  address,
+  chainId,
+  env,
+}: IGetDepositBtcAddressParams): Promise<IDepositAddress[]> {
+  const { depositAddrApiUrl } = getApiConfig(env);
+  const toBlockchain = getChainNameById(chainId);
+
+  const requestrParams = {
+    to_address: address,
+    to_blockchain: toBlockchain,
+    limit: 1,
+    offset: 0,
+    asc: false,
+  };
+
+  const { data } = await axios.get<IDepositAddressesResponse>(ADDRESS_URL, {
+    baseURL: depositAddrApiUrl,
+    params: requestrParams,
+  });
+
+  return data?.addresses || [];
+}

package/src/sdk/getDepositBtcAddress/index.ts

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

package/src/sdk/getDepositsByAddress/getDepositsByAddress.stories.tsx

@@ -0,0 +1,49 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { defaultEnv } from '../../common/const';
+import { Button } from '../../stories/components/Button';
+import { CodeBlock } from '../../stories/components/CodeBlock';
+import { exampleEvmAddress } from '../../stories/const';
+import useQuery from '../../stories/hooks/useQuery';
+import { fromCamelCase } from '../../stories/utils/fromCamelCase';
+import {
+  getDepositsByAddress,
+  IGetDepositsByAddressParams,
+} from './getDepositsByAddress';
+
+const { name } = getDepositsByAddress;
+const nameWithWhitespaces = fromCamelCase(name);
+
+const meta = {
+  title: 'SDK/getDepositsByAddress',
+  component: StoryView,
+  tags: ['autodocs'],
+} satisfies Meta<typeof StoryView>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const WithParams: Story = {
+  args: {
+    address: exampleEvmAddress,
+    env: defaultEnv,
+  },
+};
+
+export function StoryView(props: IGetDepositsByAddressParams) {
+  const { data, error, isLoading, refetch } = useQuery(
+    () => getDepositsByAddress(props),
+    [props],
+    false,
+  );
+
+  return (
+    <>
+      <Button onClick={refetch} disabled={isLoading} isLoading={isLoading}>
+        {nameWithWhitespaces}
+      </Button>
+
+      <CodeBlock text={error || data} />
+    </>
+  );
+}

package/src/sdk/getDepositsByAddress/getDepositsByAddress.ts

@@ -0,0 +1,146 @@
+import axios from 'axios';
+import { IEnvParam } from '../../common/types/internalTypes';
+import { OChainId, TChainId, TEnv } from '../../common/types/types';
+import { fromSatoshi } from '../../common/utils/convertSatoshi';
+import { getApiConfig } from '../apiConfig';
+import { getCainIdByName } from '../utils/getCainIdByName';
+
+type Address = string;
+
+interface IDepositResponse {
+  txid: string;
+  index?: number;
+  block_height?: string;
+  block_time?: string;
+  value: number;
+  address: Address;
+  to_chain: string;
+  claim_tx?: string;
+  raw_payload: string;
+  payload: string;
+  signature: string;
+  sanctioned?: boolean;
+}
+
+interface IDepositsByAddressResponse {
+  outputs: IDepositResponse[];
+}
+
+export interface IDeposit {
+  txid: string;
+  index?: number;
+  blockHeight?: number;
+  blockTime?: number;
+  value: number;
+  address: Address;
+  chainId: TChainId;
+  isClaimed: boolean;
+  rawPayload?: string;
+  signature?: string;
+  isRestricted?: boolean;
+}
+
+export interface IGetDepositsByAddressParams extends IEnvParam {
+  /**
+   * The EVM address to get deposits for
+   */
+  address: Address;
+}
+
+/**
+ * Returns all deposits for a given address
+ *
+ * @param {IGetDepositsByAddressParams} params - the parameters for getting deposits
+ *
+ * @returns {Promise<IDeposit[]>} a list of deposits
+ */
+export async function getDepositsByAddress({
+  address,
+  env,
+}: IGetDepositsByAddressParams): Promise<IDeposit[]> {
+  const { baseApiUrl } = getApiConfig(env);
+  const url = `${baseApiUrl}/api/v1/address/outputs/${address}`;
+
+  const { data } = await axios.get<IDepositsByAddressResponse | undefined>(url);
+
+  const outputs = data?.outputs ?? [];
+
+  return outputs.map(mapResponse(env));
+}
+
+function mapResponse(env?: TEnv) {
+  return (data: IDepositResponse): IDeposit => ({
+    txid: data.txid,
+    index: data.index ?? 0,
+    blockHeight: data.block_height ? Number(data.block_height) : undefined,
+    blockTime: data.block_time ? Number(data.block_time) : undefined,
+    value: fromSatoshi(data.value),
+    address: data.address,
+    chainId: getCainIdByName(data.to_chain, env),
+    // todo: return claiming tx from the API when it's available
+    isClaimed: !!data.claim_tx,
+    rawPayload: data.raw_payload,
+    signature: data.signature,
+    isRestricted: !!data.sanctioned,
+  });
+}
+
+export const demoDepositsByAddress: IDeposit[] = [
+  {
+    txid: 'txid0',
+    index: 0,
+    blockHeight: 100,
+    blockTime: 1715964690,
+    value: 0.2,
+    address: 'address0',
+    chainId: OChainId.holesky,
+    isClaimed: false,
+    rawPayload: 'rawPayload0',
+    signature: 'signature0',
+  },
+  {
+    txid: 'dasjmnkosdfjnkdsgjnk',
+    index: 0,
+    blockHeight: 110,
+    blockTime: 1715964690,
+    value: 0.3,
+    address: 'adslhjnkbsfdahbk',
+    chainId: OChainId.holesky,
+    isClaimed: false,
+    rawPayload: 'rawPayload0',
+    signature: 'signature0',
+  },
+  {
+    txid: '0xfsmkfdskm',
+    index: 0,
+    blockHeight: 102,
+    blockTime: 1715964690,
+    value: 0.55,
+    address: 'dgfgfasd',
+    chainId: OChainId.holesky,
+    isClaimed: false,
+  },
+  {
+    txid: 'kmgnjkofejnadwnjdasljmnkjgsdklmn',
+    index: 0,
+    blockHeight: 102,
+    blockTime: 1715964691,
+    value: 0.77,
+    address: 'hgjhyewadwss',
+    chainId: OChainId.holesky,
+    isClaimed: false,
+    isRestricted: true,
+  },
+  {
+    txid: 'f6b6d0e1e77df21e406bd730c32b05c3fae8296491a1d946925eff07d02d5825',
+    index: 1,
+    blockHeight: 100,
+    blockTime: 1715789138,
+    value: 0.2,
+    address: 'address1',
+    chainId: OChainId.holesky,
+    isClaimed: true,
+    rawPayload: 'rawPayload1',
+    signature: 'signature1',
+  },
+];

package/src/sdk/getDepositsByAddress/index.ts

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

package/src/sdk/index.ts

@@ -0,0 +1,3 @@
+export * from './generateDepositBtcAddress';
+export * from './getDepositBtcAddress';
+export * from './getDepositsByAddress';

package/src/sdk/internalTypes.ts

@@ -0,0 +1,5 @@
+export const OChainName = {
+  eth: 'DESTINATION_BLOCKCHAIN_ETHEREUM',
+} as const;
+
+export type TChainName = (typeof OChainName)[keyof typeof OChainName];

package/src/sdk/utils/getCainIdByName.ts

@@ -0,0 +1,21 @@
+import { defaultEnv } from '../../common/const';
+import { OChainId, OEnv, TChainId, TEnv } from '../../common/types/types';
+import { TChainName } from '../internalTypes';
+
+/**
+ * @param chainId the chain ID
+ *
+ * @returns the chain name
+ */
+export function getCainIdByName(
+  chain: string,
+  env: TEnv = defaultEnv,
+): TChainId {
+  switch (chain as TChainName) {
+    case 'DESTINATION_BLOCKCHAIN_ETHEREUM':
+      return env === OEnv.prod ? OChainId.ethereum : OChainId.holesky;
+
+    default:
+      return OChainId.ethereum;
+  }
+}

package/src/sdk/utils/getChainNameById.ts

@@ -0,0 +1,17 @@
+import { OChainId, TChainId } from '../../common/types/types';
+import { OChainName, TChainName } from '../internalTypes';
+
+/**
+ * @param chainId the chain ID
+ *
+ * @returns the chain name
+ */
+export function getChainNameById(chainId: TChainId): TChainName {
+  switch (chainId) {
+    case OChainId.holesky:
+    case OChainId.ethereum:
+      return OChainName.eth;
+    default:
+      throw new Error(`Unknown chain ID: ${chainId}`);
+  }
+}

package/src/stories/components/Button/Button.tsx

@@ -0,0 +1,43 @@
+import React from 'react';
+import { Spinner } from '../Spinner';
+
+export interface ButtonProps {
+  disabled?: boolean;
+  children?: React.ReactNode;
+  primary?: boolean;
+  size?: 'small' | 'medium' | 'large';
+  isLoading?: boolean;
+  onClick?: () => void;
+}
+
+/**
+ * Primary UI component for user interaction
+ */
+export const Button = ({
+  primary = true,
+  size = 'medium',
+  children,
+  isLoading,
+  ...props
+}: ButtonProps) => {
+  const mode = primary
+    ? 'storybook-button--primary'
+    : 'storybook-button--secondary';
+
+  return (
+    <button
+      type="button"
+      className={[
+        'btn',
+        size === 'small' ? 'btn-sm' : '',
+        size === 'large' ? 'btn-lg' : '',
+        primary ? 'btn-primary' : 'btn-secondary',
+      ].join(' ')}
+      {...props}
+    >
+      {children}
+
+      {isLoading && <Spinner color="text-light" className="ms-2" />}
+    </button>
+  );
+};

package/src/stories/components/Button/index.ts

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

package/src/stories/components/CodeBlock/CodeBlock.tsx

@@ -0,0 +1,24 @@
+import './CodeBlockStyles.css';
+
+interface ICodeBlockProps {
+  text?: any;
+  withFormatting?: boolean;
+}
+
+export function CodeBlock({
+  text,
+  withFormatting = true,
+}: ICodeBlockProps): JSX.Element | null {
+  const formattedCode =
+    text && withFormatting ? JSON.stringify(text, null, 2) : text;
+
+  if (!text) {
+    return null;
+  }
+
+  return (
+    <pre className="card my-3 code-block--max-height">
+      <code className="card-body">{formattedCode}</code>
+    </pre>
+  );
+}

package/src/stories/components/CodeBlock/CodeBlockStyles.css

@@ -0,0 +1,3 @@
+.code-block--max-height {
+  max-height: 500px;
+}

package/src/stories/components/CodeBlock/index.ts

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

package/src/stories/components/Spinner/Spinner.tsx

@@ -0,0 +1,25 @@
+interface ISpinnerProps {
+  color?: 'text-primary' | 'text-light';
+  size?: 'sm' | 'md';
+  className?: string;
+}
+
+export function Spinner({
+  color = 'text-primary',
+  size = 'sm',
+  className,
+}: ISpinnerProps): JSX.Element {
+  return (
+    <div
+      className={[
+        'spinner-border',
+        color,
+        size === 'sm' ? 'spinner-border-sm' : '',
+        className || '',
+      ].join(' ')}
+      role="status"
+    >
+      <span className="visually-hidden">Loading...</span>
+    </div>
+  );
+}

package/src/stories/components/Spinner/index.ts

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

package/src/stories/const.ts

@@ -0,0 +1 @@
+export const exampleEvmAddress = '0x659579f1460c38c3ce3288b47b074646cef855fc';

package/src/stories/hooks/useConnect.ts

@@ -0,0 +1,47 @@
+import Web3 from 'web3';
+import { TChainId } from '../../common/types/types';
+import { isValidChain } from '../../common/utils/isValidChain';
+import { connectInjectedWallet } from '../utils/connectInjectedWallet';
+import { getWalletInfo } from '../utils/getWalletInfo';
+import useQuery from './useQuery';
+
+interface IRequestConnect {
+  web3: Web3;
+  account: string;
+  chainId: TChainId;
+}
+
+interface IUseConnect {
+  data: IRequestConnect | null;
+  error: string | null;
+  isLoading: boolean;
+  connect: () => void;
+}
+
+export function useConnect(): IUseConnect {
+  const {
+    data,
+    error,
+    isLoading,
+    refetch: connect,
+  } = useQuery(requestConnect, [], false);
+
+  return {
+    data,
+    error,
+    isLoading,
+    connect,
+  };
+}
+
+async function requestConnect(): Promise<IRequestConnect> {
+  const provider = await connectInjectedWallet();
+  const web3 = new Web3(provider);
+  const { account, chainId } = await getWalletInfo(web3);
+
+  if (!isValidChain(chainId)) {
+    throw new Error('Invalid chain');
+  }
+
+  return { web3, account, chainId };
+}

package/src/stories/hooks/useQuery.ts

@@ -0,0 +1,56 @@
+import { useCallback, useEffect, useState } from 'react';
+import { getErrorMessage } from '../../common/utils/getErrorMessage';
+
+type QueryFn<T> = () => Promise<T>;
+
+interface UseQueryResult<T> {
+  data: T | null;
+  error: string | null;
+  isLoading: boolean;
+  refetch: () => void;
+}
+
+/**
+ * Custom hook for making a query and managing the query state.
+ *
+ * @template T - The type of data returned by the query.
+ * @param queryFn The function that performs the query.
+ * @param dependencies The dependencies that trigger a re-fetch of the query.
+ * @param shouldFetch Determines whether the query should be fetched initially. Defaults to true.
+ * @returns The query result object containing the data, error, loading state, and a refetch function.
+ */
+export function useQuery<T>(
+  queryFn: QueryFn<T>,
+  dependencies: any[] = [],
+  shouldFetch = true,
+): UseQueryResult<T> {
+  const [data, setData] = useState<T | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [isLoading, setLoading] = useState<boolean>(false);
+
+  const fetchData = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    setData(null);
+    try {
+      const result = await queryFn();
+      setData(result);
+    } catch (err) {
+      console.error(err);
+      const errorMsg = getErrorMessage(err);
+      setError(errorMsg);
+    } finally {
+      setLoading(false);
+    }
+  }, [queryFn, ...dependencies]);
+
+  useEffect(() => {
+    if (shouldFetch) {
+      fetchData();
+    }
+  }, [shouldFetch, fetchData, ...dependencies]);
+
+  return { data, error, isLoading, refetch: fetchData };
+}
+
+export default useQuery;