doc: doc for x/finality module (#190)

client/docs/swagger-ui/swagger.yaml

@@ -1148,6 +1148,56 @@ paths:
  type: boolean
  tags:
  - Query
+ /babylon/btclightclient/v1/params:
+ get:
+ summary: Params queries the parameters of the module.
+ operationId: BtcLightClientParams
+ responses:
+ '200':
+ description: A successful response.
+ schema:
+ type: object
+ properties:
+ params:
+ description: params holds all the parameters of this module.
+ type: object
+ properties:
+ insert_headers_allow_list:
+ type: array
+ items:
+ type: string
+ title: >-
+ List of addresses which are allowed to insert headers to
+ btc light client
+
+ if the list is empty, any address can insert headers
+ description: >-
+ QueryParamsResponse is the response type for the Query/Params RPC
+ method.
+ default:
+ description: An unexpected error response.
+ schema:
+ type: object
+ properties:
+ error:
+ type: string
+ code:
+ type: integer
+ format: int32
+ message:
+ type: string
+ details:
+ type: array
+ items:
+ type: object
+ properties:
+ type_url:
+ type: string
+ value:
+ type: string
+ format: byte
+ tags:
+ - Query
  /babylon/btclightclient/v1/tip:
  get:
  summary: Tip return best header on canonical chain
@@ -10561,6 +10611,19 @@ definitions:
  - Total work spent on the header. This is the sum of the work corresponding
  to the header Bits field
  and the total work of the header.
+ babylon.btclightclient.v1.Params:
+ type: object
+ properties:
+ insert_headers_allow_list:
+ type: array
+ items:
+ type: string
+ title: >-
+ List of addresses which are allowed to insert headers to btc light
+ client
+
+ if the list is empty, any address can insert headers
+ description: Params defines the parameters for the module.
  babylon.btclightclient.v1.QueryBaseHeaderResponse:
  type: object
  properties:
@@ -10715,6 +10778,23 @@ definitions:
  description: >-
  QueryMainChainResponse is response type for the Query/MainChain RPC
  method.
+ babylon.btclightclient.v1.QueryParamsResponse:
+ type: object
+ properties:
+ params:
+ description: params holds all the parameters of this module.
+ type: object
+ properties:
+ insert_headers_allow_list:
+ type: array
+ items:
+ type: string
+ title: >-
+ List of addresses which are allowed to insert headers to btc light
+ client
+
+ if the list is empty, any address can insert headers
+ description: QueryParamsResponse is the response type for the Query/Params RPC method.
  babylon.btclightclient.v1.QueryTipResponse:
  type: object
  properties:

proto/babylon/finality/v1/finality.proto

@@ -5,7 +5,7 @@ option go_package = "github.com/babylonchain/babylon/x/finality/types";
 
 import "gogoproto/gogo.proto";
 
-// IndexedBlock is the block with some indexed info
+// IndexedBlock is the necessary metadata and finalization status of a block
 message IndexedBlock {
  // height is the height of the block
  uint64 height = 1;
@@ -19,7 +19,7 @@ message IndexedBlock {
 // Evidence is the evidence that a finality provider has signed finality
 // signatures with correct public randomness on two conflicting Babylon headers
 message Evidence {
- // fp_btc_pk is the BTC Pk of the finality provider that casts this vote
+ // fp_btc_pk is the BTC PK of the finality provider that casts this vote
  bytes fp_btc_pk = 1 [ (gogoproto.customtype) = "github.com/babylonchain/babylon/types.BIP340PubKey" ];
  // block_height is the height of the conflicting blocks
  uint64 block_height = 2;

proto/babylon/finality/v1/params.proto

@@ -9,7 +9,7 @@ option go_package = "github.com/babylonchain/babylon/x/finality/types";
 message Params {
  option (gogoproto.goproto_stringer) = false;
 
- // min_pub_rand is the minimum number of public randomoness each 
+ // min_pub_rand is the minimum number of public randomness each 
  // message should commit
  uint64 min_pub_rand = 1;
 }

proto/babylon/finality/v1/tx.proto

@@ -21,12 +21,12 @@ service Msg {
  rpc UpdateParams(MsgUpdateParams) returns (MsgUpdateParamsResponse);
 }
 
-// MsgAddFinalitySig defines a message for adding a vote
+// MsgAddFinalitySig defines a message for adding a finality vote
 message MsgAddFinalitySig {
  option (cosmos.msg.v1.signer) = "signer";
 
  string signer = 1;
- // fp_btc_pk is the BTC Pk of the finality provider that casts this vote
+ // fp_btc_pk is the BTC PK of the finality provider that casts this vote
  bytes fp_btc_pk = 2 [ (gogoproto.customtype) = "github.com/babylonchain/babylon/types.BIP340PubKey" ];
  // block_height is the height of the voted block
  uint64 block_height = 3;
@@ -46,7 +46,7 @@ message MsgCommitPubRandList {
  option (cosmos.msg.v1.signer) = "signer";
 
  string signer = 1;
- // fp_btc_pk is the BTC Pk of the finality provider that commits the public randomness
+ // fp_btc_pk is the BTC PK of the finality provider that commits the public randomness
  bytes fp_btc_pk = 2 [ (gogoproto.customtype) = "github.com/babylonchain/babylon/types.BIP340PubKey" ];
  // start_height is the start block height of the list of public randomness
  uint64 start_height = 3;

x/btcstaking/README.md

@@ -30,6 +30,8 @@ providers and BTC delegations under them. This includes:
 - [Events](#events)
 - [Queries](#queries)
 
+<!-- TODO: a section about module parameters -->
+
 ## Concepts
 
 Babylon's Bitcoin Staking protocol allows bitcoin holders to *trustlessly* stake
@@ -130,14 +132,14 @@ message FinalityProvider {
 
 ### BTC delegations
 
-The BTC delegation storage at `x/btcstaking/keeper/btc_delegations.go` maintains
-all BTC delegations. The key is the staking transaction hash corresponding to
-the BTC delegation, and the value is a `BTCDelegation` object. The
-`BTCDelegation` [structure](../../proto/babylon/btcstaking/v1/btcstaking.proto)
-includes information of a BTC delegation and a structure `BTCUndelegation` that
-includes information of its early unbonding path. The staking transaction's hash
-uniquely identifies a `BTCDelegation` as creating a BTC delegation requires the
-staker to submit a staking transaction to Bitcoin.
+The [BTC delegation storage](./keeper/btc_delegations.go) maintains all BTC
+delegations. The key is the staking transaction hash corresponding to the BTC
+delegation, and the value is a `BTCDelegation` object. The `BTCDelegation`
+[structure](../../proto/babylon/btcstaking/v1/btcstaking.proto) includes
+information of a BTC delegation and a structure `BTCUndelegation` that includes
+information of its early unbonding path. The staking transaction's hash uniquely
+identifies a `BTCDelegation` as creating a BTC delegation requires the staker to
+submit a staking transaction to Bitcoin.
 
 ```protobuf
 
@@ -223,9 +225,9 @@ message BTCUndelegation {
 The [BTC delegation index storage](./keeper/btc_delegators.go) maintains an
 index between the BTC delegator and its BTC delegations. The key is the BTC
 delegator's Bitcoin secp256k1 public key in BIP-340 format, and the value is a
-`BTCDelegatorDelegationIndex` object containing staking transaction hashes of
-the delegator's BTC delegations. The `BTCDelegatorDelegationIndex` is defined at
-`proto/babylon/btcstaking/v1/btcstaking.proto`.
+`BTCDelegatorDelegationIndex`
+[object](../../proto/babylon/btcstaking/v1/btcstaking.proto) that contains
+staking transaction hashes of the delegator's BTC delegations.
 
 ```protobuf
 // BTCDelegatorDelegationIndex is a list of staking tx hashes of BTC delegations from the same delegator.
@@ -610,7 +612,7 @@ message SelectiveSlashingEvidence {
 
 ## Queries
 
-The BTC staking module provides a set of queries about the status of
-checkpointed consumer chains, listed at
-[docs.babylonchain.io](https://docs.babylonchain.io/docs/developer-guides/grpcrestapi#tag/ZoneConcierge).
+The BTC staking module provides a set of queries about the status of finality
+providers and BTC delegations, listed at
+[docs.babylonchain.io](https://docs.babylonchain.io/docs/developer-guides/grpcrestapi#tag/BTCStaking).
 <!-- TODO: update Babylon doc website -->