@hiero-ledger/sdk 2.70.0

package/src/transaction/BatchTransaction.js

@@ -0,0 +1,293 @@
+import FreezeTransaction from "../system/FreezeTransaction.js";
+import Transaction, { TRANSACTION_REGISTRY } from "./Transaction.js";
+import { proto } from "@hashgraph/proto";
+
+/**
+ * @namespace proto
+ * @typedef {import("@hashgraph/proto").proto.ITransaction} HieroProto.proto.ITransaction
+ * @typedef {import("@hashgraph/proto").proto.ITransactionBody} HieroProto.proto.ITransactionBody
+ * @typedef {import("@hashgraph/proto").proto.TransactionBody} HieroProto.proto.TransactionBody
+ * @typedef {import("@hashgraph/proto").proto.ITransactionResponse} HieroProto.proto.ITransactionResponse
+ */
+
+/**
+ * @typedef {import("../channel/Channel.js").default} Channel
+ * @typedef {import("../transaction/TransactionId.js").default} TransactionId
+ * @typedef {import("../account/AccountId.js").default} AccountId
+ * @typedef {import("../Key.js").default} Key
+ */
+
+/**
+ * @description Execute multiple transactions in a single consensus event. This allows for atomic execution of multiple
+ * transactions, where they either all succeed or all fail together.
+ * <p>
+ * Requirements:
+ * <ul>
+ *     <li>All inner transactions must be frozen before being added to the batch</li>
+ *     <li>All inner transactions must have a batch key set</li>
+ *     <li>All inner transactions must be signed as required for each individual transaction</li>
+ *     <li>The BatchTransaction must be signed by all batch keys of the inner transactions</li>
+ *     <li>Certain transaction types (FreezeTransaction, BatchTransaction) are not allowed in a batch</li>
+ * </ul>
+ * <p>
+ * Important notes:
+ * <ul>
+ *     <li>Fees are assessed for each inner transaction separately</li>
+ *     <li>The maximum number of inner transactions in a batch is limited to 25</li>
+ *     <li>Inner transactions cannot be scheduled transactions</li>
+ * </ul>
+ *
+ */
+export default class BatchTransaction extends Transaction {
+    /**
+     * @param {object} [options]
+     * @param {Transaction[] | null} [options.transactions]
+     */
+    constructor(options) {
+        super();
+        this._batchTransactions = options?.transactions || [];
+    }
+
+    /**
+     * Set the list of transactions to be executed as part of this BatchTransaction.
+     * <p>
+     * Requirements for each inner transaction:
+     * <ul>
+     *     <li>Must be frozen (use {@link Transaction#freeze()} or {@link Transaction#freezeWith(Client)})</li>
+     *     <li>Must have a batch key set (use {@link Transaction#setBatchKey(Key)}} or {@link Transaction#batchify(Client, Key)})</li>
+     *     <li>Must not be a blacklisted transaction type</li>
+     * </ul>
+     * <p>
+     * Note: This method creates a defensive copy of the provided list.
+     *
+     * @param {Transaction[]} txs
+     * @returns {BatchTransaction}
+     */
+    setInnerTransactions(txs) {
+        txs.forEach((tx) => this._validateTransaction(tx));
+        this._batchTransactions = txs;
+        return this;
+    }
+
+    /**
+     * Append a transaction to the list of transactions this BatchTransaction will execute.
+     * <p>
+     * Requirements for the inner transaction:
+     * <ul>
+     *     <li>Must be frozen (use {@link Transaction#freeze()} or {@link Transaction#freezeWith(Client)})</li>
+     *     <li>Must have a batch key set (use {@link Transaction#setBatchKey(Key)}} or {@link Transaction#batchify(Client, Key)})</li>
+     *     <li>Must not be a blacklisted transaction type</li>
+     * </ul>
+     *
+     * @param {Transaction} tx
+     * @returns {BatchTransaction}
+     */
+    addInnerTransaction(tx) {
+        this._validateTransaction(tx);
+        this._requireNotFrozen();
+        this._batchTransactions.push(tx);
+        return this;
+    }
+
+    /**
+     * Get the list of transactions this BatchTransaction is currently configured to execute.
+     * <p>
+     * Note: This returns the actual list of transactions. Modifications to this list will affect
+     * the batch transaction if it is not frozen.
+     *
+     * @returns {Transaction[]}
+     */
+    get innerTransactions() {
+        return this._batchTransactions;
+    }
+
+    /**
+     * Get the list of transaction IDs of each inner transaction of this BatchTransaction.
+     * <p>
+     * This method is particularly useful after execution to:
+     * <ul>
+     *     <li>Track individual transaction results</li>
+     *     <li>Query receipts for specific inner transactions</li>
+     *     <li>Monitor the status of each transaction in the batch</li>
+     * </ul>
+     * <p>
+     * <b>NOTE:</b> Transaction IDs will only be meaningful after the batch transaction has been
+     * executed or the IDs have been explicitly set on the inner transactions.
+     *
+     * @returns {(TransactionId | null)[]}
+     */
+    get innerTransactionIds() {
+        if (!Array.isArray(this._batchTransactions)) {
+            return [];
+        }
+
+        return this._batchTransactions.map((tx) => tx.transactionId);
+    }
+
+    /**
+     *
+     * @returns {proto.AtomicBatchTransactionBody}
+     */
+    _makeTransactionData() {
+        if (!Array.isArray(this._batchTransactions)) {
+            return {
+                transactions: [],
+            };
+        }
+
+        const signedTransactionBytes = this._batchTransactions.map((tx) =>
+            proto.SignedTransaction.encode(
+                tx._signedTransactions.get(0),
+            ).finish(),
+        );
+        return {
+            transactions: signedTransactionBytes,
+        };
+    }
+
+    /**
+     * @internal
+     * @param {proto.ITransaction[]} transactions
+     * @param {proto.ISignedTransaction[]} signedTransactions
+     * @param {TransactionId[]} transactionIds
+     * @param {AccountId[]} nodeIds
+     * @param {HieroProto.proto.ITransactionBody[]} bodies
+     * @returns {BatchTransaction}
+     */
+    static _fromProtobuf(
+        transactions,
+        signedTransactions,
+        transactionIds,
+        nodeIds,
+        bodies,
+    ) {
+        const body = bodies[0];
+        const atomicBatchTxBytes = body.atomicBatch?.transactions;
+
+        const atomicBatchSignedTransactions = atomicBatchTxBytes?.map((tx) =>
+            proto.SignedTransaction.decode(tx),
+        );
+
+        const atomicBatchTxs = atomicBatchSignedTransactions?.map((tx) => {
+            const txBody = proto.TransactionBody.decode(tx.bodyBytes);
+            const txType = txBody.data;
+            if (!txType) {
+                throw new Error("Transaction type not found");
+            }
+
+            const fromProtobuf = TRANSACTION_REGISTRY.get(txType);
+            if (!fromProtobuf) {
+                throw new Error("fromProtobuf not found");
+            }
+            /* Inner transactions only have one signed transactios therefore
+            the other properties are empty that are needed from the 
+            Transaction._fromProtobufTransactions method
+            */
+
+            /**
+             * @type {proto.ITransaction[]}
+             */
+            const innerTransactions = [];
+            /**
+             * @type {proto.ISignedTransaction[]}
+             */
+            const signedInnerTransactions = [tx];
+            /**
+             * @type {TransactionId[]}
+             */
+            const innerTransactionIds = [];
+
+            /**
+             * Node account IDs is empty for inner transactions
+             * @type {AccountId[]}
+             */
+            const nodeAccountIds = [];
+
+            /**
+             * @type {HieroProto.proto.TransactionBody[]}
+             */
+            const bodies = [txBody];
+
+            return fromProtobuf(
+                innerTransactions,
+                signedInnerTransactions,
+                innerTransactionIds,
+                nodeAccountIds,
+                bodies,
+            );
+        });
+
+        return Transaction._fromProtobufTransactions(
+            new BatchTransaction({
+                transactions: atomicBatchTxs,
+            }),
+            transactions,
+            signedTransactions,
+            transactionIds,
+            nodeIds,
+            bodies,
+        );
+    }
+
+    /**
+     * This method returns a key for the `data` field in a transaction body.
+     * Each transaction overwrite this to make sure when we build the transaction body
+     * we set the right data field.
+     *
+     * @abstract
+     * @protected
+     * @returns {NonNullable<HieroProto.proto.TransactionBody["data"]>}
+     */
+    _getTransactionDataCase() {
+        return "atomicBatch";
+    }
+
+    /**
+     * @description Get the log ID for the BatchTransaction.
+     * @returns {string}
+     */
+    _getLogId() {
+        const timestamp = /** @type {import("../Timestamp.js").default} */ (
+            this._transactionIds.current.validStart
+        );
+        return `AtomicBatch:${timestamp.toString()}`;
+    }
+
+    /**
+     * @override
+     * @internal
+     * @param {Channel} channel
+     * @param {HieroProto.proto.ITransaction} request
+     * @returns {Promise<HieroProto.proto.ITransactionResponse>}
+     */
+    _execute(channel, request) {
+        return channel.util.atomicBatch(request);
+    }
+
+    /**
+     * @description Validate the transaction
+     * @param {Transaction} tx
+     * @throws {Error} If the transaction is a batch or freeze transaction
+     */
+    _validateTransaction(tx) {
+        if (tx instanceof BatchTransaction || tx instanceof FreezeTransaction) {
+            throw new Error(
+                "Transaction is not allowed to be added to a batch",
+            );
+        }
+        if (!tx.isFrozen()) {
+            throw new Error(
+                "Transaction must be frozen before being added to a batch",
+            );
+        }
+        if (!tx.batchKey) {
+            throw new Error("Transaction must have a batch key");
+        }
+    }
+}
+
+TRANSACTION_REGISTRY.set(
+    "atomicBatch",
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    BatchTransaction._fromProtobuf,
+);

