@lombard.finance/sdk-starknet 0.3.0-canary.2

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@lombard.finance/sdk-starknet",
+  "version": "0.3.0-canary.2",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "license": "MIT",
+  "type": "module",
+  "types": "./src/index.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">= 22.14.0"
+  },
+  "scripts": {
+    "build": "yarn types && vite build",
+    "build-docs": "rimraf ./sdk-docs && typedoc --out sdk-docs",
+    "build-storybook": "storybook build -o sdk-storybook",
+    "lint": "eslint . --ext .js,.jsx,.ts,.tsx --max-warnings=0",
+    "format": "prettier --write \"src/**/*.{js,jsx,ts,tsx}\"",
+    "format:check": "prettier --check \"src/**/*.{js,jsx,ts,tsx}\"",
+    "storybook": "storybook dev -p 6006",
+    "types": "tsc --noEmit",
+    "watch": "vite build --watch"
+  },
+  "dependencies": {
+    "@lombard.finance/sdk-common": "3.4.0-canary.2",
+    "starknet": "~6.24.1"
+  },
+  "devDependencies": {
+    "@chromatic-com/storybook": "1.6.1",
+    "@starknet-io/get-starknet": "^4.0.7",
+    "@storybook/addon-essentials": "^8.2.9",
+    "@storybook/addon-interactions": "^8.2.9",
+    "@storybook/addon-links": "^8.2.9",
+    "@storybook/addon-onboarding": "^8.2.9",
+    "@storybook/blocks": "^8.2.9",
+    "@storybook/react": "^8.2.9",
+    "@storybook/react-vite": "^8.2.9",
+    "@storybook/test": "^8.2.9",
+    "@tanstack/react-query": "^5.71.1",
+    "@types/node": "^24.7.2",
+    "axios": "^1.7.4",
+    "bignumber.js": "^9.1.2",
+    "bootstrap": "^5.3.3",
+    "rimraf": "^5",
+    "storybook": "^8.2.9",
+    "typedoc": "^0.26.6",
+    "typescript": "^5.4.5",
+    "vite": "^6.3.5"
+  },
+  "peerDependencies": {
+    "@noble/hashes": "^1.7.2",
+    "axios": "^1",
+    "bignumber.js": "^9"
+  },
+  "resolutions": {
+    "starknet": "~6.24.1"
+  }
+}

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

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useEffect } from 'react';
+
+import { Button } from '../stories/components/Button';
+import { CodeBlock } from '../stories/components/CodeBlock';
+import { ConnectButton } from '../stories/components/ConnectButton';
+import { functionType } from '../stories/components/decorators';
+import { starknetContext } from '../stories/components/decorators/starknet-context';
+import { useConnection } from '../stories/hooks/use-connection';
+import useQuery from '../stories/hooks/use-query';
+import { Token } from '../tokens/lib/tokens';
+import { approve } from './approve';
+
+const meta = {
+  title: 'write/approve',
+  component: StoryView,
+  tags: ['autodocs'],
+  decorators: [functionType('write'), starknetContext()],
+} satisfies Meta<typeof StoryView>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const WithParams: Story = {
+  args: {
+    amount: 1,
+    spender:
+      '0x07777d51699c68356c9dad77a56ac2fc90e03312f4afe554650791c379d6719d',
+    token: Token.LBTC,
+  },
+};
+
+type FuncParameters = Parameters<typeof approve>[0];
+type Props = Omit<FuncParameters, 'walletAccount'>;
+
+export function StoryView(props: Props) {
+  const { account } = useConnection();
+
+  useEffect(() => {
+    console.log('s account', account);
+  }, [account]);
+
+  const request = async () => {
+    if (!account) {
+      console.info('Cannot perform action');
+      return;
+    }
+
+    return approve({
+      walletAccount: account,
+      ...props,
+    });
+  };
+
+  const { data, error, isLoading, refetch } = useQuery(request, [], false);
+
+  return (
+    <>
+      <div className="mb-4">
+        <ConnectButton />
+      </div>
+
+      <Button
+        onClick={refetch}
+        disabled={isLoading}
+        isLoading={isLoading}
+        actionName={approve.name}
+      />
+
+      <CodeBlock text={error || data} />
+    </>
+  );
+}

package/src/contract-functions/approve.ts

