Protocol Documentation
Table of Contents
relay/relay.proto
ChunkRequest
A request for chunks within a specific blob. Requests are fulfilled in all-or-nothing fashion. If any of the requested chunks are not found or are unable to be fetched, the entire request will fail.
| Field | Type | Label | Description |
|---|---|---|---|
| by_index | ChunkRequestByIndex | Request chunks by their individual indices. | |
| by_range | ChunkRequestByRange | Request chunks by a range of indices. |
ChunkRequestByIndex
A request for chunks within a specific blob. Each chunk is requested individually by its index.
| Field | Type | Label | Description |
|---|---|---|---|
| blob_key | bytes | The blob key. | |
| chunk_indices | uint32 | repeated | The index of the chunk within the blob. |
ChunkRequestByRange
A request for chunks within a specific blob. Each chunk is requested a range of indices.
| Field | Type | Label | Description |
|---|---|---|---|
| blob_key | bytes | The blob key. | |
| start_index | uint32 | The first index to start fetching chunks from. | |
| end_index | uint32 | One past the last index to fetch chunks from. Similar semantics to golang slices. |
GetBlobReply
The reply to a GetBlobs request.
| Field | Type | Label | Description |
|---|---|---|---|
| blob | bytes | The blob requested. |
GetBlobRequest
A request to fetch one or more blobs.
| Field | Type | Label | Description |
|---|---|---|---|
| blob_key | bytes | The key of the blob to fetch. |
GetChunksReply
The reply to a GetChunks request.
| Field | Type | Label | Description |
|---|---|---|---|
| data | bytes | repeated | The chunks requested. The order of these chunks will be the same as the order of the requested chunks. data is the raw data of the bundle (i.e. serialized byte array of the frames) |
GetChunksRequest
Request chunks from blobs stored by this relay.
| Field | Type | Label | Description |
|---|---|---|---|
| chunk_requests | ChunkRequest | repeated | The chunk requests. Chunks are returned in the same order as they are requested. |
| operator_id | bytes | If this is an authenticated request, this should hold the ID of the operator. If this is an unauthenticated request, this field should be empty. Relays may choose to reject unauthenticated requests. | |
| timestamp | uint32 | Timestamp of the request in seconds since the Unix epoch. If too far out of sync with the server's clock, request may be rejected. | |
| operator_signature | bytes | If this is an authenticated request, this field will hold a BLS signature by the requester on the hash of this request. Relays may choose to reject unauthenticated requests. |
The following describes the schema for computing the hash of this request This algorithm is implemented in golang using relay.auth.HashGetChunksRequest().
All integers are encoded as unsigned 4 byte big endian values.
Perform a keccak256 hash on the following data in the following order: 1. the length of the operator ID in bytes 2. the operator id 3. the number of chunk requests 4. for each chunk request: a. if the chunk request is a request by index: i. a one byte ASCII representation of the character "i" (aka Ox69) ii. the length blob key in bytes iii. the blob key iv. the start index v. the end index b. if the chunk request is a request by range: i. a one byte ASCII representation of the character "r" (aka Ox72) ii. the length of the blob key in bytes iii. the blob key iv. each requested chunk index, in order 5. the timestamp (seconds since the Unix epoch encoded as a 4 byte big endian value) |
Relay
Relay is a service that provides access to public relay functionality.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| GetBlob | GetBlobRequest | GetBlobReply | GetBlob retrieves a blob stored by the relay. |
| GetChunks | GetChunksRequest | GetChunksReply | GetChunks retrieves chunks from blobs stored by the relay. |