Struct KickoffStateMachine

pub struct KickoffStateMachine<T: Owner> {
    pub(crate) matchers: HashMap<Matcher, KickoffEvent>,
    pub(crate) dirty: bool,
    pub(crate) kickoff_data: KickoffData,
    pub(crate) deposit_data: DepositData,
    pub(crate) kickoff_height: u32,
    pub(crate) payout_blockhash: Witness,
    spent_watchtower_utxos: HashSet<usize>,
    latest_blockhash: Witness,
    watchtower_challenges: HashMap<usize, Transaction>,
    operator_asserts: HashMap<usize, Witness>,
    operator_challenge_acks: HashMap<usize, Witness>,
    phantom: PhantomData<T>,
}

State machine for tracking a single kickoff process in the protocol.

Purpose

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.

States

• 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)
• challenged: Entered if the kickoff is challenged. Watchtower challenges are only sent if the kickoff is challenged.
• closed: Terminal state indicating the kickoff process has ended, either by kickoff finalizer utxo or burn connector utxo being spent.

Events

• Challenged: The kickoff is challenged, transitioning to the challenged state.
• WatchtowerChallengeSent: A watchtower challenge is detected on Bitcoin, stores the watchtower challenge transaction, and stores the watchtower utxo as spent.
• OperatorAssertSent: An operator BitVM assert is detected, stores the witness of the assert utxo.
• WatchtowerChallengeTimeoutSent: A watchtower challenge timeout is detected, stores watchtower utxo as spent.
• 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.
• 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.
• KickoffFinalizerSpent: The kickoff finalizer is spent, ending the kickoff process, transitions to the closed state.
• BurnConnectorSpent: The burn connector is spent, ending the kickoff process, transitions to the closed state.
• 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.
• SavedToDb: Indicates the state machine has been persisted and resets the dirty flag.

Behavior

• The state machine maintains a set of matchers to detect relevant Bitcoin transactions and trigger corresponding events.
• It tracks the progress of the kickoff, including challenges, operator actions, and finalization.
• When terminal events occur (e.g., finalizer or burn connector spent), the state machine transitions to closed and clears all matchers.
• The state machine interacts with the owner to perform protocol duties (e.g., sending challenges, asserts, or disproves) as required by the protocol logic.

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.

Fields

matchers: HashMap<Matcher, KickoffEvent>

Maps matchers to the resulting kickoff events.

dirty: bool

Indicates if the state machine has unsaved changes that need to be persisted on db. dirty flag is set if any matcher matches the current block. the flag is set to true in on_transition and on_dispatch the flag is set to false after the state machine is saved to db and the event SavedToDb is dispatched

kickoff_data: KickoffData

The kickoff data associated with the kickoff being tracked.

deposit_data: DepositData

The deposit data that the kickoff tries to withdraw from.

kickoff_height: u32

The block height at which the kickoff transaction was mined.

payout_blockhash: Witness

The witness for the kickoff transactions input which is a winternitz signature that commits the payout blockhash.

spent_watchtower_utxos: HashSet<usize>

Set of indices of watchtower UTXOs that have already been spent.

latest_blockhash: Witness

The witness taken from the transaction spending the latest blockhash utxo.

watchtower_challenges: HashMap<usize, Transaction>

Saves watchtower challenges with the watchtower index as the key. Watchtower challenges are encoded as the output of the watchtower challenge tx. (taproot addresses parsed as 32 bytes + OP_RETURN data), in total 144 bytes.

operator_asserts: HashMap<usize, Witness>

Saves operator asserts with the index of the assert utxo as the key. Operator asserts are witnesses that spend the assert utxo’s and contain the winternitz signature of the BitVM assertion.

operator_challenge_acks: HashMap<usize, Witness>

Saves operator challenge acks with the index of the challenge ack utxo as the key. Operator challenge acks are witnesses that spend the challenge ack utxo’s. The witness contains the revealed preimage that can be used to disprove if the operator maliciously doesn’t include the watchtower challenge in the BitVM proof.

