feat: Implement HIP-1195 Hiero Hooks and Account Allowance Hooks

[rwalworth]

Summary

This PR implements the Hiero hooks API for the C++ SDK, including the core hook data types, HookStoreTransaction, hook support on account/contract create/update transactions, hook-aware TransferTransaction, and four end-to-end examples. It also upgrades the HAPI protobufs from v0.69.1 to v0.72.0, which introduces the hook_store service proto and removes the deprecated lambda_sstore proto.

Key Changes:

• New hooks/ subsystem: 17 new types covering EVM hooks, hook calls (fungible, NFT, EVM), hook IDs, and hook creation details
• HookStoreTransaction for updating EVM hook storage slots
• Hook creation/deletion support on AccountCreateTransaction, AccountUpdateTransaction, ContractCreateTransaction, and ContractUpdateTransaction
• Hook call support (FungibleHookCall, NftHookCall) on TransferTransaction
• HAPI upgrade to v0.72.0 with new proto files
• 17 unit test files and 4 integration test files, plus 4 example programs

---

Changes

Hook Data Types (src/sdk/main/include/hooks/, src/sdk/main/src/hooks/)

17 new classes/enumerations for the full hook type hierarchy:

Type	Description
HookCreationDetails	Specifies extension point, EVM hook, admin key, and memo for creating a new hook
HookId / HookEntityId	Identifiers for hooks and hook entities
HookExtensionPoint	Enum — currently ACCOUNT_ALLOWANCE_HOOK
EvmHook	EVM hook definition (spec + storage updates)
EvmHookSpec	Specifies the contract and selector for an EVM hook
EvmHookCall	Encodes an EVM hook call
EvmHookMappingEntry / EvmHookMappingEntries	Key/value mapping entries for hook storage
EvmHookStorageSlot / EvmHookStorageUpdate	Storage slot address and pending update
HookCall	Union type for the three call variants
FungibleHookCall / NftHookCall	Fungible and NFT hook call details
FungibleHookType / NftHookType	Enumerations for hook call types

All types implement fromProtobuf() / toProtobuf() round-trips.

Files added:

• src/sdk/main/include/hooks/ (14 headers)
• src/sdk/main/src/hooks/ (14 source files)

HookStoreTransaction

New transaction type that updates the EVM storage slots of an existing hook. Supports adding individual EvmHookStorageUpdate entries or replacing them wholesale, and serialises to the HookStoreTransactionBody protobuf.

Files added:

• src/sdk/main/include/HookStoreTransaction.h
• src/sdk/main/src/HookStoreTransaction.cc

Account & Contract Transaction Hook Support

AccountCreateTransaction, AccountUpdateTransaction, ContractCreateTransaction, and ContractUpdateTransaction all gained hook management APIs:

• Create transactions — addHook(HookCreationDetails) / setHooks(vector<HookCreationDetails>) to attach hooks at creation time
• Update transactions — additionally addHookToDelete(int64_t hookId) / setHooksToDelete(...) to remove existing hooks

Files modified:

• src/sdk/main/include/AccountCreateTransaction.h / .cc
• src/sdk/main/include/AccountUpdateTransaction.h / .cc
• src/sdk/main/include/ContractCreateTransaction.h / .cc
• src/sdk/main/include/ContractUpdateTransaction.h / .cc

TransferTransaction Hook Calls

TransferTransaction can now carry FungibleHookCall and NftHookCall alongside regular transfers. The hook calls are serialised into the CryptoTransferTransactionBody protobuf via the updated HbarTransfer, TokenTransfer, and TokenNftTransfer helpers.

Files modified:

• src/sdk/main/include/TransferTransaction.h / .cc
• src/sdk/main/include/HbarTransfer.h / .cc
• src/sdk/main/include/TokenTransfer.h / .cc
• src/sdk/main/include/TokenNftTransfer.h / .cc

HAPI Protobuf Upgrade (v0.69.1 → v0.72.0)

• Updated HieroApi.cmake to target v0.72.0
• Replaced lambda_sstore.proto with hook_store.proto in proto/CMakeLists.txt
• Added: registered_node_create.proto, registered_node_delete.proto, registered_node_update.proto, registered_service_endpoint.proto, tss/ledger_id_publication.proto, tss/tss_encryption_key.proto
• Removed: block/stream/chain_of_trust_proof.proto

Examples (4 new programs)

