diff --git a/specs/src/consensus.md b/specs/src/consensus.md index 69dc17f136..fa708ce95d 100644 --- a/specs/src/consensus.md +++ b/specs/src/consensus.md @@ -32,6 +32,7 @@ | `SHARE_INFO_BYTES` | `uint64` | `1` | `byte` | The number of bytes used for [share](data_structures.md#share) information | | `SHARE_RESERVED_BYTES` | `uint64` | `4` | `byte` | The number of bytes used to store the index of the first transaction in a transaction share. Must be able to represent any integer up to and including `SHARE_SIZE - 1`. | | `SHARE_SIZE` | `uint64` | `512` | `byte` | Size of transaction and blob [shares](data_structures.md#share), in bytes. | +| `SignerSize` | `int` | `20` | `byte` | The number of bytes used to store the signer in a [share](data_structures.md#share). | | `STATE_SUBTREE_RESERVED_BYTES` | `uint64` | `1` | `byte` | Number of bytes reserved to identify state subtrees. | | `UNBONDING_DURATION` | `uint32` | | `block` | Duration, in blocks, for unbonding a validator or delegation. | | `v1.Version` | `uint64` | `1` | | First version of the application. Breaking changes (hard forks) must update this parameter. | diff --git a/specs/src/figures/first_share_with_signer.dot b/specs/src/figures/first_share_with_signer.dot new file mode 100644 index 0000000000..d22e7eff1e --- /dev/null +++ b/specs/src/figures/first_share_with_signer.dot @@ -0,0 +1,25 @@ +digraph G { + node [shape = record, penwidth = 0]; + + share [label=< + + + + + + + + + + + + + + + + + + +
0129303454512
namespace versionnamespace idinfo bytesequence lengthsignerblob1
+ >]; +} diff --git a/specs/src/figures/first_share_with_signer.svg b/specs/src/figures/first_share_with_signer.svg new file mode 100644 index 0000000000..71dfe3d8e3 --- /dev/null +++ b/specs/src/figures/first_share_with_signer.svg @@ -0,0 +1,31 @@ + + + +G + + + +share + +0 +1 +29 +30 +34 +54 +512 + +namespace version + +namespace id + +info byte + +sequence length + +signer + +blob1 + + + \ No newline at end of file diff --git a/specs/src/shares.md b/specs/src/shares.md index ce84a8950a..59ed91c9f3 100644 --- a/specs/src/shares.md +++ b/specs/src/shares.md @@ -23,6 +23,12 @@ User submitted transactions are split into shares (see [share splitting](#share- ## Share Format +### Share Version + +The share version is a 7-bit big-endian unsigned integer that is used to indicate the version of the [share format](#share-format). A new share version MUST be introduced if the share format changes in a way that is not backwards compatible. There are two share versions [share version 0](#share-version-0) and [share version 1](#share-version-1). + +### Share Version 0 + Every share has a fixed size [`SHARE_SIZE`](./consensus.md#constants). The share format below is consistent for all shares: - The first [`NAMESPACE_VERSION_SIZE`](./consensus.md#constants) bytes of a share's raw data is the namespace version of that share (denoted by "namespace version" in the figure below). @@ -44,9 +50,17 @@ Continuation share in a sequence: Since raw data that exceeds [`SHARE_SIZE`](./consensus.md#constants)`-`[`NAMESPACE_SIZE`](./consensus.md#constants)`-`[`SHARE_INFO_BYTES`](./consensus.md#constants) `-` [`SEQUENCE_BYTES`](./consensus.md#constants) bytes will span more than one share, developers MAY choose to encode additional metadata in their raw blob data prior to inclusion in a Celestia block. For example, Celestia transaction shares encode additional metadata in the form of "reserved bytes". -### Share Version +### Share Version 1 + +Share version 1 is similar to share version 0 with the addition of a `signer` field. The signer is located after the sequence length in the first share. The signer is [`SIGNER_SIZE`](./consensus.md#constants) bytes. + +First share in a sequence with signer: + +![figure 3: first share with signer](./figures/first_share_with_signer.svg) + +Continuation share in a sequence: -The share version is a 7-bit big-endian unsigned integer that is used to indicate the version of the [share format](#share-format). The only supported share version is `0`. A new share version MUST be introduced if the share format changes in a way that is not backwards compatible. +![figure 4: share continuation](./figures/share_continuation.svg) ## Transaction Shares