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

Signed-off-by: Aman <amkr6207@gmail.com>

Author: amkr6207

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 com.hedera.hashgraph.sdk.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

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`
+- `com.hedera.hashgraph.sdk.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));
+```

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));
+```

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));
+```

hiero-enterprise-base/src/main/java/org/hiero/base/AccountClient.java

@@ -94,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.
    *
@@ -142,7 +156,7 @@ default void addHook(@NonNull Account account, @NonNull HookDetails hookDetails)
       throws HieroException {
     Objects.requireNonNull(account, "account must not be null");
     Objects.requireNonNull(hookDetails, "hookDetails must not be null");
-    updateHooks(account, List.of(hookDetails), List.of());
+    updateAccountHooks(account, List.of(hookDetails), List.of());
   }
 
   /** Deletes a hook from an account. */
@@ -151,7 +165,7 @@ default void deleteHook(@NonNull Account account, long hookId) throws HieroExcep
     if (hookId < 0) {
       throw new IllegalArgumentException("hookId must be non-negative");
     }
-    updateHooks(account, List.of(), List.of(hookId));
+    updateAccountHooks(account, List.of(), List.of(hookId));
   }
 
   /** Updates account hooks by creating and/or deleting hooks. */
@@ -160,6 +174,6 @@ default void updateHooks(
       @NonNull List<HookDetails> hooksToCreate,
       @NonNull List<Long> hookIdsToDelete)
       throws HieroException {
-    throw new UnsupportedOperationException("Account hook management is not implemented yet.");
+    updateAccountHooks(account, hooksToCreate, hookIdsToDelete);
   }
 }

hiero-enterprise-base/src/main/java/org/hiero/base/data/HookDetails.java

@@ -1,39 +1,33 @@
 package org.hiero.base.data;
 
-import com.hedera.hashgraph.sdk.ContractId;
-import com.hedera.hashgraph.sdk.EvmHookStorageUpdate;
+import com.hedera.hashgraph.sdk.EvmHook;
+import com.hedera.hashgraph.sdk.HookCreationDetails;
 import com.hedera.hashgraph.sdk.HookExtensionPoint;
 import com.hedera.hashgraph.sdk.Key;
-import java.util.List;
 import java.util.Objects;
 import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.Nullable;
 
-/**
- * High-level representation of a hook to attach to an account.
- *
- * @param extensionPoint the extension point where the hook should be attached
- * @param hookId unique identifier of the hook on the owning entity
- * @param evmHookContractId contract implementing the hook logic
- * @param initialStorageUpdates initial EVM storage updates to apply on hook creation
- * @param adminKey optional key used to authorize management operations for this hook
- */
+/** Data model describing a hook to be created on an account update transaction. */
 public record HookDetails(
     @NonNull HookExtensionPoint extensionPoint,
     long hookId,
-    @NonNull ContractId evmHookContractId,
-    @NonNull List<EvmHookStorageUpdate> initialStorageUpdates,
+    @NonNull EvmHook hook,
     @Nullable Key adminKey) {
 
   public HookDetails {
-    Objects.requireNonNull(extensionPoint, "extensionPoint must not be null");
-    Objects.requireNonNull(evmHookContractId, "evmHookContractId must not be null");
-    Objects.requireNonNull(initialStorageUpdates, "initialStorageUpdates must not be null");
-    initialStorageUpdates.forEach(
-        update -> Objects.requireNonNull(update, "initialStorageUpdates must not contain null"));
-    initialStorageUpdates = List.copyOf(initialStorageUpdates);
+    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, hookId, hook, adminKey);
+    }
+    return new HookCreationDetails(extensionPoint, hookId, hook);
+  }
 }

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)

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");

hiero-enterprise-base/src/main/java/org/hiero/base/protocol/ProtocolLayerClient.java

@@ -202,6 +202,16 @@ default AccountHookUpdateResult executeAccountHookUpdateTransaction(
   @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.
    *