@tetherto/wdk-wallet-evm 1.0.0-beta.2

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@tetherto/wdk-wallet-evm",
+  "version": "1.0.0-beta.2",
+  "description": "A simple package to manage BIP-32 wallets for evm blockchains.",
+  "keywords": [
+    "wdk",
+    "wallet",
+    "bip-32",
+    "ethereum"
+  ],
+  "author": "Tether",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/tetherto/wdk-wallet-evm.git"
+  },
+  "main": "index.js",
+  "type": "module",
+  "types": "./types",
+  "scripts": {
+    "build:types": "tsc",
+    "lint": "standard",
+    "lint:fix": "standard --fix",
+    "test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest",
+    "test:coverage": "cross-env NODE_OPTIONS=--experimental-vm-modules jest --coverage",
+    "test:integration": "cross-env NODE_OPTIONS=--experimental-vm-modules jest tests/integration",
+    "test:integration:coverage": "cross-env NODE_OPTIONS=--experimental-vm-modules jest tests/integration --coverage"
+  },
+  "dependencies": {
+    "@noble/curves": "1.9.2",
+    "@noble/hashes": "1.8.0",
+    "@noble/secp256k1": "2.2.3",
+    "@tetherto/wdk-wallet": "^1.0.0-beta.1",
+    "bare-wdk-runtime": "2.0.0",
+    "bip39": "3.1.0",
+    "ethers": "6.14.3",
+    "sodium-universal": "5.0.1"
+  },
+  "devDependencies": {
+    "@nomicfoundation/hardhat-ethers": "3.0.9",
+    "cross-env": "7.0.3",
+    "hardhat": "2.24.2",
+    "jest": "29.7.0",
+    "standard": "17.1.2",
+    "typescript": "5.8.3"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "bare": "./bare.js",
+      "default": "./index.js"
+    },
+    "./package": {
+      "default": "./package.json"
+    }
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "standard": {
+    "ignore": [
+      "bare.js",
+      "tests/**/*.js"
+    ]
+  }
+}

package/src/memory-safe/hd-node-wallet.js

