babylon_apis/
finality_api.rs

1/// Finality messages / API
2/// The definitions here roughly follow the same structure as the equivalent IBC protobuf pub struct types,
3/// defined in `packages/proto/src/gen/babylon.finality.v1.rs`
4use cosmwasm_schema::cw_serde;
5use cosmwasm_std::Binary;
6
7use babylon_merkle::Proof;
8
9use crate::Bytes;
10
11#[cw_serde]
12/// babylon_finality execution handlers
13pub enum ExecuteMsg {
14    /// Change the admin
15    UpdateAdmin { admin: Option<String> },
16    /// Set the BTC staking addr.
17    /// Only admin or the babylon contract can set this
18    UpdateStaking { staking: String },
19    /// Committing a sequence of public randomness for EOTS
20    CommitPublicRandomness {
21        /// BTC PK of the finality provider that commits the public randomness
22        fp_pubkey_hex: String,
23        /// Start block height of the list of public randomness
24        start_height: u64,
25        /// Amount of public randomness committed
26        num_pub_rand: u64,
27        /// Commitment of these public randomness values.
28        /// Currently, it's the root of the Merkle tree that includes the public randomness
29        commitment: Binary,
30        /// Signature on (start_height || num_pub_rand || commitment) signed by
31        /// the SK corresponding to `fp_pubkey_hex`.
32        /// This prevents others committing public randomness on behalf of `fp_pubkey_hex`
33        signature: Binary,
34    },
35    /// Submit Finality Signature.
36    ///
37    /// This is a message that can be called by a finality provider to submit their finality
38    /// signature to the Consumer chain.
39    /// The signature is verified by the Consumer chain using the finality provider's public key
40    ///
41    /// This message is equivalent to the `MsgAddFinalitySig` message in the Babylon finality protobuf
42    /// defs.
43    SubmitFinalitySignature {
44        fp_pubkey_hex: String,
45        height: u64,
46        pub_rand: Binary,
47        proof: Proof,
48        // FIXME: Rename to block_app_hash for consistency / clarity
49        block_hash: Binary,
50        signature: Binary,
51    },
52    /// Unjails finality provider.
53    /// Admin can unjail anyone anytime, others can unjail only themselves, and only if the jail
54    /// period passed.
55    Unjail {
56        /// FP to unjail
57        fp_pubkey_hex: String,
58    },
59}
60
61/// Represents the necessary metadata and finalization status of a block.
62#[cw_serde]
63pub struct IndexedBlock {
64    /// Height of the block.
65    pub height: u64,
66    /// AppHash of the block.
67    pub app_hash: Bytes,
68    /// Whether the IndexedBlock is finalised by 2/3 of the finality providers or not.
69    pub finalized: bool,
70}
71
72/// Represents a commitment to a series of public randomness.
73/// Currently, the commitment is a root of a Merkle tree that includes a series of public randomness
74/// values
75#[cw_serde]
76pub struct PubRandCommit {
77    /// Height of the first commitment.
78    pub start_height: u64,
79    /// Number of committed public randomness.
80    pub num_pub_rand: u64,
81    /// Height that the commit was submitted.
82    pub height: u64,
83    /// Value of the commitment.
84    /// Currently, it's the root of the Merkle tree constructed by the public randomness
85    pub commitment: Bytes,
86}
87
88impl PubRandCommit {
89    /// Checks if the given height is within the range of the commitment
90    pub fn in_range(&self, height: u64) -> bool {
91        self.start_height <= height && height <= self.end_height()
92    }
93
94    /// Returns the height of the last commitment
95    pub fn end_height(&self) -> u64 {
96        self.start_height + self.num_pub_rand - 1
97    }
98}
99
100/// Evidence is the evidence that a finality provider has signed finality
101/// signatures with correct public randomness on two conflicting Babylon headers
102#[cw_serde]
103pub struct Evidence {
104    /// BTC PK of the finality provider that casts this vote
105    pub fp_btc_pk: Bytes,
106    /// Height of the conflicting blocks
107    pub block_height: u64,
108    /// Public randomness the finality provider has committed to.
109    /// Deserializes to `SchnorrPubRand`
110    pub pub_rand: Bytes,
111    /// AppHash of the canonical block
112    pub canonical_app_hash: Bytes,
113    /// AppHash of the fork block
114    pub fork_app_hash: Bytes,
115    /// Finality signature to the canonical block,
116    /// where finality signature is an EOTS signature, i.e.,
117    /// the `s` in a Schnorr signature `(r, s)`.
118    /// `r` is the public randomness already committed by the finality provider.
119    /// Deserializes to `SchnorrEOTSSig`
120    pub canonical_finality_sig: Bytes,
121    /// Finality signature to the fork block,
122    /// where finality signature is an EOTS signature.
123    /// Deserializes to `SchnorrEOTSSig`
124    pub fork_finality_sig: Bytes,
125}
126
127#[cw_serde]
128pub enum SudoMsg {
129    /// The SDK should call SudoMsg::BeginBlock{} once per block (in BeginBlock).
130    /// It allows the staking module to index the BTC height, and update the power
131    /// distribution of the active Finality Providers.
132    BeginBlock {
133        hash_hex: String,
134        app_hash_hex: String,
135    },
136    /// The SDK should call SudoMsg::EndBlock{} once per block (in EndBlock).
137    /// It allows the finality module to index blocks and tally the finality provider votes
138    EndBlock {
139        hash_hex: String,
140        app_hash_hex: String,
141    },
142}
babylon_apis/finality_api.rs

babylon_apis/
finality_api.rs
