Module iota::timelock
A timelock implementation.
use iota::address;
use iota::balance;
use iota::clock;
use iota::hex;
use iota::labeler;
use iota::object;
use iota::system_admin_cap;
use iota::transfer;
use iota::tx_context;
use iota::types;
use std::address;
use std::ascii;
use std::bcs;
use std::option;
use std::string;
use std::type_name;
use std::vector;
Module Functions
pub 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 iota::tx_context::TxContext): iota::timelock::TimeLock<T>
Implementation
public fun lock<T: store>(
locked: T,
expiration_timestamp_ms: u64,
ctx: &mut TxContext,
): TimeLock<T> {
// Create a timelock.
pack(locked, expiration_timestamp_ms, option::none(), ctx)
}
pub 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 iota::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);
}
pub lock_with_label
Function to lock a labeled object till a unix timestamp in milliseconds.
public fun lock_with_label<T: store, L>(_: &iota::labeler::LabelerCap<L>, locked: T, expiration_timestamp_ms: u64, ctx: &mut iota::tx_context::TxContext): iota::timelock::TimeLock<T>
Implementation
public fun lock_with_label<T: store, L>(
_: &LabelerCap,
locked: T,
expiration_timestamp_ms: u64,
ctx: &mut TxContext,
): TimeLock<T> {
// Calculate a label value.
let label = type_name<L>();
// Create a labeled timelock.
pack(locked, expiration_timestamp_ms, option::some(label), ctx)
}
pub 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: &iota::labeler::LabelerCap<L>, obj: T, to: address, expiration_timestamp_ms: u64, ctx: &mut iota::tx_context::TxContext)
Implementation
public fun lock_with_label_and_transfer<T: store, L>(
labeler: &LabelerCap,
obj: T,
to: address,
expiration_timestamp_ms: u64,
ctx: &mut TxContext,
) {
transfer(lock_with_label(labeler, obj, expiration_timestamp_ms, ctx), to);
}
pub system_pack
A utility function to pack a TimeLock that can be invoked only by a system package.
public fun system_pack<T: store>(_: &iota::system_admin_cap::IotaSystemAdminCap, locked: T, expiration_timestamp_ms: u64, label: std::option::Option<std::string::String>, ctx: &mut iota::tx_context::TxContext): iota::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)
}
pub system_unpack
An utility function to unpack a TimeLock that can be invoked only by a system package.
public fun system_unpack<T: store>(_: &iota::system_admin_cap::IotaSystemAdminCap, lock: iota::timelock::TimeLock<T>): (T, u64, std::option::Option<std::string::String>)
Implementation
public fun system_unpack<T: store>(
_: &IotaSystemAdminCap,
lock: TimeLock<T>,
): (T, u64, Option<String>) {
unpack(lock)
}
pub 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>(): std::string::String
Implementation
public fun type_name<L>(): String {
string::from_ascii(std::type_name::get_with_original_ids<L>().into_string())
}
prv pack
A utility function to pack a TimeLock.
fun pack<T: store>(locked: T, expiration_timestamp_ms: u64, label: std::option::Option<std::string::String>, ctx: &mut iota::tx_context::TxContext): iota::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,
}
}
Structs
struct TimeLock
TimeLock struct that holds a locked object.
public struct TimeLock<T: store> has key
Fields
id: iota::object::UIDlocked: TThe locked object.
expiration_timestamp_ms: u64This is the epoch time stamp of when the lock expires.
label: std::option::Option<std::string::String>Timelock related label.
pub expiration_timestamp_ms
Function to get the expiration timestamp of a TimeLock.
public fun expiration_timestamp_ms<T: store>(self: &iota::timelock::TimeLock<T>): u64
Implementation
public fun expiration_timestamp_ms<T: store>(self: &TimeLock<T>): u64 {
self.expiration_timestamp_ms
}
pub is_labeled_with
Check if a TimeLock is labeled with the type L.
public fun is_labeled_with<T: store, L>(self: &iota::timelock::TimeLock<T>): bool
Implementation
pub is_locked
Function to check if a TimeLock is locked based on the epoch start time.
public fun is_locked<T: store>(self: &iota::timelock::TimeLock<T>, ctx: &iota::tx_context::TxContext): bool
Implementation
public fun is_locked<T: store>(self: &TimeLock<T>, ctx: &TxContext): bool {
self.remaining_time(ctx) > 0
}
pub is_locked_with_clock
Function to check if a TimeLock is locked based on the Clock object.
public fun is_locked_with_clock<T: store>(self: &iota::timelock::TimeLock<T>, clock: &iota::clock::Clock): bool
Implementation
public fun is_locked_with_clock<T: store>(self: &TimeLock<T>, clock: &Clock): bool {
self.remaining_time_with_clock(clock) > 0
}
pub join
Join two TimeLock<Balance<T>> together.
public fun join<T>(self: &mut iota::timelock::TimeLock<iota::balance::Balance<T>>, other: iota::timelock::TimeLock<iota::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);
}
pub join_vec
Join everything in others with self.
public fun join_vec<T>(self: &mut iota::timelock::TimeLock<iota::balance::Balance<T>>, others: vector<iota::timelock::TimeLock<iota::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)
}
pub label
Function to get the label of a TimeLock.
public fun label<T: store>(self: &iota::timelock::TimeLock<T>): std::option::Option<std::string::String>
pub locked
Function to get the locked object of a TimeLock.
public fun locked<T: store>(self: &iota::timelock::TimeLock<T>): &T
pub remaining_time
Function to get the remaining time of a TimeLock based on the epoch start time.
Returns 0 if the lock has expired.
public fun remaining_time<T: store>(self: &iota::timelock::TimeLock<T>, ctx: &iota::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();
self.remaining_time_with_timestamp(current_timestamp_ms)
}
pub remaining_time_with_clock
Function to get the remaining time of a TimeLock based on the Clock object.
Returns 0 if the lock has expired.
public fun remaining_time_with_clock<T: store>(self: &iota::timelock::TimeLock<T>, clock: &iota::clock::Clock): u64
Implementation
public fun remaining_time_with_clock<T: store>(self: &TimeLock<T>, clock: &Clock): u64 {
// Get the clock's timestamp.
let current_timestamp_ms = clock.timestamp_ms();
self.remaining_time_with_timestamp(current_timestamp_ms)
}
pub split
Split a TimeLock<Balance<T>> and take a sub balance from it.
public fun split<T>(self: &mut iota::timelock::TimeLock<iota::balance::Balance<T>>, value: u64, ctx: &mut iota::tx_context::TxContext): iota::timelock::TimeLock<iota::balance::Balance<T>>
Implementation
pub transfer_to_sender
A utility function to transfer a TimeLock to the sender.
public fun transfer_to_sender<T: store>(lock: iota::timelock::TimeLock<T>, ctx: &iota::tx_context::TxContext)
Implementation
public fun transfer_to_sender<T: store>(lock: TimeLock<T>, ctx: &TxContext) {
transfer(lock, ctx.sender())
}
pub unlock
Function to unlock the object from a TimeLock based on the epoch start time.
public fun unlock<T: store>(self: iota::timelock::TimeLock<T>, ctx: &iota::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
}
pub unlock_with_clock
Function to unlock the object from a TimeLock based on the Clock object.
public fun unlock_with_clock<T: store>(self: iota::timelock::TimeLock<T>, clock: &iota::clock::Clock): T
Implementation
public fun unlock_with_clock<T: store>(self: TimeLock<T>, clock: &Clock): T {
// Unpack the timelock.
let (locked, expiration_timestamp_ms, _) = unpack(self);
// Check if the lock has expired.
assert!(expiration_timestamp_ms <= clock.timestamp_ms(), ENotExpiredYet);
locked
}
pub entry 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 iota::timelock::TimeLock<iota::balance::Balance<T>>, value: u64, ctx: &mut iota::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)
}
prv remaining_time_with_timestamp
An utility function to get the remaining time of a TimeLock.
fun remaining_time_with_timestamp<T: store>(self: &iota::timelock::TimeLock<T>, current_timestamp_ms: u64): u64
Implementation
fun remaining_time_with_timestamp<T: store>(self: &TimeLock<T>, current_timestamp_ms: u64): u64 {
// 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
}
prv transfer
A utility function to transfer a TimeLock to a receiver.
fun transfer<T: store>(lock: iota::timelock::TimeLock<T>, receiver: address)
Implementation
fun transfer<T: store>(lock: TimeLock<T>, receiver: address) {
transfer::transfer(lock, receiver);
}
prv unpack
An utility function to unpack a TimeLock.
fun unpack<T: store>(lock: iota::timelock::TimeLock<T>): (T, u64, std::option::Option<std::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)
}
Constants
err ENotExpiredYet
The lock has not expired yet.
const ENotExpiredYet: u64 = 1;
err EDifferentExpirationTime
For when trying to join two time-locked balances with different expiration time.
const EDifferentExpirationTime: u64 = 2;
err EDifferentLabels
For when trying to join two time-locked balances with different labels.
const EDifferentLabels: u64 = 3;