@hiero-ledger/sdk 2.80.0 → 2.81.0-beta.1

package/src/hooks/FungibleHookCall.js

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import HookCall from "./HookCall.js";
+import EvmHookCall from "./EvmHookCall.js";
+import FungibleHookType from "./FungibleHookType.js";
+
+/**
+ * @namespace proto
+ * @typedef {import("@hiero-ledger/proto").proto.IHookCall} HieroProto.proto.IHookCall
+ */
+
+/**
+ * @typedef {typeof FungibleHookType[keyof typeof FungibleHookType]} FungibleHookTypeValue
+ */
+
+/**
+ * A typed hook call for fungible (HBAR and FT) transfers.
+ */
+class FungibleHookCall extends HookCall {
+    /**
+     * @param {object} props
+     * @param {Long} [props.hookId]
+     * @param {import("../hooks/EvmHookCall.js").default} [props.evmHookCall]
+     * @param {FungibleHookTypeValue} props.type - One of FungibleHookType.PRE_TX_ALLOWANCE_HOOK or FungibleHookType.PRE_POST_TX_ALLOWANCE_HOOK
+     */
+    constructor(props) {
+        super(props);
+
+        if (props.type == null) {
+            throw new Error("type cannot be null");
+        }
+
+        /**
+         * The type of fungible hook
+         * @private
+         * @type {FungibleHookTypeValue}
+         */
+        this._type = props.type;
+    }
+
+    /**
+     * @returns {FungibleHookTypeValue}
+     */
+    get type() {
+        return this._type;
+    }
+
+    /**
+     * @internal
+     * @param {HieroProto.proto.IHookCall} hookCall
+     * @param {FungibleHookTypeValue} type
+     * @returns {FungibleHookCall}
+     */
+    static _fromProtobufWithType(hookCall, type) {
+        return new FungibleHookCall({
+            hookId: hookCall.hookId != null ? hookCall.hookId : undefined,
+            evmHookCall: hookCall.evmHookCall
+                ? EvmHookCall._fromProtobuf(hookCall.evmHookCall)
+                : undefined,
+            type,
+        });
+    }
+}
+
+export default FungibleHookCall;

package/src/hooks/FungibleHookType.js

@@ -0,0 +1,6 @@
+const FungibleHookType = Object.freeze({
+    PRE_TX_ALLOWANCE_HOOK: 0,
+    PRE_POST_TX_ALLOWANCE_HOOK: 1,
+});
+
+export default FungibleHookType;

package/src/hooks/HookCall.js

@@ -0,0 +1,97 @@
+/**
+ * @namespace proto
+ * @typedef {import("@hiero-ledger/proto").proto.IHookCall} HieroProto.proto.IHookCall
+ */
+
+import EvmHookCall from "../hooks/EvmHookCall.js";
+
+/**
+ *
+ * Specifies a call to a hook from within a transaction.
+ * <p>
+ * Often the hook's entity is implied by the nature of the call site. For example, when using an account allowance hook
+ * inside a crypto transfer, the hook's entity is necessarily the account whose authorization is required.
+ * <p>
+ * For future extension points where the hook owner is not forced by the context, we include the option to fully
+ * specify the hook id for the call.
+ */
+class HookCall {
+    /**
+     *
+     * @param {object} props
+     * @param {Long} [props.hookId]
+     * @param {import("../hooks/EvmHookCall.js").default} [props.evmHookCall]
+     */
+    constructor(props = {}) {
+        if (props.hookId !== undefined) {
+            this.setHookId(props.hookId);
+        }
+
+        if (props.evmHookCall !== undefined) {
+            this.setCall(props.evmHookCall);
+        }
+    }
+
+    /**
+     *
+     * @param {Long} hookId
+     * @returns {this}
+     */
+    setHookId(hookId) {
+        this._hookId = hookId;
+        return this;
+    }
+
+    /**
+     *
+     * @param {import("../hooks/EvmHookCall.js").default} evmHookCall
+     * @returns {this}
+     */
+    setCall(evmHookCall) {
+        this._evmHookCall = evmHookCall;
+        return this;
+    }
+
+    /**
+     *
+     * @returns {Long | undefined}
+     */
+    get hookId() {
+        return this._hookId;
+    }
+
+    /**
+     *
+     * @returns {import("../hooks/EvmHookCall.js").default | undefined}
+     */
+    get evmHookCall() {
+        return this._evmHookCall;
+    }
+
+    /**
+     * @internal
+     * @param {HieroProto.proto.IHookCall} hookCall
+     * @returns {HookCall}
+     */
+    static _fromProtobuf(hookCall) {
+        return new HookCall({
+            hookId: hookCall.hookId ?? undefined,
+            evmHookCall: hookCall.evmHookCall
+                ? EvmHookCall._fromProtobuf(hookCall.evmHookCall)
+                : undefined,
+        });
+    }
+
+    /**
+     *
+     * @returns {import("@hiero-ledger/proto").proto.HookCall}}
+     */
+    _toProtobuf() {
+        return {
+            hookId: this._hookId,
+            evmHookCall: this._evmHookCall?._toProtobuf(),
+        };
+    }
+}
+
+export default HookCall;

