Merge pull request #8891 from BitGo/CGD-1471-mpt-sdk-builders

feat(sdk-coin-xrp): add MPT transaction builders

Author: HimanshuS2212

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

@@ -5,17 +5,32 @@ import {
   VerifyAddressOptions as BaseVerifyAddressOptions,
   TransactionPrebuild,
 } from '@bitgo/sdk-core';
-import { AccountDelete, AccountSet, Amount, Payment, Signer, SignerEntry, SignerListSet, TrustSet } from 'xrpl';
+import {
+  AccountDelete,
+  AccountSet,
+  Amount,
+  MPTAmount,
+  MPTokenAuthorize,
+  Payment,
+  Signer,
+  SignerEntry,
+  SignerListSet,
+  TrustSet,
+} from 'xrpl';
 
 export enum XrpTransactionType {
   AccountDelete = 'AccountDelete',
   AccountSet = 'AccountSet',
   Payment = 'Payment',
   SignerListSet = 'SignerListSet',
   TrustSet = 'TrustSet',
+  MPTokenAuthorize = 'MPTokenAuthorize',
 }
 
-export type XrpTransaction = AccountDelete | Payment | AccountSet | SignerListSet | TrustSet;
+// Re-export so consumers can import alongside other XRP types from this module.
+export type { MPTAmount, MPTokenAuthorize };
+
+export type XrpTransaction = AccountDelete | Payment | AccountSet | SignerListSet | TrustSet | MPTokenAuthorize;
 
 export interface Address {
   address: string;
@@ -138,6 +153,10 @@ export interface TxData {
   // signer list set fields
   signerQuorum?: number;
   signerEntries?: SignerEntry[];
+  // mpt fields
+  mptIssuanceId?: string;
+  mptHolder?: string; // issuer-side auth only (Phase 2) — absent for holder self-auth
+  mptAmount?: MPTAmount;
 }
 
 export interface SignerDetails {

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

@@ -5,6 +5,8 @@ export { AccountSetBuilder } from './accountSetBuilder';
 export * from './constants';
 export * from './iface';
 export { KeyPair } from './keyPair';
+export { MPTAuthorizeBuilder } from './mpTokenAuthorizeBuilder';
+export { MPTokenTransferBuilder } from './mptTransferBuilder';
 export { TokenTransferBuilder } from './tokenTransferBuilder';
 export { Transaction } from './transaction';
 export { TransactionBuilder } from './transactionBuilder';

modules/sdk-coin-xrp/src/lib/mpTokenAuthorizeBuilder.ts

@@ -0,0 +1,85 @@
+import { BuildTransactionError, TransactionType } from '@bitgo/sdk-core';
+import { BaseCoin as CoinConfig } from '@bitgo/statics';
+import { MPTokenAuthorize } from 'xrpl';
+import { XrpTransactionType } from './iface';
+import { Transaction } from './transaction';
+import { TransactionBuilder } from './transactionBuilder';
+import utils from './utils';
+
+export class MPTAuthorizeBuilder extends TransactionBuilder {
+  private _mptIssuanceId?: string;
+  private _mptHolder?: string;
+
+  constructor(_coinConfig: Readonly<CoinConfig>) {
+    super(_coinConfig);
+  }
+
+  protected get transactionType(): TransactionType {
+    return TransactionType.MPTokenAuthorize;
+  }
+
+  protected get xrpTransactionType(): XrpTransactionType.MPTokenAuthorize {
+    return XrpTransactionType.MPTokenAuthorize;
+  }
+
+  /**
+   * Set the MPTokenIssuanceID to authorize.
+   * @param {string} id - 48-character hex MPTokenIssuanceID
+   */
+  mptIssuanceId(id: string): this {
+    if (!/^[0-9a-fA-F]{48}$/.test(id)) {
+      throw new BuildTransactionError('MPTokenIssuanceID must be a 48-character hex string (192 bits)');
+    }
+    this._mptIssuanceId = id;
+    return this;
+  }
+
+  /**
+   * Set the Holder field for issuer-side authorization (Phase 2 only).
+   * Omit for standard holder self-authorization.
+   * @param {string} address - the holder account address (must be a valid XRP address)
+   */
+  mptHolder(address: string): this {
+    if (!utils.isValidAddress(address)) {
+      throw new BuildTransactionError('Invalid holder address: ' + address);
+    }
+    this._mptHolder = address;
+    return this;
+  }
+
+  initBuilder(tx: Transaction): void {
+    super.initBuilder(tx);
+    const { mptIssuanceId, mptHolder } = tx.toJson();
+    if (mptIssuanceId) {
+      this._mptIssuanceId = mptIssuanceId;
+    }
+    if (mptHolder) {
+      this._mptHolder = mptHolder;
+    }
+  }
+
+  /** @inheritdoc */
+  protected async buildImplementation(): Promise<Transaction> {
+    if (!this._sender) {
+      throw new BuildTransactionError('Sender must be set before building the transaction');
+    }
+    if (!this._mptIssuanceId) {
+      throw new BuildTransactionError('MPTokenIssuanceID must be set before building the transaction');
+    }
+
+    const authorizeFields: MPTokenAuthorize = {
+      TransactionType: this.xrpTransactionType,
+      Account: this._sender,
+      MPTokenIssuanceID: this._mptIssuanceId,
+    };
+
+    // Omit Holder for self-authorization — setting it causes XRPL rejection on holder self-auth.
+    if (this._mptHolder) {
+      authorizeFields.Holder = this._mptHolder;
+    }
+
+    this._specificFields = authorizeFields;
+
+    return await super.buildImplementation();
+  }
+}

modules/sdk-coin-xrp/src/lib/mptTransferBuilder.ts

@@ -0,0 +1,100 @@
+import { BuildTransactionError, TransactionType } from '@bitgo/sdk-core';
+import { BaseCoin as CoinConfig } from '@bitgo/statics';
+import { MPTAmount, Payment } from 'xrpl';
+import { XrpTransactionType } from './iface';
+import { Transaction } from './transaction';
+import { TransactionBuilder } from './transactionBuilder';
+import utils from './utils';
+
+export class MPTokenTransferBuilder extends TransactionBuilder {
+  private _mptIssuanceId?: string;
+  private _value?: string;
+  private _destination?: string;
+  private _destinationTag?: number;
+
+  constructor(_coinConfig: Readonly<CoinConfig>) {
+    super(_coinConfig);
+  }
+
+  protected get transactionType(): TransactionType {
+    return TransactionType.SendMPT;
+  }
+
+  protected get xrpTransactionType(): XrpTransactionType.Payment {
+    // MPT transfers use a standard Payment transaction with an MPT Amount object
+    return XrpTransactionType.Payment;
+  }
+
+  /**
+   * Set the recipient address (with optional destination tag).
+   * @param {string} address - the recipient XRP address, optionally with destination tag
+   */
+  to(address: string): this {
+    const { address: xrpAddress, destinationTag } = utils.getAddressDetails(address);
+    this._destination = xrpAddress;
+    this._destinationTag = destinationTag;
+    return this;
+  }
+
+  /**
+   * Set the MPT issuance ID and raw integer amount to transfer.
+   * The value is a raw integer string — AssetScale is display-only and never applied here.
+   * @param {string} issuanceId - 48-character hex MPTokenIssuanceID
+   * @param {string} value - raw integer string (e.g. "1000" = 1000 base units)
+   */
+  mptAmount(issuanceId: string, value: string): this {
+    if (!/^[0-9a-fA-F]{48}$/.test(issuanceId)) {
+      throw new BuildTransactionError('MPTokenIssuanceID must be a 48-character hex string');
+    }
+    if (!/^\d+$/.test(value)) {
+      throw new BuildTransactionError('MPT value must be a non-negative integer string');
+    }
+    this._mptIssuanceId = issuanceId;
+    this._value = value;
+    return this;
+  }
+
+  initBuilder(tx: Transaction): void {
+    super.initBuilder(tx);
+    const { destination, destinationTag, mptAmount } = tx.toJson();
+    if (destination) {
+      const normalizedAddress = utils.normalizeAddress({ address: destination, destinationTag });
+      this.to(normalizedAddress);
+    }
+    if (mptAmount) {
+      this.mptAmount(mptAmount.mpt_issuance_id, mptAmount.value);
+    }
+  }
+
+  /** @inheritdoc */
+  protected async buildImplementation(): Promise<Transaction> {
+    if (!this._sender) {
+      throw new BuildTransactionError('Sender must be set before building the transaction');
+    }
+    if (!this._destination || !this._mptIssuanceId || !this._value) {
+      throw new BuildTransactionError(
+        'Missing mandatory MPT payment parameters: destination, mptIssuanceId, and value are all required'
+      );
+    }
+
+    const mptAmountObj: MPTAmount = {
+      mpt_issuance_id: this._mptIssuanceId,
+      value: this._value,
+    };
+
+    const paymentFields: Payment = {
+      TransactionType: this.xrpTransactionType,
+      Account: this._sender,
+      Destination: this._destination,
+      Amount: mptAmountObj,
+    };
+
+    if (typeof this._destinationTag === 'number') {
+      paymentFields.DestinationTag = this._destinationTag;
+    }
+
+    this._specificFields = paymentFields;
+
+    return await super.buildImplementation();
+  }
+}