@arkiv-network/sdk/dist/expirationTime-C9rz8--Q.d.ts

TypeScript client library for Arkiv's blockchains interactions

import { n as Lifetime, t as Expiry } from "./expiry-S2PUL8Hg.js";

//#region src/utils/expirationTime.d.ts

/**
 * The optional floor a deadline can carry.
 *
 * `atLeast` takes a duration — one of the `from*` helpers — and never another deadline, so
 * `atBlock(x, { atLeast: atBlock(y) })` does not compile. Two deadlines are not a thing the engine
 * can resolve.
 */
type DeadlineOptions = {
  /** Live at least this long from now, even if the deadline is sooner. */
  atLeast?: Lifetime | undefined;
};
/**
 * 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`;
 * {@link ExpirationTime.atBlock} and {@link 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.
 *
 * @example The 90% case: a duration, and nothing else to think about.
 * await client.createEntity(Posts, values, { expiration: ExpirationTime.fromDays(30) })
 *
 * @example An exact block, or a wall-clock date.
 * expiration: ExpirationTime.atBlock(1_200_000n)
 * expiration: ExpirationTime.atDate(new Date("2027-01-01"))
 *
 * @example A deadline that still guarantees a minimum life.
 * expiration: ExpirationTime.atBlock(1_200_000n, { atLeast: ExpirationTime.fromDays(1) })
 *
 * @example 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 its
 * create or extension lands in. A longer expiry, such as `fromYears(1)`, is refused before the
 * transaction is sent.
 */
declare const ExpirationTime: {
  /**
   * A raw number of seconds. Must be a whole number of blocks' worth — see the other helpers, which
   * all produce one by construction.
   *
   * @throws {InvalidExpiryError} If the duration is not a positive multiple of the block time.
   */
  fromSeconds: (seconds: number) => Lifetime;
  /**
   * A number of minutes.
   *
   * @throws {InvalidExpiryError} If the duration is not a positive multiple of the block time.
   */
  fromMinutes: (minutes: number) => Lifetime;
  /**
   * A number of hours.
   *
   * @throws {InvalidExpiryError} If the duration is not a positive multiple of the block time.
   */
  fromHours: (hours: number) => Lifetime;
  /**
   * A number of days. The everyday form — `fromDays(30)` is what most creates want.
   *
   * @throws {InvalidExpiryError} If the duration is not a positive multiple of the block time.
   */
  fromDays: (days: number) => Lifetime;
  /**
   * A number of weeks, each of 7 days.
   *
   * @throws {InvalidExpiryError} If the duration is not a positive multiple of the block time.
   */
  fromWeeks: (weeks: number) => 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 {@link ExpirationTime.atDate} when the
   * expiry has to land on a particular calendar day.
   *
   * @throws {InvalidExpiryError} If the duration is not a positive multiple of the block time.
   */
  fromMonths: (months: number) => 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 {@link ExpirationTime.atDate} for a calendar
   * deadline.
   *
   * @throws {InvalidExpiryError} If the duration is not a positive multiple of the block time.
   */
  fromYears: (years: number) => 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.
   *
   * @throws {InvalidExpiryError} If the count is not a positive whole number.
   */
  fromBlocks: (blocks: number) => Lifetime;
  /**
   * The longest lifetime the chain allows: {@link 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.
   */
  max: () => Lifetime;
  /**
   * An absolute block height.
   *
   * @param block - The block the entity expires at.
   * @param options - Optionally, a floor: `{ atLeast: ExpirationTime.fromDays(1) }`.
   * @throws {InvalidExpiryError} If the height is negative.
   */
  atBlock: (block: bigint, options?: DeadlineOptions) => 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.
   *
   * @param date - When the entity should expire.
   * @param options - Optionally, a floor: `{ atLeast: ExpirationTime.fromDays(1) }`.
   * @throws {InvalidExpiryError} If the value is not a valid `Date`.
   */
  atDate: (date: Date, options?: DeadlineOptions) => Expiry;
};
//#endregion
export { ExpirationTime as n, DeadlineOptions as t };
//# sourceMappingURL=expirationTime-C9rz8--Q.d.ts.map