package/src/hooks/HookCreationDetails.js

@@ -0,0 +1,155 @@
+import Long from "long";
+import HookExtensionPoint from "./HookExtensionPoint.js";
+
+/**
+ * The details of a hook's creation.
+ */
+class HookCreationDetails {
+    /**
+     *
+     * @param {object} props
+     * @param {HookExtensionPoint} [props.extensionPoint]
+     * @param {Long | number} [props.hookId]
+     * @param {import("./EvmHook.js").default} [props.evmHook]
+     * @param {import("../Key.js").default} [props.adminKey]
+     */
+    constructor(props = {}) {
+        /**
+         * @private
+         * @type {HookExtensionPoint | null}
+         */
+        this._extensionPoint = null;
+
+        /**
+         * @private
+         * @type {Long | null}
+         */
+        this._hookId = null;
+
+        /**
+         * @private
+         * @type {import("./EvmHook.js").default | null}
+         */
+        this._evmHook = null;
+
+        /**
+         * @private
+         * @type {import("../Key.js").default | null}
+         */
+        this._adminKey = null;
+
+        if (props.extensionPoint != null) {
+            this.setExtensionPoint(props.extensionPoint);
+        }
+
+        if (props.hookId != null) {
+            this.setHookId(props.hookId);
+        }
+
+        if (props.evmHook != null) {
+            this.setEvmHook(props.evmHook);
+        }
+
+        if (props.adminKey != null) {
+            this.setAdminKey(props.adminKey);
+        }
+    }
+
+    /**
+     *
+     * @param {HookExtensionPoint} extensionPoint
+     * @returns {this}
+     */
+    setExtensionPoint(extensionPoint) {
+        this._extensionPoint = extensionPoint;
+        return this;
+    }
+
+    /**
+     *
+     * @param {Long | number} hookId
+     * @returns {this}
+     */
+    setHookId(hookId) {
+        this._hookId =
+            hookId instanceof Long ? hookId : Long.fromNumber(hookId);
+        return this;
+    }
+
+    /**
+     *
+     * @param {import("./EvmHook.js").default} evmHook
+     * @returns {this}
+     */
+    setEvmHook(evmHook) {
+        this._evmHook = evmHook;
+        return this;
+    }
+
+    /**
+     *
+     * @param {import("../Key.js").default} adminKey
+     * @returns {this}
+     */
+    setAdminKey(adminKey) {
+        this._adminKey = adminKey;
+        return this;
+    }
+
+    /**
+     *
+     * @returns {HookExtensionPoint | null}
+     */
+    get extensionPoint() {
+        return this._extensionPoint;
+    }
+
+    /**
+     *
+     * @returns {Long | null}
+     */
+    get hookId() {
+        return this._hookId;
+    }
+
+    /**
+     *
+     * @returns {import("./EvmHook.js").default | null}
+     */
+    get evmHook() {
+        return this._evmHook;
+    }
+
+    /**
+     *
+     * @returns {import("../Key.js").default | null}
+     */
+    get adminKey() {
+        return this._adminKey;
+    }
+
+    /**
+     *
+     * @returns {import("@hiero-ledger/proto").com.hedera.hapi.node.hooks.IHookCreationDetails}
+     */
+    _toProtobuf() {
+        if (this._extensionPoint == null) {
+            throw new Error(
+                "extensionPoint is required for HookCreationDetails",
+            );
+        }
+
+        return {
+            extensionPoint:
+                /** @type {import("@hiero-ledger/proto").com.hedera.hapi.node.hooks.HookExtensionPoint} */ (
+                    this._extensionPoint
+                ),
+            hookId: this._hookId,
+            evmHook: this._evmHook != null ? this._evmHook._toProtobuf() : null,
+            adminKey:
+                this._adminKey != null ? this._adminKey._toProtobufKey() : null,
+        };
+    }
+}
+
+export default HookCreationDetails;

