@lombard.finance/ts-verifier 0.1.0 → 0.1.2

package/.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: Publish
+run-name: Publish ts-verifier from ${{ github.ref_name }}
+
+on:
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: [self-hosted]
+    environment: production
+    container:
+      image: ${{ vars.AWS_ECR_REGISTRY }}/library/alpine-git-node-aws:latest
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}-publish
+      cancel-in-progress: true
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.ref || github.sha }}
+
+      - name: Allow Git to access repo
+        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+      - name: Debug Git status
+        run: |
+          echo "PWD: $(pwd)"
+          ls -la
+          git status
+
+      - name: Set Git identity
+        run: |
+          git config user.name "${{ github.actor }}"
+          git config user.email "${{ github.actor }}@users.noreply.github.com"
+          echo "✅ Git identity configured successfully."
+
+      - name: Setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      - name: Build package
+        run: yarn build
+
+      - name: Configure registry
+        working-directory: ./
+        run: |
+          npm config set access public -ws=false -iwr
+          npm config set //registry.npmjs.org/:_authToken ${{ secrets.NPMJS_TOKEN }} -ws=false -iwr
+
+      - name: Publish
+        working-directory: ./
+        run: npm publish

package/.nvmrc

@@ -0,0 +1 @@
+22.14.0

package/CODEOWNERS

@@ -0,0 +1,2 @@
+# Restrict any changes to GitHub workflow files without approval. This is required to protect sensitive NPM token.
+/.github/workflows/ @megatron757 @fruit37 @le0n229

package/README.md

@@ -28,7 +28,7 @@ yarn global add ts-node
 The library can be used very simply:
 
 ```bash
-ts-node verifier.ts <blockchain> <destination_address>
+ts-node src/verifier.ts <blockchain> <destination_address>
 ```
 
 Possible options for blockchain are:
@@ -37,15 +37,54 @@ Possible options for blockchain are:
 - `bsc`
 - `base`
 - `sui`
+- `sonic`
+- `ink`
+- `solana`
+- `katana`
+
+You can also run an example:
+```bash
+ts-node src/example.ts
+```
 
 The library will query the Lombard API for deposit addresses, and then compute them internally to see if they match. For each deposit address linked to your destination address, the binary will attempt to match them, printing out 'match' or 'mismatch' in either case, and printing both addresses (fetched and derived) in all cases so that you may double-check the result yourself. It will look something like this:
 
 ```bash
-$ ts-node verifier.ts ethereum 0x564974801D2ffBE736Ed59C9bE39F6c0A4274aE6
-Checking for address bc1qu6mwr50akfpfwjes4nh53taexuhzt6gsf8ysnn:
-- partner code: lombard
-- nonce: 0
-Address fetched from API:       bc1qu6mwr50akfpfwjes4nh53taexuhzt6gsf8ysnn
-Address computed:               bc1qu6mwr50akfpfwjes4nh53taexuhzt6gsf8ysnn
-Addresses match! 
+$ ts-node src/verifier.ts ethereum 0x564974801D2ffBE736Ed59C9bE39F6c0A4274aE6                
+Address 1: bc1qu6mwr50akfpfwjes4nh53taexuhzt6gsf8ysnn
+Metadata used:
+  - To Address: 0x564974801D2ffBE736Ed59C9bE39F6c0A4274aE6
+  - Blockchain: ethereum
+  - Partner Code: lombard
+  - Nonce: 0
+  - Aux Version: 0
+  - Token Address: 0x8236a87084f8b84306f72007f36f2618a5634494
+Addresses match!
 ```
+
+or like this:
+```bash
+$  ts-node src/verifier.ts solana 74AYR1KpkXw3RYHia4KDGSGqNjGgEDWjLtdEvAgHcLu2      
+Address 1: bc1qhvquxlsegnyc3fsuckvs8qqm28puu23mycdh7u
+Metadata used:
+  - To Address: 74AYR1KpkXw3RYHia4KDGSGqNjGgEDWjLtdEvAgHcLu2
+  - Blockchain: solana
+  - Partner Code: lombard
+  - Nonce: 0
+  - Aux Version: 0
+  - Token Address: LomP48F7bLbKyMRHHsDVt7wuHaUQvQnVVspjcbfuAek
+Addresses match!
+
+------------------------------------------------------------
+
+Address 2: bc1qast400qh327zr6gg8s0n0t05gu9q0z7utfmh00
+Metadata used:
+  - To Address: 74AYR1KpkXw3RYHia4KDGSGqNjGgEDWjLtdEvAgHcLu2
+  - Blockchain: solana
+  - Partner Code: okx
+  - Nonce: 0
+  - Aux Version: 0
+  - Token Address: LomP48F7bLbKyMRHHsDVt7wuHaUQvQnVVspjcbfuAek
+Addresses match!
+```
+

