mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-04-26 18:07:58 +00:00
Serban Iorga
142a11ad95
* Move the bridges subtree under root * Squashed 'bridges/' changes from 277f0d5496..e50398d1c5 e50398d1c5 bridges subtree fixes (#2528) 99af07522d Markdown linter (#1309) (#2526) 733ff0fe7a `polkadot-staging` branch: Use polkadot-sdk dependencies (#2524) e8a59f141e Fix benchmark with new XCM::V3 `MAX_INSTRUCTIONS_TO_DECODE` (#2514) 62b185de15 Backport `polkadot-sdk` changes to `polkadot-staging` (#2518) d9658f4d5b Fix equivocation detection containers startup (#2516) (#2517) d65db28a8f Backport: building images from locally built binaries (#2513) 5fdbaf45f6 Start the equivocation detection loop from the complex relayer (#2507) (#2512) 7fbb67de46 Backport: Implement basic equivocations detection loop (#2375) cb7efe245c Manually update deps in polkadot staging (#2371) d17981fc33 #2351 to polkadot-staging (#2359) git-subtree-dir: bridges git-subtree-split: e50398d1c594e4e96df70b0bd376e565d17e8558 * Reapply diener workspacify * Fix Cargo.toml * Fix test * Adjustments
102 lines
6.2 KiB
Markdown
102 lines
6.2 KiB
Markdown
# 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/call_ext) 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/).
|