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

docs(cip-19): add NamespaceRangeID along with NamespaceRangeContainer #197

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

docs(cip-19): add NamespaceRangeID along with NamespaceRangeContainer #197

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1ffad29
docs(cip-19): add NamespaceRangeID along with NamespaceRangeContainer
vgonkivs Aug 20, 2024
f36f11c
renamings
vgonkivs Aug 28, 2024
5af9ede
apply suggestion
vgonkivs Aug 29, 2024
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
43 changes: 43 additions & 0 deletions cips/cip-19.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -311,6 +311,49 @@ 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.

#### NamespaceRangeID
Copy link
Contributor

Choose a reason for hiding this comment

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

namespace range may suggest it's a range of namespaces, like 0x00000001 up to 0x00000004. Maybe just NamespaceData would be better? just dropping Row prefix from RowNamespaceData, also better showing correlation between the two?

Copy link
Member

@Wondertan Wondertan Aug 28, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

We have:
RowNamespaceData - namespace data within a row
NamespaceData - all the namespace data that can span over multiple rows

To avoid namespace confusion I propose to do:
NamespaceRange -> RangeNamespaceData - namespace data range that can span over multiple rows

Copy link
Member Author

Choose a reason for hiding this comment

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

Agree with @Wondertan. The container itself and request namings should contain Range


NamespaceRangeID: encapsulates SampleID, Namespace and identifies the continuous range of shares in the DataSquare. Formated as below:

```text
NamespaceRangeID {
SampleID;
Copy link
Contributor

Choose a reason for hiding this comment

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

what is the purpose of sample here? does it mean take Length shares from given SampleID? I think it needs better clarification below. Also why not just using EdsId + Namespace providing whole namespace from given block? Is there a usecase for a user to request his shares but eg. skipping the first and last one?

Copy link
Member Author

Choose a reason for hiding this comment

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

does it mean take Length shares from given SampleID?

Yes

Copy link
Member Author

Choose a reason for hiding this comment

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

Also why not just using EdsId + Namespace providing whole namespace from given block? Is there a usecase for a user to request his shares but eg. skipping the first and last one?

This means we will retrieve the whole eds from the requested namespace. For example, blob.GetProof needs a specific range of shares rather than the whole namespace.

Copy link
Contributor

Choose a reason for hiding this comment

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

should we then specify here what should happen if cid is pointing to shares outside of it's namespace? eg. what if the sample id is not in correct namespace or the length goes beyond the namespace?

Copy link
Contributor

Choose a reason for hiding this comment

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

also I'm not exactly sure what is the usecase here, user would need to already know the blob's position in eds and it's length in shares to even use that, however shwap itself doesn't give any of such abilities

Namespace;
Length: u16;
OmitData: bool;
Copy link
Contributor

Choose a reason for hiding this comment

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

should OmitData also be present in RowNamespaceId?

Copy link
Member

Choose a reason for hiding this comment

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

It may also be part of SampleID, i.e., one can request just the proof for the share/sample without the data itself. However, we are unaware of any use cases for the Row and Sample containers that can be requested without data. We could add that to be consistent with OmitData usage across types, but our approach is to specify and implement only what's known to be helpful in practice.

}
```

The fields with validity rules that form NamespaceRangeID are:

[SampleID](#sampleid): it MUST follow formatting and validity rules.

[**Namespace**][ns]: A fixed-size 29 bytes array representing the Namespace of interest. It MUST follow [Namespace][ns]
formatting and its validity rules.

Length: uint16 representation of the length of the range. This number MUST NOT exceed the last original share of the DataSquare.

OmitData: bool flag that specifies whether the user expects the original data along with the proof or not.

[Serialized](#serialization-for-share-identifiers) NamespaceRangeID MUST have a length of 44 bytes.

#### NamespaceRangeContainer

NamespaceRangeContainer containers encapsulate user-submitted data under [namespaces][ns] within a single or multiple
of [DataSquare][square] rows. It MAY contain [shares][shares] and [NMT][nmt] proof of share inclusion or proof only.

NamespaceRangeContainer container are protobuf formatted using the following proto3 schema:

```protobuf
syntax = "proto3";

message NamespaceRangeContainer {
vgonkivs marked this conversation as resolved.
Show resolved Hide resolved
repeated RowNamespaceData namespacedData = 1;
vgonkivs marked this conversation as resolved.
Show resolved Hide resolved
}
```

The fields with validity rules that form [RowNamespaceData](#rownamespacedata-container) container.

### Core Structures

This section is purposed for messages that do not fit into [Identifier](#share-identifiers) or [Container](#share-containers)
Expand Down