Module 0x1::epoch_timeout_config

On-chain config for the epoch force-end watchdog.

When configured with force_end_grace_period_secs = some(n), an in-progress reconfiguration is finalized unconditionally (regardless of DKG state) once now >= last_reconfiguration_time + epoch_interval + n_secs.

When force_end_grace_period_secs = none, the watchdog is disabled.

• Resource EpochTimeoutConfig
• Constants
• Function initialize
• Function set_for_next_epoch
• Function on_new_epoch
• Function new_disabled
• Function new_with_grace_period
• Function force_end_grace_period_secs
• Specification
  • Function on_new_epoch
  • Function new_with_grace_period

use 0x1::config_buffer;
use 0x1::error;
use 0x1::option;
use 0x1::system_addresses;

Resource EpochTimeoutConfig

struct EpochTimeoutConfig has copy, drop, store, key

Constants

new_with_grace_period(0) is disallowed: a zero grace period would cause the watchdog to fire in the same block prologue that triggers reconfig, skipping DKG entirely. Use new_disabled() if you mean to disable the watchdog.

const E_GRACE_PERIOD_MUST_BE_POSITIVE: u64 = 1;

Function initialize

Initialize the configuration. Used in genesis or governance.

public fun initialize(framework: &signer)

public fun initialize(framework: &signer) {
    system_addresses::assert_aptos_framework(framework);
    if (!exists<EpochTimeoutConfig>(@aptos_framework)) {
        move_to(framework, new_disabled())
    }
}

Function set_for_next_epoch

Used by on-chain governance to update the watchdog config for the next epoch.

public fun set_for_next_epoch(framework: &signer, new_config: epoch_timeout_config::EpochTimeoutConfig)

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

Function on_new_epoch

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

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

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

Function new_disabled

public fun new_disabled(): epoch_timeout_config::EpochTimeoutConfig

public fun new_disabled(): EpochTimeoutConfig {
    EpochTimeoutConfig { force_end_grace_period_secs: std::option::none() }
}

Function new_with_grace_period

Build a watchdog config with a positive grace period (seconds). The grace period is the slack allowed beyond the epoch interval before the watchdog force-finalizes the reconfig. Aborts on grace_period_secs == 0 — pass through new_disabled() to turn the watchdog off.

public fun new_with_grace_period(grace_period_secs: u64): epoch_timeout_config::EpochTimeoutConfig

public fun new_with_grace_period(grace_period_secs: u64): EpochTimeoutConfig {
    assert!(
        grace_period_secs > 0,
        error::invalid_argument(E_GRACE_PERIOD_MUST_BE_POSITIVE),
    );
    EpochTimeoutConfig {
        force_end_grace_period_secs: std::option::some(grace_period_secs)
    }
}

Function force_end_grace_period_secs

Return the configured grace period in seconds, or none if the watchdog is disabled (or the resource has not been initialized).

public fun force_end_grace_period_secs(): option::Option<u64>

public fun force_end_grace_period_secs(): Option<u64> acquires EpochTimeoutConfig {
    if (exists<EpochTimeoutConfig>(@aptos_framework)) {
        borrow_global<EpochTimeoutConfig>(@aptos_framework).force_end_grace_period_secs
    } else {
        std::option::none()
    }
}

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<EpochTimeoutConfig>;
aborts_if false;

Function new_with_grace_period

public fun new_with_grace_period(grace_period_secs: u64): epoch_timeout_config::EpochTimeoutConfig

aborts_if grace_period_secs == 0;