-
Notifications
You must be signed in to change notification settings - Fork 129
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
added/updated pallet level docs to grandpa and messages pallets (#1771)
- Loading branch information
Showing
3 changed files
with
137 additions
and
236 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,83 @@ | ||
# Bridge GRANDPA Pallet | ||
|
||
The bridge GRANDPA pallet is a light client for the GRANDPA finality gadget, running at the bridged chain. | ||
It may import headers and their GRANDPA finality proofs (justifications) of the bridged chain. Imported | ||
headers then may be used to verify storage proofs by other pallets. This makes the bridge GRANDPA pallet | ||
a basic pallet of all bridges with Substrate-based chains. It is used by all bridge types (bridge between | ||
standalone chains, between parachains and any combination of those) and is used by other bridge pallets. | ||
It is used by the parachains light client (bridge parachains pallet) and by messages pallet. | ||
|
||
## A Brief Introduction into GRANDPA Finality | ||
|
||
You can find detailed information on GRANDPA, by exploring its [repository](https://github.com/paritytech/finality-grandpa). | ||
Here is the minimal reqiuired GRANDPA information to understand how pallet works. | ||
|
||
Any Substrate chain may use different block authorship algorithms (like BABE or Aura) to determine block producers and | ||
generate blocks. This has nothing common with finality, though - the task of block authorship is to coordinate | ||
blocks generation. Any block may be reverted (if there's a fork) if it is not finalized. The finality solution | ||
for (standalone) Substrate-based chains is the GRANDPA finality gadget. If some block is finalized by the gadget, it | ||
can't be reverted. | ||
|
||
In GRANDPA, there are validators, identified by their public keys. They select some generated block and produce | ||
signatures on this block hash. If there are enough (more than `2 / 3 * N`, where `N` is number of validators) | ||
signatures, then the block is considered finalized. The set of signatures for the block is called justification. | ||
Anyone who knows the public keys of validators is able to verify GRANDPA justification and that it is generated | ||
for provided header. | ||
|
||
There are two main things in GRANDPA that help building light clients: | ||
|
||
- there's no need to import all headers of the bridged chain. Light client may import finalized headers or just | ||
some of finalized headders that it consider useful. While the validators set stays the same, the client may | ||
import any header that is finalized by this set; | ||
- when validators set changes, the GRANDPA gadget adds next set to the header. So light client doesn't need to | ||
verify storage proofs when this happens - it only needs to look at the header and see if it changes the set. | ||
Once set is changed, all following justifications are generated by the new set. Header that is changing the | ||
set is called "mandatory" in the pallet. As the name says, the light client need to import all such headers | ||
to be able to operate properly. | ||
|
||
## Pallet Operations | ||
|
||
The main entrypoint of the pallet is the `submit_finality_proof` call. It has two arguments - the finalized | ||
headers and associated GRANDPA justification. The call simply verifies the justification using current | ||
validators set and checks if header is better than the previous best header. If both checks are passed, the | ||
header (only its useful fields) is inserted into the runtime storage and may be used by other pallets to verify | ||
storage proofs. | ||
|
||
The submitter pays regular fee for submitting all headers, except for the mandatory header. Since it is | ||
required for the pallet operations, submitting such header is free. So if you're ok with session-length | ||
lags (meaning that there's exactly 1 mandatory header per session), the cost of pallet calls is zero. | ||
|
||
When the pallet sees mandatory header, it updates the validators set with the set from the header. All | ||
following justifications (until next mandatory header) must be generated by this new set. | ||
|
||
## Pallet Initialization | ||
|
||
As the previous section states, there are two things that are mandatory for pallet operations: best finalized | ||
header and the current validators set. Without it the pallet can't import any headers. But how to provide | ||
initial values for these fields? There are two options. | ||
|
||
First option, while it is easier, doesn't work in all cases. It is to start chain with initial header and | ||
validators set specified in the chain specification. This won't work, however, if we want to add bridge | ||
to already started chain. | ||
|
||
For the latter case we have the `initialize` call. It accepts the initial header and initial validators set. | ||
The call may be called by the governance, root or by the pallet owner (if it is set). | ||
|
||
## Non-Essential Functionality | ||
|
||
There may be a special account in every runtime where the bridge GRANDPA module is deployed. This | ||
account, named 'module owner', is like a module-level sudo account - he's able to halt and | ||
resume all module operations without requiring runtime upgrade. Calls that are related to this | ||
account are: | ||
- `fn set_owner()`: current module owner may call it to transfer "ownership" to another account; | ||
- `fn set_operating_mode()`: the module owner (or sudo account) may call this function to stop all | ||
module operations. After this call, all finality proofs will be rejected until further `set_operating_mode` call'. | ||
This call may be used when something extraordinary happens with the bridge; | ||
- `fn initialize()`: module owner may call this function to initialize the bridge. | ||
|
||
If pallet owner is not defined, the governance may be used to make those calls. | ||
|
||
## GRANDPA Finality Relay | ||
|
||
We have an offchain actor, who is watching for GRANDPA justifications and submits them to the bridged chain. | ||
It is the finality relay - you may look at the [crate level documentation and the code](../../relays/finality/). |
Oops, something went wrong.