netrunner/rpcpb/rpc.proto

syntax = "proto3";

option go_package = "github.com/luxfi/netrunner;rpcpb";

package rpcpb;

import "google/api/annotations.proto";

service PingService {
  rpc Ping(PingRequest) returns (PingResponse) {
    option (google.api.http) = {
      post: "/v1/ping"
      body: "*"
    };
  }
}

message PingRequest {}

message PingResponse {
  int32 pid = 1;
}

service ControlService {
  rpc RPCVersion(RPCVersionRequest) returns (RPCVersionResponse) {
    option (google.api.http) = {
      post: "/v1/control/rpcversion"
      body: "*"
    };
  }

  rpc Start(StartRequest) returns (StartResponse) {
    option (google.api.http) = {
      post: "/v1/control/start"
      body: "*"
    };
  }

  rpc CreateBlockchains(CreateBlockchainsRequest) returns (CreateBlockchainsResponse) {
    option (google.api.http) = {
      post: "/v1/control/createblockchains"
      body: "*"
    };
  }

  rpc TransformElasticSubnets(TransformElasticSubnetsRequest) returns (TransformElasticSubnetsResponse) {
    option (google.api.http) = {
      post: "/v1/control/transformelasticsubnets"
      body: "*"
    };
  }

  rpc AddPermissionlessValidator(AddPermissionlessValidatorRequest) returns (AddPermissionlessValidatorResponse) {
    option (google.api.http) = {
      post: "/v1/control/addpermissionlessvalidator"
      body: "*"
    };
  }

  rpc RemoveSubnetValidator(RemoveSubnetValidatorRequest) returns (RemoveSubnetValidatorResponse) {
    option (google.api.http) = {
      post: "/v1/control/removesubnetvalidator"
      body: "*"
    };
  }

  rpc CreateSubnets(CreateSubnetsRequest) returns (CreateSubnetsResponse) {
    option (google.api.http) = {
      post: "/v1/control/createsubnets"
      body: "*"
    };
  }

  rpc Health(HealthRequest) returns (HealthResponse) {
    option (google.api.http) = {
      post: "/v1/control/health"
      body: "*"
    };
  }

  rpc URIs(URIsRequest) returns (URIsResponse) {
    option (google.api.http) = {
      post: "/v1/control/uris"
      body: "*"
    };
  }

  rpc WaitForHealthy(WaitForHealthyRequest) returns (WaitForHealthyResponse) {
    option (google.api.http) = {
      post: "/v1/control/waitforhealthy"
      body: "*"
    };
  }

  rpc Status(StatusRequest) returns (StatusResponse) {
    option (google.api.http) = {
      post: "/v1/control/status"
      body: "*"
    };
  }

  rpc StreamStatus(StreamStatusRequest) returns (stream StreamStatusResponse) {
    option (google.api.http) = {
      post: "/v1/control/streamstatus"
      body: "*"
    };
  }

  rpc RemoveNode(RemoveNodeRequest) returns (RemoveNodeResponse) {
    option (google.api.http) = {
      post: "/v1/control/removenode"
      body: "*"
    };
  }

  rpc AddNode(AddNodeRequest) returns (AddNodeResponse) {
    option (google.api.http) = {
      post: "/v1/control/addnode"
      body: "*"
    };
  }

  rpc RestartNode(RestartNodeRequest) returns (RestartNodeResponse) {
    option (google.api.http) = {
      post: "/v1/control/restartnode"
      body: "*"
    };
  }

  rpc PauseNode(PauseNodeRequest) returns (PauseNodeResponse) {
    option (google.api.http) = {
      post: "/v1/control/pausenode"
      body: "*"
    };
  }

  rpc ResumeNode(ResumeNodeRequest) returns (ResumeNodeResponse) {
    option (google.api.http) = {
      post: "/v1/control/resumenode"
      body: "*"
    };
  }

  rpc Stop(StopRequest) returns (StopResponse) {
    option (google.api.http) = {
      post: "/v1/control/stop"
      body: "*"
    };
  }

  rpc AttachPeer(AttachPeerRequest) returns (AttachPeerResponse) {
    option (google.api.http) = {
      post: "/v1/control/attachpeer"
      body: "*"
    };
  }

  rpc SendOutboundMessage(SendOutboundMessageRequest) returns (SendOutboundMessageResponse) {
    option (google.api.http) = {
      post: "/v1/control/sendoutboundmessage"
      body: "*"
    };
  }

  rpc SaveSnapshot(SaveSnapshotRequest) returns (SaveSnapshotResponse) {
    option (google.api.http) = {
      post: "/v1/control/savesnapshot"
      body: "*"
    };
  }

  rpc LoadSnapshot(LoadSnapshotRequest) returns (LoadSnapshotResponse) {
    option (google.api.http) = {
      post: "/v1/control/loadsnapshot"
      body: "*"
    };
  }

  rpc RemoveSnapshot(RemoveSnapshotRequest) returns (RemoveSnapshotResponse) {
    option (google.api.http) = {
      post: "/v1/control/removesnapshot"
      body: "*"
    };
  }

  rpc GetSnapshotNames(GetSnapshotNamesRequest) returns (GetSnapshotNamesResponse) {
    option (google.api.http) = {
      post: "/v1/control/getsnapshotnames"
      body: "*"
    };
  }
}