phantom: PhantomData<T>

Marker for the generic owner type (phantom data for type safety). This is used to ensure that the state machine is generic over the owner type.

Implementations

impl<T: Owner> KickoffStateMachine<T>

pub fn new( kickoff_data: KickoffData, kickoff_height: u32, deposit_data: DepositData, payout_blockhash: Witness, ) -> Self

impl<T: Owner> KickoffStateMachine<T>

pub(crate) fn on_transition(&mut self, state_a: &State, state_b: &State)

pub fn kickoff_meta(&self, method: &'static str) -> StateMachineError

pub(crate) fn on_dispatch( &mut self, _state: StateOrSuperstate<'_, '_, Self>, evt: &KickoffEvent, )

async fn create_matcher_for_latest_blockhash_if_ready( &mut self, context: &mut StateContext<T>, )

Checks if the latest blockhash is ready to be committed on Bitcoin. The check is done by checking if all watchtower challenge utxos are spent. 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.

async fn disprove_if_ready(&mut self, context: &mut StateContext<T>)

Checks if the disprove is ready to be sent on Bitcoin The check is done by checking if all operator asserts are received, latest blockhash is committed and all watchtower challenge utxos are spent If the check is successful, the disprove is sent on Bitcoin

async fn send_operator_asserts_if_ready( &mut self, context: &mut StateContext<T>, )

Checks if the operator asserts are ready to be sent on Bitcoin The check is done by checking if all watchtower challenge utxos are spent and latest blockhash is committed If the check is successful, the operator asserts are sent on Bitcoin

async fn send_watchtower_challenge(&mut self, context: &mut StateContext<T>)

async fn send_disprove(&mut self, context: &mut StateContext<T>)

async fn send_latest_blockhash(&mut self, context: &mut StateContext<T>)

async fn unhandled_event( &mut self, context: &mut StateContext<T>, event: &KickoffEvent, )

pub(crate) async fn on_challenged_entry( &mut self, context: &mut StateContext<T>, )

If the kickoff is challenged, the state machine will add corresponding matchers for sending watchtower challenges after some amount of blocks passes since the kickoff was included in Bitcoin. Sending watchtower challenges only happen if the kickoff is challenged. As sending latest blockhash commit and asserts depend on watchtower challenges/timeouts being sent, they will also not be sent if the kickoff is not challenged and kickoff finalizer is spent with ChallengeTimeout, which changes the state to “Closed”.

pub(crate) async fn challenged( &mut self, event: &KickoffEvent, context: &mut StateContext<T>, ) -> Response<State>

State that is entered when the kickoff is challenged It only includes special handling for the TimeToSendWatchtowerChallenge event All other events are handled in the kickoff superstate

async fn kickoff( &mut self, event: &KickoffEvent, context: &mut StateContext<T>, ) -> Response<State>

pub(crate) async fn kickoff_started( &mut self, event: &KickoffEvent, context: &mut StateContext<T>, ) -> Response<State>

State that is entered when the kickoff is started It will transition to the “Challenged” state if the kickoff is challenged

async fn add_default_kickoff_matchers( &mut self, context: &mut StateContext<T>, ) -> Result<(), BridgeError>

Adds the default matchers that will be used if the state is “challenged” or “kickoff_started”. These matchers are used to detect when various transactions in the contract are mined on Bitcoin.

pub(crate) async fn on_kickoff_started_entry( &mut self, context: &mut StateContext<T>, )

pub(crate) async fn on_closed_entry(&mut self, context: &mut StateContext<T>)

Clears all matchers when the state is “closed”. This means the state machine will not do any more actions anymore.

pub(crate) async fn closed( &mut self, event: &KickoffEvent, context: &mut StateContext<T>, ) -> Response<State>

Trait Implementations

impl<T: Owner> BlockMatcher for KickoffStateMachine<T>

type StateEvent = KickoffEvent

fn match_block(&self, block: &BlockCache) -> Vec<Self::StateEvent>

impl<T: Clone + Owner> Clone for KickoffStateMachine<T>

fn clone(&self) -> KickoffStateMachine<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug + Owner> Debug for KickoffStateMachine<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, T: Owner> Deserialize<'de> for KickoffStateMachine<T>

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T: Owner> IntoStateMachine for KickoffStateMachine<T>

const INITIAL: State

Initial state of the state machine.

const ON_TRANSITION: fn(_: &mut Self, _: &Self::State, _: &Self::State) = Self::on_transition

Method that is called after every transition.

const ON_DISPATCH: fn(_: &mut Self, _: StateOrSuperstate<'_, '_, Self>, _: &Self::Event<'_>) = Self::on_dispatch

Method that is called before an event is dispatched to a state or superstate handler.

type Event<'event> = KickoffEvent

Event that is processed by the state machine.

type Context<'context> = StateContext<T>

External context that can be passed in.

type State = State

Enumeration of the various states.

type Superstate<'sub> = Superstate

Enumeration of the various superstates.

impl<T: PartialEq + Owner> PartialEq for KickoffStateMachine<T>

fn eq(&self, other: &KickoffStateMachine<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: Owner> Serialize for KickoffStateMachine<T>

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<T: Owner> State<KickoffStateMachine<T>> for State

fn call_handler<'fut>( &'fut mut self, shared_storage: &'fut mut KickoffStateMachine<T>, event: &'fut <KickoffStateMachine<T> as IntoStateMachine>::Event<'_>, context: &'fut mut <KickoffStateMachine<T> as IntoStateMachine>::Context<'_>, ) -> Pin<Box<dyn Future<Output = Response<Self>> + Send + 'fut>>

Call the handler for the current state and let it handle the given event.

fn call_entry_action<'fut>( &'fut mut self, shared_storage: &'fut mut KickoffStateMachine<T>, context: &'fut mut <KickoffStateMachine<T> as IntoStateMachine>::Context<'_>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'fut>>

Call the entry action for the current state.

fn call_exit_action<'fut>( &'fut mut self, shared_storage: &'fut mut KickoffStateMachine<T>, context: &'fut mut <KickoffStateMachine<T> as IntoStateMachine>::Context<'_>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'fut>>

Call the exit action for the current state.

fn superstate( &mut self, ) -> Option<<KickoffStateMachine<T> as IntoStateMachine>::Superstate<'_>>

Return the superstate of the current state, if there is one.

impl<'sub, T: Owner> Superstate<KickoffStateMachine<T>> for Superstate

where Self: 'sub,

fn call_handler<'fut>( &'fut mut self, shared_storage: &'fut mut KickoffStateMachine<T>, event: &'fut <KickoffStateMachine<T> as IntoStateMachine>::Event<'_>, context: &'fut mut <KickoffStateMachine<T> as IntoStateMachine>::Context<'_>, ) -> Pin<Box<dyn Future<Output = Response<<KickoffStateMachine<T> as IntoStateMachine>::State>> + Send + 'fut>>

Call the handler for the current superstate.

fn call_entry_action<'fut>( &'fut mut self, shared_storage: &'fut mut KickoffStateMachine<T>, context: &'fut mut <KickoffStateMachine<T> as IntoStateMachine>::Context<'_>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'fut>>

Call the entry action for the current superstate.

fn call_exit_action<'fut>( &'fut mut self, shared_storage: &'fut mut KickoffStateMachine<T>, context: &'fut mut <KickoffStateMachine<T> as IntoStateMachine>::Context<'_>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'fut>>

Call the exit action for the current superstate.

fn superstate( &mut self, ) -> Option<<KickoffStateMachine<T> as IntoStateMachine>::Superstate<'_>>

Return the superstate of the current superstate, if there is one.

impl<T: Eq + Owner> Eq for KickoffStateMachine<T>

impl<T: Owner> StructuralPartialEq for KickoffStateMachine<T>