hiero-ledger / hiero-ledger/hiero-sdk-cpp

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

Open
#994 6 comments 0 reactions 0 assignees View on GitHub
priority: low scope: examples scope: tests skill: intermediate status: ready for dev
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.