network-api/proto/orchestrator.proto

// Copyright (c) 2024 Nexus. All rights reserved.
//
// If you use this protocol to communicate with Nexus's servers,
// you must agree to the Terms of Service: https://nexus.xyz/tos

syntax = "proto3";

package nexus.orchestrator;

service Orchestrator {
  // Request a proof for a program.
  rpc RequestProof(ProofRequest) returns (ProofResponse) {}

  // Compile a Rust program to an ELF binary for use by clients that don't
  // support compiling programs themselves.
  rpc Compile(CompileRequest) returns (CompileResponse) {}

  // Register a supply node with the network of compute governed by the
  // orchestrator.
  rpc AddProver(stream ProverRequest) returns (stream ProverResponse) {}
}

message ProofRequest {
  CompiledProgram program = 1;

  VMProgramInput input = 2;

  // Step of the trace to start the proof, inclusive.
  //
  // If missing, proving starts at the beginning of the trace.
  optional int32 step_to_start = 3;

  // Number of steps for this proof request.
  //
  // If zero, proving is skipped. If missing, all steps are proved.
  optional int32 steps_to_prove = 4;
}

message ProofResponse {
  Proof proof = 1;
}

// A message that always represents a program runnable on the Nexus VM.
message CompiledProgram {
  oneof program {
    // ELF binary containing a program to be proved, expressed in the RV32I ISA.
    bytes rv32i_elf_bytes = 1;
  }
}

message VMProgramInput {
  oneof input {
    // Input expressed as raw bytes to be read as-is off of the input tape.
    bytes raw_bytes = 1;
  }
}

message Proof {
  oneof proof {
    bytes nova_bytes = 1;
  }
}

message ProgramSource {
  // The source code to be compiled. There will be a variety of languages and
  // ways to express everything a program needs for compilation (dependencies,
  // multiple files, etc.) as our scope expands.
  oneof source {
    // Option to use when the program in question can be expressed as a single
    // rust file (i.e., a program written in the playground).
    string rust_single_file = 1;
  }
}

message CompileRequest {
  ProgramSource source = 1;
}

message CompileResponse {
  CompiledProgram program = 1;
}

message Progress {
  // Completion status expressed as a number between zero and one,
  // inclusive.
  float completed_fraction = 1;

  // The total size of the execution trace in steps.
  int32 steps_in_trace = 2;

  // The number of steps of the execution trace to be proven.
  int32 steps_to_prove = 3;

  // The number of steps proven so far.
  int32 steps_proven = 4;
}

// Streamed messages sent to the orchestrator to keep it updated with the
// prover's status.
message ProverRequest {
  oneof contents {
    // Details about this supply node for use by the orchestrator.
    ProverRequestRegistration registration = 1;

    // A completed proof.
    Proof proof = 2;

    // Periodic progress update for the current proof.
    Progress progress = 3;

    // Periodic liveness indicator when no proof is being computed.
    Heartbeat heartbeat = 4;
  }
}

enum ProverType {
  // Experimental new prover types should leave the prover type unspecified.
  PROVER_TYPE_UNSPECIFIED = 0;

  // The default prover type, used for volunteered compute resources.
  PROVER_TYPE_VOLUNTEER = 1;

  // Provers running on public continuous integration.
  // May restrict the types of programs that can be assigned.
  PROVER_TYPE_CI = 2;
}

// Metadata that helps the orchestrator schedule work to the requesting compute
// supplier.
message ProverRequestRegistration {
  // What type of prover this is.
  ProverType prover_type = 1;

  // A unique identifier for this prover, generated by the prover.
  //
  // Distict provers must not share an identifier; do not use a constant value.
  string prover_id = 2;

  // The number of proof cycles that this prover expects to compute
  // over the course of one second. Proof cycles are proof steps times k.
  optional double estimated_proof_cycles_hertz = 3;
}

message ProverResponse {
  // Forward the literal request for now
  ProofRequest to_prove = 1;
}

message Heartbeat {
}