ark/api-spec/protobuf/ark/v1/service.proto

syntax = "proto3";

package ark.v1;

import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";

service ArkService {
  rpc GetInfo(GetInfoRequest) returns (GetInfoResponse) {
    option (google.api.http) = {
      get: "/v1/info"
    };
  }
  rpc GetBoardingAddress(GetBoardingAddressRequest) returns (GetBoardingAddressResponse) {
    option (google.api.http) = {
      post: "/v1/boarding"
      body: "*"
    };
  };

  /* In-Round Transaction APIs */

  rpc RegisterInputsForNextRound(RegisterInputsForNextRoundRequest) returns (RegisterInputsForNextRoundResponse) {
    option (google.api.http) = {
      post: "/v1/round/registerInputs"
      body: "*"
    };
  };
  rpc RegisterOutputsForNextRound(RegisterOutputsForNextRoundRequest) returns (RegisterOutputsForNextRoundResponse) {
    option (google.api.http) = {
      post: "/v1/round/registerOutputs"
      body: "*"
    };
  };
  rpc SubmitTreeNonces(SubmitTreeNoncesRequest) returns (SubmitTreeNoncesResponse) {
    option (google.api.http) = {
      post: "/v1/round/tree/submitNonces"
      body: "*"
    };
  }
  rpc SubmitTreeSignatures(SubmitTreeSignaturesRequest) returns (SubmitTreeSignaturesResponse) {
    option (google.api.http) = {
      post: "/v1/round/tree/submitSignatures"
      body: "*"
    };
  }
  rpc SubmitSignedForfeitTxs(SubmitSignedForfeitTxsRequest) returns (SubmitSignedForfeitTxsResponse) {
    option (google.api.http) = {
      post: "/v1/round/submitForfeitTxs"
      body: "*"
    };
  };
  rpc GetEventStream(GetEventStreamRequest) returns (stream GetEventStreamResponse) {
    option (google.api.http) = {
      get: "/v1/events"
    };
  };
  rpc Ping(PingRequest) returns (PingResponse) {
    option (google.api.http) = {
      get: "/v1/round/ping/{request_id}"
    };
  };

  /* Out-of-Round Transaction APIs */

  rpc SubmitRedeemTx(SubmitRedeemTxRequest) returns (SubmitRedeemTxResponse) {
    option (google.api.http) = {
      post: "/v1/redeem-tx"
      body: "*"
    };
  }

  /* Explorer-like APIs */

  rpc GetRound(GetRoundRequest) returns (GetRoundResponse) {
    option (google.api.http) = {
      get: "/v1/round/{txid}"
    };
  };
  rpc GetRoundById(GetRoundByIdRequest) returns (GetRoundByIdResponse) {
    option (google.api.http) = {
      get: "/v1/round/id/{id}"
    };
  };
  rpc ListVtxos(ListVtxosRequest) returns (ListVtxosResponse) {
    option (google.api.http) = {
      get: "/v1/vtxos/{address}"
    };
  }
  rpc GetTransactionsStream(GetTransactionsStreamRequest) returns (stream GetTransactionsStreamResponse) {
    option (google.api.http) = {
      get: "/v1/transactions"
    };
  }

  /* Entity APIs */

  rpc SetNostrRecipient(SetNostrRecipientRequest) returns (SetNostrRecipientResponse) {
    option (google.api.http) = {
      post: "/v1/vtxo/nostr"
      body: "*"
    };
  }

  rpc DeleteNostrRecipient(DeleteNostrRecipientRequest) returns (DeleteNostrRecipientResponse) {
    option (google.api.http) = {
      post: "/v1/vtxo/nostr/delete"
      body: "*"
    };
  }
}

message GetInfoRequest {}
message GetInfoResponse {
  string pubkey = 1;
  int64 round_lifetime = 2;
  int64 unilateral_exit_delay = 3;
  int64 round_interval = 4;
  string network = 5;
  int64 dust = 6;
  string boarding_descriptor_template = 7;
  repeated string vtxo_descriptor_templates = 8;
  string forfeit_address = 9;
  MarketHour market_hour = 10;
}

message GetBoardingAddressRequest {
  string pubkey = 1;
}
message GetBoardingAddressResponse {
  string address = 1;
  oneof taproot_tree {
    string descriptor = 2;
    Tapscripts tapscripts = 3;
  }
}

/* In-Round Transaction API messages */

message RegisterInputsForNextRoundRequest {
  repeated Input inputs = 1;
  optional string ephemeral_pubkey = 2;
  repeated string notes = 3;
}
message RegisterInputsForNextRoundResponse {
  string request_id = 1;
}

message RegisterOutputsForNextRoundRequest {
  string request_id = 1;
  // List of receivers for to convert to leaves in the next VTXO tree. 
  repeated Output outputs = 2;
}
message RegisterOutputsForNextRoundResponse {}

message SubmitTreeNoncesRequest {
  string round_id = 1;
  string pubkey = 2;
  string tree_nonces = 3;
}
message SubmitTreeNoncesResponse {}

message SubmitTreeSignaturesRequest {
  string round_id = 1;
  string pubkey = 2;
  string tree_signatures = 3;
}
message SubmitTreeSignaturesResponse {}