package/package.json

@@ -1,18 +1,40 @@
 {
   "name": "@lombard.finance/ts-verifier",
   "description": "Lombard Deposit Address Verifier",
-  "version": "0.1.0",
-  "homepage": "/",
+  "version": "0.1.2",
+  "license": "MIT",
   "scripts": {
+    "build": "yarn types && vite build && yarn build-types",
+    "build-types": "tsc -b tsconfig.build.json",
+    "types": "tsc --noEmit",
     "format": "prettier *.js \"*{.js,.ts}\" -w",
     "lint": "prettier *.js \"*{.js,.ts}\" --check"
   },
+  "engines": {
+    "node": ">= 22.14.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "type": "module",
+  "types": "./src/index.ts",
   "dependencies": {
-    "@types/node": "^22.13.10",
-    "@types/secp256k1": "^4.0.6",
+    "@solana/spl-token": "^0.4.13",
+    "@solana/web3.js": "^1.98.2",
     "bitcoinjs-lib": "^6.1.7",
-    "prettier": "^3.5.3",
+    "bs58": "^6.0.0",
     "secp256k1": "^5.0.1",
-    "typescript": "^5.8.2"
+    "typescript": "^5.8.3",
+    "vite": "^6.3.5"
+  },
+  "devDependencies": {
+    "@types/bs58": "^5.0.0",
+    "@types/node": "^22.13.10",
+    "@types/secp256k1": "^4.0.6",
+    "prettier": "^3.5.3"
   }
 }

package/src/api.ts

@@ -0,0 +1,122 @@
+import bs58 from "bs58";
+import { Networks, NetworkParams } from "./bitcoin";
+import { Address, BlockchainConfig, Ecosystem } from "./chain-id";
+
+// Get Addresses by Destination API
+const MAINNET_URL =
+  "https://mainnet.prod.lombard.finance/api/v1/address/destination/";
+const GASTALD_URL =
+  "https://gastald-testnet.prod.lombard.finance/api/v1/address/destination/";
+
+// API Response interfaces
+export interface DepositMetadata {
+  to_address: string;
+  to_blockchain: string;
+  referral: string;
+  nonce?: number;
+  token_address?: string;
+  aux_version?: number;
+}
+
+export interface AddressInfo {
+  btc_address: string;
+  type: string;
+  deposit_metadata: DepositMetadata;
+  created_at: string;
+  deprecated: boolean;
+}
+
+export interface ApiResponse {
+  addresses: AddressInfo[];
+}
+
+export class APIError extends Error {
+  constructor(
+    message: string,
+    public statusCode?: number,
+  ) {
+    super(message);
+    this.name = "APIError";
+  }
+}
+
+export interface AddressesResponse {
+  addresses: {
+    btcAddress: string;
+    toAddress: string;
+    referralId: string;
+    nonce: number;
+    auxVersion: number;
+    tokenAddress: Address;
+  }[];
+}
+
+// Fetch address data from the Lombard API
+export async function fetchAddressMetadata(
+  chainConfig: BlockchainConfig,
+  toAddress: string,
+  network: NetworkParams,
+): Promise<AddressesResponse> {
+  try {
+    const url = `${network === Networks.mainnet ? MAINNET_URL : GASTALD_URL}${chainConfig.name}/${toAddress}`;
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      throw new APIError(
+        `API request failed with status: ${response.status}`,
+        response.status,
+      );
+    }
+
+    const data = (await response.json()) as ApiResponse;
+
+    if (!data.addresses?.length) {
+      throw new APIError("No addresses returned from API");
+    }
+
+    const nonDeprecatedAddresses = data.addresses.filter(
+      (addr) => !addr.deprecated,
+    );
+
+    if (!nonDeprecatedAddresses.length) {
+      throw new APIError("No non-deprecated addresses found");
+    }
+
+    const addresses = await Promise.all(
+      nonDeprecatedAddresses.map(async (addr) => {
+        let tokenAddress = chainConfig.stlbtc;
+        if (addr.deposit_metadata.token_address != undefined) {
+          tokenAddress =
+            chainConfig.ecosystem === Ecosystem.Solana
+              ? Buffer.from(bs58.decode(addr.deposit_metadata.token_address))
+              : Buffer.from(
+                  trimHexPrefix(addr.deposit_metadata.token_address),
+                  "hex",
+                );
+        }
+
+        return {
+          btcAddress: addr.btc_address,
+          toAddress: addr.deposit_metadata.to_address,
+          referralId: addr.deposit_metadata.referral,
+          nonce: addr.deposit_metadata.nonce ?? 0,
+          auxVersion: addr.deposit_metadata.aux_version ?? 0,
+          tokenAddress: tokenAddress,
+        };
+      }),
+    );
+
+    return { addresses };
+  } catch (error: unknown) {
+    if (error instanceof APIError) {
+      throw error;
+    }
+
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new APIError(`Failed to fetch address data: ${errorMessage}`);
+  }
+}
+
+export function trimHexPrefix(hex: string): string {
+  return hex.startsWith("0x") ? hex.substring(2) : hex;
+}