message SubnetParticipants {
  repeated string node_names = 1;
}

message ClusterInfo {
  repeated string node_names       = 1;
  map<string, NodeInfo> node_infos = 2;
  int32 pid                        = 3;
  string root_data_dir             = 4;
  bool healthy                     = 5;

  // Maps from the node ID to its attached peer infos.
  map<string, ListOfAttachedPeerInfo> attached_peer_infos = 6;

  // Set to "true" once custom blockchains are ready.
  bool custom_chains_healthy = 7;
  // The map of blockchain IDs in "ids.ID" format to its blockchain information.
  map<string, CustomChainInfo> custom_chains = 8;
  map<string, SubnetInfo> subnets          = 9;
}

message SubnetInfo {
  // If Subnet is an Elastic Subnet
  bool is_elastic = 1;

  // TXID for the elastic subnet transform
  string elastic_subnet_id = 2;

  // node validators of subnet
  SubnetParticipants subnet_participants = 3;
}

message CustomChainInfo {
  // Blockchain name given to the create blockchain TX
  // Currently used to keep a record of the VM name,
  // which is not saved anywhere and can't be recovered from VM ID
  string chain_name = 1;

  // VM ID in "ids.ID" format.
  string vm_id = 2;

  // Create subnet transaction ID -- subnet ID.
  // The subnet ID must be whitelisted by the lux node.
  string subnet_id = 3;

  // Create blockchain transaction ID -- blockchain ID>
  // The blockchain ID is used for RPC endpoints.
  string chain_id = 4;
}

message NodeInfo {
  string name                 = 1;
  string exec_path            = 2;
  string uri                  = 3;
  string id                   = 4;
  string log_dir              = 5;
  string db_dir               = 6;
  string plugin_dir           = 7;
  string whitelisted_subnets  = 8;
  bytes  config               = 9;
  bool   paused               = 10;
}

message AttachedPeerInfo {
  string id = 1;
}

message ListOfAttachedPeerInfo {
  repeated AttachedPeerInfo peers = 1;
}

message StartRequest {
  string exec_path                    = 1;
  optional uint32 num_nodes           = 2;
  optional string whitelisted_subnets = 3;
  optional string global_node_config  = 4;
  // Used for both database and log files.
  optional string root_data_dir = 5;

  // Plugin dir from which to load all custom VM executables.
  string plugin_dir = 6;

  // The list of:
  // - custom chain's VM name
  // - genesis file path
  // - (optional) subnet id to use.
  // - chain config file path
  // - network upgrade file path
  //
  // subnet id must be always nil when using StartRequest, as the network is empty and has no preloaded
  // subnet ids available.
  //
  // The matching file with the name in "ids.ID" format must exist.
  // e.g., ids.ToID(hashing.ComputeHash256("subnetevm")).String()
  // e.g., subnet-cli create VMID subnetevm
  //
  // If this field is set to none (by default), the node/network-runner
  // does not install the custom chain and does not create the subnet,
  // even if the VM binary exists on the local plugins directory.
  repeated BlockchainSpec blockchain_specs = 7;

  map<string, string> custom_node_configs = 8;

  // Map of chain name to config file contents.
  // If specified, will create a file "chainname/config.json" with
  // the contents provided here.
  map<string, string> chain_configs = 9;

  // Map of chain name to upgrade file contents.
  // If specified, will create a file "chainname/upgrade.json" with
  // the contents provided here.
  map<string, string> upgrade_configs = 10;

  // reassign default/custom ports if they are already taken
  optional bool reassign_ports_if_used = 11;

  // use dynamic ports instead of default ones
  optional bool dynamic_ports = 12;

  // Map of subnet id to subnet config file contents.
  // If specified, will create a file "subnetid.json" under subnets config dir with
  // the contents provided here.
  map<string, string> subnet_configs = 13;
}

