Validity Ranges

Validity ranges define the time window during which a transaction can be included in a block. This is essential for time-locked smart contracts, deadline-based escrows, and any logic that depends on the current time.

Setting Validity

Use .setValidity() with Unix timestamps in milliseconds:

import { Address, Assets, preprod, Client } from "@evolution-sdk/evolution"

const client = Client.make(preprod)
  .withBlockfrost({
    baseUrl: "https://cardano-preprod.blockfrost.io/api/v0",
    projectId: process.env.BLOCKFROST_API_KEY!
  })
  .withSeed({ mnemonic: process.env.WALLET_MNEMONIC!, accountIndex: 0 })

const now = BigInt(Date.now())

const tx = await client
  .newTx()
  .payToAddress({
    address: Address.fromBech32("addr_test1vrm9x2dgvdau8vckj4duc89m638t8djmluqw5pdrFollw8qd9k63"),
    assets: Assets.fromLovelace(2_000_000n)
  })
  .setValidity({
    from: now, // Valid after this time
    to: now + 300_000n // Expires after 5 minutes
  })
  .build()

Parameters

Both are optional — you can set just one bound:

// Only set expiry (most common for simple transactions)
.setValidity({ to: now + 600_000n })

// Only set start time (for time-locked scripts)
.setValidity({ from: now })

// Both bounds (for scripts that check time ranges)
.setValidity({ from: now, to: now + 300_000n })

Why Validity Matters

For regular transactions: Setting a TTL prevents old transactions from being submitted after conditions have changed.

For smart contracts: Plutus validators can inspect the validity range to enforce time-based conditions like deadlines or vesting schedules. The validator sees the range, not the exact current time — it knows the transaction was submitted within the specified window.

Next Steps

• Smart Contracts — Time-locked script spending
• POSIX Time — Unix timestamp utilities
• Slots — Slot-based time