@@ -0,0 +1,56 @@
+import { toBaseDenomination } from '@lombard.finance/sdk-common/utils/numbers';
+
+import { getTokenContract, TokenParameters } from '../tokens/lib/tokens';
+import { StarknetChainId } from '../utils/chains';
+import { Address } from '../utils/common';
+import { EnvParameters } from '../utils/env';
+import { getRpcProvider } from '../utils/rpc-providers';
+import { WalletAccountParameters } from '../utils/wallet-account';
+
+type ApproveParameters = {
+  /** The approved amount. */
+  amount: BigNumber.Value;
+  /** The spender address. */
+  spender: Address;
+} & TokenParameters &
+  WalletAccountParameters &
+  EnvParameters;
+
+export async function approve({
+  amount,
+  spender,
+  token,
+  walletAccount,
+  env,
+}: ApproveParameters) {
+  const chainId = (await walletAccount.getChainId()) as StarknetChainId;
+
+  // Use SDK's RPC provider for read-only operations to avoid wallet RPC rate limits
+  // (Wallet extensions like Braavos/ArgentX use OnFinality which has strict rate limits)
+  const rpcProvider = getRpcProvider(chainId);
+
+  // Read decimals using SDK RPC (avoid wallet rate limits)
+  const readOnlyContract = getTokenContract({
+    chainId,
+    contractType: 'token',
+    provider: rpcProvider,
+    token,
+    env,
+  });
+
+  const decimals = await readOnlyContract.decimals();
+  const amountBaseDenom = toBaseDenomination(amount, Number(decimals));
+
+  // Use walletAccount for write operation (signing tx)
+  const tokenContract = getTokenContract({
+    chainId,
+    contractType: 'token',
+    provider: walletAccount,
+    token,
+    env,
+  });
+
+  const tx = await tokenContract.approve(spender, amountBaseDenom.toNumber());
+
+  return tx.transaction_hash;
+}

package/src/contract-functions/balance-of.stories.tsx

@@ -0,0 +1,54 @@
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { Button } from '../stories/components/Button';
+import { CodeBlock } from '../stories/components/CodeBlock';
+import { functionType } from '../stories/components/decorators';
+import useQuery from '../stories/hooks/use-query';
+import { Token } from '../tokens/lib/tokens';
+import { StarknetChainId } from '../utils/chains';
+import { balanceOf } from './balance-of';
+
+const meta = {
+  title: 'read/balance-of',
+  component: StoryView,
+  tags: ['autodocs'],
+  decorators: [functionType('read')],
+} satisfies Meta<typeof StoryView>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const WithParams: Story = {
+  args: {
+    account:
+      '0x0222cad4d720e1693277a3cc426ae81199ff808f86c10b6dffd946b37f5953d7',
+    token: Token.LBTC,
+    chainId: StarknetChainId.SN_SEPOLIA,
+  },
+};
+
+type Props = Parameters<typeof balanceOf>[0];
+
+export function StoryView(props: Props) {
+  const request = async () => {
+    return balanceOf({
+      ...props,
+    });
+  };
+
+  const { data, error, isLoading, refetch } = useQuery(request, [], false);
+
+  return (
+    <>
+      <Button
+        onClick={refetch}
+        disabled={isLoading}
+        isLoading={isLoading}
+        actionName={balanceOf.name}
+      />
+
+      <CodeBlock text={error || data} />
+    </>
+  );
+}

package/src/contract-functions/balance-of.ts

@@ -0,0 +1,41 @@
+import { fromBaseDenomination } from '@lombard.finance/sdk-common/utils/numbers';
+import { BigNumber } from 'bignumber.js';
+
+import { getTokenContract, TokenParameters } from '../tokens/lib/tokens';
+import { ChainParameters } from '../utils/chains';
+import { Address } from '../utils/common';
+import { EnvParameters } from '../utils/env';
+import { getRpcProvider } from '../utils/rpc-providers';
+
+type BalanceOfParameters = {
+  /** The account address */
+  account: Address;
+} & TokenParameters &
+  ChainParameters &
+  EnvParameters;
+
+export async function balanceOf({
+  account,
+  token,
+  chainId,
+  env,
+}: BalanceOfParameters) {
+  const provider = getRpcProvider(chainId);
+
+  const contract = getTokenContract({
+    chainId,
+    contractType: 'token',
+    provider,
+    token,
+    env,
+  });
+
+  const balanceRaw = (await contract.balance_of(account)) as bigint;
+  const balance = BigNumber(String(balanceRaw));
+
+  const decimals = (await contract.decimals()) as number;
+
+  const tokenBalance = fromBaseDenomination(balance, decimals);
+
+  return tokenBalance;
+}

