State Datum

The state datum represents the user state of the UVerify fee system. To create a state datum, it needs a bootstrap datum as reference input. The state datum is forked from the bootstrap datum and is used to manage the user’s state. Here’s what a state datum looks like:

type StateDatum {
  id: ByteArray,
  owner: VerificationKeyHash,
  fee: Int,
  fee_interval: Int,
  fee_receivers: List<VerificationKeyHash>,
  ttl: Int,
  countdown: Int,
  certificates: List<UVerifyCertificate>,
  batch_size: Int,
  bootstrap_datum_name: AssetName,
  keep_as_oracle: bool,
}

ID 🔑

The unique identifier of the state datum. It is generated as a hash that includes the output reference of an input consumed during a successful transaction.

Owner 👤

The payment credential of the user who owns the state datum.

Fee 💰

This is the service charge applied on every fee interval.

Fee Interval ⏱️

The interval at which the fee is charged. The Cardano blockchain operates on a UTXO model, and to prevent dust UTXOs, a minimum fee of 1 ADA is required. To avoid users paying 1 ADA or more per certificate, we charge the fee at regular intervals. The fee interval specifies the number of certificates after which the fee is applied.

Fee Receivers 📥

The fee collected is distributed among the designated fee receivers, ensuring fair compensation for all parties involved.

TTL (Time to Live) ⏳

This defines the lifespan of the bootstrap datum, measured in UNIX time, providing a clear timeline for its validity.

Countdown ⏳

The countdown is the number of certificates left before the state token needs to be renewed. Furthermore, the countdown is used to determine when the fee is charged.

Certificate 📜

The UVerify certificate is part of the state datum update transaction.

type UVerifyCertificate {
  hash: ByteArray,
  algorithm: String,
  issuer: ByteArray,
  extra: List<String>,
}

Batch Size 📦

The number of certificates that can be issued in a single transaction. This helps reduce the fee cost per certificate.

Bootstrap Datum Name 🏷

The name of the bootstrap datum from which the state datum is derived. This can also be used as a condition to display a custom user interface for the certificate page.

Keep as Oracle

Normally, each certificate transaction consumes the existing state UTXO and produces a new one with updated data. The previous datum disappears from the chain as the UTXO is spent, which means it cannot be used as a reference input by other scripts.

When keep_as_oracle is set to true, the state UTXO is frozen: no further certificate updates can be made against it. The UTXO stays locked in the script permanently and its data remains available on-chain as a reference input, allowing other contracts to read it without consuming it.

The trade-off is that issuing new certificates through this state is no longer possible. To continue issuing certificates, the user must derive a new state from a bootstrap datum.