package/src/hooks/HookEntityId.js

@@ -0,0 +1,67 @@
+import AccountId from "../account/AccountId.js";
+
+/**
+ * The id of an entity using a hook.
+ */
+class HookEntityId {
+    /**
+     *
+     * @param {object} props
+     * @param {AccountId} [props.accountId]
+     */
+    constructor(props = {}) {
+        /**
+         * @private
+         * @type {?AccountId}
+         */
+        this._accountId = null;
+
+        if (props.accountId != null) {
+            this.setAccountId(props.accountId);
+        }
+    }
+
+    /**
+     * @param {AccountId} accountId
+     * @returns {this}
+     */
+    setAccountId(accountId) {
+        this._accountId = accountId;
+        return this;
+    }
+
+    /**
+     *
+     * @returns {AccountId | null}
+     */
+    get accountId() {
+        return this._accountId;
+    }
+
+    /**
+     *
+     * @returns {import("@hiero-ledger/proto").proto.IHookEntityId}
+     */
+    _toProtobuf() {
+        return {
+            accountId:
+                this._accountId != null ? this._accountId._toProtobuf() : null,
+        };
+    }
+
+    /**
+     *
+     * @param {import("@hiero-ledger/proto").proto.IHookEntityId} hookEntityId
+     * @returns {HookEntityId}
+     */
+    static _fromProtobuf(hookEntityId) {
+        return new HookEntityId({
+            accountId:
+                hookEntityId.accountId != null
+                    ? AccountId._fromProtobuf(hookEntityId.accountId)
+                    : undefined,
+        });
+    }
+}
+
+export default HookEntityId;

package/src/hooks/HookExtensionPoint.js

@@ -0,0 +1,25 @@
+/**
+ * @namespace proto
+ * @typedef {import("@hiero-ledger/proto").com.hedera.hapi.node.hooks.HookExtensionPoint} HieroHookExtensionPoint
+ */
+
+/**
+ * The Hiero extension points that accept a hook.
+ */
+export class HookExtensionPoint {
+    /**
+     * @hideconstructor
+     * @internal
+     */
+    constructor() {}
+
+    /**
+     * Used to customize an account's allowances during a CryptoTransfer transaction.
+     * @returns {HookExtensionPoint}
+     */
+    static get ACCOUNT_ALLOWANCE_HOOK() {
+        return 0;
+    }
+}
+
+export default HookExtensionPoint;

package/src/hooks/HookId.js

