@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.
- package/interfaces/index.ts +6 -0
- package/interfaces/ledger.ts +341 -11
- package/interfaces/pipeline.ts +4 -1
- package/interfaces/resolver.ts +99 -1
- package/interfaces/statedb.ts +27 -1
- package/package.json +1 -1
package/interfaces/index.ts
CHANGED
|
@@ -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)
|
package/interfaces/ledger.ts
CHANGED
|
@@ -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).
|
|
489
|
-
*
|
|
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
|
|
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
|
-
|
|
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
|
// ============================================================================
|
package/interfaces/pipeline.ts
CHANGED
|
@@ -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
|
|
package/interfaces/resolver.ts
CHANGED
|
@@ -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
|
-
*
|
|
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
|
}
|
package/interfaces/statedb.ts
CHANGED
|
@@ -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 (
|
|
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
|
|