package/src/contract-functions/mint.ts

@@ -0,0 +1,109 @@
+import { keccak_256 } from '@noble/hashes/sha3';
+
+import { getTokenContract, TokenParameters } from '../tokens/lib/tokens';
+import { makeDestinationChainId, StarknetChainId } from '../utils/chains';
+import { Address, ensureHex } from '../utils/common';
+import { EnvParameters } from '../utils/env';
+import { getRpcProvider } from '../utils/rpc-providers';
+import { parseProofHexToU256Tuples } from '../utils/span';
+import { WalletAccountParameters } from '../utils/wallet-account';
+
+export type MintParameters = TokenParameters &
+  WalletAccountParameters &
+  EnvParameters & {
+    /** The amount to be minted, satoshi */
+    amount: BigNumber.Value;
+    /** The deposit tx index, e.g. 0 */
+    depositIndex: number | string;
+    /** The raw paylod of the BTC deposit */
+    depositPayload: string;
+    /** The proof signature of the BTC deposit */
+    depositProofSignature: string;
+    /** The transaction id of the BTC deposit  */
+    depositTxId: string;
+    /** The (optional) recipient address. Uses the connected address if left empty */
+    recipientAddress?: Address;
+  };
+
+/**
+ * Mints the specified amount of token (e.g LBTC) and transfers the funds
+ * to the recipient given address.
+ */
+export async function mint({
+  amount,
+  depositPayload,
+  depositTxId,
+  depositIndex,
+  depositProofSignature,
+  token,
+  walletAccount,
+  recipientAddress,
+  env,
+}: MintParameters) {
+  const chainId = (await walletAccount.getChainId()) as StarknetChainId;
+
+  const btcTxIdBytes = (
+    depositTxId.startsWith('0x') ? depositTxId.slice(2) : depositTxId
+  ).match(/.{2}/g);
+  if (!btcTxIdBytes) {
+    throw new Error('Missing deposit tx id');
+  }
+
+  // Use SDK's RPC provider for read-only operations to avoid wallet RPC rate limits
+  // (Wallet extensions like Braavos/ArgentX use OnFinality which has strict rate limits)
+  const rpcProvider = getRpcProvider(chainId);
+
+  const readOnlyParams = {
+    chainId,
+    provider: rpcProvider, // Use SDK RPC for reads, not wallet's RPC
+    token,
+  };
+
+  const basculeContract = getTokenContract({
+    ...readOnlyParams,
+    contractType: 'bascule',
+    env,
+  });
+
+  const basculeDepositId = ensureHex(
+    Buffer.from(
+      keccak_256(Buffer.from(depositPayload.slice(8), 'hex')),
+    ).toString('hex'),
+  );
+
+  const status = await basculeContract.get_deposit_status(
+    BigInt(basculeDepositId),
+  );
+
+  if (status.activeVariant() !== 'Reported') {
+    const msg = `The deposit cannot be claimed. Bascule status: ${status.activeVariant()}`;
+    console.warn(msg); // TODO: Remove when Bascule configured
+    // throw new Error(msg); // TODO: Re-enable once configured
+  }
+
+  const to_chain = BigInt(makeDestinationChainId(chainId));
+  const recipient = recipientAddress || walletAccount.address;
+  const tx_id = BigInt(ensureHex(btcTxIdBytes.reverse().join('')));
+  const vout = Number(depositIndex);
+  const proof = parseProofHexToU256Tuples(depositProofSignature);
+
+  // For write operations (mint), use walletAccount to sign the transaction
+  const bridgeContract = getTokenContract({
+    chainId,
+    provider: walletAccount, // Need wallet account to sign tx
+    token,
+    contractType: 'bridge',
+    env,
+  });
+
+  const { transaction_hash } = await bridgeContract.mint(
+    to_chain,
+    recipient,
+    BigInt(amount.toString()),
+    tx_id,
+    vout,
+    proof,
+  );
+
+  return transaction_hash;
+}

package/src/contract-functions/redeem.ts

