# ParallelChain Protocol v0.5 Changelog

|Formula|Value|Description|
|---|---|---|
|$B_{height, nv0.5}$|TBD|Block height of the first v0.5 (new version) block.|

## Blockchain

### Types

Blocks starting from and including the target block are to contain the following changed types.

#### Transaction (V2)

"Signature" is now computed over the **tuple**: (`2u8`, Signer, Nonce, Commands, Gas Limit, Max Base Fee per Gas, Priority Fee Per Gas) instead of an “intermediate transaction” (in the tuple, `2u8` corresponds to the fact that `TransactionV2` is the second version of transaction)

#### Block Header (V2)

1. The position of the "Hash" and "Height" fields are now reversed. Height comes first.
2. Each leaf in the Transaction Hash binary merkle tree now contains the Hash field of a transaction (instead of the SHA256 over an entire transaction).

##### Base Fee Per Gas Formula (V2)

We make two changes which will allow Block Base Fee Per Gas to fall to 7:
1. The constant $B_{minbasefee}$ is removed. So the Base Fee Per Gas formula is now simply $B_{basefee, v2}(pbfpg,pgu) = pbf + B_{basefeedelta}(pbfpg,pgu)$.
2. The "minimum -1" adjustment on Base Fee Per Gas delta that was applied when $pgu$ is less than $B_{targetgasused}$ is removed. So the Base Fee Per Gas Delta formula is now:

$$
B_{basefeedelta, v2}(pbfpg, pgu) = \begin{cases} 0 & \text{if }pgu = B_{tgtgasused} \\
max(1, \frac{pbfpg \times \left(pgu - B_{tgtgasused}\right)}{8 \times B_{tgtgasused}}) & \text{if }pgu > B_{tgtgasused} \\
\frac{pbfpg \times \left(pgu - B_{tgtgasused}\right)}{8 \times B_{tgtgasused}} & \text{if }pgu < B_{tgtgasused} \end{cases}
$$

#### Block (V2)

1. "Header" is now of type `BlockHeaderV2`.
3. "Transactions" is now of type `Vec<TransactionV2>`.

#### BlockData (V2)

`BlockDataV2` refers to the fields of protocol block that are “packed” into `hotstuff_rs::Data`.

1. The order of fields is now: "Chain ID", "Proposer", **"Timestamp", "Base Fee Per Gas", "Gas Used", "Transactions Hash", "Receipts Hash", "State Hash",** "Logs Bloom", and then transactions and receipts. The bolded fields have been re-ordered to match the order of fields in protocol blocks.
2. The order of fields in the Data Hash pre-image is also changed to match the new order of fields.

#### Receipt (V2)

Receipt is now a struct type with fields:

