@bitgo-beta/sdk-coin-iota 1.0.1-beta.91 → 1.0.1-beta.910

package/README.md

@@ -36,4 +36,4 @@ const iota = sdk.coin('iota');
 
 ## Documentation
 
-For detailed API documentation, see the [BitGo API reference](https://app.bitgo.com/docs/).
+For detailed API documentation, view the BitGo [Developer Portal](https://developers.bitgo.com/reference/overview#/).

package/dist/src/iota.d.ts

@@ -1,58 +1,284 @@
-import { AuditDecryptedKeyParams, BaseCoin, BitGoBase, KeyPair, ParseTransactionOptions, ParsedTransaction, SignTransactionOptions, SignedTransaction, VerifyTransactionOptions, MultisigType, MPCAlgorithm, TssVerifyAddressOptions } from '@bitgo-beta/sdk-core';
+import { AuditDecryptedKeyParams, BaseCoin, BitGoBase, EddsaSigningMaterial, KeyPair, MPCAlgorithm, MPCConsolidationRecoveryOptions, MPCRecoveryOptions, MPCSweepTxs, MPCTxs, MultisigType, ParsedTransaction, PopulatedIntent, PrebuildTransactionWithIntentOptions, signEddsaMpcV2RecoveryTx, SignedTransaction, SignTransactionOptions, TssVerifyAddressOptions, VerifyTransactionOptions } from '@bitgo-beta/sdk-core';
 import { BaseCoin as StaticsBaseCoin, CoinFamily } from '@bitgo-beta/statics';
+import { ExplainTransactionOptions, IotaParseTransactionOptions, TransactionExplanation } from './lib/iface';
+export interface IotaRecoveryOptions extends MPCRecoveryOptions {
+    fullnodeRpcUrl?: string;
+}
+/**
+ * IOTA coin implementation.
+ * Supports TSS (Threshold Signature Scheme) with EDDSA algorithm.
+ */
 export declare class Iota extends BaseCoin {
     protected readonly _staticsCoin: Readonly<StaticsBaseCoin>;
     protected constructor(bitgo: BitGoBase, staticsCoin?: Readonly<StaticsBaseCoin>);
+    /**
+     * Factory method to create an IOTA coin instance.
+     */
     static createInstance(bitgo: BitGoBase, staticsCoin?: Readonly<StaticsBaseCoin>): BaseCoin;
     getBaseFactor(): string | number;
     getChain(): string;
     getFamily(): CoinFamily;
     getFullName(): string;
-    /** @inheritDoc */
     supportsTss(): boolean;
-    /** inherited doc */
     getDefaultMultisigType(): MultisigType;
     getMPCAlgorithm(): MPCAlgorithm;
     /**
-     * Check if an address is valid
-     * @param address the address to be validated
+     * Validates an IOTA address.
+     * @param address - The address to validate (64-character hex string)
      * @returns true if the address is valid
      */
     isValidAddress(address: string): boolean;
     /**
-     * Verifies that a transaction prebuild complies with the original intention
-     * @param params
+     * Validates a public key.
+     * @param pub - The public key to validate
+     * @returns true if the public key is valid
      */
-    verifyTransaction(params: VerifyTransactionOptions): Promise<boolean>;
+    isValidPub(pub: string): boolean;
     /**
-     * Check if an address belongs to a wallet
-     * @param params
+     * Verifies if an address belongs to a TSS wallet.
+     * @param params - Verification parameters including wallet address and user/backup public keys
+     * @returns true if the address belongs to the wallet
      */
     isWalletAddress(params: TssVerifyAddressOptions): Promise<boolean>;
     /**
-     * Parse a transaction
-     * @param params
+     * Explains a transaction by parsing its hex representation.
+     * @param params - Parameters containing the transaction hex
+     * @returns Detailed explanation of the transaction
+     * @throws Error if txHex is missing or transaction cannot be explained
      */
-    parseTransaction(params: ParseTransactionOptions): Promise<ParsedTransaction>;
+    explainTransaction(params: ExplainTransactionOptions): Promise<TransactionExplanation>;
     /**
-     * Generate a key pair
-     * @param seed Optional seed to generate key pair from
+     * Verifies that a transaction prebuild matches the original transaction parameters.
+     * Ensures recipients and amounts align with the intended transaction.
+     *
+     * @param params - Verification parameters containing prebuild and original params
+     * @returns true if verification succeeds
+     * @throws Error if verification fails
      */
-    generateKeyPair(seed?: Buffer): KeyPair;
+    verifyTransaction(params: VerifyTransactionOptions): Promise<boolean>;
     /**
-     * Check if a public key is valid
-     * @param pub Public key to check
+     * Parses a transaction and extracts inputs, outputs, and fees.
+     * @param params - Parameters containing the transaction hex
+     * @returns Parsed transaction with inputs, outputs, and fee information
      */
-    isValidPub(pub: string): boolean;
+    parseTransaction(params: IotaParseTransactionOptions): Promise<ParsedTransaction>;
     /**
-     * Sign a transaction
-     * @param params
+     * Generates a key pair for IOTA transactions.
+     * @param seed - Optional seed to generate deterministic key pair
+     * @returns Key pair with public and private keys
+     * @throws Error if private key generation fails
+     */
+    generateKeyPair(seed?: Buffer): KeyPair;
+    /**
+     * Signs a transaction (not implemented for IOTA).
+     * IOTA transactions are signed externally using TSS.
      */
     signTransaction(params: SignTransactionOptions): Promise<SignedTransaction>;
     /**
-     * Audit a decrypted private key to ensure it's valid
-     * @param params
+     * Audits a decrypted private key to ensure it's valid for the given public key.
+     * @param params - Parameters containing multiSigType, private key, and public key
+     * @throws Error if multiSigType is not TSS or if key validation fails
      */
     auditDecryptedKey({ multiSigType, prv, publicKey }: AuditDecryptedKeyParams): void;
+    /**
+     * Extracts the signable payload from a serialized transaction.
+     * @param serializedTx - The serialized transaction hex
+     * @returns Buffer containing the signable payload
+     */
+    getSignablePayload(serializedTx: string): Promise<Buffer>;
+    /**
+     * @inheritDoc
+     */
+    allowsAccountConsolidations(): boolean;
+    /**
+     * Sets coin-specific fields in the transaction intent.
+     * @param intent - The populated intent object to modify
+     * @param params - Parameters containing unspents data
+     */
+    setCoinSpecificFieldsInIntent(intent: PopulatedIntent, params: PrebuildTransactionWithIntentOptions): void;
+    /**
+     * Builds funds recovery transaction(s) without BitGo
+     *
+     * @param {IotaRecoveryOptions} params parameters needed to construct and
+     * (maybe) sign the transaction
+     * @param {EddsaSigningMaterial} [precomputedMaterial] signing material detected once by the
+     * caller (e.g. recoverConsolidations) to avoid re-decrypting the keycard on every loop iteration
+     *
+     * @returns {MPCTx | MPCSweepTxs} array of the serialized transaction hex strings and indices
+     * of the addresses being swept
+     */
+    recover(params: IotaRecoveryOptions, precomputedMaterial?: EddsaSigningMaterial): Promise<MPCTxs | MPCSweepTxs>;
+    /**
+     * Checks whether the address holds a positive balance of the specified token.
+     */
+    private hasTokenBalance;
+    /**
+     * Consolidates funds from multiple receive addresses to the base address (index 0).
+     * If walletPassphrase is not provided, returns unsigned transactions for offline signing
+     * (cold/custody wallet recovery). Otherwise, returns signed transactions.
+     *
+     * @param params - Consolidation recovery parameters
+     * @param params.bitgoKey - The commonKeychain (combined TSS public key)
+     * @param params.startingScanIndex - Starting address index to scan (default: 1)
+     * @param params.endingScanIndex - Ending address index to scan (default: startingScanIndex + 20)
+     * @param params.walletPassphrase - Optional passphrase for signing (omit for unsigned transactions)
+     * @returns MPCTxs (signed) or MPCSweepTxs (unsigned) containing all consolidation transactions
+     * @throws Error if no addresses with funds are found in the scan range
+     */
+    recoverConsolidations(params: MPCConsolidationRecoveryOptions): Promise<MPCTxs | MPCSweepTxs>;
+    /**
+     * Gets the total coin balance for an address.
+     *
+     * @param address - IOTA address to query
+     * @param rpcUrl - Optional RPC URL override
+     * @param coinType - Optional coin type (defaults to native IOTA)
+     * @returns Total balance as a bigint
+     */
+    private getBalance;
+    /**
+     * Fetches owned objects for an address via fullnode RPC.
+     * Handles pagination to retrieve all objects.
+     *
+     * @param address - IOTA address to query
+     * @param rpcUrl - Optional RPC URL override
+     * @param coinType - Optional coin type to filter objects (defaults to native IOTA)
+     * @returns Array of owned objects with balance information
+     */
+    private fetchOwnedObjects;
+    /**
+     * Makes JSON-RPC call to IOTA fullnode.
+     *
+     * @param url - Fullnode RPC URL
+     * @param method - RPC method name
+     * @param params - RPC parameters
+     * @returns RPC result
+     * @throws Error if RPC call fails
+     */
+    private makeRpcCall;
+    /**
+     * Gets the public node RPC URL from the centralized environment configuration.
+     *
+     * @returns RPC URL for the current BitGo environment
+     */
+    protected getPublicNodeUrl(): string;
+    /**
+     * Gets the native coin type identifier for filtering owned objects.
+     *
+     * @returns Native coin type string
+     */
+    private getNativeCoinType;
+    /**
+     * Prepares gas configuration for a recovery transaction.
+     *
+     * Gas estimation is done via a dry-run of a temporary transaction, then
+     * multiplied by DEFAULT_GAS_OVERHEAD (1.1x) as a safety buffer.
+     *
+     * @param ownedObjects - Native IOTA coin objects to use as gas payment
+     * @param senderAddress - Sender address for the transaction
+     * @param params - Recovery parameters (includes recoveryDestination, rpcUrl)
+     * @param paymentObjects - Optional token objects for token recovery
+     * @returns Gas budget, gas price, gas objects array, and total native balance
+     */
+    private prepareGasAndObjects;
+    private recoverIotaToken;
+    /**
+     * Detects MPCv1 vs MPCv2 keycard format and returns typed signing material.
+     * Wrapped as a protected method so sinon can stub it in tests (matching DOT/SUI).
+     */
+    protected getEddsaSigningMaterial(userKey: string, walletPassphrase: string): Promise<EddsaSigningMaterial>;
+    /**
+     * Runs the MPCv2 (MPS) recovery signing flow and returns the raw 64-byte Ed25519 signature.
+     * Wrapped as a protected method so sinon can stub it in tests (matching DOT/SUI).
+     */
+    protected signIotaMpcV2Recovery(params: Parameters<typeof signEddsaMpcV2RecoveryTx>[0]): Promise<Buffer>;
+    private signRecoveryTransaction;
+    /**
+     * Fetches current reference gas price from fullnode.
+     *
+     * @param rpcUrl - Optional RPC URL override
+     * @returns Current gas price
+     */
+    private fetchGasPrice;
+    /**
+     * Estimates gas for a transaction via dry run.
+     *
+     * @param txBase64 - Transaction in base64 format
+     * @param rpcUrl - Optional RPC URL override
+     * @returns Estimated gas cost
+     */
+    private estimateGas;
+    private buildUnsignedSweepTransaction;
+    /**
+     * Validates and extracts transaction hex from parameters.
+     * @param txHex - The transaction hex to validate
+     * @param operation - The operation being performed (for error messages)
+     * @returns The validated transaction hex
+     * @throws Error if txHex is missing
+     */
+    private validateAndExtractTxHex;
+    /**
+     * Validates that the transaction is a TransferTransaction.
+     * @param transaction - The transaction to validate
+     * @throws Error if transaction is not a TransferTransaction
+     */
+    private validateTransactionType;
+    /**
+     * Verifies that transaction recipients match the expected recipients.
+     * @param transaction - The transfer transaction to verify
+     * @param expectedRecipients - The expected recipients from transaction params
+     * @throws Error if recipients don't match
+     */
+    private verifyTransactionRecipients;
+    /**
+     * Normalizes recipients by extracting only relevant fields.
+     * @param recipients - Recipients to normalize
+     * @returns Normalized recipients with address, amount, and tokenName only
+     */
+    private normalizeRecipients;
+    /**
+     * Checks if expected recipients match actual recipients.
+     * @param expected - Expected recipients
+     * @param actual - Actual recipients from transaction
+     * @returns true if all expected recipients are found in actual recipients
+     */
+    private recipientsMatch;
+    /**
+     * Creates an empty parsed transaction result.
+     * Used when transaction has no outputs.
+     */
+    private createEmptyParsedTransaction;
+    /**
+     * Calculates the transaction fee from the explanation.
+     * @param explanation - The transaction explanation
+     * @returns The fee as a BigNumber
+     */
+    private calculateTransactionFee;
+    /**
+     * Builds the inputs array for a parsed transaction.
+     * Includes sender input and optionally sponsor input if present.
+     *
+     * @param explanation - The transaction explanation
+     * @param fee - The calculated transaction fee
+     * @returns Array of transaction inputs
+     */
+    private buildTransactionInputs;
+    /**
+     * Builds the outputs array for a parsed transaction.
+     * @param explanation - The transaction explanation
+     * @returns Array of transaction outputs
+     */
+    private buildTransactionOutputs;
+    /**
+     * Creates a transaction builder factory instance.
+     * @returns TransactionBuilderFactory for this coin
+     */
+    private getTxBuilderFactory;
+    /**
+     * Rebuilds a transaction from its hex representation.
+     * @param txHex - The transaction hex to rebuild
+     * @returns The rebuilt transaction
+     * @throws Error if transaction cannot be rebuilt
+     */
+    private rebuildTransaction;
 }
 //# sourceMappingURL=iota.d.ts.map

package/dist/src/iota.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"iota.d.ts","sourceRoot":"","sources":["../../src/iota.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,QAAQ,EACR,SAAS,EACT,OAAO,EACP,uBAAuB,EACvB,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EACjB,wBAAwB,EACxB,YAAY,EAEZ,YAAY,EAGZ,uBAAuB,EAExB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,QAAQ,IAAI,eAAe,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAK9E,qBAAa,IAAK,SAAQ,QAAQ;IAChC,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;IAE3D,SAAS,aAAa,KAAK,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,QAAQ,CAAC,eAAe,CAAC;IAU/E,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,QAAQ;IAI1F,aAAa,IAAI,MAAM,GAAG,MAAM;IAIhC,QAAQ;IAIR,SAAS,IAAI,UAAU;IAIvB,WAAW;IAIX,kBAAkB;IAClB,WAAW,IAAI,OAAO;IAItB,oBAAoB;IACpB,sBAAsB,IAAI,YAAY;IAItC,eAAe,IAAI,YAAY;IAI/B;;;;OAIG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAKxC;;;OAGG;IACG,iBAAiB,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,OAAO,CAAC;IAK3E;;;OAGG;IACG,eAAe,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC;IA0BxE;;;OAGG;IACG,gBAAgB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAKnF;;;OAGG;IACH,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO;IAYvC;;;OAGG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIhC;;;OAGG;IACG,eAAe,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIjF;;;OAGG;IACH,iBAAiB,CAAC,EAAE,YAAY,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,uBAAuB,GAAG,IAAI;CAMnF"}
+{"version":3,"file":"iota.d.ts","sourceRoot":"","sources":["../../src/iota.ts"],"names":[],"mappings":"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"}