message RPCVersionRequest {}

message RPCVersionResponse {
  uint32 version = 1;
}

message StartResponse {
  ClusterInfo cluster_info = 1;
  repeated string chain_ids = 2;
}

message SubnetSpec {
  // if empty, assumes all nodes should be participants
  repeated string participants = 1;
  // either file path or file contents
  string subnet_config = 2;
}

message ElasticSubnetSpec {
  string subnet_id = 1;
  string asset_name = 2;
  string asset_symbol = 3;
  uint64 initial_supply = 4;
  uint64 max_supply = 5;
  uint64 min_consumption_rate = 6;
  uint64 max_consumption_rate = 7;
  uint64 min_validator_stake = 8;
  uint64 max_validator_stake = 9;
  uint64 min_stake_duration = 10;
  uint64 max_stake_duration = 11;
  uint32 min_delegation_fee = 12;
  uint64 min_delegator_stake = 13;
  uint32 max_validator_weight_factor = 14;
  uint32 uptime_requirement = 15;
}

message TransformElasticSubnetsRequest {
  repeated ElasticSubnetSpec elastic_subnet_spec = 1;
}

message TransformElasticSubnetsResponse {
  ClusterInfo cluster_info = 1;
  repeated string tx_ids = 2;
  repeated string asset_ids = 3;
}

message PermissionlessValidatorSpec {
  string subnet_id = 1;
  string node_name = 2;
  uint64 staked_token_amount = 3;
  string asset_id = 4;
  string start_time = 5;
  uint64 stake_duration = 6;
}

message AddPermissionlessValidatorRequest {
  repeated PermissionlessValidatorSpec validator_spec = 1;
}

message AddPermissionlessValidatorResponse {
  ClusterInfo cluster_info = 1;
}

message RemoveSubnetValidatorSpec {
  string subnet_id = 1;
  repeated string node_names = 2;
}

message RemoveSubnetValidatorRequest {
  repeated RemoveSubnetValidatorSpec validator_spec = 1;
}

message RemoveSubnetValidatorResponse {
  ClusterInfo cluster_info = 1;
}

message BlockchainSpec {
  string vm_name = 1;
  // either file path or file contents
  string genesis = 2;
  // either a subnet_id is given for a previously created subnet,
  // or a subnet specification is given for a new subnet generation
  optional string subnet_id = 3;
  optional SubnetSpec subnet_spec = 4;
  // General chain config, either file path or file contents
  string chain_config = 5;
  // either file path or file contents
  string network_upgrade = 6;
  string blockchain_alias = 7;
  // Per node chain config, either file path or file contents
  string per_node_chain_config = 8;
}

message CreateBlockchainsRequest {
  // The list of:
  // - custom chain's VM name
  // - genesis file path
  // - (optional) subnet id to use.
  // - chain config file path
  // - network upgrade file path
  // - subnet config file path
  // - chain config file path for specific nodes
  //
  // The matching file with the name in "ids.ID" format must exist.
  // e.g., ids.ToID(hashing.ComputeHash256("subnetevm")).String()
  // e.g., subnet-cli create VMID subnetevm
  //
  // If this field is set to none (by default), the node/network-runner
  // will return error
  repeated BlockchainSpec blockchain_specs = 1;
}

message CreateBlockchainsResponse {
  ClusterInfo cluster_info = 1;
  repeated string chain_ids = 2;
}

message CreateSubnetsRequest {
  repeated SubnetSpec subnet_specs = 1;
}

