README.md

# 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.

## Signed Extension to Reject Obsolete Headers

It'd be better for anyone (for chain and for submitters) to reject all transactions that are submitting
already known headers to the pallet. This way, we leave block space to other useful transactions and
we don't charge concurrent submitters for their honest actions.

To deal with that, we have a [signed extension](./src/extension.rs) that may be added to the runtime.
It does exactly what is required - rejects all transactions with already known headers. The submitter
pays nothing for such transactions - they're simply removed from the transaction pool, when the block
is built.

You may also take a look at the [`generate_bridge_reject_obsolete_headers_and_messages`](../../bin/runtime-common/src/lib.rs)
macro that bundles several similar signed extensions in a single one.

## 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/).