[Intermediate]: Add E2E Tests and Example for HIP-1139 (Immutable Topics)

[gsstoykov]

🧩 Intermediate Friendly

This issue is a good fit for contributors who are already familiar with the Hiero C++ SDK and feel comfortable navigating the codebase.

Intermediate Issues often involve:

• Exploring existing implementations
• Understanding how different components work together
• Making thoughtful changes that follow established patterns

The goal is to support deeper problem-solving while keeping the task clear, focused, and enjoyable to work on.

---

🐞 Problem Description

HIP-1139: Enable Immutable Topic Ids and Updatable Submit Keys without an Admin Key allows topics to be made fully immutable by setting Admin Keys and Submit Keys to "dead keys" (all-zeros Ed25519 public keys that are cryptographically impossible to sign with).

The SDK already supports this feature - no implementation work is needed. However, the SDK is missing:

1. End-to-end integration tests validating the feature behavior
2. An example demonstrating the immutability transition flow

Key Concepts

Term	Description
Dead Key	An all-zeros Ed25519 public key that is cryptographically impossible to sign with
Topic Immutability	State where both Admin Key and Submit Key are unusable - no modifications or submissions possible
Key Immutability	Making a key permanently unusable by setting it to a dead key

---

💡 Expected Outcome

Implement the tests and example following the design document:

Design Document: https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/proposals/hips/hip-1139.md

Important

The implementation MUST follow the test plan and example patterns defined in the design document above. This ensures consistency across all Hiero SDK implementations.

Test Plan (13 test cases from design document)

1. Given a private topic with Admin Key and Submit Key, when Submit Key is updated to a dead key with valid Admin Key signature, then no further messages can be submitted.

2. Given a private topic with Admin Key and Submit Key, when Submit Key is updated to an empty key list with valid Admin Key signature, then messages can be submitted without a submit key signature.

3. Given a private topic with Admin Key and Submit Key, when Admin Key is updated to a dead key with valid Admin Key signature, then messages can still be submitted with submit key, but no administrative updates are possible.

4. Given a private topic with Admin Key and Submit Key, when Admin Key is updated to an empty key list with valid Admin Key signature, then messages can still be submitted with submit key, but no administrative updates are possible.

5. Given a private topic with Admin Key and Submit Key, when both keys are updated to dead keys with valid Admin Key signature, then the topic becomes fully immutable.

6. Given a private topic with only Submit Key (no Admin Key), when Submit Key is updated to a dead key with valid Submit Key signature, then no more messages can be submitted.

7. Given a private topic with only Submit Key (no Admin Key), when Submit Key is updated to an empty key list with valid Submit Key signature, then messages can be submitted without a submit key signature.

8. Given a public topic with Admin Key but no Submit Key, when Admin Key is updated to a dead key with valid Admin Key signature, then the topic is administratively immutable but still allows message submission.

9. Given a public topic with Submit Key set to a dead key, when a message submission is attempted with the original Submit Key, then submission fails with invalid signature error.

10. Given a TopicUpdateTransaction to update Submit Key to a dead key without valid Submit Key signature, then update fails with invalid signature.

11. Given a TopicUpdateTransaction to update Admin Key to a dead key without valid Admin Key signature, then update fails with invalid signature.

12. Given a TopicUpdateTransaction to update Submit Key to a dead key with valid Admin Key signature, then update succeeds.

13. Given a TopicUpdateTransaction to update Submit Key from a dead key to a valid key with valid Admin Key signature, then update succeeds.

Example

Create an example demonstrating the complete immutability transition flow as defined in the design document.

---

🧠 Implementation Notes

Test Network Setup

E2E tests require a running Hiero network to execute against. Options include:

• Local network using solo - see CI workflow for reference
• Testnet - requires testnet account credentials

Review existing E2E tests in src/sdk/tests/integration/ to understand how tests connect to the network.

Related Code References

File	Purpose
src/sdk/tests/integration/TopicUpdateTransactionIntegrationTests.cc	Existing topic update tests - add new tests here
src/sdk/tests/integration/TokenUpdateTransactionIntegrationTests.cc	Reference for zero key patterns (getZeroKey())
src/sdk/main/include/ED25519PrivateKey.h	Contains ZERO_KEY_STR and getZeroKey()
src/sdk/examples/TopicWithAdminKeyExample.cpp	Existing topic example - follow similar patterns

Dead Key Implementation

The SDK already provides dead key support:

// Option 1: Use existing helper
std::shared_ptr<PrivateKey> deadKey = ED25519PrivateKey::getZeroKey();

// Option 2: Create from bytes
auto deadKey = PublicKey::fromBytes(std::vector<std::byte>(32, std::byte{0}));

State Transitions

Admin Key	Submit Key	Topic State
Active	Active	Fully manageable
Dead	Active	Administratively immutable, submissions allowed
Active	Dead	Manageable, submissions blocked
Dead	Dead	Fully immutable
Empty KeyList	Active	Administratively immutable, submissions allowed
Active	Empty KeyList	Manageable, public submissions allowed

---

✅ Acceptance Criteria

To help get this change merged smoothly:

• Follow design document: Tests match the 13 test cases in the design document
• All tests pass: E2E tests pass against a local or test network
• Example works: Example demonstrates complete immutability transition
• Follows patterns: Tests follow existing SDK test conventions (see TokenUpdateTransactionIntegrationTests.cc for zero key patterns)
• Pass all CI checks
• Review: All code review feedback addressed

---

📋 Contribution Guide

To help your contribution go as smoothly as possible, we recommend following these steps:

• Comment /assign to request the issue
• Wait for assignment
• Fork the repository and create a branch
• Set up the project using the instructions in README.md
• Make the requested changes
• Sign each commit using -s -S
• Push your branch and open a pull request

Read Workflow Guide for step-by-step workflow guidance.
Read README.md for setup instructions.

❗ Pull requests cannot be merged without S and s signed commits.
See the Signing Guide.

---

📚 Additional Context or Resources

References

Document	Purpose
SDK Design Document	Authoritative source - defines test plan and example
HIP-1139	Background context on immutable topics
HIP-540	Related - token key immutability

If you have questions while working on this issue, feel free to ask!

You can reach the community and maintainers here:
Hiero-SDK-C++ Discord

Whether you need help finding the right file, understanding existing code, or confirming your approach — we're happy to help.

[aceppaluni]

Update:

Still working on issue and attempting to combat testing issues.