@hiero-ledger/sdk 2.70.0

package/src/file/FileUpdateTransaction.js

@@ -0,0 +1,375 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import Transaction, {
+    TRANSACTION_REGISTRY,
+} from "../transaction/Transaction.js";
+import Timestamp from "../Timestamp.js";
+import * as utf8 from "../encoding/utf8.js";
+import FileId from "./FileId.js";
+import Key from "../Key.js";
+import KeyList from "../KeyList.js";
+
+/**
+ * @namespace proto
+ * @typedef {import("@hashgraph/proto").proto.ITransaction} HieroProto.proto.ITransaction
+ * @typedef {import("@hashgraph/proto").proto.ISignedTransaction} HieroProto.proto.ISignedTransaction
+ * @typedef {import("@hashgraph/proto").proto.TransactionBody} HieroProto.proto.TransactionBody
+ * @typedef {import("@hashgraph/proto").proto.ITransactionBody} HieroProto.proto.ITransactionBody
+ * @typedef {import("@hashgraph/proto").proto.ITransactionResponse} HieroProto.proto.ITransactionResponse
+ * @typedef {import("@hashgraph/proto").proto.IFileUpdateTransactionBody} HieroProto.proto.IFileUpdateTransactionBody
+ */
+
+/**
+ * @typedef {import("../channel/Channel.js").default} Channel
+ * @typedef {import("../client/Client.js").default<*, *>} Client
+ * @typedef {import("../account/AccountId.js").default} AccountId
+ * @typedef {import("../transaction/TransactionId.js").default} TransactionId
+ */
+
+/**
+ * Update a new Hedera™ crypto-currency file.
+ */
+export default class FileUpdateTransaction extends Transaction {
+    /**
+     * @param {object} props
+     * @param {FileId | string} [props.fileId]
+     * @param {Key[] | KeyList} [props.keys]
+     * @param {Timestamp | Date} [props.expirationTime]
+     * @param {Uint8Array | string} [props.contents]
+     * @param {?string} [props.fileMemo]
+     */
+    constructor(props = {}) {
+        super();
+
+        /**
+         * @private
+         * @type {?FileId}
+         */
+        this._fileId = null;
+
+        /**
+         * @private
+         * @type {?Key[]}
+         */
+        this._keys = null;
+
+        /**
+         * @private
+         * @type {?Timestamp}
+         */
+        this._expirationTime = null;
+
+        /**
+         * @private
+         * @type {?Uint8Array}
+         */
+        this._contents = null;
+
+        /**
+         * @private
+         * @type {?string}
+         */
+        this._fileMemo = null;
+
+        if (props.fileId != null) {
+            this.setFileId(props.fileId);
+        }
+
+        if (props.keys != null) {
+            this.setKeys(props.keys);
+        }
+
+        if (props.expirationTime != null) {
+            this.setExpirationTime(props.expirationTime);
+        }
+
+        if (props.contents != null) {
+            this.setContents(props.contents);
+        }
+
+        if (props.fileMemo && props.fileMemo != null) {
+            this.setFileMemo(props.fileMemo);
+        }
+    }
+
+    /**
+     * @internal
+     * @param {HieroProto.proto.ITransaction[]} transactions
+     * @param {HieroProto.proto.ISignedTransaction[]} signedTransactions
+     * @param {TransactionId[]} transactionIds
+     * @param {AccountId[]} nodeIds
+     * @param {HieroProto.proto.ITransactionBody[]} bodies
+     * @returns {FileUpdateTransaction}
+     */
+    static _fromProtobuf(
+        transactions,
+        signedTransactions,
+        transactionIds,
+        nodeIds,
+        bodies,
+    ) {
+        const body = bodies[0];
+        const update =
+            /** @type {HieroProto.proto.IFileUpdateTransactionBody} */ (
+                body.fileUpdate
+            );
+
+        return Transaction._fromProtobufTransactions(
+            new FileUpdateTransaction({
+                fileId:
+                    update.fileID != null
+                        ? FileId._fromProtobuf(update.fileID)
+                        : undefined,
+                keys:
+                    update.keys != null
+                        ? update.keys.keys != null
+                            ? update.keys.keys.map((key) =>
+                                  Key._fromProtobufKey(key),
+                              )
+                            : undefined
+                        : undefined,
+                expirationTime:
+                    update.expirationTime != null
+                        ? Timestamp._fromProtobuf(update.expirationTime)
+                        : undefined,
+                contents: update.contents != null ? update.contents : undefined,
+                fileMemo:
+                    update.memo != null
+                        ? Object.hasOwn(update.memo, "value")
+                            ? update.memo.value
+                            : undefined
+                        : undefined,
+            }),
+            transactions,
+            signedTransactions,
+            transactionIds,
+            nodeIds,
+            bodies,
+        );
+    }
+
+    /**
+     * @returns {?FileId}
+     */
+    get fileId() {
+        return this._fileId;
+    }
+
+    /**
+     * Set the keys which must sign any transactions modifying this file. Required.
+     *
+     * All keys must sign to modify the file's contents or keys. No key is required
+     * to sign for extending the expiration time (except the one for the operator account
+     * paying for the transaction). Only one key must sign to delete the file, however.
+     *
+     * To require more than one key to sign to delete a file, add them to a
+     * KeyList and pass that here.
+     *
+     * The network currently requires a file to have at least one key (or key list or threshold key)
+     * but this requirement may be lifted in the future.
+     *
+     * @param {FileId | string} fileId
+     * @returns {this}
+     */
+    setFileId(fileId) {
+        this._requireNotFrozen();
+        this._fileId =
+            typeof fileId === "string"
+                ? FileId.fromString(fileId)
+                : fileId.clone();
+
+        return this;
+    }
+
+    /**
+     * @returns {?Key[]}
+     */
+    get keys() {
+        return this._keys;
+    }
+
+    /**
+     * Set the keys which must sign any transactions modifying this file. Required.
+     *
+     * All keys must sign to modify the file's contents or keys. No key is required
+     * to sign for extending the expiration time (except the one for the operator account
+     * paying for the transaction). Only one key must sign to delete the file, however.
+     *
+     * To require more than one key to sign to delete a file, add them to a
+     * KeyList and pass that here.
+     *
+     * The network currently requires a file to have at least one key (or key list or threshold key)
+     * but this requirement may be lifted in the future.
+     *
+     * @param {Key[] | KeyList} keys
+     * @returns {this}
+     */
+    setKeys(keys) {
+        this._requireNotFrozen();
+        if (keys instanceof KeyList && keys.threshold != null) {
+            throw new Error("Cannot set threshold key as file key");
+        }
+
+        this._keys = keys instanceof KeyList ? keys.toArray() : keys;
+
+        return this;
+    }
+
+    /**
+     * @returns {?Timestamp}
+     */
+    get expirationTime() {
+        return this._expirationTime;
+    }
+
+    /**
+     * Set the instant at which this file will expire, after which its contents will no longer be
+     * available.
+     *
+     * Defaults to 1/4 of a Julian year from the instant FileUpdateTransaction
+     * was invoked.
+     *
+     * May be extended using FileUpdateTransaction#setExpirationTime(Timestamp).
+     *
+     * @param {Timestamp | Date} expirationTime
+     * @returns {this}
+     */
+    setExpirationTime(expirationTime) {
+        this._requireNotFrozen();
+        this._expirationTime =
+            expirationTime instanceof Timestamp
+                ? expirationTime
+                : Timestamp.fromDate(expirationTime);
+
+        return this;
+    }
+
+    /**
+     * @returns {?Uint8Array}
+     */
+    get contents() {
+        return this._contents;
+    }
+
+    /**
+     * Set the given byte array as the file's contents.
+     *
+     * This may be omitted to update an empty file.
+     *
+     * Note that total size for a given transaction is limited to 6KiB (as of March 2020) by the
+     * network; if you exceed this you may receive a HederaPreCheckStatusException
+     * with Status#TransactionOversize.
+     *
+     * In this case, you will need to break the data into chunks of less than ~6KiB and execute this
+     * transaction with the first chunk and then use FileAppendTransaction with
+     * FileAppendTransaction#setContents(Uint8Array) for the remaining chunks.
+     *
+     * @param {Uint8Array | string} contents
+     * @returns {this}
+     */
+    setContents(contents) {
+        this._requireNotFrozen();
+        this._contents =
+            contents instanceof Uint8Array ? contents : utf8.encode(contents);
+
+        return this;
+    }
+
+    /**
+     * @returns {?string}
+     */
+    get fileMemo() {
+        return this._fileMemo;
+    }
+
+    /**
+     * @param {string} memo
+     * @returns {this}
+     */
+    setFileMemo(memo) {
+        this._requireNotFrozen();
+        this._fileMemo = memo;
+
+        return this;
+    }
+
+    /**
+     * @returns {this}
+     */
+    clearFileMemo() {
+        this._requireNotFrozen();
+        this._fileMemo = null;
+
+        return this;
+    }
+
+    /**
+     * @param {Client} client
+     */
+    _validateChecksums(client) {
+        if (this._fileId != null) {
+            this._fileId.validateChecksum(client);
+        }
+    }
+
+    /**
+     * @override
+     * @internal
+     * @param {Channel} channel
+     * @param {HieroProto.proto.ITransaction} request
+     * @returns {Promise<HieroProto.proto.ITransactionResponse>}
+     */
+    _execute(channel, request) {
+        return channel.file.updateFile(request);
+    }
+
+    /**
+     * @override
+     * @protected
+     * @returns {NonNullable<HieroProto.proto.TransactionBody["data"]>}
+     */
+    _getTransactionDataCase() {
+        return "fileUpdate";
+    }
+
+    /**
+     * @override
+     * @protected
+     * @returns {HieroProto.proto.IFileUpdateTransactionBody}
+     */
+    _makeTransactionData() {
+        return {
+            fileID: this._fileId != null ? this._fileId._toProtobuf() : null,
+            keys:
+                this._keys != null
+                    ? {
+                          keys: this._keys.map((key) => key._toProtobufKey()),
+                      }
+                    : null,
+            expirationTime:
+                this._expirationTime != null
+                    ? this._expirationTime._toProtobuf()
+                    : null,
+            contents: this._contents,
+            memo:
+                this._fileMemo != null
+                    ? {
+                          value: this._fileMemo,
+                      }
+                    : null,
+        };
+    }
+
+    /**
+     * @returns {string}
+     */
+    _getLogId() {
+        const timestamp = /** @type {import("../Timestamp.js").default} */ (
+            this._transactionIds.current.validStart
+        );
+        return `FileUpdateTransaction:${timestamp.toString()}`;
+    }
+}
+
+// eslint-disable-next-line @typescript-eslint/unbound-method
+TRANSACTION_REGISTRY.set("fileUpdate", FileUpdateTransaction._fromProtobuf);

