feat(sdk-coin-xtz): add xtz recovery

ticket: WIN-6482

Author: abhi-bitgo

modules/sdk-coin-xtz/package.json

@@ -50,7 +50,8 @@
     "bignumber.js": "^9.0.0",
     "bs58check": "^2.1.2",
     "libsodium-wrappers": "^0.7.6",
-    "lodash": "^4.17.15"
+    "lodash": "^4.17.15",
+    "superagent": "^9.0.1"
   },
   "devDependencies": {
     "@bitgo/sdk-api": "^1.66.1",

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

@@ -135,3 +135,39 @@ export interface Key extends BaseKey, IndexedData {}
 export interface IndexedSignature extends IndexedData {
   signature: string;
 }
+
+export type RecoverOptions = {
+  userKey: string;
+  backupKey: string;
+  walletPassphrase?: string;
+  walletContractAddress: string; // use this as walletBaseAddress for TSS
+  recoveryDestination: string;
+  krsProvider?: string;
+  gasPrice?: number;
+  gasLimit?: number;
+  bitgoFeeAddress?: string;
+  bitgoDestinationAddress?: string;
+  tokenContractAddress?: string;
+  intendedChain?: string;
+  derivationSeed?: string;
+  apiKey?: string;
+  isUnsignedSweep?: boolean;
+};
+
+export interface OfflineVaultTxInfo {
+  nextContractSequenceId?: string;
+  contractSequenceId?: string;
+  tx?: string;
+  txHex?: string;
+  userKey?: string;
+  backupKey?: string;
+  coin: string;
+  gasPrice: number;
+  gasLimit: number;
+  recipients: Recipient[];
+  walletContractAddress: string;
+  amount: string;
+  backupKeyNonce: number;
+  isEvmBasedCrossChainRecovery?: boolean;
+  walletVersion?: number;
+}

modules/sdk-coin-xtz/src/lib/utils.ts

@@ -463,3 +463,22 @@ export enum DEFAULT_STORAGE_LIMIT {
   TRANSFER = 257,
   REVEAL = 0,
 }
+
+export enum TRANSACTION_FEE {
+  ORIGINATION = 47640,
+  TRANSFER = 47640,
+  REVEAL = 1420,
+}
+
+export enum TRANSACTION_STORAGE_LIMIT {
+  ORIGINATION = 3000,
+  TRANSFER = 300,
+  REVEAL = 5,
+}
+
+export enum TRANSACTION_GAS_LIMIT {
+  ORIGINATION = 4600,
+  TRANSFER = 6000,
+  CONTRACT_TRANSFER = 20000,
+  REVEAL = 1500,
+}

modules/sdk-coin-xtz/src/xtz.ts

@@ -13,12 +13,22 @@ import {
   MultisigType,
   multisigTypes,
   AuditDecryptedKeyParams,
+  common,
+  TransactionType,
 } from '@bitgo/sdk-core';
 import { bip32 } from '@bitgo/secp256k1';
 import { CoinFamily, coins, BaseCoin as StaticsBaseCoin } from '@bitgo/statics';
 import BigNumber from 'bignumber.js';
 import { Interface, KeyPair, TransactionBuilder, Utils } from './lib';
-
+import { RecoverOptions } from './lib/iface';
+import {
+  generateDataToSign,
+  isValidOriginatedAddress,
+  TRANSACTION_FEE,
+  TRANSACTION_GAS_LIMIT,
+  TRANSACTION_STORAGE_LIMIT,
+} from './lib/utils';
+import request from 'superagent';
 export class Xtz extends BaseCoin {
   protected readonly _staticsCoin: Readonly<StaticsBaseCoin>;
 
@@ -183,6 +193,133 @@ export class Xtz extends BaseCoin {
     const signatureData = await Utils.sign(keyPair, messageHex);
     return Buffer.from(signatureData.sig);
   }
+  /**
+   * Method to validate recovery params
+   * @param {RecoverOptions} params
+   * @returns {void}
+   */
+  validateRecoveryParams(params: RecoverOptions): void {
+    if (params.userKey === undefined) {
+      throw new Error('missing userKey');
+    }
+
+    if (params.backupKey === undefined) {
+      throw new Error('missing backupKey');
+    }
+
+    if (!params.isUnsignedSweep && params.walletPassphrase === undefined && !params.userKey.startsWith('xpub')) {
+      throw new Error('missing wallet passphrase');
+    }
+
+    if (params.walletContractAddress === undefined || !this.isValidAddress(params.walletContractAddress)) {
+      throw new Error('invalid walletContractAddress');
+    }
+
+    if (params.recoveryDestination === undefined || !this.isValidAddress(params.recoveryDestination)) {
+      throw new Error('invalid recoveryDestination');
+    }
+  }
+
+  /**
+   * Make a query to blockchain explorer for information such as balance, token balance, solidity calls
+   * @param query {Object} key-value pairs of parameters to append after /api
+   * @param apiKey {string} optional API key to use instead of the one from the environment
+   * @returns {Object} response from the blockchain explorer
+   */
+  async recoveryBlockchainExplorerQuery(
+    params: {
+      actionPath: string;
+      address?: string;
+      action?: string;
+    },
+    apiKey?: string
+  ): Promise<unknown> {
+    const response = await request.get(
+      `${common.Environments[this.bitgo.getEnv()].xtzExplorerBaseUrl}/v1/${params.actionPath}${
+        params.address ? '/' + params.address : ''
+      }${params.action ? '/' + params.action : ''}${apiKey ? `?apikey=${apiKey}` : ''}`
+    );
+
+    if (!response.ok) {
+      throw new Error('could not reach TZKT');
+    }
+
+    if (response.status === 429) {
+      throw new Error('TZKT rate limit reached');
+    }
+    return response.body;
+  }
+
+  /**
+   * Queries public block explorer to get the next XTZ address details
+   * @param {string} address
+   * @param {string} apiKey - optional API key to use instead of the one from the environment
+   * @returns {Promise<any>}
+   */
+  async getAddressDetails(address: string, apiKey?: string): Promise<any> {
+    const result = await this.recoveryBlockchainExplorerQuery(
+      {
+        actionPath: 'accounts',
+        address,
+      },
+      apiKey
+    );
+
+    if (!result) {
+      throw new Error(`Unable to find details for ${address}`);
+    }
+    return result;
+  }
+
+  /**
+   * Query explorer for the balance of an address
+   * @param {String} address - the XTZ base/receive address
+   * @param {String} apiKey - optional API key to use instead of the one from the environment
+   * @returns {BigNumber} address balance
+   */
+  async queryAddressBalance(address: string, apiKey?: string): Promise<any> {
+    const result: any = await this.recoveryBlockchainExplorerQuery(
+      {
+        actionPath: isValidOriginatedAddress(address) ? 'contracts' : 'accounts',
+        address,
+      },
+      apiKey
+    );
+    // throw if the result does not exist or the result is not a valid number
+    if (!result || !result.balance) {
+      throw new Error(`Could not obtain address balance for ${address} from the explorer`);
+    }
+    return new BigNumber(result.balance, 10);
+  }
+
+  /**
+   * Generate and pack the data to sign for each transfer.
+   *
+   * @param {String} contractAddress Wallet address to withdraw funds from
+   * @param {String} contractCounter Wallet internal counter
+   * @param {String} destination Tezos address to send the funds to
+   * @param {String} amount Number of mutez to move
+   * @param {IMSClient} imsClient Existing IMS client connection to reuse
+   * @return {String} data to sign in hex format
+   */
+  async packDataToSign(contractAddress, contractCounter, destination, amount) {
+    const dataToSign = generateDataToSign(contractAddress, destination, amount, contractCounter);
+    const xtzRpcUrl = `${
+      common.Environments[this.bitgo.getEnv()].xtzRpcUrl
+    }/chains/main/blocks/head/helpers/scripts/pack_data`;
+
+    if (!xtzRpcUrl) {
+      throw new Error('XTZ RPC url not found');
+    }
+
+    const response = await request.post(xtzRpcUrl).send(dataToSign);
+    if (response.status === 404) {
+      throw new Error(`unable to pack data to sign ${response.status}: ${response.body.error.message}`);
+    } else if (response.status !== 200) {
+      throw new Error(`unexpected IMS response status ${response.status}: ${response.body.error.message}`);
+    }
+    return response.body.packed;
+  }
 
   /**
    * Builds a funds recovery transaction without BitGo.
@@ -192,8 +329,129 @@ export class Xtz extends BaseCoin {
    * 3) Send signed build - send our signed build to a public node
    * @param params
    */
-  async recover(params: any): Promise<any> {
-    throw new MethodNotImplementedError();
+  async recover(params: RecoverOptions): Promise<unknown> {
+    this.validateRecoveryParams(params);
+
+    // Clean up whitespace from entered values
+
+    const backupKey = params.backupKey.replace(/\s/g, '');
+
+    const userAddressDetails = await this.getAddressDetails(params.walletContractAddress, params.apiKey);
+
+    if (!userAddressDetails) {
+      throw new Error('Unable to fetch user address details');
+    }
+
+    // Decrypt backup private key and get address
+    let backupPrv;
+
+    try {
+      backupPrv = this.bitgo.decrypt({
+        input: backupKey,
+        password: params.walletPassphrase,
+      });
+    } catch (e) {
+      throw new Error(`Error decrypting backup keychain: ${e.message}`);
+    }
+    const keyPair = new KeyPair({ prv: backupPrv });
+    const backupSigningKey = keyPair.getKeys().prv;
+    if (!backupSigningKey) {
+      throw new Error('no private key');
+    }
+    const backupKeyAddress = keyPair.getAddress();
+
+    const backupAddressDetails = await this.getAddressDetails(backupKeyAddress, params.apiKey || '');
+
+    if (!backupAddressDetails.counter || !backupAddressDetails.balance) {
+      throw new Error(`Missing required detail(s): counter, balance`);
+    }
+    const backupKeyNonce = new BigNumber(backupAddressDetails.counter + 1, 10);
+
+    // get balance of backupKey to ensure funds are available to pay fees
+    const backupKeyBalance = new BigNumber(backupAddressDetails.balance, 10);
+
+    const gasLimit = isValidOriginatedAddress(params.recoveryDestination)
+      ? TRANSACTION_GAS_LIMIT.CONTRACT_TRANSFER
+      : TRANSACTION_GAS_LIMIT.TRANSFER;
+    const gasPrice = TRANSACTION_FEE.TRANSFER;
+
+    // Checking whether back up key address has sufficient funds for transaction
+    if (backupKeyBalance.lt(gasPrice)) {
+      const weiToGwei = 10 ** 6;
+      throw new Error(
+        `Backup key address ${backupKeyAddress} has balance ${(
+          backupKeyBalance.toNumber() / weiToGwei
+        ).toString()} Gwei.` +
+          `This address must have a balance of at least ${(gasPrice / weiToGwei).toString()}` +
+          ` Gwei to perform recoveries. Try sending some funds to this address then retry.`
+      );
+    }
+
+    // get balance of sender address
+    if (!userAddressDetails.balance || userAddressDetails.balance === 0) {
+      throw new Error('No funds to recover from source address');
+    }
+    const txAmount = userAddressDetails.balance;
+    if (new BigNumber(txAmount).isLessThanOrEqualTo(0)) {
+      throw new Error('Wallet does not have enough funds to recover');
+    }
+
+    const feeInfo = {
+      fee: new BigNumber(TRANSACTION_FEE.TRANSFER),
+      gasLimit: new BigNumber(gasLimit),
+      storageLimit: new BigNumber(TRANSACTION_STORAGE_LIMIT.TRANSFER),
+    };
+
+    const txBuilder = new TransactionBuilder(coins.get(this.getChain()));
+
+    txBuilder.type(TransactionType.Send);
+    txBuilder.source(backupKeyAddress);
+
+    // Used to set the branch for the transaction
+    const chainHead: any = await this.recoveryBlockchainExplorerQuery({
+      actionPath: 'head',
+    });
+
+    if (!chainHead || !chainHead.hash) {
+      throw new Error('Unable to fetch chain head');
+    }
+    txBuilder.branch(chainHead.hash);
+
+    if (!backupAddressDetails.revealed) {
+      feeInfo.fee = feeInfo.fee.plus(TRANSACTION_FEE.REVEAL);
+      feeInfo.gasLimit = feeInfo.gasLimit.plus(TRANSACTION_GAS_LIMIT.REVEAL);
+      feeInfo.storageLimit = feeInfo.storageLimit.plus(TRANSACTION_STORAGE_LIMIT.REVEAL);
+      backupKeyNonce.plus(1);
+      const publicKeyToReveal = keyPair.getKeys();
+      txBuilder.publicKeyToReveal(publicKeyToReveal.pub);
+    }
+
+    txBuilder.counter(backupKeyNonce.toString());
+
+    const packedDataToSign = await this.packDataToSign(
+      params.walletContractAddress,
+      backupKeyNonce.toString(),
+      params.recoveryDestination,
+      txAmount?.toString()
+    );
+
+    txBuilder
+      .transfer(txAmount?.toString())
+      .from(params.walletContractAddress)
+      .to(params.recoveryDestination)
+      .counter(backupKeyNonce.toString())
+      .fee(TRANSACTION_FEE.TRANSFER.toString())
+      .storageLimit(TRANSACTION_STORAGE_LIMIT.TRANSFER.toString())
+      .gasLimit(gasLimit.toString())
+      .dataToSign(packedDataToSign);
+
+    txBuilder.sign({ key: backupSigningKey });
+    const signedTx = await txBuilder.build();
+
+    return {
+      id: signedTx.id,
+      tx: signedTx.toBroadcastFormat(),
+    };
   }
 
   /**