Dedicated SCALE mini website

[kianenigma]

A simple github hosted website on the https://github.com/paritytech/parity-scale-codec website itself, explaining the low level format with nice examples: https://docs.substrate.io/reference/scale-codec/.

Inspired by https://borsh.io/.

Github has a lot of templates to build this kind of stuff easily.

We strongly think that the best way to teach SCALE is by lots of examples, so be creative on how you represent them, and find some very nice slides loaded with examples here: https://github.com/Polkadot-Blockchain-Academy/pba-content/blob/main/syllabus/4-Substrate/4.x-SCALE_Slides.md

This is in the spirit of documenting more things externally and reducing the workload on this repo.

[kianenigma]

Is there any intermediate outcome of this that we can have a look at?

[wentelteefje]

Website (still WIP): https://wentelteefje.github.io/parity-scale-codec-page/docs/intro/ SCALE spec: https://spec.polkadot.network/id-cryptography-encoding#sect-scale-codec

Here is a list of questions and findings that have emerged so far:

• Are float encodings relevant at all (they are never mentioned anywhere)?
• Should we include some Substrate-specific example use cases for types such as AccountID etc?
• In the linked PBA SCALE slides p.14: Replace the sentence "Big-integer mode: The upper six bits are the number of bytes following, plus four." by "Big-integer mode: The upper six bits are the number of bytes following, minus four."
• PBA slides introduce compact encoding by talking about "general integers". I personally don't like this naming convention, because SCALE compact/length encoding is only available for non-negative(!) integers (=natural numbers). From a mathematical perspective the term "general" seems quite unfitting. Is there a good reason rooted in Rust for the use of the term "general" that I'm unaware of?
• Maybe related: The HasCompact trait is used to tell if a given type can be encoded/decoded in a compact way. However, the specification defines compact encoding only with respect to non-negative integers. Does the Rust implementation of SCALE deviate from the specification and implement compact encoding for other types as well? If so, how can I figure out which Rust native types implement the HasCompact trait out of the box?
• Also w.r.t. compact/length encoding I noticed, that the Rust implementation seems not to follow the specification when it comes to Big-integer mode. In Def. 198 of the specification $m$ refers to the total number of bytes in a Big-integer encoding, including the first byte. In the Rust implementation though, $m$ only counts the number of bytes following the first byte. This probably won't pose a problem unless, in some way, it interferes with other implementations of SCALE.

[kianenigma]

Are float encodings relevant at all (they are never mentioned anywhere)?

Floating point numbers are not really used in Substrate based chains due to their undeterministic nature. There should be some content about this in the old docs.

Should we include some Substrate-specific example use cases for types such as AccountID etc?

Yes, although account id is usually a raw 32 byte which encodes to itself.

[kianenigma]

Once done, this should also go into #6.