package/src/grpc/GrpcServiceError.js

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import GrpcStatus from "./GrpcStatus.js";
+
+/**
+ * Describes how the gRPC request failed.
+ *
+ * Exists in order for the Hiero JavaScript SDK to produce the same error type for gRPC errors regardless of
+ * operating in node or the browser.
+ *
+ * Definition taken from <https://grpc.github.io/grpc/node/grpc.html#~ServiceError>.
+ */
+export default class GrpcServiceError extends Error {
+    /**
+     * @param {GrpcStatus} status
+     * @param {string} [nodeAccountId]
+     */
+    constructor(status, nodeAccountId) {
+        super(
+            `gRPC service failed with: Status: ${status.toString()}, Code: ${status.valueOf()}`,
+        );
+
+        /**
+         * @readonly
+         */
+        this.status = status;
+
+        /**
+         * Optional: node account ID associated with the error
+         */
+        this.nodeAccountId = nodeAccountId;
+
+        this.name = "GrpcServiceError";
+
+        if (typeof Error.captureStackTrace !== "undefined") {
+            Error.captureStackTrace(this, GrpcServiceError);
+        }
+    }
+
+    /**
+     * @param {Error & { code?: number; details?: string }} obj
+     * @returns {Error}
+     */
+    static _fromResponse(obj) {
+        if (obj.code != null && obj.details != null) {
+            const status = GrpcStatus._fromValue(obj.code);
+            const err = new GrpcServiceError(status);
+            err.stack += `\nCaused by: ${
+                obj.stack ? obj.stack.toString() : ""
+            }`;
+            err.message += `: ${obj.details}`;
+            return err;
+        } else {
+            return /** @type {Error} */ (obj);
+        }
+    }
+
+    /**
+     * @returns {string}
+     */
+    toString() {
+        return `${this.name}: ${this.message}`;
+    }
+}

