Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: add share version 1 to specs #3955

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+73 −2
Open

docs: add share version 1 to specs #3955

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions specs/src/consensus.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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). |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codebase verification

SignerSize is defined but not used in the codebase

The SignerSize constant in specs/src/consensus.md is currently not referenced or utilized in any other .md or .rust files. Please verify if this constant is intended for future use or if it should be removed to prevent unnecessary clutter.

🔗 Analysis chain

New constant SignerSize added

The addition of the SignerSize constant is consistent with the PR objectives to include specifications for share version 1. This constant defines the number of bytes used to store the signer in a share, which is a key feature of share version 1.

To ensure this constant is used correctly throughout the codebase, let's run a search:

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Search for uses of SignerSize in the codebase
rg --type md --type rust "SignerSize"

Length of output: 311

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it problematic that there's a different formatting i.e. SignerSize and not SIGNER_SIZE?

| `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. |
Expand Down
25 changes: 25 additions & 0 deletions specs/src/figures/first_share_with_signer.dot
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
digraph G {
node [shape = record, penwidth = 0];

share [label=<
<table border="0" cellborder="1" cellspacing="0">
<tr>
<td align="left" border="0" cellpadding="0">0</td>
<td align="left" border="0" cellpadding="0">1</td>
<td align="left" border="0" cellpadding="0">29</td>
<td align="left" border="0" cellpadding="0">30</td>
<td align="left" border="0" cellpadding="0">34</td>
<td align="left" border="0" cellpadding="0">54</td>
<td align="left" border="0" cellpadding="0">512</td>
</tr>
<tr>
<td width="8" cellpadding="4">namespace version</td>
<td width="8" cellpadding="4">namespace id</td>
<td width="1" cellpadding="4">info byte</td>
<td width="4" cellpadding="4">sequence length</td>
<td width="4" cellpadding="4">signer</td>
<td width="200" cellpadding="4">blob1</td>
</tr>
</table>
>];
}
31 changes: 31 additions & 0 deletions specs/src/figures/first_share_with_signer.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 16 additions & 2 deletions specs/src/shares.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand All @@ -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

Expand Down
Loading