Skip to content

Commit

Permalink
cip-19!: introduce core messages
Browse files Browse the repository at this point in the history
  • Loading branch information
Wondertan committed Apr 21, 2024
1 parent c4cd3e8 commit 58e45e7
Showing 1 changed file with 49 additions and 20 deletions.
69 changes: 49 additions & 20 deletions cips/cip-19.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,7 +193,7 @@ Row containers are protobuf formatted using the following proto3 schema:
syntax = "proto3";
message Row {
repeated bytes shares_half = 1;
repeated Share shares_half = 1;
HalfSide half_side= 2;
enum HalfSide {
Expand All @@ -205,11 +205,10 @@ message Row {

The fields with validity rules that form Row containers are:

**SharesHalf**: A two-dimensional variable size byte array representing either left or right half of a row with each
element being a [share][shares]. Each share MUST follow [share formatting and validity][shares-format] rules. Which half
side is defined by **HalfSide** field. Its length MUST be equal to the number of Column roots in [DAH][dah] divided by
two. The opposite half is computed using Leopard GF16 Reed-Solomon erasure-coding. Afterward, the [NMT][nmt] is built
over both halves and the computed NMT root MUST be equal to the respective Row root in [DAH][dah].
**SharesHalf**: A variable size [Share](#share) array representing either left or right half of a row. Which half side
is defined by **HalfSide** field. Its length MUST be equal to the number of Column roots in [DAH][dah] divided by two.
The opposite half is computed using Leopard GF16 Reed-Solomon erasure-coding. Afterward, the [NMT][nmt] is built over
both halves and the computed NMT root MUST be equal to the respective Row root in [DAH][dah].

**HalfSide**: An enum defining which side of the row **SharesHalf** field contains. It MUST be either **LEFT** or
**RIGHT**.
Expand Down Expand Up @@ -246,28 +245,22 @@ Sample containers are protobuf formatted using the following proto3 schema:
syntax = "proto3";
message Sample {
bytes share = 1;
Share share = 1;
Proof proof = 2;
ProofType proof_type = 3;
enum ProofType {
ROW = 0;
COL = 1;
}
AxisType proof_type = 3;
}
```

The fields with validity rules that form Sample containers are:

**Share**: A variable size array representing a share contained in a sample. It MUST follow [share
formatting and validity][shares-format] rules.
**Share**: A [Share](#share) of a sample.

**Proof**: A [protobuf formated][nmt-pb] [NMT][nmt] proof of share inclusion. It MUST follow [NMT proof verification][nmt-verify]
and be verified against the respective root from the Row or Column axis in [DAH][dah]. The axis is defined by the
ProofType field.

**ProofType**: An enum defining which axis root the **Proof** field is coming from. It MUST be either **Row** or
**Column**.
[**AxisType**](#axistype): An enum defining which axis root the **Proof** field is coming from. It MUST be either **ROW** or
**COL**.

#### RowNamespaceDataID

Expand Down Expand Up @@ -303,15 +296,14 @@ RowNamespaceData containers are protobuf formatted using the following proto3 sc
syntax = "proto3";
message RowNamespaceData {
repeated bytes shares = 1;
repeated Share shares = 1;
Proof proof = 2;
}
```

The fields with validity rules that form Data containers are:

**Shares**: A two-dimensional variable size byte array representing data of a namespace in a row where each element is a
share. Each share MUST follow [share formatting and validity][shares-format] rules.
**Shares**: A variable size [Share](#share) array representing data of a namespace in a row.

**Proof**: A [protobuf formated][nmt-pb] [NMT][nmt] proof of share inclusion. It MUST follow [NMT proof verification][nmt-verify]
and be verified against the respective root from the Row root axis in [DAH][dah].
Expand All @@ -320,6 +312,43 @@ Namespace data may span over multiple rows, in which case all the data is encaps
containers. This enables parallelization of namespace data retrieval and certain [compositions](#protocol-compositions)
may get advantage of that by requesting containers of a single namespace from multiple servers simultaneously.

### Core Structures

This section is purposed for messages that do not fit into [Identifier](#share-identifiers) or [Container](#share-containers)
categories, but have to be strictly specified to be used across the categories and beyond.

#### AxisType

The [data square][square] consists of rows and columns of [shares][shares] that are committed in NMT merkle trees.
Subsequently, we have two commitments over any share in the square. AxisType helps to point to either of those in
different contexts.

```protobuf
syntax = "proto3";
enum AxisType {
ROW = 0;
COL = 1;
}
```

#### Share

[Share][shares] defines the atomic primitive of the [data square][square].

```protobuf
syntax = "proto3";
message Share {
bytes data = 1;
}
```

The fields with validity rules that form Data containers are:

**Data**: A variable size byte array representing a share. It MUST follow [share formatting and validity][shares-format]
rules.

## Protocol Compositions

This section specifies compositions of Shwap with other protocols. While Shwap is transport agnostic, there are rough
Expand Down

0 comments on commit 58e45e7

Please sign in to comment.