feat(hooks): add account hook create/delete support across base, Spring, MicroProfile, and docs

amkr6207 · amkr6207 · commit 5ece92b36916 · 2026-05-03T12:06:00.000+05:30
Signed-off-by: Aman &lt;amkr6207@gmail.com&gt;
diff --git a/README.md b/README.md
@@ -77,6 +77,30 @@ public class HieroAccountService {
 All APIs of the client are synchronous and return the result of the operation.
 For asynchronous operations, you can easily wrap calls by use the [`@Async` annotation of spring](https://spring.io/guides/gs/async-method).
 
+### Hook lifecycle management
+
+`AccountClient` exposes hook lifecycle management via `updateAccountHooks(...)`.
+This operation delegates to Hedera SDK account update hook fields (`addHookToCreate`, `addHookToDelete`).
+
+```java
+import com.hedera.hashgraph.sdk.ContractId;
+import com.hedera.hashgraph.sdk.EvmHook;
+import java.util.List;
+import org.hiero.base.AccountClient;
+import org.hiero.base.data.Account;
+import org.hiero.base.data.HookDetails;
+import org.hiero.base.data.HookExtensionPoint;
+
+HookDetails hookToCreate =
+    new HookDetails(
+        HookExtensionPoint.ACCOUNT_ALLOWANCE_HOOK,
+        1001L,
+        new EvmHook(ContractId.fromString("0.0.5001")),
+        null);
+
+accountClient.updateAccountHooks(account, List.of(hookToCreate), List.of(77L));
+```
+
 ### Hiero Spring Sample
 
 A sample application that uses the Hiero Spring module can be found in the `hiero-enterprise-spring-sample` module.
@@ -131,6 +155,7 @@ The following services are available in spring and microprofile:
 
 - `org.hiero.base.HieroContext`: component that provides the information about the Hiero network and the operator account
 - `org.hiero.base.AccountClient`: to interact with accounts
+- `org.hiero.base.HookClient`: to interact with hook storage updates
 - `org.hiero.base.FileClient`: to interact with files
 - `org.hiero.base.FungibleTokenClient`: to interact with fungible tokens
 - `org.hiero.base.NftClient`: to interact with NFTs
diff --git a/docs/managed-services.md b/docs/managed-services.md
@@ -1,5 +1,31 @@
 # Base / Managed Services
 
-<!-- TODO: Add documentation for hiero-enterprise-base: HieroContext, AccountClient, FileClient, FungibleTokenClient, NftClient, SmartContractClient, ContractVerificationClient, mirror node repositories, ProtocolLayerClient, MirrorNodeClient. -->
+`hiero-enterprise-base` provides the core managed clients used by Spring and MicroProfile modules.
 
-Placeholder: technical documentation for the base module and managed services will be added here.
+## Hook lifecycle support
+
+Hook lifecycle operations are exposed through `AccountClient.updateAccountHooks(...)`.
+This API supports both:
+
+- creating hooks (`hooksToCreate`)
+- deleting hooks (`hooksToDelete`)
+
+Core types:
+
+- `org.hiero.base.data.HookDetails`
+- `org.hiero.base.data.HookExtensionPoint`
+- `org.hiero.base.protocol.data.AccountHookUpdateRequest`
+- `org.hiero.base.protocol.data.AccountHookUpdateResult`
+
+Example:
+
+```java
+HookDetails hookToCreate =
+    new HookDetails(
+        HookExtensionPoint.ACCOUNT_ALLOWANCE_HOOK,
+        1001L,
+        new EvmHook(ContractId.fromString("0.0.5001")),
+        null);
+
+accountClient.updateAccountHooks(account, List.of(hookToCreate), List.of(77L));
+```
diff --git a/docs/microprofile.md b/docs/microprofile.md
@@ -1,5 +1,20 @@
 # MicroProfile Integration
 
-<!-- TODO: Add MicroProfile/Quarkus setup, configuration, available clients and usage. -->
+MicroProfile integration exposes `AccountClient` via CDI.
 
-Placeholder: technical documentation for the MicroProfile integration (hiero-enterprise-microprofile) will be added here.
+## Hook lifecycle usage
+
+Use `AccountClient.updateAccountHooks(...)` to create and/or delete hooks in one account update transaction.
+
+```java
+@Inject AccountClient accountClient;
+
+HookDetails hookToCreate =
+    new HookDetails(
+        HookExtensionPoint.ACCOUNT_ALLOWANCE_HOOK,
+        1001L,
+        new EvmHook(ContractId.fromString("0.0.5001")),
+        null);
+
+accountClient.updateAccountHooks(account, List.of(hookToCreate), List.of(77L));
+```
diff --git a/docs/spring-boot.md b/docs/spring-boot.md
@@ -1,5 +1,20 @@
 # Spring Boot Integration
 
-<!-- TODO: Add Spring Boot setup, @EnableHiero, configuration properties, available clients and usage. -->
+Spring integration exposes `AccountClient` as a managed bean.
 
-Placeholder: technical documentation for the Spring Boot integration (hiero-enterprise-spring) will be added here.
+## Hook lifecycle usage
+
+Use `AccountClient.updateAccountHooks(...)` to create and/or delete hooks in one account update transaction.
+
+```java
+@Autowired AccountClient accountClient;
+
+HookDetails hookToCreate =
+    new HookDetails(
+        HookExtensionPoint.ACCOUNT_ALLOWANCE_HOOK,
+        1001L,
+        new EvmHook(ContractId.fromString("0.0.5001")),
+        null);
+
+accountClient.updateAccountHooks(account, List.of(hookToCreate), List.of(77L));
+```
diff --git a/hiero-enterprise-base/src/main/java/org/hiero/base/AccountClient.java b/hiero-enterprise-base/src/main/java/org/hiero/base/AccountClient.java
@@ -3,8 +3,10 @@
 import com.hedera.hashgraph.sdk.AccountId;
 import com.hedera.hashgraph.sdk.Hbar;
 import com.hedera.hashgraph.sdk.PrivateKey;
+import java.util.List;
 import java.util.Objects;
 import org.hiero.base.data.Account;
+import org.hiero.base.data.HookDetails;
 import org.jspecify.annotations.NonNull;
 
 /**
@@ -92,6 +94,20 @@ default Account createAccount(long initialBalanceInHbar) throws HieroException {
    */
   void updateAccountMemo(@NonNull Account account, @NonNull String memo) throws HieroException;
 
+  /**
+   * Updates account hooks by creating and/or deleting hooks in one update transaction.
+   *
+   * @param account the account to update
+   * @param hooksToCreate hook definitions to create
+   * @param hooksToDelete hook ids to delete
+   * @throws HieroException if the account could not be updated
+   */
+  void updateAccountHooks(
+      @NonNull Account account,
+      @NonNull List<HookDetails> hooksToCreate,
+      @NonNull List<Long> hooksToDelete)
+      throws HieroException;
+
   /**
    * Updates both key and memo of the given account.
    *
diff --git a/hiero-enterprise-base/src/main/java/org/hiero/base/data/HookDetails.java b/hiero-enterprise-base/src/main/java/org/hiero/base/data/HookDetails.java
@@ -0,0 +1,32 @@
+package org.hiero.base.data;
+
+import com.hedera.hashgraph.sdk.EvmHook;
+import com.hedera.hashgraph.sdk.HookCreationDetails;
+import com.hedera.hashgraph.sdk.Key;
+import java.util.Objects;
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
+
+/** Data model describing a hook to be created on an account update transaction. */
+public record HookDetails(
+    @NonNull HookExtensionPoint extensionPoint,
+    long hookId,
+    @NonNull EvmHook hook,
+    @Nullable Key adminKey) {
+
+  public HookDetails {
+    Objects.requireNonNull(extensionPoint, "extensionPoint is required");
+    Objects.requireNonNull(hook, "hook is required");
+    if (hookId < 0) {
+      throw new IllegalArgumentException("hookId must be non-negative");
+    }
+  }
+
+  @NonNull
+  public HookCreationDetails toHederaSdkType() {
+    if (adminKey != null) {
+      return new HookCreationDetails(extensionPoint.toHederaSdkType(), hookId, hook, adminKey);
+    }
+    return new HookCreationDetails(extensionPoint.toHederaSdkType(), hookId, hook);
+  }
+}
diff --git a/hiero-enterprise-base/src/main/java/org/hiero/base/data/HookExtensionPoint.java b/hiero-enterprise-base/src/main/java/org/hiero/base/data/HookExtensionPoint.java
@@ -0,0 +1,10 @@
+package org.hiero.base.data;
+
+/** Hook extension points supported by account hook creation. */
+public enum HookExtensionPoint {
+  ACCOUNT_ALLOWANCE_HOOK;
+
+  public com.hedera.hashgraph.sdk.HookExtensionPoint toHederaSdkType() {
+    return com.hedera.hashgraph.sdk.HookExtensionPoint.ACCOUNT_ALLOWANCE_HOOK;
+  }
+}
diff --git a/hiero-enterprise-base/src/main/java/org/hiero/base/implementation/AccountClientImpl.java b/hiero-enterprise-base/src/main/java/org/hiero/base/implementation/AccountClientImpl.java
@@ -3,16 +3,19 @@
 import com.hedera.hashgraph.sdk.AccountId;
 import com.hedera.hashgraph.sdk.Hbar;
 import com.hedera.hashgraph.sdk.PrivateKey;
+import java.util.List;
 import java.util.Objects;
 import org.hiero.base.AccountClient;
 import org.hiero.base.HieroException;
 import org.hiero.base.data.Account;
+import org.hiero.base.data.HookDetails;
 import org.hiero.base.protocol.ProtocolLayerClient;
 import org.hiero.base.protocol.data.AccountBalanceRequest;
 import org.hiero.base.protocol.data.AccountBalanceResponse;
 import org.hiero.base.protocol.data.AccountCreateRequest;
 import org.hiero.base.protocol.data.AccountCreateResult;
 import org.hiero.base.protocol.data.AccountDeleteRequest;
+import org.hiero.base.protocol.data.AccountHookUpdateRequest;
 import org.hiero.base.protocol.data.AccountUpdateRequest;
 import org.jspecify.annotations.NonNull;
 
@@ -76,6 +79,20 @@ public void updateAccountMemo(@NonNull Account account, @NonNull String memo)
     client.executeAccountUpdateTransaction(request);
   }
 
+  @Override
+  public void updateAccountHooks(
+      @NonNull final Account account,
+      @NonNull final List<HookDetails> hooksToCreate,
+      @NonNull final List<Long> hooksToDelete)
+      throws HieroException {
+    Objects.requireNonNull(account, "account must not be null");
+    Objects.requireNonNull(hooksToCreate, "hooksToCreate must not be null");
+    Objects.requireNonNull(hooksToDelete, "hooksToDelete must not be null");
+    final AccountHookUpdateRequest request =
+        AccountHookUpdateRequest.of(account, hooksToCreate, hooksToDelete);
+    client.executeAccountHookUpdateTransaction(request);
+  }
+
   @Override
   public @NonNull Account updateAccount(
       @NonNull Account account, @NonNull PrivateKey updatedPrivateKey, @NonNull String memo)
diff --git a/hiero-enterprise-base/src/main/java/org/hiero/base/implementation/ProtocolLayerClientImpl.java b/hiero-enterprise-base/src/main/java/org/hiero/base/implementation/ProtocolLayerClientImpl.java
@@ -58,6 +58,8 @@
 import org.hiero.base.protocol.data.AccountCreateResult;
 import org.hiero.base.protocol.data.AccountDeleteRequest;
 import org.hiero.base.protocol.data.AccountDeleteResult;
+import org.hiero.base.protocol.data.AccountHookUpdateRequest;
+import org.hiero.base.protocol.data.AccountHookUpdateResult;
 import org.hiero.base.protocol.data.AccountUpdateRequest;
 import org.hiero.base.protocol.data.AccountUpdateResult;
 import org.hiero.base.protocol.data.ContractCallRequest;
@@ -407,6 +409,30 @@ public AccountUpdateResult executeAccountUpdateTransaction(
     return new AccountUpdateResult(receipt.transactionId, receipt.status);
   }
 
+  @Override
+  @NonNull
+  public AccountHookUpdateResult executeAccountHookUpdateTransaction(
+      @NonNull final AccountHookUpdateRequest request) throws HieroException {
+    Objects.requireNonNull(request, "request must not be null");
+    final AccountUpdateTransaction transaction =
+        new AccountUpdateTransaction()
+            .setMaxTransactionFee(request.maxTransactionFee())
+            .setTransactionValidDuration(request.transactionValidDuration())
+            .setAccountId(request.toUpdate().accountId());
+
+    for (final var hookToCreate : request.hooksToCreate()) {
+      transaction.addHookToCreate(hookToCreate.toHederaSdkType());
+    }
+    for (final Long hookIdToDelete : request.hooksToDelete()) {
+      transaction.addHookToDelete(hookIdToDelete);
+    }
+
+    sign(transaction, request.toUpdate().privateKey());
+    final TransactionReceipt receipt =
+        executeTransactionAndWaitOnReceipt(transaction, TransactionType.ACCOUNT_UPDATE);
+    return new AccountHookUpdateResult(receipt.transactionId, receipt.status);
+  }
+
   public TopicCreateResult executeTopicCreateTransaction(@NonNull final TopicCreateRequest request)
       throws HieroException {
     Objects.requireNonNull(request, "request must not be null");
diff --git a/hiero-enterprise-base/src/main/java/org/hiero/base/protocol/ProtocolLayerClient.java b/hiero-enterprise-base/src/main/java/org/hiero/base/protocol/ProtocolLayerClient.java
@@ -8,6 +8,8 @@
 import org.hiero.base.protocol.data.AccountCreateResult;
 import org.hiero.base.protocol.data.AccountDeleteRequest;
 import org.hiero.base.protocol.data.AccountDeleteResult;
+import org.hiero.base.protocol.data.AccountHookUpdateRequest;
+import org.hiero.base.protocol.data.AccountHookUpdateResult;
 import org.hiero.base.protocol.data.AccountUpdateRequest;
 import org.hiero.base.protocol.data.AccountUpdateResult;
 import org.hiero.base.protocol.data.ContractCallRequest;
@@ -187,6 +189,16 @@ public interface ProtocolLayerClient {
   @NonNull AccountUpdateResult executeAccountUpdateTransaction(
       @NonNull AccountUpdateRequest request) throws HieroException;
 
+  /**
+   * Executes an account hook update transaction.
+   *
+   * @param request the request containing the details of the account hook update transaction
+   * @return the result of the account hook update transaction
+   * @throws HieroException if the transaction could not be executed
+   */
+  @NonNull AccountHookUpdateResult executeAccountHookUpdateTransaction(
+      @NonNull AccountHookUpdateRequest request) throws HieroException;
+
   /**
    * Executes a token create transaction.
    *
diff --git a/hiero-enterprise-base/src/main/java/org/hiero/base/protocol/data/AccountHookUpdateRequest.java b/hiero-enterprise-base/src/main/java/org/hiero/base/protocol/data/AccountHookUpdateRequest.java
@@ -0,0 +1,59 @@
+package org.hiero.base.protocol.data;
+
+import com.hedera.hashgraph.sdk.Hbar;
+import java.time.Duration;
+import java.util.List;
+import java.util.Objects;
+import org.hiero.base.data.Account;
+import org.hiero.base.data.HookDetails;
+import org.jspecify.annotations.NonNull;
+
+/** Request model for updating account hooks. */
+public record AccountHookUpdateRequest(
+    @NonNull Hbar maxTransactionFee,
+    @NonNull Duration transactionValidDuration,
+    @NonNull Account toUpdate,
+    @NonNull List<HookDetails> hooksToCreate,
+    @NonNull List<Long> hooksToDelete)
+    implements TransactionRequest {
+
+  public AccountHookUpdateRequest {
+    Objects.requireNonNull(maxTransactionFee, "maxTransactionFee is required");
+    Objects.requireNonNull(transactionValidDuration, "transactionValidDuration is required");
+    Objects.requireNonNull(toUpdate, "toUpdate is required");
+    Objects.requireNonNull(hooksToCreate, "hooksToCreate is required");
+    Objects.requireNonNull(hooksToDelete, "hooksToDelete is required");
+    hooksToCreate.forEach(
+        hookDetails -> Objects.requireNonNull(hookDetails, "hooksToCreate must not contain null"));
+    hooksToDelete.forEach(
+        hookId -> {
+          Objects.requireNonNull(hookId, "hooksToDelete must not contain null");
+          if (hookId < 0) {
+            throw new IllegalArgumentException("hooksToDelete must contain only non-negative ids");
+          }
+        });
+
+    if (maxTransactionFee.toTinybars() < 0) {
+      throw new IllegalArgumentException("maxTransactionFee must be non-negative");
+    }
+    if (transactionValidDuration.isNegative() || transactionValidDuration.isZero()) {
+      throw new IllegalArgumentException("transactionValidDuration must be positive");
+    }
+    if (hooksToCreate.isEmpty() && hooksToDelete.isEmpty()) {
+      throw new IllegalArgumentException("at least one hook action must be set");
+    }
+  }
+
+  @NonNull
+  public static AccountHookUpdateRequest of(
+      @NonNull final Account toUpdate,
+      @NonNull final List<HookDetails> hooksToCreate,
+      @NonNull final List<Long> hooksToDelete) {
+    return new AccountHookUpdateRequest(
+        DEFAULT_MAX_TRANSACTION_FEE,
+        DEFAULT_TRANSACTION_VALID_DURATION,
+        Objects.requireNonNull(toUpdate, "toUpdate is required"),
+        List.copyOf(Objects.requireNonNull(hooksToCreate, "hooksToCreate is required")),
+        List.copyOf(Objects.requireNonNull(hooksToDelete, "hooksToDelete is required")));
+  }
+}
diff --git a/hiero-enterprise-base/src/main/java/org/hiero/base/protocol/data/AccountHookUpdateResult.java b/hiero-enterprise-base/src/main/java/org/hiero/base/protocol/data/AccountHookUpdateResult.java
@@ -0,0 +1,15 @@
+package org.hiero.base.protocol.data;
+
+import com.hedera.hashgraph.sdk.Status;
+import com.hedera.hashgraph.sdk.TransactionId;
+import java.util.Objects;
+import org.jspecify.annotations.NonNull;
+
+public record AccountHookUpdateResult(@NonNull TransactionId transactionId, @NonNull Status status)
+    implements TransactionResult {
+
+  public AccountHookUpdateResult {
+    Objects.requireNonNull(transactionId, "transactionId is required");
+    Objects.requireNonNull(status, "status is required");
+  }
+}
diff --git a/hiero-enterprise-base/src/test/java/org/hiero/base/test/AccountClientImplTest.java b/hiero-enterprise-base/src/test/java/org/hiero/base/test/AccountClientImplTest.java
diff --git a/hiero-enterprise-base/src/test/java/org/hiero/base/test/ProtocolLayerClientTests.java b/hiero-enterprise-base/src/test/java/org/hiero/base/test/ProtocolLayerClientTests.java
diff --git a/hiero-enterprise-base/src/test/java/org/hiero/base/test/ProtocolLayerDataCreationTests.java b/hiero-enterprise-base/src/test/java/org/hiero/base/test/ProtocolLayerDataCreationTests.java
diff --git a/hiero-enterprise-microprofile/src/test/java/org/hiero/microprofile/test/ServicesTest.java b/hiero-enterprise-microprofile/src/test/java/org/hiero/microprofile/test/ServicesTest.java
diff --git a/hiero-enterprise-spring/src/test/java/org/hiero/spring/test/ServicesTest.java b/hiero-enterprise-spring/src/test/java/org/hiero/spring/test/ServicesTest.java
