Skip to main content

LeiosDB

LeiosDB stores Leios endorser blocks (EBs) and their transactions. Its SQLite backend keeps them in two files, called partitions:

  • Volatile partition stores fresh EB announcements, bodies and transaction that the node downloads or forges.
  • Immutable partition stores complete EBs (and their closure transactions) that a certificate on the immutable chain refers to.

The EBs and their closures are copied from the volatile to the immutable partition when they become older than k (the Praos security parameter). See also the ImmutableDB glossary entry.

Database schema​

  • ebs has one row for each EB announcement. Thus one EB hash can occur at several slots.
  • ebTxs is the EB body. It has one row for each transaction of the EB, in order. It stores each EB hash only once.
  • txs stores the bytes of each transaction once. Transactions stored in this table may belong to one, several or no EBs.

Volatile partition​

The queries join the tables on the EB hash (ebHashBytes) and on the transaction hash (txHashBytes).

  • Rows are inserted in ebTxs when transactions referenced by an EB body arrive.
  • ebsMissingTxs lists, for each EB body, the transactions not yet in txs. missingTxCount counts them, and both are kept in step in one transaction.
  • gcTxCandidates lists the transactions of EBs marked for GC. The GC sweep phase deletes each one from txs once no remaining EB refers to it.

Indexes:

IndexOnUsed for
idx_ebs_ebHashBytesebs(ebHashBytes)Looking up an EB by hash
idx_ebTxs_txHashBytesebTxs(txHashBytes)GC of orphaned transactions: finding the EBs that refer to a transaction
idx_ebsMissingTxs_ebHashBytesebsMissingTxs(ebHashBytes)Finding the missing transactions of an EB
idx_ebs_sweepableebs(ebSlot) WHERE status IN (0, 2)The GC mark scan
idx_ebs_markedForGcebs(ebHashBytes) WHERE status = 3The sweeper picking EBs to evict
idx_ebs_pinnedebs(ebSlot) WHERE status = 1The copier picking EBs to copy

Lifecycle of an EB row​

The status column records where an ebs row is in promotion and garbage collection:

Immutable partition​

The copier copies only complete EBs, and GC never removes EBs from this partition. Thus every ebs row has its full body in ebTxs, and every ebTxs row has its transaction in txs. For the same reason, the immutable partition does not have missingTxCount, status, ebsMissingTxs, gcTxCandidates, or any index other than idx_ebs_ebHashBytes.