@@ -0,0 +1,102 @@
+import HookEntityId from "./HookEntityId.js";
+
+/**
+ * Once a hook is created, its full id.
+ * <p>
+ * A composite of its creating entity's id and an arbitrary 64-bit hook id
+ * (which need not be sequential).
+ */
+class HookId {
+    /**
+     *
+     * @param {object} props
+     * @param {HookEntityId} [props.entityId]
+     * @param {Long} [props.hookId]
+     */
+    constructor(props = {}) {
+        /**
+         * @private
+         * @type {?HookEntityId}
+         */
+        this._entityId = null;
+
+        /**
+         * @private
+         * @type {?Long}
+         */
+        this._hookId = null;
+
+        if (props.entityId != null) {
+            this.setEntityId(props.entityId);
+        }
+
+        if (props.hookId != null) {
+            this.setHookId(props.hookId);
+        }
+    }
+
+    /**
+     *
+     * @param {HookEntityId} entityId
+     * @returns {this}
+     */
+    setEntityId(entityId) {
+        this._entityId = entityId;
+        return this;
+    }
+
+    /**
+     *
+     * @param {Long} hookId
+     * @returns {this}
+     */
+    setHookId(hookId) {
+        this._hookId = hookId;
+        return this;
+    }
+
+    /**
+     *
+     * @returns {HookEntityId | null}
+     */
+    get entityId() {
+        return this._entityId;
+    }
+
+    /**
+     *
+     * @returns {Long | null}
+     */
+    get hookId() {
+        return this._hookId;
+    }
+
+    /**
+     *
+     * @param {import("@hiero-ledger/proto").proto.IHookId} hookId
+     * @returns {HookId}
+     */
+    static _fromProtobuf(hookId) {
+        return new HookId({
+            entityId:
+                hookId.entityId != null
+                    ? HookEntityId._fromProtobuf(hookId.entityId)
+                    : undefined,
+            hookId: hookId.hookId != null ? hookId.hookId : undefined,
+        });
+    }
+
+    /**
+     *
+     * @returns {import("@hiero-ledger/proto").proto.IHookId}
+     */
+    _toProtobuf() {
+        return {
+            entityId:
+                this._entityId != null ? this._entityId._toProtobuf() : null,
+            hookId: this._hookId,
+        };
+    }
+}
+
+export default HookId;

package/src/hooks/HookStoreTransaction.js

