HIP-721: Add Software Version to Events
| Author | Edward Wertz, Nick Poorman |
|---|---|
| Requested By | Swirlds Labs |
| Discussions-To | https://github.com/hashgraph/hedera-improvement-proposal/discussions/720 |
| Status | Final ⓘ |
| Needs Council Approval | Yes ⓘ |
| Review period ends ⓘ | Wed, 10 May 2023 07:00:00 +0000 |
| Type | Standards Track ⓘ |
| Category | Core ⓘ |
| Created | 2023-04-19 |
| Updated | 2023-04-27 |
| Release | v0.39.0 |
Table of Contents
Abstract
Add the software version to events that are serialized and to the event interface. This permits the application to determine which version of software was used to create each event, and optionally to ignore events created by previous versions.
Motivation
Allow the application to control how events created by a previous software version are handled by a newer software version.
Currently, events which do not reach consensus prior to a software upgrade are lost and the transactions are never handled.
Rationale
This change is a prerequisite for a planned platform feature called the preconsensus event stream. The preconsensus event stream writes events to disk prior to the events reaching consensus. When a node is restarted, events from this stream will be replayed, starting with events that came after the state snapshot loaded into the node, and ending with the last events that were saved prior to the node shutting down. When the system performs an upgrade, this new system of replaying events will make it possible for events created before the software upgrade to reach consensus after the software upgrade. (Currently, these events are simply discarded). The change proposed by this HIP will enable the application to decide whether to act on the transactions generated by the older software version, or if those transactions should be ignored. If this feature is not implemented, the application will not know when it is receiving events that have been generated by a different software version and would attempt to handle them in the same way.
https://github.com/hashgraph/hedera-services/issues/6026
User stories
- This is an internal platform feature and will not be something the users interact with directly. However, the
following user story illustrate the benefit of this feature:
- John submits a transaction just before the mainnet undergoes a software upgrade. When John comes back after the software upgrade to check on the status of his transaction, he can see whether the transaction came to consensus and was handled after the upgrade. If the transaction failed to be handled, John can be given a more specific reasons as to why the transaction failed.
Specification
The binary serialization format for events will be updated to include the software version. The in-memory Event
interface will have a new method getSoftwareVersion() that returns the SoftwareVersion. This API change will affect
users that read our serialized event format or iterate over events in memory.
https://github.com/hashgraph/hedera-services/pull/6236
Backwards Compatibility
Previous software versions used to deserialize the event stream (post consensus) will no longer be capable of parsing the new event stream without modification. Newer software versions with this change will be able to parse events and events streams from previous software versions.
Security Implications
Currently, there is no software version in events and event processing code paths are not sensitive to the software version.
At a data layer, adding the software version does not impact security. The software version upgrade which introduces the software version in serialized events may have to handle versions of the older event serialization format until all nodes have upgraded.
At the application layer, new code paths which key off the software version value can be created. The application developer will need to consider how to process events and transactions from different software versions. The same security practices against malicious nodes sending events would apply and the application developer would need to ensure they are not introducing bugs or attack vectors if the application receives events from older or future software versions.
How to Teach This
Javadoc will be provided on the new interface method. The impacted developers are the Hedera app developers that use the platform’s Event interface and anyone that consumes the serialized event data without using the platform software.
Reference Implementation
This feature will be developed by the Swirlds Labs team. https://github.com/hashgraph/hedera-services/pull/6236
Rejected Ideas
No rejected ideas at this time.
Open Issues
No issues with this HIP at this time.
References
- Original Issue: https://github.com/hashgraph/hedera-services/issues/6026
- Pull Request of Solution: https://github.com/hashgraph/hedera-services/pull/6236
Copyright/license
This document is licensed under the Apache License, Version 2.0 – see LICENSE or (https://www.apache.org/licenses/LICENSE-2.0)
Citation
Please cite this document as: