(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_num_public_keys
    - ext_crypto_bls381_public_key
    - ext_crypto_bls381_sign
    - ext_crypto_ecdsa_bls381_generate
    - ext_crypto_ecdsa_bls381_num_public_keys
    - ext_crypto_ecdsa_bls381_public_key
    - ext_crypto_ecdsa_bls381_sign
    - ext_crypto_ecdsa_bls381_sign_with_keccak256

# RFC-0156: Add BLS12-381 Host Functions

Start Date | 2025-10-15
Description | Introduce BLS12-381 host functions
Author | Someone Unknown

## 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_num_public_keys

Retrieves the number of BLS12-381 keys of the given type available in the keystore.

#### Prototype

    (func $ext_crypto_bls381_num_public_keys_version_1
     (param $id i32) (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.

#### Result

The result represents a (possibly zero) number of keys of the given type known to the keystore.

### ext_crypto_bls381_public_key

Retrieves a BLS12-381 public key of a given type at a given index from the keystore.

#### Prototype

    (func $ext_crypto_bls381_public_key_version_1
     (param $id i32) (param $index i32) (param $out))

#### Arguments

- `id` is a pointer (Definition 215) to a key type identifier (Definition 220). The function will panic if the identifier is invalid;
- `index` is an index of the key in the keystore. If the index is out of bounds (determined by the value returned by the `ext_crypto_bls381_num_public_keys` function), the function will panic;
- `out` is a pointer (Definition 215) to an output buffer, 144 bytes long, where the key will be written.

### 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_key` 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_num_public_keys

Retrieves the number of ECDSA & BLS12-381 keys of a given type available in the keystore.

#### Prototype

    (func $ext_crypto_ecdsa_bls381_num_public_keys_version_1
     (param $id i32) (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.

#### Result

The result represents a (possibly zero) number of keys of the given type known to the keystore.

### ext_crypto_ecdsa_bls381_public_key

Retrieves an ECDSA & BLS12-381 public key of a given type at a given index from the keystore.

#### Prototype

    (func $ext_crypto_ecdsa_bls381_public_key_version_1
     (param $id i32) (param $index i32) (param $out))

#### Arguments

- `id` is a pointer (Definition 215) to a key type identifier (Definition 220). The function will panic if the identifier is invalid;
- `index` is an index of the key in the keystore. If the index is out of bounds (determined by the value returned by the `ext_crypto_ecdsa_bls381_num_public_keys` function), the function will panic;
- `out` is a pointer (Definition 215) to an output buffer, 177 bytes long, where the key will be written.

### ext_crypto_ecdsa_bls381_sign

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

#### Prototype

    (func $ext_crypto_ecdsa_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_ecdsa_bls381_public_key` 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, 177 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_sign_with_keccak256

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.

#### Prototype

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

#### 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_ecdsa_bls381_public_key` 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, 177 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.