You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: versioned_docs/version-2.0.0/concepts/serialization/structures.md
+82-43
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
## Account {#serialization-standard-account}
4
4
5
-
An Account is a structure that represented a user on a legacy Casper network. Alongside the Condor protocol release, `Accounts` were replaced with `AddressableEntities` of the type `Account`. The account structure consists of the following fields:
5
+
An Account is a structure that represented a user on a legacy Casper network. Alongside the Casper 2.0 protocol release, `Accounts` were replaced with `AddressableEntities` of the type `Account`. The account structure consists of the following fields:
6
6
7
7
-[`account_hash`](./types.md#account-hash)
8
8
@@ -17,53 +17,50 @@ An Account is a structure that represented a user on a legacy Casper network. Al
17
17
## AddressableEntity {#addressable-entity}
18
18
19
19
An Addressable Entity is a structure that represents an entity on a Casper network. The addressable entity consists of the following fields:
20
-
21
20
-[`package_hash`](./types.md#package-hash)
22
21
23
22
-[`byte_code_hash`](./types.md#byte-code-hash)
24
23
25
-
-[`entry_points`](./types.md#entrypoints)
26
-
27
24
-[`protocol_version`](./types.md#protocolversion)
28
25
29
-
-`main_purse`: The entity's main purse `URef`. You may find information on `URef` serialization [here](./primitives.md#clvalue-uref).
26
+
-[`main_purse`]: The entity's main purse `URef`. You may find information on `URef` serialization [here](./primitives.md#clvalue-uref).
A block is the core component of the Casper linear blockchain, used in two contexts:
42
38
43
39
1. A data structure containing a collection of transactions. Blocks form the primary structure of the blockchain.
44
40
2. A message that is exchanged between nodes containing the data structure as explained in (1).
45
41
46
-
Each block has a globally unique ID, achieved by hashing the contents of the block.
47
-
48
-
Each block points to its parent. An exception is the first block, which has no parent.
49
-
50
-
A block is structurally defined as follows:
51
-
52
-
-`hash`: A hash over the header of the block.
53
-
-`header`: The header of the block that contains information about the contents of the block with additional metadata.
54
-
-`body`: The block's body contains the proposer of the block and hashes of deploys and transfers contained within it.
42
+
The block is a polymorphic structure that assumes one of the well-defined variants:
43
+
*`V1` which type is `BlockV1` (it has a binary `prefix` of 0)
44
+
*`V2` which type is `BlockV2` (it has a binary `prefix` of 1)
55
45
56
-
Further, a block may consist of one of the following types:
46
+
To byte-serialize a `Block` you first need to serialize it's binary prefix and then write the bytes of the byte-serialized representation of it's variant.
57
47
58
-
-`Version1`: A legacy block created prior to the Condor upgrade.
48
+
## BlockV1 {#block-v1}
59
49
60
-
-`Version2`: A modern block.
50
+
This type:
51
+
* encapsulates block data that used to be produced in versions of the nodes prior to 2.0.
52
+
* represents a historical block that was produced prior to 2.0
53
+
Each block:
54
+
* has a globally unique ID, achieved by hashing the contents of the block.
55
+
* points to its parent. An exception is the first block, which has no parent.
61
56
62
-
### BlockHash {#block-hash}
57
+
A block is structurally defined as follows:
63
58
64
-
The block hash is a `Digest` over the contents of the block Header. The `BlockHash` serializes as the byte representation of the hash itself.
59
+
-`hash`: A hash over the header of the block. It's type is `BlockHash`
60
+
-`header`: The header of the block that contains information about the contents of the block with additional metadata. It's type is `BlockHeaderV1`.
61
+
-`body`: The block's body contains the proposer of the block and hashes of deploys and transfers contained within it. It's type is `BlockBodyV1`.
65
62
66
-
### BlockHeader {#block-header}
63
+
### BlockHeaderV1 {#block-header-v1}
67
64
68
65
The header portion of a block, structurally, is defined as follows:
69
66
@@ -72,15 +69,13 @@ The header portion of a block, structurally, is defined as follows:
72
69
-`body_hash` the hash of the block body. It serializes to the byte representation of the body hash. The serialized buffer of the `body_hash` is 32 bytes long.
73
70
-`random_bit` is a boolean needed for initializing a future era. It is serialized as a single byte; true maps to 1, while false maps to 0.
74
71
-`accumulated_seed` is a seed needed for initializing a future era. It serializes to the byte representation of the parent Hash. The serialized buffer of the `accumulated_hash` is 32 bytes long.
75
-
-`era_end` contains equivocation and reward information to be included in the terminal finalized block. It is an optional field. Thus if the field is set as `None`, it serializes to _0_. The serialization of the other case is described in the EraEnd.
72
+
-`era_end` contains equivocation and reward information to be included in the terminal finalized block. It is an optional field. Thus if the field is set as `None`, it serializes to _0_. The serialization of the other case is described in the `EraEndV1`.
76
73
-`timestamp` The timestamp from when the block was proposed. It serializes as a single `u64` value. The serialization of a `u64` value is described in the CLValues section.
77
74
-`era_id` Era ID in which this block was created. It serializes as a single `u64` value.
78
75
-`height` The height of this block, i.e., the number of ancestors. It serializes as a single `u64` value.
79
76
-`protocol_version` The version of the Casper network when this block was proposed. It is 3-element tuple containing `u32` values. It serializes as a buffer containing the three `u32` serialized values. Refer to the CLValues section on how `u32` values are serialized.
80
77
81
-
Both `BlockHeaderV1` and `BlockHeaderV2` serialize in the same way.
82
-
83
-
### EraEndV1 {#eraendV1}
78
+
#### EraEndV1 {#eraendV1}
84
79
85
80
`EraEndV1` as represented within the block header, is a struct containing two fields.
86
81
@@ -102,21 +97,9 @@ When serializing the overarching struct of `EraEndV1`, we first allocate a buffe
102
97
103
98
Note that `EraEndV1` is an optional field. Thus the above scheme only applies if there is an `EraEndV1`; if there is no era end, the field simply serializes to _0_.
104
99
105
-
### EraEndV2 {#eraendV2}
106
-
107
-
`EraEndV1` as represented within the block header, is a struct containing four fields.
108
-
109
-
-`equivocators`: A vector of `PublicKey` listing equivocators for the era.
110
-
-`inactive_validators`: A list of inactive validators for the era.
111
-
-`next_era_validator_weights`: A map of validators and their weights for the era to follow.
112
-
-`rewards`: A Binary Tree Map of `PublicKey` and `u64`.
113
-
-`next_era_gas_price`: The next era's gas price as a `u8`.
114
-
115
-
Note that `EraEndV2` is an optional field. Thus the above scheme only applies if there is an `EraEndV2`; if there is no era end, the field simply serializes to _0_.
116
-
117
100
### BlockBodyV1 {#blockbodyV1}
118
101
119
-
The body portion of a block, prior to the Condor upgrade, is structurally defined as:
102
+
The body portion of a block, prior to the Casper 2.0 upgrade, is structurally defined as:
120
103
121
104
-`proposer`: The PublicKey which proposed this block.
122
105
-`deploy_hashes`: Is a vector of hex-encoded hashes identifying Deploys included in this block.
@@ -128,6 +111,52 @@ When we serialize the `BlockBodyV1`, we create a buffer that contains the serial
128
111
-`deploy_hashes` serializes to the byte representation of all the deploy_hashes within the block header. Its length is `32 * n`, where n denotes the number of deploy hashes present within the body.
129
112
-`transfer_hashes` serializes to the byte representation of all the deploy_hashes within the block header. Its length is `32 * n`, where n denotes the number of transfers present within the body.
130
113
114
+
## BlockV2 {#block-v2}
115
+
116
+
This type represents a contemporary block that is produced by the network. A block is the core component of the Casper linear blockchain, used in two contexts:
117
+
1. A data structure containing a collection of transactions. Blocks form the primary structure of the blockchain.
118
+
2. A message that is exchanged between nodes containing the data structure as explained in (1).
119
+
120
+
Each block has a globally unique ID, achieved by hashing the contents of the block.
121
+
122
+
Each block points to its parent. An exception is the first block, which has no parent.
123
+
124
+
A block is structurally defined as follows:
125
+
126
+
-`hash`: A hash over the header of the block. It's type is `BlockHash`
127
+
-`header`: The header of the block that contains information about the contents of the block with additional metadata. It's type is `BlockHeaderV2`.
128
+
-`body`: The block's body contains the proposer of the block and hashes of deploys and transfers contained within it. It's type is `BlockBodyV2`.
129
+
130
+
### BlockHeaderV2 {#block-header-v2}
131
+
132
+
The header portion of a block, structurally, is defined as follows:
133
+
134
+
-`parent_hash` is the hash of the parent block. It serializes to the byte representation of the parent hash. The serialized buffer of the `parent_hash` is 32 bytes long.
135
+
-`state_root_hash` is the global state root hash produced by executing this block's body. It serializes to the byte representation of the `state root hash`. The serialized buffer of the `state_root_hash` is 32 bytes long.
136
+
-`body_hash` the hash of the block body. It serializes to the byte representation of the body hash. The serialized buffer of the `body_hash` is 32 bytes long.
137
+
-`random_bit` is a boolean needed for initializing a future era. It is serialized as a single byte; true maps to 1, while false maps to 0.
138
+
-`accumulated_seed` is a seed needed for initializing a future era. It serializes to the byte representation of the parent Hash. The serialized buffer of the `accumulated_hash` is 32 bytes long.
139
+
-`era_end` contains equivocation and reward information to be included in the terminal finalized block. It is an optional field. Thus if the field is set as `None`, it serializes to _0_. The serialization of the other case is described in the `EraEndV2`.
140
+
-`timestamp` The timestamp from when the block was proposed. It serializes as a single `u64` value. The serialization of a `u64` value is described in the CLValues section.
141
+
-`era_id` Era ID in which this block was created. It serializes as a single `u64` value.
142
+
-`height` The height of this block, i.e., the number of ancestors. It serializes as a single `u64` value.
143
+
-`protocol_version` The version of the Casper network when this block was proposed. It is 3-element tuple containing `u32` values. It serializes as a buffer containing the three `u32` serialized values. Refer to the CLValues section on how `u32` values are serialized.
144
+
-`proposer` public key of the proposer of the block. It's type is `PublicKey`
145
+
-`current_gas_price` gas price of the block. It is an unsigned 8 bit number.
146
+
-`last_switch_block_hash` it is an optional block hash pointing to the last switch block. It's type is `BlockHash`, but since it's optional, rules of serializing (optional fields)[./primitives.md#clvalue-option] apply.
147
+
148
+
### EraEndV2 {#eraendV2}
149
+
150
+
`EraEndV2` as represented within the block header, is a struct containing four fields.
151
+
152
+
-`equivocators`: A vector of `PublicKey` listing equivocators for the era.
153
+
-`inactive_validators`: A list of inactive validators for the era.
154
+
-`next_era_validator_weights`: A map of validators and their weights for the era to follow.
155
+
-`rewards`: A Binary Tree Map of `PublicKey` and `u64`.
156
+
-`next_era_gas_price`: The next era's gas price as a `u8`.
157
+
158
+
Note that `EraEndV2` is an optional field. Thus the above scheme only applies if there is an `EraEndV2`; if there is no era end, the field simply serializes to _0_.
159
+
131
160
### BlockBodyV2 {blockbodyv2}
132
161
133
162
A modern block is structurally defined as:
@@ -136,6 +165,20 @@ A modern block is structurally defined as:
136
165
137
166
-[`rewarded_signatures`](./types.md#rewarded-signatures): A list of identifiers for finality signatures for a particular past block. It serializes as a vector of `SingleBlockRewardedSignatures` which describes signatures for a single ancestor block. The first entry represents the signatures for the parent block, the second for the parent of the parent, and so on.
138
167
168
+
169
+
## BlockHash {#block-hash}
170
+
171
+
The block hash is a `Digest` over the contents of the block Header. The `BlockHash` serializes as the byte representation of the hash itself.
172
+
173
+
174
+
## ByteCodeAddr {#byte-code-addr}
175
+
176
+
An address for ByteCode records stored in global state. Comes in one of three variants:
177
+
-`Empty`. It serializes as a `u8` tag of `0`.
178
+
-`V1CasperWasm`. It serializes as a `u8` tag of `1` followed by 32 bytes interpreted as hex-encoded address.
179
+
-`V2CasperWasm`. It serializes as a `u8` tag of `2` followed by 32 bytes interpreted as hex-encoded address.
180
+
181
+
139
182
## Contract {#contract}
140
183
141
184
A contract struct containing the following fields:
@@ -406,10 +449,6 @@ The scheduling mode of a transaction, serialized as a [`u8`](./primitives.md#clv
406
449
407
450
-`Standard` serializes as a `0`.
408
451
409
-
-`FutureEra` serializes as a `1` followed by a future [`era_id`](./types.md#eraid).
410
-
411
-
-`FutureTimestamp` serializes as a `2` followed by a future [`timestamp`](./types.md#timestamp).
Copy file name to clipboardExpand all lines: versioned_docs/version-2.0.0/concepts/serialization/types.md
+9-6
Original file line number
Diff line number
Diff line change
@@ -214,7 +214,7 @@ Hex-encoded bytes serialized as a `u32` value describing the length of the bytes
214
214
215
215
## ByteCodeKind
216
216
217
-
The type of byte code, serialized as a single `u8` value. A `0` indicates empty byte code, while a `1` indicates a `V1CasperWasm` to be executed with the first version of the Casper execution engine.
217
+
The type of byte code, serialized as a single `u8` value. A `0` indicates empty byte code. `1` indicates a `V1CasperWasm` to be executed with the first version of the Casper execution engine.`2` indicates a `V2CasperWasm` to be executed with the first version of the Casper execution engine
218
218
219
219
## Caller {#caller}
220
220
@@ -252,6 +252,9 @@ ChainspecRegistry is a unique key variant which contains a mapping of file names
252
252
253
253
The checksum registry. It serializes as a `BTreeMap` where the first 4 bytes represent a `u32` value describing the number of checksum names as strings and [digests](#digest) held within. The remainder consists of a repeating pattern of serialized strings and then digests of the length dictated by the first four bytes.
254
254
255
+
## ContractRuntimeTag {#contract-runtime-tag}
256
+
A tag for the contracts runtime tag, serialized as a single `u8` tag of 0 for `VmCasperV1`, 1 for `VmCasperV2`.
257
+
255
258
## Delegator {#delegator}
256
259
257
260
Represents a party delegating their stake to a validator (or "delegatee"). The structure consists of the following fields:
@@ -368,7 +371,7 @@ An `enum` specifying who pays for the invocation and execution of an entry point
368
371
369
372
-`Caller`: Serializes as a 0 and indicates that the caller must cover the cost.
370
373
371
-
-`SelfOnly`: Serializes as a 1 and indicates that the contract will pay the cost to execute itself, but no subsequent invoked contracts.
374
+
-`DirectInvocationOnly`: Serializes as a 1 and indicates that the contract will pay the cost to execute itself, but no subsequent invoked contracts.
372
375
373
376
-`SelfOnward`: Serializes as a 2 and indicates that the contract will pay for executing itself and any subsequent invocations.
374
377
@@ -378,9 +381,9 @@ The context of method execution. It serializes as one of the following:
378
381
379
382
-`Caller`: Serializes as a single `u8`, `0b00000000`
380
383
381
-
-`Called`: Serializes as a single `u8`, `0b00000001`
384
+
-`DirectInvocationOnly`: Serializes as a single `u8`, `0b00000001`
382
385
383
-
-`Factory`: Serializes as a single `u8`, `0b10000000`
386
+
-`SelfOnward`: Serializes as a single `u8`, `0b10000000`
384
387
385
388
## EntrypointV2
386
389
@@ -770,9 +773,9 @@ Entity types for system contracts, serialized as a single `u8` tag identifying t
0 commit comments