package/src/grpc/GrpcStatus.js

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: Apache-2.0
+
+export default class GrpcStatus {
+    /**
+     * @hideconstructor
+     * @internal
+     * @param {number} code
+     */
+    constructor(code) {
+        /** @readonly */
+        this._code = code;
+
+        Object.freeze(this);
+    }
+
+    /**
+     * @internal
+     * @param {number} code
+     * @returns {GrpcStatus}
+     */
+    static _fromValue(code) {
+        switch (code) {
+            case 0:
+                return GrpcStatus.Ok;
+            case 1:
+                return GrpcStatus.Cancelled;
+            case 2:
+                return GrpcStatus.Unknown;
+            case 3:
+                return GrpcStatus.InvalidArgument;
+            case 4:
+                return GrpcStatus.DeadlineExceeded;
+            case 5:
+                return GrpcStatus.NotFound;
+            case 6:
+                return GrpcStatus.AlreadyExists;
+            case 7:
+                return GrpcStatus.PermissionDenied;
+            case 8:
+                return GrpcStatus.ResourceExhausted;
+            case 9:
+                return GrpcStatus.FailedPrecondition;
+            case 10:
+                return GrpcStatus.Aborted;
+            case 11:
+                return GrpcStatus.OutOfRange;
+            case 12:
+                return GrpcStatus.Unimplemented;
+            case 13:
+                return GrpcStatus.Internal;
+            case 14:
+                return GrpcStatus.Unavailable;
+            case 15:
+                return GrpcStatus.DataLoss;
+            case 16:
+                return GrpcStatus.Unauthenticated;
+            case 17:
+                return GrpcStatus.Timeout;
+            case 18:
+                return GrpcStatus.GrpcWeb;
+            default:
+                throw new Error(
+                    "(BUG) non-exhaustive GrpcStatus switch statement",
+                );
+        }
+    }
+
+    /**
+     * @returns {string}
+     */
+    toString() {
+        switch (this) {
+            case GrpcStatus.Ok:
+                return "OK";
+            case GrpcStatus.Cancelled:
+                return "CANCELLED";
+            case GrpcStatus.Unknown:
+                return "UNKNOWN";
+            case GrpcStatus.InvalidArgument:
+                return "INVALID_ARGUMENT";
+            case GrpcStatus.DeadlineExceeded:
+                return "DEADLINE_EXCEEDED";
+            case GrpcStatus.NotFound:
+                return "NOT_FOUND";
+            case GrpcStatus.AlreadyExists:
+                return "ALREADY_EXISTS";
+            case GrpcStatus.PermissionDenied:
+                return "PERMISSION_DENIED";
+            case GrpcStatus.Unauthenticated:
+                return "UNAUTHENTICATED";
+            case GrpcStatus.ResourceExhausted:
+                return "RESOURCE_EXHAUSTED";
+            case GrpcStatus.FailedPrecondition:
+                return "FAILED_PRECONDITION";
+            case GrpcStatus.Aborted:
+                return "ABORTED";
+            case GrpcStatus.OutOfRange:
+                return "OUT_OF_RANGE";
+            case GrpcStatus.Unimplemented:
+                return "UNIMPLEMENTED";
+            case GrpcStatus.Internal:
+                return "INTERNAL";
+            case GrpcStatus.Unavailable:
+                return "UNAVAILABLE";
+            case GrpcStatus.DataLoss:
+                return "DATA_LOSS";
+            case GrpcStatus.Timeout:
+                return "TIMEOUT";
+            case GrpcStatus.GrpcWeb:
+                return "GRPC_WEB";
+            default:
+                return `UNKNOWN (${this._code})`;
+        }
+    }
+
+    /**
+     * @returns {number}
+     */
+    valueOf() {
+        return this._code;
+    }
+}
+
+GrpcStatus.Ok = new GrpcStatus(0);
+GrpcStatus.Cancelled = new GrpcStatus(1);
+GrpcStatus.Unknown = new GrpcStatus(2);
+GrpcStatus.InvalidArgument = new GrpcStatus(3);
+GrpcStatus.DeadlineExceeded = new GrpcStatus(4);
+GrpcStatus.NotFound = new GrpcStatus(5);
+GrpcStatus.AlreadyExists = new GrpcStatus(6);
+GrpcStatus.PermissionDenied = new GrpcStatus(7);
+GrpcStatus.ResourceExhausted = new GrpcStatus(8);
+GrpcStatus.FailedPrecondition = new GrpcStatus(9);
+GrpcStatus.Aborted = new GrpcStatus(10);
+GrpcStatus.OutOfRange = new GrpcStatus(11);
+GrpcStatus.Unimplemented = new GrpcStatus(12);
+GrpcStatus.Internal = new GrpcStatus(13);
+GrpcStatus.Unavailable = new GrpcStatus(14);
+GrpcStatus.DataLoss = new GrpcStatus(15);
+GrpcStatus.Unauthenticated = new GrpcStatus(16);
+GrpcStatus.Timeout = new GrpcStatus(17);
+GrpcStatus.GrpcWeb = new GrpcStatus(18);

