Skip to content

Commit

Permalink
added/updated pallet level docs to grandpa and messages pallets (#1771)
Browse files Browse the repository at this point in the history
  • Loading branch information
svyatonik authored Jan 16, 2023
1 parent 6d69d1f commit a0f41b2
Show file tree
Hide file tree
Showing 3 changed files with 137 additions and 236 deletions.
4 changes: 2 additions & 2 deletions docs/high-level-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ the source chain GRANDPA justifications stream and submits every new justificati
target chain GRANDPA light client. In addition, relay is searching for mandatory headers and
submits their justifications - without that the pallet will be unable to move forward.

More: [GRANDPA Finality Relay Sequence Diagram](./grandpa-finality-relay.html), [code](../relays/finality/).
More: [GRANDPA Finality Relay Sequence Diagram](./grandpa-finality-relay.html), [pallet level documentation and code](../relays/finality/).

### Parachains Finality Relay

Expand Down Expand Up @@ -158,7 +158,7 @@ relay submits transactions to both source and target chains, it requires both _s
_target-to-source_ finality relays. They can be GRANDPA finality relays or GRANDPA+parachains finality relays,
depending on the type of connected chain.

More: [Messages Relay Sequence Diagram](./messages-relay.html), [code](../relays/messages/).
More: [Messages Relay Sequence Diagram](./messages-relay.html), [pallet level documentation and code](../relays/messages/).

### Complex Relay

Expand Down
83 changes: 83 additions & 0 deletions modules/grandpa/README.md
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/).
Loading

0 comments on commit a0f41b2

Please sign in to comment.