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

package/src/wallet-account-read-only-evm.js

@@ -0,0 +1,191 @@
+// 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 { WalletAccountReadOnly } from '@tetherto/wdk-wallet'
+
+import { BrowserProvider, Contract, JsonRpcProvider } from 'ethers'
+
+/** @typedef {import('ethers').Provider} Provider */
+/** @typedef {import('ethers').Eip1193Provider} Eip1193Provider */
+/** @typedef {import('ethers').TransactionReceipt} EvmTransactionReceipt */
+
+/** @typedef {import('@tetherto/wdk-wallet').TransactionResult} TransactionResult */
+/** @typedef {import('@tetherto/wdk-wallet').TransferOptions} TransferOptions */
+/** @typedef {import('@tetherto/wdk-wallet').TransferResult} TransferResult */
+
+/**
+ * @typedef {Object} EvmTransaction
+ * @property {string} to - The transaction's recipient.
+ * @property {number | bigint} value - The amount of ethers to send to the recipient (in weis).
+ * @property {string} [data] - The transaction's data in hex format.
+ * @property {number | bigint} [gasLimit] - The maximum amount of gas this transaction is permitted to use.
+ * @property {number | bigint} [gasPrice] - The price (in wei) per unit of gas this transaction will pay.
+ * @property {number | bigint} [maxFeePerGas] - The maximum price (in wei) per unit of gas this transaction will pay for the combined [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) block's base fee and this transaction's priority fee.
+ * @property {number | bigint} [maxPriorityFeePerGas] - The price (in wei) per unit of gas this transaction will allow in addition to the [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) block's base fee to bribe miners into giving this transaction priority. This is included in the maxFeePerGas, so this will not affect the total maximum cost set with maxFeePerGas.
+ */
+
+/**
+ * @typedef {Object} EvmWalletConfig
+ * @property {string | Eip1193Provider} [provider] - The url of the rpc provider, or an instance of a class that implements eip-1193.
+ * @property {number | bigint} [transferMaxFee] - The maximum fee amount for transfer operations.
+ */
+
+export default class WalletAccountReadOnlyEvm extends WalletAccountReadOnly {
+  /**
+   * Creates a new evm read-only wallet account.
+   *
+   * @param {string} address - The account's address.
+   * @param {Omit<EvmWalletConfig, 'transferMaxFee'>} [config] - The configuration object.
+   */
+  constructor (address, config = { }) {
+    super(address)
+
+    /**
+     * The read-only wallet account configuration.
+     *
+     * @protected
+     * @type {Omit<EvmWalletConfig, 'transferMaxFee'>}
+     */
+    this._config = config
+
+    const { provider } = config
+
+    if (provider) {
+      /**
+       * An ethers provider to interact with a node of the blockchain.
+       *
+       * @protected
+       * @type {Provider | undefined}
+       */
+      this._provider = typeof provider === 'string'
+        ? new JsonRpcProvider(provider)
+        : new BrowserProvider(provider)
+    }
+  }
+
+  /**
+   * Returns the account's eth balance.
+   *
+   * @returns {Promise<bigint>} The eth balance (in weis).
+   */
+  async getBalance () {
+    if (!this._provider) {
+      throw new Error('The wallet must be connected to a provider to retrieve balances.')
+    }
+
+    const address = await this.getAddress()
+
+    const balance = await this._provider.getBalance(address)
+
+    return balance
+  }
+
+  /**
+   * Returns the account balance for a specific token.
+   *
+   * @param {string} tokenAddress - The smart contract address of the token.
+   * @returns {Promise<bigint>} The token balance (in base unit).
+   */
+  async getTokenBalance (tokenAddress) {
+    if (!this._provider) {
+      throw new Error('The wallet must be connected to a provider to retrieve token balances.')
+    }
+
+    const address = await this.getAddress()
+
+    const abi = ['function balanceOf(address owner) view returns (uint256)']
+    const contract = new Contract(tokenAddress, abi, this._provider)
+    const balance = await contract.balanceOf(address)
+
+    return balance
+  }
+
+  /**
+   * Quotes the costs of a send transaction operation.
+   *
+   * @param {EvmTransaction} tx - The transaction.
+   * @returns {Promise<Omit<TransactionResult, 'hash'>>} The transaction's quotes.
+   */
+  async quoteSendTransaction (tx) {
+    if (!this._provider) {
+      throw new Error('The wallet must be connected to a provider to quote send transaction operations.')
+    }
+
+    const gas = await this._provider.estimateGas({
+      from: await this.getAddress(),
+      ...tx
+    })
+
+    const { maxFeePerGas } = await this._provider.getFeeData()
+
+    return { fee: gas * maxFeePerGas }
+  }
+
+  /**
+   * Quotes the costs of a transfer operation.
+   *
+   * @param {TransferOptions} options - The transfer's options.
+   * @returns {Promise<Omit<TransferResult, 'hash'>>} The transfer's quotes.
+   */
+  async quoteTransfer (options) {
+    if (!this._provider) {
+      throw new Error('The wallet must be connected to a provider to quote transfer operations.')
+    }
+
+    const tx = await WalletAccountReadOnlyEvm._getTransferTransaction(options)
+
+    const result = await this.quoteSendTransaction(tx)
+
+    return result
+  }
+
+  /**
+   * Returns a transaction's receipt.
+   *
+   * @param {string} hash - The transaction's hash.
+   * @returns {Promise<EvmTransactionReceipt | null>} – The receipt, or null if the transaction has not been included in a block yet.
+   */
+  async getTransactionReceipt (hash) {
+    if (!this._provider) {
+      throw new Error('The wallet must be connected to a provider to fetch transaction receipts.')
+    }
+
+    return await this._provider.getTransactionReceipt(hash)
+  }
+
+  /**
+   * Returns an evm transaction to execute the given token transfer.
+   *
+   * @protected
+   * @param {TransferOptions} options - The transfer's options.
+   * @returns {Promise<EvmTransaction>} The evm transaction.
+   */
+  static async _getTransferTransaction (options) {
+    const { token, recipient, amount } = options
+
+    const abi = ['function transfer(address to, uint256 amount) returns (bool)']
+
+    const contract = new Contract(token, abi)
+
+    const tx = {
+      to: token,
+      value: 0,
+      data: contract.interface.encodeFunctionData('transfer', [recipient, amount])
+    }
+
+    return tx
+  }
+}