package/src/aux-data.ts

@@ -0,0 +1,49 @@
+import * as crypto from "crypto";
+import { sha256, BitcoinAddressError } from "./bitcoin";
+
+const DEPOSIT_AUX_TAG = "LombardDepositAux";
+const DEPOSIT_AUX_V0 = 0;
+const DEPOSIT_AUX_V1 = 1;
+const SUPPORTED_VERSIONS = new Set([DEPOSIT_AUX_V0, DEPOSIT_AUX_V1]);
+const MAX_REFERRAL_ID_SIZE = 256;
+
+/**
+ * Creates a tagged hasher used for deposit aux data
+ */
+function auxDepositHasher(): crypto.Hash {
+  const tag = sha256(Buffer.from(DEPOSIT_AUX_TAG));
+
+  const h = crypto.createHash("sha256");
+  h.update(tag);
+  h.update(tag);
+
+  return h;
+}
+
+export function computeAuxData(
+  nonce: number,
+  referrerId: Buffer | Uint8Array,
+  version: number,
+): Buffer {
+  if (referrerId.length > MAX_REFERRAL_ID_SIZE) {
+    throw new BitcoinAddressError(
+      `Wrong size for referrerId (got ${referrerId.length}, want not greater than ${MAX_REFERRAL_ID_SIZE})`,
+    );
+  }
+
+  if (!SUPPORTED_VERSIONS.has(version)) {
+    throw new BitcoinAddressError("version is not supported");
+  }
+
+  const nonceBytes = Buffer.alloc(4);
+  nonceBytes.writeUInt32BE(nonce, 0);
+
+  const h = auxDepositHasher();
+
+  // Version0
+  h.update(Buffer.from([version]));
+  h.update(nonceBytes);
+  h.update(Buffer.from(referrerId));
+
+  return h.digest();
+}

package/src/bitcoin.ts

@@ -0,0 +1,62 @@
+import * as bitcoin from "bitcoinjs-lib";
+import * as crypto from "crypto";
+
+// Network Parameters
+export interface NetworkParams {
+  messagePrefix: string;
+  bech32: string;
+  bip32: {
+    public: number;
+    private: number;
+  };
+  pubKeyHash: number;
+  scriptHash: number;
+  wif: number;
+}
+
+// Networks
+export const Networks = {
+  mainnet: bitcoin.networks.bitcoin,
+  signet: {
+    messagePrefix: "\x18Bitcoin Signed Message:\n",
+    bech32: "tb",
+    bip32: {
+      public: 0x043587cf,
+      private: 0x04358394,
+    },
+    pubKeyHash: 0x6f,
+    scriptHash: 0xc4,
+    wif: 0xef,
+  } as NetworkParams,
+};
+
+// Error classes
+export class BitcoinAddressError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BitcoinAddressError";
+  }
+}
+
+/**
+ * Converts a public key to a segwit address
+ */
+export function pubkeyToSegwitAddr(
+  publicKey: Buffer,
+  network: NetworkParams,
+): string {
+  const publicKeyHash = bitcoin.crypto.hash160(publicKey);
+  const address = bitcoin.payments.p2wpkh({
+    hash: publicKeyHash,
+    network: network,
+  });
+
+  return address.address!;
+}
+
+/**
+ * Helper function to create a SHA-256 hash
+ */
+export function sha256(data: Buffer | Uint8Array): Buffer {
+  return crypto.createHash("sha256").update(data).digest();
+}

package/src/chain-id.ts

