lp_rpc.proto

syntax = "proto3";

package net;

// RPC calls implemented by the orchestrator
service Orchestrator {

  // Called by the broadcaster to request transcoder info from an orchestrator.
  rpc GetOrchestrator(OrchestratorRequest) returns (OrchestratorInfo);
  rpc Ping(PingPong) returns (PingPong);
}

service Transcoder {

  // Called by the transcoder to register to an orchestrator. The orchestrator
  // notifies registered transcoders of segments as they come in.
  rpc RegisterTranscoder(RegisterRequest) returns (stream NotifySegment);
}

message PingPong {
  // Implementation defined
  bytes value = 1;

}


// This request is sent by the broadcaster in `GetTranscoder` to request
// information on which transcoder to use.
message OrchestratorRequest {

  // Ethereum address of the broadcaster
  bytes address = 1;

  // Broadcaster's signature over its address
  bytes sig   = 2;
}

/*
  OSInfo needed to negotiate storages that will be used.
  It carries info needed to write to the storage.
*/
message OSInfo {

  enum StorageType {
    DIRECT     = 0;
    S3         = 1;
    GOOGLE     = 2;
  }

  // Storage type: direct, s3, ipfs.
  StorageType storageType = 1;

  S3OSInfo s3info = 16;
}

message S3OSInfo {

  // Host to use to connect to S3
  string host = 1;

  // Key (prefix) to use when uploading the object.
  string key = 2;

  // POST policy that S3 owner node creates to give write access to other node.
  string policy = 3;

  // Signature for POST policy.
  string signature = 4;

  // Needed for POST policy.
  string credential = 5;

  // Needed for POST policy.
  string xAmzDate = 6;
}

// PriceInfo conveys pricing info for transcoding services
message PriceInfo {
  // price in wei
  int64 pricePerUnit = 1;

  // Pixels covered in the price
  // Set price to 1 wei and pixelsPerUnit > 1 to have a smaller price granularity per pixel than 1 wei
  int64 pixelsPerUnit = 2;
}

// The orchestrator sends this in response to `GetOrchestrator`, containing
// miscellaneous data related to the job.
message OrchestratorInfo {

  // URI of the transcoder to use for submitting segments.
  string transcoder  = 1;

  // Parameters for probabilistic micropayment tickets
  TicketParams ticket_params = 2;

  // Price Info containing the price per pixel to transcode
  PriceInfo price_info = 3;

  // ETH address that should sign transcoded results
  bytes address = 4;

  // Orchestrator returns info about own input object storage, if it wants it to be used.
  repeated OSInfo storage = 32;
}

// Data included by the broadcaster when submitting a segment for transcoding.
message SegData {

  // Manifest ID this segment belongs to
  bytes manifestId = 1;

  // Sequence number of the segment to be transcoded
  int64 seq  = 2;

  // Hash of the segment data to be transcoded
  bytes hash = 3;

  // Transcoding profiles to use
  bytes profiles = 4;

  // Broadcaster signature for the segment. Corresponds to:
  // broadcaster.sign(manifestId | seqNo | dataHash | profiles)
  bytes sig  = 5;

  // Broadcaster's preferred storage medium(s)
  // XXX should we include this in a sig somewhere until certs are authenticated?
  repeated OSInfo storage = 32;

  // Transcoding profiles to use. Supersedes `profiles` field
  // Deprecated by `fullProfiles2` but may still be used for mpegts formats
  repeated VideoProfile fullProfiles = 33;

  // Transcoding profiles to use. Supersedes `fullProfiles` field
  repeated VideoProfile fullProfiles2 = 34;
}

message VideoProfile {
  // Name of VideoProfile
  string name = 16;

  // Width of VideoProfile
  int32 width = 17;

  // Height of VideoProfile
  int32 height = 18;

  // Bitrate of VideoProfile
  int32 bitrate =19;

  // FPS of VideoProfile
  uint32 fps = 20;

  // Desired output format
  enum Format {
    MPEGTS     = 0;
    MP4        = 1;
  }
  Format format = 21;
}

// Individual transcoded segment data.
message TranscodedSegmentData {

    // URL where the transcoded data can be downloaded from.
    string url = 1;

    // Amount of pixels processed (output pixels)
    int64 pixels = 2;
}

// A set of transcoded segments following the profiles specified in the job.
message TranscodeData {

    // Transcoded data, in the order specified in the job options
    repeated TranscodedSegmentData segments = 1;

    // Signature of the hash of the concatenated hashes
    bytes sig = 2;
}

// Response that a transcoder sends after transcoding a segment.
message TranscodeResult {

    // Sequence number of the transcoded results.
    int64 seq = 1;

    // Result of transcoding can be an error, or successful with more info
    oneof result {
        string error = 2;
        TranscodeData data = 3;
    }

    // Used to notify a broadcaster of updated orchestrator information 
    OrchestratorInfo info = 16;
}

// Sent by the transcoder to register itself to the orchestrator.
message RegisterRequest {

    // Shared secret for auth
    string secret = 1;

    // Transcoder capacity 
    int64 capacity = 2;
}

// Sent by the orchestrator to the transcoder
message NotifySegment {

    // URL of the segment to transcode.
    string url      = 1;

    // Job the segment belongs to.
    string job      = 2;

    // ID for this particular transcoding task.
    int64 taskId   = 16;

    // Set of profiles to transcode this segment into.
    bytes profiles = 17;

    // Transcoding profiles to use. Supersedes `profiles` field

    repeated VideoProfile fullProfiles = 33;
}

// Required parameters for probabilistic micropayment tickets
message TicketParams {
  // ETH address of the recipient
  bytes recipient = 1;

  // Pay out (in Wei) to the recipient if the ticket wins
  bytes face_value = 2;

  // Probability that the ticket wins
  bytes win_prob = 3;

  // 32 byte keccak-256 hash commitment to a random number provided
  // by the recipient
  bytes recipient_rand_hash = 4;

  // Value generated by recipient that the recipient can use
  // to derive the random number corresponding to the recipient's hash commitment
  bytes seed = 5;

  // Block number at which the current set of advertised TicketParams is no longer valid
  bytes expiration_block = 6;

  // Expected ticket expiration params
  TicketExpirationParams expiration_params = 7;
}

// Sender Params (nonces and signatures) 
message TicketSenderParams {
  // Monotonically increasing counter that makes the ticket
  // unique relative to a particular hash commitment to a recipient's random number
  uint32 sender_nonce = 1;

  // Sender signature over the ticket
  bytes sig = 2;
}

// Ticket params for expiration related validation
message TicketExpirationParams {
  // Round during which tickets are created
  int64 creation_round = 1;

  // Block hash associated with creation_round
  bytes creation_round_block_hash = 2;
}

// Payment for transcoding video segments
// A payment can constitute of multiple tickets
// A broadcaster might need to send multiple tickets to top up his credit with an Orchestrator
message Payment {
  // Probabilistic micropayment ticket parameters
  // These remain the same even when sending multiple tickets
  TicketParams ticket_params = 1;

  // ETH address of the sender
  bytes sender = 2;

  // Ticket params for expiration related validation
  TicketExpirationParams expiration_params = 3;
 
  repeated TicketSenderParams ticket_sender_params = 4;

  // O's last known price
  PriceInfo expected_price = 5;
}