@@ -0,0 +1,196 @@
+// Copyright 2024 Tether Operations Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict'
+
+import {
+  assert, assertArgument, assertPrivate, BaseWallet, computeHmac, dataSlice, defineProperties,
+  getBytes, getNumber, hexlify, isBytesLike, ripemd160, sha256
+} from 'ethers'
+
+import * as secp256k1 from '@noble/secp256k1'
+
+import MemorySafeSigningKey from './signing-key.js'
+
+const MasterSecret = new Uint8Array([66, 105, 116, 99, 111, 105, 110, 32, 115, 101, 101, 100])
+
+const HardenedBit = 0x80000000
+
+const _guard = { }
+
+function serI (index, chainCode, publicKey, privateKeyBuffer) {
+  const data = new Uint8Array(37)
+
+  if (index & HardenedBit) {
+    assert(privateKeyBuffer != null, 'cannot derive child of neutered node', 'UNSUPPORTED_OPERATION', {
+      operation: 'deriveChild'
+    })
+
+    data.set(getBytes(privateKeyBuffer), 1)
+  } else {
+    data.set(getBytes(publicKey))
+  }
+
+  for (let i = 24; i >= 0; i -= 8) { data[33 + (i >> 3)] = ((index >> (24 - i)) & 0xff) }
+  const I = getBytes(computeHmac('sha512', chainCode, data))
+
+  return { IL: I.slice(0, 32), IR: I.slice(32) }
+}
+
+function derivePath (node, path) {
+  const components = path.split('/')
+
+  assertArgument(components.length > 0, 'invalid path', 'path', path)
+
+  if (components[0] === 'm') {
+    assertArgument(node.depth === 0, `cannot derive root path (i.e. path starting with "m/") for a node at non-zero depth ${node.depth}`, 'path', path)
+    components.shift()
+  }
+
+  let result = node
+  for (let i = 0; i < components.length; i++) {
+    const component = components[i]
+
+    if (component.match(/^[0-9]+'$/)) {
+      const index = parseInt(component.substring(0, component.length - 1))
+      assertArgument(index < HardenedBit, 'invalid path index', `path[${i}]`, component)
+      result = result.deriveChild(HardenedBit + index)
+    } else if (component.match(/^[0-9]+$/)) {
+      const index = parseInt(component)
+      assertArgument(index < HardenedBit, 'invalid path index', `path[${i}]`, component)
+      result = result.deriveChild(index)
+    } else {
+      assertArgument(false, 'invalid path component', `path[${i}]`, component)
+    }
+  }
+
+  return result
+}
+
+function addToPrivateKey (privateKey, x) {
+  let carry = 0
+
+  for (let i = 31; i >= 0; i--) {
+    const sum = privateKey[i] + x[i] + carry
+    privateKey[i] = sum & 0xff
+    carry = sum >> 8
+  }
+
+  return carry > 0
+}
+
+function subtractCurveOrderFromPrivateKey (privateKey) {
+  let carry = 0
+
+  for (let i = 31; i >= 0; i--) {
+    const curveOrderByte = Number((secp256k1.CURVE.n >> BigInt(8 * (31 - i))) & 0xffn)
+    const diff = privateKey[i] - curveOrderByte - carry
+    privateKey[i] = diff < 0 ? diff + 256 : diff
+    carry = diff < 0 ? 1 : 0
+  }
+}
+
+function compareWithCurveOrder (buffer, offset = 0) {
+  for (let i = 0; i < 32; i++) {
+    const curveOrderByte = Number((secp256k1.CURVE.n >> BigInt(8 * (31 - i))) & 0xffn)
+    if (buffer[offset + i] > curveOrderByte) return 1
+    if (buffer[offset + i] < curveOrderByte) return -1
+  }
+
+  return 0
+}
+
+/** @internal */
+export default class MemorySafeHDNodeWallet extends BaseWallet {
+  constructor (guard, signingKey, parentFingerprint, chainCode, path, index, depth, mnemonic, provider) {
+    super(signingKey, provider)
+    assertPrivate(guard, _guard, 'MemorySafeHDNodeWallet')
+
+    defineProperties(this, { publicKey: signingKey.compressedPublicKey })
+
+    const fingerprint = dataSlice(ripemd160(sha256(this.publicKey)), 0, 4)
+    defineProperties(this, {
+      parentFingerprint,
+      fingerprint,
+      chainCode,
+      path,
+      index,
+      depth
+    })
+
+    defineProperties(this, { mnemonic })
+  }
+
+  connect (provider) {
+    return new MemorySafeHDNodeWallet(_guard, this.signingKey, this.parentFingerprint,
+      this.chainCode, this.path, this.index, this.depth, this.mnemonic, provider)
+  }
+
+  get privateKeyBuffer () {
+    return this.signingKey.privateKeyBuffer
+  }
+
+  get publicKeyBuffer () {
+    return this.signingKey.publicKeyBuffer
+  }
+
+  deriveChild (_index) {
+    const index = getNumber(_index, 'index')
+    assertArgument(index <= 0xffffffff, 'invalid index', 'index', index)
+
+    let path = this.path
+    if (path) {
+      path += '/' + (index & ~HardenedBit)
+      if (index & HardenedBit) { path += "'" }
+    }
+
+    const { IR, IL } = serI(index, this.chainCode, this.publicKey, this.privateKeyBuffer)
+
+    const overflow = addToPrivateKey(this.privateKeyBuffer, IL)
+
+    if (overflow || compareWithCurveOrder(this.privateKeyBuffer) >= 0) {
+      subtractCurveOrderFromPrivateKey(this.privateKeyBuffer)
+    }
+
+    const ki = new MemorySafeSigningKey(this.privateKeyBuffer)
+
+    return new MemorySafeHDNodeWallet(_guard, ki, this.fingerprint, hexlify(IR),
+      path, index, this.depth + 1, this.mnemonic, this.provider)
+  }
+
+  derivePath (path) {
+    return derivePath(this, path)
+  }
+
+  dispose () {
+    this.signingKey.dispose()
+  }
+
+  static fromSeed (seed) {
+    return MemorySafeHDNodeWallet._fromSeed(seed, null)
+  }
+
+  static _fromSeed (_seed, mnemonic) {
+    assertArgument(isBytesLike(_seed), 'invalid seed', 'seed', '[REDACTED]')
+
+    const seed = getBytes(_seed, 'seed')
+    assertArgument(seed.length >= 16 && seed.length <= 64, 'invalid seed', 'seed', '[REDACTED]')
+
+    const I = getBytes(computeHmac('sha512', MasterSecret, seed))
+    const signingKey = new MemorySafeSigningKey(I.slice(0, 32))
+
+    return new MemorySafeHDNodeWallet(_guard, signingKey, '0x00000000', hexlify(I.slice(32)),
+      'm', 0, 0, mnemonic, null)
+  }
+}

package/src/memory-safe/signing-key.js

@@ -0,0 +1,77 @@
+// Copyright 2024 Tether Operations Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict'
+
+import { hmac } from '@noble/hashes/hmac'
+import { sha256 } from '@noble/hashes/sha256'
+import * as secp256k1 from '@noble/secp256k1'
+
+import { assertArgument, dataLength, getBytesCopy, Signature, SigningKey, toBeHex } from 'ethers'
+
+// eslint-disable-next-line camelcase
+import { sodium_memzero } from 'sodium-universal'
+
+const NULL = '0x0000000000000000000000000000000000000000000000000000000000000000'
+
+secp256k1.etc.hmacSha256Sync = (key, ...messages) => {
+  return hmac(sha256, key, secp256k1.etc.concatBytes(...messages))
+}
+
+/** @internal */
+export default class MemorySafeSigningKey extends SigningKey {
+  constructor (privateKeyBuffer) {
+    super(NULL)
+
+    this._privateKeyBuffer = privateKeyBuffer
+
+    this._publicKeyBuffer = secp256k1.getPublicKey(privateKeyBuffer, true)
+  }
+
+  get publicKey () {
+    return SigningKey.computePublicKey(this._privateKeyBuffer)
+  }
+
+  get compressedPublicKey () {
+    return SigningKey.computePublicKey(this._privateKeyBuffer, true)
+  }
+
+  get privateKeyBuffer () {
+    return this._privateKeyBuffer
+  }
+
+  get publicKeyBuffer () {
+    return this._publicKeyBuffer
+  }
+
+  sign (digest) {
+    assertArgument(dataLength(digest) === 32, 'invalid digest length', 'digest', digest)
+
+    const sig = secp256k1.sign(getBytesCopy(digest), this._privateKeyBuffer, {
+      lowS: true
+    })
+
+    return Signature.from({
+      r: toBeHex(sig.r, 32),
+      s: toBeHex(sig.s, 32),
+      v: (sig.recovery ? 0x1c : 0x1b)
+    })
+  }
+
+  dispose () {
+    sodium_memzero(this._privateKeyBuffer)
+
+    this._privateKeyBuffer = undefined
+  }
+}

package/src/wallet-account-evm.js

@@ -0,0 +1,200 @@
+// Copyright 2024 Tether Operations Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict'
+
+import { verifyMessage } from 'ethers'
+
+import * as bip39 from 'bip39'
+
+import WalletAccountReadOnlyEvm from './wallet-account-read-only-evm.js'
+
+import MemorySafeHDNodeWallet from './memory-safe/hd-node-wallet.js'
+
+/** @typedef {import('ethers').HDNodeWallet} HDNodeWallet */
+
+/** @typedef {import('@tetherto/wdk-wallet').IWalletAccount} IWalletAccount */
+
+/** @typedef {import('@tetherto/wdk-wallet').KeyPair} KeyPair */
+/** @typedef {import('@tetherto/wdk-wallet').TransactionResult} TransactionResult */
+/** @typedef {import('@tetherto/wdk-wallet').TransferOptions} TransferOptions */
+/** @typedef {import('@tetherto/wdk-wallet').TransferResult} TransferResult */
+
+/** @typedef {import('./wallet-account-read-only-evm.js').EvmTransaction} EvmTransaction */
+/** @typedef {import('./wallet-account-read-only-evm.js').EvmWalletConfig} EvmWalletConfig */
+
+const BIP_44_ETH_DERIVATION_PATH_PREFIX = "m/44'/60'"
+
+/** @implements {IWalletAccount} */
+export default class WalletAccountEvm extends WalletAccountReadOnlyEvm {
+  /**
+   * Creates a new evm wallet account.
+   *
+   * @param {string | Uint8Array} seed - The wallet's [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) seed phrase.
+   * @param {string} path - The BIP-44 derivation path (e.g. "0'/0/0").
+   * @param {EvmWalletConfig} [config] - The configuration object.
+   */
+  constructor (seed, path, config = {}) {
+    if (typeof seed === 'string') {
+      if (!bip39.validateMnemonic(seed)) {
+        throw new Error('The seed phrase is invalid.')
+      }
+
+      seed = bip39.mnemonicToSeedSync(seed)
+    }
+
+    path = BIP_44_ETH_DERIVATION_PATH_PREFIX + '/' + path
+
+    const account = MemorySafeHDNodeWallet.fromSeed(seed)
+      .derivePath(path)
+
+    super(account.address, config)
+
+    /**
+     * The wallet account configuration.
+     *
+     * @protected
+     * @type {EvmWalletConfig}
+     */
+    this._config = config
+
+    /**
+     * The account.
+     *
+     * @protected
+     * @type {HDNodeWallet}
+     */
+    this._account = account
+
+    if (this._provider) {
+      this._account = this._account.connect(this._provider)
+    }
+  }
+
+  /**
+   * The derivation path's index of this account.
+   *
+   * @type {number}
+   */
+  get index () {
+    return this._account.index
+  }
+
+  /**
+   * The derivation path of this account (see [BIP-44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)).
+   *
+   * @type {string}
+   */
+  get path () {
+    return this._account.path
+  }
+
+  /**
+   * The account's key pair.
+   *
+   * @type {KeyPair}
+   */
+  get keyPair () {
+    return {
+      privateKey: this._account.privateKeyBuffer,
+      publicKey: this._account.publicKeyBuffer
+    }
+  }
+
+  /**
+   * Signs a message.
+   *
+   * @param {string} message - The message to sign.
+   * @returns {Promise<string>} The message's signature.
+   */
+  async sign (message) {
+    return await this._account.signMessage(message)
+  }
+
+  /**
+   * Verifies a message's signature.
+   *
+   * @param {string} message - The original message.
+   * @param {string} signature - The signature to verify.
+   * @returns {Promise<boolean>} True if the signature is valid.
+   */
+  async verify (message, signature) {
+    const address = await verifyMessage(message, signature)
+
+    return address.toLowerCase() === this._account.address.toLowerCase()
+  }
+
+  /**
+   * Sends a transaction.
+   *
+   * @param {EvmTransaction} tx - The transaction.
+   * @returns {Promise<TransactionResult>} The transaction's result.
+   */
+  async sendTransaction (tx) {
+    if (!this._account.provider) {
+      throw new Error('The wallet must be connected to a provider to send transactions.')
+    }
+
+    const { fee } = await this.quoteSendTransaction(tx)
+
+    const { hash } = await this._account.sendTransaction({
+      from: await this.getAddress(),
+      ...tx
+    })
+
+    return { hash, fee }
+  }
+
+  /**
+   * Transfers a token to another address.
+   *
+   * @param {TransferOptions} options - The transfer's options.
+   * @returns {Promise<TransferResult>} The transfer's result.
+   */
+  async transfer (options) {
+    if (!this._account.provider) {
+      throw new Error('The wallet must be connected to a provider to transfer tokens.')
+    }
+
+    const tx = await WalletAccountEvm._getTransferTransaction(options)
+
+    const { fee } = await this.quoteSendTransaction(tx)
+
+    if (this._config.transferMaxFee !== undefined && fee >= this._config.transferMaxFee) {
+      throw new Error('Exceeded maximum fee cost for transfer operation.')
+    }
+
+    const { hash } = await this._account.sendTransaction(tx)
+
+    return { hash, fee }
+  }
+
+  /**
+   * Returns a read-only copy of the account.
+   *
+   * @returns {Promise<WalletAccountReadOnlyEvm>} The read-only account.
+   */
+  async toReadOnlyAccount () {
+    const readOnlyAccount = new WalletAccountReadOnlyEvm(this._account.address, this._config)
+
+    return readOnlyAccount
+  }
+
+  /**
+   * Disposes the wallet account, erasing the private key from the memory.
+   */
+  dispose () {
+    this._account.dispose()
+  }
+}