@ocap/types 1.30.23 → 1.30.25

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.
@@ -24,6 +24,9 @@ export type { TDelegateConfig, TForeignToken, TTxFeeConfig, TCurveConfig };
24
24
  /** Transaction type URL pattern like 'fg:t:transfer' */
25
25
  export type TxTypeUrl = `fg:t:${string}`;
26
26
 
27
+ /** Execution mode: standard multi-account chain or lightweight zero-gas single-node ledger */
28
+ export type ChainMode = 'chain' | 'ledger';
29
+
27
30
  /** Map of transaction type URL to number value (size, fee, etc.) */
28
31
  export type TxTypeMap = { default: number } & Partial<Record<TxTypeUrl, number>>;
29
32
 
@@ -72,6 +75,8 @@ export interface ITransactionConfig extends Omit<TTransactionConfig, 'txFee' | '
72
75
  delegate: TDelegateConfig;
73
76
  supportedTxs: string[];
74
77
  multiSignV2Txs: string[];
78
+ /** Optional activation height for unsignedTxHash deduplication (default: 0, always active) */
79
+ unsignedTxHashDedupHeight?: number;
75
80
  }
76
81
 
77
82
  /**
@@ -116,6 +121,7 @@ export interface IConsensusConfig {
116
121
 
117
122
  /** Default configuration (without required fields like address) */