message CreateSubnetsResponse {
  ClusterInfo cluster_info = 1;
  repeated string subnet_ids = 2;
}

message HealthRequest {}

message HealthResponse {
  ClusterInfo cluster_info = 1;
}

message URIsRequest {}

message URIsResponse {
  repeated string uris = 1;
}

message WaitForHealthyRequest {}

message WaitForHealthyResponse {
  ClusterInfo cluster_info = 1;
}

message StatusRequest {}

message StatusResponse {
  ClusterInfo cluster_info = 1;
}

message StreamStatusRequest {
  int64 push_interval = 1;
}

message StreamStatusResponse {
  ClusterInfo cluster_info = 1;
}

message RestartNodeRequest {
  // Must be a valid node name.
  string name = 1;

  // Optional fields are set to the previous values if empty.
  optional string exec_path           = 2;
  optional string whitelisted_subnets = 3;

  // Map of chain name to config file contents.
  // If specified, will create a file "chainname/config.json" with
  // the contents provided here.
  map<string, string> chain_configs = 4;

  // Map of chain name to config file contents.
  // If specified, will create a file "chainname/upgrade.json" with
  // the contents provided here.
  map<string, string> upgrade_configs = 5;

  // Map of subnet id to subnet config file contents.
  // If specified, will create a file "subnetid.json" under subnets config dir with
  // the contents provided here.
  map<string, string> subnet_configs = 6;

  // Plugin dir from which to load all custom VM executables.
  string plugin_dir = 7;
}

message RestartNodeResponse {
  ClusterInfo cluster_info = 1;
}

message RemoveNodeRequest {
  string name = 1;
}

message RemoveNodeResponse {
  ClusterInfo cluster_info = 1;
}

message PauseNodeRequest {
  string name = 1;
}

message PauseNodeResponse {
  ClusterInfo cluster_info = 1;
}

message ResumeNodeRequest {
  string name = 1;
}

message ResumeNodeResponse {
  ClusterInfo cluster_info = 1;
}

message AddNodeRequest {
  string name                       = 1;
  string exec_path                  = 2;
  optional string node_config       = 3;

  // Map of chain name to config file contents.
  // If specified, will create a file "chainname/config.json" with
  // the contents provided here.
  map<string, string> chain_configs = 4;

  // Map of chain name to config file contents.
  // If specified, will create a file "chainname/upgrade.json" with
  // the contents provided here.
  map<string, string> upgrade_configs = 5;

  // Map of subnet id to subnet config file contents.
  // If specified, will create a file "subnetid.json" under subnets config dir with
  // the contents provided here.
  map<string, string> subnet_configs = 6;

  // Plugin dir from which to load all custom VM executables.
  string plugin_dir = 7;
}

message AddNodeResponse {
  ClusterInfo cluster_info = 1;
}

message StopRequest {}

message StopResponse {
  ClusterInfo cluster_info = 1;
}

message AttachPeerRequest {
  string node_name = 1;
}

message AttachPeerResponse {
  ClusterInfo cluster_info = 1;
  AttachedPeerInfo attached_peer_info = 2;
}

message SendOutboundMessageRequest {
  string node_name = 1;
  string peer_id   = 2;
  uint32 op        = 3;
  bytes bytes      = 4;
}

message SendOutboundMessageResponse {
  bool sent = 1;
}

message SaveSnapshotRequest {
  string snapshot_name = 1;
}

message SaveSnapshotResponse {
  string snapshot_path = 1;
}

message LoadSnapshotRequest {
  string snapshot_name = 1;
  optional string exec_path = 2;
  string plugin_dir = 3;
  optional string root_data_dir = 4;
  map<string, string> chain_configs = 5;
  map<string, string> upgrade_configs = 6;
  optional string global_node_config  = 7;
  optional bool reassign_ports_if_used = 8;
  map<string, string> subnet_configs = 9;
}

message LoadSnapshotResponse {
  ClusterInfo cluster_info = 1;
}

message RemoveSnapshotRequest {
  string snapshot_name = 1;
}

message RemoveSnapshotResponse {
}

message GetSnapshotNamesRequest {
}

message GetSnapshotNamesResponse {
  repeated string snapshot_names = 1;
}