|Field|Type|Additional info.|
|---|---|---|
|Gas Used|`u64`|The transaction's inclusion cost + the sum of the "Gas Used"s of each of the command's Command Receipts.|
|Exit Code|`ExitCodeV2`|The exit code of the last command in the transaction that was executed.|
|Command Receipts|`Vec<CommandReceiptV2>`|Describes the execution of each command in the transaction. `receipt.command_receipts.len()` is **always** equal to `transaction.commands.len()`. If execution exits before a command begins executing (e.g., because of gas exhaustion), the command receipts of the non-executed commands have exit code [`NotExecuted`](#exit-code).|

#### CommandReceipt (V2)

Command Receipt is now an enum type. Its variants come in the same order as Command (which is unchanged), and are all structs with a [common set](#common-fields) of two fields, as well as *additional* fields for [call](#call:-additional-fields), [withdraw deposit](#withdraw-deposit:-additional-fields), [stake deposit](#stake-deposit:-additional-fields), and [unstake deposit](#unstake-deposit:-additional-fields) that come after the common fields.

##### Common fields

|Field|Type|Additional info.|
|---|---|---|
|Exit Code|`ExitCodeV2`|[Next section](#exit-code).|
|Gas Used|`u64`|Unchanged.|

##### Call: additional fields

|Field|Type|
|---|---|
|Return Value|`Vec<u8>`|
|Log|`Vec<Log>`|

##### Withdraw Deposit: additional fields

|Field|Type|
|---|---|
|Amount Withdrawn|`u64`|

##### Stake Deposit: additional fields

|Field|Type|
|---|---|
|Amount Staked|`u64`|

##### Unstake Deposit: additional fields

|Field|Type|
|---|---|
|Amount Unstaked|`u64`|

#### ExitCode (V2)

“Operation Successful” is now called “Ok”, and “Operation Failed” is now called “Error”. There is also a new “Not Executed” variant:

|Variant|Additional info.|
|---|---|
|Ok|Rename of Operation Successful in v0.4.|
|Error|Rename of Operation Failed in v0.4.|
|Gas Exhausted|Unchanged.|
|Not Executed|Transaction execution exited before the command was executed, for example due to gas exhaustion.|

### Timing

Implementations can be rewritten immediately to use `validate_block_for_sync`.

#### `validate_block_for_sync`

HotStuff-rs v0.3 adds a [special variant of `validate_block`](hotstuff_rs#13) that is exclusively used in sync mode that is called `validate_block_for_sync`. Unlike `validate_block`, this function has no timing requirements and can exit as soon as possible, speeding up block sync.

#### Target block time, version upgrade

To allow for enough time to produce and validate the [version upgrade `Next Epoch`](#version-upgrade-`next-epoch`) command, a special, we introduce a special, larger variant of $B_{tbt}$:

|Formula|Value|Description|
|---|---|---|
|$B_{tbt, vu05}$|TBD|Target block time, (version upgrade, v0.4 to v0.5.) in seconds.|

Upon the replica committing a block with height $B_{height, nv0.5} - 2$, Pacemaker implementations must switch to using $B_{height, nv0.5}$ as `minimum_view_timeout`, and upon committing a block with height $B_{height, nv0.5}$, they must switch back to using $B_{tbt}$.

## World State

In the [version upgrade `Next Epoch` command](version-upgrade-`next-epoch`) the MPTs of the world state are to be rebuilt with the following changes:

### Accounts Trie (V2)

#### Accounts Trie MPT Keys

The "protected visibility byte" (`0x01`) in between `public_address` and `index` has been removed.

Each of an account's fields (Nonce, Balance, Code, CBI Version, and Storage Hash) now sit in the backing MPT of the accounts trie at `(public_address, index)`.

### Storage Trie (V2)

#### Storage Trie MPT Keys

The "public visibility byte" (`0x01`) has been removed.

Every user-provided Storage Trie key now sit in the backing MPT of a storage trie at exactly the key.

## Runtime

### Version upgrade Next Epoch command

v0.5 of the protocol makes [fundamental changes](#world-state) to the data layout of the Account and Storage tries. Since these apply to not only new state but also existing state, all Storage tries and the Account trie will need to be "rebuilt".

This rebuild will be done in the `NextEpoch` command in the block at height $B_{height, nv0.5} - 1$ (i.e., the parent of the first version 0.5 block), which is to be an epoch boundary block.

The rebuild procedure must be equivalent to:
1. For each Storage trie:
1. Initialize a new `ExtensionLayout` storage trie.
2. For each key-value pair in the old storage trie:
- Insert it into the new storage trie without the public visibility byte.
4. Set the Storage Hash of the account in the world state trie to the root hash of the new storage trie.
2. Initialize a new `ExtensionLayout` world state trie.
3. For each key-value pair in the old world state trie:
- Insert it into the new world state trie without the protected visibility byte.

### Contract address (V2)

Starting from and including the upgrade block, contract address is to be a function of the index of the deploy command:

|Formula|New value|Description|
|---|---|---|
|$R_{contractaddr, v2}(s, n, i)$|$SHA256(s, n, i)$|The address of a contract deployed in the $i$-th command of a transaction with signer = $s$ and nonce = $n$.|

## Gas

Starting from and including the upgrade block, the following gas formulas will change:

### World State access

Storage Trie access gas costs are updated to reflect the removal of the ["double-count" of Public Address length](https://github.com/parallelchain-io/parallelchain-protocol/issues/3) in the gas formulae.

#### Storage Trie operations

##### Get

|Symbol|Formula|Description|
|---|---|---|
|$G_{st,get,v2}(k, a)$|$G_{mpt,get}(G_{at,keylen} + k)$|Cost of getting a key of length $k$ that is currently mapped to a value of length $a$ from a Storage Trie.|

##### Set

|Symbol|Formula|Description|
|---|---|---|
|$G_{st,set,v2}(k, a, b)$|$G_{mpt,set}(G_{at, keylen} + k, a, b)$|Cost of setting a key of length $k$ to a value of length $b$ in a Storage Trie given that the key is currently set to a value of length $a$.|

### Transaction inclusion cost (V2)

The size of minimal command receipts and receipts have changed reflecting the updates to the CommandReceipt and Receipt types. Transaction inclusion cost is updated to use these new sizes:

|Symbol|Formula|
|---|---|
|$G_{txincl, v2}(txn)$|$$[serialize(txn).len() + G_{minrcpsize, v2}(txn.commands)] \times G_{txdata} + 5 \times [G_{sget}(G_{acckeylen}, 8) + G_{sset}(G_{acckeylen}, 8, 8)]$$|
|$G_{minrcpsize, v2}(cmds)$|$$13 + \sum_{cmd \in cmds}G_{mincmdrcpsize, v2}(cmd)$$|
|$G_{mincmdrcpsize, v2}(cmd)$|$$\begin{cases} 17 & \text{if cmd is Call, Withdraw Deposit, Stake Deposit, or Unstake Deposit} \\ 9 & \text{otherwise.} \end{cases}$$|

## P2P (V2)

A [phased upgrade](#phased-upgrade) will be scheduled to move existing replicas

### GossipSub

#### Configuration

Message ID is no longer overriden. Fall back to the [`rust-libp2p` default](https://docs.rs/libp2p/latest/libp2p/gossipsub/struct.Config.html#method.message_id) ("concatenate the source peer id with a sequence number").

#### Topics

##### State Machine Replication

1. Both SMR topics have been renamed:

|Previous topic|New topic|
|---|---|
|"consensus"|"hotstuff_rs"|
|`base64url(public_addr)`|"hotstuff_rs/" + `base64url(public_addr)`|

2. Each replica is now required to subscribe to not only the "hotstuff_rs" topic, but *also* the individual topics of *all* replicas in its closest Kademlia k-bucket. However, only messages destined for a replica's individual topic should be forwarded to `hotstuff_rs`.

##### Transaction Drop Notification

Removed. Functionality replaced with `subscribe_to_transaction_events` RPC.

### Kademlia

#### Configuration

|Overridden configuration|New value|
|---|---|
|Protocol names|"parallelchain_mainnet/v2"|

### Phased upgrade

To avoid requiring a coordinated shutdown, binary upgrade, and then restart of Mainnet replicas in order to effect a transition from P2P V1 to P2P V2, we will instead do a phased upgrade.

Fullnode software implementing v0.5 of the protocol will support both P2P V1 and V2. A configuration variable will be made available that lets operators choose between using both P2P V2 only, or both V1 and V2, e.g.,

enum P2PVersion {
    V1AndV2,
    V2,
}

A fullnode configured to use both versions of P2P will send and process GossipSub messages in both V1 and V2 networks. To prevent duplicated processing of messages, each Fullnode can remember the set of peers that it has received V2 messages from, and not forward messages it receives on the V1 P2P network from the same peer to the rest of the implementation.

Phased rollout of P2P can proceed as follows:
1. On each of 4 designated dates, replicas representing 20% of validator power will shut down and start with new binaries, with `P2PVersion::V1AndV2` selected.
2. On a single, final date, the last 20% of validator power will shut down and start with new binaries, now with `P2PVersion::V2` selected.
3. Then, on 4 further designated dates, replicas restarted in step 1 restart again, this time with `P2PVersion::V2` selected.

## RPC

A single new RPC, as well as "v2s" of four existing RPCs.

### New RPCs

#### `subscribe_to_transaction_events`

This new RPC replaces [Transaction Drop Notifications](https://github.com/parallelchain-io/parallelchain-protocol/blob/master/P2P.md#transaction-drop-notification2) as a mechanism which clients can use to determine the status of "pending transactions" (i.e., transactions that have been submitted to the network but have not been included in a committed block).

Calling this RPC establishes the [Notification WebSocket](#notification-websocket).

##### HTTP Method

Unlike every other RPC, `subscribe_to_transaction_events` calls are to use the HTTP "GET" method. This is because only HTTP "GET" requests can be upgraded to a WebSocket.

##### Request body

Empty. Instead, parameters are provided through query string (next subsection).

##### Query parameters

|Parameter|Value|
|---|---|
|"transaction_hash"|List of transaction hashes.|
|"signer"|List of signers.|

Both parameters are:
- **Optional**: if neither parameters are provided, the established WebSocket will receive events about every transaction.
- **Mutually exclusive**: if both parameters are provided, the server may return 400 (Bad Request).
- **Sets**: if a value is repeated twice or more in the list, it is treated as if it is only present once.

Parameter values are to be encoded as comma-delineated lists of Base64URL encoded transaction hashes / signer public addresses in between square brackets ("[]"). For example, the following RPC call establishes a WebSocket that subscribes to transactions with hashes "abc" and "def" (of course, real Base64URL hashes will be longer than 3 characters):
> /subscribe_to_transaction_events?transaction_hash=[abc, def]

##### Response

None. [Notification WebSocket](#notification-websocket) established.

### Notification WebSocket

The Notification WebSocket supports two types of messages:
- **Notification**: containing `(TransactionHash, Event)`.
- [**Ping** and **Pong**](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#pings_and_pongs_the_heartbeat_of_websockets): each side may send a ping to the other side, expecting a pong to test connection and/or process liveness.

The fullnode at the server-side of the notification websocket sends notification messages to the client to inform them of changes in the "status" of the specified transactions (all transactions, if [query parameters](#query-parameters) are empty).

#### Transaction Event

A Transaction Event is an enum whose variants indicate that "something has happened" to the Transaction.

Transaction Event has 9 variants. These are specified in the table below. For example, the first row of this table represents the enum variant `Received(Transaction)`, and the second row of the table represents the enum variant `InsertedToMempool`.

The transaction events enum and the "reason" enums that variants of the transaction events enum can contain are designed to be *as exhaustive as possible*. This means that some events--and especially some reasons--may not correspond to scenarios that occur in simpler fullnode implementations. The protocol does not require fullnode implementations to emit every single transaction event variant or reason variant.

|Variant|Field|Description|
|---|---|---|
|Received|Transaction|The transaction was received either in a `submit_transaction` RPC call, or in a P2P GossipSub message addressed to the "mempool" topic.|
|Inserted to Mempool|N/A|The transaction was inserted into the Fullnode's local mempool.|
|Rejected from Mempool|[Rejected from Mempool Reason](#rejected-from-mempool-reason)|The fullnode attempted to insert the transaction into its local mempool, but it was rejected and discarded.|
|Removed from Mempool|[Removed from Mempool Reason](#removed-from-mempool-reason)|The transaction that was previously in the fullnode's local mempool was removed and discarded.|
|Popped to Executor|N/A|The transaction was "popped" (removed) from the fullnode's local mempool to be executed as part of a new block. This is emitted from [`produce_block`](https://github.com/parallelchain-io/parallelchain-protocol/blob/master/Blockchain.md#app), but not `validate_block`.|
|Included in Block|N/A|The transaction was included in a block that was (or is about to be) written into the fullnode's local Block Tree. This is emitted from both `produce_block` and `validate_block`.|
|Rejected from Block|[Rejected from Block Reason](#rejected-from-block-reason)|The fullnode executed the transaction in `produce_block` (refer to the "Popped to Executor" variant), but decided not to include it in a block and thus discarded it.|
|Block Pruned|N/A|The transaction was included in a block that was subsequently removed ("pruned") from the blockchain (because a conflicting block was committed).|
|Block Committed|Block Hash|The transaction was included in a block that was committed.|

##### Rejected from Mempool Reason

|Variant|Description|
|---|---|
|Nonce Less Than Committed|The transaction's nonce is smaller than the the transaction signer's nonce in the committed world state (the world state after executing the highest committed block).|
|Base Fee Per Gas Too Low|The transaction's base fee per gas is considered "too low" by the local Fullnode.<br><br> Fullnode implementations and administrators are free to choose any policy for deciding that a transaction's base fee per gas is "too low".[^1]|
|Mempool is Full|The local fullnode's mempool is full (e.g., number of bytes-wise).|
|Duplicate Signer and Nonce|The local fullnode's mempool already contains a transaction with the same signer and nonce.|
|Other|Any reason for rejecting a transaction from the local mempool that do not reasonably fit into any of the four reasons above.|

[^1]: For example, a simple Fullnode could reject a transaction from entering its mempool if its base fee per gas is smaller than some configuration variable. Likewise, a more sophisticated Fullnode could reject a transaction if its base fee per gas is 2 standard deviations lower than the average base fee per gas in the blocks committed in the past hour.

##### Removed from Mempool Reason

|Variant|Description|
|---|---|
|Nonce Less Than Committed|The transaction's nonce is now smaller than the transaction signer's nonce in the committed world state (i.e., because a new block was committed).|
|Base Fee Per Gas Too Low|The transaction's base fee per gas is now considered "too low" by the local fullnode (refer to the description of the variant with the same name in [Rejected from Block Reason](#rejected-from-block-reason) for a discussion of what counts as "too low").|
|Mempool is Full|The local fullnode's mempool has become full, so this transaction was removed to create more space.|
|Replaced by Duplicate Signer and Nonce|The local fullnode received a transaction with the same signer and nonce and chose to replace this transaction in its local mempool with the |
|Other|Any reason for removing a transaction from the local mempool that do not reasonably fit into any of the four reasons above.|

##### Rejected from Block Reason

|Variant|Description|
|---|---|
|Nonce Less Than Committed|The transaction's nonce is smaller than the the transaction signer's nonce in the committed world state.|
|Nonce Not Equal to Speculative|The transaction's nonce is not equal to the transaction signer's nonce in the speculative world state (the world state after executing the parent block and all preceding transactions in the current block).|
|Base Fee Per Gas Too Low|The transaction's base fee per gas is smaller than the block's base fee per gas.|
|Balance Less Than Inclusion Cost|The transaction signer's balance is smaller than the current block's base fee per gas.|
|Other|Any reason for rejecting a transaction from the current block that do not reasonably fit into any of the four reasons above.|

### V2 RPCs

The following changed RPCs will be accessible at their existing URLs suffixed by "/v2".

#### `submit_transaction/v2`

##### Request

struct SubmitTransactionRequestV2 {
    transaction: TransactionV1OrV2,
}

enum TransactionV1OrV2 {
    V1(TransactionV1),
    V2(TransactionV2),
}

##### Response

struct SubmitTransactionResponseV2 {
    error: Option<SubmitTransactionErrorV2>,
}

enum SubmitTransactionErrorV2 {
    NonceLTCommitted,
    BaseFeePerGasTooLow,
    MempoolIsFull,
    TransactionVersionTooOld,
    Other,
}

#### `transaction/v2`

##### Request

Unchanged.

##### Response

struct TransactionResponseV2 {
    transaction: Option<TransactionV1ToV2>,
    receipt: Option<ReceiptV1ToV2>,
    block_hash: Option<CryptoHash>,
    position: Option<u32>,
}

// VxToVy is distinct from VxOrVy since, in the future, VxToVy can be
// extended to cover a wider range of versions without enumerating
// every single version in the range.

enum TransactionV1ToV2 {
    V1(TransactionV1),
    V2(TransactionV2),
}

enum ReceiptV1ToV2 {
    V1(ReceiptV1),
    V2(ReceiptV2),
}

#### `receipt/v2`

##### Request

Unchanged.

##### Response

struct ReceiptResponseV2 {
    transaction_hash: CryptoHash,
    receipt: Option<ReceiptV1ToV2>,
    block_hash: Option<CryptoHash>,
    position: Option<u32>,
}

#### `block/v2`

##### Request

Unchanged.

##### Response

struct BlockResponseV2 {
    block: Option<BlockV1ToV2>,
}

#### `view/v2`

##### Request

Unchanged.

##### Response

struct ViewResponseV2 {
    command_receipt: CommandReceiptV1ToV2,
}

#### `state/v2`

A new version of the state RPC is added which responds with an Enum, with one variant of the Enum representing an OK response, and the other representing Error response.

The Error variant introduces a way that calls to `state/v2` can fail, namely, if the `StateRequest` requests a key that is "too long", and therefore will use up more of the Fullnode's resources to get from a Storage Trie than the Fullnode administrator is willing to allow.

Fullnode implementations are free to decide what counts as a Storage Key that is too long.

##### Request

Unchanged.

##### Response

enum StateResponseV2 {
    OK {
        accounts: HashMap<PublicAddress, Account>,
        storage_tuples: HashMap<PublicAddress, HashMap<Vec<u8>, Vec<u8>>>,
        block_hash: CryptoHash,
    },
    Error {
        error: RequestedStorageKeyIsTooLongError,   
    },
}

struct RequestedStorageKeyIsTooLongError;