lbry.go/blobex/blobex.proto

syntax = "proto3";

package blobex;

/*

## Errors
- invalid request
- banned for nonpayment
- banned for uploading unwanted blobs
- blob not wanted
- blob not available
- not accepting blobs

## Considerations

- there are two requests to upload a blob. how to reduce that to one?
  - UploadCheck checks for many hashes at once. if you're just uploading one or a few, just do it and handle the error

- how to avoid receiving the whole blob and then determining the blob is not wanted? may not ever be possible

- is avail check necessary? just request what you want for download
  - maybe you want to check multiple blobs at once?

- how to check for wanted blobs from stream hash?

- prices should be set by hosts, since they are offering blobs for download and have the best information on prices. but request is initiated by client. how do we make sure clients are not overpaying without making them make two requests for each blob?

- should we have another request to submit proof of payment? or at least a txid?

*/

service BlobExchange {
    rpc PriceCheck(PriceCheckRequest) returns (PriceCheckResponse) {}
    rpc DownloadCheck(HashesRequest) returns (HashesResponse) {}
    rpc Download(stream DownloadRequest) returns (stream DownloadResponse) {}
    rpc UploadCheck(HashesRequest) returns (HashesResponse) {}
    rpc Upload(stream UploadRequest) returns (stream UploadResponse) {}
}

message Error {
    // should we enum the error codes?
    uint32 code = 1;
    string message = 2;
}

// how much does the host charge per kb at the moment
message PriceCheckRequest {
}
message PriceCheckResponse{
    Error error = 1;
    uint64 deweysPerKB = 2;
}

// are any of the hashs available for download, or are any of the hashes desired for upload
// NOTE: if any hashes are stream hashes, and the server has the manifest but not all the content
// blobs, the server may reply that it needs extra blobs that were not in the original request
message HashesRequest {
    repeated string hashes = 1;
}
message HashesResponse {
    Error error = 1;
    map<string, bool> hashes = 2;
}

// download the hash
message DownloadRequest {
    string hash = 1;
}
message DownloadResponse {
    Error error = 1;
    string hash = 2;
    bytes blob = 3;
    string address = 4;  // address where payment for data download should be sent
    uint64 price = 5;    // price of the data in this blob
}

// upload the hash
message UploadRequest {
    string hash = 1;
    bytes blob = 2;
}
message UploadResponse {
    Error error = 1;
    string hash = 2;
}