@lombard.finance/sdk-sui 1.1.3 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lombard.finance/sdk-sui",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Sui integration for the Lombard SDK - stake BTC and manage LBTC on Sui",
   "exports": {
     ".": {
@@ -61,6 +61,7 @@
     "@lombard.finance/sdk-common": "4.0.0",
     "@mysten/sui": "^1.21.1",
     "@mysten/wallet-standard": "^0.13.7",
+    "@noble/hashes": "^1.8.0",
     "@wallet-standard/base": "^1.1.0",
     "@wallet-standard/core": "^1.1.0",
     "vite": "^6.3.5"

package/src/const/getConfig.ts

@@ -67,15 +67,15 @@ const testnetConfig: IConfig = {
 // https://github.com/lombard-finance/sui-contracts/blob/main/mainnet.json
 const prodConfig: IConfig = {
   mint: {
-    // lbtc_v2_current
+    // lbtc_v5_current
     target:
-      '0x818430a456ff977f7320f78650d19801f90758d200a01dd3c2c679472c521357::treasury::mint_v2',
+      '0x124477c9cffb667be781e867fd29579d3498a47e6b69d06155841ca85bcb02d0::treasury::mint_v2',
     denyList: '0x403',
   },
   redeem: {
-    // lbtc_v2_current
+    // lbtc_v5_current
     target:
-      '0x818430a456ff977f7320f78650d19801f90758d200a01dd3c2c679472c521357::treasury::redeem',
+      '0x124477c9cffb667be781e867fd29579d3498a47e6b69d06155841ca85bcb02d0::treasury::redeem',
   },
   // lbtc_v1_deprecated - This is intentional
   LBTC: '0x3e8e9423d80e1774a7ca128fccd8bf5f1f7753be658c5e645929037f7c819040::lbtc::LBTC',

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './const';
 export * from './web3Sdk/claimLBTC';
 export * from './web3Sdk/getBalance';
+export * from './web3Sdk/getBasculeDepositStatus';
 export * from './web3Sdk/signLbtcDestionationAddrSui';
 export * from './web3Sdk/signTermsOfService';
 export * from './web3Sdk/unstakeLBTC';

package/src/web3Sdk/claimLBTC/claimLBTC.ts

@@ -7,6 +7,10 @@ import { WalletWithFeatures } from '@wallet-standard/base';
 import type { WalletAccount } from '@wallet-standard/core';
 
 import { getConfig } from '../../const';
+import {
+  getBasculeDepositStatus,
+  SuiBasculeDepositStatus,
+} from '../getBasculeDepositStatus';
 
 type Not0xPrefixedHex = string;
 
@@ -34,6 +38,31 @@ export async function claimLBTC({
   client,
   env = DEFAULT_ENV,
 }: IClaimLBTCParams): Promise<SuiTransactionBlockResponse> {
+  // Pre-flight the Bascule status so we surface a clear error instead of an
+  // opaque on-chain abort from bascule::validate_withdrawal (mirrors the EVM
+  // SDK's claimLBTC). The mint targets the same Bascule object this checks.
+  const basculeStatus = await getBasculeDepositStatus({ client, payload, env });
+  if (basculeStatus !== SuiBasculeDepositStatus.REPORTED) {
+    switch (basculeStatus) {
+      case SuiBasculeDepositStatus.UNREPORTED:
+        throw new Error(
+          'The deposit cannot be claimed because it is unreported or potentially still pending, please try again later.',
+        );
+      case SuiBasculeDepositStatus.WITHDRAWN:
+        throw new Error(
+          'The deposit cannot be claimed because it is withdrawn already.',
+        );
+      case SuiBasculeDepositStatus.PAUSED:
+        throw new Error(
+          'The deposit cannot be claimed because the bridge is paused, please try again later.',
+        );
+      default:
+        throw new Error(
+          'The deposit cannot be claimed because it is blocked by bridge security.',
+        );
+    }
+  }
+
   const transaction = new Transaction();
 
   const {

package/src/web3Sdk/getBasculeDepositStatus/__tests__/getBasculeDepositStatus.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  deriveDepositId,
+  getBasculeDepositStatus,
+  SuiBasculeDepositStatus,
+} from '../getBasculeDepositStatus';
+
+// A synthetic mint payload: 4-byte selector + 5 big-endian 32-byte words
+// (to_chain, recipient, amount=100000, tx_id, vout=3). The expected deposit id
+// is computed independently (pure-python keccak mirroring Move's to_deposit_id
+// and sui-claimer's payload.go) and pinned here as a regression vector.
+const PAYLOAD =
+  'ce25e7c2' +
+  '0000000000000000000000000000000000000000000000000000000000000001' + // to_chain
+  'a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1' + // recipient
+  '00000000000000000000000000000000000000000000000000000000000186a0' + // amount = 100000
+  'b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2' + // tx_id
+  '0000000000000000000000000000000000000000000000000000000000000003'; // vout = 3
+
+const EXPECTED_DEPOSIT_ID =
+  '103946673116742332945389452905418796987698243721899433814538596425314178876115';
+
+describe('deriveDepositId', () => {
+  it('matches the on-chain to_deposit_id derivation', () => {
+    expect(deriveDepositId(PAYLOAD)).toBe(EXPECTED_DEPOSIT_ID);
+  });
+
+  it('accepts a 0x-prefixed payload', () => {
+    expect(deriveDepositId(`0x${PAYLOAD}`)).toBe(EXPECTED_DEPOSIT_ID);
+  });
+
+  it('rejects a payload of the wrong length', () => {
+    expect(() => deriveDepositId('ce25e7c2')).toThrow(/length/);
+  });
+
+  it('rejects a payload with non-hex characters', () => {
+    // Correct length, but the final byte 'ag' has a non-hex low nibble.
+    // Number.parseInt used to accept this as 0x0a; strict validation rejects it.
+    expect(() => deriveDepositId(`${PAYLOAD.slice(0, -2)}ag`)).toThrow(
+      /non-hex/,
+    );
+  });
+});
+
+describe('getBasculeDepositStatus', () => {
+  const makeClient = (overrides: {
+    paused?: boolean;
+    tableId?: string;
+    variant?: string | null;
+  }) =>
+    ({
+      getObject: vi.fn().mockResolvedValue({
+        data: {
+          content: {
+            dataType: 'moveObject',
+            fields: {
+              mIsPaused: overrides.paused ?? false,
+              mDepositHistory: {
+                fields: { id: { id: overrides.tableId ?? '0xtable' } },
+              },
+            },
+          },
+        },
+      }),
+      getDynamicFieldObject: vi.fn().mockResolvedValue(
+        overrides.variant
+          ? {
+              data: {
+                content: {
+                  dataType: 'moveObject',
+                  fields: { value: { variant: overrides.variant } },
+                },
+              },
+            }
+          : { data: null, error: { code: 'dynamicFieldNotFound' } },
+      ),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }) as any;
+
+  it('returns REPORTED for a reported deposit', async () => {
+    const status = await getBasculeDepositStatus({
+      client: makeClient({ variant: 'Reported' }),
+      payload: PAYLOAD,
+    });
+    expect(status).toBe(SuiBasculeDepositStatus.REPORTED);
+  });
+
+  it('returns WITHDRAWN for an already-withdrawn deposit', async () => {
+    const status = await getBasculeDepositStatus({
+      client: makeClient({ variant: 'Withdrawn' }),
+      payload: PAYLOAD,
+    });
+    expect(status).toBe(SuiBasculeDepositStatus.WITHDRAWN);
+  });
+
+  it('returns UNREPORTED when the deposit is not in the table', async () => {
+    const status = await getBasculeDepositStatus({
+      client: makeClient({ variant: null }),
+      payload: PAYLOAD,
+    });
+    expect(status).toBe(SuiBasculeDepositStatus.UNREPORTED);
+  });
+
+  it('returns PAUSED without looking up the deposit when paused', async () => {
+    const client = makeClient({ paused: true, variant: 'Reported' });
+    const status = await getBasculeDepositStatus({ client, payload: PAYLOAD });
+    expect(status).toBe(SuiBasculeDepositStatus.PAUSED);
+    expect(client.getDynamicFieldObject).not.toHaveBeenCalled();
+  });
+});

package/src/web3Sdk/getBasculeDepositStatus/getBasculeDepositStatus.ts

@@ -0,0 +1,300 @@
+import { DEFAULT_ENV, Env } from '@lombard.finance/sdk-common';
+import type { SuiClient } from '@mysten/sui/client';
+import { keccak_256 } from '@noble/hashes/sha3';
+
+import { getConfig } from '../../const';
+
+type Not0xPrefixedHex = string;
+
+/**
+ * The Bascule deposit status on Sui, mirroring the EVM SDK's
+ * `BasculeDepositStatus`. `PAUSED` is Sui-specific: the on-chain
+ * `validate_withdrawal` aborts for every deposit while the Bascule is paused,
+ * so there is no point inspecting an individual deposit.
+ */
+export enum SuiBasculeDepositStatus {
+  /** Deposit is not reported yet (or unknown) — minting would abort. */
+  UNREPORTED = 'UNREPORTED',
+  /** Deposit is reported and may be minted. */
+  REPORTED = 'REPORTED',
+  /** Deposit has already been withdrawn (already minted). */
+  WITHDRAWN = 'WITHDRAWN',
+  /** The Bascule is paused — no deposit can be minted right now. */
+  PAUSED = 'PAUSED',
+}
+
+// On-chain DepositState enum variant names (see bascule::bascule::DepositState).
+const DEPOSIT_REPORTED = 'Reported';
+const DEPOSIT_WITHDRAWN = 'Withdrawn';
+
+// Mint payload layout (matches consortium::payload_decoder::decode_mint_payload):
+// a 4-byte action selector followed by 5 big-endian 32-byte words:
+// to_chain || recipient || amount || tx_id || vout.
+const SELECTOR_LEN = 4;
+const WORD_LEN = 32;
+const WORDS = 5;
+const PAYLOAD_LEN = SELECTOR_LEN + WORDS * WORD_LEN;
+
+export interface IGetSuiBasculeDepositStatusParameters {
+  /** Sui RPC client. */
+  client: SuiClient;
+  /**
+   * The raw mint payload (hex, with or without `0x` prefix), see
+   * `Deposit.rawPayload`.
+   */
+  payload: Not0xPrefixedHex;
+  /** The optional environment identifier (defaults to the SDK default). */
+  env?: Env;
+}
+
+/**
+ * Returns the Bascule deposit status for a Sui mint payload, so a claim can be
+ * pre-flighted before submitting the transaction (the on-chain
+ * `bascule::validate_withdrawal` would otherwise abort the mint).
+ *
+ * The deposit id is derived exactly as `bascule::bascule::to_deposit_id` does
+ * on-chain (and as `sui-claimer` derives it server-side):
+ *
+ *   keccak256( zero32 || 0x03,0x53,0x55,0x49 || to || u64_le(amount) || tx_id || u32_le(index) )
+ *
+ * read back as a little-endian u256.
+ */
+export async function getBasculeDepositStatus({
+  client,
+  payload,
+  env = DEFAULT_ENV,
+}: IGetSuiBasculeDepositStatusParameters): Promise<SuiBasculeDepositStatus> {
+  const { bascule } = getConfig(env);
+
+  // No Bascule configured for this env — treat as reported (parity with the EVM
+  // SDK, which returns REPORTED when the bascule address is the zero address).
+  if (!bascule) {
+    return SuiBasculeDepositStatus.REPORTED;
+  }
+
+  const depositId = deriveDepositId(payload);
+  const { paused, depositTableId } = await getBasculeState(client, bascule);
+
+  // While paused, validate_withdrawal aborts for every deposit, so there is no
+  // point looking up the individual deposit status.
+  if (paused) {
+    return SuiBasculeDepositStatus.PAUSED;
+  }
+
+  const status = await getDepositStatus(client, depositTableId, depositId);
+  switch (status) {
+    case DEPOSIT_REPORTED:
+      return SuiBasculeDepositStatus.REPORTED;
+    case DEPOSIT_WITHDRAWN:
+      return SuiBasculeDepositStatus.WITHDRAWN;
+    default:
+      // Not found, or an unrecognized status — not mintable.
+      return SuiBasculeDepositStatus.UNREPORTED;
+  }
+}
+
+interface BasculeState {
+  depositTableId: string;
+  paused: boolean;
+}
+
+/**
+ * Reads the shared Bascule object and extracts the deposit-history table id and
+ * the pause flag.
+ */
+async function getBasculeState(
+  client: SuiClient,
+  basculeAddress: string,
+): Promise<BasculeState> {
+  const resp = await client.getObject({
+    id: basculeAddress,
+    options: { showContent: true },
+  });
+
+  const content = resp.data?.content;
+  if (!content || content.dataType !== 'moveObject') {
+    throw new Error(`Bascule object ${basculeAddress} has no content`);
+  }
+
+  const fields = content.fields as Record<string, unknown>;
+
+  const paused = fields.mIsPaused;
+  if (typeof paused !== 'boolean') {
+    throw new Error(
+      `Bascule object ${basculeAddress} has invalid mIsPaused field`,
+    );
+  }
+
+  const depositTableId = nestedString(fields, [
+    'mDepositHistory',
+    'fields',
+    'id',
+    'id',
+  ]);
+
+  return { depositTableId, paused };
+}
+
+/**
+ * Looks up a deposit id in the Bascule deposit-history table. Returns the
+ * DepositState variant name (`Reported`/`Withdrawn`) or `undefined` if there is
+ * no entry. A missing dynamic field is surfaced by the RPC as an error / empty
+ * data rather than a thrown transport error.
+ */
+async function getDepositStatus(
+  client: SuiClient,
+  tableId: string,
+  depositId: string,
+): Promise<string | undefined> {
+  const resp = await client.getDynamicFieldObject({
+    parentId: tableId,
+    name: { type: 'u256', value: depositId },
+  });
+
+  const content = resp.data?.content;
+  if (!content || content.dataType !== 'moveObject') {
+    return undefined;
+  }
+
+  const fields = content.fields as Record<string, unknown>;
+  const value = fields.value;
+  if (value && typeof value === 'object' && 'variant' in value) {
+    const variant = (value as { variant: unknown }).variant;
+    if (typeof variant === 'string') {
+      return variant;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Derives the Bascule deposit id (a u256, returned as a decimal string) exactly
+ * as `bascule::bascule::to_deposit_id` does on-chain.
+ */
+export function deriveDepositId(payloadHex: Not0xPrefixedHex): string {
+  const raw = hexToBytes(payloadHex);
+  if (raw.length !== PAYLOAD_LEN) {
+    throw new Error(
+      `Invalid mint payload length ${raw.length}, want ${PAYLOAD_LEN}`,
+    );
+  }
+
+  const body = raw.subarray(SELECTOR_LEN);
+  const word = (i: number) => body.subarray(i * WORD_LEN, (i + 1) * WORD_LEN);
+  // word(0) = to_chain (unused for the deposit id)
+
+  const to = word(1); // recipient, 32-byte big-endian address bytes
+  const amount = bigEndianWordToUint(word(2), 8, 'amount'); // u64
+  // tx_id = bcs::to_bytes(&txid_u256): the payload word is big-endian, BCS of a
+  // u256 is little-endian, so bascule sees the word reversed.
+  const txId = reversed(word(3));
+  const index = bigEndianWordToUint(word(4), 4, 'vout'); // u32
+
+  const preimage = concatBytes(
+    new Uint8Array(32), // CODESYNC(non-evm-prefix): 32 zero bytes
+    Uint8Array.from([0x03, 0x53, 0x55, 0x49]), // CODESYNC(sui-unique-id)
+    to,
+    uintToLeBytes(amount, 8),
+    txId,
+    uintToLeBytes(index, 4),
+  );
+
+  const digest = keccak_256(preimage);
+
+  // peel_u256 reads the digest as a little-endian u256.
+  let value = 0n;
+  for (let i = digest.length - 1; i >= 0; i--) {
+    value = (value << 8n) | BigInt(digest[i]);
+  }
+  return value.toString();
+}
+
+// --- byte helpers -----------------------------------------------------------
+
+function hexToBytes(hex: string): Uint8Array {
+  const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+  if (clean.length % 2 !== 0) {
+    throw new Error('Invalid payload hex: odd length');
+  }
+  // Reject any non-hex character outright, matching Go's strict
+  // hex.DecodeString. A per-byte Number.parseInt would silently accept a
+  // malformed low nibble (e.g. 'ag' -> 0x0a), yielding a wrong deposit id.
+  if (!/^[0-9a-fA-F]*$/.test(clean)) {
+    throw new Error('Invalid payload hex: non-hex characters');
+  }
+  const out = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+/**
+ * Mirrors `u256.try_as_u64()/try_as_u32()`: the value must fit in `byteWidth`
+ * bytes, i.e. the upper bytes of the big-endian word must be zero.
+ */
+function bigEndianWordToUint(
+  word: Uint8Array,
+  byteWidth: number,
+  label: string,
+): bigint {
+  for (let i = 0; i < word.length - byteWidth; i++) {
+    if (word[i] !== 0) {
+      throw new Error(`${label} does not fit in u${byteWidth * 8}`);
+    }
+  }
+  let value = 0n;
+  for (let i = word.length - byteWidth; i < word.length; i++) {
+    value = (value << 8n) | BigInt(word[i]);
+  }
+  return value;
+}
+
+function uintToLeBytes(value: bigint, byteWidth: number): Uint8Array {
+  const out = new Uint8Array(byteWidth);
+  let v = value;
+  for (let i = 0; i < byteWidth; i++) {
+    out[i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  return out;
+}
+
+function reversed(bytes: Uint8Array): Uint8Array {
+  const out = new Uint8Array(bytes.length);
+  for (let i = 0; i < bytes.length; i++) {
+    out[i] = bytes[bytes.length - 1 - i];
+  }
+  return out;
+}
+
+function concatBytes(...parts: Uint8Array[]): Uint8Array {
+  const total = parts.reduce((n, p) => n + p.length, 0);
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const p of parts) {
+    out.set(p, off);
+    off += p.length;
+  }
+  return out;
+}
+
+function nestedString(
+  fields: Record<string, unknown>,
+  keys: string[],
+): string {
+  let cur: unknown = fields;
+  for (let i = 0; i < keys.length; i++) {
+    if (cur === null || typeof cur !== 'object') {
+      throw new Error(`key "${keys[i - 1]}" is not an object`);
+    }
+    cur = (cur as Record<string, unknown>)[keys[i]];
+    if (cur === undefined) {
+      throw new Error(`missing key "${keys[i]}"`);
+    }
+  }
+  if (typeof cur !== 'string') {
+    throw new Error(`key "${keys[keys.length - 1]}" is not a string`);
+  }
+  return cur;
+}

package/src/web3Sdk/getBasculeDepositStatus/index.ts

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