@@ -0,0 +1,280 @@
+import bs58 from "bs58";
+
+// Address type
+export type Address = Buffer;
+
+// ChainId type
+export type LChainId = Buffer;
+
+// Blockchain Types
+export enum Ecosystem {
+  EVM = "evm",
+  Sui = "sui",
+  Solana = "solana",
+}
+
+export enum SupportedBlockchains {
+  Ethereum = "ethereum",
+  Base = "base",
+  BSC = "bsc",
+  Sui = "sui",
+  Sonic = "sonic",
+  Ink = "ink",
+  Solana = "solana",
+  Katana = "katana",
+}
+
+// Blockchain configuration map for mainnet
+export const mainnetBlockchainConfigs = new Map([
+  [
+    SupportedBlockchains.Ethereum,
+    {
+      chainId: Buffer.from(
+        "0000000000000000000000000000000000000000000000000000000000000001",
+        "hex",
+      ),
+      stlbtc: Buffer.from("8236a87084f8B84306f72007F36F2618A5634494", "hex"),
+      nativeLbtc: null,
+      name: "DESTINATION_BLOCKCHAIN_ETHEREUM",
+      ecosystem: Ecosystem.EVM,
+    },
+  ],
+
+  [
+    SupportedBlockchains.Base,
+    {
+      chainId: Buffer.from(
+        "0000000000000000000000000000000000000000000000000000000000002105",
+        "hex",
+      ),
+      stlbtc: Buffer.from("ecAc9C5F704e954931349Da37F60E39f515c11c1", "hex"),
+      nativeLbtc: null,
+      name: "DESTINATION_BLOCKCHAIN_BASE",
+      ecosystem: Ecosystem.EVM,
+    },
+  ],
+
+  [
+    SupportedBlockchains.BSC,
+    {
+      chainId: Buffer.from(
+        "0000000000000000000000000000000000000000000000000000000000000038",
+        "hex",
+      ),
+      stlbtc: Buffer.from("ecAc9C5F704e954931349Da37F60E39f515c11c1", "hex"),
+      nativeLbtc: null,
+      name: "DESTINATION_BLOCKCHAIN_BSC",
+      ecosystem: Ecosystem.EVM,
+    },
+  ],
+
+  [
+    SupportedBlockchains.Sui,
+    {
+      chainId: Buffer.from(
+        "0100000000000000000000000000000000000000000000000000000035834a8a",
+        "hex",
+      ),
+      stlbtc: Buffer.from(
+        "3e8e9423d80e1774a7ca128fccd8bf5f1f7753be658c5e645929037f7c819040",
+        "hex",
+      ),
+      nativeLbtc: null,
+      name: "DESTINATION_BLOCKCHAIN_SUI",
+      ecosystem: Ecosystem.Sui,
+    },
+  ],
+
+  [
+    SupportedBlockchains.Sonic,
+    {
+      chainId: Buffer.from(
+        "0000000000000000000000000000000000000000000000000000000000000092",
+        "hex",
+      ),
+      stlbtc: Buffer.from("ecAc9C5F704e954931349Da37F60E39f515c11c1", "hex"),
+      nativeLbtc: null,
+      name: "DESTINATION_BLOCKCHAIN_SONIC",
+      ecosystem: Ecosystem.EVM,
+    },
+  ],
+
+  [
+    SupportedBlockchains.Ink,
+    {
+      chainId: Buffer.from(
+        "000000000000000000000000000000000000000000000000000000000000def1",
+        "hex",
+      ),
+      stlbtc: Buffer.from("ecAc9C5F704e954931349Da37F60E39f515c11c1", "hex"),
+      nativeLbtc: null,
+      name: "DESTINATION_BLOCKCHAIN_INK",
+      ecosystem: Ecosystem.EVM,
+    },
+  ],
+
+  [
+    SupportedBlockchains.Solana,
+    {
+      chainId: Buffer.from(
+        "02296998a6f8e2a784db5d9f95e18fc23f70441a1039446801089879b08c7ef0",
+        "hex",
+      ),
+      stlbtc: Buffer.from(
+        bs58.decode("LomP48F7bLbKyMRHHsDVt7wuHaUQvQnVVspjcbfuAek"),
+      ),
+      nativeLbtc: null,
+      name: "DESTINATION_BLOCKCHAIN_SOLANA",
+      ecosystem: Ecosystem.Solana,
+    },
+  ],
+
+  [
+    SupportedBlockchains.Katana,
+    {
+      chainId: Buffer.from(
+        "00000000000000000000000000000000000000000000000000000000000b67d2",
+        "hex",
+      ),
+      stlbtc: Buffer.from("ecAc9C5F704e954931349Da37F60E39f515c11c1", "hex"),
+      nativeLbtc: Buffer.from(
+        "B0F70C0bD6FD87dbEb7C10dC692a2a6106817072",
+        "hex",
+      ),
+      name: "DESTINATION_BLOCKCHAIN_KATANA",
+      ecosystem: Ecosystem.EVM,
+    },
+  ],
+]);
+
+// Blockchain configuration map for Gastald testnet
+export const gastaldBlockchainConfigs = new Map([
+  [
+    SupportedBlockchains.Ethereum,
+    {
+      chainId: Buffer.from(
+        "0000000000000000000000000000000000000000000000000000000000004268",
+        "hex",
+      ),
+      stlbtc: Buffer.from("38A13AB20D15ffbE5A7312d2336EF1552580a4E2", "hex"),
+      nativeLbtc: null,
+      name: "DESTINATION_BLOCKCHAIN_ETHEREUM",
+      ecosystem: Ecosystem.EVM,
+    },
+  ],
+
+  [
+    SupportedBlockchains.Base,
+    {
+      chainId: Buffer.from(
+        "0000000000000000000000000000000000000000000000000000000000014a34",
+        "hex",
+      ),
+      stlbtc: Buffer.from("107Fc7d90484534704dD2A9e24c7BD45DB4dD1B5", "hex"),
+      nativeLbtc: null,
+      name: "DESTINATION_BLOCKCHAIN_BASE",
+      ecosystem: Ecosystem.EVM,
+    },
+  ],
+
+  [
+    SupportedBlockchains.BSC,
+    {
+      chainId: Buffer.from(
+        "0000000000000000000000000000000000000000000000000000000000000061",
+        "hex",
+      ),
+      stlbtc: Buffer.from("107Fc7d90484534704dD2A9e24c7BD45DB4dD1B5", "hex"),
+      nativeLbtc: null,
+      name: "DESTINATION_BLOCKCHAIN_BSC",
+      ecosystem: Ecosystem.EVM,
+    },
+  ],
+
+  [
+    SupportedBlockchains.Sui,
+    {
+      chainId: Buffer.from(
+        "010000000000000000000000000000000000000000000000000000004c78adac",
+        "hex",
+      ),
+      stlbtc: Buffer.from(
+        "50454d0b0fbad1288a6ab74f2e8ce0905a3317870673ab7787ebcf6f322b45fa",
+        "hex",
+      ),
+      nativeLbtc: null,
+      name: "DESTINATION_BLOCKCHAIN_SUI",
+      ecosystem: Ecosystem.Sui,
+    },
+  ],
+
+  [
+    SupportedBlockchains.Sonic,
+    {
+      chainId: Buffer.from(
+        "000000000000000000000000000000000000000000000000000000000000dede",
+        "hex",
+      ),
+      stlbtc: Buffer.from("107Fc7d90484534704dD2A9e24c7BD45DB4dD1B5", "hex"),
+      nativeLbtc: null,
+      name: "DESTINATION_BLOCKCHAIN_SONIC",
+      ecosystem: Ecosystem.EVM,
+    },
+  ],
+
+  [
+    SupportedBlockchains.Ink,
+    {
+      chainId: Buffer.from(
+        "00000000000000000000000000000000000000000000000000000000000ba5ed",
+        "hex",
+      ),
+      stlbtc: Buffer.from("107Fc7d90484534704dD2A9e24c7BD45DB4dD1B5", "hex"),
+      nativeLbtc: null,
+      name: "DESTINATION_BLOCKCHAIN_INK",
+      ecosystem: Ecosystem.EVM,
+    },
+  ],
+
+  [
+    SupportedBlockchains.Solana,
+    {
+      chainId: Buffer.from(
+        "0259db5080fc2c6d3bcf7ca90712d3c2e5e6c28f27f0dfbb9953bdb0894c03ab",
+        "hex",
+      ),
+      stlbtc: Buffer.from(
+        bs58.decode("79cscM6J9Af24TGGWcXyDf56fDLoodkyXdVy4R9aZ6C6"),
+      ),
+      nativeLbtc: null,
+      name: "DESTINATION_BLOCKCHAIN_SOLANA",
+      ecosystem: Ecosystem.Solana,
+    },
+  ],
+
+  [
+    SupportedBlockchains.Katana,
+    {
+      chainId: Buffer.from(
+        "000000000000000000000000000000000000000000000000000000000001f977",
+        "hex",
+      ),
+      stlbtc: Buffer.from("107Fc7d90484534704dD2A9e24c7BD45DB4dD1B5", "hex"),
+      nativeLbtc: Buffer.from(
+        "20eA7b8ABb4B583788F1DFC738C709a2d9675681",
+        "hex",
+      ),
+      name: "DESTINATION_BLOCKCHAIN_KATANA",
+      ecosystem: Ecosystem.EVM,
+    },
+  ],
+]);
+
+// Type definition for the config structure
+export interface BlockchainConfig {
+  chainId: LChainId;
+  stlbtc: Address;
+  nativeLbtc: Address | null;
+  name: string;
+  ecosystem: Ecosystem;
+}