clementine_core/states/kickoff.rs
1use std::collections::{HashMap, HashSet};
2
3use bitcoin::{OutPoint, Transaction, Witness};
4use eyre::Context;
5use serde_with::serde_as;
6use statig::prelude::*;
7
8use crate::{
9 bitvm_client::ClementineBitVMPublicKeys,
10 builder::transaction::{input::UtxoVout, remove_txhandler_from_map, ContractContext},
11 deposit::{DepositData, KickoffData},
12};
13use clementine_errors::BridgeError;
14use clementine_primitives::TransactionType;
15
16use super::{
17 block_cache::BlockCache,
18 context::{Duty, StateContext},
19 matcher::{BlockMatcher, Matcher},
20 Owner, StateMachineError,
21};
22
23/// Events that can be dispatched to the kickoff state machine
24/// These event either trigger state transitions or trigger actions of the owner
25#[derive(
26 Debug, Clone, PartialEq, Eq, Hash, Ord, PartialOrd, serde::Serialize, serde::Deserialize,
27)]
28pub enum KickoffEvent {
29 /// Event that is dispatched when the kickoff is challenged
30 /// This will change the state to "Challenged"
31 Challenged,
32 /// Event that is dispatched when a watchtower challenge is detected in Bitcoin
33 WatchtowerChallengeSent {
34 watchtower_idx: usize,
35 challenge_outpoint: OutPoint,
36 },
37 /// Event that is dispatched when an operator BitVM assert is detected in Bitcoin
38 OperatorAssertSent {
39 assert_idx: usize,
40 assert_outpoint: OutPoint,
41 },
42 /// Event that is dispatched when a watchtower challenge timeout is detected in Bitcoin
43 WatchtowerChallengeTimeoutSent { watchtower_idx: usize },
44 /// Event that is dispatched when an operator challenge ack is detected in Bitcoin
45 /// Operator challenge acks are sent by operators to acknowledge watchtower challenges
46 OperatorChallengeAckSent {
47 watchtower_idx: usize,
48 challenge_ack_outpoint: OutPoint,
49 },
50 /// Event that is dispatched when the latest blockhash is detected in Bitcoin
51 LatestBlockHashSent { latest_blockhash_outpoint: OutPoint },
52 /// Event that is dispatched when the kickoff finalizer is spent in Bitcoin
53 /// Irrespective of whether the kickoff is malicious or not, the kickoff process is finished when the kickoff finalizer is spent.
54 KickoffFinalizerSpent,
55 /// Event that is dispatched when the burn connector is spent in Bitcoin
56 BurnConnectorSpent,
57 /// Vvent that is used to indicate that it is time for the owner to send latest blockhash tx.
58 /// Matcher for this event is created after all watchtower challenge utxos are spent.
59 /// Latest blockhash is sent some blocks after all watchtower challenge utxos are spent, so that the total work until the block commiitted
60 /// in latest blockhash is definitely higher than the highest work in valid watchtower challenges.
61 TimeToSendLatestBlockhash,
62 /// Event that is used to indicate that it is time for the owner to send watchtower challenge tx.
63 /// Watchtower challenges are sent after some blocks pass since the kickoff tx, so that the total work in the watchtower challenge is as high as possible.
64 TimeToSendWatchtowerChallenge,
65 /// Special event that is used to indicate that the state machine has been saved to the database and the dirty flag should be reset to false
66 SavedToDb,
67}
68
69/// State machine for tracking a single kickoff process in the protocol.
70///
71/// # Purpose
72/// The `KickoffStateMachine` manages the lifecycle of a single kickoff process, which is created after a kickoff transaction is detected on Bitcoin. It tracks the transactions related to the kickoff and the resulting data.
73///
74/// # States
75/// - `kickoff_started`: The initial state after a kickoff is detected. Waits for further events such as challenges, but still tracks any committed data on Bitcoin (like latest blockhash, operator asserts, watchtower challenges, etc)
76/// - `challenged`: Entered if the kickoff is challenged. Watchtower challenges are only sent if the kickoff is challenged.
77/// - `closed`: Terminal state indicating the kickoff process has ended, either by kickoff finalizer utxo or burn connector utxo being spent.
78///
79/// # Events
80/// - `Challenged`: The kickoff is challenged, transitioning to the `challenged` state.
81/// - `WatchtowerChallengeSent`: A watchtower challenge is detected on Bitcoin, stores the watchtower challenge transaction, and stores the watchtower utxo as spent.
82/// - `OperatorAssertSent`: An operator BitVM assert is detected, stores the witness of the assert utxo.
83/// - `WatchtowerChallengeTimeoutSent`: A watchtower challenge timeout is detected, stores watchtower utxo as spent.
84/// - `OperatorChallengeAckSent`: An operator challenge acknowledgment is detected, stores the witness of the challenge ack utxo, which holds the revealed preimage that can be used to disprove if the operator maliciously doesn't include the watchtower challenge in the BitVM proof. After sending this transaction, the operator is forced to use the corresponding watchtower challenge in its BitVM proof, otherwise it can be disproven.
85/// - `LatestBlockHashSent`: The latest blockhash is committed on Bitcoin, stores the witness of the latest blockhash utxo, which holds the blockhash that should be used by the operator in its BitVM proof.
86/// - `KickoffFinalizerSpent`: The kickoff finalizer is spent, ending the kickoff process, transitions to the `closed` state.
87/// - `BurnConnectorSpent`: The burn connector is spent, ending the kickoff process, transitions to the `closed` state.
88/// - `TimeToSendWatchtowerChallenge`: Time to send a watchtower challenge (used in challenged state), this event notifies the owner to create and send a watchtower challenge tx. Verifiers wait after a kickoff to send a watchtower challenge so that the total work in the watchtower challenge is as high as possible.
89/// - `SavedToDb`: Indicates the state machine has been persisted and resets the dirty flag.
90///
91/// # Behavior
92/// - The state machine maintains a set of matchers to detect relevant Bitcoin transactions and trigger corresponding events.
93/// - It tracks the progress of the kickoff, including challenges, operator actions, and finalization.
94/// - When terminal events occur (e.g., finalizer or burn connector spent), the state machine transitions to `closed` and clears all matchers.
95/// - The state machine interacts with the owner to perform protocol duties (e.g., sending challenges, asserts, or disproves) as required by the protocol logic.
96///
97/// This design ensures that all protocol-critical events related to a kickoff are tracked and handled in a robust, stateful manner, supporting both normal and adversarial scenarios.
98#[serde_as]
99#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
100pub struct KickoffStateMachine<T: Owner> {
101 /// Maps matchers to the resulting kickoff events.
102 #[serde_as(as = "Vec<(_, _)>")]
103 pub(crate) matchers: HashMap<Matcher, KickoffEvent>,
104 /// Indicates if the state machine has unsaved changes that need to be persisted on db.
105 /// dirty flag is set if any matcher matches the current block.
106 /// the flag is set to true in on_transition and on_dispatch
107 /// the flag is set to false after the state machine is saved to db and the event SavedToDb is dispatched
108 pub(crate) dirty: bool,
109 /// The kickoff data associated with the kickoff being tracked.
110 pub(crate) kickoff_data: KickoffData,
111 /// The deposit data that the kickoff tries to withdraw from.
112 pub(crate) deposit_data: DepositData,
113 /// The block height at which the kickoff transaction was mined.
114 pub(crate) kickoff_height: u32,
115 /// The witness for the kickoff transactions input which is a winternitz signature that commits the payout blockhash.
116 pub(crate) payout_blockhash: Witness,
117 /// Marker to indicate if the state machine is in the challenged state.
118 challenged: bool,
119 /// Set of indices of watchtower UTXOs that have already been spent.
120 spent_watchtower_utxos: HashSet<usize>,
121 /// The witness taken from the transaction spending the latest blockhash utxo.
122 latest_blockhash: Witness,
123 /// Saves watchtower challenges with the watchtower index as the key.
124 /// Watchtower challenges are encoded as the output of the watchtower challenge tx.
125 /// (taproot addresses parsed as 32 bytes + OP_RETURN data), in total 144 bytes.
126 watchtower_challenges: HashMap<usize, Transaction>,
127 /// Saves operator asserts with the index of the assert utxo as the key.
128 /// Operator asserts are witnesses that spend the assert utxo's and contain the winternitz signature of the BitVM assertion.
129 operator_asserts: HashMap<usize, Witness>,
130 /// Saves operator challenge acks with the index of the challenge ack utxo as the key.
131 /// Operator challenge acks are witnesses that spend the challenge ack utxo's.
132 /// The witness contains the revealed preimage that can be used to disprove if the operator
133 /// maliciously doesn't include the watchtower challenge in the BitVM proof.
134 operator_challenge_acks: HashMap<usize, Witness>,
135 /// Marker for the generic owner type (phantom data for type safety).
136 /// This is used to ensure that the state machine is generic over the owner type.
137 phantom: std::marker::PhantomData<T>,
138}
139
140impl<T: Owner> BlockMatcher for KickoffStateMachine<T> {
141 type StateEvent = KickoffEvent;
142
143 fn match_block(&self, block: &BlockCache) -> Vec<Self::StateEvent> {
144 self.matchers
145 .iter()
146 .filter_map(|(matcher, kickoff_event)| {
147 matcher.matches(block).map(|ord| (ord, kickoff_event))
148 })
149 .min()
150 .map(|(_, kickoff_event)| kickoff_event)
151 .into_iter()
152 .cloned()
153 .collect()
154 }
155}
156
157impl<T: Owner> KickoffStateMachine<T> {
158 pub fn new(
159 kickoff_data: KickoffData,
160 kickoff_height: u32,
161 deposit_data: DepositData,
162 payout_blockhash: Witness,
163 ) -> Self {
164 Self {
165 kickoff_data,
166 kickoff_height,
167 deposit_data,
168 payout_blockhash,
169 latest_blockhash: Witness::default(),
170 matchers: HashMap::new(),
171 dirty: true,
172 challenged: false,
173 phantom: std::marker::PhantomData,
174 watchtower_challenges: HashMap::new(),
175 operator_asserts: HashMap::new(),
176 spent_watchtower_utxos: HashSet::new(),
177 operator_challenge_acks: HashMap::new(),
178 }
179 }
180}
181
182#[state_machine(
183 initial = "State::kickoff_started()",
184 on_dispatch = "Self::on_dispatch",
185 on_transition = "Self::on_transition",
186 state(derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize))
187)]
188impl<T: Owner> KickoffStateMachine<T> {
189 #[action]
190 pub(crate) fn on_transition(&mut self, state_a: &State, state_b: &State) {
191 tracing::trace!(?self.kickoff_data, ?self.deposit_data, "Transitioning from {:?} to {:?}", state_a, state_b);
192 self.dirty = true;
193 }
194
195 pub fn kickoff_meta(&self, method: &'static str) -> StateMachineError {
196 eyre::eyre!(
197 "Error in kickoff state machine for kickoff {:?} in {}",
198 self.kickoff_data,
199 method
200 )
201 .into()
202 }
203
204 #[action]
205 pub(crate) fn on_dispatch(
206 &mut self,
207 _state: StateOrSuperstate<'_, '_, Self>,
208 evt: &KickoffEvent,
209 ) {
210 if matches!(evt, KickoffEvent::SavedToDb) {
211 self.dirty = false;
212 } else {
213 tracing::trace!(?self.kickoff_data, "Dispatching event {:?}", evt);
214 self.dirty = true;
215
216 // Remove the matcher corresponding to the event.
217 if let Some((matcher, _)) = self.matchers.iter().find(|(_, ev)| ev == &evt) {
218 let matcher = matcher.clone();
219 self.matchers.remove(&matcher);
220 }
221 }
222 }
223
224 /// Checks if the latest blockhash is ready to be committed on Bitcoin.
225 /// The check is done by checking if all watchtower challenge utxos are spent.
226 /// If the check is successful, the a new matcher is created to send latest blockhash tx after finality depth blocks pass from current block height.
227 async fn create_matcher_for_latest_blockhash_if_ready(
228 &mut self,
229 context: &mut StateContext<T>,
230 ) {
231 context
232 .capture_error(async |context| {
233 {
234 // if all watchtower challenge utxos are spent, its safe to send latest blockhash commit tx
235 if self.challenged
236 && self.spent_watchtower_utxos.len()
237 == self.deposit_data.get_num_watchtowers()
238 {
239 // create a matcher to send latest blockhash tx after finality depth blocks pass from current block height
240 self.matchers.insert(
241 Matcher::BlockHeight(
242 context.cache.block_height
243 + context.config.protocol_paramset.finality_depth
244 - 1,
245 ),
246 KickoffEvent::TimeToSendLatestBlockhash,
247 );
248 }
249 Ok::<(), BridgeError>(())
250 }
251 .wrap_err(self.kickoff_meta("on check_if_time_to_commit_latest_blockhash"))
252 })
253 .await;
254 }
255
256 /// Checks if the disprove is ready to be sent on Bitcoin
257 /// The check is done by checking if all operator asserts are received,
258 /// latest blockhash is committed and all watchtower challenge utxos are spent
259 /// If the check is successful, the disprove is sent on Bitcoin
260 async fn disprove_if_ready(&mut self, context: &mut StateContext<T>) {
261 if self.challenged && self.operator_asserts.len() == ClementineBitVMPublicKeys::number_of_assert_txs()
262 && self.latest_blockhash != Witness::default()
263 && self.spent_watchtower_utxos.len() == self.deposit_data.get_num_watchtowers()
264 // check if all operator acks are received, one ack for each watchtower challenge
265 // to make sure we have all preimages required to disprove if operator didn't include
266 // the watchtower challenge in the BitVM proof
267 && self.watchtower_challenges.keys().all(|idx| self.operator_challenge_acks.contains_key(idx))
268 {
269 self.send_disprove(context).await;
270 }
271 }
272
273 /// Checks if the operator asserts are ready to be sent on Bitcoin
274 /// The check is done by checking if all watchtower challenge utxos are spent and latest blockhash is committed
275 /// If the check is successful, the operator asserts are sent on Bitcoin
276 async fn send_operator_asserts_if_ready(&mut self, context: &mut StateContext<T>) {
277 context
278 .capture_error(async |context| {
279 {
280 // if all watchtower challenge utxos are spent and latest blockhash is committed, its safe to send asserts
281 if self.challenged
282 && self.spent_watchtower_utxos.len()
283 == self.deposit_data.get_num_watchtowers()
284 && self.latest_blockhash != Witness::default()
285 {
286 context
287 .dispatch_duty(Duty::SendOperatorAsserts {
288 kickoff_data: self.kickoff_data,
289 deposit_data: self.deposit_data.clone(),
290 watchtower_challenges: self.watchtower_challenges.clone(),
291 payout_blockhash: self.payout_blockhash.clone(),
292 latest_blockhash: self.latest_blockhash.clone(),
293 })
294 .await?;
295 }
296 Ok::<(), BridgeError>(())
297 }
298 .wrap_err(self.kickoff_meta("on send_operator_asserts"))
299 })
300 .await;
301 }
302
303 async fn send_watchtower_challenge(&mut self, context: &mut StateContext<T>) {
304 context
305 .capture_error(async |context| {
306 {
307 context
308 .dispatch_duty(Duty::WatchtowerChallenge {
309 kickoff_data: self.kickoff_data,
310 deposit_data: self.deposit_data.clone(),
311 })
312 .await?;
313 Ok::<(), BridgeError>(())
314 }
315 .wrap_err(self.kickoff_meta("on send_watchtower_challenge"))
316 })
317 .await;
318 }
319
320 async fn send_disprove(&mut self, context: &mut StateContext<T>) {
321 context
322 .capture_error(async |context| {
323 {
324 context
325 .dispatch_duty(Duty::VerifierDisprove {
326 kickoff_data: self.kickoff_data,
327 deposit_data: self.deposit_data.clone(),
328 operator_asserts: self.operator_asserts.clone(),
329 operator_acks: self.operator_challenge_acks.clone(),
330 payout_blockhash: self.payout_blockhash.clone(),
331 latest_blockhash: self.latest_blockhash.clone(),
332 })
333 .await?;
334 Ok::<(), BridgeError>(())
335 }
336 .wrap_err(self.kickoff_meta("on send_disprove"))
337 })
338 .await;
339 }
340
341 async fn send_latest_blockhash(&mut self, context: &mut StateContext<T>) {
342 context
343 .capture_error(async |context| {
344 {
345 context
346 .dispatch_duty(Duty::SendLatestBlockhash {
347 kickoff_data: self.kickoff_data,
348 deposit_data: self.deposit_data.clone(),
349 latest_blockhash: context.cache.block.header.block_hash(),
350 })
351 .await?;
352 Ok::<(), BridgeError>(())
353 }
354 .wrap_err(self.kickoff_meta("on send_latest_blockhash"))
355 })
356 .await;
357 }
358
359 async fn unhandled_event(&mut self, context: &mut StateContext<T>, event: &KickoffEvent) {
360 context
361 .capture_error(async |_context| {
362 let event_str = format!("{event:?}");
363 Err(StateMachineError::UnhandledEvent(event_str))
364 .wrap_err(self.kickoff_meta("kickoff unhandled event"))
365 })
366 .await;
367 }
368
369 /// If the kickoff is challenged, the state machine will add corresponding matchers for
370 /// sending watchtower challenges after some amount of blocks passes since the kickoff was included in Bitcoin.
371 /// Sending watchtower challenges only happen if the kickoff is challenged.
372 /// As sending latest blockhash commit and asserts depend on watchtower challenges/timeouts being sent,
373 /// they will also not be sent if the kickoff is not challenged and kickoff finalizer is spent with ChallengeTimeout,
374 /// which changes the state to "Closed".
375 #[action]
376 pub(crate) async fn on_challenged_entry(&mut self, context: &mut StateContext<T>) {
377 self.challenged = true;
378 context
379 .capture_error(async |context| {
380 {
381 // create times to send necessary challenge asserts
382 self.matchers.insert(
383 Matcher::BlockHeight(
384 self.kickoff_height
385 + context.config.time_to_send_watchtower_challenge as u32,
386 ),
387 KickoffEvent::TimeToSendWatchtowerChallenge,
388 );
389 Ok::<(), BridgeError>(())
390 }
391 .wrap_err(self.kickoff_meta("on_kickoff_started_entry"))
392 })
393 .await;
394 // check if any action is ready to be started as it could already be ready before a challenge arrives
395 // but we want to make sure kickoff is actually challenged before we start sending actions
396 self.create_matcher_for_latest_blockhash_if_ready(context)
397 .await;
398 self.send_operator_asserts_if_ready(context).await;
399 self.disprove_if_ready(context).await;
400 }
401
402 /// State that is entered when the kickoff is challenged
403 /// It only includes special handling for the TimeToSendWatchtowerChallenge event
404 /// All other events are handled in the kickoff superstate
405 #[state(superstate = "kickoff", entry_action = "on_challenged_entry")]
406 pub(crate) async fn challenged(
407 &mut self,
408 event: &KickoffEvent,
409 context: &mut StateContext<T>,
410 ) -> Response<State> {
411 match event {
412 KickoffEvent::WatchtowerChallengeSent { .. }
413 | KickoffEvent::OperatorAssertSent { .. }
414 | KickoffEvent::OperatorChallengeAckSent { .. }
415 | KickoffEvent::KickoffFinalizerSpent
416 | KickoffEvent::BurnConnectorSpent
417 | KickoffEvent::WatchtowerChallengeTimeoutSent { .. }
418 | KickoffEvent::LatestBlockHashSent { .. }
419 | KickoffEvent::TimeToSendLatestBlockhash
420 | KickoffEvent::SavedToDb => Super,
421 KickoffEvent::TimeToSendWatchtowerChallenge => {
422 self.send_watchtower_challenge(context).await;
423 Handled
424 }
425 _ => {
426 self.unhandled_event(context, event).await;
427 Handled
428 }
429 }
430 }
431
432 #[superstate]
433 async fn kickoff(
434 &mut self,
435 event: &KickoffEvent,
436 context: &mut StateContext<T>,
437 ) -> Response<State> {
438 tracing::trace!("Received event in kickoff superstate: {:?}", event);
439 match event {
440 // When a watchtower challenge is detected in Bitcoin,
441 // save the full challenge transaction and check if the latest blockhash can be committed
442 // and if the disprove is ready to be sent
443 KickoffEvent::WatchtowerChallengeSent {
444 watchtower_idx,
445 challenge_outpoint,
446 } => {
447 self.spent_watchtower_utxos.insert(*watchtower_idx);
448 let tx = context
449 .cache
450 .get_tx_of_utxo(challenge_outpoint)
451 .expect("Challenge outpoint that got matched should be in block");
452 // save challenge witness
453 self.watchtower_challenges
454 .insert(*watchtower_idx, tx.clone());
455 self.create_matcher_for_latest_blockhash_if_ready(context)
456 .await;
457 self.send_operator_asserts_if_ready(context).await;
458 self.disprove_if_ready(context).await;
459 Handled
460 }
461 // When an operator assert is detected in Bitcoin,
462 // save the assert witness (which is the BitVM winternitz commit)
463 // and check if the disprove is ready to be sent
464 KickoffEvent::OperatorAssertSent {
465 assert_idx,
466 assert_outpoint,
467 } => {
468 let witness = context
469 .cache
470 .get_witness_of_utxo(assert_outpoint)
471 .expect("Assert outpoint that got matched should be in block");
472 // save assert witness
473 self.operator_asserts.insert(*assert_idx, witness);
474 self.disprove_if_ready(context).await;
475 Handled
476 }
477 // When an operator challenge ack is detected in Bitcoin,
478 // save the ack witness as the witness includes the revealed preimage that
479 // can be used to disprove if the operator maliciously doesn't include the
480 // watchtower challenge in the BitVM proof
481 KickoffEvent::OperatorChallengeAckSent {
482 watchtower_idx,
483 challenge_ack_outpoint,
484 } => {
485 let witness = context
486 .cache
487 .get_witness_of_utxo(challenge_ack_outpoint)
488 .expect("Challenge ack outpoint that got matched should be in block");
489 // save challenge ack witness
490 self.operator_challenge_acks
491 .insert(*watchtower_idx, witness);
492 self.disprove_if_ready(context).await;
493 Handled
494 }
495 // When the kickoff finalizer is spent in Bitcoin,
496 // the kickoff process is finished and the state machine will transition to the "Closed" state
497 KickoffEvent::KickoffFinalizerSpent => Transition(State::closed()),
498 // When the burn connector of the operator is spent in Bitcoin, it means the operator cannot continue with any more kickoffs
499 // (unless burn connector is spent by ready to reimburse tx), so the state machine will transition to the "Closed" state
500 KickoffEvent::BurnConnectorSpent => {
501 tracing::error!(
502 "Burn connector spent before kickoff was finalized for kickoff {:?}",
503 self.kickoff_data
504 );
505 Transition(State::closed())
506 }
507 // When a watchtower challenge timeout is detected in Bitcoin,
508 // set the watchtower utxo as spent and check if the latest blockhash can be committed
509 KickoffEvent::WatchtowerChallengeTimeoutSent { watchtower_idx } => {
510 self.spent_watchtower_utxos.insert(*watchtower_idx);
511 self.create_matcher_for_latest_blockhash_if_ready(context)
512 .await;
513 self.send_operator_asserts_if_ready(context).await;
514 self.disprove_if_ready(context).await;
515 Handled
516 }
517 // When the latest blockhash is detected in Bitcoin,
518 // save the witness which includes the blockhash and check if the operator asserts and
519 // disprove tx are ready to be sent
520 KickoffEvent::LatestBlockHashSent {
521 latest_blockhash_outpoint,
522 } => {
523 let witness = context
524 .cache
525 .get_witness_of_utxo(latest_blockhash_outpoint)
526 .expect("Latest blockhash outpoint that got matched should be in block");
527 // save latest blockhash witness
528 self.latest_blockhash = witness;
529 // can start sending asserts as latest blockhash is committed and finalized
530 self.send_operator_asserts_if_ready(context).await;
531 self.disprove_if_ready(context).await;
532 Handled
533 }
534 KickoffEvent::TimeToSendLatestBlockhash => {
535 // tell owner to send latest blockhash tx
536 self.send_latest_blockhash(context).await;
537 Handled
538 }
539 KickoffEvent::SavedToDb => Handled,
540 _ => {
541 self.unhandled_event(context, event).await;
542 Handled
543 }
544 }
545 }
546
547 /// State that is entered when the kickoff is started
548 /// It will transition to the "Challenged" state if the kickoff is challenged
549 #[state(superstate = "kickoff", entry_action = "on_kickoff_started_entry")]
550 pub(crate) async fn kickoff_started(
551 &mut self,
552 event: &KickoffEvent,
553 context: &mut StateContext<T>,
554 ) -> Response<State> {
555 match event {
556 KickoffEvent::Challenged => {
557 tracing::warn!("Warning: Operator challenged: {:?}", self.kickoff_data);
558 Transition(State::challenged())
559 }
560 KickoffEvent::WatchtowerChallengeSent { .. }
561 | KickoffEvent::OperatorAssertSent { .. }
562 | KickoffEvent::OperatorChallengeAckSent { .. }
563 | KickoffEvent::KickoffFinalizerSpent
564 | KickoffEvent::BurnConnectorSpent
565 | KickoffEvent::WatchtowerChallengeTimeoutSent { .. }
566 | KickoffEvent::LatestBlockHashSent { .. }
567 | KickoffEvent::TimeToSendLatestBlockhash
568 | KickoffEvent::SavedToDb => Super,
569 _ => {
570 self.unhandled_event(context, event).await;
571 Handled
572 }
573 }
574 }
575
576 /// Adds the default matchers that will be used if the state is "challenged" or "kickoff_started".
577 /// These matchers are used to detect when various transactions in the contract are mined on Bitcoin.
578 async fn add_default_kickoff_matchers(
579 &mut self,
580 context: &mut StateContext<T>,
581 ) -> Result<(), BridgeError> {
582 // First create all transactions for the current deposit
583 let contract_context = ContractContext::new_context_for_kickoff(
584 self.kickoff_data,
585 self.deposit_data.clone(),
586 context.config.protocol_paramset,
587 );
588 let mut txhandlers = {
589 let mut guard = context.shared_dbtx.lock().await;
590 context
591 .owner
592 .create_txhandlers(
593 &mut guard,
594 TransactionType::AllNeededForDeposit,
595 contract_context,
596 )
597 .await?
598 };
599 let kickoff_txhandler =
600 remove_txhandler_from_map(&mut txhandlers, TransactionType::Kickoff)?;
601
602 // add operator asserts
603 let kickoff_txid = *kickoff_txhandler.get_txid();
604 let num_asserts = crate::bitvm_client::ClementineBitVMPublicKeys::number_of_assert_txs();
605 for assert_idx in 0..num_asserts {
606 let mini_assert_vout = UtxoVout::Assert(assert_idx).get_vout();
607 let assert_timeout_txhandler = remove_txhandler_from_map(
608 &mut txhandlers,
609 TransactionType::AssertTimeout(assert_idx),
610 )?;
611 let assert_timeout_txid = assert_timeout_txhandler.get_txid();
612 // Assert transactions can have any txid (there is no enforcement on how the assert utxo is spent, just that
613 // spending assert utxo reveals the BitVM winternitz commit in the utxo's witness)
614 // But assert timeouts are nofn signed transactions with a fixed txid, so we can detect assert transactions
615 // by checking if the assert utxo is spent but not by the assert timeout tx
616 self.matchers.insert(
617 Matcher::SpentUtxoButNotTxid(
618 OutPoint {
619 txid: kickoff_txid,
620 vout: mini_assert_vout,
621 },
622 vec![*assert_timeout_txid],
623 ),
624 KickoffEvent::OperatorAssertSent {
625 assert_outpoint: OutPoint {
626 txid: kickoff_txid,
627 vout: mini_assert_vout,
628 },
629 assert_idx,
630 },
631 );
632 }
633 // add latest blockhash tx sent matcher
634 let latest_blockhash_timeout_txhandler =
635 remove_txhandler_from_map(&mut txhandlers, TransactionType::LatestBlockhashTimeout)?;
636 let latest_blockhash_timeout_txid = latest_blockhash_timeout_txhandler.get_txid();
637 let latest_blockhash_outpoint = OutPoint {
638 txid: kickoff_txid,
639 vout: UtxoVout::LatestBlockhash.get_vout(),
640 };
641 // Same logic as before with assert transaction detection, if latest blockhash utxo is not spent by latest blockhash timeout tx,
642 // it means the latest blockhash is committed on Bitcoin
643 self.matchers.insert(
644 Matcher::SpentUtxoButNotTxid(
645 latest_blockhash_outpoint,
646 vec![*latest_blockhash_timeout_txid],
647 ),
648 KickoffEvent::LatestBlockHashSent {
649 latest_blockhash_outpoint,
650 },
651 );
652 // add watchtower challenges and challenge acks matchers
653 for watchtower_idx in 0..self.deposit_data.get_num_watchtowers() {
654 let watchtower_challenge_vout =
655 UtxoVout::WatchtowerChallenge(watchtower_idx).get_vout();
656 let watchtower_timeout_txhandler = remove_txhandler_from_map(
657 &mut txhandlers,
658 TransactionType::WatchtowerChallengeTimeout(watchtower_idx),
659 )?;
660 let watchtower_timeout_txid = watchtower_timeout_txhandler.get_txid();
661 // matcher in case watchtower challenge timeout is sent
662 self.matchers.insert(
663 Matcher::SentTx(*watchtower_timeout_txid),
664 KickoffEvent::WatchtowerChallengeTimeoutSent { watchtower_idx },
665 );
666 // matcher in case watchtower challenge is sent (watchtower challenge utxo is spent but not by watchtower challenge timeout tx)
667 self.matchers.insert(
668 Matcher::SpentUtxoButNotTxid(
669 OutPoint {
670 txid: kickoff_txid,
671 vout: watchtower_challenge_vout,
672 },
673 vec![*watchtower_timeout_txid],
674 ),
675 KickoffEvent::WatchtowerChallengeSent {
676 watchtower_idx,
677 challenge_outpoint: OutPoint {
678 txid: kickoff_txid,
679 vout: watchtower_challenge_vout,
680 },
681 },
682 );
683 // add operator challenge ack matcher
684 let operator_challenge_ack_vout =
685 UtxoVout::WatchtowerChallengeAck(watchtower_idx).get_vout();
686 let operator_challenge_nack_txhandler = remove_txhandler_from_map(
687 &mut txhandlers,
688 TransactionType::OperatorChallengeNack(watchtower_idx),
689 )?;
690 let operator_challenge_nack_txid = operator_challenge_nack_txhandler.get_txid();
691 // operator challenge ack utxo is spent but not by operator challenge nack tx or watchtower challenge timeout tx
692 self.matchers.insert(
693 Matcher::SpentUtxoButNotTxid(
694 OutPoint {
695 txid: kickoff_txid,
696 vout: operator_challenge_ack_vout,
697 },
698 vec![*operator_challenge_nack_txid, *watchtower_timeout_txid],
699 ),
700 KickoffEvent::OperatorChallengeAckSent {
701 watchtower_idx,
702 challenge_ack_outpoint: OutPoint {
703 txid: kickoff_txid,
704 vout: operator_challenge_ack_vout,
705 },
706 },
707 );
708 }
709
710 // add burn connector tx spent matcher
711 // Burn connector can also be spent in ready to reimburse tx, but before spending burn connector that way,
712 // the kickoff finalizer needs to be spent first, otherwise pre-signed "Kickoff not finalized" tx can be sent by
713 // any verifier, slashing the operator.
714 // If the kickoff finalizer is spent first, the state will be in "Closed" state and all matchers will be deleted.
715 let round_txhandler = remove_txhandler_from_map(&mut txhandlers, TransactionType::Round)?;
716 let round_txid = *round_txhandler.get_txid();
717 self.matchers.insert(
718 Matcher::SpentUtxo(OutPoint {
719 txid: round_txid,
720 vout: UtxoVout::CollateralInRound.get_vout(),
721 }),
722 KickoffEvent::BurnConnectorSpent,
723 );
724 // add kickoff finalizer utxo spent matcher
725 self.matchers.insert(
726 Matcher::SpentUtxo(OutPoint {
727 txid: kickoff_txid,
728 vout: UtxoVout::KickoffFinalizer.get_vout(),
729 }),
730 KickoffEvent::KickoffFinalizerSpent,
731 );
732 // add challenge detector matcher, if challenge utxo is not spent by challenge timeout tx, it means the kickoff is challenged
733 let challenge_timeout_txhandler =
734 remove_txhandler_from_map(&mut txhandlers, TransactionType::ChallengeTimeout)?;
735 let challenge_timeout_txid = challenge_timeout_txhandler.get_txid();
736 self.matchers.insert(
737 Matcher::SpentUtxoButNotTxid(
738 OutPoint {
739 txid: kickoff_txid,
740 vout: UtxoVout::Challenge.get_vout(),
741 },
742 vec![*challenge_timeout_txid],
743 ),
744 KickoffEvent::Challenged,
745 );
746 Ok(())
747 }
748
749 #[action]
750 pub(crate) async fn on_kickoff_started_entry(&mut self, context: &mut StateContext<T>) {
751 context
752 .capture_error(async |context| {
753 {
754 // Add all watchtower challenges and operator asserts to matchers
755 self.add_default_kickoff_matchers(context).await?;
756 Ok::<(), BridgeError>(())
757 }
758 .wrap_err(self.kickoff_meta("on_kickoff_started_entry"))
759 })
760 .await;
761 }
762
763 /// Clears all matchers when the state is "closed".
764 /// This means the state machine will not do any more actions anymore.
765 #[action]
766 #[allow(unused_variables)]
767 pub(crate) async fn on_closed_entry(&mut self, context: &mut StateContext<T>) {
768 self.matchers.clear();
769 }
770
771 #[state(entry_action = "on_closed_entry")]
772 // Terminal state when the kickoff process ends
773 #[allow(unused_variables)]
774 pub(crate) async fn closed(
775 &mut self,
776 event: &KickoffEvent,
777 context: &mut StateContext<T>,
778 ) -> Response<State> {
779 Handled
780 }
781}