Skip to main content

Module 0x2::timelock

A timelock implementation.

use 0x1::ascii;
use 0x1::option;
use 0x1::string;
use 0x1::type_name;
use 0x2::balance;
use 0x2::labeler;
use 0x2::object;
use 0x2::system_admin_cap;
use 0x2::transfer;
use 0x2::tx_context;

Resource TimeLock​

TimeLock struct that holds a locked object.

struct TimeLock<T: store> has key
Fields
id: object::UID
locked: T

The locked object.

expiration_timestamp_ms: u64

This is the epoch time stamp of when the lock expires.

label: option::Option<string::String>

Timelock related label.

Constants​

For when trying to join two time-locked balances with different expiration time.

const EDifferentExpirationTime: u64 = 2;

For when trying to join two time-locked balances with different labels.

const EDifferentLabels: u64 = 3;

Expiration timestamp of the lock is in the past.

const EExpireEpochIsPast: u64 = 0;

The lock has not expired yet.

const ENotExpiredYet: u64 = 1;

Function lock​

Function to lock an object till a unix timestamp in milliseconds.

public fun lock<T: store>(locked: T, expiration_timestamp_ms: u64, ctx: &mut tx_context::TxContext): timelock::TimeLock<T>
Implementation
public fun lock<T: store>(locked: T, expiration_timestamp_ms: u64, ctx: &mut TxContext): TimeLock<T> {
// Check that expiration_timestamp_ms is valid.
check_expiration_timestamp_ms(expiration_timestamp_ms, ctx);
// Create a timelock.
pack(locked, expiration_timestamp_ms, option::none(), ctx)
}

Function lock_with_label​

Function to lock a labeled object till a unix timestamp in milliseconds.

public fun lock_with_label<T: store, L>(_: &labeler::LabelerCap<L>, locked: T, expiration_timestamp_ms: u64, ctx: &mut tx_context::TxContext): timelock::TimeLock<T>
Implementation
public fun lock_with_label<T: store, L>(
_: &LabelerCap<L>,
locked: T,
expiration_timestamp_ms: u64,
ctx: &mut TxContext
): TimeLock<T> {
// Check that expiration_timestamp_ms is valid.
check_expiration_timestamp_ms(expiration_timestamp_ms, ctx);
// Calculate a label value.
let label = type_name<L>();
// Create a labeled timelock.
pack(locked, expiration_timestamp_ms, option::some(label), ctx)
}

Function lock_and_transfer​

Function to lock an object obj until expiration_timestamp_ms and transfer it to address to. Since Timelock<T> does not support public transfer, use this function to lock an object to an address.

public fun lock_and_transfer<T: store>(obj: T, to: address, expiration_timestamp_ms: u64, ctx: &mut tx_context::TxContext)
Implementation
public fun lock_and_transfer<T: store>(
obj: T,
to: address,
expiration_timestamp_ms: u64,
ctx: &mut TxContext
) {
transfer(lock(obj, expiration_timestamp_ms, ctx), to);
}

Function lock_with_label_and_transfer​

Function to lock a labeled object obj until expiration_timestamp_ms and transfer it to address to. Since Timelock<T> does not support public transfer, use this function to lock a labeled object to an address.

public fun lock_with_label_and_transfer<T: store, L>(labeler: &labeler::LabelerCap<L>, obj: T, to: address, expiration_timestamp_ms: u64, ctx: &mut tx_context::TxContext)
Implementation
public fun lock_with_label_and_transfer<T: store, L>(
labeler: &LabelerCap<L>,
obj: T,
to: address,
expiration_timestamp_ms: u64,
ctx: &mut TxContext
) {
transfer(lock_with_label(labeler, obj, expiration_timestamp_ms, ctx), to);
}

Function unlock​

Function to unlock the object from a TimeLock.

public fun unlock<T: store>(self: timelock::TimeLock<T>, ctx: &tx_context::TxContext): T
Implementation
public fun unlock<T: store>(self: TimeLock<T>, ctx: &TxContext): T {
// Unpack the timelock.
let (locked, expiration_timestamp_ms, _) = unpack(self);
// Check if the lock has expired.
assert!(expiration_timestamp_ms <= ctx.epoch_timestamp_ms(), ENotExpiredYet);
locked
}

