feat(sdk-coin-starknet): implement Starknet SDK module CECHO-924

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: shubham-damkondwar

modules/sdk-coin-starknet/.eslintignore

@@ -0,0 +1,4 @@
+node_modules
+.idea
+public
+dist

modules/sdk-coin-starknet/.eslintrc.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../.eslintrc.json",
+  "rules": {
+    "@typescript-eslint/explicit-module-boundary-types": "error",
+    "indent": "off"
+  }
+}

modules/sdk-coin-starknet/.mocharc.yml

@@ -0,0 +1,8 @@
+require: 'tsx'
+timeout: 120000
+reporter: 'min'
+reporter-option:
+  - 'cdn=true'
+  - 'json=false'
+exit: true
+spec: ['test/unit/**/*.ts']

modules/sdk-coin-starknet/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@bitgo/sdk-coin-starknet",
+  "version": "1.0.0",
+  "description": "BitGo SDK coin library for Starknet",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "scripts": {
+    "build": "npm run prepare",
+    "build-ts": "yarn tsc --build --incremental --verbose .",
+    "fmt": "prettier --write .",
+    "check-fmt": "prettier --check '**/*.{ts,js,json}'",
+    "clean": "rm -r ./dist",
+    "lint": "eslint --quiet .",
+    "prepare": "npm run build-ts",
+    "test": "npm run coverage",
+    "coverage": "nyc -- npm run unit-test",
+    "unit-test": "mocha"
+  },
+  "author": "BitGo SDK Team <sdkteam@bitgo.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BitGo/BitGoJS.git",
+    "directory": "modules/sdk-coin-starknet"
+  },
+  "lint-staged": {
+    "*.{js,ts}": [
+      "yarn prettier --write",
+      "yarn eslint --fix"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "nyc": {
+    "extension": [
+      ".ts"
+    ]
+  },
+  "dependencies": {
+    "@bitgo/sdk-core": "^36.44.0",
+    "@bitgo/sdk-lib-mpc": "^10.12.0",
+    "@bitgo/secp256k1": "^1.11.0",
+    "@bitgo/statics": "^58.39.0",
+    "@scure/starknet": "^1.1.0",
+    "bignumber.js": "^9.1.1"
+  },
+  "devDependencies": {
+    "@bitgo/sdk-api": "^1.79.2",
+    "@bitgo/sdk-test": "^9.1.42"
+  },
+  "gitHead": "18e460ddf02de2dbf13c2aa243478188fb539f0c",
+  "files": [
+    "dist"
+  ]
+}

modules/sdk-coin-starknet/src/index.ts

@@ -0,0 +1,3 @@
+export * from './lib';
+export * from './starknet';
+export * from './register';

modules/sdk-coin-starknet/src/lib/constants.ts

@@ -0,0 +1,39 @@
+export const DECIMALS = 18;
+
+// OZ EthAccountUpgradeable class hash (v0.17.0) — secp256k1 signature verification
+export const OZ_ETH_ACCOUNT_CLASS_HASH = '0x3940bc18abf1df6bc540cabadb1cad9486c6803b95801e57b6153ae21abfe06';
+
+// STRK token contract (same on both mainnet and sepolia)
+export const STRK_TOKEN_CONTRACT = '0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d';
+
+// ETH token contract on Starknet
+export const ETH_TOKEN_CONTRACT = '0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7';
+
+// Chain IDs
+export const MAINNET_CHAIN_ID = '0x534e5f4d41494e'; // SN_MAIN
+export const TESTNET_CHAIN_ID = '0x534e5f5345504f4c4941'; // SN_SEPOLIA
+
+// RPC endpoints
+export const MAINNET_RPC_URL = 'https://starknet-mainnet-rpc.publicnode.com/';
+export const TESTNET_RPC_URL = 'https://starknet-sepolia-rpc.publicnode.com/';
+
+// felt252 max value (2^251 + 17 * 2^192 + 1)
+export const FELT_MAX = (1n << 251n) + 17n * (1n << 192n) + 1n;
+
+// u256 split mask (128 bits)
+export const MASK_128 = (1n << 128n) - 1n;
+
+// Contract address bound: 2^251 - 256
+export const ADDR_BOUND = 2n ** 251n - 256n;
+
+// encodeShortString('STARKNET_CONTRACT_ADDRESS')
+export const CONTRACT_ADDRESS_PREFIX = 0x535441524b4e45545f434f4e54524143545f41444452455353n;
+
+// Default resource bounds for EthAccount (secp256k1 verification is gas-heavy ~24M L2 gas)
+export const DEFAULT_RESOURCE_BOUNDS = {
+  l2_gas: { max_amount: 30000000n, max_price_per_unit: 100000000000n },
+  l1_gas: { max_amount: 0n, max_price_per_unit: 100000000000000n },
+  l1_data_gas: { max_amount: 1000n, max_price_per_unit: 10000000000n },
+};
+
+export const ROOT_PATH = 'm/0';

modules/sdk-coin-starknet/src/lib/iface.ts

@@ -0,0 +1,81 @@
+import {
+  TransactionExplanation as BaseTransactionExplanation,
+  TransactionType as BitGoTransactionType,
+  TssVerifyAddressOptions,
+} from '@bitgo/sdk-core';
+
+export enum StarknetTransactionType {
+  INVOKE = 'INVOKE',
+  DEPLOY_ACCOUNT = 'DEPLOY_ACCOUNT',
+}
+
+export interface StarknetCall {
+  contractAddress: string;
+  entrypoint: string;
+  calldata: string[];
+}
+
+export interface StarknetResourceBounds {
+  l2_gas: { max_amount: bigint; max_price_per_unit: bigint };
+  l1_gas: { max_amount: bigint; max_price_per_unit: bigint };
+  l1_data_gas: { max_amount: bigint; max_price_per_unit: bigint };
+}
+
+export interface StarknetTransactionData {
+  senderAddress: string;
+  calls: StarknetCall[];
+  nonce?: string;
+  chainId: string;
+  resourceBounds?: StarknetResourceBounds;
+  transactionType: StarknetTransactionType;
+  signature?: string[];
+  transactionHash?: string;
+  // For token transfers
+  receiverAddress?: string;
+  amount?: string;
+  tokenContract?: string;
+}
+
+export interface TxData {
+  id?: string;
+  sender: string;
+  senderPublicKey?: string;
+  recipient?: string;
+  amount?: string;
+  fee?: string;
+  nonce?: string;
+  type?: BitGoTransactionType;
+}
+
+export interface StarknetTransactionExplanation extends BaseTransactionExplanation {
+  sender?: string;
+  type?: BitGoTransactionType;
+}
+
+export interface TransactionHexParams {
+  transactionHex: string;
+  signableHex?: string;
+}
+
+export interface TssVerifyStarknetAddressOptions extends TssVerifyAddressOptions {
+  rootAddress?: string;
+}
+
+export interface RecoveryOptions {
+  userKey: string;
+  backupKey: string;
+  bitgoKey?: string;
+  rootAddress?: string;
+  recoveryDestination: string;
+  walletPassphrase: string;
+}
+
+export interface RecoveryTransaction {
+  id: string;
+  tx: string;
+}
+
+export interface UnsignedSweepRecoveryTransaction {
+  txHex: string;
+  coin: string;
+}

modules/sdk-coin-starknet/src/lib/index.ts

@@ -0,0 +1,9 @@
+import * as Utils from './utils';
+export * from './iface';
+
+export { KeyPair } from './keyPair';
+export { TransactionBuilder } from './transactionBuilder';
+export { TransferBuilder } from './transferBuilder';
+export { TransactionBuilderFactory } from './transactionBuilderFactory';
+export { Transaction } from './transaction';
+export { Utils };

modules/sdk-coin-starknet/src/lib/keyPair.ts

@@ -0,0 +1,48 @@
+import {
+  DefaultKeys,
+  KeyPairOptions,
+  Secp256k1ExtendedKeyPair,
+  isSeed,
+  isPrivateKey,
+  isPublicKey,
+} from '@bitgo/sdk-core';
+import utils from './utils';
+import { bip32 } from '@bitgo/secp256k1';
+import { randomBytes } from 'crypto';
+
+const DEFAULT_SEED_SIZE_BYTES = 16;
+
+export class KeyPair extends Secp256k1ExtendedKeyPair {
+  constructor(source?: KeyPairOptions) {
+    super(source);
+    if (!source) {
+      const seed = randomBytes(DEFAULT_SEED_SIZE_BYTES);
+      this.hdNode = bip32.fromSeed(seed);
+    } else if (isSeed(source)) {
+      this.hdNode = bip32.fromSeed(source.seed);
+    } else if (isPrivateKey(source)) {
+      super.recordKeysFromPrivateKey(source.prv);
+    } else if (isPublicKey(source)) {
+      super.recordKeysFromPublicKey(source.pub);
+    } else {
+      throw new Error('Invalid key pair options');
+    }
+
+    if (this.hdNode) {
+      this.keyPair = Secp256k1ExtendedKeyPair.toKeyPair(this.hdNode);
+    }
+  }
+
+  /** @inheritdoc */
+  getKeys(): DefaultKeys {
+    return {
+      pub: this.getPublicKey({ compressed: true }).toString('hex'),
+      prv: this.getPrivateKey()?.toString('hex'),
+    };
+  }
+
+  /** @inheritdoc */
+  getAddress(): string {
+    return utils.getAddressFromPublicKey(this.getKeys().pub);
+  }
+}

modules/sdk-coin-starknet/src/lib/transaction.ts

@@ -0,0 +1,120 @@
+import {
+  BaseKey,
+  BaseTransaction,
+  TransactionRecipient,
+  TransactionType,
+  InvalidTransactionError,
+} from '@bitgo/sdk-core';
+import { BaseCoin as CoinConfig } from '@bitgo/statics';
+import { StarknetTransactionData, StarknetTransactionType, StarknetTransactionExplanation, TxData } from './iface';
+import utils from './utils';
+
+export class Transaction extends BaseTransaction {
+  protected _starknetTransactionData!: StarknetTransactionData;
+  protected _signedTransaction?: string;
+
+  constructor(_coinConfig: Readonly<CoinConfig>) {
+    super(_coinConfig);
+  }
+
+  get starknetTransactionData(): StarknetTransactionData {
+    return this._starknetTransactionData;
+  }
+
+  set starknetTransactionData(data: StarknetTransactionData) {
+    this._starknetTransactionData = data;
+  }
+
+  get signedTransaction(): string | undefined {
+    return this._signedTransaction;
+  }
+
+  set signedTransaction(tx: string) {
+    this._signedTransaction = tx;
+  }
+
+  async fromRawTransaction(rawTransaction: string): Promise<void> {
+    try {
+      const buffer = Buffer.from(rawTransaction, 'hex');
+      const jsonString = buffer.toString('utf-8');
+      const parsed = JSON.parse(jsonString);
+
+      this._starknetTransactionData = {
+        senderAddress: parsed.senderAddress,
+        calls: parsed.calls || [],
+        nonce: parsed.nonce,
+        chainId: parsed.chainId,
+        transactionType: parsed.transactionType || StarknetTransactionType.INVOKE,
+        signature: parsed.signature,
+        transactionHash: parsed.transactionHash,
+        receiverAddress: parsed.receiverAddress,
+        amount: parsed.amount,
+        tokenContract: parsed.tokenContract,
+      };
+
+      if (parsed.signature && parsed.signature.length > 0) {
+        this._signedTransaction = rawTransaction;
+      }
+
+      utils.validateRawTransaction(this._starknetTransactionData);
+      this._id = parsed.transactionHash || '';
+    } catch (error) {
+      throw new InvalidTransactionError(`Invalid transaction: ${error.message}`);
+    }
+  }
+
+  /** @inheritdoc */
+  toJson(): TxData {
+    if (!this._starknetTransactionData) {
+      throw new InvalidTransactionError('Empty transaction');
+    }
+    return {
+      id: this._id,
+      sender: this._starknetTransactionData.senderAddress,
+      recipient: this._starknetTransactionData.receiverAddress,
+      amount: this._starknetTransactionData.amount,
+      nonce: this._starknetTransactionData.nonce,
+      type: TransactionType.Send,
+    };
+  }
+
+  /** @inheritDoc */
+  explainTransaction(): StarknetTransactionExplanation {
+    const result = this.toJson();
+    const displayOrder = ['id', 'outputAmount', 'changeAmount', 'outputs', 'changeOutputs', 'fee'];
+    const outputs: TransactionRecipient[] = [];
+
+    if (result.recipient && result.amount) {
+      outputs.push({
+        address: result.recipient,
+        amount: result.amount,
+      });
+    }
+
+    return {
+      displayOrder,
+      id: this.id,
+      outputs,
+      outputAmount: result.amount || '0',
+      fee: { fee: '0' },
+      type: result.type,
+      changeOutputs: [],
+      changeAmount: '0',
+    };
+  }
+
+  /** @inheritdoc */
+  toBroadcastFormat(): string {
+    const data = this._starknetTransactionData;
+    if (!data) {
+      throw new InvalidTransactionError('Empty transaction');
+    }
+    const json = JSON.stringify(data);
+    return Buffer.from(json, 'utf-8').toString('hex');
+  }
+
+  /** @inheritdoc */
+  canSign(_key: BaseKey): boolean {
+    return true;
+  }
+}