diff --git a/README.md b/README.md index 6e9883f..c1df155 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ protocol and APIs. |[UIP-0021](https://github.com/dtr-org/uips/blob/master/UIP-0021.md)|Transfer Esperanza Transactions|Proposed|2018-11-08| |[UIP-0024](https://github.com/dtr-org/uips/blob/master/UIP-0024.md)|CTOR - Canonical Transactions Ordering Rule|Proposed|2018-12-14| |[UIP-0026](https://github.com/dtr-org/uips/blob/master/UIP-0026.md)|Graphene - block propagation protocol|Proposed|2019-02-21| +|[UIP-0027](https://github.com/dtr-org/uips/blob/master/UIP-0027.md)|Transaction service fields|Draft|2019-05-07| The team is committed to fostering a welcoming and harassment-free environment. All participants are expected to adhere to our [code of diff --git a/UIP-0027.md b/UIP-0027.md new file mode 100644 index 0000000..be6bc22 --- /dev/null +++ b/UIP-0027.md @@ -0,0 +1,93 @@ +# UIP-27: Transaction service fields + +``` +Author: Dima Saveliev +Status: Draft +Created: 2019-05-07 +``` + +## Abstract + + This document describes protocol changes in the transaction structure: +the `nVersion` field is going to be replaced by four separate service fields: +* type +* version +* two more fields are vacant + + +## Motivation + + [UIP-0018](https://github.com/dtr-org/uips/blob/master/UIP-0018.md) introduced **a transaction type** concept +and added the corresponding field as a part of already existing `nVersion` field. +That was achieved by overloading `nVersion` with bit arithmetic at the cost of increasing complexity of the code. + + By implementing separate service fields we solve the following problems: + + 1. Clean-up the logic behind the `type` and `version` fields. + 2. Minimize the size of `type` and `version` fields. + 3. Minimize the impact on the existing test suite. + + As an additional benefit, we will have two more fields for possible future needs. + + +## Specification + +At the moment we have this `nVersion` field structure: + +_These pictures illustrate `nVersion` in big-endian order as we have it in the runtime. +It's worth noting, however, that the serialized bytes will have a little-endian order._ + +``` + 0x00 0x00 0x00 0x00 +^------^ ^------^ ^----------------^ + unused type version +^------------------------------------^ + nVersion +``` + +* `nVersion` - original `uint32_t` value +* `type` - derived `uint8_t` attribute +* `version` - derived `uint16_t` attribute + +Proposed layout for the same bytes: +``` + 0x00 0x00 0x00 0x00 +^------^ ^------^ ^------^ ^------^ +reserved type reserved version +``` + +* `type` - independent`uint8_t` field +* `version` - independent`uint8_t` field + + +## Rationale + +This format was chosen in order to preserve the existing byte order and to minimize the impact on the existing test suite. +It's very hard to add, remove or even swap existing bytes due to a couple of reasons: + +* Tests contain a lot of magic numbers, based on the assumptions regarding transaction size. +* Some tests heavily rely on hardcoded, unique transactions from the real Bitcoin network. +* Unit-e wants to sync regularly with Bitcoin Core with minimal effort. + +All these conditions make structural changes hard, thus it's much more effective +to act in the context of the existing layout. + +By implementing four separate fields we decouple unrelated entities, remove technical debt +without a tremendous amount of extra work and keep our test suite intact hence eliminate some range of security risks. + + +## Backwards compatibility + +The proposed change will have a minimal impact on existing Unit-e codebase and will not change the byte order of existing messages. +We shrink the actual size of `version` field down to 1 byte, but it's not a problem, because the range +of [0, 255] integer values is more than enough to reflect existing transaction versions. + +## Reference implementation + +Work in progress. + +## Copyright + +This document and all its auxiliary files are dual-licensed under +[CC0](https://creativecommons.org/publicdomain/zero/1.0/) and +[MIT](https://opensource.org/licenses/MIT).