Function join​

Join two TimeLock<Balance<T>> together.

public fun join<T>(self: &mut timelock::TimeLock<balance::Balance<T>>, other: timelock::TimeLock<balance::Balance<T>>)
Implementation
public fun join<T>(self: &mut TimeLock<Balance<T>>, other: TimeLock<Balance<T>>) {
// Check the preconditions.
assert!(self.expiration_timestamp_ms() == other.expiration_timestamp_ms(), EDifferentExpirationTime);
assert!(self.label() == other.label(), EDifferentLabels);
// Unpack the time-locked balance.
let (value, _, _) = unpack(other);
// Join the balances.
self.locked.join(value);
}

Function join_vec​

Join everything in others with self.

public fun join_vec<T>(self: &mut timelock::TimeLock<balance::Balance<T>>, others: vector<timelock::TimeLock<balance::Balance<T>>>)
Implementation
public fun join_vec<T>(self: &mut TimeLock<Balance<T>>, mut others: vector<TimeLock<Balance<T>>>) {
// Create useful variables.
let (mut i, len) = (0, others.length());
// Join all the balances.
while (i < len) {
let other = others.pop_back();
Self::join(self, other);
i = i + 1
};
// Destroy the empty vector.
vector::destroy_empty(others)
}

Function split​

Split a TimeLock<Balance<T>> and take a sub balance from it.

public fun split<T>(self: &mut timelock::TimeLock<balance::Balance<T>>, value: u64, ctx: &mut tx_context::TxContext): timelock::TimeLock<balance::Balance<T>>
Implementation
public fun split<T>(self: &mut TimeLock<Balance<T>>, value: u64, ctx: &mut TxContext): TimeLock<Balance<T>> {
// Split the locked balance.
let value = self.locked.split(value);
// Pack the split balance into a timelock.
pack(value, self.expiration_timestamp_ms(), self.label(), ctx)
}

Function split_balance​

Split the given TimeLock<Balance<T>> into two parts, one with principal value, and transfer the newly split part to the sender address.

public entry fun split_balance<T>(self: &mut timelock::TimeLock<balance::Balance<T>>, value: u64, ctx: &mut tx_context::TxContext)
Implementation
public entry fun split_balance<T>(self: &mut TimeLock<Balance<T>>, value: u64, ctx: &mut TxContext) {
split(self, value, ctx).transfer_to_sender(ctx)
}

Function transfer_to_sender​

A utility function to transfer a TimeLock to the sender.

public fun transfer_to_sender<T: store>(lock: timelock::TimeLock<T>, ctx: &tx_context::TxContext)
Implementation
public fun transfer_to_sender<T: store>(lock: TimeLock<T>, ctx: &TxContext) {
transfer(lock, ctx.sender())
}

Function system_pack​

A utility function to pack a TimeLock that can be invoked only by a system package.

public fun system_pack<T: store>(_: &system_admin_cap::IotaSystemAdminCap, locked: T, expiration_timestamp_ms: u64, label: option::Option<string::String>, ctx: &mut tx_context::TxContext): timelock::TimeLock<T>
Implementation
public fun system_pack<T: store>(
_: &IotaSystemAdminCap,
locked: T,
expiration_timestamp_ms: u64,
label: Option<String>,
ctx: &mut TxContext): TimeLock<T>
{
pack(locked, expiration_timestamp_ms, label, ctx)
}

Function system_unpack​

An utility function to unpack a TimeLock that can be invoked only by a system package.

public fun system_unpack<T: store>(_: &system_admin_cap::IotaSystemAdminCap, lock: timelock::TimeLock<T>): (T, u64, option::Option<string::String>)
Implementation
public fun system_unpack<T: store>(_: &IotaSystemAdminCap, lock: TimeLock<T>): (T, u64, Option<String>) {
unpack(lock)
}

Function type_name​

Return a fully qualified type name with the original package IDs that is used as type related a label value.

public fun type_name<L>(): string::String
Implementation
public fun type_name<L>(): String {
string::from_ascii(std::type_name::get_with_original_ids<L>().into_string())
}

