Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Module 0x1::randomness_config

Structs and functions for on-chain randomness configurations.

use 0x1::config_buffer;
use 0x1::copyable_any;
use 0x1::fixed_point64;
use 0x1::string;
use 0x1::system_addresses;

Resource RandomnessConfig

The configuration of the on-chain randomness feature.

struct RandomnessConfig has copy, drop, store, key
Fields
variant: copyable_any::Any
A config variant packed as an Any. Currently the variant type is one of the following. - ConfigOff - ConfigV1

Struct ConfigOff

A randomness config variant indicating the feature is disabled.

struct ConfigOff has copy, drop, store
Fields
dummy_field: bool

Struct ConfigV1

A randomness config variant indicating the feature is enabled.

struct ConfigV1 has copy, drop, store
Fields
secrecy_threshold: fixed_point64::FixedPoint64
Any validator subset should not be able to reconstruct randomness if subset_power / total_power <= secrecy_threshold,
reconstruction_threshold: fixed_point64::FixedPoint64
Any validator subset should be able to reconstruct randomness if subset_power / total_power > reconstruction_threshold.

Struct ConfigV2

A randomness config variant indicating the feature is enabled with fast path.

struct ConfigV2 has copy, drop, store
Fields
secrecy_threshold: fixed_point64::FixedPoint64
Any validator subset should not be able to reconstruct randomness if subset_power / total_power <= secrecy_threshold,
reconstruction_threshold: fixed_point64::FixedPoint64
Any validator subset should be able to reconstruct randomness if subset_power / total_power > reconstruction_threshold.
fast_path_secrecy_threshold: fixed_point64::FixedPoint64
Any validator subset should not be able to reconstruct randomness via the fast path if subset_power / total_power <= fast_path_secrecy_threshold,

Constants 

const EINVALID_CONFIG_VARIANT: u64 = 1;

Function initialize

Initialize the configuration. Used in genesis or governance.

public fun initialize(framework: &signer, config: randomness_config::RandomnessConfig)
Implementation 
public fun initialize(framework: &signer, config: RandomnessConfig) {
    system_addresses::assert_aptos_framework(framework);
    if (!exists<RandomnessConfig>(@aptos_framework)) {
        move_to(framework, config)
    }
}

Function set_for_next_epoch

This can be called by on-chain governance to update on-chain consensus configs for the next epoch.

public fun set_for_next_epoch(framework: &signer, new_config: randomness_config::RandomnessConfig)
Implementation 
public fun set_for_next_epoch(framework: &signer, new_config: RandomnessConfig) {
    system_addresses::assert_aptos_framework(framework);
    config_buffer::upsert(new_config);
}

Function on_new_epoch

Only used in reconfigurations to apply the pending RandomnessConfig, if there is any.

public(friend) fun on_new_epoch(framework: &signer)
Implementation 
public(friend) fun on_new_epoch(framework: &signer) acquires RandomnessConfig {
    system_addresses::assert_aptos_framework(framework);
    if (config_buffer::does_exist<RandomnessConfig>()) {
        let new_config = config_buffer::extract_v2<RandomnessConfig>();
        if (exists<RandomnessConfig>(@aptos_framework)) {
            *borrow_global_mut<RandomnessConfig>(@aptos_framework) = new_config;
        } else {
            move_to(framework, new_config);
        }
    }
}

Function enabled

Check whether on-chain randomness main logic (e.g., DKGManager, RandManager, BlockMetadataExt) is enabled.

NOTE: this returning true does not mean randomness will run. The feature works if and only if consensus_config::validator_txn_enabled() && randomness_config::enabled().

public fun enabled(): bool
Implementation 
public fun enabled(): bool acquires RandomnessConfig {
    if (exists<RandomnessConfig>(@aptos_framework)) {
        let config = borrow_global<RandomnessConfig>(@aptos_framework);
        let variant_type_name = *config.variant.type_name().bytes();
        variant_type_name != b"0x1::randomness_config::ConfigOff"
    } else {
        false
    }
}

Function new_off

Create a ConfigOff variant.

public fun new_off(): randomness_config::RandomnessConfig
Implementation 
public fun new_off(): RandomnessConfig {
    RandomnessConfig {
        variant: copyable_any::pack( ConfigOff {} )
    }
}

Function new_v1

Create a ConfigV1 variant.

public fun new_v1(secrecy_threshold: fixed_point64::FixedPoint64, reconstruction_threshold: fixed_point64::FixedPoint64): randomness_config::RandomnessConfig
Implementation 
public fun new_v1(secrecy_threshold: FixedPoint64, reconstruction_threshold: FixedPoint64): RandomnessConfig {
    RandomnessConfig {
        variant: copyable_any::pack( ConfigV1 {
            secrecy_threshold,
            reconstruction_threshold
        } )
    }
}

Function new_v2

Create a ConfigV2 variant.

public fun new_v2(secrecy_threshold: fixed_point64::FixedPoint64, reconstruction_threshold: fixed_point64::FixedPoint64, fast_path_secrecy_threshold: fixed_point64::FixedPoint64): randomness_config::RandomnessConfig
Implementation 
public fun new_v2(
    secrecy_threshold: FixedPoint64,
    reconstruction_threshold: FixedPoint64,
    fast_path_secrecy_threshold: FixedPoint64,
): RandomnessConfig {
    RandomnessConfig {
        variant: copyable_any::pack( ConfigV2 {
            secrecy_threshold,
            reconstruction_threshold,
            fast_path_secrecy_threshold,
        } )
    }
}

Function current

Get the currently effective randomness configuration object.

public fun current(): randomness_config::RandomnessConfig
Implementation 
public fun current(): RandomnessConfig acquires RandomnessConfig {
    if (exists<RandomnessConfig>(@aptos_framework)) {
        *borrow_global<RandomnessConfig>(@aptos_framework)
    } else {
        new_off()
    }
}

Specification

Function on_new_epoch 

public(friend) fun on_new_epoch(framework: &signer)

requires @aptos_framework == std::signer::address_of(framework);
include config_buffer::OnNewEpochRequirement<RandomnessConfig>;
aborts_if false;

Function current 

public fun current(): randomness_config::RandomnessConfig

aborts_if false;