hiero-ledger / hiero-ledger/hiero-sdk-cpp
[Advanced]: Upgrade gRPC and protobuf dependencies
- Dominant language
- C++
- Stars
- 42
- Forks
- 108
- Avg merge
- 11h 45m
- Merged PRs (30d)
- 2
Description
### 🧠 Advanced
This issue is well-suited for contributors who are very familiar with the Hiero C++ SDK and enjoy working with its core abstractions and design patterns.
Advanced Issues often involve:
- Exploring and shaping SDK architecture
- Reasoning about trade-offs and long-term impact
- Working across multiple modules or systems
- Updating tests, examples, and documentation alongside code
The goal is to support thoughtful, high-impact contributions in a clear and collaborative way.
> [!IMPORTANT]
> ### 🧭 About Advanced Issues
>
> Advanced Issues usually focus on larger changes that influence how the SDK works as a whole.
>
> These issues often:
> - Touch core abstractions or shared utilities
> - Span multiple parts of the codebase
> - Involve design decisions and trade-offs
> - Consider long-term maintainability and compatibility
>
> Smaller fixes, focused refactors, and onboarding-friendly tasks are just as valuable and often use different labels.
### 👾 Description of the Task
The `grpc` and `protobuf` packages pinned in `vcpkg.json` are significantly out of date. `grpc` is constrained to `>= 1.49.0` (released September 2022) and `protobuf` to `>= 3.21.6` (released August 2022). The current stable releases are gRPC ~1.71.x and protobuf 5.29.x.
These two libraries are tightly versioned — they share transitive dependencies (`abseil`, `re2`, `utf8-range`, `c-ares`) and must be upgraded together. Two-plus years of accumulated bug fixes, TLS/HTTP2 patches, and security improvements are currently not being picked up.
The protobuf 3.x → 5.x transition includes C++ API changes:
- Deprecated arena-allocation accessors were removed
- `google::protobuf::Message` reflection interfaces changed
- Generated accessor naming conventions for certain field types were updated
Any call sites in `src/sdk/main/src/` that invoke generated protobuf methods or interact with reflection APIs may need updates.
Relevant files:
```
vcpkg.json
CMakeLists.txt
src/sdk/main/CMakeLists.txt
src/sdk/main/src/ (all .cc files using generated proto types)
```
### 💡 Proposed Approach
Upgrade `grpc` and `protobuf` together in a single branch since they are co-dependent. Work through any compilation errors caused by the API changes in protobuf 5.x, update the vcpkg baseline if required, and verify the full unit and integration test suite passes before opening a PR.
The upgrade should not change any public SDK API surface — all changes should be internal to how the SDK communicates with generated proto types.
> [!CAUTION]
> ### 🚫 Stop if Public API Changes Are Required
>
> If you encounter a scenario where upgrading gRPC or protobuf **requires a change to the public SDK API** (i.e., any header in `src/sdk/main/include/` that is not under `include/impl/`), **do not proceed with this issue**.
>
> Public API changes require a major version release and must be planned and communicated separately. In that case:
> 1. Stop work on this branch
> 2. Document what public API change is required and why in a comment on this issue
> 3. A maintainer will open a separate tracking issue for the major version bump
>
> All changes in this issue must remain invisible to SDK consumers.
### 👩💻 Implementation Steps
- [ ] Review the protobuf [upgrade guide from 3.x to 4.x/5.x](https://protobuf.dev/news/2023-04-20/) to understand breaking changes
- [ ] Review the [gRPC changelog](https://github.com/grpc/grpc/releases) from 1.49 to current for any C++ API changes
- [ ] Update `vcpkg.json` — change `"version>="` for both packages:
```json
{ "name": "grpc", "version>=": "" },
{ "name": "protobuf", "version>=": "" }
```
- [ ] Update the vcpkg submodule and `builtin-baseline` if the new versions are not available at the current baseline commit
- [ ] Run `cmake --preset linux-x64-debug` and resolve all compilation errors
- [ ] Search `src/sdk/main/src/` for direct use of protobuf reflection or arena APIs and update any broken call sites
- [ ] Run the full unit test suite:
```bash
cmake --build --preset linux-x64-debug
ctest -j6 -C Debug --test-dir build/linux-x64-debug --output-on-failure
```
- [ ] Verify integration tests pass against a local Hiero Solo network
- [ ] Open a pull request with a summary of API changes encountered and how they were resolved
### ✔️ Acceptance Criteria
- [ ] `vcpkg.json` constrains `grpc` and `protobuf` to current stable releases
- [ ] The SDK builds cleanly on Linux (required), macOS and Windows (best effort)
- [ ] All unit tests pass
- [ ] All integration tests pass (run via `hiero-solo-action` as in CI)
- [ ] No public SDK API changes are introduced
- [ ] No unrelated files or behavior changes are included
---
### 📋 Step-by-Step Contribution Guide
To help keep contributions consistent and easy to review, 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](https://github.com/hiero-ledger/hiero-sdk-cpp/blob/main/docs/training/workflow.md) for step-by-step workflow guidance.
Read [README.md](https://github.com/hiero-ledger/hiero-sdk-cpp/blob/main/README.md) for setup instructions.
❗ Pull requests **cannot be merged** without `S` and `s` signed commits.
See the [Signing Guide](https://github.com/hiero-ledger/hiero-sdk-cpp/blob/main/docs/training/signing.md).
### 🤔 Additional Information
This upgrade should be done on a dedicated branch — do not combine it with other dependency bumps, as the compilation errors from protobuf 5.x may touch many files and the diff needs to be reviewable.
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
Research direction
Start with vcpkg.json, CMakeLists.txt, and src/sdk/main/CMakeLists.txt, then review the protobuf upgrade guide and gRPC changelog. Build with cmake --preset linux-x64-debug, inspect protobuf call sites under src/sdk/main/src/, and run the specified unit and integration tests. Done means current stable dependencies build cleanly with all tests passing and no public SDK API changes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cmake, cpp, grpc
- Domain
- backend, build-system
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100