@@ -0,0 +1,185 @@
+import HookId from "../hooks/HookId.js";
+import { EvmHookStorageUpdate } from "../hooks/EvmHookStorageUpdate.js";
+import Transaction, {
+    TRANSACTION_REGISTRY,
+} from "../transaction/Transaction.js";
+
+/**
+ * @typedef {import("../channel/Channel.js").default} Channel
+ * @typedef {import("../client/Client.js").default<*, *>} Client
+ * @typedef {import("../Timestamp.js").default} Timestamp
+ * @typedef {import("../transaction/TransactionId.js").default} TransactionId
+ */
+
+class HookStoreTransaction extends Transaction {
+    /**
+     *
+     * @param {object} props
+     * @param {import("../hooks/HookId.js").default} [props.hookId]
+     * @param {import("../hooks/EvmHookStorageUpdate.js").EvmHookStorageUpdate[]} [props.storageUpdates]
+     */
+    constructor(props = {}) {
+        super();
+
+        /**
+         * @private
+         * @type {HookId | null}
+         */
+        this._hookId = null;
+
+        /**
+         * @private
+         * @type {EvmHookStorageUpdate[]}
+         */
+        this._storageUpdates = [];
+
+        if (props.hookId != null) {
+            this.setHookId(props.hookId);
+        }
+
+        if (props.storageUpdates != null) {
+            this.setStorageUpdates(props.storageUpdates);
+        }
+    }
+
+    /**
+     * @returns {HookId | null}
+     */
+    get hookId() {
+        return this._hookId;
+    }
+
+    /**
+     *
+     * @param {HookId} hookId
+     * @returns {this}
+     */
+    setHookId(hookId) {
+        this._requireNotFrozen();
+        this._hookId = hookId;
+        return this;
+    }
+
+    /**
+     * @returns {EvmHookStorageUpdate[] | []}
+     */
+    get storageUpdates() {
+        return this._storageUpdates;
+    }
+
+    /**
+     *
+     * @param {EvmHookStorageUpdate[]} storageUpdates
+     * @returns {this}
+     */
+    setStorageUpdates(storageUpdates) {
+        this._requireNotFrozen();
+        this._storageUpdates = storageUpdates;
+        return this;
+    }
+
+    /**
+     * @param {EvmHookStorageUpdate} storageUpdate
+     * @returns {this}
+     */
+    addStorageUpdate(storageUpdate) {
+        this._requireNotFrozen();
+        this._storageUpdates.push(storageUpdate);
+        return this;
+    }
+
+    /**
+     * @override
+     * @protected
+     * @returns {import("@hiero-ledger/proto").com.hedera.hapi.node.hooks.IHookStoreTransactionBody} HieroProto.proto.IHookStoreTransactionBody
+     */
+    _makeTransactionData() {
+        return {
+            hookId: this.hookId?._toProtobuf(),
+            storageUpdates: this.storageUpdates?.map((update) =>
+                update._toProtobuf(),
+            ),
+        };
+    }
+
+    /**
+     * @override
+     * @internal
+     * @param {Channel} channel
+     * @param {import("@hiero-ledger/proto").proto.ITransaction} request
+     * @returns {Promise<import("@hiero-ledger/proto").proto.ITransactionResponse>}
+     */
+    _execute(channel, request) {
+        return channel.smartContract.hookStore(request);
+    }
+
+    /**
+     * @override
+     * @protected
+     * @returns {NonNullable<import("@hiero-ledger/proto").proto.TransactionBody["data"]>}
+     */
+    _getTransactionDataCase() {
+        return "hookStore";
+    }
+
+    /**
+     * @returns {string}
+     */
+    _getLogId() {
+        const timestamp = /** @type {import("../Timestamp.js").default} */ (
+            this._transactionIds.current.validStart
+        );
+        return `HookStoreTransaction:${timestamp.toString()}`;
+    }
+
+    /**
+     * @internal
+     * @param {import("@hiero-ledger/proto").proto.ITransaction[]} transactions
+     * @param {import("@hiero-ledger/proto").proto.ISignedTransaction[]} signedTransactions
+     * @param {TransactionId[]} transactionIds
+     * @param {import("../account/AccountId.js").default[]} nodeIds
+     * @param {import("@hiero-ledger/proto").proto.ITransactionBody[]} bodies
+     * @returns {HookStoreTransaction}
+     */
+    static _fromProtobuf(
+        transactions,
+        signedTransactions,
+        transactionIds,
+        nodeIds,
+        bodies,
+    ) {
+        const body = bodies[0];
+        const create =
+            /** @type {import("@hiero-ledger/proto").com.hedera.hapi.node.hooks.IHookStoreTransactionBody} */ (
+                body.hookStore
+            );
+
+        return Transaction._fromProtobufTransactions(
+            new HookStoreTransaction({
+                hookId:
+                    create.hookId != null
+                        ? HookId._fromProtobuf(create.hookId)
+                        : undefined,
+                storageUpdates:
+                    create.storageUpdates != null
+                        ? create.storageUpdates.map((update) =>
+                              EvmHookStorageUpdate._fromProtobuf(update),
+                          )
+                        : undefined,
+            }),
+            transactions,
+            signedTransactions,
+            transactionIds,
+            nodeIds,
+            bodies,
+        );
+    }
+}
+
+TRANSACTION_REGISTRY.set(
+    "hookStore",
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    HookStoreTransaction._fromProtobuf,
+);
+
+export default HookStoreTransaction;