(source)

Table of Contents

• RFC-0156: Add BLS12-381 Host Functions
  • Summary
  • Credits
  • Interaction with other RFCs
  • Motivation
  • Stakeholders
  • Explanation
    • ext_crypto_bls381_generate
    • ext_crypto_bls381_generate_proof_of_possession
    • ext_crypto_bls381_public_keys
    • ext_crypto_bls381_sign
    • ext_crypto_ecdsa_bls381_generate
    • ext_crypto_ecdsa_bls381_public_keys

RFC-0156: Add BLS12-381 Host Functions

Summary

Introduce new host functions allowing runtimes to generate BLS12-381 keys, signatures, and proofs of possession.

Credits

BLS implementation and initial host functions implementation are authored by Seyed Hosseini and co-authored by Davide Galassi.

Interaction with other RFCs

This RFC respects the runtime-side memory allocation strategy that will be introduced by RFC-145.

Motivation

New functions are required to equip BEEFY with BLS signatures, which are essential for the accountable light client protocol.

Stakeholders

Runtime developers who will be able to use the new signature types.

Explanation

This RFC proposes introducing new host functions as follows.

ext_crypto_bls381_generate

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.

Prototype

(func $ext_crypto_bls381_generate_version_1
 (param $id i32) (param $seed i64) (param $out i32))

Arguments

• id is a pointer (Definition 215) to a key type identifier (Definition 220). The function will panic if the identifier is invalid;
• seed is a pointer-size (Definition 216) to a SCALE-encoded Option value (Definition 200) containing a BIP-39 seed which must be valid UTF-8. The function will panic if the seed is not a valid UTF-8;
• out is a pointer (Definition 215) to an output buffer, 144 bytes long, where the public key will be written.

ext_crypto_bls381_generate_proof_of_possession

Generates a BLS12-381 Proof Of Possession for a given public key and owner identifier.

Prototype

(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))

Arguments

• id is a pointer (Definition 215) to a key type identifier (Definition 220). The function will panic if the identifier is invalid;
• pub_key is a pointer (Definition 215) to a public key, 144 bytes long;
• owner is a pointer-size (Definition 216) to an opaque owner identifier;
• out is a pointer (Definition 215) to an output buffer, 224 bytes long, where the proof of possession will be written.

Result

The function returns 0 on success. On error, -1 is returned, and the output buffer should be considered uninitialized.

ext_crypto_bls381_public_keys

Retrieves all BLS12-381 public keys of a given type from the keystore.

Prototype

(func $ext_crypto_bls381_public_keys_version_1
 (param $id i32) (param $out i64) (result i32))

Arguments

• id is a pointer (Definition 215) to a key type identifier (Definition 220). The function will panic if the identifier is invalid;
• out is a pointer-size (Definition 216) to a buffer where the public keys of the given type known to the keystore will be stored consecutively. The value is actually stored only if the buffer is large enough. Otherwise, the buffer is not written into, and its contents are unchanged.

Result

The result is an unsigned 32-bit integer representing the total size in bytes required to store all public keys of the given type. The number of keys can be determined by dividing this value by the known key size (144 bytes for BLS12-381). A value of 0 indicates that no keys of the given type are known to the keystore.

ext_crypto_bls381_sign

Signs an input message using a given BLS12-381 key.

Prototype

(func $ext_crypto_bls381_sign_version_1
 (param $id i32) (param $pub_key i32) (param $msg i64) (param $out i64) (result i64))

Arguments

• id is a pointer (Definition 215) to a key type identifier (Definition 220). The function will panic if the identifier is invalid;
• pub_key is a pointer (Definition 215) to public key bytes (as returned by ext_crypto_bls381_public_keys function);
• msg is a pointer-size (Definition 216) to a message that is to be signed;
• out is a pointer (Definition 215) to an output buffer, 112 bytes long, where the signature will be written.

Result

The function returns 0 on success. On error, -1 is returned, and the output buffer should be considered uninitialized.

ext_crypto_ecdsa_bls381_generate

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.

Prototype

(func $ext_crypto_ecdsa_bls381_generate_version_1
 (param $id i32) (param $seed i64) (param $out i32))

Arguments

• id is a pointer (Definition 215) to a key type identifier (Definition 220). The function will panic if the identifier is invalid;
• seed is a pointer-size (Definition 216) to a SCALE-encoded Option value (Definition 200) containing a BIP-39 seed which must be valid UTF-8. The function will panic if the seed is not a valid UTF-8;
• out is a pointer (Definition 215) to an output buffer, 177 bytes long, where the public key will be written.

ext_crypto_ecdsa_bls381_public_keys

Retrieves all ECDSA & BLS12-381 public keys of a given type from the keystore.

Prototype

(func $ext_crypto_ecdsa_bls381_public_keys_version_1
 (param $id i32) (param $out i64) (result i32))

Arguments

• id is a pointer (Definition 215) to a key type identifier (Definition 220). The function will panic if the identifier is invalid;
• out is a pointer-size (Definition 216) to a buffer where the public keys of the given type known to the keystore will be stored consecutively. The value is actually stored only if the buffer is large enough. Otherwise, the buffer is not written into, and its contents are unchanged.

Result

The result is an unsigned 32-bit integer representing the total size in bytes required to store all public keys of the given type. The number of keys can be determined by dividing this value by the known key size (177 bytes for ECDSA & BLS12-381). A value of 0 indicates that no keys of the given type are known to the keystore.