ExpirationTime
constExpirationTime:object
Defined in: src/utils/expirationTime.ts:53
Builds the expiration 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
A number of days. The everyday form — fromDays(30) is what most creates want.
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”Throws
Section titled “Throws”If the duration is not a positive multiple of the block time.
fromHours()
Section titled “fromHours()”fromHours: (
hours) =>Lifetime
A number of hours.
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”Throws
Section titled “Throws”If the duration is not a positive multiple of the block time.
fromMinutes()
Section titled “fromMinutes()”fromMinutes: (
minutes) =>Lifetime
A number of minutes.
Parameters
Section titled “Parameters”minutes
Section titled “minutes”number
Returns
Section titled “Returns”Throws
Section titled “Throws”If the duration is not a positive multiple of the block time.
fromMonths()
Section titled “fromMonths()”fromMonths: (
months) =>Lifetime
A number of months, each of exactly 30 days — calendar months are not all the same length, and a lifetime is a duration rather than a date. Use ExpirationTime.atDate when the expiry has to land on a particular calendar day.
Parameters
Section titled “Parameters”months
Section titled “months”number
Returns
Section titled “Returns”Throws
Section titled “Throws”If the duration is not a positive multiple of the block time.
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
A number of weeks, each of 7 days.
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”Throws
Section titled “Throws”If the duration is not a positive multiple of the block time.
fromYears()
Section titled “fromYears()”fromYears: (
years) =>Lifetime
A number of years, each of exactly 365 days — leap days are not counted, so fromYears(4)
is a day short of four calendar years. Use ExpirationTime.atDate for a calendar
deadline.
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”Throws
Section titled “Throws”If the duration is not a positive multiple of the block time.
max: () =>
Lifetime
The longest lifetime the chain allows: MAX_LIFETIME blocks (about 182 days), counted from the block the transaction lands in. Extending an entity with it pushes its expiry out to that maximum again.
Returns
Section titled “Returns”Examples
Section titled “Examples”The 90% case: a duration, and nothing else to think about.await client.createEntity(Posts, values, { expiration: ExpirationTime.fromDays(30) })An exact block, or a wall-clock date.expiration: ExpirationTime.atBlock(1_200_000n)expiration: ExpirationTime.atDate(new Date("2027-01-01"))A deadline that still guarantees a minimum life.expiration: ExpirationTime.atBlock(1_200_000n, { atLeast: ExpirationTime.fromDays(1) })The longest life the chain allows.expiration: ExpirationTime.max()
No entity may live more than {@link MAX_LIFETIME} blocks (about 182 days) past the block itscreate or extension lands in. A longer expiry, such as `fromYears(1)`, is refused before thetransaction is sent.