Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lucid.foundation/llms.txt

Use this file to discover all available pages before exploring further.

The thought_epoch program is the on-chain anchor for Lucid’s receipt verification system. It stores Merkle Mountain Range (MMR) roots on Solana, making AI interaction history permanently verifiable. Program ID (devnet): 8QXiFjguJT4PLVzH6BYNMHXZ3eLRaoF8cwx23EBc44Q6

​
Instructions

InstructionDescription
init_epochCreate a new epoch record PDA (first time only)
commit_epochUpdate an existing epoch record with a new MMR root
init_epochsCreate a new batch record for up to 16 roots
commit_epochsUpdate an existing batch record with new roots
init_epoch_v2Create a v2 record with extended metadata
commit_epoch_v2Update a v2 record with new root and metadata

​
Account Structures

​
EpochRecord

Stores a single MMR root.
FieldTypeDescription
merkle_root[u8; 32]SHA-256 MMR root hash
authorityPubkeySigner authorized to update
PDA seeds: ["epoch", authority]

​
EpochRecordBatch

Stores up to 16 MMR roots in a single account.
FieldTypeDescription
rootsVec<[u8; 32]>Up to 16 MMR root hashes
authorityPubkeySigner authorized to update
PDA seeds: ["epochs", authority]

​
EpochRecordV2

Extended epoch record with metadata for richer on-chain queries.
FieldTypeDescription
merkle_root[u8; 32]SHA-256 MMR root hash
authorityPubkeySigner authorized to update
epoch_idu64Sequential epoch identifier
leaf_countu64Number of receipts in this epoch
timestampi64Unix timestamp of epoch finalization
mmr_sizeu64Total MMR size at finalization
PDA seeds: ["epoch_v2", authority]

​
Usage

The offchain engine finalizes an epoch when either threshold is met (100+ receipts or 1+ hour). It then calls commit_epoch_v2 to anchor the root: 
import { Program } from '@coral-xyz/anchor';

await program.methods
  .commitEpochV2(
    root,       // [u8; 32] MMR root
    epochId,    // u64
    leafCount,  // u64
    timestamp,  // i64
    mmrSize     // u64
  )
  .accounts({
    authority: wallet.publicKey,
    epochRecordV2: epochPda,
  })
  .rpc();

​
Gas Costs

  • Single commit: 5 LUCID (mGas)
  • Batch commit (up to 16 roots): 7 LUCID total (2 base + 5 mGas)

​
Errors

ErrorDescription
BatchTooLargeBatch size exceeds MAX_BATCH (16)