Example	Description
AccountHooksExample.cpp	Create and update an account with EVM hooks attached
ContractHooksExample.cpp	Deploy a contract and attach hooks during creation and update
HookStoreExample.cpp	Submit a HookStoreTransaction to update EVM storage slots
TransferTransactionHooksExample.cpp	Execute token/NFT transfers with fungible and NFT hook calls

Also includes a Solidity contract HieroHookContract.sol used by the examples.

---

Testing

Unit Tests (17 new files)

Test File	Coverage
EvmHookUnitTests.cc	EvmHook protobuf round-trip
EvmHookCallUnitTests.cc	EvmHookCall protobuf round-trip
EvmHookMappingEntriesUnitTests.cc	EvmHookMappingEntries protobuf round-trip
EvmHookMappingEntryUnitTests.cc	EvmHookMappingEntry protobuf round-trip
EvmHookSpecUnitTests.cc	EvmHookSpec protobuf round-trip
EvmHookStorageSlotUnitTests.cc	EvmHookStorageSlot protobuf round-trip
EvmHookStorageUpdateUnitTests.cc	EvmHookStorageUpdate protobuf round-trip
FungibleHookCallUnitTests.cc	FungibleHookCall protobuf round-trip
NftHookCallUnitTests.cc	NftHookCall protobuf round-trip
NftHookTypeUnitTests.cc	NftHookType enum mapping
HookCallUnitTests.cc	HookCall union protobuf round-trip
HookCreationDetailsUnitTests.cc	HookCreationDetails protobuf round-trip
HookEntityIdUnitTests.cc	HookEntityId protobuf round-trip
HookIdUnitTests.cc	HookId protobuf round-trip
HbarTransferUnitTests.cc	HbarTransfer with hook call protobuf round-trip
TokenTransferHookUnitTests.cc	TokenTransfer with hook call protobuf round-trip
TokenNftTransferHookUnitTests.cc	TokenNftTransfer with hook call protobuf round-trip
TransferTransactionHookUnitTests.cc	TransferTransaction with hook calls serialisation

Integration Tests (4 new/expanded files)

Test File	Description
HookStoreTransactionIntegrationTests.cc	Submit HookStoreTransaction against a local solo network
TransferTransactionHooksIntegrationTests.cc	Full transfer flows with fungible and NFT hook calls
AccountCreateTransactionIntegrationTests.cc	(expanded) Create accounts with hooks
AccountUpdateTransactionIntegrationTests.cc	(expanded) Update accounts adding/deleting hooks
ContractCreateTransactionIntegrationTests.cc	(expanded) Deploy contracts with hooks
ContractUpdateTransactionIntegrationTests.cc	(expanded) Update contracts adding/deleting hooks

Prerequisites:

• Local Hiero network running via solo
• /etc/hosts configured with Kubernetes DNS entries

---

Files Changed Summary

Category	Count	Notes
New hook types (headers + sources)	28	Full protobuf round-trip support
New transaction types	2	HookStoreTransaction (header + source)
Modified transactions	8	Account, Contract create/update; TransferTransaction + transfer helpers
New examples	4	+ Solidity contract
New unit test files	17
New/expanded integration test files	6
Build / proto config	3	HieroApi.cmake, proto/CMakeLists.txt, src/sdk/main/CMakeLists.txt
CI	1	.github/workflows/zxc-build-library.yaml
Total files changed	94	9,188 insertions, 207 deletions

---

Breaking Changes

None. All previously existing public APIs remain unchanged. Hook-related APIs are purely additive.

The protobuf upgrade from v0.69.1 to v0.72.0 removes lambda_sstore.proto (replaced by hook_store.proto), but this was not part of the SDK's public API surface.

[github-actions]

Hey @rwalworth 👋 thanks for the PR!
I'm your friendly PR Helper Bot 🤖 and I'll be riding shotgun on this one, keeping track of your PR's status to help you get it approved and merged.

This comment updates automatically as you push changes -- think of it as your PR's live scoreboard!
Here's the latest:

---

PR Checks

✅ DCO Sign-off -- All commits have valid sign-offs. Nice work!

---

✅ GPG Signature -- All commits have verified GPG signatures. Locked and loaded!

---

✅ Merge Conflicts -- No merge conflicts detected. Smooth sailing!

---

✅ Issue Link -- Linked to #1013 (assigned to you).

---

🎉 All checks passed! Your PR is ready for review. Great job!

[gsstoykov]

LGTM.