MsgSelectiveSlashingEvidence
Upon MsgSelectiveSlashingEvidence, a Babylon node will execute as follows:
-
-
- Find the BTC delegation with the given staking transaction hash.
- Ensure the BTC delegation is active or unbonding.
- Ensure the given secret key corresponds to the finality provider's public key. diff --git a/static/remote-docs/guides/architecture/btc_staking_program/finality_providers.html b/static/remote-docs/guides/architecture/btc_staking_program/finality_providers.html index ca123d52..7985a1e8 100644 --- a/static/remote-docs/guides/architecture/btc_staking_program/finality_providers.html +++ b/static/remote-docs/guides/architecture/btc_staking_program/finality_providers.html @@ -55,7 +55,7 @@
- State
- Parameters -
- ChainInfo -
- EpochChainInfo -
- CanonicalChain -
- Fork +
- LatestEpochHeaders +
- FinalizedEpochHeaders +
- BSNBTCState
- Params
- Port
- LastSentBTCSegment @@ -100,8 +99,7 @@
Table of contents
- Extract the header info and the client state from the message
- Determine if the header is on a fork by checking if the client is frozen
- Call
HandleHeaderWithValidCommitto process the header
- - If the PoS system hosting the header is not known to Babylon Genesis,
-initialize
ChainInfostorage for the PoS system
- - If the header is on a fork, insert the header to the fork storage and update
-
ChainInfo
- - If the header is canonical, insert the header to the canonical chain storage
-and update
ChainInfo
- - Unfreeze the client if it was frozen due to a fork header +
- Check if the BSN is registered through the
btcstkconsumermodule and is a Cosmos BSN; if not, ignore the header
+ - Create an
IndexedHeaderwith the header metadata and Babylon context
+ - If the header is not on a fork and is newer than the existing latest header, +update the latest epoch header for the BSN +
- Log fork events for monitoring and debugging purposes
Finality Provider
Finality Provider for Consumer Networks Specification
For detailed technical specifications and requirements of the finality provider -program for Consumer networks, please see SPEC-CONSUMER.md. +program for Consumer networks, please see ./docs/SPEC-CONSUMER.md. The spec document outlines the Consumer's interfaces, message handlers and queries. It also provides guidance for integrators.
diff --git a/static/remote-docs/guides/architecture/consumer_zone_programs/babylon_contracts.html b/static/remote-docs/guides/architecture/consumer_zone_programs/babylon_contracts.html index 7ae31a48..2154820e 100644 --- a/static/remote-docs/guides/architecture/consumer_zone_programs/babylon_contracts.html +++ b/static/remote-docs/guides/architecture/consumer_zone_programs/babylon_contracts.html @@ -74,6 +74,9 @@Integration tests the contract
the integration tests.cargo run-script integration
E2E tests
+cargo run-script e2e
+Generate the schema
cargo run-script gen-schema
Table of contents
State
-The Zone Concierge module keeps handling IBC headers of PoS systems, and -maintains the following KV stores.
+The Zone Concierge module maintains a simplified header indexing system with the following KV stores. Consumer registration is handled by the btcstkconsumer module.
Parameters
The parameter storage maintains the Zone Concierge module's parameters. The Zone Concierge module's parameters are represented as a @@ -117,54 +115,36 @@
Parameters
[ (gogoproto.moretags) = "yaml:\"ibc_packet_timeout_seconds\"" ]; } -ChainInfo
-The chain info storage maintains ChainInfo
-for each PoS system. The key is the PoS system's ConsumerID, which is the ID
-of the IBC light client. The value is a ChainInfo object. The ChainInfo is a
-structure storing the information of a PoS system that checkpoints to Babylon
-Genesis.
// ChainInfo is the information of a Consumer
-message ChainInfo {
- // consumer_id is the ID of the consumer
- string consumer_id = 1;
- // latest_header is the latest header in the Consumer's canonical chain
- IndexedHeader latest_header = 2;
- // latest_forks is the latest forks, formed as a series of IndexedHeader (from
- // low to high)
- Forks latest_forks = 3;
- // timestamped_headers_count is the number of timestamped headers in the Consumer's
- // canonical chain
- uint64 timestamped_headers_count = 4;
-}
-EpochChainInfo
-The epoch chain info storage maintains
-ChainInfo at the end of each Babylon epoch for each PoS system. The key is the
-PoS system's ConsumerID plus the epoch number, and the value is a ChainInfo
-object.
CanonicalChain
-The canonical chain storage maintains the
-metadata of canonical IBC headers of a PoS system. The key is the BSN's
-ConsumerID plus the height, and the value is a IndexedHeader object.
-IndexedHeader is a structure storing IBC header's metadata.
// IndexedHeader is the metadata of a Consumer header
+LatestEpochHeaders
+The latest epoch headers storage maintains
+the most recent header received from each BSN during the current epoch. The
+key is the BSN's ConsumerID, and the value is an IndexedHeader object.
+This storage is cleared at the end of each epoch when headers are moved to the
+finalized storage.
+FinalizedEpochHeaders
+The finalized epoch headers storage
+maintains headers that have been finalized for each BSN and epoch. The key
+is the epoch number plus the BSN's ConsumerID, and the value is an
+IndexedHeaderWithProof object. The IndexedHeaderWithProof contains both the
+header metadata and the inclusion proof.
+// IndexedHeader is the metadata of a BSN header
message IndexedHeader {
- // consumer_id is the unique ID of the consumer
+ // consumer_id is the unique ID of the BSN
string consumer_id = 1;
// hash is the hash of this header
bytes hash = 2;
- // height is the height of this header on the Consumer's ledger
- // (hash, height) jointly provides the position of the header on the Consumer's ledger
+ // height is the height of this header on the BSN's ledger.
+ // (hash, height) jointly provide the position of the header on the BSN ledger
uint64 height = 3;
- // time is the timestamp of this header on the Consumer's ledger.
- // It is needed for the Consumer to unbond all mature validators/delegations
- // before this timestamp when this header is BTC-finalised
+ // time is the timestamp of this header on the BSN's ledger.
+ // It is needed for a BSN to unbond all mature validators/delegations before
+ // this timestamp, when this header is BTC-finalised
google.protobuf.Timestamp time = 4 [ (gogoproto.stdtime) = true ];
- // babylon_header_hash is the hash of the babylon block that includes this
- // Consumer header
+ // babylon_header_hash is the hash of the babylon block that includes this BSN
+ // header
bytes babylon_header_hash = 5;
// babylon_header_height is the height of the babylon block that includes this
- // Consumer header
+ // BSN header
uint64 babylon_header_height = 6;
// epoch is the epoch number of this header on Babylon ledger
uint64 babylon_epoch = 7;
@@ -173,12 +153,32 @@ CanonicalChain
// the header on Babylon ledger
bytes babylon_tx_hash = 8;
}
+
+// IndexedHeaderWithProof is an indexed header with a proof that the header is
+// included in the epoch
+message IndexedHeaderWithProof {
+ IndexedHeader header = 1;
+ // proof is an inclusion proof that the header
+ // is committed to the `app_hash` of the sealer header of header.babylon_epoch
+ tendermint.crypto.ProofOps proof = 2;
+}
+
+BSNBTCState
+The BSN BTC state storage maintains
+unified BTC synchronization state for each BSN. The key is the BSN's
+ConsumerID, and the value is a BSNBTCState object that tracks the base
+BTC header and last sent BTC header segment for each BSN.
+// BSNBTCState stores per-BSN BTC synchronization state
+// This includes both the base header and the last sent segment
+message BSNBTCState {
+ // base_header is the base BTC header for this BSN
+ // This represents the starting point from which BTC headers are synchronized
+ babylon.btclightclient.v1.BTCHeaderInfo base_header = 1;
+ // last_sent_segment is the last segment of BTC headers sent to this BSN
+ // This is used to determine the next headers to send and handle reorgs
+ BTCChainSegment last_sent_segment = 2;
+}
-Fork
-The fork storage maintains the metadata of canonical
-IBC headers of a PoS system. The key is the PoS system's ConsumerID plus the
-height, and the value is a list of IndexedHeader objects, which represent fork
-headers at that height.
Params
The parameter storage maintains the parameters for the
Zone Concierge module.
@@ -222,32 +222,33 @@ PostHandler for intercepting IBC headers
Hooks
The Zone Concierge module subscribes to the Epoching module's AfterEpochEnds
-hook for indexing the epochs when receiving
-headers from BSNs, the Checkpointing module's AfterRawCheckpointSealed
-hook for recording epoch chain info proofs,
-and the Checkpointing module's AfterRawCheckpointFinalized
+hook for recording epoch headers, the
+Checkpointing module's AfterRawCheckpointSealed
+hook for recording epoch header proofs, and
+the Checkpointing module's AfterRawCheckpointFinalized
hook for sending BTC timestamps to BSNs.
Indexing headers upon AfterEpochEnds
The AfterEpochEnds hook is triggered when an epoch is ended, i.e., the last
block in this epoch has been committed by CometBFT. Upon AfterEpochEnds, the
-Zone Concierge will save the current ChainInfo to the EpochChainInfo storage
-for each BSN.
-
+
- Record all current latest epoch headers as finalized headers for the completed epoch +
- Clear the latest epoch headers to prepare for the next epoch +
Recording proofs upon AfterRawCheckpointSealed
The AfterRawCheckpointSealed hook is triggered when an epoch's raw checkpoint
is sealed by validator signatures. Upon AfterRawCheckpointSealed, the Zone
Concierge will:
-
-
- Record epoch chain info with inclusion proofs for each BSN +
- Generate inclusion proofs for all finalized headers in the sealed epoch
- Generate and store the proof that the epoch is sealed
Sending BTC timestamps upon AfterRawCheckpointFinalized
@@ -261,11 +262,11 @@ Sending BTC timestamps upon AfterRawCheckpointFinalized
Bitcoin.
// BTCTimestamp is a BTC timestamp that carries information of a BTC-finalized epoch
// It includes a number of BTC headers, a raw checkpoint, an epoch metadata, and
-// a Consumer header if there exists Consumer headers checkpointed to this epoch.
+// a BSN header if there exists BSN headers checkpointed to this epoch.
// Upon a newly finalized epoch in Babylon, Babylon will send a BTC timestamp to each
-// PoS blockchain that has phase-2 integration with Babylon via IBC.
+// BSN via IBC.
message BTCTimestamp {
- // header is the last Consumer header in the finalized Babylon epoch
+ // header is the last BSN header in the finalized Babylon epoch
babylon.zoneconcierge.v1.IndexedHeader header = 1;
/*
@@ -290,25 +291,24 @@ Sending BTC timestamps upon AfterRawCheckpointFinalized
/*
Proofs that the header is finalized
*/
- babylon.zoneconcierge.v1.ProofFinalizedChainInfo proof = 6;
+ babylon.zoneconcierge.v1.ProofFinalizedHeader proof = 6;
}
-// ProofFinalizedChainInfo is a set of proofs that attest a chain info is
+// ProofFinalizedHeader is a set of proofs that attest a header is
// BTC-finalized
-message ProofFinalizedChainInfo {
+message ProofFinalizedHeader {
/*
- The following fields include proofs that attest the chain info is
+ The following fields include proofs that attest the header is
BTC-finalized
*/
- // proof_consumer_header_in_epoch is the proof that the Consumer header is timestamped
- // within a certain epoch
- tendermint.crypto.ProofOps proof_consumer_header_in_epoch = 1;
// proof_epoch_sealed is the proof that the epoch is sealed
- babylon.zoneconcierge.v1.ProofEpochSealed proof_epoch_sealed = 2;
+ babylon.zoneconcierge.v1.ProofEpochSealed proof_epoch_sealed = 1;
// proof_epoch_submitted is the proof that the epoch's checkpoint is included
// in BTC ledger It is the two TransactionInfo in the best (i.e., earliest)
// checkpoint submission
- repeated babylon.btccheckpoint.v1.TransactionInfo proof_epoch_submitted = 3;
+ repeated babylon.btccheckpoint.v1.TransactionInfo proof_epoch_submitted = 2;
+ // proof_consumer_header_in_epoch is the proof that the BSN header is included in the epoch
+ tendermint.crypto.ProofOps proof_consumer_header_in_epoch = 3;
}
When AfterRawCheckpointFinalized is triggered, the Zone Concierge module will
@@ -317,18 +317,8 @@
Sending BTC timestamps upon AfterRawCheckpointFinalized
-
Determine BTC headers to broadcast: Get all BTC headers to be sent in BTC -timestamps by:
--
-
- Finding the segment of BTC headers sent upon the last time
-
AfterRawCheckpointFinalizedwas triggered
- - If all BTC headers in the segment are no longer canonical (due to a Bitcoin
-reorg), send the last
w+1BTC headers from the current tip, wherewis -thecheckpoint_finalization_timeout-parameter in the -BTCCheckpoint module
- - Otherwise, send BTC headers from the latest header that is still canonical -in the segment to the current tip of the BTC light client -
w+1+BTC headers from the current tip for compatibility) - Finding the segment of BTC headers sent upon the last time
-
-
Broadcast BTC timestamps to all open channels: For each open IBC channel @@ -336,7 +326,7 @@
Sending BTC timestamps upon
AfterRawCheckpointFinalized- Find the
ConsumerIDof the counterparty chain (i.e., the PoS system) in the IBC channel
- - Get the
ChainInfoof theConsumerIDat the last finalised epoch
+ - Get the finalized header for the
ConsumerIDat the last finalised epoch - Get the metadata of the last finalised epoch and its corresponding raw checkpoint
- Generate the proof that the last PoS system's canonical header is committed
@@ -364,20 +354,23 @@
Broadcasting BTC Headers
The
-EndBlockercallsBroadcastBTCHeadersto send BTC headers to all open IBC channels with BSNs. This ensures that BSNs' BTC light clients stay synchronized with Babylon Genesis' BTC light client.The header selection logic follows the same rules as described in the Hooks -section:
+The header selection logic now uses per-BSN BTC state tracking with the +following enhanced rules:
-
-
- If no headers have been sent previously: Send the last
w+1BTC headers from -the tip
- - If headers have been sent previously:
-
-
-
- If the last sent segment is still valid (no Bitcoin reorg): Send headers -from the last sent header to the current tip -
- If the last sent segment is invalid (Bitcoin reorg occurred): Send the last
-
w+1headers from the current tip
-
+ - BSN-specific BTC state: Each BSN has its own
BSNBTCState+that tracks the base BTC header and last sent segment
+ - No BSN base header: Falls back to sending the last
w+1BTC headers +from the tip (wherewis the confirmation depth parameter)
+ - BSN base header exists but no headers sent: Send headers from the +BSN's base header to the current tip +
- Headers previously sent: Send headers from the child of the most recent +valid header in the last sent segment to the current tip +
- Reorg detection: If no header from the last sent segment is still valid +(indicating a Bitcoin reorg), fall back to sending from the BSN's base +header to the current tip
This per-BSN approach provides better efficiency and reorg handling +compared to the previous global broadcast strategy.
Broadcasting BTC Staking Events
After broadcasting BTC headers, the
EndBlockercallsBroadcastBTCStakingConsumerEventsto propagate BTC staking events to relevant @@ -429,21 +422,21 @@Handling Inbound IBC Packets
Inbound IBC Packets
The inbound packet structure is defined as follows. Currently, the Zone Concierge module handles one type of -incoming packet:
ConsumerSlashingIBCPacket. This packet type allows BSNs to +incoming packet:BSNSlashingIBCPacket. This packet type allows BSNs to report slashing evidence for finality providers.
@@ -500,7 +493,7 @@// InboundPacket represents packets received by Babylon from other chains message InboundPacket { // packet is the actual message carried in the IBC packet oneof packet { - ConsumerSlashingIBCPacket consumer_slashing = 1; + BSNSlashingIBCPacket bsn_slashing = 1; } } -// ConsumerSlashingIBCPacket defines the slashing information that a Consumer sends to Babylon's ZoneConcierge upon a -// Consumer slashing event. -// It includes the FP public key, the Consumer block height at the slashing event, and the double sign evidence. -message ConsumerSlashingIBCPacket { - /// evidence is the FP slashing evidence that the Consumer sends to Babylon +// BSNSlashingIBCPacket defines the slashing information that a BSN sends to Babylon's ZoneConcierge upon a +// BSN slashing event. +// It includes the FP public key, the BSN block height at the slashing event, and the double sign evidence. +message BSNSlashingIBCPacket { + /// evidence is the FP slashing evidence that the BSN sends to Babylon babylon.finality.v1.Evidence evidence = 1; }IBC Communication Protocol
| Packet Direction | Types | |-----------------|-------| | Outbound |
+| Inbound |BTCHeaders,BTCTimestamp,BTCStakingConsumerEvent| -| Inbound |ConsumerSlashingIBCPacket|BSNSlashingIBCPacket|Relaying BTC Headers
Zone Concierge relays BTC headers from Babylon Genesis' BTC light client to BSNs in two scenarios:
@@ -513,7 +506,8 @@Relaying BTC Headers
- If no headers have been sent previously: Send the last
- Find the
This ensures BSNs can keep their BTC light clients synchronized with Bitcoin's canonical chain. The headers are sent through IBC packets to all open channels -between Babylon and the BSNs.
+between Babylon and the BSNs, with enhanced per-consumer tracking for improved +efficiency and reorg handling.Relaying BTC Timestamps
Zone Concierge sends BTC timestamps to BSNs when a Babylon epoch becomes
BTC-finalised. The AfterRawCheckpointFinalized hook is triggered when an
diff --git a/static/remote-docs/guides/overview/phases_of_the_launch/phase-2/registration.html b/static/remote-docs/guides/overview/phases_of_the_launch/phase-2/registration.html
index 25fbe6d3..00109bad 100644
--- a/static/remote-docs/guides/overview/phases_of_the_launch/phase-2/registration.html
+++ b/static/remote-docs/guides/overview/phases_of_the_launch/phase-2/registration.html
@@ -499,7 +499,7 @@
Explanation of Fields
Specifying more than one finality provider constitutes multi-staking, i.e delegating across multiple BSNs. The system enforces the following constraints:
-
-
- At least one finality provider must be securing the Babylon Genesis chain. +
- Exactly one finality provider must be securing the Babylon Genesis chain.
- At most one finality provider may be selected per consumer BSN.
- The total number of finality providers must not exceed the
max_multi_staked_fps limit, which can be queried from the registered BSN.