Merge pull request #7695 from BitGo/WIN-8153

feat(sdk-coin-iota): refactor iota sdk for beter readability

Author: parasgarg-bitgo

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

@@ -1,11 +1,90 @@
+// ========================================
+// Address and Digest Length Constants
+// ========================================
+
+/**
+ * Length of IOTA addresses in characters (excluding 0x prefix).
+ * IOTA uses 64-character hexadecimal addresses.
+ */
 export const IOTA_ADDRESS_LENGTH = 64;
+
+/**
+ * Length of transaction digest in bytes.
+ * Used for transaction IDs and hashes.
+ */
 export const IOTA_TRANSACTION_DIGEST_LENGTH = 32;
+
+/**
+ * Length of block digest in bytes.
+ * Used for block IDs and references.
+ */
 export const IOTA_BLOCK_DIGEST_LENGTH = 32;
+
+// ========================================
+// Cryptographic Constants
+// ========================================
+
+/**
+ * Length of Ed25519 signatures in bytes.
+ * IOTA uses Ed25519 for transaction signing.
+ */
 export const IOTA_SIGNATURE_LENGTH = 64;
-export const IOTA_KEY_BYTES_LENGTH = 32; // Ed25519 public key is 32 bytes
+
+/**
+ * Length of Ed25519 public keys in bytes.
+ * Standard Ed25519 key size.
+ */
+export const IOTA_KEY_BYTES_LENGTH = 32;
+
+// ========================================
+// Transaction Object Limits
+// ========================================
+
+/**
+ * Maximum number of input objects allowed in a single transaction.
+ * This limit ensures transactions can be processed efficiently by the network.
+ */
 export const MAX_INPUT_OBJECTS = 2048;
+
+/**
+ * Maximum number of gas payment objects allowed per transaction.
+ * When exceeded, objects must be merged before the transaction can be built.
+ * This prevents transaction size from becoming too large.
+ */
 export const MAX_GAS_PAYMENT_OBJECTS = 256;
+
+/**
+ * Maximum number of recipients in a transfer transaction.
+ * Limits the number of outputs to keep transaction size manageable.
+ */
+export const MAX_RECIPIENTS = 256;
+
+// ========================================
+// Gas Configuration Limits
+// ========================================
+
+/**
+ * Maximum gas budget allowed for a transaction.
+ * Used for dry-run simulations to estimate gas costs.
+ * Set to a very high value (50 billion) to ensure simulation completes.
+ */
 export const MAX_GAS_BUDGET = 50000000000;
+
+/**
+ * Maximum gas price for simulated transactions.
+ * Used when building dry-run transactions for gas estimation.
+ */
 export const MAX_GAS_PRICE = 100000;
-export const MAX_RECIPIENTS = 256; // Maximum number of recipients in a transfer transaction
+
+// ========================================
+// Transaction Command Types
+// ========================================
+
+/**
+ * Valid command types for transfer transactions.
+ * Transfer transactions can only contain these three command types:
+ * - SplitCoins: Split a coin into multiple coins with specified amounts
+ * - MergeCoins: Merge multiple coins into a single coin
+ * - TransferObjects: Transfer coins/objects to recipients
+ */
 export const TRANSFER_TRANSACTION_COMMANDS = ['SplitCoins', 'MergeCoins', 'TransferObjects'];

modules/sdk-coin-iota/src/lib/constants.ts

@@ -6,46 +6,199 @@ import {
   TransactionType,
 } from '@bitgo/sdk-core';
 
+/**
+ * Extended transaction explanation for IOTA transactions.
+ * Includes IOTA-specific fields like sender and optional sponsor.
+ *
+ * @example
+ * ```typescript
+ * const explanation: TransactionExplanation = {
+ *   type: TransactionType.Send,
+ *   sender: '0x1234...',
+ *   sponsor: '0x5678...', // Optional gas sponsor
+ *   outputAmount: '1000000',
+ *   outputs: [...],
+ *   fee: { fee: '5000' }
+ * };
+ * ```
+ */
 export interface TransactionExplanation extends BaseTransactionExplanation {
+  /** The type of transaction (e.g., Send, Receive) */
   type: BitGoTransactionType;
+
+  /** The address initiating the transaction */
   sender: string;
+
+  /**
+   * Optional gas sponsor address.
+   * When present, this address pays for the transaction's gas fees
+   * instead of the sender.
+   */
   sponsor?: string;
 }
 