message SubmitSignedForfeitTxsRequest {
  // Forfeit txs signed by the user. 
  repeated string signed_forfeit_txs = 1;
  // The user has to sign also the round tx if he registerd a boarding UTXO.
  optional string signed_round_tx = 2;
}
message SubmitSignedForfeitTxsResponse {}

message GetEventStreamRequest {}
message GetEventStreamResponse {
  oneof event {
    RoundFinalizationEvent round_finalization = 1;
    RoundFinalizedEvent round_finalized = 2;
    RoundFailed round_failed = 3;
    RoundSigningEvent round_signing = 4;
    RoundSigningNoncesGeneratedEvent round_signing_nonces_generated = 5; 
  }
}

message PingRequest {
  // The id used to register inputs and ouptuts.
  string request_id = 1;
}
message PingResponse {}

message SubmitRedeemTxRequest {
  string redeem_tx = 1;
}
message SubmitRedeemTxResponse {
  string signed_redeem_tx = 1;
}

/* Explorer-like API messages */

message GetRoundRequest {
  string txid = 1;
}
message GetRoundResponse {
  Round round = 1;
}

message GetRoundByIdRequest {
  string id = 1;
}
message GetRoundByIdResponse {
  Round round = 1;
}

message ListVtxosRequest {
  string address = 1;
}
message ListVtxosResponse {
  repeated Vtxo spendable_vtxos = 1;
  repeated Vtxo spent_vtxos = 2;
}

/* Events */

message RoundFinalizationEvent {
  string id = 1;
  string round_tx = 2;
  Tree vtxo_tree = 3;
  repeated string connectors = 4;
  int64 min_relay_fee_rate = 5;
}

message RoundFinalizedEvent {
  string id = 1;
  string round_txid = 2;
}

message RoundFailed {
  string id = 1;
  string reason = 2;
}

message RoundSigningEvent {
  string id = 1;
  repeated string cosigners_pubkeys = 2;
  Tree unsigned_vtxo_tree = 3;
  string unsigned_round_tx = 4;
}

message RoundSigningNoncesGeneratedEvent {
  string id = 1;
  string tree_nonces = 2;
}

/* Types */

enum RoundStage {
  ROUND_STAGE_UNSPECIFIED = 0;
  ROUND_STAGE_REGISTRATION = 1;
  ROUND_STAGE_FINALIZATION = 2;
  ROUND_STAGE_FINALIZED = 3;
  ROUND_STAGE_FAILED = 4;
}

message Round {
  string id = 1;
  int64 start = 2;
  int64 end = 3;
  string round_tx = 4;
  Tree vtxo_tree = 5;
  repeated string forfeit_txs = 6;
  repeated string connectors = 7;
  RoundStage stage = 8;
}

message Outpoint {
  string txid = 1;
  uint32 vout = 2;
}

message Input {
  Outpoint outpoint = 1;
  oneof taproot_tree {
    string descriptor = 2;
    Tapscripts tapscripts = 3;
  }
}

message Output {
  string address = 1; // onchain or off-chain
  uint64 amount = 2; // Amount to send in satoshis.
}

message Tree {
  repeated TreeLevel levels = 1;
}

message TreeLevel {
  repeated Node nodes = 1;
}

message Node {
  string txid = 1;
  string tx = 2;
  string parent_txid = 3;
}

message Vtxo {
  Outpoint outpoint = 1;
  bool spent = 2;
  string round_txid = 3;
  string spent_by = 4;
  int64 expire_at = 5;
  bool swept = 6;
  bool is_pending = 7;
  string redeem_tx = 8;
  uint64 amount = 9;
  string pubkey = 10;
  int64 created_at = 11;
}

message GetTransactionsStreamRequest {}
message GetTransactionsStreamResponse {
  oneof tx {
    RoundTransaction round = 1;
    RedeemTransaction redeem = 2;
  }
}

message RoundTransaction {
  string txid = 1;
  repeated Outpoint spent_vtxos = 2;
  repeated Vtxo spendable_vtxos = 3;
  repeated Outpoint claimed_boarding_utxos = 4;
}

message RedeemTransaction {
  string txid = 1;
  repeated Outpoint spent_vtxos = 2;
  repeated Vtxo spendable_vtxos = 3;
}

// This message is used to prove to the server that the user controls the vtxo without revealing the whole VTXO taproot tree.
message OwnershipProof {
  string control_block = 1;
  string script = 2;
  string signature = 3; // VTXO outpoint signed with script's secret key
}

message SignedVtxoOutpoint {
  Outpoint outpoint = 1;
  OwnershipProof proof = 2;
}

message SetNostrRecipientRequest {
  string nostr_recipient = 1;
  repeated SignedVtxoOutpoint vtxos = 2;
}

message SetNostrRecipientResponse {}

message DeleteNostrRecipientRequest {
  repeated SignedVtxoOutpoint vtxos = 1;
}

message DeleteNostrRecipientResponse {}

message Tapscripts {
  repeated string scripts = 1;
}

message MarketHour {
  google.protobuf.Timestamp next_start_time = 1;
  google.protobuf.Timestamp next_end_time = 2;
  google.protobuf.Duration period = 3;
  google.protobuf.Duration round_interval = 4;
}