118
123
  export interface IDefaultConfig {
124
+ mode?: ChainMode;
119
125
  transaction: ITransactionConfig;
120
126
  vaults: IVaultsConfig;
121
127
  accounts: IAccountConfig[];
@@ -125,6 +131,7 @@ export interface IDefaultConfig {
125
131
 
126
132
  /** Full chain configuration */
127
133
  export interface IChainConfig {
134
+ mode?: ChainMode;
128
135
  chainId: string;
129
136
  chainName?: string;
130
137
  version: string;
@@ -163,6 +163,32 @@ export type TIndexedState =
163
163
  // Index Table Type Mappings
164
164
  // ============================================================================
165
165
 
166
+ /**
167
+ * A persisted record of a failed indexdb write (create/update) originating from
168
+ * `connectIndexDB()`'s statedb event listeners. The write path itself is fire-and-forget
169
+ * (EventEmitter, no retry) — this table is the durable trail that lets a background
170
+ * drain/retry worker (or manual replay) recover from a transient indexdb failure without
171
+ * silently drifting from statedb. See issue #67.
172
+ */
173
+ export interface TIndexFailure {
174
+ /** Unique id for this failure record (not derived from the failed entity) */
175
+ id: string;
176
+ /** IndexDB table the write targeted, e.g. 'account', 'tx' */
177
+ table: string;
178
+ /** Statedb event that triggered the write, e.g. 'create' | 'update' */
179
+ event: string;
180
+ /** Primary key of the entity that failed to index, best-effort (may be empty if unknown) */
181
+ entityId: string;
182
+ /** JSON-serialized snapshot of the state that failed to index, for replay/debugging */
183
+ payload: string;
184
+ /** Number of retry attempts made so far (0 = never retried) */
185
+ attempts: number;
186
+ /** Message of the most recent error */
187
+ lastError: string;
188
+ createdAt: string;
189
+ lastAttemptAt: string;
190
+ }
191
+
166
192
  /** Maps table name to its indexed document type */
167
193
  export type IndexTableTypeMap = {
168
194
  tx: TIndexedTransaction;
@@ -177,6 +203,7 @@ export type IndexTableTypeMap = {
177
203
  rollupValidator: TIndexedRollupValidator;
178
204
  tokenFactory: TIndexedTokenFactoryState;
179
205
  tokenDistribution: TTokenDistribution;
206
+ indexFailure: TIndexFailure;
180
207
  };
181
208
 
182
209
  /** Valid index table names */
@@ -411,6 +438,13 @@ export interface IIndexDB {
411
438
  tokenDistribution: IIndexTable<IndexTableTypeMap['tokenDistribution']>;
412
439
  tokenFactory: IIndexTable<IndexTableTypeMap['tokenFactory']>;
413
440
 
441
+ /**
442
+ * Optional: durable log of failed indexdb writes (see TIndexFailure). Optional so
443
+ * existing/third-party IIndexDB implementers stay source-compatible; adapters that
444
+ * provide it get automatic failure persistence from `connectIndexDB()`.
445
+ */
446
+ indexFailure?: IIndexTable<IndexTableTypeMap['indexFailure']>;
447
+
414
448
  // List methods
415
449
  listTransactions(params?: Partial<TRequestListTransactions>): Promisable<IListTransactionsResult>;
416
450
  listAssets(params?: Partial<TRequestListAssets>): Promisable<IListAssetsResult>;
@@ -455,4 +489,41 @@ export interface IIndexDB {
455
489
  * Must be called during graceful shutdown.
456
490
  */
457
491
  close(): Promise<void>;
492
+
493
+ /**
494
+ * Clear all index tables (or state-only index tables when `preserveTx` is true).
495
+ */
496
+ clear?(options?: { preserveTx?: boolean }): Promise<void>;
497
+
498
+ /**
499
+ * Deterministically rebuild IndexDB tables from StateDB.
500
+ */
501
+ rebuild?(statedb: unknown, options?: IRebuildOptions): Promise<IRebuildResult>;
502
+ }
503
+
504
+ /**
505
+ * Options for rebuilding IndexDB from StateDB (`vledger index rebuild`).
506
+ */
507
+ export interface IRebuildOptions {
508
+ /**
509
+ * When true, skips clearing and rebuilding the `tx` index table,
510
+ * rebuilding only state-derived index tables.
511
+ */
512
+ preserveTx?: boolean;
513
+ /**
514
+ * Optional chain address to read chain state from `statedb.chain`.
515
+ */
516
+ chainAddress?: string;
517
+ }
518
+
519
+ /**
520
+ * Result summary of an IndexDB rebuild operation.
521
+ */
522
+ export interface IRebuildResult {
523
+ /** Number of indexed records written per table */
524
+ tables: Record<string, number>;
525
+ /** Total number of records written across all tables */
526
+ totalRecords: number;
527
+ /** Elapsed time in milliseconds */
528
+ durationMs: number;
458
529
  }
@@ -117,6 +117,12 @@ export interface ICheckpoint {
117
117
 
118
118
  /** Proposer signature */
119
119
  signature: string;
120
+
121
+ /** Optional canonical SHA-256 digest of the checkpoint's segment bundle (`{ chainId, checkpoint, entries }`) */
122
+ segmentContentHash?: string;
123
+
124
+ /** Optional proposer signature over `computeSegmentCommitmentDigest(checkpoint.hash, segmentContentHash)` */
125
+ segmentCommitmentSignature?: string;
120
126
  }
121
127
 
122
128
  /**
@@ -321,6 +327,21 @@ export interface ILedgerStorage {
321
327
  getCheckpointByHeight(height: number): Promise<ICheckpoint | null>;
322
328
  getLatestCheckpoint(): Promise<ICheckpoint | null>;
323
329
  getCheckpointForSequence(seq: number): Promise<ICheckpoint | null>;
330
+ saveSegmentCommitment?(
331
+ checkpointHash: string,
332
+ segmentContentHash: string,
333
+ segmentCommitmentSignature?: string
334
+ ): Promise<void>;
335
+
336
+ // Hot-to-Cold retention pruning (optional on storage adapters)
337
+ pruneEntriesUpTo?(maxSequence: number): Promise<number>;
338
+
339
+ // Single-writer lease operations (Stage 5, optional on storage adapters)
340
+ acquireLease?(holderId: string, ttlMs: number, now?: number): Promise<IWriterLease>;
341
+ renewLease?(holderId: string, ttlMs: number, now?: number): Promise<IWriterLease>;
342
+ releaseLease?(holderId: string): Promise<boolean>;
343
+ getLease?(): Promise<IWriterLease | null>;
344
+ setLeaseConfig?(config?: IWriterLeaseConfig): void;
324
345
 
325
346
  // Schema migration
326
347
  getMigrationVersion(): Promise<number>;
@@ -333,6 +354,264 @@ export interface ILedgerStorage {
333
354
  reset(): Promise<void>;
334
355
  }
335
356
 
357
+ // ============================================================================
358
+ // Segment Backup / Restore Types
359
+ // ============================================================================
360
+
361
+ /**
362
+ * Self-contained, Checkpoint-sliced ledger segment for incremental backup & restore
363
+ */
364
+ export interface ILedgerSegment {
365
+ /** Chain DID */
366
+ chainId: string;
367
+
368
+ /** Checkpoint covering this segment */
369
+ checkpoint: ICheckpoint;
370
+
371
+ /** Finalized entries in (checkpoint.prevSequence, checkpoint.sequence] */
372
+ entries: ILedgerEntry[];
373
+ }
374
+
375
+ /**
376
+ * Options for verifying and importing a ledger segment
377
+ */
378
+ export interface IImportSegmentOptions {
379
+ /** Optional expected proposer DID to enforce */
380
+ expectedProposer?: string;
381
+
382
+ /** Optional signature verifier callback */
383
+ verifier?: (data: Buffer, signature: string, proposer: string) => Promise<boolean> | boolean;
384
+ }
385
+
386
+ // ============================================================================
387
+ // Client Light Verification & Anchor Types (Stage 3 & Stage 8)
388
+ // ============================================================================
389
+
390
+ /**
391
+ * Parameters for pure offline transaction inclusion verification (`verifyTxInclusion`).
392
+ */
393
+ export interface IVerifyTxInclusionParams {
394
+ /** Expected transaction hash (0x + 64 hex chars, or 64 hex chars) */
395
+ txHash?: string;
396
+
397
+ /** Ledger entry returned by getLedgerEntry */
398
+ entry: Pick<ILedgerEntry, 'sequence' | 'hash' | 'txRaw' | 'entryHash' | 'stateCommitHash' | 'finalized'>;
399
+
400
+ /** Merkle inclusion proof returned by getMerkleProof */
401
+ proof: IMerkleProof;
402
+
403
+ /** Checkpoint covering the entry's sequence */
404
+ checkpoint: ICheckpoint;
405
+
406
+ /**
407
+ * Sequencer/Moderator public key (hex or Buffer) — a trust anchor. One of `proposerPublicKey` or
408
+ * `verifier` is required: without it verification fails closed (#1133). Empty values do not count.
409
+ */
410
+ proposerPublicKey?: string | Buffer;
411
+
412
+ /** Optional expected proposer DID */
413
+ expectedProposer?: string;
414
+
415
+ /** Custom checkpoint signature verifier — a trust anchor (takes precedence over `proposerPublicKey`) */
416
+ verifier?: (data: Buffer, signature: string, proposer: string) => Promise<boolean> | boolean;
417
+
418
+ /**
419
+ * UNSAFE. Skip the checkpoint signature check when no trust anchor is supplied, restoring the pre-#1133
420
+ * structural-only result. A malicious source can then forge inclusion; use only for bundles read from a
421
+ * store you already trust. Has no effect when a trust anchor is supplied (the signature is still checked).
422
+ */
423
+ allowUnauthenticated?: boolean;
424
+
425
+ /**
426
+ * If true, also verifies toTxHash(Buffer.from(entry.txRaw, 'base64')) === entry.hash. entry.hash is
427
+ * not covered by the Merkle leaf, so this is what binds txHash to the proven entry (#976). Use it
428
+ * for OCAP chain ledgers; core/client enables it by default (pass false to opt out).
429
+ */
430
+ verifyTxRawHash?: boolean;
431
+
432
+ /** Optional k-of-n witness cosigning threshold (default 0) */
433
+ witnessQuorum?: number;
434
+
435
+ /** Optional witness attestations / cosignatures attached to checkpoint */
436
+ witnessAttestations?: IWitnessAttestation[];
437
+
438
+ /** Optional map of trusted witness DID -> public key (or list of trusted witness DIDs) */
439
+ trustedWitnesses?: Record<string, string | Buffer> | string[];
440
+ }
441
+
442
+ /**
443
+ * Result of `verifyTxInclusion`.
444
+ *
445
+ * Only `txRaw` is authenticated: `entryHash` covers `sequence`, `txRaw` and `stateCommitHash`, not
446
+ * `entry.tx`, `from`, `pk`, `nonce` or `signature`. A `verified: true` result says nothing about those
447
+ * fields. Decode the verified `txRaw` yourself; never read `entry.tx` directly (#1139).
448
+ */
449
+ export interface IVerifyTxInclusionResult {
450
+ verified: boolean;
451
+ reason?: string;
452
+ }
453
+
454
+ /**
455
+ * External witness attestation / cosignature over a Checkpoint (Stage 7).
456
+ */
457
+ export interface IWitnessAttestation {
458
+ chainId: string;
459
+ height: number;
460
+ checkpointHash: string;
461
+ txRoot: string;
462
+ stateRoot?: string;
463
+ ok: boolean;
464
+ reason?: string;
465
+ witness: string;
466
+ timestamp: number;
467
+ signature: string;
468
+ }
469
+
470
+ /**
471
+ * Upstream data provider interface for read-only replica sync (Stage 4).
472
+ */
473
+ export interface IReplicaUpstreamSource {
474
+ getLatestCheckpoint(): Promise<ICheckpoint | null>;
475
+ getCheckpointByHeight(height: number): Promise<ICheckpoint | null>;
476
+ getEntriesByRange(fromSeq: number, toSeq: number): Promise<ILedgerEntry[]>;
477
+ }
478
+
479
+ /**
480
+ * Result of a replica sync cycle (Stage 4).
481
+ */
482
+ export interface IReplicaSyncResult {
483
+ syncedHeights: number[];
484
+ latestHeight: number;
485
+ halted: boolean;
486
+ haltReason?: string;
487
+ haltedAtHeight?: number;
488
+ }
489
+
490
+ /**
491
+ * Rate limit configuration for public gateway (Stage 6).
492
+ */
493
+ export interface IGatewayRateLimitOptions {
494
+ maxRequests: number;
495
+ windowMs: number;
496
+ maxQueryCost?: number;
497
+ }
498
+
499
+ /**
500
+ * Verified transaction read bundle returned by public gateway (Stage 6).
501
+ */
502
+ export interface IGatewayVerifiedTxReadResult {
503
+ entry: ILedgerEntry;
504
+ checkpoint: ICheckpoint | null;
505
+ proof: IMerkleProof | null;
506
+ cosignatures?: IWitnessAttestation[];
507
+ }
508
+
509
+ /**
510
+ * Single-writer lease row in database (Stage 5).
511
+ */
512
+ export interface IWriterLeaseRow {
513
+ id: number;
514
+ holder: string;
515
+ expiresAt: number;
516
+ updatedAt: number;
517
+ }
518
+
519
+ /**
520
+ * Active single-writer lease state (Stage 5).
521
+ */
522
+ export interface IWriterLease {
523
+ holder: string;
524
+ expiresAt: number;
525
+ updatedAt: number;
526
+ }
527
+
528
+ /**
529
+ * Single-writer lease configuration on storage adapters (Stage 5).
530
+ * Default is disabled (`enabled: false`) so single-process tests and deployments
531
+ * require no explicit lease setup.
532
+ */
533
+ export interface IWriterLeaseConfig {
534
+ enabled: boolean;
535
+ holderId: string;
536
+ ttlMs?: number;
537
+ }
538
+
539
+ /**
540
+ * Cold governance root key signature on a KeyRotationCert (Stage 5).
541
+ */
542
+ export interface IKeyRotationSignature {
543
+ signer: string;
544
+ signature: string;
545
+ }
546
+
547
+ /**
548
+ * Key rotation certificate authorizing transition from oldProposer to newProposer (Stage 5).
549
+ * Must be signed by Cold Governance Root Key(s) (`m-of-n`), not solely self-signed by the online hot key.
550
+ */
551
+ export interface IKeyRotationCert {
552
+ chainId: string;
553
+ oldProposer: string;
554
+ newProposer: string;
555
+ newProposerPublicKey?: string;
556
+ effectiveHeight: number;
557
+ lastOldCheckpointHash: string;
558
+ timestamp: number;
559
+ reason?: string;
560
+ certHash: string;
561
+ /** Signatures from Cold Governance Root Key(s) */
562
+ governanceSignatures: IKeyRotationSignature[];
563
+ /** Optional continuity signature from oldProposer if uncompromised */
564
+ oldProposerSignature?: string;
565
+ }
566
+
567
+ /**
568
+ * Options for verifying a KeyRotationCert and its first checkpoint (Stage 5).
569
+ */
570
+ export interface IVerifyKeyRotationOptions {
571
+ /** Trusted Cold Governance Root Key(s): map of DID -> publicKey (hex/Buffer) */
572
+ trustedGovernanceKeys: Record<string, string | Buffer>;
573
+ /** Required number of distinct valid governance signatures (default 1) */
574
+ threshold?: number;
575
+ /** Expected chainId */
576
+ expectedChainId?: string;
577
+ /** Optional last confirmed checkpoint from the old proposer */
578
+ lastOldCheckpoint?: ICheckpoint;
579
+ /** Optional first checkpoint signed by the new proposer */
580
+ firstNewCheckpoint?: ICheckpoint;
581
+ /** Custom signature verifier callback */
582
+ verifier?: (
583
+ data: Buffer,
584
+ signature: string,
585
+ signer: string,
586
+ publicKey?: string | Buffer
587
+ ) => Promise<boolean> | boolean;
588
+ }
589
+
590
+ /**
591
+ * Checkpoint hash anchor payload for external anti-rollback anchoring (Stage 8).
592
+ */
593
+ export interface IAnchorPayload {
594
+ chainId: string;
595
+ height: number;
596
+ checkpointHash: string;
597
+ sequence: number;
598
+ txRoot: string;
599
+ stateRoot?: string;
600
+ timestamp: number;
601
+ proposer: string;
602
+ }
603
+
604
+ /**
605
+ * Signed anchor receipt produced by `AnchorPublisher`.
606
+ */
607
+ export interface IAnchorReceipt {
608
+ payload: IAnchorPayload;
609
+ anchorHash: string;
610
+ signature: string;
611
+ publishedAt: number;
612
+ externalTxId?: string;
613
+ }
614
+
336
615
  // ============================================================================
337
616
  // Ledger Interface
338
617
  // ============================================================================
@@ -384,7 +663,12 @@ export interface ILedger {
384
663
 
385
664
  // Merkle
386
665
  getMerkleProof(sequence: number): Promise<IMerkleProof>;
387
- verifyMerkleProof(proof: IMerkleProof): boolean;
666
+ /** treeSize = checkpoint.txCount; pass it when the leaf is not recomputed locally (#972) */
667
+ verifyMerkleProof(proof: IMerkleProof, treeSize?: number): boolean;
668
+
669
+ // Incremental Backup / Restore
670
+ exportSegment(height: number): Promise<ILedgerSegment>;
671
+ importSegment(segment: ILedgerSegment, options?: IImportSegmentOptions): Promise<void>;
388
672
 
389
673
  // Monitoring
390
674
  getHealth(): Promise<ILedgerHealth>;
@@ -83,6 +83,7 @@ export interface IMultiSigData {
83
83
  delegator?: string;
84
84
  pk: Uint8Array;
85
85
  signature: Uint8Array;
86
+ extra?: string;
86
87
  data?: IAny;
87
88
  }
88
89
 
@@ -242,6 +243,12 @@ export interface ITxOnlyContext extends IBaseContext {
242
243
  tx: IDecodedTransaction;
243
244
  /** Transaction hash (DID format) */
244
245
  txHash: string;
246
+ /**
247
+ * Canonical hash of the unsigned transaction body (excluding outer `signature`
248
+ * and per-multisig `signature`/`extra` fields). Used to prevent duplicate
249
+ * execution via signature/extra malleability.
250
+ */
251
+ unsignedTxHash?: string;
245
252
  /** Transaction timestamp (ISO 8601) */
246
253
  txTime: string;
247
254
  /** Transaction size in bytes */
@@ -501,6 +501,11 @@ export interface IResolver {
501
501
  ctx?: IResolverContext
502
502
  ): Promise<TVerifyAccountRiskResult | null> | null;
503
503
 
504
+ // ============ Verifiable Ledger Queries ============
505
+ getLatestCheckpoint?(args?: { height?: number }): Promise<unknown>;
506
+ getLedgerEntry?(args?: { hash?: string; sequence?: number }): Promise<unknown>;
507
+ getMerkleProof?(args: { sequence: number }): Promise<unknown>;
508
+
504
509
  // ============ Lifecycle ============
505
510
  /**
506
511
  * Graceful shutdown: drain the transaction queue and stop accepting new requests.
package/lib/enum_pb.d.ts CHANGED
@@ -85,6 +85,7 @@ export interface KeyTypeMap {
85
85
  ED25519: 0;
86
86
  SECP256K1: 1;
87
87
  ETHEREUM: 2;
88
+ PASSKEY: 3;
88
89
  }
89
90
 
90
91
  export const KeyType: KeyTypeMap;
package/lib/type_pb.d.ts CHANGED
@@ -122,6 +122,7 @@ export type TMultisig = {
122
122
  pk: Uint8Array | string,
123
123
  signature: Uint8Array | string,
124
124
  delegator: string,
125
+ extra: string,
125
126
  data?: google_protobuf_any_pb.Any,
126
127
  }
127
128
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ocap/types",
3
- "version": "1.30.23",
3
+ "version": "1.30.25",
4
4
  "description": "Typescript definitions generated from protobuf",
5
5
  "keywords": [
6
6
  "ocap",