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

syntax = "proto3";

package ark.v1;

import "google/api/annotations.proto";

service ArkService {
  rpc RegisterPayment(RegisterPaymentRequest) returns (RegisterPaymentResponse) {
    option (google.api.http) = {
      post: "/v1/payment/register"
      body: "*"
    };
  };
  rpc ClaimPayment(ClaimPaymentRequest) returns (ClaimPaymentResponse) {
    option (google.api.http) = {
      post: "/v1/payment/claim"
      body: "*"
    };
  };
  rpc SendTreeNonces(SendTreeNoncesRequest) returns (SendTreeNoncesResponse) {
    option (google.api.http) = {
      post: "/v1/payment/tree/nonces"
      body: "*"
    };
  }
  rpc SendTreeSignatures(SendTreeSignaturesRequest) returns (SendTreeSignaturesResponse) {
    option (google.api.http) = {
      post: "/v1/payment/tree/signatures"
      body: "*"
    };
  }
  rpc FinalizePayment(FinalizePaymentRequest) returns (FinalizePaymentResponse) {
    option (google.api.http) = {
      post: "/v1/payment/finalize"
      body: "*"
    };
  };
  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 GetEventStream(GetEventStreamRequest) returns (stream GetEventStreamResponse) {
    option (google.api.http) = {
      get: "/v1/events"
    };
  };
  rpc Ping(PingRequest) returns (PingResponse) {
    option (google.api.http) = {
      get: "/v1/ping/{payment_id}"
    };
  };
  rpc ListVtxos(ListVtxosRequest) returns (ListVtxosResponse) {
    option (google.api.http) = {
      get: "/v1/vtxos/{address}"
    };
  }
  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: "*"
    };
  };
  rpc CreatePayment(CreatePaymentRequest) returns (CreatePaymentResponse) {
    option (google.api.http) = {
      post: "/v1/payment"
      body: "*"
    };
  }
  rpc CompletePayment(CompletePaymentRequest) returns (CompletePaymentResponse) {
    option (google.api.http) = {
      post: "/v1/payment/complete"
      body: "*"
    };
  }
}

message CreatePaymentRequest {
  repeated Input inputs = 1;
  repeated Output outputs = 2;
}
message CreatePaymentResponse {
  string signed_redeem_tx = 1; // signed only by the ASP
  repeated string usigned_unconditional_forfeit_txs = 2;
}

message CompletePaymentRequest {
  string signed_redeem_tx = 1;
  repeated string signed_unconditional_forfeit_txs = 2;
}
message CompletePaymentResponse {}

message GetBoardingAddressRequest {
  string pubkey = 1;
}

message GetBoardingAddressResponse {
  string address = 1;
  string descriptor = 2;
}

message RegisterPaymentRequest {
  repeated Input inputs = 1;
  optional string ephemeral_pubkey = 2;
}
message RegisterPaymentResponse {
  // Mocks wabisabi's credentials.
  string id = 1;
}

message ClaimPaymentRequest {
  // Mocks wabisabi's credentials.
  string id = 1;
  // List of receivers for a registered payment. 
  repeated Output outputs = 2;
}
message ClaimPaymentResponse {}

message FinalizePaymentRequest {
  // Forfeit txs signed by the user. 
  repeated string signed_forfeit_txs = 1;
  // If payment has boarding input, the user must sign the associated inputs.
  optional string signed_round_tx = 2;
}
message FinalizePaymentResponse {}

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

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

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 {
  string payment_id = 1;
}
message PingResponse {
  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 ListVtxosRequest {
  string address = 1;
}
message ListVtxosResponse {
  repeated Vtxo spendable_vtxos = 1;
  repeated Vtxo spent_vtxos = 2;
}

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;
}

// EVENT TYPES

message RoundFinalizationEvent {
  string id = 1;
  string pool_tx = 2;
  repeated string forfeit_txs = 3;
  Tree congestion_tree = 4;
  repeated string connectors = 5;
}

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

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

message RoundSigningEvent {
  string id = 1;
  repeated string cosigners_pubkeys = 2;
  Tree unsigned_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 pool_tx = 4;
  Tree congestion_tree = 5;
  repeated string forfeit_txs = 6;
  repeated string connectors = 7;
  RoundStage stage = 8;
}

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

message BoardingInput {
  string txid = 1;
  uint32 vout = 2;
  string descriptor = 3;
}

message Input {
  oneof input {
    VtxoInput vtxo_input = 1;
    BoardingInput boarding_input = 2;
  }
}

message Output {
  // Either the offchain or onchain address.
  string address = 1;
  // Amount to send in satoshis.
  uint64 amount = 2;
}

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 {
  Input outpoint = 1;
  Output receiver = 2;
  bool spent = 3;
  string pool_txid = 4;
  string spent_by = 5;
  int64 expire_at = 6;
  bool swept = 7;
  bool pending = 8;
  PendingPayment pending_data = 9;
}

message PendingPayment {
  string redeem_tx = 1;
  repeated string unconditional_forfeit_txs =2;
}

message SendTreeNoncesRequest {
  string round_id = 1;
  string public_key = 2;
  string tree_nonces = 3;
}

message SendTreeNoncesResponse {}

message SendTreeSignaturesRequest {
  string round_id = 1;
  string public_key = 2;
  string tree_signatures = 3;
}

message SendTreeSignaturesResponse {}