package/src/transaction/CustomFeeLimit.js

@@ -0,0 +1,121 @@
+import AccountId from "../account/AccountId.js";
+import CustomFixedFee from "../token/CustomFixedFee.js";
+
+/**
+ * @namespace proto
+ * @typedef {import("@hashgraph/proto").proto.IFixedFee} HieroProto.proto.IFixedFee
+ * @typedef {import("@hashgraph/proto").proto.ICustomFeeLimit} HieroProto.proto.ICustomFeeLimit
+ */
+
+export default class CustomFeeLimit {
+    /**
+     *
+     * @param {object} props
+     * @param {?AccountId | string} [props.accountId]
+     * @param {?CustomFixedFee[]} [props.fees]
+     */
+    constructor(props = {}) {
+        /**
+         * @type {?AccountId}
+         */
+        this._accountId = null;
+
+        if (props.accountId) {
+            this.setAccountId(props.accountId);
+        }
+
+        /**
+         * @type {?CustomFixedFee[]}
+         */
+        this._fees = null;
+
+        if (props.fees) {
+            this.setFees(props.fees);
+        }
+    }
+
+    /**
+     * @static
+     * @param {HieroProto.proto.ICustomFeeLimit} customFeeLimit
+     * @returns {CustomFeeLimit}
+     */
+    static _fromProtobuf(customFeeLimit) {
+        return new CustomFeeLimit({
+            accountId:
+                customFeeLimit.accountId != null
+                    ? AccountId._fromProtobuf(customFeeLimit.accountId)
+                    : null,
+            fees:
+                customFeeLimit.fees != null
+                    ? customFeeLimit.fees.map((fixedFee) => {
+                          return CustomFixedFee._fromProtobuf({
+                              fixedFee: fixedFee,
+                          });
+                      })
+                    : null,
+        });
+    }
+
+    /**
+     * @returns {?AccountId}
+     */
+    getAccountId() {
+        return this._accountId;
+    }
+
+    /**
+     *
+     * @param {AccountId | string} accountId
+     * @returns {this}
+     */
+    setAccountId(accountId) {
+        if (accountId instanceof AccountId) {
+            this._accountId = accountId;
+        } else {
+            this._accountId = AccountId.fromString(accountId);
+        }
+        return this;
+    }
+
+    /**
+     * @returns {?CustomFixedFee[]}
+     */
+    getFees() {
+        return this._fees;
+    }
+
+    /**
+     *
+     * @param {CustomFixedFee[]} fees
+     * @returns {this}
+     */
+    setFees(fees) {
+        this._fees = fees;
+
+        return this;
+    }
+
+    /**
+     *
+     * @returns {HieroProto.proto.ICustomFeeLimit}
+     */
+    _toProtobuf() {
+        /** @type {HieroProto.proto.IFixedFee[]} */
+        const protoFixedFees = [];
+
+        if (this._fees != null) {
+            this._fees.forEach((fixedFee) => {
+                const fixedFeeProto = fixedFee._toProtobuf();
+                if (fixedFeeProto.fixedFee != null) {
+                    protoFixedFees.push(fixedFeeProto.fixedFee);
+                }
+            });
+        }
+
+        return {
+            accountId:
+                this._accountId != null ? this._accountId._toProtobuf() : null,
+            fees: protoFixedFees,
+        };
+    }
+}

