ExpirationTime
constExpirationTime:object
Defined in: src/utils/expirationTime.ts:46
Builds the expires of a create or an extension.
Every helper returns the { minLifetime, expiresAt } pair the ABI carries, so what you write is
what goes on the wire. The from* helpers fill minLifetime and leave expiresAt at 0n;
ExpirationTime.atBlock and ExpirationTime.atDate do the reverse. The engine takes
whichever comes later, which is why a deadline can also carry a floor.
Values are plain data — no methods, no prototype — so they log, clone and compare like any other object.
Type Declaration
Section titled “Type Declaration”atBlock()
Section titled “atBlock()”atBlock: (
block,options?) =>Expiry
An absolute block height.
Parameters
Section titled “Parameters”bigint
The block the entity expires at.
options?
Section titled “options?”Optionally, a floor: { atLeast: ExpirationTime.fromDays(1) }.
Returns
Section titled “Returns”Throws
Section titled “Throws”If the height is negative.
atDate()
Section titled “atDate()”atDate: (
date,options?) =>Expiry
A wall-clock instant, placed against the block the transaction is built on.
A date cannot land on a block boundary in general, so it rounds up to the next block: the entity lives until at least the instant asked for. This is why a date is never rejected for “not being a whole number of blocks” the way a duration is — it becomes a block height, not a duration.
Parameters
Section titled “Parameters”Date
When the entity should expire.
options?
Section titled “options?”Optionally, a floor: { atLeast: ExpirationTime.fromDays(1) }.
Returns
Section titled “Returns”Throws
Section titled “Throws”If the value is not a valid Date.
fromBlocks()
Section titled “fromBlocks()”fromBlocks: (
blocks) =>Lifetime
A number of blocks, for callers who think in the chain’s own unit. Always exact — there is no conversion to be approximate about.
Parameters
Section titled “Parameters”blocks
Section titled “blocks”number
Returns
Section titled “Returns”Throws
Section titled “Throws”If the count is not a positive whole number.
fromDays()
Section titled “fromDays()”fromDays: (
days) =>Lifetime
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”fromHours()
Section titled “fromHours()”fromHours: (
hours) =>Lifetime
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”fromMinutes()
Section titled “fromMinutes()”fromMinutes: (
minutes) =>Lifetime
Parameters
Section titled “Parameters”minutes
Section titled “minutes”number
Returns
Section titled “Returns”fromMonths()
Section titled “fromMonths()”fromMonths: (
months) =>Lifetime
Parameters
Section titled “Parameters”months
Section titled “months”number
Returns
Section titled “Returns”fromSeconds()
Section titled “fromSeconds()”fromSeconds: (
seconds) =>Lifetime
A raw number of seconds. Must be a whole number of blocks’ worth — see the other helpers, which all produce one by construction.
Parameters
Section titled “Parameters”seconds
Section titled “seconds”number
Returns
Section titled “Returns”Throws
Section titled “Throws”If the duration is not a positive multiple of the block time.
fromWeeks()
Section titled “fromWeeks()”fromWeeks: (
weeks) =>Lifetime
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”fromYears()
Section titled “fromYears()”fromYears: (
years) =>Lifetime
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”permanent()
Section titled “permanent()”permanent: () =>
Expiry
An entity that should never expire.
This is atBlock(MAX_EXPIRES_AT) — the largest expiry the uint64 field holds — and the
engine treats it as an ordinary deadline rather than a special case. There is no permanence
flag; a block height no chain will reach is what permanence is.
Returns
Section titled “Returns”Examples
Section titled “Examples”The 90% case: a duration, and nothing else to think about.await client.createEntity({ payload, contentType, expires: ExpirationTime.fromDays(30) })An exact block, or a wall-clock date.expires: ExpirationTime.atBlock(1_200_000n)expires: ExpirationTime.atDate(new Date("2027-01-01"))A deadline that still guarantees a minimum life.expires: ExpirationTime.atBlock(1_200_000n, { atLeast: ExpirationTime.fromDays(1) })