@ocap/types 1.29.5 → 1.29.6

package/interfaces/index.ts

@@ -252,3 +252,29 @@ export type {
   // Main interface
   IResolver,
 } from './resolver';
+
+// Ledger types (VLedger - Verifiable Ledger Kernel)
+export type {
+  // Entry types
+  ILedgerEntry,
+  ILedgerEntryRow,
+  // Checkpoint types
+  ICheckpoint,
+  ICheckpointRow,
+  // Merkle types
+  IMerkleProof,
+  // Configuration types
+  ICheckpointConfig,
+  ILedgerCapabilities,
+  // Input types
+  ISignedTransactionInput,
+  // Storage interface
+  ILedgerStorage,
+  // Main interface
+  ILedger,
+  // Factory interface
+  ILedgerFactory,
+  // Table type mappings
+  LedgerTableTypeMap,
+  LedgerTableName,
+} from './ledger';

package/interfaces/indexdb.ts

@@ -441,4 +441,10 @@ export interface IIndexDB {
    * Should be called after all tables are initialized
    */
   attachReadyListeners(): void;
+
+  /**
+   * Close the database connection and release all resources.
+   * Must be called during graceful shutdown.
+   */
+  close(): Promise<void>;
 }

package/interfaces/ledger.ts

@@ -0,0 +1,376 @@
+// core/types/interfaces/ledger.ts
+// Ledger state and operation types for Ledger - Verifiable Ledger Kernel
+
+// ============================================================================
+// Ledger Entry Types
+// ============================================================================
+
+/**
+ * Ledger Entry - Immutable record of a signed transaction
+ */
+export interface ILedgerEntry {
+  /** Global incrementing sequence number */
+  sequence: number;
+
+  /** Transaction hash (0x + 64 hex chars) */
+  hash: string;
+
+  /** Signer DID */
+  from: string;
+
+  /** Anti-replay nonce */
+  nonce: number;
+
+  /** Public key */
+  pk: string;
+
+  /** Signature */
+  signature: string;
+
+  /** Base64 encoded raw transaction bytes */
+  txRaw: string;
+
+  /** Decoded JSON object (redundant storage for querying) */
+  tx: Record<string, unknown>;
+
+  /** Transaction type (e.g., 'fg:t:transfer') */
+  txType: string;
+
+  /** Entry timestamp (ms) */
+  timestamp: number;
+
+  /** Chain DID this entry belongs to */
+  chainId: string;
+
+  /** hash(sequence + txRaw) for Merkle Tree leaf */
+  entryHash: string;
+
+  /** Transaction verification context (passkey, gasStakeHeaders, etc.) */
+  txExtra?: Record<string, unknown>;
+
+  /** State commit hash (e.g. Dolt commit) that contains this tx's state changes */
+  stateCommitHash?: string;
+
+  /** Whether the entry has been finalized (stateCommitHash set and entryHash recomputed) */
+  finalized: boolean;
+}
+
+/**
+ * Storage row type for ledger entries (used by adapters)
+ * Uses camelCase to match TypeScript conventions and statedb-dolt patterns
+ */
+export interface ILedgerEntryRow {
+  sequence: number;
+  hash: string;
+  from: string;
+  nonce: number;
+  pk: string;
+  signature: string;
+  txRaw: string;
+  tx: string; // JSON string
+  txType: string;
+  timestamp: number;
+  chainId: string;
+  entryHash: string;
+  txExtra: string | null; // JSON string for verification context
+  stateCommitHash: string | null;
+  finalized: number; // 0 or 1 for SQL compatibility
+}
+
+// ============================================================================
+// Checkpoint Types
+// ============================================================================
+
+/**
+ * Checkpoint - Verifiable snapshot proof at a Ledger position
+ */
+export interface ICheckpoint {
+  /** Checkpoint incrementing number */
+  height: number;
+
+  /** Checkpoint's own hash */
+  hash: string;
+
+  /** Last entry sequence covered */
+  sequence: number;
+
+  /** Previous checkpoint's sequence */
+  prevSequence: number;
+
+  /** Merkle root of ledger entries */
+  txRoot: string;
+
+  /** Cumulative transaction count */
+  txCount: number;
+
+  /** State root (optional, e.g., Dolt commit hash) */
+  stateRoot?: string;
+
+  /** Creation timestamp (ms) */
+  timestamp: number;
+
+  /** Previous checkpoint hash */
+  prevCheckpoint: string | null;
+
+  /** Proposer DID */
+  proposer: string;
+
+  /** Proposer signature */
+  signature: string;
+}
+
+/**
+ * Storage row type for checkpoints (used by adapters)
+ * Uses camelCase to match TypeScript conventions and statedb-dolt patterns
+ */
+export interface ICheckpointRow {
+  height: number;
+  hash: string;
+  sequence: number;
+  prevSequence: number;
+  txRoot: string;
+  txCount: number;
+  stateRoot: string | null;
+  timestamp: number;
+  prevCheckpoint: string | null;
+  proposer: string;
+  signature: string;
+}
+
+// ============================================================================
+// Merkle Proof Types
+// ============================================================================
+
+/**
+ * Merkle Proof - Proves an entry belongs to a checkpoint
+ */
+export interface IMerkleProof {
+  /** Entry position (sequence - 1) */
+  index: number;
+
+  /** Entry hash (leaf) */
+  leaf: string;
+
+  /** Merkle path (sibling hashes) */
+  proof: string[];
+
+  /** Checkpoint's txRoot */
+  root: string;
+}
+
+// ============================================================================
+// Configuration Types
+// ============================================================================
+
+/**
+ * Checkpoint configuration
+ */
+export interface ICheckpointConfig {
+  /** Trigger batch size: create checkpoint every N transactions */
+  batchSize: number;
+
+  /** Time trigger: max time since last checkpoint (ms) */
+  timeoutMs: number;
+
+  /** Enable auto checkpoint */
+  auto: boolean;
+}
+
+/**
+ * Ledger capabilities for testing
+ */
+export interface ILedgerCapabilities {
+  /** Persistent storage */
+  persistence: boolean;
+
+  /** True transaction semantics */
+  transaction: boolean;
+
+  /** Supports stateRoot */
+  stateRoot: boolean;
+
+  /** Supports schema migration */
+  migration: boolean;
+}
+
+// ============================================================================
+// Input Types
+// ============================================================================
+
+/**
+ * Signed transaction input for ledger.append()
+ */
+export interface ISignedTransactionInput {
+  txRaw: string;
+  tx: Record<string, unknown>;
+  txHash: string;
+  txType: string;
+  from: string;
+  nonce: number;
+  pk: string;
+  signature: string;
+  chainId: string;
+  timestamp: number;
+  /** Transaction verification context (passkey, gasStakeHeaders, etc.) */
+  txExtra?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Storage Interface
+// ============================================================================
+
+/**
+ * Storage adapter interface - SQLite/Dolt implement this
+ */
+export interface ILedgerStorage {
+  // Entry operations
+  appendEntries(entries: ILedgerEntry[]): Promise<void>;
+
+  /**
+   * Atomically append an entry with database-generated sequence and entryHash.
+   * This method is concurrency-safe: sequence is generated within a transaction
+   * using MAX(sequence)+1, ensuring no conflicts under multi-instance writes.
+   *
+   * The entry is created with finalized=false. Call finalizeEntry() after
+   * statedb commit to set stateCommitHash, recompute entryHash, and mark finalized.
+   *
+   * @param entry - Entry data without sequence, entryHash, and finalized (set by storage)
+   * @returns Complete entry with sequence, entryHash, and finalized=false
+   */
+  appendEntryAtomic(entry: Omit<ILedgerEntry, 'sequence' | 'entryHash' | 'finalized'>): Promise<ILedgerEntry>;
+  getEntryByHash(hash: string): Promise<ILedgerEntry | null>;
+  getEntryBySequence(seq: number): Promise<ILedgerEntry | null>;
+  getEntriesByRange(from: number, to: number): Promise<ILedgerEntry[]>;
+  getLatestSequence(): Promise<number>;
+  /**
+   * Iterate entry hashes in a sequence range (inclusive).
+   *
+   * @param fromSeq - Start sequence (inclusive)
+   * @param toSeq - End sequence (inclusive)
+   * @param callback - Called for each entry in ascending sequence order
+   */
+  iterateEntryHashes(
+    fromSeq: number,
+    toSeq: number,
+    callback: (seq: number, entryHash: string) => Promise<void>
+  ): Promise<void>;
+
+  /**
+   * Finalize an entry: set stateCommitHash, recompute entryHash, mark as finalized.
+   *
+   * @param txHash - Transaction hash identifying the entry
+   * @param stateCommitHash - State commit hash from statedb
+   * @param sequence - Entry sequence (needed for entryHash recomputation)
+   * @param txRaw - Raw transaction bytes (needed for entryHash recomputation)
+   */
+  finalizeEntry(txHash: string, stateCommitHash: string, sequence: number, txRaw: string): Promise<void>;
+
+  /**
+   * Check if there are any unfinalized entries in the given sequence range (inclusive).
+   *
+   * @returns true if at least one entry in [fromSeq, toSeq] has finalized=false
+   */
+  hasUnfinalizedInRange(fromSeq: number, toSeq: number): Promise<boolean>;
+
+  // Checkpoint operations
+  saveCheckpoint(checkpoint: ICheckpoint): Promise<void>;
+  getCheckpointByHeight(height: number): Promise<ICheckpoint | null>;
+  getLatestCheckpoint(): Promise<ICheckpoint | null>;
+  getCheckpointForSequence(seq: number): Promise<ICheckpoint | null>;
+
+  // Schema migration
+  getMigrationVersion(): Promise<number>;
+  runMigrations(): Promise<void>;
+  rollbackMigration(targetVersion: number): Promise<void>;
+
+  // Lifecycle
+  init(): Promise<void>;
+  close(): Promise<void>;
+  reset(): Promise<void>;
+}
+
+// ============================================================================
+// Ledger Interface
+// ============================================================================
+
+/**
+ * Ledger interface - Main API
+ */
+export interface ILedger {
+  readonly chainId: string;
+
+  // Write (Append-only)
+  append(tx: ISignedTransactionInput): Promise<ILedgerEntry>;
+
+  /**
+   * Batch append for offline / single-process scenarios (e.g. data migration, import).
+   *
+   * NOT concurrency-safe: sequences are computed in memory from a single
+   * getLatestSequence() call, so concurrent writers would produce conflicts.
+   * Use `append()` for online multi-instance workloads.
+   */
+  appendBatch(txs: ISignedTransactionInput[]): Promise<ILedgerEntry[]>;
+
+  // Read
+  get(hash: string): Promise<ILedgerEntry | null>;
+  getBySequence(seq: number): Promise<ILedgerEntry | null>;
+  getRange(from: number, to: number): Promise<ILedgerEntry[]>;
+
+  // Metadata
+  getLatestSequence(): Promise<number>;
+
+  // State commit hash
+  /**
+   * Finalize a ledger entry: set stateCommitHash, recompute entryHash, mark finalized.
+   *
+   * @param txHash - Transaction hash identifying the entry
+   * @param stateCommitHash - State commit hash from statedb
+   * @param sequence - Entry sequence (needed for entryHash recomputation)
+   * @param txRaw - Raw transaction bytes (needed for entryHash recomputation)
+   */
+  finalizeEntry(txHash: string, stateCommitHash: string, sequence: number, txRaw: string): Promise<void>;
+
+  // Checkpoint
+  createCheckpoint(): Promise<ICheckpoint>;
+  /** Create a checkpoint if batchSize/timeoutMs threshold is reached. Returns checkpoint or null. */
+  createCheckpointIfNeeded(): Promise<ICheckpoint | null>;
+  /** Get checkpoint by height, or latest if height is undefined */
+  getCheckpoint(height?: number): Promise<ICheckpoint | null>;
+  getCheckpointForSequence(seq: number): Promise<ICheckpoint | null>;
+
+  // Merkle
+  getMerkleProof(sequence: number): Promise<IMerkleProof>;
+  verifyMerkleProof(proof: IMerkleProof): boolean;
+
+  // Lifecycle
+  initialize(): Promise<void>;
+  close(): Promise<void>;
+}
+
+// ============================================================================
+// Factory Interface
+// ============================================================================
+
+/**
+ * Ledger factory interface for testing
+ */
+export interface ILedgerFactory {
+  name: string;
+  capabilities: ILedgerCapabilities;
+  create(): Promise<ILedger>;
+  cleanup(ledger: ILedger): Promise<void>;
+}
+
+// ============================================================================
+// Table Type Mapping
+// ============================================================================
+
+/**
+ * Maps ledger table names to their row types
+ */
+export type LedgerTableTypeMap = {
+  entries: ILedgerEntryRow;
+  checkpoints: ICheckpointRow;
+};
+
+export type LedgerTableName = keyof LedgerTableTypeMap;

package/interfaces/pipeline.ts

@@ -18,6 +18,8 @@
 //   type DelegateContext = IReadyContext<TDelegateTx> & IWithSender & IWithReceiver & IWithDelegation;
 //
 
+import type { ILedger } from './ledger';
+
 import type { TTokenInput, TTransactionReceipt } from '../lib/type_pb';
 import type { BN } from './base';
 import type { IAny } from './base';
@@ -195,6 +197,12 @@ export interface IBaseContext<TItx = unknown> {
   /** @internal Type parameter placeholder */
   readonly __itxType?: TItx;
 
+  /** Verifiable ledger instance for append-only transaction log */
+  ledger: ILedger;
+
+  /** Ledger sequence number (set by WriteLedger pipe, used in Phase 6) */
+  ledgerSequence?: number;
+
   /** Index signature for IOperationContext compatibility and dynamic property access */
   [key: string]: unknown;
 }

package/interfaces/resolver.ts

@@ -500,4 +500,10 @@ export interface IResolver {
     args: Partial<TRequestVerifyAccountRisk>,
     ctx?: IResolverContext
   ): Promise<TVerifyAccountRiskResult | null> | null;
+
+  // ============ Lifecycle ============
+  /**
+   * Graceful shutdown: drain the transaction queue and stop accepting new requests.
+   */
+  shutdown(): Promise<void>;
 }

package/interfaces/statedb.ts

@@ -190,4 +190,10 @@ export interface IStateDB extends IReady {
 
   /** Get table by name - use this for dynamic table access */
   getTable?(name: StateDBTableName): IStateTable<unknown>;
+
+  /**
+   * Close the database connection and release all resources.
+   * Must be called during graceful shutdown.
+   */
+  close(): Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ocap/types",
-  "version": "1.29.5",
+  "version": "1.29.6",
   "description": "Typescript definitions generated from protobuf",
   "keywords": [
     "ocap",