package/src/transaction/List.js

@@ -0,0 +1,175 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * A custom list type which round robins, supports locking, and as additional
+ * QoL improvements.
+ *
+ * @template {any} T
+ */
+export default class List {
+    constructor() {
+        /** @type {T[]} */
+        this.list = [];
+        this.locked = false;
+        this.index = 0;
+    }
+
+    /**
+     * Overwrite the entire list.
+     *
+     * @throws if the list is locked
+     * @param {T[]} list
+     * @returns {this}
+     */
+    setList(list) {
+        if (this.locked) {
+            throw new Error("list is locked");
+        }
+
+        this.list = list;
+        this.index = 0;
+
+        return this;
+    }
+
+    /**
+     * Push items to the end of the list.
+     *
+     * @throws if the list is locked
+     * @param {T[]} items
+     * @returns {this}
+     */
+    push(...items) {
+        if (this.locked) {
+            throw new Error("list is locked");
+        }
+
+        this.list.push(...items);
+        return this;
+    }
+
+    /**
+     * Locks the list.
+     *
+     * @returns {this}
+     */
+    setLocked() {
+        this.locked = true;
+        return this;
+    }
+
+    /**
+     * Clear the list
+     */
+    clear() {
+        this.list = [];
+        this.index = 0;
+        this.locked = false;
+    }
+
+    /**
+     * The get value at a particular index.
+     *
+     * @param {number} index
+     * @returns {T}
+     */
+    get(index) {
+        return this.list[index];
+    }
+
+    /**
+     * Set value at index
+     *
+     * @param {number} index
+     * @param {T} item
+     * @returns {this}
+     */
+    set(index, item) {
+        // QoL: If the index is at the end simply push the element to the end
+        if (index === this.length) {
+            this.list.push(item);
+        } else {
+            this.list[index] = item;
+        }
+
+        return this;
+    }
+
+    /**
+     * Set value at index if it's not already set
+     *
+     * @throws if the list is locked
+     * @param {number} index
+     * @param {() => T} lambda
+     * @returns {this}
+     */
+    setIfAbsent(index, lambda) {
+        if (index == this.length || this.list[index] == null) {
+            this.set(index, lambda());
+        }
+
+        return this;
+    }
+
+    /**
+     * Get the current value, and advance the index
+     *
+     * @returns {T}
+     */
+    get next() {
+        return this.get(this.advance());
+    }
+
+    /**
+     * Get the current value.
+     *
+     * @returns {T}
+     */
+    get current() {
+        return this.get(this.index);
+    }
+
+    /**
+     * Advance the index to the next element in a round robin fashion
+     *
+     * @returns {number}
+     */
+    advance() {
+        const index = this.index;
+        this.index = (this.index + 1) % this.list.length;
+        return index;
+    }
+
+    /**
+     * Is the list empty
+     *
+     * @returns {boolean}
+     */
+    get isEmpty() {
+        return this.length === 0;
+    }
+
+    /**
+     * Get the length of the list
+     *
+     * @returns {number}
+     */
+    get length() {
+        return this.list.length;
+    }
+
+    /**
+     * Shallow clone this list.
+     * Perhaps we should explicitly call this `shallowClone()` since it doesn't
+     * clone the list inside?
+     *
+     * @returns {List<T>}
+     */
+    clone() {
+        /** @type {List<T>} */
+        const list = new List();
+        list.list = this.list;
+        list.locked = this.locked;
+        return list;
+    }
+}

