This book contains the Polkadot Fellowship Requests for Comments (RFCs) detailing proposed changes to the technical implementation of the Polkadot network.
polkadot-fellows/RFCs
(source)
Table of Contents
Introduce new host functions allowing runtimes to generate BLS12-381 keys, signatures, and proofs of possession.
BLS implementation and initial host functions implementation are authored by Seyed Hosseini and co-authored by Davide Galassi.
This RFC respects the runtime-side memory allocation strategy that will be introduced by RFC-145.
New functions are required to equip BEEFY with BLS signatures, which are essential for the accountable light client protocol.
Runtime developers who will be able to use the new signature types.
This RFC proposes introducing new host functions as follows.
Generates a BLS12-381 key for the given key type using an optional seed, stores it in the keystore, and returns a corresponding public key.
seed
(func $ext_crypto_bls381_generate_version_1 - (param $id i32) (param $seed i64) (param $out i32)) -
id
out
Generates a BLS12-381 Proof Of Possession for a given public key and owner identifier.
(func $ext_crypto_bls381_generate_proof_of_possession_version_1 - (param $id i32) (param $pub_key i32) (param $owner i64) (param $out i32) (result i64)) -
pub_key
owner
The function returns 0 on success. On error, -1 is returned, and the output buffer should be considered uninitialized.
0
-1
Retrieves the number of BLS12-381 keys of the given type available in the keystore.
(func $ext_crypto_bls381_num_public_keys_version_1 - (param $id i32) (result i32)) -
The result represents a (possibly zero) number of keys of the given type known to the keystore.
Retrieves a BLS12-381 public key of a given type at a given index from the keystore.
(func $ext_crypto_bls381_public_key_version_1 - (param $id i32) (param $index i32) (param $out)) -
index
ext_crypto_bls381_num_public_keys
Signs an input message using a given BLS12-381 key.
(func $ext_crypto_bls381_sign_version_1 - (param $id i32) (param $pub_key i32) (param $msg i64) (param $out i64) (result i64)) -
ext_crypto_bls381_public_key
msg
Generates a combination ECDSA & BLS12-381 key for a given key type using an optional seed, stores it in the keystore, and returns the corresponding public key.
(func $ext_crypto_ecdsa_bls381_generate_version_1 - (param $id i32) (param $seed i64) (param $out i32)) -
Retrieves the number of ECDSA & BLS12-381 keys of a given type available in the keystore.
(func $ext_crypto_ecdsa_bls381_num_public_keys_version_1 - (param $id i32) (result i32)) -
Retrieves an ECDSA & BLS12-381 public key of a given type at a given index from the keystore.
(func $ext_crypto_ecdsa_bls381_public_key_version_1 - (param $id i32) (param $index i32) (param $out)) -
ext_crypto_ecdsa_bls381_num_public_keys
Signs an input message using a given ECDSA & BLS12-381 key.
(func $ext_crypto_ecdsa_bls381_sign_version_1 - (param $id i32) (param $pub_key i32) (param $msg i64) (param $out i64) (result i64)) -
ext_crypto_ecdsa_bls381_public_key
Hashes a message using Keccak256 and then signs it using the ECDSA algorithm. It does not affect the behavior of the BLS12-381 component. Generates a BLS12-381 signature according to the IETF standard.
(func $ext_crypto_ecdsa_bls381_sign_with_keccak256_version_1 - (param $id i32) (param $pub_key i32) (param $msg i64) (param $out i64) (result i64)) -
Update the runtime-host interface so that it no longer uses the host-side allocator.
The API of these new functions was heavily inspired by the API used by the C programming language.
ext_misc_runtime_version
ext_offchain_random_seed
The heap allocation of the runtime is currently controlled by the host using a memory allocator on the host side.
The API of many host functions contains buffer allocations. For example, when calling ext_hashing_twox_256_version_1, the host allocates a 32-byte buffer using the host allocator, and returns a pointer to this buffer to the runtime. The runtime later has to call ext_allocator_free_version_1 on this pointer to free the buffer.
ext_hashing_twox_256_version_1
ext_allocator_free_version_1
Even though no benchmark has been done, it is pretty obvious that this design is very inefficient. To continue with the example of ext_hashing_twox_256_version_1, it would be more efficient to instead write the output hash to a buffer allocated by the runtime on its stack and passed by pointer to the function. Allocating a buffer on the stack, in the worst case, consists simply of decreasing a number; in the best case, it is free. Doing so would save many VM memory reads and writes by the allocator, and would save a function call to ext_allocator_free_version_1.
Furthermore, the existence of the host-side allocator has become questionable over time. It is implemented in a very naive way: every allocation is rounded up to the next power of two, and once a piece of memory is allocated it can only be reused for allocations which also round up to the exactly the same size. So in theory it's possible to end up in a situation where we still technically have plenty of free memory, but our allocations will fail because all of that memory is reserved for differently sized buckets. That behavior is de-facto hardcoded into the current protocol and for determinism and backwards compatibility reasons, it needs to be implemented exactly identically in every client implementation.
In addition to that, runtimes make substantial use of heap memory allocations, and each allocation needs to go through the runtime <-> host boundary twice (once for allocating and once for freeing). Moving the allocator to the runtime side would be a good idea, although it would increase the runtime size. But before the host-side allocator can be deprecated, all the host functions that use it must be updated to avoid using it.
Runtime developers, who will benefit from the improved performance and more deterministic behavior of the runtime code.
The Runtime optional positive integer is a signed 64-bit value. Positive values in the range of [0..2³²) represent corresponding unsigned 32-bit values. The value of -1 represents a non-existing value (an absent value). All other values are invalid.
(func $ext_storage_read_version_2 (param $key i64) (param $value_out i64) (param $value_offset i32) (result i64))
key
value_out
value_offset
The result is an optional positive integer (New Definition I), representing either the full length of the value in storage or the absence of such a value in storage.
maybe_prefix
maybe_limit
unique
loops
The result represents the length of the continuation cursor which might have been written to the buffer provided in maybe_cursor_out. A zero value represents the absence of such a cursor and no need for continuation (the prefix has been completely cleared).
maybe_cursor_out
(func $ext_storage_root_version_3 (param $out i64) (result i32))
(func $ext_storage_next_key_version_2 (param $key_in i64) (param $key_out i64) (result i32))
key_in
key_out
The result is the full length of the output key that might have been stored in key_out, or zero if no next key was found.
storage_key
prefix
(func $ext_default_child_storage_root_version_3 (param $storage_key i64) (param $out i64) (result i32))
(func $ext_default_child_storage_next_key_version_2 (param $storage_key i64) (param $key_in i64) (param $key_out i64) (result i32))
The result is the length of the output key that might have been written into key_out, or zero if no next key was found.
(func $ext_trie_{blake2|keccak}_256_[ordered_]root_version_3 (param $input i64) (param $version i32) (param $out i32))
input
version
1
(func $ext_misc_runtime_version_version_2 (param $wasm i64) (param $out i64) (result i64))
wasm
The result is an optional positive integer (New Definition I) representing the length of the output data that might have been stored in out. An absent value represents the absence of the version information in the Wasm blob or a failure to read one.
(func $ext_crypto_{ed25519|sr25519|ecdsa}_num_public_keys (param $id i32) (result i32))
(func $ext_crypto_{ed25519|sr25519|ecdsa}_public_key (param $id i32) (param $index i32) (param $out))
_num_public_keys
(func $ext_crypto_{ed25519|sr25519|ecdsa}_generate_version_2 (param $id i32) (param $seed i64) (param $out i32))
(func $ext_crypto_{ed25519|sr25519|ecdsa}_sign{_prehashed|}_version_2 (param $id i32) (param $pub_key i32) (param $msg i64) (param $out i64) (result i64))
_public_key
The function returns 0 on success. On error, -1 is returned and the output buffer should be considered uninitialized.
(func $ext_crypto_secp256k1_ecdsa_recover\[_compressed]_version_3 (param $sig i32) (param $msg i32) (param $out i32) (result i64))
sig
The function returns 0 on success. On error, it returns a negative ECDSA verification error code, where -1 stands for incorrect R or S, -2 stands for invalid V, and -3 stands for invalid signature.
-2
-3
(func $ext_hashing_{keccak|sha2|blake2|twox}_{64|128|256|512}_version_2 (param $data i64) (param $out i32))
data
(func $ext_offchain_submit_transaction_version_2 (param $data i64) (result i64))
The result is 0 for success or -1 for failure.
(func $ext_offchain_submit_transaction_version_2 (param $out i32) (result i64))
(func $ext_offchain_random_seed_version_2 (param $out i32))
(func $ext_offchain_local_storage_read_version_1 (param $kind i32) (param $key i64) (param $value_out i64) (param $offset i32) (result i64))
kind
offset
(func $ext_offchain_http_request_start_version_2 (param $method i64) (param $uri i64) (param $meta i64) (result i64))
method is a pointer-size (Definition 216) to the HTTP method. Possible values are “GET” and “POST”; uri is a pointer-size (Definition 216) to the URI; meta is a future-reserved field containing additional, SCALE-encoded parameters. Currently, an empty array should be passed.
method
uri
meta
On success, a positive request identifier is returned. On error, -1 is returned.
(func $ext_offchain_http_request_add_header_version_2 (param $request_id i32) (param $name i64) (param $value i64) (result i64))
request_id
ext_offchain_http_request_start
name
value
(func $ext_offchain_http_request_write_body_version_2 (param $request_id i32) (param $chunk i64) (param $deadline i64) (result i64))
chunk
deadline
None
On success, 0 is returned. On failure, a negative error code is returned, where -1 denotes the deadline was reached, -2 denotes that an I/O error occurred, and -3 denotes that the request ID provided was invalid.
(func $ext_offchain_http_response_wait_version_2 (param $ids i64) (param $deadline i64) (param $out i64))
ids
(func $ext_offchain_http_response_header_name_version_1 (param $request_id i32) (param $header_index i32) (param $out i64) (result i64))
header_index
The result is an optional positive integer (New Definition I), representing either the full length of the header name or the absence of the header with such index.
(func $ext_offchain_http_response_header_value_version_1 (param $request_id i32) (param $header_index i32) (param $out i64) (result i64))
The result is an optional positive integer (New Definition I), representing either the full length of the header value or the absence of the header with such index.
(func $ext_offchain_http_response_read_body_version_2 (param $request_id i32) (param $buffer i64) (param $deadline i64) (result i64))
buffer
On success, the number of bytes written to the buffer is returned. A value of 0 means the entire response was consumed and no further calls to the function are needed for the provided request ID. On failure, a negative error code is returned, where -1 denotes the deadline was reached, -2 denotes that an I/O error occurred, and -3 denotes that the request ID provided was invalid.
(func $ext_input_read_version_1 (param $buffer i64))
pUSD (Polkadot USD over-collateralised debt token) is a new DOT-collateralized stablecoin deployed on Asset Hub. It is an overcollateralized stablecoin backed purely by DOT. The implementation follows the Honzon protocol pioneered by Acala. In addition, this RFC introduces an opt-in pUSD Savings module that lets holders lock pUSD to earn interest funded from stability fees.
"Polkadot Hub should have a native DOT backed stable coin because people need it and otherwise we will haemorrhage benefits, liquidity and/or security." - Gav
pUSD is implemented using the Honzon protocol stack used to power aUSD, adapted for DOT-only collateral on Asset Hub.
The Honzon protocol functions as a lending system where users can:
(func $ext_crypto_bls381_generate_version_1 + (param $id i32) (param $seed i64) (param $out i32)) +
(func $ext_crypto_bls381_generate_proof_of_possession_version_1 + (param $id i32) (param $pub_key i32) (param $owner i64) (param $out i32) (result i64)) +
(func $ext_crypto_bls381_num_public_keys_version_1 + (param $id i32) (result i32)) +
(func $ext_crypto_bls381_public_key_version_1 + (param $id i32) (param $index i32) (param $out)) +
(func $ext_crypto_bls381_sign_version_1 + (param $id i32) (param $pub_key i32) (param $msg i64) (param $out i64) (result i64)) +
(func $ext_crypto_ecdsa_bls381_generate_version_1 + (param $id i32) (param $seed i64) (param $out i32)) +
(func $ext_crypto_ecdsa_bls381_num_public_keys_version_1 + (param $id i32) (result i32)) +
(func $ext_crypto_ecdsa_bls381_public_key_version_1 + (param $id i32) (param $index i32) (param $out)) +
(func $ext_crypto_ecdsa_bls381_sign_version_1 + (param $id i32) (param $pub_key i32) (param $msg i64) (param $out i64) (result i64)) +
(func $ext_crypto_ecdsa_bls381_sign_with_keccak256_version_1 + (param $id i32) (param $pub_key i32) (param $msg i64) (param $out i64) (result i64)) +