Skip to content

Commit

Permalink
pr comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@gitferry
gitferry committed Oct 11, 2024
1 parent 066dd51 commit aa31ddb
Show file tree
Hide file tree
Showing 4 changed files with 322 additions and 209 deletions.
44 changes: 22 additions & 22 deletions proto/babylon/btcstaking/v1/events.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ option go_package = "github.com/babylonlabs-io/babylon/x/btcstaking/types";
message EventFinalityProviderCreated {
// btc_pk_hex is the hex string of Bitcoin secp256k1 PK of this finality provider
string btc_pk_hex = 1;
// addr is the address to receive commission from delegations.
// addr is the babylon address to receive commission from delegations.
string addr = 2;
// commission defines the commission rate of the finality provider.
// commission defines the commission rate of the finality provider in decimals.
string commission = 3;
// moniker defines a human-readable name for the finality provider.
string moniker = 4;
Expand All @@ -32,7 +32,7 @@ message EventFinalityProviderCreated {
message EventFinalityProviderEdited {
// btc_pk_hex is the hex string of Bitcoin secp256k1 PK of this finality provider
string btc_pk_hex = 1;
// commission defines the commission rate of the finality provider.
// commission defines the commission rate of the finality provider in decimals.
string commission = 2;
// moniker defines a human-readable name for the finality provider.
string moniker = 3;
Expand Down Expand Up @@ -102,15 +102,6 @@ message EventPowerDistUpdate {
}
}

message EventFinalityProviderStatusChange {
// btc_pk is the BTC public key of the finality provider
string btc_pk = 1;
// new_status is the new status that the finality provider
// is transitioned to, following FinalityProviderStatus
string new_status = 2;
}

// FinalityProviderStatus is the status of a finality provider.
// A finality provider starts with status INACTIVE once registered.
// Possible status transitions are when:
// 1. it has accumulated sufficient delegations and has
Expand All @@ -127,6 +118,15 @@ message EventFinalityProviderStatusChange {
// ACTIVE -> INACTIVE.
// Note that it is impossible for a SLASHED finality provider to
// transition to other status
message EventFinalityProviderStatusChange {
// btc_pk is the BTC public key of the finality provider
string btc_pk = 1;
// new_status is the status that the finality provider
// is transitioned to, following FinalityProviderStatus
string new_status = 2;
}

// FinalityProviderStatus is the status of a finality provider.
enum FinalityProviderStatus {
// FINALITY_PROVIDER_STATUS_INACTIVE defines a finality provider that does not have sufficient
// delegations or does not have timestamped public randomness.
Expand Down Expand Up @@ -164,8 +164,8 @@ message EventBTCDelegationCreated {
string unbonding_time = 7;
// unbonding_tx is hex encoded bytes of the unsigned unbonding tx
string unbonding_tx = 8;
// state of the BTC delegation
string state = 9;
// new_status of the BTC delegation
string new_status = 9;
}

// EventCovenantSignatureReceived is the event emitted when a covenant committee
Expand All @@ -188,8 +188,8 @@ message EventCovenantQuorumReached {
// staking_tx_hash is the hash of the staking identifing the BTC delegation
// that this covenant signature is for
string staking_tx_hash = 1;
// state of the BTC delegation
string state = 2;
// new_status of the BTC delegation
string new_status = 2;
}

// EventBTCDelegationInclusionProofReceived is the event emitted when a BTC delegation
Expand All @@ -204,8 +204,8 @@ message EventBTCDelegationInclusionProofReceived {
// end_height is the end height of the BTC delegation
// it is calculated by end_height = start_height + staking_time
string end_height = 3;
// state of the BTC delegation
string state = 4;
// new_status of the BTC delegation
string new_status = 4;
}

// EventBTCDelgationUnbondedEarly is the event emitted when a BTC delegation
Expand All @@ -214,8 +214,8 @@ message EventBTCDelgationUnbondedEarly {
// staking_tx_hash is the hash of the staking tx.
// It uniquely identifies a BTC delegation
string staking_tx_hash = 1;
// state of the BTC delegation
string state = 2;
// new_status of the BTC delegation
string new_status = 2;
}

// EventBTCDelegationExpired is the event emitted when a BTC delegation
Expand All @@ -224,6 +224,6 @@ message EventBTCDelegationExpired {
// staking_tx_hash is the hash of the staking tx.
// It uniquely identifies a BTC delegation
string staking_tx_hash = 1;
// state of the BTC delegation
string state = 2;
// new_status of the BTC delegation
string new_status = 2;
}
184 changes: 149 additions & 35 deletions x/btcstaking/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -715,51 +715,165 @@ The logic is defined at [x/btcstaking/abci.go](./abci.go).

## Events

The BTC staking module emits a set of events as follows. The events are defined
The BTC staking module emits a set of events for external subscribers. The events are defined
at `proto/babylon/btcstaking/v1/events.proto`.

### Finality provider events

```protobuf
// EventNewFinalityProvider is the event emitted when a finality provider is created
message EventNewFinalityProvider { FinalityProvider fp = 1; }
// EventBTCDelegationStateUpdate is the event emitted when a BTC delegation's state is
// updated. There are the following possible state transitions:
// - non-existing -> pending, which happens upon `MsgCreateBTCDelegation`
// - pending -> active, which happens upon `MsgAddCovenantSigs`
// - active -> unbonded, which happens upon `MsgBTCUndelegate` or upon staking tx timelock expires
message EventBTCDelegationStateUpdate {
// EventFinalityProviderCreated is the event emitted when a finality provider is created
message EventFinalityProviderCreated {
// btc_pk_hex is the hex string of Bitcoin secp256k1 PK of this finality provider
string btc_pk_hex = 1;
// addr is the babylon address to receive commission from delegations.
string addr = 2;
// commission defines the commission rate of the finality provider in decimals.
string commission = 3;
// moniker defines a human-readable name for the finality provider.
string moniker = 4;
// identity defines an optional identity signature (ex. UPort or Keybase).
string identity = 5;
// website defines an optional website link.
string website = 6;
// security_contact defines an optional email for security contact.
string security_contact = 7;
// details define other optional details.
string details = 8;
}
// EventFinalityProviderEdited is the event emitted when a finality provider is edited
message EventFinalityProviderEdited {
// btc_pk_hex is the hex string of Bitcoin secp256k1 PK of this finality provider
string btc_pk_hex = 1;
// commission defines the commission rate of the finality provider in decimals.
string commission = 2;
// moniker defines a human-readable name for the finality provider.
string moniker = 3;
// identity defines an optional identity signature (ex. UPort or Keybase).
string identity = 4;
// website defines an optional website link.
string website = 5;
// security_contact defines an optional email for security contact.
string security_contact = 6;
// details define other optional details.
string details = 7;
}
// A finality provider starts with status INACTIVE once registered.
// Possible status transitions are when:
// 1. it has accumulated sufficient delegations and has
// timestamped public randomness:
// INACTIVE -> ACTIVE
// 2. it is jailed due to downtime:
// ACTIVE -> JAILED
// 3. it is slashed due to double-sign:
// ACTIVE -> SLASHED
// 4. it is unjailed after a jailing period:
// JAILED -> INACTIVE/ACTIVE (depending on (1))
// 5. it does not have sufficient delegations or does not
// have timestamped public randomness:
// ACTIVE -> INACTIVE.
// Note that it is impossible for a SLASHED finality provider to
// transition to other status
message EventFinalityProviderStatusChange {
// btc_pk is the BTC public key of the finality provider
string btc_pk = 1;
// new_status is the status that the finality provider
// is transitioned to, following FinalityProviderStatus
string new_status = 2;
}
```

### Delegation events

```protobuf
// EventBTCDelegationCreated is the event emitted when a BTC delegation is created
// on the Babylon chain
message EventBTCDelegationCreated {
// staking_tx_hash is the hash of the staking tx.
// It uniquely identifies a BTC delegation
string staking_tx_hash = 1;
// new_state is the new state of this BTC delegation
BTCDelegationStatus new_state = 2;
// version of the params used to validate the delegation
string params_version = 2;
// finality_provider_btc_pks_hex is the list of hex str of Bitcoin secp256k1 PK of
// the finality providers that this BTC delegation delegates to
// the PK follows encoding in BIP-340 spec
repeated string finality_provider_btc_pks_hex = 3;
// staker_btc_pk_hex is the hex str of Bitcoin secp256k1 PK of the staker that
// creates this BTC delegation the PK follows encoding in BIP-340 spec
string staker_btc_pk_hex = 4;
// staking_time is the timelock of the staking tx specified in the BTC script
string staking_time = 5;
// staking_amount is the total amount of BTC stake in this delegation
// quantified in satoshi
string staking_amount = 6;
// unbonding_time is the time is timelock on unbonding tx chosen by the staker
string unbonding_time = 7;
// unbonding_tx is hex encoded bytes of the unsigned unbonding tx
string unbonding_tx = 8;
// new_status of the BTC delegation
string new_status = 9;
}
// EventCovenantSignatureReceived is the event emitted when a covenant committee
// sends valid covenant signatures for a BTC delegation
message EventCovenantSignatureReceived{
// staking_tx_hash is the hash of the staking identifing the BTC delegation
// that this covenant signature is for
string staking_tx_hash = 1;
// covenant_btc_pk_hex is the hex str of Bitcoin secp256k1 PK of the
// covnenat committee that send the signature
string covenant_btc_pk_hex = 2;
// covenant_unbonding_signature_hex is the hex str of the BIP340 Schnorr
// signature of the covenant committee on the unbonding tx
string covenant_unbonding_signature_hex = 3;
}
// EventCovenantQuorumReached is the event emitted quorum of covenant committee
// is reached for a BTC delegation
message EventCovenantQuorumReached {
// staking_tx_hash is the hash of the staking identifing the BTC delegation
// that this covenant signature is for
string staking_tx_hash = 1;
// new_status of the BTC delegation
string new_status = 2;
}
// EventBTCDelegationInclusionProofReceived is the event emitted when a BTC delegation
// inclusion proof is received
message EventBTCDelegationInclusionProofReceived {
// staking_tx_hash is the hash of the staking tx.
// It uniquely identifies a BTC delegation
string staking_tx_hash = 1;
// start_height is the start BTC height of the BTC delegation
// it is the start BTC height of the timelock
string start_height = 2;
// end_height is the end height of the BTC delegation
// it is calculated by end_height = start_height + staking_time
string end_height = 3;
// new_status of the BTC delegation
string new_status = 4;
}
// EventSelectiveSlashing is the event emitted when an adversarial
// finality provider selectively slashes a BTC delegation. This will
// result in slashing of all BTC delegations under this finality provider.
message EventSelectiveSlashing {
// evidence is the evidence of selective slashing
SelectiveSlashingEvidence evidence = 1;
// EventBTCDelgationUnbondedEarly is the event emitted when a BTC delegation
// is unbonded by staker sending unbonding tx to BTC
message EventBTCDelgationUnbondedEarly {
// staking_tx_hash is the hash of the staking tx.
// It uniquely identifies a BTC delegation
string staking_tx_hash = 1;
// new_status of the BTC delegation
string new_status = 2;
}
// EventPowerDistUpdate is an event that affects voting power distribution
// of BTC staking protocol
message EventPowerDistUpdate {
// EventSlashedFinalityProvider defines an event that a finality provider
// is slashed
// TODO: unify with existing slashing events
message EventSlashedFinalityProvider {
bytes pk = 1 [ (gogoproto.customtype) = "github.com/babylonlabs-io/babylon/types.BIP340PubKey" ];
}
// ev is the event that affects voting power distribution
oneof ev {
// slashed_fp means a finality provider is slashed
EventSlashedFinalityProvider slashed_fp = 1;
// btc_del_state_update means a BTC delegation's state is updated
EventBTCDelegationStateUpdate btc_del_state_update = 2;
}
// EventBTCDelegationExpired is the event emitted when a BTC delegation
// is unbonded by expiration of the staking tx timelock
message EventBTCDelegationExpired {
// staking_tx_hash is the hash of the staking tx.
// It uniquely identifies a BTC delegation
string staking_tx_hash = 1;
// new_status of the BTC delegation
string new_status = 2;
}
```

Expand Down
10 changes: 5 additions & 5 deletions x/btcstaking/types/events.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ func NewInclusionProofEvent(
StakingTxHash: stakingTxHash,
StartHeight: strconv.FormatUint(startHeight, 10),
EndHeight: strconv.FormatUint(endHeight, 10),
State: state.String(),
NewStatus: state.String(),
}
}

Expand All @@ -97,7 +97,7 @@ func NewBtcDelCreationEvent(
StakingAmount: strconv.FormatUint(btcDel.TotalSat, 10),
UnbondingTime: strconv.FormatUint(uint64(btcDel.UnbondingTime), 10),
UnbondingTx: hex.EncodeToString(btcDel.BtcUndelegation.UnbondingTx),
State: BTCDelegationStatus_PENDING.String(),
NewStatus: BTCDelegationStatus_PENDING.String(),
}
}

Expand All @@ -119,7 +119,7 @@ func NewCovenantQuorumReachedEvent(
) *EventCovenantQuorumReached {
return &EventCovenantQuorumReached{
StakingTxHash: btcDel.MustGetStakingTxHash().String(),
State: state.String(),
NewStatus: state.String(),
}
}

Expand All @@ -128,7 +128,7 @@ func NewDelegationUnbondedEarlyEvent(
) *EventBTCDelgationUnbondedEarly {
return &EventBTCDelgationUnbondedEarly{
StakingTxHash: stakingTxHash,
State: BTCDelegationStatus_UNBONDED.String(),
NewStatus: BTCDelegationStatus_UNBONDED.String(),
}
}

Expand All @@ -137,7 +137,7 @@ func NewExpiredDelegationEvent(
) *EventBTCDelegationExpired {
return &EventBTCDelegationExpired{
StakingTxHash: stakingTxHash,
State: BTCDelegationStatus_UNBONDED.String(),
NewStatus: BTCDelegationStatus_UNBONDED.String(),
}
}

Expand Down
Loading

0 comments on commit aa31ddb

Please sign in to comment.