package/src/transaction/NodeAccountIdSignatureMap.js

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import ObjectMap from "../ObjectMap.js";
+import TransactionId from "./TransactionId.js";
+import SignaturePairMap from "./SignaturePairMap.js";
+import * as HieroProto from "@hashgraph/proto";
+
+/**
+ * @augments {ObjectMap<TransactionId, SignaturePairMap>}
+ */
+export default class NodeAccountIdSignatureMap extends ObjectMap {
+    constructor() {
+        super((s) => TransactionId.fromString(s));
+    }
+
+    /**
+     * This function is used to create a NodeAccountIdSignaturemap from an already built transaction.
+     * @param { import('./List.js').default<import("@hashgraph/proto").proto.ISignedTransaction>} signedTransactions
+     * @returns {NodeAccountIdSignatureMap}
+     */
+    static _fromSignedTransactions(signedTransactions) {
+        const signatures = new NodeAccountIdSignatureMap();
+
+        for (const { bodyBytes, sigMap } of signedTransactions.list) {
+            if (bodyBytes != null && sigMap != null) {
+                const body = HieroProto.proto.TransactionBody.decode(bodyBytes);
+
+                if (body.transactionID != null) {
+                    const transactionId = TransactionId._fromProtobuf(
+                        body.transactionID,
+                    );
+
+                    signatures._set(
+                        transactionId,
+                        SignaturePairMap._fromTransactionSigMap(sigMap),
+                    );
+                }
+            }
+        }
+
+        return signatures;
+    }
+
+    /**
+     *
+     * Adds a signature pair for this transaction id.
+     * @param {TransactionId} txId
+     * @param {import("../SignerSignature.js").PublicKey} publicKey
+     * @param {Uint8Array} signature
+     */
+    addSignature(txId, publicKey, signature) {
+        const sigPairMap = this.get(txId);
+        if (sigPairMap) {
+            sigPairMap.addSignature(publicKey, signature);
+        } else {
+            this._set(
+                txId,
+                new SignaturePairMap().addSignature(publicKey, signature),
+            );
+        }
+    }
+}

