polkadot-blockchain-academy/pba-book

The materials used in the Polkadot Blockchain Academy

Polkadot Blockchain Academy

The Polkadot Blockchain Academy is an intensive academic program teaching Blockchain, Substrate and Polkadot to talented developers.

This program aims at:

• Improving our core dev hiring pipeline in both quantity and quality of candidates
• Seeding the industry with Substrate knowledge and advocates
• Building a surplus of developers for lesser product prototyping if they’re not hired out
• Improving our non-dev onboarding processes

Selected through an admission process, candidates will receive an intensive education taught by a mix of professionals from Parity, Web3 and some visiting professors.

Curriculum Versions

The curriculum is expected to change per cohort in the first run. You can find the snapshot of the slides at the end of each cohort here:

• Cambridge - August 2022
• Buenos Aires - January 2023
• Berkeley - July 2023
• Hong Kong - January 2024

Venue Suggestions

This curriculum is designed to be taught as an in-person course with ~25-60 students. (Although it may be somewhat useful for online or independent learning). The venue where the course is taught should provide the following. These may be a single space with flexible seating, or two different spaces for lecture- and collaboration-style work.

• Overhead projector that all students can easily see
• Aisles for instructors to easily move among students to answer questions or help debug
• Group work stations where student groups of 5-10 students can gather
• A large whiteboard for instructors to share diagrams
• Internet connection that can support >10Mbps while all students are connected
• LAN connection that allows P2P connections to start a private blockchain network

Contributing

Subject Matter Experts (SMEs) should explore ./CONTRIBUTING.md to learn how to use this repo.

pba-book's Issues

CI isn't deploying Pages

Example: https://github.com/Polkadot-Blockchain-Academy/pba-book/actions/runs/6204872842

Reported upstream:

• actions/deploy-pages#222
• Asking for community help: https://github.com/orgs/community/discussions/66706#discussion-5613026

The error:

Error: Deployment failed, Please ensure that the file permissions are correct.

Thus this might be due to #2 having bun write static files with bad permissions, and rsync picks them up... unclear.

Move to faster and more feature rich link checker

See paritytech/polkadot-sdk#1875 as reference, https://github.com/lycheeverse/lychee is far more feature rich that mlc and likely faster to boot.

Rectanlges appearing in section 4.2 Substrate Wasm Meta-Protocol

Some rectangles are appearing and shouldn't be there(see below):

Move to more legible non-header Font

Ran into https://fonts.google.com/specimen/Atkinson+Hyperlegible via https://www.dedp.online/introduction.html and IMHO it is a much more legible (true to it's name!) font face than we use at the moment (work sans, vendored not a CDN). I would think keeping Unbounded (The official & treasury funded Polkadot's ecosystem font) as a header font and perhaps emphasis option is a good idea.

If this were adopted for the book, there should be no issue I would expect, but in the slides there may be some minor visual bugs as this would change the fixed pixel width we have been relying on with the present font (neither of these are monospace... perhaps mono would be a good option moving forward if there is a desire to update fonts over time)

Define a CLA and impliment a mechanism to sign it

Something akin to https://cla.parity.io/ that is used for contributors to the Polkadot SDK would be ideal IMHO. As it stands, the license is all that describes rights of contributors as, that may be enough. But a CLA should likely be considered in addition to it.

--v appearing

Is there an easy fix to solve this --v appearing (see below)?

Preprocessor to remove `yml` header for slides in book pages

The raw slides.md file is placed in the page.md file when rendered, although this leads the the yml header of that file to be dumped there too, and it's not useful in that form to the reader. There may be an easy fix to add an mdbook preprocessor to remove that: https://github.com/dvogt23/mdbook-yml-header/tree/main

Considerations

This should work as the slides are rendered first and apart from the book at this time, note that if the reveal tooling is brought into a mdbook preprocessor or something like this, it could be this other yml header remover would remove it before the slides were processsed (and the slides do benefit from it, and need it in cases that custom settings are passed)

Random Colored Artifacts Showing Up

See:

These colored blocks show up when I navigate to this page:

https://polkadot-blockchain-academy.github.io/pba-book/substrate/wasm/page.html?highlight=wasm%20export#workshop-inspecting-wasm-code

They stay fixed on screen as you scroll.

Move from Cargo Make to Just

While cargo make is nice, seeing https://github.com/casey/just far more commonly, and TBH it's far more legible and succinct IMHO even though it is an DSL... Thus a move to a simpler make system should help contributors be able to clearly see what each task/job is doing and how to modify it very easily.

The migration should be rather trivial, just need to ensure the CI is updated. As a nice followup or in closing this, using the just file instead of CI being independent would make this repo more DRY too. see https://github.com/casey/just#github-actions

Add missed public repos

Missed in first cut of the Book post UCB, now opened up as public repos:

• https://github.com/Polkadot-Blockchain-Academy/pba-zombienet
• https://github.com/Polkadot-Blockchain-Academy/formal-verification-kani-scale-codec
• https://github.com/Polkadot-Blockchain-Academy/frame-testing-exercise

Update how-to on jump-to-top

1. you can click any header
2. your URL (on refresh / share etc.) jumps to that location again on refresh
3. hit the top banner to quick scroll up to the top of the page ✨

So getting back to slides is easier. Perhaps this would also remove the hacked in bottom right #top button we have now to do that.

makers serve command not working for me

I am trying to build the book for offline use. makers install and makers build both worked fine, but when I run makers serve I get an error (sh: line 1: type: mlc: not found) and the suggested fix is to run makers install-dev, but that gives the error shown below (and the suggested fix for that is the same command I was running (so it is recursive lol):

error[E0635]: unknown feature proc_macro_span_shrink
--> /Users/rogerbos/.cargo/registry/src/index.crates.io-6f17d22bba15001f/proc-macro2-1.0.47/src/lib.rs:92:30
|
92 | feature(proc_macro_span, proc_macro_span_shrink)
| ^^^^^^^^^^^^^^^^^^^^^^

Compiling futures-io v0.3.21
For more information about this error, try rustc --explain E0635.
error: could not compile proc-macro2 (lib) due to previous error
warning: build failed, waiting for other jobs to finish...
error: failed to compile mlc v0.16.2, intermediate artifacts can be found at /var/folders/_f/jx8_bq5j6z156s5v4_hwx4xc0000gp/T/cargo-installZOWg04.
To reuse those artifacts with a future compilation, set the environment variable CARGO_TARGET_DIR to that path.
[cargo-make][1] ERROR - Error while executing command, exit code: 101
[cargo-make][1] WARN - Build Failed.
[cargo-make] INFO - Running Task: catch-error
sh: line 1: type: mlc: not found
-e ❌ You may need to install the dev tooling. Run:

makers install-dev

Any suggested fix or workaround would be welcomed. Thanks in advance.

Automated PR deployment prereviews

It would be great to have each PR have an up-to-date rendering of the book to accelerate reviews.

We have used fleek before to host slides (IPFS hosted too 🌟) very easily. We use Github pages for the main deployment at his time, but an alternative web3 first host,, we could go back to using fleek. Notably, they allow PR development previews very easily too: https://docs.fleek.co/internet-computer-hosting/site-deployment/#previewing-a-deployment that looks like a good fit for this purpose. Of course, there are other avenues to getting a deployment preview too we could consider.

Using webp format to reduce repository size

Allowing any type of image format could lead to a heavy repository. I would suggest converting all images to webp (considering the repository data is consumed as a website/slides). A webp images can be as minimum 25% less heavy than a PNG or JPEG (Study).

There is already a File Size comparison section, maybe we could add here the recommendation of using webp. In the same way, maybe adding a makers img-conv command that convert all images non-webp to webp can be a good idea. This can be done with the cwebp package.

As example, in my latest PR I was able to reduce size of some PNG from 10 mb to 900kb.

Enable translations

Enable contributors to translate to multiple languages, here is the inspiration from Comprehensive Rust repo: https://github.com/google/comprehensive-rust/blob/main/TRANSLATIONS.md#translations-of-comprehensive-rust-