Skip to content
This repository has been archived by the owner on Nov 15, 2023. It is now read-only.

PVF timeouts follow-up #6151

Merged
merged 6 commits into from
Nov 1, 2022
Merged

PVF timeouts follow-up #6151

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5f0a6e3
Rename timeout consts and timeout parameter; bump leniency
mrcnski Oct 13, 2022
38231a2
Update implementor's guide with info about PVFs
mrcnski Oct 13, 2022
2db8522
Make glossary a bit easier to read
mrcnski Oct 13, 2022
5e56bdf
Add a note to LENIENT_PREPARATION_TIMEOUT
mrcnski Oct 13, 2022
3bcf8d2
Remove PVF-specific section from glossary
mrcnski Oct 14, 2022
7c8e466
Fix some typos
mrcnski Oct 31, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Update implementor's guide with info about PVFs
  • Loading branch information
@mrcnski
mrcnski committed Oct 13, 2022
commit 38231a271fbb4bd48c88277b31dd49a95651b1a3
28 changes: 28 additions & 0 deletions roadmap/implementers-guide/src/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ exactly one downward message queue.
- PDK (Parachain Development Kit): A toolset that allows one to develop a parachain. Cumulus is a PDK.
- Preimage: In our context, if `H(X) = Y` where `H` is a hash function and `Y` is the hash, then `X` is the hash preimage.
- Proof-of-Validity (PoV): A stateless-client proof that a parachain candidate is valid, with respect to some validation function.
- PVF: Parachain Validation Function. The validation code that is run by
validators on parachains or parathreads. See the [PVF glossary][1].
- Relay Parent: A block in the relay chain, referred to in a context where work is being done in the context of the state at this block.
- Router: The router module is a meta module that consists of three runtime modules responsible for routing messages between paras and the relay chain. The three separate runtime modules are: Dmp, Ump, Hrmp, each responsible for the respective part of message routing.
- Runtime: The relay-chain state machine.
Expand All @@ -40,6 +42,32 @@ exactly one downward message queue.
- VMP: (Vertical Message Passing) A family of mechanisms that are responsible for message exchange between the relay chain and parachains.
- XCMP (Cross-Chain Message Passing) A type of horizontal message passing (i.e. between parachains) that allows secure message passing directly between parachains and has minimal resource requirements from the relay chain, thus highly scalable.

## PVF

The PVF functionality involves several processes which may be potentially
confusing:

- **Prechecking:** This is the process of initially checking the PVF when it is
first added. We attempt *preparation* of the PVF and make sure it succeeds
within a given timeout.
- **Execution:** This actually executes the PVF. The node may not have the
artifact from prechecking, in which case this process also includes a
*preparation* job. The timeout for preparation here is more lenient than when
prechecking.
- **Preparation:** This is the process of preparing the WASM blob and includes
both *prevalidation* and *compilation*. As prevalidation is pretty minimal
right now, preparation mostly consists of compilation. Note that *prechecking*
just consists of preparation, whereas *execution* will also prepare the PVF if
the artifact is not already found.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't get this last sentence. prechecking == preparation && execution == preparation?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah that is confusing, I will try to reword it a bit. How about this:

Prechecking only tries to prepare the artifact, with a strict timeout. Execution will also prepare (if the artifact is not found), but with a more lenient timeout, in addition to then executing the compiled code.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ended up removing this sentence.

- **Prevalidation:** Right now this just tries to deserialize the binary with
parity-wasm. It is a part of *preparation*.
- **Compilation:** This is the process of compiling a PVF from wasm code to
a machine code *artifact*. It is a part of *preparation*.
- **Artifact:** The compiled machine code for the wasm module.

## See Also
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you get a bit carried away with your PVF hat on : ) IOW, I don't think this deserves a separate section in the glossary. This is the whole project glossary, and it's not clear if we can continue to introduce sections for each area of interest (and not sure if there can always be a clear divide).

If we do remove the section, then some overly abstract terms will have to go, specifically compilation and execution. But I won't be too sad about that, I don't think they are absolutely necessary. In my subjective opinion, they are quite understandable without explicit spelling out.

They still do care some additional information, but that information should live somewhere else. E.g. overview of a PVF execution mechanism, which does not exist right now, but seems to be useful.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough, I just wanted to be thorough. :) Cleaned up the glossary.

They still do care some additional information, but that information should live somewhere else. E.g. overview of a PVF execution mechanism, which does not exist right now, but seems to be useful.

