Protocol Update 2 - Alpha Centauri 2.0 - Transaction Memos¶
Effective on Mainnet |
Oct 13, 2021 |
|---|---|
Effective on Testnet |
Sep 22, 2021 |
Specification hash |
|
Specification¶
Protocol update
Protocol Version: 2
Builds on Protocol Version: 1
Abstract
This document describes the changes in Concordium protocol version 2
compared to protocol version 1, which is the initial protocol at the
launch of mainnet.
The protocol change adds three new transaction types to the set of
supported transactions. These three transactions are transfer with
memo, encrypted transfer with memo, and transfer with schedule and
memo. These transactions behave akin to the analogously named existing
transactions without a memo, but allow the sender to add a message to
the transfer. This message is recorded on the chain.
Background
Concordium protocol version 1 supports the following 16 account
transaction types `DeployModule`, `InitContract`, `Update`,
`Transfer`, `AddBaker`, `RemoveBaker`, `UpdateBakerStake`,
`UpdateBakerRestakeEarnings`, `UpdateBakerKeys`,
`UpdateCredentialKeys`, `EncryptedAmountTransfer`,
`TransferToEncrypted`, `TransferToPublic`, `TransferWithSchedule`,
`UpdateCredentials`, `RegisterData`. Each transaction has a common
signature and header, and a transaction-type specific payload.
If a transaction payload is not among the above listed recognized
payloads then the transaction can still be included in a block, but
its outcome will be `SerializationFailure`, and it will have no other
effect on the state of the chain.
When transactions are parsed their type is determined by a single-byte
tag value. Each supported transaction type has a protocol-defined tag.
When a valid transaction is included in a block it generates a list of
one or more events. In protocol version 1 there are 21 possible events
that can be generated. For example an event is "Transferred" a given
amount of GTU from address A to address B. These events are part of a
transaction outcome. Outcomes of all transactions in a block are
hashed, and their combined hash is included in a block.
Changes
1. Protocol version 2 will have all protocol 1 transaction types with
the same meaning, and three additional transaction types. These are
- TransferWithMemo
- EncryptedAmountTransferWithMemo
- TransferWithScheduleAndMemo
with tags 22, 23, and 24, respectively. These will have the same
payloads as the corresponding existing transactions, and an additional
memo field. The memo is a byte array with a maximum size of 256.
The protocol does not give any meaning to the memo, it is an
uninterpreted part of the transaction that is recorded by the chain.
2. Protocol 2 will have all protocol 1 events, and additionally a new
event `TransferMemo` that will be generated by the three new
transaction types. The event contains verbatim the memo that was part
of the transaction.
3. The cost of the three new transaction types uses the same formula
as the cost of the corresponding existing transaction types. The
per-transaction-type cost factor is the same. As a consequence the
cost C(tₘ) of a transaction with a memo is
C(tₘ) = C(t) + size + 2
where t is the corresponding existing transaction without a memo and
size is the size in bytes of the memo. The +2 accounts for the
recording of the size of the memo, which uses 2 bytes.
Effects
1. All existing transactions that are valid retain their semantics
exactly; their outcomes are the same, as well as their effects on the
state of the chain.
2. If a transaction would be included in a block, but fail with
`SerializationFailure` rejection reason in protocol version 1 then it
might be valid in protocol version 2 and interpreted as either
`TransferWithMemo`, `EncryptedAmountTransferWithMemo`, or
`TransferWithScheduleAndMemo`. This will only happen if the
transaction payload tag is 22, 23, or 24, which have no assigned
meaning in protocol version 1.
Serialization
The new transaction payload types are serialized as follows.
TransferWithMemo
- tag 22: byte (1 byte)
- receiver address: account address (32 bytes)
- memo: memo (variable length)
- amount: amount (8 bytes)
EncryptedAmountTransferWithMemo
- tag 23: byte (1 byte)
- receiver address: account address (32 bytes)
- memo: memo (variable length)
- remaining amount: encrypted amount (192 bytes)
- amount to transfer: encrypted amount (192 bytes)
- index: encrypted amount index (8 bytes)
- proof: encrypted transfer proof (2192 bytes)
TransferWithScheduleAndMemo
- tag 24: byte (1 byte)
- receiver address: account address (32 bytes)
- memo: memo (variable length)
- schedule length: byte (1 byte)
- schedule: sequence of pairs (timestamp, amount) (variable length)
where `memo` is serialized as
- length: u16 (2 bytes big endian)
- bytes: byte array (variable length)
Genesis data format
The genesis data format at protocol version 2 is the same as at
protocol version 1, except that the version tag is 4 instead of 3. In
particular, the `GDP2Initial` and `GDP2Regenesis` genesis data formats
are the same as `GDP1Initial` and `GDP1Regenesis` respectively.
`GDP2Initial` specifies core genesis parameters and an initial state,
which may be used as an initial genesis block. `GDP2Regenesis`
specifies core genesis parameters, the hashes of the first genesis
block, previous genesis block and terminal block of the preceding
chain, and the state at regenesis. This is used when restarting a chain
as a result of a protocol update.
Protocol update instruction
The protocol update instruction is identified by the SHA256 hash of
this file. The instruction does not need any auxiliary data.
The protocol update starts a new chain with the genesis block
containing genesis data in the `GDP2Regenesis` format. The parameters
are determined as follows:
- The core genesis parameters are unchanged, except that the genesis
time is the timestamp of the last finalized block of the preceding
chain.
- The hash of the first genesis block is either
- the hash of the genesis block of the preceding chain, if it is
a `GDP1Initial` genesis block; or
- the first genesis block recorded in the genesis block of the
preceding chain, if it is a `GDP1Regenesis` genesis block.
- The hash of the previous genesis block is the hash of the genesis
block of the preceding chain.
- The hash of the terminal block is the hash of the last finalized
block of the preceding chain.
- The state is derived from the state at the last finalized block of
the preceding chain as follows:
- The `SeedState` data structure is updated with:
- the `epoch` is reset to 0;
- the `currentLeadershipElectionNonce` is the SHA256 hash of the
concatenation of the string `"Regenesis"` with the previous value
of `updatedNonce`; and
- the `updatedNonce` is the same as
`currentLeadershipElectionNonce`.
- The `Updates` data structure is updated with:
- the current protocol update is unset; and
- the protocol update queue is emptied.
Commentary¶
Protocol update commentary
Protocol Version: 2
Builds on Protocol Version: 1
This protocol update adds the ability for the sender of a GTU transfer
to add a memo to the transfer to convey additional information to the
recipient. This functionality corresponds to the typical reference
field in a conventional bank transfer. The memo is optional.
The memo is recorded on the chain as part of the transaction, and it
can never be retracted. In particular this means it is publicly
visible to anyone who is observing the chain. As a consequence it
should not contain sensitive information or information that can be
misused by copying.
The memo will be visible in all the clients, e.g., mobile wallets,
desktop wallet, concordium-client, both for the sender and the
recepient of the transfer.
The data in the memo can be arbitrary strings, integers, or more
complex values. The only limit is the size of the data. The data is
not checked by the chain, it is simply recorded there. In order for
the tools to understand the data and display it in a readable way to
the users it is conventional to use CBOR encoding. Concordium's tools
will use this, and expect it. If this convention is not adhered to
then user experience will be degraded.
The protocol update is fully backwards compatible. This means that all
existing valid transactions will retain their validity and semantics,
e.g., a transfer of 10GTU will still mean a transfer of 10GTU.
New transaction types have a cost in-line with existing transactions,
but accounting for the increased transaction size. For example, a
transfer of GTU with memo will cost as much as a transfer of GTU
without a memo plus a cost based on the size of the memo, which is a
linear function fo the size.
Because existing nodes do not support new transaction types node
runners will have to update their nodes before the protocol update
will take effect. The updated node that supports the update will be
released ahead of time to give node runners time to update. Clients
such as wallets and the concordium-client will be released
concurrently with the updated node as well.