+/**
+ * Represents an IOTA object (coin or NFT) used as transaction input.
+ * Objects in IOTA are versioned and content-addressable.
+ *
+ * @example
+ * ```typescript
+ * const coinObject: TransactionObjectInput = {
+ *   objectId: '0x1234...', // Unique object identifier
+ *   version: '42',         // Object version number
+ *   digest: 'ABC123...'    // Content hash
+ * };
+ * ```
+ */
 export type TransactionObjectInput = {
+  /** Unique identifier for the object (64-character hex string) */
   objectId: string;
+
+  /** Version number of the object (as string) */
   version: string;
+
+  /** Base58-encoded digest of the object's content */
   digest: string;
 };
 
+/**
+ * Gas configuration for IOTA transactions.
+ * All fields are optional to support both simulation and real transactions.
+ *
+ * @example
+ * ```typescript
+ * const gasData: GasData = {
+ *   gasBudget: 5000000,  // Maximum gas units to spend
+ *   gasPrice: 1000,      // Price per gas unit
+ *   gasPaymentObjects: [coinObject1, coinObject2]  // Coins to pay gas
+ * };
+ * ```
+ */
 export type GasData = {
+  /**
+   * Maximum amount of gas units this transaction can consume.
+   * Measured in gas units.
+   */
   gasBudget?: number;
+
+  /**
+   * Price per gas unit in MIST (smallest IOTA unit).
+   * Total fee = gasBudget * gasPrice
+   */
   gasPrice?: number;
+
+  /**
+   * Array of coin objects used to pay for gas.
+   * These objects will be consumed to cover the transaction fee.
+   */
   gasPaymentObjects?: TransactionObjectInput[];
 };
 
 /**
- * The transaction data returned from the toJson() function of a transaction
+ * Base transaction data returned from the toJson() function.
+ * Contains common fields present in all IOTA transactions.
+ *
+ * @example
+ * ```typescript
+ * const txData: TxData = {
+ *   type: TransactionType.Send,
+ *   sender: '0x1234...',
+ *   gasBudget: 5000000,
+ *   gasPrice: 1000,
+ *   gasPaymentObjects: [...],
+ *   gasSponsor: '0x5678...'  // Optional
+ * };
+ * ```
  */
 export interface TxData {
+  /** Transaction ID (digest), available after transaction is built */
   id?: string;
+
+  /** Address of the transaction sender */
   sender: string;
+
+  /** Maximum gas units allocated for this transaction */
   gasBudget?: number;
+
+  /** Price per gas unit in MIST */
   gasPrice?: number;
+
+  /** Coin objects used to pay for gas */
   gasPaymentObjects?: TransactionObjectInput[];
+
+  /**
+   * Optional address that sponsors (pays for) the gas.
+   * If not provided, the sender pays for gas.
+   */
   gasSponsor?: string;
+
+  /** Type of the transaction */
   type: TransactionType;
 }
 
+/**
+ * Transfer transaction data with recipient information.
+ * Extends TxData with transfer-specific fields.
+ *
+ * @example
+ * ```typescript
+ * const transferData: TransferTxData = {
+ *   type: TransactionType.Send,
+ *   sender: '0x1234...',
+ *   recipients: [
+ *     { address: '0xabcd...', amount: '1000000' },
+ *     { address: '0xef01...', amount: '2000000' }
+ *   ],
+ *   paymentObjects: [coinObject],
+ *   gasBudget: 5000000,
+ *   gasPrice: 1000,
+ *   gasPaymentObjects: [gasObject]
+ * };
+ * ```
+ */
 export interface TransferTxData extends TxData {
+  /**
+   * Array of recipients and the amounts they receive.
+   * Each recipient must have a valid IOTA address and amount.
+   */
   recipients: TransactionRecipient[];
+
+  /**
+   * Optional coin objects used as payment sources.
+   * These are split and transferred to recipients.
+   * If not provided, gas objects are used for payment.
+   */
   paymentObjects?: TransactionObjectInput[];
 }
 
+/**
+ * Options for explaining an IOTA transaction.
+ *
+ * @example
+ * ```typescript
+ * const explanation = await iota.explainTransaction({
+ *   txHex: '0x1234...'  // Raw transaction hex
+ * });
+ * ```
+ */
 export interface ExplainTransactionOptions {
+  /** Raw transaction data in hexadecimal format */
   txHex: string;
 }
 
+/**
+ * Options for parsing an IOTA transaction.
+ * Extends base parsing options with IOTA-specific requirements.
+ *
+ * @example
+ * ```typescript
+ * const parsed = await iota.parseTransaction({
+ *   txHex: '0x1234...'  // Raw transaction hex
+ * });
+ * // Returns: { inputs: [...], outputs: [...], fee: BigNumber }
+ * ```
+ */
 export interface IotaParseTransactionOptions extends BaseParseTransactionOptions {
+  /** Raw transaction data in hexadecimal format */
   txHex: string;
 }