I can do that, but can you clarify where that should go? e.g. its own page, or on the PVF Prechecking page? Should it just be about execution? I added a Summary section to the PVF Prechecking page, maybe that's enough.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is for now. I was just thinking of Architecture Overview → PVF. Optionally, PVF prechecking could be a subpage of that.


Also of use is the [Substrate Glossary](https://substrate.dev/docs/en/knowledgebase/getting-started/glossary).

[0]: https://wiki.polkadot.network/docs/learn-consensus
[1]: #pvf
47 changes: 22 additions & 25 deletions roadmap/implementers-guide/src/pvf-prechecking.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,14 @@
# PVF Pre-checking Overview

> ⚠️ This discusses a mechanism that is currently under-development. Follow the progress under [#3211].

## Terms

This functionality involves several processes which may be potentially
confusing:

- **Prechecking:** This is the process of initially checking the PVF when it is
first added. We attempt *preparation* of the PVF and make sure it succeeds
within a given timeout.
- **Execution:** This actually executes the PVF. The node may not have the
artifact from prechecking, in which case this process also includes a
*preparation* job. The timeout for preparation here is more lenient than when
prechecking.
- **Preparation:** This is the process of preparing the WASM blob and includes
both *prevalidation* and *compilation*. As prevalidation is pretty minimal
right now, preparation mostly consists of compilation. Note that *prechecking*
just consists of preparation, whereas *execution* will also prepare the PVF if
the artifact is not already found.
- **Prevalidation:** Right now this just tries to deserialize the binary with
parity-wasm. It is a part of *preparation*.
- **Compilation:** This is the process of compiling a PVF from wasm code to
machine code. It is a part of *preparation*.
> ⚠️ This discusses a mechanism that is currently under-development. Follow the progress under [#3211][3211].
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The hashtag was breaking this link, this made it work.


For an explanation of the terms used in this document, please see the [glossary].

## Motivation

Parachains' and parathreads' validation function is described by a wasm module that we refer to as a PVF. Since it's a wasm module the typical way of executing it is to compile it to machine code. Typically an optimizing compiler consists of algorithms that are able to optimize the resulting machine code heavily. However, while those algorithms perform quite well for a typical wasm code produced by standard toolchains (e.g. rustc/LLVM), those algorithms can be abused to consume a lot of resources. Moreover, since those algorithms are rather complex there is a lot of room for a bug that can crash the compiler.
Parachains' and parathreads' validation function is described by a wasm module that we refer to as a PVF. Since a PVF is a wasm module the typical way of executing it is to compile it to machine code.

Typically an optimizing compiler consists of algorithms that are able to optimize the resulting machine code heavily. However, while those algorithms perform quite well for a typical wasm code produced by standard toolchains (e.g. rustc/LLVM), those algorithms can be abused to consume a lot of resources. Moreover, since those algorithms are rather complex there is a lot of room for a bug that can crash the compiler.

If compilation of a Parachain Validation Function (PVF) takes too long or uses too much memory, this can leave a node in limbo as to whether a candidate of that parachain is valid or not.

Expand Down Expand Up @@ -66,7 +48,22 @@ The logic described above is implemented by the [paras] module.

On the node-side, there is a PVF pre-checking [subsystem][pvf-prechecker-subsystem] that scans the chain for new PVFs via using [runtime APIs][pvf-runtime-api]. Upon finding a new PVF, the subsystem will initiate a PVF pre-checking request and wait for the result. Whenever the result is obtained, the subsystem will use the [runtime API][pvf-runtime-api] to submit a vote for the PVF. The vote is an unsigned transaction. The vote will be distributed via the gossip similarly to a normal transaction. Eventually a block producer will include the vote into the block where it will be handled by the [runtime][paras].

[#3211]: https://github.com/paritytech/polkadot/issues/3211
## Summary

Parachains' and parathreads' validation function is described by a wasm module that we refer to as a PVF.

In order to make the PVF usable for candidate validation it has to be registered on-chain.

As part of the registration process, it has to go through pre-checking.

Pre-checking is a game of attempting preparation and reporting the results back on-chain.

We define preparation as a process that: validates the consistency of the wasm binary (aka prevalidation) and the compilation of the wasm module into machine code (refered to as artifact).

Besides pre-checking, preparation can also be triggered by execution, since a compiled artifact is needed for the execution.

[glossary]: glossary.md#pvf
[3211]: https://github.com/paritytech/polkadot/issues/3211
[paras]: runtime/paras.md
[pvf-runtime-api]: runtime-api/pvf-prechecking.md
[pvf-prechecker-subsystem]: node/utility/pvf-prechecker.md