Function expiration_timestamp_ms​

Function to get the expiration timestamp of a TimeLock.

public fun expiration_timestamp_ms<T: store>(self: &timelock::TimeLock<T>): u64
Implementation
public fun expiration_timestamp_ms<T: store>(self: &TimeLock<T>): u64 {
self.expiration_timestamp_ms
}

Function is_locked​

Function to check if a TimeLock is locked.

public fun is_locked<T: store>(self: &timelock::TimeLock<T>, ctx: &tx_context::TxContext): bool
Implementation
public fun is_locked<T: store>(self: &TimeLock<T>, ctx: &TxContext): bool {
self.remaining_time(ctx) > 0
}

Function remaining_time​

Function to get the remaining time of a TimeLock. Returns 0 if the lock has expired.

public fun remaining_time<T: store>(self: &timelock::TimeLock<T>, ctx: &tx_context::TxContext): u64
Implementation
public fun remaining_time<T: store>(self: &TimeLock<T>, ctx: &TxContext): u64 {
// Get the epoch timestamp.
let current_timestamp_ms = ctx.epoch_timestamp_ms();
// Check if the lock has expired.
if (self.expiration_timestamp_ms < current_timestamp_ms) {
return 0
};
// Calculate the remaining time.
self.expiration_timestamp_ms - current_timestamp_ms
}

Function locked​

Function to get the locked object of a TimeLock.

public fun locked<T: store>(self: &timelock::TimeLock<T>): &T
Implementation
public fun locked<T: store>(self: &TimeLock<T>): &T {
&self.locked
}

Function label​

Function to get the label of a TimeLock.

public fun label<T: store>(self: &timelock::TimeLock<T>): option::Option<string::String>
Implementation
public fun label<T: store>(self: &TimeLock<T>): Option<String> {
self.label
}

Function is_labeled_with​

Check if a TimeLock is labeled with the type L.

public fun is_labeled_with<T: store, L>(self: &timelock::TimeLock<T>): bool
Implementation
public fun is_labeled_with<T: store, L>(self: &TimeLock<T>): bool {
if (self.label.is_some()) {
self.label.borrow() == type_name<L>()
}
else {
false
}
}

Function pack​

A utility function to pack a TimeLock.

fun pack<T: store>(locked: T, expiration_timestamp_ms: u64, label: option::Option<string::String>, ctx: &mut tx_context::TxContext): timelock::TimeLock<T>
Implementation
fun pack<T: store>(
locked: T,
expiration_timestamp_ms: u64,
label: Option<String>,
ctx: &mut TxContext): TimeLock<T>
{
// Create a timelock.
TimeLock {
id: object::new(ctx),
locked,
expiration_timestamp_ms,
label,
}
}

Function unpack​

An utility function to unpack a TimeLock.

fun unpack<T: store>(lock: timelock::TimeLock<T>): (T, u64, option::Option<string::String>)
Implementation
fun unpack<T: store>(lock: TimeLock<T>): (T, u64, Option<String>) {
// Unpack the timelock.
let TimeLock {
id,
locked,
expiration_timestamp_ms,
label,
} = lock;
// Delete the timelock.
object::delete(id);
(locked, expiration_timestamp_ms, label)
}

Function transfer​

A utility function to transfer a TimeLock to a receiver.

fun transfer<T: store>(lock: timelock::TimeLock<T>, receiver: address)
Implementation
fun transfer<T: store>(lock: TimeLock<T>, receiver: address) {
transfer::transfer(lock, receiver);
}

Function check_expiration_timestamp_ms​

An utility function to check that the expiration_timestamp_ms value is valid.

fun check_expiration_timestamp_ms(expiration_timestamp_ms: u64, ctx: &tx_context::TxContext)
Implementation
fun check_expiration_timestamp_ms(expiration_timestamp_ms: u64, ctx: &TxContext) {
// Get the epoch timestamp.
let epoch_timestamp_ms = ctx.epoch_timestamp_ms();
// Check that expiration_timestamp_ms is valid.
assert!(expiration_timestamp_ms > epoch_timestamp_ms, EExpireEpochIsPast);
}