hiero-ledger / hiero-ledger/hiero-sdk-cpp
[Intermediate]: Add E2E Tests and Example for HIP-1139 (Immutable Topics)
- Dominant language
- C++
- Stars
- 42
- Forks
- 108
- Avg merge
- 11h 45m
- Merged PRs (30d)
- 2
Description
## 🧩 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](https://github.com/hiero-ledger/hiero-improvement-proposals/blob/main/HIP/hip-1139.md) 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](https://github.com/hashgraph/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:
```cpp
// Option 1: Use existing helper
std::shared_ptr deadKey = ED25519PrivateKey::getZeroKey();
// Option 2: Create from bytes
auto deadKey = PublicKey::fromBytes(std::vector(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](docs/training/workflow.md) for step-by-step workflow guidance.
Read [README.md](README.md) for setup instructions.
❗ Pull requests **cannot be merged** without `S` and `s` signed commits.
See the [Signing Guide](docs/training/signing.md).
---
## 📚 Additional Context or Resources
### References
| Document | Purpose |
|----------|---------|
| **[SDK Design Document](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/proposals/hips/hip-1139.md)** | **Authoritative source** - defines test plan and example |
| [HIP-1139](https://github.com/hiero-ledger/hiero-improvement-proposals/blob/main/HIP/hip-1139.md) | Background context on immutable topics |
| [HIP-540](https://github.com/hashgraph/hedera-improvement-proposal/blob/main/HIP/hip-540.md) | 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](https://discord.com/channels/905194001349627914/1337424839761465364)
Whether you need help finding the right file, understanding existing code, or confirming your approach — we're happy to help.
Contributor guide
Assessment
This issue has not been assessed yet.