package/src/wallet-manager-evm.js

@@ -0,0 +1,127 @@
+// 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 WalletManager from '@tetherto/wdk-wallet'
+
+import { BrowserProvider, JsonRpcProvider } from 'ethers'
+
+import WalletAccountEvm from './wallet-account-evm.js'
+
+/** @typedef {import('ethers').Provider} Provider */
+
+/** @typedef {import("@tetherto/wdk-wallet").FeeRates} FeeRates */
+
+/** @typedef {import('./wallet-account-evm.js').EvmWalletConfig} EvmWalletConfig */
+
+export default class WalletManagerEvm extends WalletManager {
+  /**
+   * Multiplier for normal fee rate calculations (in %).
+   *
+   * @protected
+   * @type {bigint}
+   */
+  static _FEE_RATE_NORMAL_MULTIPLIER = 110n
+
+  /**
+   * Multiplier for fast fee rate calculations (in %).
+   *
+   * @protected
+   * @type {bigint}
+   */
+  static _FEE_RATE_FAST_MULTIPLIER = 200n
+
+  /**
+   * Creates a new wallet manager for evm blockchains.
+   *
+   * @param {string | Uint8Array} seed - The wallet's [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) seed phrase.
+   * @param {EvmWalletConfig} [config] - The configuration object.
+   */
+  constructor (seed, config = {}) {
+    super(seed, config)
+
+    /**
+     * The evm wallet configuration.
+     *
+     * @protected
+     * @type {EvmWalletConfig}
+     */
+    this._config = config
+
+    const { provider } = config
+
+    if (provider) {
+      /**
+       * An ethers provider to interact with a node of the blockchain.
+       *
+       * @protected
+       * @type {Provider | undefined}
+       */
+      this._provider = typeof provider === 'string'
+        ? new JsonRpcProvider(provider)
+        : new BrowserProvider(provider)
+    }
+  }
+
+  /**
+   * Returns the wallet account at a specific index (see [BIP-44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)).
+   *
+   * @example
+   * // Returns the account with derivation path m/44'/60'/0'/0/1
+   * const account = await wallet.getAccount(1);
+   * @param {number} [index] - The index of the account to get (default: 0).
+   * @returns {Promise<WalletAccountEvm>} The account.
+   */
+  async getAccount (index = 0) {
+    return await this.getAccountByPath(`0'/0/${index}`)
+  }
+
+  /**
+   * Returns the wallet account at a specific BIP-44 derivation path.
+   *
+   * @example
+   * // Returns the account with derivation path m/44'/60'/0'/0/1
+   * const account = await wallet.getAccountByPath("0'/0/1");
+   * @param {string} path - The derivation path (e.g. "0'/0/0").
+   * @returns {Promise<WalletAccountEvm>} The account.
+   */
+  async getAccountByPath (path) {
+    if (!this._accounts[path]) {
+      const account = new WalletAccountEvm(this.seed, path, this._config)
+
+      this._accounts[path] = account
+    }
+
+    return this._accounts[path]
+  }
+
+  /**
+   * Returns the current fee rates.
+   *
+   * @returns {Promise<FeeRates>} The fee rates (in weis).
+   */
+  async getFeeRates () {
+    if (!this._provider) {
+      throw new Error('The wallet must be connected to a provider to get fee rates.')
+    }
+
+    const { maxFeePerGas } = await this._provider.getFeeData()
+
+    return {
+      normal: maxFeePerGas * WalletManagerEvm._FEE_RATE_NORMAL_MULTIPLIER / 100n,
+      fast: maxFeePerGas * WalletManagerEvm._FEE_RATE_FAST_MULTIPLIER / 100n
+    }
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,11 @@
+export { default } from "./src/wallet-manager-evm.js";
+export { default as WalletAccountReadOnlyEvm } from "./src/wallet-account-read-only-evm.js";
+export { default as WalletAccountEvm } from "./src/wallet-account-evm.js";
+export type EvmTransactionReceipt = import("ethers").TransactionReceipt;
+export type FeeRates = import("@tetherto/wdk-wallet").FeeRates;
+export type KeyPair = import("@tetherto/wdk-wallet").KeyPair;
+export type TransactionResult = import("@tetherto/wdk-wallet").TransactionResult;
+export type TransferOptions = import("@tetherto/wdk-wallet").TransferOptions;
+export type TransferResult = import("@tetherto/wdk-wallet").TransferResult;
+export type EvmTransaction = import("./src/wallet-account-read-only-evm.js").EvmTransaction;
+export type EvmWalletConfig = import("./src/wallet-account-read-only-evm.js").EvmWalletConfig;

package/types/src/wallet-account-evm.d.ts

@@ -0,0 +1,91 @@
+/** @implements {IWalletAccount} */
+export default class WalletAccountEvm extends WalletAccountReadOnlyEvm implements IWalletAccount {
+    /**
+     * 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: string | Uint8Array, path: string, config?: EvmWalletConfig);
+    /**
+     * The wallet account configuration.
+     *
+     * @protected
+     * @type {EvmWalletConfig}
+     */
+    protected _config: EvmWalletConfig;
+    /**
+     * The account.
+     *
+     * @protected
+     * @type {HDNodeWallet}
+     */
+    protected _account: HDNodeWallet;
+    /**
+     * The derivation path's index of this account.
+     *
+     * @type {number}
+     */
+    get index(): number;
+    /**
+     * The derivation path of this account (see [BIP-44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)).
+     *
+     * @type {string}
+     */
+    get path(): string;
+    /**
+     * The account's key pair.
+     *
+     * @type {KeyPair}
+     */
+    get keyPair(): KeyPair;
+    /**
+     * Signs a message.
+     *
+     * @param {string} message - The message to sign.
+     * @returns {Promise<string>} The message's signature.
+     */
+    sign(message: string): Promise<string>;
+    /**
+     * 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.
+     */
+    verify(message: string, signature: string): Promise<boolean>;
+    /**
+     * Sends a transaction.
+     *
+     * @param {EvmTransaction} tx - The transaction.
+     * @returns {Promise<TransactionResult>} The transaction's result.
+     */
+    sendTransaction(tx: EvmTransaction): Promise<TransactionResult>;
+    /**
+     * Transfers a token to another address.
+     *
+     * @param {TransferOptions} options - The transfer's options.
+     * @returns {Promise<TransferResult>} The transfer's result.
+     */
+    transfer(options: TransferOptions): Promise<TransferResult>;
+    /**
+     * Returns a read-only copy of the account.
+     *
+     * @returns {Promise<WalletAccountReadOnlyEvm>} The read-only account.
+     */
+    toReadOnlyAccount(): Promise<WalletAccountReadOnlyEvm>;
+    /**
+     * Disposes the wallet account, erasing the private key from the memory.
+     */
+    dispose(): void;
+}
+export type HDNodeWallet = import("ethers").HDNodeWallet;
+export type IWalletAccount = import("@tetherto/wdk-wallet").IWalletAccount;
+export type KeyPair = import("@tetherto/wdk-wallet").KeyPair;
+export type TransactionResult = import("@tetherto/wdk-wallet").TransactionResult;
+export type TransferOptions = import("@tetherto/wdk-wallet").TransferOptions;
+export type TransferResult = import("@tetherto/wdk-wallet").TransferResult;
+export type EvmTransaction = import("./wallet-account-read-only-evm.js").EvmTransaction;
+export type EvmWalletConfig = import("./wallet-account-read-only-evm.js").EvmWalletConfig;
+import WalletAccountReadOnlyEvm from './wallet-account-read-only-evm.js';

package/types/src/wallet-account-read-only-evm.d.ts

@@ -0,0 +1,112 @@
+export default class WalletAccountReadOnlyEvm extends WalletAccountReadOnly {
+    /**
+     * Returns an evm transaction to execute the given token transfer.
+     *
+     * @protected
+     * @param {TransferOptions} options - The transfer's options.
+     * @returns {Promise<EvmTransaction>} The evm transaction.
+     */
+    protected static _getTransferTransaction(options: TransferOptions): Promise<EvmTransaction>;
+    /**
+     * Creates a new evm read-only wallet account.
+     *
+     * @param {string} address - The account's address.
+     * @param {Omit<EvmWalletConfig, 'transferMaxFee'>} [config] - The configuration object.
+     */
+    constructor(address: string, config?: Omit<EvmWalletConfig, "transferMaxFee">);
+    /**
+     * The read-only wallet account configuration.
+     *
+     * @protected
+     * @type {Omit<EvmWalletConfig, 'transferMaxFee'>}
+     */
+    protected _config: Omit<EvmWalletConfig, "transferMaxFee">;
+    /**
+     * An ethers provider to interact with a node of the blockchain.
+     *
+     * @protected
+     * @type {Provider | undefined}
+     */
+    protected _provider: Provider | undefined;
+    /**
+     * Returns the account's eth balance.
+     *
+     * @returns {Promise<bigint>} The eth balance (in weis).
+     */
+    getBalance(): Promise<bigint>;
+    /**
+     * Returns the account balance for a specific token.
+     *
+     * @param {string} tokenAddress - The smart contract address of the token.
+     * @returns {Promise<bigint>} The token balance (in base unit).
+     */
+    getTokenBalance(tokenAddress: string): Promise<bigint>;
+    /**
+     * Quotes the costs of a send transaction operation.
+     *
+     * @param {EvmTransaction} tx - The transaction.
+     * @returns {Promise<Omit<TransactionResult, 'hash'>>} The transaction's quotes.
+     */
+    quoteSendTransaction(tx: EvmTransaction): Promise<Omit<TransactionResult, "hash">>;
+    /**
+     * Quotes the costs of a transfer operation.
+     *
+     * @param {TransferOptions} options - The transfer's options.
+     * @returns {Promise<Omit<TransferResult, 'hash'>>} The transfer's quotes.
+     */
+    quoteTransfer(options: TransferOptions): Promise<Omit<TransferResult, "hash">>;
+    /**
+     * Returns a transaction's receipt.
+     *
+     * @param {string} hash - The transaction's hash.
+     * @returns {Promise<EvmTransactionReceipt | null>} – The receipt, or null if the transaction has not been included in a block yet.
+     */
+    getTransactionReceipt(hash: string): Promise<EvmTransactionReceipt | null>;
+}
+export type Provider = import("ethers").Provider;
+export type Eip1193Provider = import("ethers").Eip1193Provider;
+export type EvmTransactionReceipt = import("ethers").TransactionReceipt;
+export type TransactionResult = import("@tetherto/wdk-wallet").TransactionResult;
+export type TransferOptions = import("@tetherto/wdk-wallet").TransferOptions;
+export type TransferResult = import("@tetherto/wdk-wallet").TransferResult;
+export type EvmTransaction = {
+    /**
+     * - The transaction's recipient.
+     */
+    to: string;
+    /**
+     * - The amount of ethers to send to the recipient (in weis).
+     */
+    value: number | bigint;
+    /**
+     * - The transaction's data in hex format.
+     */
+    data?: string;
+    /**
+     * - The maximum amount of gas this transaction is permitted to use.
+     */
+    gasLimit?: number | bigint;
+    /**
+     * - The price (in wei) per unit of gas this transaction will pay.
+     */
+    gasPrice?: number | bigint;
+    /**
+     * - The maximum price (in wei) per unit of gas this transaction will pay for the combined [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) block's base fee and this transaction's priority fee.
+     */
+    maxFeePerGas?: number | bigint;
+    /**
+     * - The price (in wei) per unit of gas this transaction will allow in addition to the [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) block's base fee to bribe miners into giving this transaction priority. This is included in the maxFeePerGas, so this will not affect the total maximum cost set with maxFeePerGas.
+     */
+    maxPriorityFeePerGas?: number | bigint;
+};
+export type EvmWalletConfig = {
+    /**
+     * - The url of the rpc provider, or an instance of a class that implements eip-1193.
+     */
+    provider?: string | Eip1193Provider;
+    /**
+     * - The maximum fee amount for transfer operations.
+     */
+    transferMaxFee?: number | bigint;
+};
+import { WalletAccountReadOnly } from '@tetherto/wdk-wallet';

package/types/src/wallet-manager-evm.d.ts

@@ -0,0 +1,68 @@
+export default class WalletManagerEvm extends WalletManager {
+    /**
+     * Multiplier for normal fee rate calculations (in %).
+     *
+     * @protected
+     * @type {bigint}
+     */
+    protected static _FEE_RATE_NORMAL_MULTIPLIER: bigint;
+    /**
+     * Multiplier for fast fee rate calculations (in %).
+     *
+     * @protected
+     * @type {bigint}
+     */
+    protected static _FEE_RATE_FAST_MULTIPLIER: bigint;
+    /**
+     * Creates a new wallet manager for evm blockchains.
+     *
+     * @param {string | Uint8Array} seed - The wallet's [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) seed phrase.
+     * @param {EvmWalletConfig} [config] - The configuration object.
+     */
+    constructor(seed: string | Uint8Array, config?: EvmWalletConfig);
+    /**
+     * The evm wallet configuration.
+     *
+     * @protected
+     * @type {EvmWalletConfig}
+     */
+    protected _config: EvmWalletConfig;
+    /**
+     * An ethers provider to interact with a node of the blockchain.
+     *
+     * @protected
+     * @type {Provider | undefined}
+     */
+    protected _provider: Provider | undefined;
+    /**
+     * Returns the wallet account at a specific index (see [BIP-44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)).
+     *
+     * @example
+     * // Returns the account with derivation path m/44'/60'/0'/0/1
+     * const account = await wallet.getAccount(1);
+     * @param {number} [index] - The index of the account to get (default: 0).
+     * @returns {Promise<WalletAccountEvm>} The account.
+     */
+    getAccount(index?: number): Promise<WalletAccountEvm>;
+    /**
+     * Returns the wallet account at a specific BIP-44 derivation path.
+     *
+     * @example
+     * // Returns the account with derivation path m/44'/60'/0'/0/1
+     * const account = await wallet.getAccountByPath("0'/0/1");
+     * @param {string} path - The derivation path (e.g. "0'/0/0").
+     * @returns {Promise<WalletAccountEvm>} The account.
+     */
+    getAccountByPath(path: string): Promise<WalletAccountEvm>;
+    /**
+     * Returns the current fee rates.
+     *
+     * @returns {Promise<FeeRates>} The fee rates (in weis).
+     */
+    getFeeRates(): Promise<FeeRates>;
+}
+export type Provider = import("ethers").Provider;
+export type FeeRates = import("@tetherto/wdk-wallet").FeeRates;
+export type EvmWalletConfig = import("./wallet-account-evm.js").EvmWalletConfig;
+import WalletManager from '@tetherto/wdk-wallet';
+import WalletAccountEvm from './wallet-account-evm.js';