feat: added withdraw route

Withdraw route + test cases added

TICKET: BTC-2053

Author: parvbitgo067

modules/abstract-lightning/package.json

@@ -39,7 +39,7 @@
     ]
   },
   "dependencies": {
-    "@bitgo/public-types": "4.17.0",
+    "@bitgo/public-types": "4.26.0",
     "@bitgo/sdk-core": "^32.1.0",
     "@bitgo/statics": "^51.7.0",
     "@bitgo/utxo-lib": "^11.3.0",

modules/abstract-lightning/src/codecs/api/index.ts

@@ -2,5 +2,6 @@ export * from './backup';
 export * from './balance';
 export * from './invoice';
 export * from './payment';
+export * from './withdraw';
 export * from './transaction';
 export * from './wallet';

modules/abstract-lightning/src/codecs/api/withdraw.ts

@@ -0,0 +1,42 @@
+import * as t from 'io-ts';
+import { LightningOnchainRequest } from '@bitgo/public-types';
+import { PendingApprovalData, TxRequestState } from '@bitgo/sdk-core';
+
+// todo:(current) which to keep here which to take to common types
+export const LightningOnchainWithdrawParams = t.intersection([
+  LightningOnchainRequest,
+  t.type({
+    // todo:(current) is passphrase required?
+    // passphrase: t.string,
+  }),
+]);
+
+export type LightningOnchainWithdrawParams = t.TypeOf<typeof LightningOnchainWithdrawParams>;
+
+export type LightningOnchainWithdrawResponse = {
+  /**
+   * Unique identifier for the payment request submitted to BitGo.
+   */
+  txRequestId: string;
+
+  /**
+   * Status of the payment request submission to BitGo.
+   * - `'delivered'`: Successfully received by BitGo, but may or may not have been sent to the Lightning Network yet.
+   * - For the actual withdraw status, track `transfer`.
+   */
+  txRequestState: TxRequestState;
+
+  /**
+   * Pending approval details, if applicable.
+   * - If present, withdraw has not been initiated yet.
+   */
+  pendingApproval?: PendingApprovalData;
+
+  /**
+   * Latest transfer details for this withdraw request (if available).
+   * - Provides the current state of the transfer.
+   * - To track the latest withdraw status, monitor `transfer` asynchronously.
+   * This field is absent if approval is required before processing.
+   */
+  transfer?: any;
+};

modules/abstract-lightning/src/wallet/lightning.ts

@@ -24,6 +24,8 @@ import {
   TransactionQuery,
   PaymentInfo,
   PaymentQuery,
+  LightningOnchainWithdrawParams,
+  LightningOnchainWithdrawResponse,
 } from '../codecs';
 import { LightningPaymentIntent, LightningPaymentRequest } from '@bitgo/public-types';
 
@@ -156,6 +158,15 @@ export interface ILightningWallet {
    * @returns {Promise<PayInvoiceResponse>} Payment result containing transaction request details and payment status
    */
   payInvoice(params: SubmitPaymentParams): Promise<PayInvoiceResponse>;
+
+  /**
+   * On chain withdrawal
+   * @param {LightningOnchainWithdrawParams} params - Withdraw parameters
+   * @param {LightningOnchainRecipient[]} params.recipients - The recipients to pay
+   * @param {bigint} [params.satsPerVbyte] - Optional value for sats per virtual byte
+   * @returns {Promise<LightningOnchainWithdrawResponse>} Withdraw result containing transaction request details and status
+   */
+  withdrawOnchain(params: LightningOnchainWithdrawParams): Promise<LightningOnchainWithdrawResponse>;
   /**
    * Get payment details by payment hash
    * @param {string} paymentHash - Payment hash to lookup
@@ -301,6 +312,49 @@ export class LightningWallet implements ILightningWallet {
     };
   }
 
+  async withdrawOnchain(params: LightningOnchainWithdrawParams): Promise<LightningOnchainWithdrawResponse> {
+    const reqId = new RequestTracer();
+    this.wallet.bitgo.setRequestTracer(reqId);
+
+    const paymentIntent: { intent: LightningPaymentIntent } = {
+      intent: {
+        onchainRequest: {
+          recipients: params.recipients,
+          satsPerVbyte: params.satsPerVbyte,
+        },
+        intentType: 'payment',
+      },
+    };
+
+    const transactionRequestCreate = (await this.wallet.bitgo
+      .post(this.wallet.bitgo.url('/wallet/' + this.wallet.id() + '/txrequests', 2))
+      .send(t.type({ intent: LightningPaymentIntent }).encode(paymentIntent))
+      .result()) as TxRequest;
+
+    if (transactionRequestCreate.state === 'pendingApproval') {
+      const pendingApprovals = new PendingApprovals(this.wallet.bitgo, this.wallet.baseCoin);
+      const pendingApproval = await pendingApprovals.get({ id: transactionRequestCreate.pendingApprovalId });
+      return {
+        pendingApproval: pendingApproval.toJSON(),
+        txRequestId: transactionRequestCreate.txRequestId,
+        txRequestState: transactionRequestCreate.state,
+      };
+    }
+
+    const transactionRequestSend = await commonTssMethods.sendTxRequest(
+      this.wallet.bitgo,
+      this.wallet.id(),
+      transactionRequestCreate.txRequestId,
+      RequestType.tx,
+      reqId
+    );
+
+    return {
+      txRequestId: transactionRequestCreate.txRequestId,
+      txRequestState: transactionRequestSend.state,
+    };
+  }
+
   async getPayment(paymentHash: string): Promise<PaymentInfo> {
     const response = await this.wallet.bitgo
       .get(this.wallet.bitgo.url(`/wallet/${this.wallet.id()}/lightning/payment/${paymentHash}`, 2))

modules/bitgo/test/v2/unit/lightning/lightningWallets.ts

@@ -15,6 +15,7 @@ import {
   getLightningKeychain,
   getLightningAuthKeychains,
   updateWalletCoinSpecific,
+  LightningOnchainWithdrawParams,
 } from '@bitgo/abstract-lightning';
 
 import { BitGo, common, GenerateLightningWalletOptions, Wallet, Wallets } from '../../../../src';
@@ -651,4 +652,96 @@ describe('Lightning wallets', function () {
       assert.strictEqual(signedRequest.passphrase, undefined, 'passphrase should not exist in request');
     });
   });
+  describe('On chain withdrawal', function () {
+    let wallet: LightningWallet;
+    beforeEach(function () {
+      wallet = getLightningWallet(
+        new Wallet(bitgo, basecoin, {
+          id: 'walletId',
+          coin: 'tlnbtc',
+          subType: 'lightningCustody',
+          coinSpecific: { keys: ['def', 'ghi'] },
+        })
+      ) as LightningWallet;
+    });
+    it('should withdraw on chain', async function () {
+      const params: LightningOnchainWithdrawParams = {
+        recipients: [
+          {
+            amountSat: 500000n,
+            address: 'bcrt1qjq48cqk2u80hewdcndf539m8nnnvt845nl68x7',
+          },
+        ],
+        satsPerVbyte: 15n,
+      };
+
+      const txRequestResponse = {
+        txRequestId: 'txReq123',
+        state: 'pendingDelivery',
+      };
+
+      const finalPaymentResponse = {
+        txRequestId: 'txReq123',
+        state: 'delivered',
+      };
+
+      const createTxRequestNock = nock(bgUrl)
+        .post(`/api/v2/wallet/${wallet.wallet.id()}/txrequests`)
+        .reply(200, txRequestResponse);
+
+      const sendTxRequestNock = nock(bgUrl)
+        .post(`/api/v2/wallet/${wallet.wallet.id()}/txrequests/${txRequestResponse.txRequestId}/transactions/0/send`)
+        .reply(200, finalPaymentResponse);
+
+      const response = await wallet.withdrawOnchain(params);
+      assert.strictEqual(response.txRequestId, 'txReq123');
+      assert.strictEqual(response.txRequestState, 'delivered');
+
+      createTxRequestNock.done();
+      sendTxRequestNock.done();
+    });
+
+    it('should handle pending approval when withdrawing onchain', async function () {
+      const params: LightningOnchainWithdrawParams = {
+        recipients: [
+          {
+            amountSat: 500000n,
+            address: 'bcrt1qjq48cqk2u80hewdcndf539m8nnnvt845nl68x7',
+          },
+        ],
+        satsPerVbyte: 15n,
+      };
+
+      const txRequestResponse = {
+        txRequestId: 'txReq123',
+        state: 'pendingApproval',
+        pendingApprovalId: 'approval123',
+      };
+
+      const pendingApprovalData: PendingApprovalData = {
+        id: 'approval123',
+        state: State.PENDING,
+        creator: 'user123',
+        info: {
+          type: Type.TRANSACTION_REQUEST,
+        },
+      };
+
+      const createTxRequestNock = nock(bgUrl)
+        .post(`/api/v2/wallet/${wallet.wallet.id()}/txrequests`)
+        .reply(200, txRequestResponse);
+
+      const getPendingApprovalNock = nock(bgUrl)
+        .get(`/api/v2/${coinName}/pendingapprovals/${txRequestResponse.pendingApprovalId}`)
+        .reply(200, pendingApprovalData);
+
+      const response = await wallet.withdrawOnchain(params);
+      assert.strictEqual(response.txRequestId, 'txReq123');
+      assert.strictEqual(response.txRequestState, 'pendingApproval');
+      assert(response.pendingApproval);
+
+      createTxRequestNock.done();
+      getPendingApprovalNock.done();
+    });
+  });
 });

modules/express/package.json

@@ -56,7 +56,7 @@
     "superagent": "^9.0.1"
   },
   "devDependencies": {
-    "@bitgo/public-types": "4.17.0",
+    "@bitgo/public-types": "4.26.0",
     "@bitgo/sdk-lib-mpc": "^10.2.0",
     "@bitgo/sdk-test": "^8.0.80",
     "@types/argparse": "^1.0.36",

modules/express/src/clientRoutes.ts

@@ -57,6 +57,7 @@ import { handlePayLightningInvoice } from './lightning/lightningInvoiceRoutes';
 import { handleUpdateLightningWalletCoinSpecific } from './lightning/lightningWalletRoutes';
 import { ProxyAgent } from 'proxy-agent';
 import { isLightningCoinName } from '@bitgo/abstract-lightning';
+import { handleLightningWithdraw } from './lightning/lightningWithdrawRoutes';
 
 const { version } = require('bitgo/package.json');
 const pjson = require('../package.json');
@@ -1721,6 +1722,14 @@ export function setupAPIRoutes(app: express.Application, config: Config): void {
     promiseWrapper(handlePayLightningInvoice)
   );
 
+  // lightning - onchain withdrawal
+  app.post(
+    '/api/v2/:coin/wallet/:id/lightning/withdraw',
+    parseBody,
+    prepareBitGo(config),
+    promiseWrapper(handleLightningWithdraw)
+  );
+
   // any other API v2 call
   app.use('/api/v2/user/*', parseBody, prepareBitGo(config), promiseWrapper(handleV2UserREST));
   app.use('/api/v2/:coin/*', parseBody, prepareBitGo(config), promiseWrapper(handleV2CoinSpecificREST));

modules/express/src/lightning/lightningWithdrawRoutes.ts

@@ -0,0 +1,22 @@
+import * as express from 'express';
+import { decodeOrElse } from '@bitgo/sdk-core';
+import { getLightningWallet, LightningOnchainWithdrawParams } from '@bitgo/abstract-lightning';
+import { ApiResponseError } from '../errors';
+
+export async function handleLightningWithdraw(req: express.Request): Promise<any> {
+  const bitgo = req.bitgo;
+  const params = decodeOrElse(
+    LightningOnchainWithdrawParams.name,
+    LightningOnchainWithdrawParams,
+    req.body,
+    (error) => {
+      throw new ApiResponseError(`Invalid request body for withdrawing on chain lightning balance`, 400);
+    }
+  );
+
+  const coin = bitgo.coin(req.params.coin);
+  const wallet = await coin.wallets().get({ id: req.params.id });
+  const lightningWallet = getLightningWallet(wallet);
+
+  return await lightningWallet.withdrawOnchain(params);
+}

modules/express/test/unit/lightning/lightningWithdrawRoutes.test.ts

@@ -0,0 +1,101 @@
+import * as sinon from 'sinon';
+import * as should from 'should';
+import * as express from 'express';
+import { PayInvoiceResponse } from '@bitgo/abstract-lightning';
+import { BitGo } from 'bitgo';
+import { handleLightningWithdraw } from '../../../src/lightning/lightningWithdrawRoutes';
+
+describe('Lightning Withdraw Routes', () => {
+  let bitgo;
+  const coin = 'tlnbtc';
+
+  const mockRequestObject = (params: { body?: any; params?: any; query?: any; bitgo?: any }) => {
+    const req: Partial<express.Request> = {};
+    req.body = params.body || {};
+    req.params = params.params || {};
+    req.query = params.query || {};
+    req.bitgo = params.bitgo;
+    return req as express.Request;
+  };
+
+  afterEach(() => {
+    sinon.restore();
+  });
+
+  describe('On chain withdrawal', () => {
+    it('should successfully make a on chain withdrawal', async () => {
+      const inputParams = {
+        recipients: [
+          {
+            amountSat: '500000',
+            address: 'bcrt1qjq48cqk2u80hewdcndf539m8nnnvt845nl68x7',
+          },
+        ],
+        satsPerVbyte: '15',
+      };
+
+      const expectedResponse: PayInvoiceResponse = {
+        txRequestState: 'delivered',
+        txRequestId: '123',
+      };
+
+      const onchainWithdrawStub = sinon.stub().resolves(expectedResponse);
+      const mockLightningWallet = {
+        withdrawOnchain: onchainWithdrawStub,
+      };
+
+      // Mock the module import
+      const proxyquire = require('proxyquire');
+      const lightningWithdrawRoutes = proxyquire('../../../src/lightning/lightningWithdrawRoutes', {
+        '@bitgo/abstract-lightning': {
+          getLightningWallet: () => mockLightningWallet,
+        },
+      });
+
+      const walletStub = {};
+      const coinStub = {
+        wallets: () => ({ get: sinon.stub().resolves(walletStub) }),
+      };
+      const stubBitgo = sinon.createStubInstance(BitGo as any, { coin: coinStub });
+
+      const req = mockRequestObject({
+        params: { id: 'testWalletId', coin },
+        body: inputParams,
+        bitgo: stubBitgo,
+      });
+
+      const result = await lightningWithdrawRoutes.handleLightningWithdraw(req);
+
+      should(result).deepEqual(expectedResponse);
+      should(onchainWithdrawStub).be.calledOnce();
+      const [firstArg] = onchainWithdrawStub.getCall(0).args;
+
+      const decodedRecipients = inputParams.recipients.map((recipient) => {
+        return {
+          ...recipient,
+          amountSat: BigInt(recipient.amountSat),
+        };
+      });
+
+      // we decode the amountMsat string to bigint, it should be in bigint format when passed to payInvoice
+      should(firstArg).have.property('recipients', decodedRecipients);
+      should(firstArg).have.property('satsPerVbyte', BigInt(inputParams.satsPerVbyte));
+    });
+
+    it('should throw an error if the passphrase is missing in the request params', async () => {
+      const inputParams = {
+        satsPerVbyte: '15',
+      };
+
+      const req = mockRequestObject({
+        params: { id: 'testWalletId', coin },
+        body: inputParams,
+      });
+      req.bitgo = bitgo;
+
+      await should(handleLightningWithdraw(req)).be.rejectedWith(
+        'Invalid request body for withdrawing on chain lightning balance'
+      );
+    });
+  });
+});