@ocap/types 1.31.9 → 1.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -253,6 +253,12 @@ export type {
253
253
  IBlocksResult,
254
254
  // Main interface
255
255
  IResolver,
256
+ // Follower / Node Runtime types (#1710)
257
+ TNodeRole,
258
+ TNodeWritePolicy,
259
+ TFollowerSyncMode,
260
+ IFollowerStatusResponse,
261
+ INodeRuntimeAdapter,
256
262
  } from './resolver';
257
263
 
258
264
  // Ledger types (VLedger - Verifiable Ledger Kernel)
@@ -1,6 +1,8 @@
1
1
  // core/types/interfaces/ledger.ts
2
2
  // Ledger state and operation types for Ledger - Verifiable Ledger Kernel
3
3
 
4
+ import type { TNodeRole } from './resolver';
5
+
4
6
  // ============================================================================
5
7
  // Ledger Entry Types
6
8
  // ============================================================================
@@ -85,6 +87,55 @@ export interface ILedgerEntryRow {
85
87
  // Checkpoint Types
86
88
  // ============================================================================
87
89
 
90
+ /**
91
+ * Quorum signature entry in a HotStuff-Lite QuorumCertificate (#1712).
92
+ */
93
+ export interface IQuorumSignatureEntry {
94
+ voterDid: string;
95
+ signature: string;
96
+ timestamp: number;
97
+ }
98
+
99
+ /**
100
+ * HotStuff-Lite 2f+1 QuorumCertificate attached to a finalized Checkpoint (#1712).
101
+ */
102
+ export interface IQuorumCertificate {
103
+ version: 1;
104
+ chainId: string;
105
+ viewNumber: number;
106
+ height: number;
107
+ checkpointHash: string;
108
+ prevCheckpointHash: string | null;
109
+ prevSequence: number;
110
+ sequence: number;
111
+ txRoot: string;
112
+ stateRoot?: string;
113
+ leaderDid: string;
114
+ quorumThreshold: number;
115
+ clusterSize: number;
116
+ signatures: IQuorumSignatureEntry[];
117
+ qcHash: string;
118
+ createdAt: number;
119
+ }
120
+
121
+ /**
122
+ * Validator member descriptor for a HotStuff-Lite BFT cluster (#1712).
123
+ */
124
+ export interface IHotStuffValidatorMember {
125
+ did: string;
126
+ publicKey: string;
127
+ endpoint?: string;
128
+ }
129
+
130
+ /**
131
+ * Cluster configuration for verifying HotStuff-Lite 2f+1 QuorumCertificates (#1712).
132
+ */
133
+ export interface IHotStuffClusterConfig {
134
+ chainId: string;
135
+ validators: IHotStuffValidatorMember[];
136
+ quorumThreshold?: number;
137
+ }
138
+
88
139
  /**
89
140
  * Checkpoint - Verifiable snapshot proof at a Ledger position
90
141
  */
@@ -127,6 +178,9 @@ export interface ICheckpoint {
127
178
 
128
179
  /** Optional proposer signature over `computeSegmentCommitmentDigest(checkpoint.hash, segmentContentHash)` */
129
180
  segmentCommitmentSignature?: string;
181
+
182
+ /** Optional HotStuff-Lite 2f+1 QuorumCertificate certifying this checkpoint (#1712) */
183
+ qc?: IQuorumCertificate;
130
184
  }
131
185
 
132
186
  /**
@@ -208,6 +262,16 @@ export interface ILedgerHealth {
208
262
  // Configuration Types
209
263
  // ============================================================================
210
264
 
265
+ /**
266
+ * Runtime role of a Ledger instance for autonomous checkpoint fencing (#1810)
267
+ */
268
+ export type TLedgerNodeRole = 'validator' | 'standby' | 'follower' | 'readonly';
269
+
270
+ /**
271
+ * Consensus mode of a Ledger instance (#1810)
272
+ */
273
+ export type TLedgerConsensusMode = 'single' | 'hotstuff';
274
+
211
275
  /**
212
276
  * Checkpoint configuration
213
277
  */
@@ -215,11 +279,25 @@ export interface ICheckpointConfig {
215
279
  /** Trigger batch size: create checkpoint every N transactions */
216
280
  batchSize: number;
217
281
 
218
- /** Time trigger: max time since last checkpoint (ms) */
282
+ /** Time trigger: max wait time since earliest pending entry / last checkpoint (ms) */
219
283
  timeoutMs: number;
220
284
 
221
285
  /** Enable auto checkpoint */
222
286
  auto: boolean;
287
+
288
+ /**
289
+ * Explicitly enable background periodic checkpoint timer on quiet chains (#1810).
290
+ * Only active when `periodicTimer === true`, `auto === true`, `timeoutMs > 0`, and the node is a
291
+ * standalone writable `validator` (never on `follower`, `standby`, `readonly`, or `hotstuff`).
292
+ * Defaults to `false`.
293
+ */
294
+ periodicTimer?: boolean;
295
+
296
+ /**
297
+ * Optional polling interval (ms) for the periodic checkpoint timer (#1810).
298
+ * Defaults to `Math.min(15_000, Math.max(20, Math.floor(timeoutMs / 4)))`.
299
+ */
300
+ timerIntervalMs?: number;
223
301
  }
224
302
 
225
303
  /**
@@ -279,6 +357,12 @@ export interface IEntryHashPolicy {
279
357
  resolve?(storage: ILedgerStorage): Promise<unknown>;
280
358
  }
281
359
 
360
+ export interface IPersistedTrustAnchor {
361
+ proposer: string;
362
+ proposerPublicKey: string;
363
+ signatureRatchetLocked?: boolean;
364
+ }
365
+
282
366
  /**
283
367
  * Storage adapter interface - SQLite implements this
284
368
  */
@@ -354,8 +438,17 @@ export interface ILedgerStorage {
354
438
  segmentCommitmentSignature?: string
355
439
  ): Promise<void>;
356
440
 
357
- // Hot-to-Cold retention pruning (optional on storage adapters)
358
- pruneEntriesUpTo?(maxSequence: number): Promise<number>;
441
+ // Hot-to-Cold retention pruning & proof artifact persistence (optional on storage adapters, #1711)
442
+ pruneEntriesUpTo?(maxSequence: number, options?: { vacuum?: boolean; chunkSize?: number }): Promise<number>;
443
+ getPrunedEntrySequence?(hash: string): Promise<number | null>;
444
+ persistEntryHashV2From?(v2From: number): Promise<void>;
445
+ getPersistedTrustAnchor?(): Promise<IPersistedTrustAnchor | null>;
446
+ persistTrustAnchor?(anchor: IPersistedTrustAnchor | null): Promise<void>;
447
+ saveWitnessAttestation?(attestation: IWitnessAttestation, options?: { replaceInvalidFraud?: boolean }): Promise<void>;
448
+ getWitnessAttestations?(height: number): Promise<IWitnessAttestation[]>;
449
+ getWitnessFraudAlerts?(): Promise<IWitnessAttestation[]>;
450
+ saveAnchorReceipt?(receipt: IAnchorReceipt): Promise<void>;
451
+ getAnchorReceipt?(height?: number): Promise<IAnchorReceipt | null>;
359
452
 
360
453
  // Single-writer lease operations (Stage 5, optional on storage adapters)
361
454
  acquireLease?(holderId: string, ttlMs: number, now?: number): Promise<IWriterLease>;
@@ -420,6 +513,18 @@ export interface IImportSegmentOptions {
420
513
  * Defaults to `true`. Set `false` only when importing legacy synthetic segments whose headers carry an external stateRoot.
421
514
  */
422
515
  verifyStateRoot?: boolean;
516
+
517
+ /**
518
+ * Set to `true` ONLY when the bare `checkpoint` header was cryptographically bound to `this.chainId` by a
519
+ * verified proposer `statusSignature` or full cold segment `segmentCommitmentSignature` (#1711).
520
+ */
521
+ chainBoundAuthenticated?: boolean;
522
+
523
+ /**
524
+ * Optional HotStuff-Lite 3f+1 cluster config (#1712): when provided, every checkpoint at `height > 0`
525
+ * MUST carry a valid `2f+1` `QuorumCertificate` (`checkpoint.qc`) signed by cluster validators.
526
+ */
527
+ hotstuffClusterConfig?: IHotStuffClusterConfig;
423
528
  }
424
529
 
425
530
  // ============================================================================
@@ -484,15 +589,40 @@ export interface IVerifyTxInclusionParams {
484
589
  verifyDecodedEntry?: boolean;
485
590
 
486
591
  /**
487
- * Entry hash versioning (#1337). Entries with `sequence >= entryHashV2From` must be v2
488
- * (length-prefixed) and earlier ones v1 (legacy, <= 1.30.26). When omitted the verifier accepts
489
- * either format (v2 first, then legacy v1), which keeps historical proofs verifying.
592
+ * Entry hash versioning (#1337, #1407). Entries with `sequence >= entryHashV2From` must be v2
593
+ * (length-prefixed) and earlier ones v1 (legacy, <= 1.30.26). Pass `'infinity'` or `Infinity` for a
594
+ * chain where v2 has not been activated (accepts v1 only). When omitted the verifier accepts either
595
+ * format (v2 first, then legacy v1), which keeps historical proofs verifying.
490
596
  */
491
- entryHashV2From?: number;
597
+ entryHashV2From?: number | 'infinity';
492
598
 
493
599
  /** Set false to refuse legacy v1 entry hashes when `entryHashV2From` is unknown (default true). */
494
600
  allowLegacyEntryHash?: boolean;
495
601
 
602
+ /**
603
+ * Checkpoint height at which proposer checkpoint signatures became active (#1376, #1707).
604
+ * - For `checkpoint.height >= checkpointSigActivationHeight`: strictly fails closed on `'unsigned'`
605
+ * or missing `trustAnchor` (`proposerPublicKey` / `verifier`).
606
+ * - For `checkpoint.height < checkpointSigActivationHeight`: verifies the checkpoint via contiguous
607
+ * SHA-256 `prevCheckpoint` hash-chain links up to `activationCheckpointHash`.
608
+ */
609
+ checkpointSigActivationHeight?: number;
610
+
611
+ /**
612
+ * Trusted 64-hex SHA-256 checkpoint hash anchoring pre-activation (`< checkpointSigActivationHeight`)
613
+ * checkpoints via backward `prevCheckpoint` hash-chain verification (#1707).
614
+ */
615
+ activationCheckpointHash?: string;
616
+
617
+ /**
618
+ * Contiguous ascending checkpoints linking `checkpoint` up to `activationCheckpointHash`
619
+ * when `checkpoint.height < checkpointSigActivationHeight` and `checkpoint.hash !== activationCheckpointHash`.
620
+ */
621
+ checkpointChain?: ICheckpoint[];
622
+
623
+ /** Optional expected chainId enforced against entry, witness attestations, and anchor receipt */
624
+ expectedChainId?: string;
625
+
496
626
  /** Optional k-of-n witness cosigning threshold (default 0) */
497
627
  witnessQuorum?: number;
498
628
 
@@ -500,7 +630,35 @@ export interface IVerifyTxInclusionParams {
500
630
  witnessAttestations?: IWitnessAttestation[];
501
631
 
502
632
  /** Optional map of trusted witness DID -> public key (or list of trusted witness DIDs) */
503
- trustedWitnesses?: Record<string, string | Buffer> | string[];
633
+ trustedWitnesses?: Record<string, string | Uint8Array | Buffer> | string[];
634
+
635
+ /** Optional external/proposer anchor receipt binding checkpoint hash (#1711) */
636
+ anchorReceipt?: IAnchorReceipt;
637
+
638
+ /** Explicit public key authenticating `anchorReceipt.signature` (never falls back to hot `proposerPublicKey`) */
639
+ anchorPublicKey?: string | Uint8Array | Buffer;
640
+
641
+ /** Optional custom verifier callback authenticating `anchorReceipt.signature` */
642
+ anchorVerifier?: (data: Buffer, signature: string, signer: string) => Promise<boolean> | boolean;
643
+
644
+ /** When true, `verifyTxInclusion` fails closed if `anchorReceipt` is missing */
645
+ requireAnchorReceipt?: boolean;
646
+
647
+ /** Optional previously observed anchor receipt at the same height to detect split-view / rollback conflicts */
648
+ priorAnchorReceipt?: IAnchorReceipt;
649
+
650
+ /**
651
+ * Set to `true` ONLY when the caller has already verified `segmentContentHash === checkpoint.segmentContentHash`
652
+ * over `{ chainId: expectedChainId, checkpoint, entries }`. `verifyTxInclusion` still cryptographically verifies
653
+ * `checkpoint.segmentCommitmentSignature` against `trustAnchor` before honoring this flag (#1711).
654
+ */
655
+ segmentChainIdAuthenticated?: boolean;
656
+
657
+ /**
658
+ * Optional HotStuff-Lite 3f+1 cluster config (#1712): when provided, `verifyTxInclusion` enforces
659
+ * `2f+1` validator signatures on `checkpoint.qc` in addition to Merkle & entry verification.
660
+ */
661
+ hotstuffClusterConfig?: IHotStuffClusterConfig;
504
662
  }
505
663
 
506
664
  /**
@@ -528,6 +686,8 @@ export interface IWitnessAttestation {
528
686
  ok: boolean;
529
687
  reason?: string;
530
688
  witness: string;
689
+ /** Optional witness public key (hex/base64) bound via `verifyDidMatchesMultiCurvePublicKey` (#1711) */
690
+ witnessPublicKey?: string;
531
691
  timestamp: number;
532
692
  signature: string;
533
693
  }
@@ -676,7 +836,7 @@ export interface IAnchorPayload {
676
836
  height: number;
677
837
  checkpointHash: string;
678
838
  sequence: number;
679
- txRoot: string;
839
+ txRoot?: string;
680
840
  stateRoot?: string;
681
841
  timestamp: number;
682
842
  proposer: string;
@@ -689,8 +849,13 @@ export interface IAnchorReceipt {
689
849
  payload: IAnchorPayload;
690
850
  anchorHash: string;
691
851
  signature: string;
692
- publishedAt: number;
852
+ anchoredAt?: number;
853
+ publishedAt?: number;
854
+ anchorTarget?: string;
855
+ externalRef?: string;
693
856
  externalTxId?: string;
857
+ anchorSigner?: string;
858
+ anchorPublicKey?: string;
694
859
  }
695
860
 
696
861
  // ============================================================================
@@ -722,6 +887,13 @@ export interface ILedger {
722
887
 
723
888
  // Metadata
724
889
  getLatestSequence(): Promise<number>;
890
+ getProposer?(): string;
891
+ getProposerPublicKey?(): string | undefined;
892
+ isCheckpointSigningEnabled?(): boolean;
893
+ getEntryHashV2From?(): number;
894
+ getPersistedTrustAnchor?(): Promise<IPersistedTrustAnchor | null>;
895
+ persistTrustAnchor?(anchor: IPersistedTrustAnchor | null): Promise<void>;
896
+ signConsensusDigest?(digest: Uint8Array): Promise<string | null>;
725
897
 
726
898
  // State commit hash
727
899
  /**
@@ -747,9 +919,23 @@ export interface ILedger {
747
919
  /** treeSize = checkpoint.txCount; pass it when the leaf is not recomputed locally (#972) */
748
920
  verifyMerkleProof(proof: IMerkleProof, treeSize?: number): boolean;
749
921
 
750
- // Incremental Backup / Restore
922
+ // Incremental Backup / Restore & Verified Follower Replication (#1710)
751
923
  exportSegment(height: number): Promise<ILedgerSegment>;
752
924
  importSegment(segment: ILedgerSegment, options?: IImportSegmentOptions): Promise<void>;
925
+ verifySegmentForImport?(
926
+ segment: ILedgerSegment,
927
+ options?: IImportSegmentOptions & { allowAheadLocalSequence?: boolean }
928
+ ): Promise<void>;
929
+ appendVerifiedEntries?(
930
+ entries: ILedgerEntry[],
931
+ options?: {
932
+ entryHashV2From?: number | 'infinity';
933
+ verifyTxRawHash?: boolean;
934
+ strictDecode?: boolean;
935
+ requireWireOnly?: boolean;
936
+ }
937
+ ): Promise<void>;
938
+ sealVerifiedCheckpoint?(checkpoint: ICheckpoint, options?: IImportSegmentOptions): Promise<void>;
753
939
 
754
940
  // Monitoring
755
941
  getHealth(): Promise<ILedgerHealth>;
@@ -759,6 +945,150 @@ export interface ILedger {
759
945
  close(): Promise<void>;
760
946
  }
761
947
 
948
+ // ============================================================================
949
+ // Sanitized Public Snapshot, Cold Archive Head & Hot-Tail Sync Types (#1709)
950
+ // ============================================================================
951
+
952
+ /**
953
+ * Checksum and byte-size metadata for a single compressed SQLite file in a sanitized public snapshot.
954
+ */
955
+ export interface ISanitizedSnapshotFileMeta {
956
+ file: 'statedb.sqlite.zst' | 'ledger.sqlite.zst';
957
+ rawBytes: number;
958
+ rawSha256: string;
959
+ zstBytes: number;
960
+ zstSha256: string;
961
+ }
962
+
963
+ /**
964
+ * Individual validator signature entry over `ISanitizedSnapshotManifest.manifestHash` (#1712).
965
+ */
966
+ export interface ISnapshotManifestSignatureEntry {
967
+ signerDid: string;
968
+ publicKey?: string | null;
969
+ signature: string;
970
+ }
971
+
972
+ /**
973
+ * Signed manifest describing a sanitized, checkpoint-aligned public base snapshot (`statedb.sqlite.zst` + `ledger.sqlite.zst`).
974
+ */
975
+ export interface ISanitizedSnapshotManifest {
976
+ version: 1;
977
+ chainId: string;
978
+ snapshotDir?: string | null;
979
+ createdAt: string;
980
+ snapshotSequence: number;
981
+ stateCommitHash: string;
982
+ checkpointHeight: number;
983
+ checkpointSequence: number;
984
+ checkpointHash: string | null;
985
+ checkpointStateRoot: string | null;
986
+ entryHashV2From: number | 'infinity';
987
+ files: {
988
+ statedb: ISanitizedSnapshotFileMeta;
989
+ ledger: ISanitizedSnapshotFileMeta;
990
+ };
991
+ proposer: string | null;
992
+ proposerPublicKey: string | null;
993
+ manifestHash: string;
994
+ signature: string;
995
+ /** Optional `>= 2f+1` validator quorum signatures over `manifestHash` for HotStuff clusters (#1712) */
996
+ quorumSignatures?: ISnapshotManifestSignatureEntry[];
997
+ }
998
+
999
+ /**
1000
+ * Lightweight head pointer (`<prefix>/<chainId>/latest.json`) published to R2/S3/CDN after sealing a checkpoint segment.
1001
+ */
1002
+ export interface ILedgerArchiveHead {
1003
+ version: 1;
1004
+ chainId: string;
1005
+ latestHeight: number;
1006
+ latestSequence: number;
1007
+ latestCheckpointHash: string;
1008
+ latestStateRoot: string | null;
1009
+ latestSegmentKey: string;
1010
+ latestSegmentContentHash: string;
1011
+ entryHashV2From: number | 'infinity';
1012
+ proposer: string;
1013
+ proposerPublicKey?: string;
1014
+ updatedAt: number;
1015
+ }
1016
+
1017
+ /**
1018
+ * Read-only hot-tail status response (`GET /api/ledger/status`).
1019
+ */
1020
+ export interface ILedgerStatusResponse {
1021
+ chainId: string;
1022
+ latestSequence: number;
1023
+ latestCheckpoint: ICheckpoint | null;
1024
+ entryHashV2From: string | null;
1025
+ proposer: string | null;
1026
+ proposerPublicKey: string | null;
1027
+ signatureKeyType?: 'ed25519' | 'secp256k1' | null;
1028
+ checkpointSigningEnabled: boolean;
1029
+ snapshotBaseUrl: string | null;
1030
+ nodeId?: string;
1031
+ nodeRole?: TLedgerNodeRole;
1032
+ followerAuthenticated?: boolean;
1033
+ trustedProposer?: string | null;
1034
+ trustedProposerPublicKey?: string | null;
1035
+ upstreamNodeId?: string | null;
1036
+ upstreamNodeRole?: TNodeRole | null;
1037
+ retentionMode?: 'archive' | 'tiered';
1038
+ witnessQuorum?: number;
1039
+ consensusMode?: TLedgerConsensusMode;
1040
+ consensusView?: number;
1041
+ highQC?: IQuorumCertificate | null;
1042
+ lastTC?: unknown;
1043
+ writable?: boolean;
1044
+ halted?: boolean;
1045
+ statusSignature?: string | null;
1046
+ }
1047
+
1048
+ /**
1049
+ * Bounded read-only hot-tail entries response (`GET /api/ledger/entries?from=<seq>&limit=<n>`).
1050
+ */
1051
+ export interface ILedgerEntriesResponse {
1052
+ chainId: string;
1053
+ from: number;
1054
+ limit: number;
1055
+ count: number;
1056
+ latestSequence: number;
1057
+ nextFrom: number;
1058
+ hasMore: boolean;
1059
+ entryHashV2From?: string | null;
1060
+ proposer?: string | null;
1061
+ proposerPublicKey?: string | null;
1062
+ batchSignature?: string | null;
1063
+ entries: ILedgerEntry[];
1064
+ }
1065
+
1066
+ /**
1067
+ * Consensus commit hook (`#1712`) invoked by `tx-protocols` `createExecute` when a node runs in
1068
+ * `CONSENSUS_MODE=hotstuff`:
1069
+ * 1. `prepareProposalSlot()` pins the monotonic slot timestamp (`timestampMs`) and next sequence
1070
+ * before executing the transaction pipeline.
1071
+ * 2. `commitStagedEntry(...)` runs inside `SqliteStateDB.runAsLambda`'s `beforeCommit` hook AFTER
1072
+ * `_state_commit` is computed and BEFORE SQLite commits `statedb.sqlite`. It collects a `2f+1`
1073
+ * `QuorumCertificate` and atomically writes the finalized entry + QC checkpoint into `ledger.sqlite`,
1074
+ * or throws an error with `isConsensusAbort === true` so `statedb.sqlite` rolls back cleanly.
1075
+ * 3. `afterStateCommitted(...)` runs immediately after `statedb.sqlite` and `indexdb` commit to
1076
+ * fast-path push `/consensus/commit` to peer replicas and advance the cluster view.
1077
+ */
1078
+ export interface IConsensusCommitter {
1079
+ prepareProposalSlot(): Promise<{
1080
+ timestampMs: number;
1081
+ sequence: number;
1082
+ }>;
1083
+ commitStagedEntry(params: {
1084
+ txInput: ISignedTransactionInput;
1085
+ sequence: number;
1086
+ stateCommitHash: string;
1087
+ timestampMs: number;
1088
+ }): Promise<ILedgerEntry>;
1089
+ afterStateCommitted?(entry: ILedgerEntry): Promise<void>;
1090
+ }
1091
+
762
1092
  // ============================================================================
763
1093
  // Factory Interface
764
1094
  // ============================================================================
@@ -18,7 +18,7 @@
18
18
  // type DelegateContext = IReadyContext<TDelegateTx> & IWithSender & IWithReceiver & IWithDelegation;
19
19
  //
20
20
 
21
- import type { ILedger } from './ledger';
21
+ import type { IConsensusCommitter, ILedger } from './ledger';
22
22
 
23
23
  import type { TTokenInput, TTransactionReceipt } from '../lib/type_pb';
24
24
  import type { BN } from './base';
@@ -219,6 +219,9 @@ export interface IBaseContext<TItx = unknown> {
219
219
  /** Verifiable ledger instance for append-only transaction log */
220
220
  ledger: ILedger;
221
221
 
222
+ /** Optional BFT consensus committer (`#1712`) staging ledger writes until a 2f+1 QC is sealed */
223
+ consensusCommitter?: IConsensusCommitter;
224
+
222
225
  /** Ledger sequence number (set by WriteLedger pipe, used in Phase 6) */
223
226
  ledgerSequence?: number;
224
227
 
@@ -64,6 +64,7 @@ import type {
64
64
 
65
65
  import type { TTransactionReceipt } from '../lib/type_pb';
66
66
  import type { TPageInfo } from './indexdb';
67
+ import type { IConsensusCommitter, IQuorumCertificate } from './ledger';
67
68
 
68
69
  // Note: We don't import IList*Result from indexdb because resolver uses its own paging format
69
70
 
@@ -77,6 +78,8 @@ export interface IResolverContext {
77
78
  featureSwitch: Record<string, unknown>;
78
79
  gasStakeHeaders: { token: string; pk: string };
79
80
  request: { userAgent: string | undefined; ip: string; id: string };
81
+ /** Raw X-Ocap-Forwarded-Hop header value when present (#1710 loop prevention) */
82
+ forwardedHop?: string | string[];
80
83
  /**
81
84
  * Set by @ocap/gql on listTransactions / listAssetTransactions calls only: the result is read solely through
82
85
  * the GraphQL `IndexedTransaction` type, so the resolver may read just the index columns that type and
@@ -86,6 +89,80 @@ export interface IResolverContext {
86
89
  [key: string]: unknown;
87
90
  }
88
91
 
92
+ export type TNodeRole = 'validator' | 'standby' | 'follower';
93
+ export type TNodeWritePolicy = 'reject' | 'forward';
94
+ export type TNodeRetentionMode = 'archive' | 'tiered';
95
+ export type TFollowerSyncMode = 'primary' | 'active-follower' | 'offline-readonly';
96
+
97
+ export interface IFollowerStatusResponse {
98
+ chainId: string;
99
+ nodeRole: TNodeRole;
100
+ writePolicy: TNodeWritePolicy;
101
+ retentionMode?: TNodeRetentionMode;
102
+ syncMode: TFollowerSyncMode;
103
+ synced: boolean;
104
+ halted: boolean;
105
+ haltReason: string | null;
106
+ localSequence: number;
107
+ upstreamSequence: number | null;
108
+ syncLagEntries: number | null;
109
+ verifiedCheckpointHeight: number;
110
+ verifiedCheckpointHash: string | null;
111
+ localStateCommitHash: string;
112
+ activeLeaderUrl: string | null;
113
+ lastUpstreamSuccessAt: string | null;
114
+ witnessEnabled?: boolean;
115
+ witnessAddress?: string | null;
116
+ }
117
+
118
+ export interface INodeRuntimeAdapter {
119
+ readonly role: TNodeRole;
120
+ readonly writePolicy: TNodeWritePolicy;
121
+ isSynced(): boolean | Promise<boolean>;
122
+ isHalted(): boolean;
123
+ isReconciling?(): boolean;
124
+ getHaltReason(): string | null;
125
+ isFollowerAuthenticated?(): boolean;
126
+ getTrustedProposer?(): string | null;
127
+ getTrustedProposerPublicKey?(): string | null;
128
+ getUpstreamNodeId?(): string | null;
129
+ getUpstreamNodeRole?(): TNodeRole | null;
130
+ /**
131
+ * Optional multi-node BFT hook (#1712): returns `true` when this node is the active writable
132
+ * leader and should execute `sendTx` locally; returns `false` when non-leader or quorum-isolated
133
+ * so `Resolver.sendTx` forwards via `forwardSendTx` (if `writePolicy === 'forward'`) or rejects.
134
+ */
135
+ shouldHandleWriteLocally?(): boolean;
136
+ /** Optional BFT committer injected into `execute()` when handling leader writes locally (#1712) */
137
+ getConsensusCommitter?(): IConsensusCommitter | undefined;
138
+ /**
139
+ * Optional serialized execution wrapper (#1712): runs pre-round catchup/`lockedCheckpoint` recovery,
140
+ * executes `fn()` under the consensus mutex so `SqliteStateDB` never overlaps dry-run/replay transactions,
141
+ * and broadcasts `/consensus/commit` after releasing the mutex.
142
+ */
143
+ executeWithConsensusLock?<T>(fn: () => Promise<T>): Promise<T>;
144
+ getConsensusMode?(): 'single' | 'hotstuff';
145
+ getConsensusView?(): number;
146
+ getHighQC?(): IQuorumCertificate | null;
147
+ getLockedQC?(): IQuorumCertificate | null;
148
+ getLastTC?(): unknown;
149
+ getRuntimeDiagnostics?(options?: {
150
+ includePrivateTopology?: boolean;
151
+ }): Record<string, unknown> | Promise<Record<string, unknown>>;
152
+ updateRuntimeConfig?(patch: {
153
+ writePolicy?: TNodeWritePolicy;
154
+ pollIntervalMs?: number;
155
+ maxSyncLag?: number;
156
+ peerUrls?: string[];
157
+ }): void;
158
+ triggerSyncOrProbe?(): Promise<Record<string, unknown>>;
159
+ forwardSendTx?(
160
+ args: { tx: string; extra?: Record<string, unknown> | string },
161
+ ctx?: IResolverContext
162
+ ): Promise<{ hash: string; warning?: unknown }>;
163
+ getFollowerStatus?(): Promise<IFollowerStatusResponse>;
164
+ }
165
+
89
166
  // ============ Extended Request Args (Proto types missing fields) ============
90
167
 
91
168
  /**
@@ -357,6 +434,11 @@ export interface IResolverChainInfo {
357
434
  network?: string;
358
435
  supportedTxs?: string[];
359
436
  synced?: boolean;
437
+ nodeRole?: TNodeRole;
438
+ writePolicy?: TNodeWritePolicy;
439
+ syncLagEntries?: number | null;
440
+ verifiedCheckpointHeight?: number;
441
+ halted?: boolean;
360
442
  votingPower?: string;
361
443
  [key: string]: unknown;
362
444
  }
@@ -382,6 +464,11 @@ export interface IResolverNodeInfo {
382
464
  p2pAddress?: string;
383
465
  supportedTxs?: string[];
384
466
  synced?: boolean;
467
+ nodeRole?: TNodeRole;
468
+ writePolicy?: TNodeWritePolicy;
469
+ syncLagEntries?: number | null;
470
+ verifiedCheckpointHeight?: number;
471
+ halted?: boolean;
385
472
  votingPower?: string;
386
473
  [key: string]: unknown;
387
474
  }
@@ -405,6 +492,10 @@ export interface IResolverValidatorsInfo {
405
492
  validators: Array<{
406
493
  address: string;
407
494
  name?: string;
495
+ pubKey?: {
496
+ type: string;
497
+ data: string;
498
+ };
408
499
  proposerPriority?: string;
409
500
  votingPower?: string;
410
501
  }>;
@@ -512,10 +603,17 @@ export interface IResolver {
512
603
  getLatestCheckpoint?(args?: { height?: number }): Promise<unknown>;
513
604
  getLedgerEntry?(args?: { hash?: string; sequence?: number }): Promise<unknown>;
514
605
  getMerkleProof?(args: { sequence: number }): Promise<unknown>;
606
+ getLedgerInfo?(): Promise<unknown>;
607
+ getFollowerStatus?(): Promise<IFollowerStatusResponse | null>;
515
608
 
516
609
  // ============ Lifecycle ============
517
610
  /**
518
- * Graceful shutdown: drain the transaction queue and stop accepting new requests.
611
+ * Idempotent state initialization hook (#1811).
612
+ * When constructed with `deferInitialize: true`, rejects cleanly on immutable config mismatch instead of calling `process.exit(1)`.
613
+ */
614
+ initialize(): Promise<void>;
615
+ /**
616
+ * Graceful shutdown: reject new sendTx, drain in-flight pre-flights, transaction queue, and pending index writes.
519
617
  */
520
618
  shutdown(): Promise<void>;
521
619
  }
@@ -187,9 +187,35 @@ export interface IStateDB extends IReady {
187
187
  evidence: IStateTable<IEvidenceState>;
188
188
  balance: IBalanceTable;
189
189
 
190
- /** Run function within a database transaction - txn type depends on StateDB implementation (dolt, fs, memory) */
190
+ /** Run function within a database transaction - txn type depends on StateDB implementation (sqlite, fs, memory) */
191
191
  runAsLambda?<T>(fn: (txn: unknown) => T | Promise<T>, options?: Record<string, unknown>): Promise<T>;
192
192
 
193
+ /** Execute 1..N steps inside a single rolled-back SQLite dry-run transaction, returning per-step `_state_commit` hashes (#1712) */
194
+ runDryRunBatch?(
195
+ steps: Array<{
196
+ commitMessage?: string;
197
+ expectedCommitHash?: string;
198
+ fn: (txn: unknown) => unknown | Promise<unknown>;
199
+ }>
200
+ ): Promise<{
201
+ commitHashes: string[];
202
+ finalCommitHash: string;
203
+ }>;
204
+
205
+ /** Execute an arbitrary multi-lambda session inside a single rolled-back SQLite transaction using savepoints (#1712) */
206
+ runWithinDryRunSession?<T>(
207
+ sessionFn: (
208
+ runSubLambda: <R>(fn: (txn: unknown) => R | Promise<R>, options?: Record<string, unknown>) => Promise<R>
209
+ ) => Promise<T>
210
+ ): Promise<{
211
+ result: T;
212
+ commitHashes: string[];
213
+ finalCommitHash: string | null;
214
+ }>;
215
+
216
+ /** Read the current deterministic state commit hash (e.g. `_state_commit.current_hash` on SQLite) */
217
+ getCurrentCommitHash?(): Promise<string>;
218
+
193
219
  /** Get table by name - use this for dynamic table access */
194
220
  getTable?(name: StateDBTableName): IStateTable<unknown>;
195
221
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ocap/types",
3
- "version": "1.31.9",
3
+ "version": "1.32.0",
4
4
  "description": "Typescript definitions generated from protobuf",
5
5
  "keywords": [
6
6
  "ocap",