package/src/http/HttpError.js

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import HttpStatus from "./HttpStatus.js";
+
+/**
+ * Describes how the http request failed.
+ */
+export default class HttpError extends Error {
+    /**
+     * @param {HttpStatus} status
+     */
+    constructor(status) {
+        super(`failed with error code: ${status.toString()}`);
+
+        /**
+         * @readonly
+         */
+        this.status = status;
+
+        this.name = "HttpError";
+
+        if (typeof Error.captureStackTrace !== "undefined") {
+            Error.captureStackTrace(this, HttpError);
+        }
+    }
+}

package/src/http/HttpStatus.js

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+
+export default class HttpStatus {
+    /**
+     * @hideconstructor
+     * @internal
+     * @param {number} code
+     */
+    constructor(code) {
+        /** @readonly */
+        this._code = code;
+
+        Object.freeze(this);
+    }
+
+    /**
+     * @internal
+     * @param {number} code
+     * @returns {HttpStatus}
+     */
+    static _fromValue(code) {
+        return new HttpStatus(code);
+    }
+
+    /**
+     * @returns {string}
+     */
+    toString() {
+        return this._code.toString();
+    }
+
+    /**
+     * @returns {number}
+     */
+    valueOf() {
+        return this._code;
+    }
+}

package/src/index.js

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * The entry point for NodeJS applications
+ */
+
+export * from "./exports.js";
+
+export { default as LocalProvider } from "./LocalProvider.js";
+export { default as Client } from "./client/NodeClient.js";
+export { default as AddressBookQuery } from "./network/AddressBookQuery.js";