package/src/transaction/NodeAccountIdSignatureMapLegacy.js

@@ -0,0 +1,41 @@
+import ObjectMap from "../ObjectMap.js";
+import PublicKey from "../PublicKey.js";
+
+/**
+ * @deprecated
+ * @augments {ObjectMap<PublicKey, Uint8Array>}
+ */
+export default class NodeAccountIdSignatureMap extends ObjectMap {
+    constructor() {
+        super((s) => PublicKey.fromString(s));
+    }
+
+    /**
+     * @param {import("@hashgraph/proto").proto.ISignatureMap} sigMap
+     * @returns {NodeAccountIdSignatureMap}
+     */
+    static _fromTransactionSigMap(sigMap) {
+        // eslint-disable-next-line deprecation/deprecation
+        const signatures = new NodeAccountIdSignatureMap();
+        const sigPairs = sigMap.sigPair != null ? sigMap.sigPair : [];
+
+        for (const sigPair of sigPairs) {
+            if (sigPair.pubKeyPrefix != null) {
+                if (sigPair.ed25519 != null) {
+                    signatures._set(
+                        PublicKey.fromBytesED25519(sigPair.pubKeyPrefix),
+                        sigPair.ed25519,
+                    );
+                } else if (sigPair.ECDSASecp256k1 != null) {
+                    signatures._set(
+                        PublicKey.fromBytesECDSA(sigPair.pubKeyPrefix),
+
+                        sigPair.ECDSASecp256k1,
+                    );
+                }
+            }
+        }
+
+        return signatures;
+    }
+}