Module `0x1::DiemTimestamp`

This module keeps a global wall clock that stores the current Unix time in microseconds. It interacts with the other modules in the following ways:

Genesis: to initialize the timestamp
VASP: to keep track of when credentials expire
DiemSystem, DiemAccount, DiemConfig: to check if the current state is in the genesis state
DiemBlock: to reach consensus on the global wall clock time
AccountLimits: to limit the time of account limits

This module moreover enables code to assert that it is running in genesis (<code><a href="DiemTimestamp.md#0x1_DiemTimestamp_assert_genesis">Self::assert_genesis</a></code>) or after genesis (<code><a href="DiemTimestamp.md#0x1_DiemTimestamp_assert_operating">Self::assert_operating</a></code>). These are essentially distinct states of the system. Specifically, if <code><a href="DiemTimestamp.md#0x1_DiemTimestamp_assert_operating">Self::assert_operating</a></code> succeeds, assumptions about invariants over the global state can be made which reflect that the system has been successfully initialized.

Resource CurrentTimeMicroseconds
Constants
Function set_time_has_started
Function update_global_time
Function now_microseconds
Function now_seconds
Function is_genesis
Function assert_genesis
Function is_operating
Function assert_operating
Module Specification

<pre><code>use <a href="CoreAddresses.md#0x1_CoreAddresses">0x1::CoreAddresses</a>; use <a href="../../../../../../move-stdlib/docs/Errors.md#0x1_Errors">0x1::Errors</a>; </code></pre>

Resource `CurrentTimeMicroseconds`

A singleton resource holding the current Unix time in microseconds

<pre><code>resource struct <a href="DiemTimestamp.md#0x1_DiemTimestamp_CurrentTimeMicroseconds">CurrentTimeMicroseconds</a> </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>microseconds: u64</code> </dt> <dd> </dd> </dl> </details>

Constants

The blockchain is not in the genesis state anymore

<pre><code>const <a href="DiemTimestamp.md#0x1_DiemTimestamp_ENOT_GENESIS">ENOT_GENESIS</a>: u64 = 0; </code></pre>

The blockchain is not in an operating state yet

<pre><code>const <a href="DiemTimestamp.md#0x1_DiemTimestamp_ENOT_OPERATING">ENOT_OPERATING</a>: u64 = 1; </code></pre>

An invalid timestamp was provided

<pre><code>const <a href="DiemTimestamp.md#0x1_DiemTimestamp_ETIMESTAMP">ETIMESTAMP</a>: u64 = 2; </code></pre>

Conversion factor between seconds and microseconds

<pre><code>const <a href="DiemTimestamp.md#0x1_DiemTimestamp_MICRO_CONVERSION_FACTOR">MICRO_CONVERSION_FACTOR</a>: u64 = 1000000; </code></pre>

Function `set_time_has_started`

Marks that time has started and genesis has finished. This can only be called from genesis and with the root account.

<pre><code>public fun <a href="DiemTimestamp.md#0x1_DiemTimestamp_set_time_has_started">set_time_has_started</a>(dr_account: &signer) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="DiemTimestamp.md#0x1_DiemTimestamp_set_time_has_started">set_time_has_started</a>(dr_account: &signer) { <a href="DiemTimestamp.md#0x1_DiemTimestamp_assert_genesis">assert_genesis</a>(); <a href="CoreAddresses.md#0x1_CoreAddresses_assert_diem_root">CoreAddresses::assert_diem_root</a>(dr_account); let timer = <a href="DiemTimestamp.md#0x1_DiemTimestamp_CurrentTimeMicroseconds">CurrentTimeMicroseconds</a> { microseconds: 0 }; move_to(dr_account, timer); } </code></pre> </details> <details> <summary>Specification</summary>

The friend of this function is <code><a href="Genesis.md#0x1_Genesis_initialize">Genesis::initialize</a></code> which means that this function can't be verified on its own and has to be verified in context of Genesis execution. After time has started, all invariants guarded by <code><a href="DiemTimestamp.md#0x1_DiemTimestamp_is_operating">DiemTimestamp::is_operating</a></code> will become activated and need to hold.

<pre><code>pragma friend = <a href="Genesis.md#0x1_Genesis_initialize">0x1::Genesis::initialize</a>; include <a href="DiemTimestamp.md#0x1_DiemTimestamp_AbortsIfNotGenesis">AbortsIfNotGenesis</a>; include <a href="CoreAddresses.md#0x1_CoreAddresses_AbortsIfNotDiemRoot">CoreAddresses::AbortsIfNotDiemRoot</a>{account: dr_account}; ensures <a href="DiemTimestamp.md#0x1_DiemTimestamp_is_operating">is_operating</a>(); </code></pre> </details>

Function `update_global_time`