@@ -0,0 +1,107 @@
+import { Env, getOutputScript } from '@lombard.finance/sdk-common';
+import {
+  BtcAddressType,
+  getBtcAddressType,
+} from '@lombard.finance/sdk-common/utils/btc-address-type';
+import { toBaseDenomination } from '@lombard.finance/sdk-common/utils/numbers';
+import { ByteArray, CallData, uint256 } from 'starknet';
+
+import { getTokenContract, TokenParameters } from '../tokens/lib/tokens';
+import { StarknetChainId } from '../utils/chains';
+import { EnvParameters } from '../utils/env';
+import { ERR_UNEXPECTED_OUTPUT_SCRIPT } from '../utils/err';
+import { getRpcProvider } from '../utils/rpc-providers';
+import { WalletAccountParameters } from '../utils/wallet-account';
+
+export type RedeemParameters = TokenParameters &
+  WalletAccountParameters &
+  EnvParameters & {
+    /** The amount, e.g. 1.2 LBTC */
+    amount: BigNumber.Value;
+    /** The destination BTC address */
+    btcAddress: string;
+  };
+
+/**
+ * Redeems (unstakes) specified amount of token and sends equivalent amount of
+ * BTC to the provided BTC address.
+ */
+export async function redeem({
+  amount,
+  btcAddress,
+  token,
+  walletAccount,
+  env,
+}: RedeemParameters) {
+  const chainId = (await walletAccount.getChainId()) as StarknetChainId;
+
+  // Use SDK's RPC provider for read-only operations to avoid wallet RPC rate limits
+  // (Wallet extensions like Braavos/ArgentX use OnFinality which has strict rate limits)
+  const rpcProvider = getRpcProvider(chainId);
+
+  const tokenParams = {
+    token,
+    chainId,
+    provider: rpcProvider, // Use SDK RPC for reads, not wallet's RPC
+  };
+
+  const tokenContract = getTokenContract({
+    ...tokenParams,
+    contractType: 'token',
+    env,
+  });
+
+  const decimals = Number(await tokenContract.decimals());
+  const amountBaseDenom = toBaseDenomination(amount, decimals);
+
+  const bridgeContract = getTokenContract({
+    ...tokenParams,
+    contractType: 'bridge',
+    env,
+  });
+
+  const script = await getOutputScript(
+    btcAddress,
+    chainId === StarknetChainId.SN_MAIN ? Env.prod : Env.stage,
+  );
+
+  const addressType = getBtcAddressType(btcAddress);
+
+  let script_pub_key: ByteArray | undefined = undefined;
+  if (
+    addressType === BtcAddressType.p2tr ||
+    addressType === BtcAddressType.p2wsh
+  ) {
+    const word = `0x${script.slice(2, 64)}`;
+    const pending_word = `0x${script.slice(64) || '0'}`;
+
+    script_pub_key = {
+      data: [word],
+      pending_word: pending_word,
+      pending_word_len: script.slice(64).length / 2,
+    };
+  }
+
+  if (addressType === BtcAddressType.p2wpkh) {
+    script_pub_key = {
+      data: [],
+      pending_word: `0x${script.slice(2)}`,
+      pending_word_len: script.slice(2).length / 2,
+    };
+  }
+
+  if (!script_pub_key) {
+    throw ERR_UNEXPECTED_OUTPUT_SCRIPT;
+  }
+
+  const { transaction_hash } = await walletAccount.execute({
+    contractAddress: bridgeContract.address,
+    entrypoint: 'redeem',
+    calldata: CallData.compile({
+      script_pub_key,
+      amount: uint256.bnToUint256(amountBaseDenom.toNumber()),
+    }),
+  });
+
+  return transaction_hash;
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+/** Starknet tokens */
+
+export * from './tokens/lib/tokens';
+
+/** Contract functions */
+
+export * from './contract-functions/approve';
+export * from './contract-functions/balance-of';
+export * from './contract-functions/mint';
+export * from './contract-functions/redeem';
+
+/** Wallet functions */
+
+export * from './wallet-functions/sign-message';
+export * from './wallet-functions/sign-terms-of-service';
+
+/** Utils */
+
+export * from './utils/chains';
+export * from './utils/rpc-providers';
+export * from './utils/typed-data';
+
+/** Module */
+
+export { starknetModule } from './module/createStarknetModule';

package/src/module/createStarknetModule.ts

@@ -0,0 +1,38 @@
+/**
+ * Starknet Module
+ *
+ * Provides Starknet chain service for LBTC operations.
+ * Uses Service-First pattern: module is a thin factory that instantiates the service.
+ *
+ * @module module/createStarknetModule
+ */
+
+import type { ChainModule, StarknetService } from '@lombard.finance/sdk-common';
+
+import { StarknetServiceImpl } from '../services/StarknetServiceImpl';
+
+/**
+ * Create Starknet module
+ *
+ * Optional module that provides StarknetService for Starknet operations.
+ *
+ * @example
+ * ```ts
+ * import { starknetModule } from '@lombard.finance/sdk-starknet';
+ *
+ * const config = createConfig({
+ *   modules: [starknetModule()],
+ *   providers: { starknet: () => starknetWallet },
+ * });
+ * ```
+ */
+export function starknetModule(): ChainModule<'starknet', StarknetService> {
+  return {
+    id: 'starknet',
+    chain: 'starknet',
+    requiresProviders: ['starknet'],
+    register(ctx) {
+      return new StarknetServiceImpl(() => ctx.getProvider('starknet'));
+    },
+  };
+}

package/src/services/StarknetServiceImpl.ts

@@ -0,0 +1,83 @@
+/**
+ * Starknet Service Implementation
+ *
+ * Provides Starknet-specific operations for LBTC destination signing and unstaking.
+ *
+ * @module services/StarknetServiceImpl
+ */
+
+import type { Env, StarknetService } from '@lombard.finance/sdk-common';
+import type { WalletAccount } from 'starknet';
+
+import { redeem } from '../contract-functions/redeem';
+import { Token } from '../tokens/lib/tokens';
+import { StarknetChainId } from '../utils/chains';
+import { signLbtcDestinationAddrStarknet } from '../wallet-functions/sign-message';
+
+/**
+ * Provider resolver function type
+ */
+type ProviderResolver = () => Promise<unknown>;
+
+/**
+ * Starknet wallet provider interface
+ */
+interface StarknetWalletProvider {
+  getProvider: () => WalletAccount;
+}
+
+/**
+ * Starknet Service Implementation
+ *
+ * Wraps low-level Starknet functions into a clean service interface.
+ * Instantiated by starknetModule().
+ */
+export class StarknetServiceImpl implements StarknetService {
+  constructor(private readonly getProvider: ProviderResolver) {}
+
+  /**
+   * Sign LBTC destination address for Starknet minting
+   */
+  async signLbtcDestination(args: {
+    chainId: string;
+  }): Promise<{ signature: string; pubKey: string }> {
+    const provider = await this.getProvider();
+    const walletProvider = provider as StarknetWalletProvider;
+    const walletAccount = walletProvider.getProvider();
+
+    const result = await signLbtcDestinationAddrStarknet({
+      walletAccount,
+      chainId: args.chainId as StarknetChainId,
+    });
+
+    return {
+      signature: result.signatureHex,
+      pubKey: result.pubKey,
+    };
+  }
+
+  /**
+   * Unstake LBTC on Starknet to receive BTC
+   *
+   * Burns LBTC on Starknet and releases BTC to the provided Bitcoin address.
+   */
+  async unstake(args: {
+    amount: string;
+    btcAddress: string;
+    env: string;
+  }): Promise<{ txHash: string }> {
+    const provider = await this.getProvider();
+    const walletProvider = provider as StarknetWalletProvider;
+    const walletAccount = walletProvider.getProvider();
+
+    const txHash = await redeem({
+      amount: args.amount,
+      btcAddress: args.btcAddress,
+      token: Token.LBTC,
+      walletAccount,
+      env: args.env as Env,
+    });
+
+    return { txHash };
+  }
+}

package/src/services/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Starknet Service Exports
+ *
+ * @module services
+ */
+
+export { StarknetServiceImpl } from './StarknetServiceImpl';

package/src/stories/components/Button/Button.css

@@ -0,0 +1,10 @@
+.story-btn {
+  border: 1px solid var(--bs-gray-900);
+  background: var(--bs-gray-200);
+  color: var(--bs-gray-900);
+}
+
+.story-btn:hover {
+  background: var(--bs-gray-700);
+  color: var(--bs-gray-100);
+}