update clementine.proto

Author: mmtftr

proto/clementine.proto

@@ -12,10 +12,6 @@ message Outpoint {
   uint32 vout = 2;
 }
 
-message XonlyPublicKey {
-  bytes xonly_pk = 1;
-}
-
 message NofnResponse {
   bytes nofn_xonly_pk = 1;
   uint32 num_verifiers = 2;
@@ -278,14 +274,14 @@ message EntityError {
 
 message EntityStatus {
   bool automation = 1;
-  string wallet_balance = 2;
-  uint32 tx_sender_synced_height = 3;
-  uint32 finalized_synced_height = 4;
-  uint32 hcp_last_proven_height = 5;
+  optional string wallet_balance = 2;
+  optional uint32 tx_sender_synced_height = 3;
+  optional uint32 finalized_synced_height = 4;
+  optional uint32 hcp_last_proven_height = 5;
   StoppedTasks stopped_tasks = 6;
-  uint32 rpc_tip_height = 7;
-  uint32 bitcoin_syncer_synced_height = 8;
-  uint32 state_manager_next_height = 9;
+  optional uint32 rpc_tip_height = 7;
+  optional uint32 bitcoin_syncer_synced_height = 8;
+  optional uint32 state_manager_next_height = 9;
 }
 
 enum EntityType {
@@ -356,11 +352,31 @@ service ClementineOperator {
   // Restarts the background tasks for the operator.
   rpc RestartBackgroundTasks(Empty) returns (Empty) {}
 
-  // Prepares a withdrawal if it's profitable and the withdrawal is correct and registered in Citrea bridge contract/
+  // Prepares a withdrawal if it's profitable and the withdrawal is correct and registered in Citrea bridge contract.
   // If withdrawal is accepted, the payout tx will be added to the TxSender and success is returned, otherwise an error is returned.
   // If automation is disabled, the withdrawal will not be accepted and an error will be returned.
-  rpc Withdraw(WithdrawParams)
-    returns (Empty) {}
+  // Note: This is intended for operator's own use, so it doesn't include a signature from aggregator.
+  rpc InternalWithdraw(WithdrawParams)
+    returns (RawSignedTx) {}
+
+
+  // First, if verification address in operator's config is set, the signature in rpc is checked to see if it was signed by the verification address.
+  // Then prepares a withdrawal if it's profitable and the withdrawal is correct and registered in Citrea bridge contract.
+  // If withdrawal is accepted, the payout tx will be added to the TxSender and success is returned, otherwise an error is returned.
+  // If automation is disabled, the withdrawal will not be accepted and an error will be returned.
+  rpc Withdraw(WithdrawParamsWithSig)
+    returns (RawSignedTx) {}
+
+  // For a given deposit outpoint, determines the next step in the kickoff process the operator is in,
+  // and returns the raw signed txs that the operator needs to send next, for enabling reimbursement process
+  // without automation.
+  //
+  // # Parameters
+  // - deposit_outpoint: Deposit outpoint to create the kickoff for
+  //
+  // # Returns
+  // - Raw signed txs that the operator needs to send next
+  rpc GetReimbursementTxs(Outpoint) returns (SignedTxsWithType) {}
 
   // Signs all tx's it can according to given transaction type (use it with AllNeededForDeposit to get almost all tx's)
   // Creates the transactions denoted by the deposit and operator_idx, round_idx, and kickoff_idx.
@@ -411,7 +427,8 @@ message NonceGenRequest {
 
 message NonceGenFirstResponse {
   // ID of the nonce session (used to store nonces in verifier's memory)
-  uint32 id = 1;
+  // The id is string representation of a u128 number
+  string id = 1;
   // Number of nonces to generate
   uint32 num_nonces = 2;
 }
@@ -422,8 +439,34 @@ message NonceGenResponse {
   }
 }
 
-message OptimisticPayoutParams {
+message OptimisticWithdrawParams {
   WithdrawParams withdrawal = 1;
+  // An ECDSA signature (of citrea/aggregator) over the withdrawal params
+  // to authenticate the withdrawal params. This will be signed manually by citrea
+  // after manual verification of the optimistic payout.
+  optional string verification_signature = 2;
+}
+
+message WithdrawParamsWithSig {
+  WithdrawParams withdrawal = 1;
+  // An ECDSA signature (of citrea/aggregator) over the withdrawal params
+  // to authenticate the withdrawal params. This will be signed manually by citrea
+  // after manual verification of the optimistic payout.
+  // This message contains same data as the one in Optimistic Payout signature, but with a different message name,
+  // so that the same signature can't be used for both optimistic payout and normal withdrawal.
+  optional string verification_signature = 2;
+}
+
+// Input of the aggregator's withdraw function.
+// It contains the withdrawal params along with the verification signature that signs the withdrawal params.
+// It also contains the operator's xonly public keys that the withdrawal request should be sent to. If the list is empty, the withdrawal will be sent to all operators.
+message AggregatorWithdrawalInput {
+  WithdrawParamsWithSig withdrawal = 1;
+  repeated XOnlyPublicKeyRpc operator_xonly_pks = 2;
+}
+
+message OptimisticPayoutParams {
+  OptimisticWithdrawParams opt_withdrawal = 1;
   NonceGenFirstResponse nonce_gen = 2;
   bytes agg_nonce = 3;
 }
@@ -473,7 +516,7 @@ message TxMetadata {
   // Optional outpoint of the deposit transaction
   Outpoint deposit_outpoint = 1;
   // Deposit identification
-  XonlyPublicKey operator_xonly_pk = 2;
+  XOnlyPublicKeyRpc operator_xonly_pk = 2;
   uint32 round_idx = 4;
   uint32 kickoff_idx = 5;
   // Transaction ID
@@ -616,9 +659,13 @@ message AggregatorWithdrawResponse {
   repeated string withdraw_responses = 1;
 }
 
-message CreateEmergencyStopTxRequest {
+message GetEmergencyStopTxRequest {
+  repeated Txid txids = 1;
+}
+
+message GetEmergencyStopTxResponse {
   repeated Txid txids = 1;
-  bool add_anchor = 2;
+  repeated bytes encrypted_emergency_stop_txs = 2;
 }
 
 message SendMoveTxRequest {
@@ -655,11 +702,13 @@ service ClementineAggregator {
 
   // Call's withdraw on all operators
   // Used by the clementine-backend service to initiate a withdrawal
-  rpc Withdraw(WithdrawParams)
+  // If the operator's xonly public keys list is empty, the withdrawal will be sent to all operators.
+  // If not, only the operators in the list will be sent the withdrawal request.
+  rpc Withdraw(AggregatorWithdrawalInput)
     returns (AggregatorWithdrawResponse) {}
 
   // Perform an optimistic payout to reimburse a peg-out from Citrea
-  rpc OptimisticPayout(WithdrawParams) returns (RawSignedTx)  {}
+  rpc OptimisticPayout(OptimisticWithdrawParams) returns (RawSignedTx)  {}
 
   // Send a pre-signed tx to the network
   rpc InternalSendTx(SendTxRequest) returns (Empty) {}
@@ -673,7 +722,7 @@ service ClementineAggregator {
   // Creates an emergency stop tx that won't be broadcasted.
   // Tx will have around 3 sats/vbyte fee.
   // Set add_anchor to true to add an anchor output for cpfp..
-  rpc InternalCreateEmergencyStopTx(CreateEmergencyStopTxRequest) returns (SignedTxWithType) {}
+  rpc InternalGetEmergencyStopTx(GetEmergencyStopTxRequest) returns (GetEmergencyStopTxResponse) {}
 
   rpc Vergen(Empty) returns (VergenResponse) {}
-}
+}

src/clementine/client.rs

@@ -82,6 +82,10 @@ impl ClementineAggregatorTestClient {
         Ok(Self { client })
     }
 
+    pub fn inner_mut(&mut self) -> &mut ClementineAggregatorClient<Channel> {
+        &mut self.client
+    }
+
     pub async fn new_deposit(&mut self, deposit: Deposit) -> Result<RawSignedTx> {
         let request = Request::new(deposit);
         let response = self
@@ -92,7 +96,10 @@ impl ClementineAggregatorTestClient {
         Ok(response.into_inner())
     }
 
-    pub async fn withdraw(&mut self, params: WithdrawParams) -> Result<AggregatorWithdrawResponse> {
+    pub async fn withdraw(
+        &mut self,
+        params: AggregatorWithdrawalInput,
+    ) -> Result<AggregatorWithdrawResponse> {
         let request = Request::new(params);
         let response = self
             .client
@@ -102,7 +109,10 @@ impl ClementineAggregatorTestClient {
         Ok(response.into_inner())
     }
 
-    pub async fn optimistic_payout(&mut self, params: WithdrawParams) -> Result<RawSignedTx> {
+    pub async fn optimistic_payout(
+        &mut self,
+        params: OptimisticWithdrawParams,
+    ) -> Result<RawSignedTx> {
         let request = Request::new(params);
         let response = self
             .client
@@ -155,6 +165,10 @@ impl ClementineOperatorTestClient {
         Ok(Self { client })
     }
 
+    pub fn inner_mut(&mut self) -> &mut ClementineOperatorClient<Channel> {
+        &mut self.client
+    }
+
     pub async fn get_x_only_public_key(&mut self) -> Result<XOnlyPublicKeyRpc> {
         let request = Request::new(Empty {});
         let response = self
@@ -185,7 +199,7 @@ impl ClementineOperatorTestClient {
         Ok(response.into_inner())
     }
 
-    pub async fn withdraw(&mut self, params: WithdrawParams) -> Result<()> {
+    pub async fn withdraw(&mut self, params: WithdrawParamsWithSig) -> Result<()> {
         let request = Request::new(params);
         self.client
             .withdraw(request)
@@ -216,6 +230,10 @@ impl ClementineVerifierTestClient {
         Ok(Self { client })
     }
 
+    pub fn inner_mut(&mut self) -> &mut ClementineVerifierClient<Channel> {
+        &mut self.client
+    }
+
     pub async fn get_params(&mut self) -> Result<VerifierParams> {
         let request = Request::new(Empty {});
         let response = self