Skip to content

Commit

Permalink
proto: Update operator comments.
Browse files Browse the repository at this point in the history
  • Loading branch information
@ceyhunsen
ceyhunsen committed Oct 17, 2024
1 parent 253b8ca commit fbeaf1c
Show file tree
Hide file tree
Showing 2 changed files with 149 additions and 105 deletions.
102 changes: 58 additions & 44 deletions core/src/rpc/clementine.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,16 +20,57 @@ message WinternitzPubkey {

// Operator --------------------------------------------------------------------

message OperatorConfig {
uint32 operator_id = 1;
Outpoint initial_time_tx_outpoint = 2;
string xonly_pk = 3;
string wallet_reimburse_address = 4;
}
message OperatorParams {
// Operator's configuration.
OperatorConfig operator_details = 1;
// Winternitz pubkeys for each watchtowers challenge + bitvm assert tx.
// If there are 100 watchtowers and total of 1000 timetxs, it will take
// 1000 * (100*240 + 600*20) ~= 1 GB of hash for every winternitz pubkey.
repeated WinternitzPubkey winternitz_pubkeys = 2;
// Adaptor signatures for asserting a watchtower's challenge to zero.
// Total of 1000*100 preimages.
repeated AssertEmptyPublicKey assert_empty_public_key = 3;
// Timeout transaction signatures. It is not desired to have N-of-N in time
// txs. So, operator will sign the timeout txs. Takes total of 1000 schnorr
// sigs.
repeated bytes timeout_tx_sigs = 4;
}

message DepositParams {
// User's deposit UTXO.
Outpoint deposit_outpoint = 1;
// User's EVM address.
bytes evm_address = 2;
// User's recovery taproot address.
string recovery_taproot_address = 3;
// User can take back funds after this amount of blocks.
uint64 user_takes_after = 4;
}
message DepositSignSession {
DepositParams deposit_params = 1;
repeated NonceGenFirstResponse nonce_gen_first_responses = 2;
}
message OperatorBurnSig {
bytes schnorr_sig = 1;
}

message NewWithdrawalSigParams {
uint32 withdrawal_id = 1;
// User's [`bitcoin::sighash::TapSighashType::SinglePlusAnyoneCanPay`]
// signature
bytes user_sig = 2;
Outpoint users_intent_outpoint = 3;
bytes users_intent_script_pubkey = 4;
uint64 users_intent_amount = 5;
bytes output_script_pubkey = 6;
uint64 output_amount = 7;
}

message NewWithdrawalSigResponse {
bytes txid = 1;
}
Expand All @@ -39,37 +80,6 @@ message WithdrawalFinalizedParams {
Outpoint deposit_outpoint = 2;
}

message OperatorBurnSig {
bytes schnorr_sig = 1;
}

message DepositSignSession {
DepositParams deposit_params = 1;
repeated NonceGenFirstResponse nonce_gen_first_responses = 2;
}

message OperatorConfig {
uint32 operator_id = 1;
Outpoint initial_time_tx_outpoint = 2;
string xonly_pk = 3;
string wallet_reimburse_address = 4;
}

// Operators' parameters for longest chain proofs.
message OperatorParams {
OperatorConfig operator_details = 1;
// Winternitz pubkeys for each watchtowers challenge + bitvm assert tx.
// If 100 watchtowers and total of 1000 timetxs, we will have 1000*(100*240 +
// 600*20) ~= 1 GB hashes for every winternitz pubkey.
repeated WinternitzPubkey winternitz_pubkeys = 2;
// Adaptor signatures for asserting a watchtower's challenge to zero.
// Total of, 1000*100 preimages.
repeated AssertEmptyPublicKey assert_empty_public_key = 3;
// We don't want N-of-N in time txs, so operator will sign the timeout txs.
// Total of 1000 schnorr sigs.
repeated bytes timeout_tx_sigs = 4;
}

// An operator is responsible for paying withdrawals. It has an unique ID and
// chain of UTXOs named `time_txs`. An operator also runs a verifier. These are
// connected to the same database and both have access to watchtowers'
Expand All @@ -88,20 +98,31 @@ service ClementineOperator {
//
// # Parameters
//
// - Deposit parameters
// - User's deposit information
// - Nonce metadata
//
// # Returns
//
// - Operator burn Schnorr signature
rpc DepositSign(DepositSignSession) returns (stream OperatorBurnSig) {}

// Prepares a withdrawal if it's profitable and previous time_tx's timelock
// has ended, by paying for the withdrawal and locking the current time_tx.
rpc NewWithdrawalSig(NewWithdrawalSigParams)
returns (NewWithdrawalSigResponse) {}

// 1- Calculate move_txid, check if the withdrawal idx matches the move_txid
// 2- Check if it is really proved on citrea
// 3- If it is, send operator_take_txs
// Checks if a withdrawal is finalized.
//
// Steps:
//
// 1. Calculate move_txid and check if the withdrawal idx matches it
// 2. Check if it is proved on citrea
// 3. Send operator_take_txs
//
// # Parameters
//
// - withdrawal_id: Withdrawal's ID
// - deposit_outpoint: Withdrawal's deposit UTXO
rpc WithdrawalFinalized(WithdrawalFinalizedParams) returns (Empty) {}
}

Expand All @@ -121,6 +142,7 @@ message PartialSig {
}

message NonceGenFirstResponse {
// Nonce ID
uint32 id = 1;
// New public key for the deposit
bytes public_key = 2;
Expand All @@ -129,7 +151,6 @@ message NonceGenFirstResponse {
// Number of nonces to generate
uint32 num_nonces = 4;
}

message NonceGenResponse {
oneof response {
NonceGenFirstResponse first_response = 1;
Expand Down Expand Up @@ -198,13 +219,6 @@ service ClementineWatchtower {

// Aggregator ------------------------------------------------------------------

message DepositParams {
Outpoint deposit_outpoint = 1;
bytes evm_address = 2;
string recovery_taproot_address = 3;
uint64 user_takes_after = 4;
}

message RawSignedMoveTx {
bytes raw_tx = 1;
}
Expand Down
152 changes: 91 additions & 61 deletions core/src/rpc/clementine.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,69 @@ pub struct WinternitzPubkey {
pub digit_pubkey: ::prost::alloc::vec::Vec<::prost::alloc::vec::Vec<u8>>,
}
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct OperatorConfig {
#[prost(uint32, tag = "1")]
pub operator_id: u32,
#[prost(message, optional, tag = "2")]
pub initial_time_tx_outpoint: ::core::option::Option<Outpoint>,
#[prost(string, tag = "3")]
pub xonly_pk: ::prost::alloc::string::String,
#[prost(string, tag = "4")]
pub wallet_reimburse_address: ::prost::alloc::string::String,
}
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct OperatorParams {
/// Operator's configuration.
#[prost(message, optional, tag = "1")]
pub operator_details: ::core::option::Option<OperatorConfig>,
/// Winternitz pubkeys for each watchtowers challenge + bitvm assert tx.
/// If there are 100 watchtowers and total of 1000 timetxs, it will take
/// 1000 * (100*240 + 600*20) ~= 1 GB of hash for every winternitz pubkey.
#[prost(message, repeated, tag = "2")]
pub winternitz_pubkeys: ::prost::alloc::vec::Vec<WinternitzPubkey>,
/// Adaptor signatures for asserting a watchtower's challenge to zero.
/// Total of 1000*100 preimages.
#[prost(message, repeated, tag = "3")]
pub assert_empty_public_key: ::prost::alloc::vec::Vec<AssertEmptyPublicKey>,
/// Timeout transaction signatures. It is not desired to have N-of-N in time
/// txs. So, operator will sign the timeout txs. Takes total of 1000 schnorr
/// sigs.
#[prost(bytes = "vec", repeated, tag = "4")]
pub timeout_tx_sigs: ::prost::alloc::vec::Vec<::prost::alloc::vec::Vec<u8>>,
}
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct DepositParams {
/// User's deposit UTXO.
#[prost(message, optional, tag = "1")]
pub deposit_outpoint: ::core::option::Option<Outpoint>,
/// User's EVM address.
#[prost(bytes = "vec", tag = "2")]
pub evm_address: ::prost::alloc::vec::Vec<u8>,
/// User's recovery taproot address.
#[prost(string, tag = "3")]
pub recovery_taproot_address: ::prost::alloc::string::String,
/// User can take back funds after this amount of blocks.
#[prost(uint64, tag = "4")]
pub user_takes_after: u64,
}
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct DepositSignSession {
#[prost(message, optional, tag = "1")]
pub deposit_params: ::core::option::Option<DepositParams>,
#[prost(message, repeated, tag = "2")]
pub nonce_gen_first_responses: ::prost::alloc::vec::Vec<NonceGenFirstResponse>,
}
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct OperatorBurnSig {
#[prost(bytes = "vec", tag = "1")]
pub schnorr_sig: ::prost::alloc::vec::Vec<u8>,
}
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct NewWithdrawalSigParams {
#[prost(uint32, tag = "1")]
pub withdrawal_id: u32,
/// User's \[`bitcoin::sighash::TapSighashType::SinglePlusAnyoneCanPay`\]
/// signature
#[prost(bytes = "vec", tag = "2")]
pub user_sig: ::prost::alloc::vec::Vec<u8>,
#[prost(message, optional, tag = "3")]
Expand All @@ -52,48 +112,6 @@ pub struct WithdrawalFinalizedParams {
pub deposit_outpoint: ::core::option::Option<Outpoint>,
}
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct OperatorBurnSig {
#[prost(bytes = "vec", tag = "1")]
pub schnorr_sig: ::prost::alloc::vec::Vec<u8>,
}
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct DepositSignSession {
#[prost(message, optional, tag = "1")]
pub deposit_params: ::core::option::Option<DepositParams>,
#[prost(message, repeated, tag = "2")]
pub nonce_gen_first_responses: ::prost::alloc::vec::Vec<NonceGenFirstResponse>,
}
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct OperatorConfig {
#[prost(uint32, tag = "1")]
pub operator_id: u32,
#[prost(message, optional, tag = "2")]
pub initial_time_tx_outpoint: ::core::option::Option<Outpoint>,
#[prost(string, tag = "3")]
pub xonly_pk: ::prost::alloc::string::String,
#[prost(string, tag = "4")]
pub wallet_reimburse_address: ::prost::alloc::string::String,
}
/// Operators' parameters for longest chain proofs.
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct OperatorParams {
#[prost(message, optional, tag = "1")]
pub operator_details: ::core::option::Option<OperatorConfig>,
/// Winternitz pubkeys for each watchtowers challenge + bitvm assert tx.
/// If 100 watchtowers and total of 1000 timetxs, we will have 1000*(100*240 +
/// 600*20) ~= 1 GB hashes for every winternitz pubkey.
#[prost(message, repeated, tag = "2")]
pub winternitz_pubkeys: ::prost::alloc::vec::Vec<WinternitzPubkey>,
/// Adaptor signatures for asserting a watchtower's challenge to zero.
/// Total of, 1000*100 preimages.
#[prost(message, repeated, tag = "3")]
pub assert_empty_public_key: ::prost::alloc::vec::Vec<AssertEmptyPublicKey>,
/// We don't want N-of-N in time txs, so operator will sign the timeout txs.
/// Total of 1000 schnorr sigs.
#[prost(bytes = "vec", repeated, tag = "4")]
pub timeout_tx_sigs: ::prost::alloc::vec::Vec<::prost::alloc::vec::Vec<u8>>,
}
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct VerifierParams {
#[prost(uint32, tag = "1")]
pub id: u32,
Expand All @@ -115,6 +133,7 @@ pub struct PartialSig {
}
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct NonceGenFirstResponse {
/// Nonce ID
#[prost(uint32, tag = "1")]
pub id: u32,
/// New public key for the deposit
Expand Down Expand Up @@ -186,17 +205,6 @@ pub struct WatchtowerParams {
pub winternitz_pubkeys: ::prost::alloc::vec::Vec<WinternitzPubkey>,
}
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct DepositParams {
#[prost(message, optional, tag = "1")]
pub deposit_outpoint: ::core::option::Option<Outpoint>,
#[prost(bytes = "vec", tag = "2")]
pub evm_address: ::prost::alloc::vec::Vec<u8>,
#[prost(string, tag = "3")]
pub recovery_taproot_address: ::prost::alloc::string::String,
#[prost(uint64, tag = "4")]
pub user_takes_after: u64,
}
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct RawSignedMoveTx {
#[prost(bytes = "vec", tag = "1")]
pub raw_tx: ::prost::alloc::vec::Vec<u8>,
Expand Down Expand Up @@ -328,7 +336,7 @@ pub mod clementine_operator_client {
///
/// # Parameters
///
/// - Deposit parameters
/// - User's deposit information
/// - Nonce metadata
///
/// # Returns
Expand Down Expand Up @@ -358,6 +366,8 @@ pub mod clementine_operator_client {
.insert(GrpcMethod::new("clementine.ClementineOperator", "DepositSign"));
self.inner.server_streaming(req, path, codec).await
}
/// Prepares a withdrawal if it's profitable and previous time_tx's timelock
/// has ended, by paying for the withdrawal and locking the current time_tx.
pub async fn new_withdrawal_sig(
&mut self,
request: impl tonic::IntoRequest<super::NewWithdrawalSigParams>,
Expand All @@ -384,9 +394,18 @@ pub mod clementine_operator_client {
);
self.inner.unary(req, path, codec).await
}
/// 1- Calculate move_txid, check if the withdrawal idx matches the move_txid
/// 2- Check if it is really proved on citrea
/// 3- If it is, send operator_take_txs
/// Checks if a withdrawal is finalized.
///
/// Steps:
///
/// 1. Calculate move_txid and check if the withdrawal idx matches it
/// 2. Check if it is proved on citrea
/// 3. Send operator_take_txs
///
/// # Parameters
///
/// - withdrawal_id: Withdrawal's ID
/// - deposit_outpoint: Withdrawal's deposit UTXO
pub async fn withdrawal_finalized(
&mut self,
request: impl tonic::IntoRequest<super::WithdrawalFinalizedParams>,
Expand Down Expand Up @@ -982,7 +1001,7 @@ pub mod clementine_operator_server {
///
/// # Parameters
///
/// - Deposit parameters
/// - User's deposit information
/// - Nonce metadata
///
/// # Returns
Expand All @@ -995,16 +1014,27 @@ pub mod clementine_operator_server {
tonic::Response<Self::DepositSignStream>,
tonic::Status,
>;
/// Prepares a withdrawal if it's profitable and previous time_tx's timelock
/// has ended, by paying for the withdrawal and locking the current time_tx.
async fn new_withdrawal_sig(
&self,
request: tonic::Request<super::NewWithdrawalSigParams>,
) -> std::result::Result<
tonic::Response<super::NewWithdrawalSigResponse>,
tonic::Status,
>;
/// 1- Calculate move_txid, check if the withdrawal idx matches the move_txid
/// 2- Check if it is really proved on citrea
/// 3- If it is, send operator_take_txs
/// Checks if a withdrawal is finalized.
///
/// Steps:
///
/// 1. Calculate move_txid and check if the withdrawal idx matches it
/// 2. Check if it is proved on citrea
/// 3. Send operator_take_txs
///
/// # Parameters
///
/// - withdrawal_id: Withdrawal's ID
/// - deposit_outpoint: Withdrawal's deposit UTXO
async fn withdrawal_finalized(
&self,
request: tonic::Request<super::WithdrawalFinalizedParams>,
Expand Down

0 comments on commit fbeaf1c

Please sign in to comment.