Updates the wall clock time by consensus. Requires VM privilege and will be invoked during block prologue.

<pre><code>public fun <a href="DiemTimestamp.md#0x1_DiemTimestamp_update_global_time">update_global_time</a>(account: &signer, proposer: address, timestamp: u64) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="DiemTimestamp.md#0x1_DiemTimestamp_update_global_time">update_global_time</a>( account: &signer, proposer: address, timestamp: u64 ) acquires <a href="DiemTimestamp.md#0x1_DiemTimestamp_CurrentTimeMicroseconds">CurrentTimeMicroseconds</a> { <a href="DiemTimestamp.md#0x1_DiemTimestamp_assert_operating">assert_operating</a>(); // Can only be invoked by DiemVM signer. <a href="CoreAddresses.md#0x1_CoreAddresses_assert_vm">CoreAddresses::assert_vm</a>(account); let global_timer = borrow_global_mut<<a href="DiemTimestamp.md#0x1_DiemTimestamp_CurrentTimeMicroseconds">CurrentTimeMicroseconds</a>>(<a href="CoreAddresses.md#0x1_CoreAddresses_DIEM_ROOT_ADDRESS">CoreAddresses::DIEM_ROOT_ADDRESS</a>()); let now = global_timer.microseconds; if (proposer == <a href="CoreAddresses.md#0x1_CoreAddresses_VM_RESERVED_ADDRESS">CoreAddresses::VM_RESERVED_ADDRESS</a>()) { // NIL block with null address as proposer. Timestamp must be equal. assert(now == timestamp, <a href="../../../../../../move-stdlib/docs/Errors.md#0x1_Errors_invalid_argument">Errors::invalid_argument</a>(<a href="DiemTimestamp.md#0x1_DiemTimestamp_ETIMESTAMP">ETIMESTAMP</a>)); } else { // Normal block. Time must advance assert(now < timestamp, <a href="../../../../../../move-stdlib/docs/Errors.md#0x1_Errors_invalid_argument">Errors::invalid_argument</a>(<a href="DiemTimestamp.md#0x1_DiemTimestamp_ETIMESTAMP">ETIMESTAMP</a>)); }; global_timer.microseconds = timestamp; } </code></pre> </details> <details> <summary>Specification</summary> <pre><code>pragma opaque; modifies global<<a href="DiemTimestamp.md#0x1_DiemTimestamp_CurrentTimeMicroseconds">CurrentTimeMicroseconds</a>>(<a href="CoreAddresses.md#0x1_CoreAddresses_DIEM_ROOT_ADDRESS">CoreAddresses::DIEM_ROOT_ADDRESS</a>()); <a name="0x1_DiemTimestamp_now$10"></a> let now = <a href="DiemTimestamp.md#0x1_DiemTimestamp_spec_now_microseconds">spec_now_microseconds</a>(); </code></pre>

Conditions unique for abstract and concrete version of this function.

<pre><code>include <a href="DiemTimestamp.md#0x1_DiemTimestamp_AbortsIfNotOperating">AbortsIfNotOperating</a>; include <a href="CoreAddresses.md#0x1_CoreAddresses_AbortsIfNotVM">CoreAddresses::AbortsIfNotVM</a>; ensures now == timestamp; </code></pre>

Conditions we only check for the implementation, but do not pass to the caller.

<pre><code>aborts_if [concrete] (if (proposer == <a href="CoreAddresses.md#0x1_CoreAddresses_VM_RESERVED_ADDRESS">CoreAddresses::VM_RESERVED_ADDRESS</a>()) { now != timestamp // Refers to the now in the pre state } else { now >= timestamp } ) with <a href="../../../../../../move-stdlib/docs/Errors.md#0x1_Errors_INVALID_ARGUMENT">Errors::INVALID_ARGUMENT</a>; </code></pre> </details>

Function `now_microseconds`

Gets the current time in microseconds.

<pre><code>public fun <a href="DiemTimestamp.md#0x1_DiemTimestamp_now_microseconds">now_microseconds</a>(): u64 </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="DiemTimestamp.md#0x1_DiemTimestamp_now_microseconds">now_microseconds</a>(): u64 acquires <a href="DiemTimestamp.md#0x1_DiemTimestamp_CurrentTimeMicroseconds">CurrentTimeMicroseconds</a> { <a href="DiemTimestamp.md#0x1_DiemTimestamp_assert_operating">assert_operating</a>(); borrow_global<<a href="DiemTimestamp.md#0x1_DiemTimestamp_CurrentTimeMicroseconds">CurrentTimeMicroseconds</a>>(<a href="CoreAddresses.md#0x1_CoreAddresses_DIEM_ROOT_ADDRESS">CoreAddresses::DIEM_ROOT_ADDRESS</a>()).microseconds } </code></pre> </details> <details> <summary>Specification</summary> <pre><code>pragma opaque; include <a href="DiemTimestamp.md#0x1_DiemTimestamp_AbortsIfNotOperating">AbortsIfNotOperating</a>; ensures result == <a href="DiemTimestamp.md#0x1_DiemTimestamp_spec_now_microseconds">spec_now_microseconds</a>(); </code></pre>

<pre><code>define <a href="DiemTimestamp.md#0x1_DiemTimestamp_spec_now_microseconds">spec_now_microseconds</a>(): u64 { global<<a href="DiemTimestamp.md#0x1_DiemTimestamp_CurrentTimeMicroseconds">CurrentTimeMicroseconds</a>>(<a href="CoreAddresses.md#0x1_CoreAddresses_DIEM_ROOT_ADDRESS">CoreAddresses::DIEM_ROOT_ADDRESS</a>()).microseconds } </code></pre> </details>

Function `now_seconds`

Gets the current time in seconds.

<pre><code>public fun <a href="DiemTimestamp.md#0x1_DiemTimestamp_now_seconds">now_seconds</a>(): u64 </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="DiemTimestamp.md#0x1_DiemTimestamp_now_seconds">now_seconds</a>(): u64 acquires <a href="DiemTimestamp.md#0x1_DiemTimestamp_CurrentTimeMicroseconds">CurrentTimeMicroseconds</a> { <a href="DiemTimestamp.md#0x1_DiemTimestamp_now_microseconds">now_microseconds</a>() / <a href="DiemTimestamp.md#0x1_DiemTimestamp_MICRO_CONVERSION_FACTOR">MICRO_CONVERSION_FACTOR</a> } </code></pre> </details> <details> <summary>Specification</summary> <pre><code>pragma opaque; include <a href="DiemTimestamp.md#0x1_DiemTimestamp_AbortsIfNotOperating">AbortsIfNotOperating</a>; ensures result == <a href="DiemTimestamp.md#0x1_DiemTimestamp_spec_now_microseconds">spec_now_microseconds</a>() / <a href="DiemTimestamp.md#0x1_DiemTimestamp_MICRO_CONVERSION_FACTOR">MICRO_CONVERSION_FACTOR</a>; </code></pre>

<pre><code>define <a href="DiemTimestamp.md#0x1_DiemTimestamp_spec_now_seconds">spec_now_seconds</a>(): u64 { global<<a href="DiemTimestamp.md#0x1_DiemTimestamp_CurrentTimeMicroseconds">CurrentTimeMicroseconds</a>>(<a href="CoreAddresses.md#0x1_CoreAddresses_DIEM_ROOT_ADDRESS">CoreAddresses::DIEM_ROOT_ADDRESS</a>()).microseconds / <a href="DiemTimestamp.md#0x1_DiemTimestamp_MICRO_CONVERSION_FACTOR">MICRO_CONVERSION_FACTOR</a> } </code></pre> </details>

Function `is_genesis`

Helper function to determine if Diem is in genesis state.

<pre><code>public fun <a href="DiemTimestamp.md#0x1_DiemTimestamp_is_genesis">is_genesis</a>(): bool </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="DiemTimestamp.md#0x1_DiemTimestamp_is_genesis">is_genesis</a>(): bool { !exists<<a href="DiemTimestamp.md#0x1_DiemTimestamp_CurrentTimeMicroseconds">CurrentTimeMicroseconds</a>>(<a href="CoreAddresses.md#0x1_CoreAddresses_DIEM_ROOT_ADDRESS">CoreAddresses::DIEM_ROOT_ADDRESS</a>()) } </code></pre> </details>

Function `assert_genesis`

Helper function to assert genesis state.

<pre><code>public fun <a href="DiemTimestamp.md#0x1_DiemTimestamp_assert_genesis">assert_genesis</a>() </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="DiemTimestamp.md#0x1_DiemTimestamp_assert_genesis">assert_genesis</a>() { assert(<a href="DiemTimestamp.md#0x1_DiemTimestamp_is_genesis">is_genesis</a>(), <a href="../../../../../../move-stdlib/docs/Errors.md#0x1_Errors_invalid_state">Errors::invalid_state</a>(<a href="DiemTimestamp.md#0x1_DiemTimestamp_ENOT_GENESIS">ENOT_GENESIS</a>)); } </code></pre> </details> <details> <summary>Specification</summary> <pre><code>pragma opaque = true; include <a href="DiemTimestamp.md#0x1_DiemTimestamp_AbortsIfNotGenesis">AbortsIfNotGenesis</a>; </code></pre>

Helper schema to specify that a function aborts if not in genesis.

<pre><code>schema <a href="DiemTimestamp.md#0x1_DiemTimestamp_AbortsIfNotGenesis">AbortsIfNotGenesis</a> { aborts_if !<a href="DiemTimestamp.md#0x1_DiemTimestamp_is_genesis">is_genesis</a>() with <a href="../../../../../../move-stdlib/docs/Errors.md#0x1_Errors_INVALID_STATE">Errors::INVALID_STATE</a>; } </code></pre> </details>

Function `is_operating`

Helper function to determine if Diem is operating. This is the same as <code>!<a href="DiemTimestamp.md#0x1_DiemTimestamp_is_genesis">is_genesis</a>()</code> and is provided for convenience. Testing <code><a href="DiemTimestamp.md#0x1_DiemTimestamp_is_operating">is_operating</a>()</code> is more frequent than <code><a href="DiemTimestamp.md#0x1_DiemTimestamp_is_genesis">is_genesis</a>()</code>.

<pre><code>public fun <a href="DiemTimestamp.md#0x1_DiemTimestamp_is_operating">is_operating</a>(): bool </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="DiemTimestamp.md#0x1_DiemTimestamp_is_operating">is_operating</a>(): bool { exists<<a href="DiemTimestamp.md#0x1_DiemTimestamp_CurrentTimeMicroseconds">CurrentTimeMicroseconds</a>>(<a href="CoreAddresses.md#0x1_CoreAddresses_DIEM_ROOT_ADDRESS">CoreAddresses::DIEM_ROOT_ADDRESS</a>()) } </code></pre> </details>

Function `assert_operating`

Helper function to assert operating (!genesis) state.

<pre><code>public fun <a href="DiemTimestamp.md#0x1_DiemTimestamp_assert_operating">assert_operating</a>() </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="DiemTimestamp.md#0x1_DiemTimestamp_assert_operating">assert_operating</a>() { assert(<a href="DiemTimestamp.md#0x1_DiemTimestamp_is_operating">is_operating</a>(), <a href="../../../../../../move-stdlib/docs/Errors.md#0x1_Errors_invalid_state">Errors::invalid_state</a>(<a href="DiemTimestamp.md#0x1_DiemTimestamp_ENOT_OPERATING">ENOT_OPERATING</a>)); } </code></pre> </details> <details> <summary>Specification</summary> <pre><code>pragma opaque = true; include <a href="DiemTimestamp.md#0x1_DiemTimestamp_AbortsIfNotOperating">AbortsIfNotOperating</a>; </code></pre>

Helper schema to specify that a function aborts if not operating.

<pre><code>schema <a href="DiemTimestamp.md#0x1_DiemTimestamp_AbortsIfNotOperating">AbortsIfNotOperating</a> { aborts_if !<a href="DiemTimestamp.md#0x1_DiemTimestamp_is_operating">is_operating</a>() with <a href="../../../../../../move-stdlib/docs/Errors.md#0x1_Errors_INVALID_STATE">Errors::INVALID_STATE</a>; } </code></pre> </details>

Module Specification

After genesis, <code><a href="DiemTimestamp.md#0x1_DiemTimestamp_CurrentTimeMicroseconds">CurrentTimeMicroseconds</a></code> is published forever

<pre><code>invariant [global] <a href="DiemTimestamp.md#0x1_DiemTimestamp_is_operating">is_operating</a>() ==> exists<<a href="DiemTimestamp.md#0x1_DiemTimestamp_CurrentTimeMicroseconds">CurrentTimeMicroseconds</a>>(<a href="CoreAddresses.md#0x1_CoreAddresses_DIEM_ROOT_ADDRESS">CoreAddresses::DIEM_ROOT_ADDRESS</a>()); </code></pre>

After genesis, time progresses monotonically.

<pre><code>invariant update [global] old(<a href="DiemTimestamp.md#0x1_DiemTimestamp_is_operating">is_operating</a>()) ==> old(<a href="DiemTimestamp.md#0x1_DiemTimestamp_spec_now_microseconds">spec_now_microseconds</a>()) <= <a href="DiemTimestamp.md#0x1_DiemTimestamp_spec_now_microseconds">spec_now_microseconds</a>(); </code></pre>

All functions which do not have an <code>aborts_if</code> specification in this module are implicitly declared to never abort.

<pre><code>pragma aborts_if_is_strict; </code></pre>

Module `0x1::DiemTimestamp`

Module 0x1::DiemTimestamp

Resource CurrentTimeMicroseconds

Constants

Function set_time_has_started

Function update_global_time

Function now_microseconds

Function now_seconds

Function is_genesis

Function assert_genesis

Function is_operating

Function assert_operating

Module Specification

Module `0x1::DiemTimestamp`

Resource `CurrentTimeMicroseconds`

Function `set_time_has_started`

Function `update_global_time`

Function `now_microseconds`

Function `now_seconds`

Function `is_genesis`

Function `assert_genesis`

Function `is_operating`

Function `assert_operating`