@optimystic/db-core 1.5.0 → 1.6.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/README.md +336 -336
- package/dist/src/cluster/structs.d.ts +37 -0
- package/dist/src/cluster/structs.d.ts.map +1 -1
- package/dist/src/cluster/structs.js +13 -0
- package/dist/src/cluster/structs.js.map +1 -1
- package/dist/src/collection/collection.d.ts +44 -4
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +95 -14
- package/dist/src/collection/collection.js.map +1 -1
- package/dist/src/log/log.d.ts +41 -8
- package/dist/src/log/log.d.ts.map +1 -1
- package/dist/src/log/log.js +15 -10
- package/dist/src/log/log.js.map +1 -1
- package/dist/src/testing/test-transactor.d.ts +36 -0
- package/dist/src/testing/test-transactor.d.ts.map +1 -1
- package/dist/src/testing/test-transactor.js +49 -0
- package/dist/src/testing/test-transactor.js.map +1 -1
- package/dist/src/transaction/coordinator.d.ts.map +1 -1
- package/dist/src/transaction/coordinator.js +26 -9
- package/dist/src/transaction/coordinator.js.map +1 -1
- package/package.json +1 -1
- package/src/blocks/block-store.ts +31 -31
- package/src/blocks/block-types.ts +11 -11
- package/src/blocks/index.ts +5 -5
- package/src/blocks/structs.ts +17 -17
- package/src/btree/btree.ts +872 -872
- package/src/btree/independent-trunk.ts +53 -53
- package/src/btree/index.ts +5 -5
- package/src/btree/key-range.ts +15 -15
- package/src/btree/keyset.ts +6 -6
- package/src/btree/nodes.ts +25 -25
- package/src/btree/path.ts +37 -37
- package/src/btree/tree-block.ts +11 -11
- package/src/btree/trunk.ts +14 -14
- package/src/chain/chain-nodes.ts +26 -26
- package/src/chain/chain.ts +349 -349
- package/src/chain/index.ts +3 -3
- package/src/cluster/i-cluster.ts +6 -6
- package/src/cluster/index.ts +3 -3
- package/src/cluster/structs.ts +38 -0
- package/src/cohort-topic/addressing.ts +120 -120
- package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
- package/src/cohort-topic/antidos/index.ts +5 -5
- package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
- package/src/cohort-topic/antidos/replay-guard.ts +146 -146
- package/src/cohort-topic/antidos/topic-budget.ts +160 -160
- package/src/cohort-topic/antiflood/index.ts +2 -2
- package/src/cohort-topic/antiflood/invariants.ts +108 -108
- package/src/cohort-topic/antiflood/jitter.ts +117 -117
- package/src/cohort-topic/coldstart.ts +237 -237
- package/src/cohort-topic/dmax.ts +88 -88
- package/src/cohort-topic/gossip/bus.ts +254 -254
- package/src/cohort-topic/gossip/index.ts +3 -3
- package/src/cohort-topic/gossip/records.ts +45 -45
- package/src/cohort-topic/gossip/view.ts +91 -91
- package/src/cohort-topic/index.ts +20 -20
- package/src/cohort-topic/load/barometer.ts +134 -134
- package/src/cohort-topic/load/index.ts +1 -1
- package/src/cohort-topic/member-engine.ts +430 -430
- package/src/cohort-topic/membership/index.ts +3 -3
- package/src/cohort-topic/membership/publisher.ts +163 -163
- package/src/cohort-topic/membership/source.ts +41 -41
- package/src/cohort-topic/ports.ts +157 -157
- package/src/cohort-topic/promotion.ts +477 -477
- package/src/cohort-topic/registration/bytes.ts +37 -37
- package/src/cohort-topic/registration/handoff.ts +154 -154
- package/src/cohort-topic/registration/index.ts +6 -6
- package/src/cohort-topic/registration/renewal.ts +495 -495
- package/src/cohort-topic/registration/sharding.ts +61 -61
- package/src/cohort-topic/registration/store.ts +81 -81
- package/src/cohort-topic/registration/types.ts +91 -91
- package/src/cohort-topic/ring-hash.ts +50 -50
- package/src/cohort-topic/service.ts +416 -416
- package/src/cohort-topic/sig/index.ts +2 -2
- package/src/cohort-topic/sig/payloads.ts +59 -59
- package/src/cohort-topic/sig/threshold.ts +64 -64
- package/src/cohort-topic/tiers.ts +74 -74
- package/src/cohort-topic/traffic.ts +233 -233
- package/src/cohort-topic/walk.ts +326 -326
- package/src/cohort-topic/willingness.ts +237 -237
- package/src/cohort-topic/wire/index.ts +18 -18
- package/src/cohort-topic/wire/payloads.ts +126 -126
- package/src/collection/action.ts +48 -48
- package/src/collection/collection-type-registry.ts +37 -37
- package/src/collection/collection.ts +2203 -2118
- package/src/collection/index.ts +4 -4
- package/src/collections/diary/index.ts +2 -2
- package/src/collections/diary/struct.ts +3 -3
- package/src/collections/index.ts +2 -2
- package/src/collections/tree/collection-trunk.ts +25 -25
- package/src/collections/tree/index.ts +2 -2
- package/src/collections/tree/readme.md +55 -55
- package/src/log/index.ts +2 -2
- package/src/log/log.ts +304 -268
- package/src/log/struct.ts +165 -165
- package/src/matchmaking/capability-filter.ts +45 -45
- package/src/matchmaking/config.ts +98 -98
- package/src/matchmaking/index.ts +21 -21
- package/src/matchmaking/multi-cohort-seeker.ts +234 -234
- package/src/matchmaking/provider.ts +123 -123
- package/src/matchmaking/query-eval.ts +105 -105
- package/src/matchmaking/seeker-walk.ts +127 -127
- package/src/matchmaking/seeker.ts +86 -86
- package/src/matchmaking/topic-anchor.ts +90 -90
- package/src/matchmaking/voting-quorum.ts +394 -394
- package/src/network/i-peer-network.ts +25 -25
- package/src/network/repo-protocol.ts +13 -13
- package/src/network/types.ts +37 -37
- package/src/reactivity/backfill.ts +220 -220
- package/src/reactivity/backpressure.ts +191 -191
- package/src/reactivity/checkpoint.ts +308 -308
- package/src/reactivity/config.ts +172 -172
- package/src/reactivity/dedupe.ts +132 -132
- package/src/reactivity/forwarder.ts +87 -87
- package/src/reactivity/index.ts +34 -34
- package/src/reactivity/notification.ts +123 -123
- package/src/reactivity/policy.ts +79 -79
- package/src/reactivity/push-state.ts +310 -310
- package/src/reactivity/recover.ts +153 -153
- package/src/reactivity/replay-buffer.ts +141 -141
- package/src/reactivity/resume.ts +549 -549
- package/src/reactivity/rotation.ts +415 -415
- package/src/reactivity/subscriber.ts +132 -132
- package/src/reactivity/subscription.ts +66 -66
- package/src/reactivity/topic-anchor.ts +71 -71
- package/src/reactivity/verify.ts +73 -73
- package/src/reactivity/wire-validate.ts +13 -13
- package/src/testing/async-wait.ts +65 -65
- package/src/testing/index.ts +2 -2
- package/src/testing/test-transactor.ts +62 -0
- package/src/transaction/actions-engine.ts +68 -68
- package/src/transaction/coordinator.ts +28 -11
- package/src/transaction/index.ts +52 -52
- package/src/transaction/operations-hash.ts +196 -196
- package/src/transaction/read-dependency-collector.ts +78 -78
- package/src/transaction/session.ts +238 -238
- package/src/transaction/transaction.ts +442 -442
- package/src/transaction/validator.ts +197 -197
- package/src/transactor/block-floors.ts +126 -126
- package/src/transactor/index.ts +6 -6
- package/src/transactor/network-transactor.ts +1545 -1545
- package/src/transform/atomic-proxy.ts +92 -92
- package/src/transform/cache-source.ts +370 -370
- package/src/transform/helpers.ts +164 -164
- package/src/transform/index.ts +7 -7
- package/src/transform/struct.ts +21 -21
- package/src/utility/actor.ts +62 -62
- package/src/utility/backoff.ts +95 -95
- package/src/utility/batch-coordinator.ts +191 -191
- package/src/utility/ensured.ts +32 -32
- package/src/utility/groupby.ts +18 -18
- package/src/utility/hash-string.ts +14 -14
- package/src/utility/is-record-empty.ts +5 -5
- package/src/utility/latches.ts +42 -42
- package/src/utility/lru-map.ts +60 -60
- package/src/utility/nameof.ts +7 -7
- package/src/utility/pending.ts +43 -43
|
@@ -1,442 +1,442 @@
|
|
|
1
|
-
import { randomBytes } from "@noble/hashes/utils.js";
|
|
2
|
-
import { toString as uint8ArrayToString } from "uint8arrays/to-string";
|
|
3
|
-
import type { BlockId } from "../blocks/index.js";
|
|
4
|
-
import type { CollectionId } from "../collection/index.js";
|
|
5
|
-
import { hashString } from "../utility/hash-string.js";
|
|
6
|
-
|
|
7
|
-
/**
|
|
8
|
-
* Transaction Stamp: Created at BEGIN, stable throughout transaction lifecycle.
|
|
9
|
-
*
|
|
10
|
-
* The stamp contains metadata about the transaction's origin and context.
|
|
11
|
-
* The id is computed as a hash of these fields.
|
|
12
|
-
*/
|
|
13
|
-
export type TransactionStamp = {
|
|
14
|
-
/** Peer that initiated the transaction */
|
|
15
|
-
peerId: string;
|
|
16
|
-
|
|
17
|
-
/** When transaction started (milliseconds since epoch) */
|
|
18
|
-
timestamp: number;
|
|
19
|
-
|
|
20
|
-
/** Hash of schema version(s) for validation */
|
|
21
|
-
schemaHash: string;
|
|
22
|
-
|
|
23
|
-
/** Which engine (e.g., 'quereus@0.5.3', 'actions@1.0.0') */
|
|
24
|
-
engineId: string;
|
|
25
|
-
|
|
26
|
-
/** Absolute ms epoch after which transaction is invalid */
|
|
27
|
-
expiration: number;
|
|
28
|
-
|
|
29
|
-
/**
|
|
30
|
-
* Random per-transaction nonce, folded into {@link TransactionStamp.id}.
|
|
31
|
-
*
|
|
32
|
-
* Anti-replay for read-free transactions: a transaction with no reads has nothing
|
|
33
|
-
* binding it to a point in history beyond {@link expiration}, so without this a
|
|
34
|
-
* captured signed read-free transaction could be re-submitted within the TTL window.
|
|
35
|
-
* The nonce makes two otherwise-identical transactions from the same peer at the
|
|
36
|
-
* same millisecond produce different ids (hence different signed bytes).
|
|
37
|
-
*/
|
|
38
|
-
nonce: string;
|
|
39
|
-
|
|
40
|
-
/** Hash of the stamp fields (computed) - stable identifier throughout transaction */
|
|
41
|
-
id: string;
|
|
42
|
-
};
|
|
43
|
-
|
|
44
|
-
/**
|
|
45
|
-
* Transaction: Finalized at COMMIT with complete statement history.
|
|
46
|
-
*
|
|
47
|
-
* Transactions span multiple collections and use pluggable engines for interpreting the statements.
|
|
48
|
-
* The engine re-executes the statements to verify the resulting operations match what was proposed.
|
|
49
|
-
*/
|
|
50
|
-
export type Transaction = {
|
|
51
|
-
/** The transaction stamp (includes stable id) */
|
|
52
|
-
stamp: TransactionStamp;
|
|
53
|
-
|
|
54
|
-
/** Engine-specific statements (for replay/validation)
|
|
55
|
-
* Array of statements executed during the transaction.
|
|
56
|
-
* - For Quereus: SQL statements
|
|
57
|
-
* - For ActionsEngine: JSON-encoded actions
|
|
58
|
-
*/
|
|
59
|
-
statements: string[];
|
|
60
|
-
|
|
61
|
-
/** Read dependencies for optimistic concurrency control */
|
|
62
|
-
reads: ReadDependency[];
|
|
63
|
-
|
|
64
|
-
/** Transaction identifier (hash of stamp.id + statements + reads)
|
|
65
|
-
* Final transaction identity, used in logs
|
|
66
|
-
*/
|
|
67
|
-
id: string;
|
|
68
|
-
|
|
69
|
-
/**
|
|
70
|
-
* Optional client signature (base64url) over {@link clientSignaturePayload}
|
|
71
|
-
* `(stamp.id, statements, reads)`, produced at commit by an injected
|
|
72
|
-
* {@link TransactionSigner}.
|
|
73
|
-
*
|
|
74
|
-
* A node that wires a {@link ClientSignatureVerifier} into its
|
|
75
|
-
* {@link TransactionValidator} verifies this at pend; where no verifier is wired,
|
|
76
|
-
* unsigned transactions are still accepted (migration / single-node-dev posture).
|
|
77
|
-
* Plain field on the transaction, so it rides along through serialization/persistence
|
|
78
|
-
* for later recovery-time re-verification.
|
|
79
|
-
*
|
|
80
|
-
* NOTE: preservation is verified only through JSON round-trip and an in-memory session commit —
|
|
81
|
-
* NOT yet through the db-p2p cluster-repo on-disk transaction-log serialization. No recovery
|
|
82
|
-
* reader exists today; when one lands, confirm this field survives that path so `verifyPeerSig`
|
|
83
|
-
* can re-run at recovery time.
|
|
84
|
-
*/
|
|
85
|
-
signature?: string;
|
|
86
|
-
|
|
87
|
-
/**
|
|
88
|
-
* Aged, advisory retry priority (default 0 when absent). Rises by one per failed retry
|
|
89
|
-
* attempt (attempt-count-derived — deterministic, no wall clock, clock-skew-free) and is
|
|
90
|
-
* capped at {@link MaxPriority}. A cluster member uses it ONLY as the first tiebreak in a
|
|
91
|
-
* concurrent race between two simultaneously-pending conflicting transactions
|
|
92
|
-
* (`resolveRace`), so a transaction that keeps losing races eventually out-ranks fresh
|
|
93
|
-
* (priority-0) rivals instead of losing at random forever.
|
|
94
|
-
*
|
|
95
|
-
* FAIRNESS-ONLY — MUST NOT influence validity, the operations hash, stale-read checks, the
|
|
96
|
-
* transaction id, or the client signature. It is deliberately excluded from
|
|
97
|
-
* {@link createTransactionId} and {@link clientSignaturePayload} so two attempts of the same
|
|
98
|
-
* logical transaction (differing only in priority) keep the same id and signature; folding it
|
|
99
|
-
* into either would churn identity/anti-replay on every retry. It rides inside the signed
|
|
100
|
-
* cluster `message` (via the pend operation), so it is integrity-protected in transit — a
|
|
101
|
-
* relaying peer cannot strip or inflate it without invalidating the message hash — but the
|
|
102
|
-
* originating coordinator can still self-assert it (a fairness concern, not a safety one; see
|
|
103
|
-
* `docs/correctness.md` Theorem 9).
|
|
104
|
-
*/
|
|
105
|
-
priority?: number;
|
|
106
|
-
};
|
|
107
|
-
|
|
108
|
-
/**
|
|
109
|
-
* Read dependency for optimistic concurrency control.
|
|
110
|
-
* Tracks which block revisions were read during transaction execution.
|
|
111
|
-
*/
|
|
112
|
-
export type ReadDependency = {
|
|
113
|
-
blockId: BlockId;
|
|
114
|
-
/** Expected revision number at time of read */
|
|
115
|
-
revision: number;
|
|
116
|
-
};
|
|
117
|
-
|
|
118
|
-
/**
|
|
119
|
-
* Transaction reference embedded in actions.
|
|
120
|
-
* Just the transaction ID - full transaction can be looked up separately if needed.
|
|
121
|
-
*/
|
|
122
|
-
export type TransactionRef = string; // The transaction ID
|
|
123
|
-
|
|
124
|
-
/** Default transaction time-to-live in milliseconds (30 seconds). */
|
|
125
|
-
export const DEFAULT_TRANSACTION_TTL_MS = 30_000;
|
|
126
|
-
|
|
127
|
-
/**
|
|
128
|
-
* Upper bound on a transaction's aged {@link Transaction.priority}. Capping is essential: it
|
|
129
|
-
* bounds the fairness effect (an aged transaction cannot accrue unlimited advantage) and bounds
|
|
130
|
-
* the throughput cost (it can impose at most `MaxPriority` extra race-losses on rivals before it
|
|
131
|
-
* commits). Two transactions capped out at `MaxPriority` fall back to the existing approval-count /
|
|
132
|
-
* message-hash tiebreak, so behavior degrades gracefully to the pre-priority status quo.
|
|
133
|
-
*/
|
|
134
|
-
export const MaxPriority = 8;
|
|
135
|
-
|
|
136
|
-
/**
|
|
137
|
-
* Clamp an attempt-derived priority into `[0, MaxPriority]`. Total: any non-finite / negative
|
|
138
|
-
* input collapses to 0, anything above the cap to {@link MaxPriority}, and the result is floored
|
|
139
|
-
* to an integer. Used both where priority is *set* (the retry loops) and where it is *read* (a
|
|
140
|
-
* cluster member's `resolveRace`), so a Byzantine coordinator self-asserting an out-of-range value
|
|
141
|
-
* cannot exceed the cap.
|
|
142
|
-
*/
|
|
143
|
-
export function clampPriority(priority: number | undefined): number {
|
|
144
|
-
if (typeof priority !== 'number' || Number.isNaN(priority) || priority <= 0) {
|
|
145
|
-
return 0;
|
|
146
|
-
}
|
|
147
|
-
// A positive out-of-range value (including +Infinity, or a Byzantine self-asserted number) clamps
|
|
148
|
-
// DOWN to the cap; anything strictly inside the range is floored to an integer.
|
|
149
|
-
if (priority >= MaxPriority) {
|
|
150
|
-
return MaxPriority;
|
|
151
|
-
}
|
|
152
|
-
return Math.floor(priority);
|
|
153
|
-
}
|
|
154
|
-
|
|
155
|
-
/** Check whether a transaction stamp has expired. */
|
|
156
|
-
export function isTransactionExpired(stamp: TransactionStamp): boolean {
|
|
157
|
-
return Date.now() > stamp.expiration;
|
|
158
|
-
}
|
|
159
|
-
|
|
160
|
-
/** The stamp fields that feed the id hash (everything except the id itself). */
|
|
161
|
-
export type StampFields = Omit<TransactionStamp, 'id'>;
|
|
162
|
-
|
|
163
|
-
/**
|
|
164
|
-
* Compute the canonical stamp id from its fields. MUST match the historical field order
|
|
165
|
-
* (peerId, timestamp, schemaHash, engineId, expiration, nonce) — changing it churns every
|
|
166
|
-
* existing stamp id and client signature. Both {@link createTransactionStamp} and the
|
|
167
|
-
* validator's integrity check derive the id through this one function, so a validating node
|
|
168
|
-
* can re-derive the id and reject a stamp whose fields were tampered while id stayed fixed.
|
|
169
|
-
*/
|
|
170
|
-
export async function computeStampId(fields: StampFields): Promise<string> {
|
|
171
|
-
// Destructure and rebuild in fixed order rather than passing `fields` straight to
|
|
172
|
-
// JSON.stringify — this ignores any stray `id` (or extra) property a caller slipped in,
|
|
173
|
-
// so the serialized bytes depend on exactly the six fields and nothing else.
|
|
174
|
-
const { peerId, timestamp, schemaHash, engineId, expiration, nonce } = fields;
|
|
175
|
-
const stampData = JSON.stringify({ peerId, timestamp, schemaHash, engineId, expiration, nonce });
|
|
176
|
-
return `stamp:${await hashString(stampData)}`;
|
|
177
|
-
}
|
|
178
|
-
|
|
179
|
-
/**
|
|
180
|
-
* Create a transaction stamp with computed id.
|
|
181
|
-
* The id is a hash of the stamp fields (including expiration).
|
|
182
|
-
*/
|
|
183
|
-
export async function createTransactionStamp(
|
|
184
|
-
peerId: string,
|
|
185
|
-
timestamp: number,
|
|
186
|
-
schemaHash: string,
|
|
187
|
-
engineId: string,
|
|
188
|
-
ttlMs: number = DEFAULT_TRANSACTION_TTL_MS
|
|
189
|
-
): Promise<TransactionStamp> {
|
|
190
|
-
const expiration = timestamp + ttlMs;
|
|
191
|
-
// Cross-platform CSPRNG (Node + browser) via @noble/hashes — matches the rest of
|
|
192
|
-
// db-core (see collection.ts, transactor-source.ts). The nonce is folded into the
|
|
193
|
-
// id hash so two otherwise-identical stamps diverge.
|
|
194
|
-
const nonce = uint8ArrayToString(randomBytes(16), 'base64url');
|
|
195
|
-
const id = await computeStampId({ peerId, timestamp, schemaHash, engineId, expiration, nonce });
|
|
196
|
-
return { peerId, timestamp, schemaHash, engineId, expiration, nonce, id };
|
|
197
|
-
}
|
|
198
|
-
|
|
199
|
-
/**
|
|
200
|
-
* Create a transaction id from stamp id, statements, and reads.
|
|
201
|
-
* This is the final transaction identity used in logs.
|
|
202
|
-
*
|
|
203
|
-
* NOTE: reads are serialized in their given order here (non-canonical). This differs
|
|
204
|
-
* from {@link clientSignaturePayload}, which canonicalises reads before hashing. That is
|
|
205
|
-
* intentional for this ticket — the signature payload is self-contained — but the
|
|
206
|
-
* non-canonical ordering here is a separate hygiene concern (see
|
|
207
|
-
* design-consensus-hygiene-notes), NOT fixed here to avoid changing existing tx ids.
|
|
208
|
-
*
|
|
209
|
-
* NOTE: {@link Transaction.priority} is deliberately absent from this preimage — the id is a pure
|
|
210
|
-
* function of `(stampId, statements, reads)`, so two retry attempts that differ only in aged
|
|
211
|
-
* priority produce the SAME id. Do not add priority here.
|
|
212
|
-
*/
|
|
213
|
-
export async function createTransactionId(
|
|
214
|
-
stampId: string,
|
|
215
|
-
statements: string[],
|
|
216
|
-
reads: ReadDependency[]
|
|
217
|
-
): Promise<string> {
|
|
218
|
-
const txData = JSON.stringify({ stampId, statements, reads });
|
|
219
|
-
return `tx:${await hashString(txData)}`;
|
|
220
|
-
}
|
|
221
|
-
|
|
222
|
-
/**
|
|
223
|
-
* Version prefix for the client-signature payload, so the signed form can evolve
|
|
224
|
-
* without ambiguity. Distinct from (but consistent in spirit with) the operations-hash
|
|
225
|
-
* canonical form — this covers transaction INPUTS, not operations.
|
|
226
|
-
*/
|
|
227
|
-
export const CLIENT_SIG_VERSION = 'txsig:v1';
|
|
228
|
-
|
|
229
|
-
/**
|
|
230
|
-
* Canonical bytes a client signs and a node verifies. Deterministic: reads are sorted
|
|
231
|
-
* (blockId, then revision); statements keep their sequential order.
|
|
232
|
-
*
|
|
233
|
-
* Binds three things at once: the CLIENT IDENTITY (via `stampId`, which hashes peerId +
|
|
234
|
-
* nonce), the EXACT statements, and the OCC read set (blockId + revision — "tail
|
|
235
|
-
* binding" for anti-replay). Both signer and verifier derive the bytes from
|
|
236
|
-
* `transaction.stamp.id` + `transaction.statements` + `transaction.reads` through this
|
|
237
|
-
* one function, so they reproduce identical bytes regardless of read ordering.
|
|
238
|
-
*
|
|
239
|
-
* NOTE: {@link Transaction.priority} is deliberately absent from the signed bytes — a retry that
|
|
240
|
-
* only bumps priority keeps the same signature, so anti-replay / OCC binding never churns. Do not
|
|
241
|
-
* add priority here.
|
|
242
|
-
*/
|
|
243
|
-
export function clientSignaturePayload(
|
|
244
|
-
stampId: string,
|
|
245
|
-
statements: readonly string[],
|
|
246
|
-
reads: readonly ReadDependency[]
|
|
247
|
-
): Uint8Array {
|
|
248
|
-
const canonicalReads = [...reads].sort(
|
|
249
|
-
(a, b) => a.blockId < b.blockId ? -1 : a.blockId > b.blockId ? 1
|
|
250
|
-
: a.revision - b.revision
|
|
251
|
-
);
|
|
252
|
-
const body = JSON.stringify({ stampId, statements, reads: canonicalReads });
|
|
253
|
-
return new TextEncoder().encode(`${CLIENT_SIG_VERSION}:${body}`);
|
|
254
|
-
}
|
|
255
|
-
|
|
256
|
-
/**
|
|
257
|
-
* Signs the canonical client-signature payload, returning base64url. Async to allow
|
|
258
|
-
* libp2p `PrivateKey.sign`; tests pass a synchronous fake.
|
|
259
|
-
*/
|
|
260
|
-
export type TransactionSigner = (payload: Uint8Array) => Promise<string> | string;
|
|
261
|
-
|
|
262
|
-
/**
|
|
263
|
-
* Returns true iff `signature` (base64url) is a valid client signature over `payload`
|
|
264
|
-
* for signer identity `peerId`. Total: returns false, never throws, on any malformed
|
|
265
|
-
* input. The p2p wiring backs this with verifyPeerSig + peerIdBindsPublicKey; tests
|
|
266
|
-
* pass a fake.
|
|
267
|
-
*/
|
|
268
|
-
export type ClientSignatureVerifier =
|
|
269
|
-
(peerId: string, payload: Uint8Array, signature: string) => boolean;
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
/**
|
|
274
|
-
* Transaction engine interface.
|
|
275
|
-
* Pluggable engines implement this to process transaction statements.
|
|
276
|
-
*
|
|
277
|
-
* Engines are responsible for:
|
|
278
|
-
* 1. Parsing the engine-specific statements
|
|
279
|
-
* 2. Executing/re-executing to produce actions
|
|
280
|
-
* 3. Returning the resulting actions per collection
|
|
281
|
-
*
|
|
282
|
-
* CONTRACT — an engine must never cause the same action to be applied twice. The
|
|
283
|
-
* caller (a {@link TransactionSession} on the no-pre-supplied-actions branch, or a
|
|
284
|
-
* {@link TransactionCoordinator} in `execute()`) applies whatever non-empty
|
|
285
|
-
* `CollectionActions[]` this method RETURNS. Therefore `execute()` must satisfy
|
|
286
|
-
* exactly ONE of:
|
|
287
|
-
*
|
|
288
|
-
* (a) PURE TRANSLATOR (preferred; how {@link ActionsEngine} works) — parse the
|
|
289
|
-
* statements, RETURN the actions, and do NOT apply them / do NOT call
|
|
290
|
-
* `coordinator.applyActions` / do NOT mutate any collection state. The caller
|
|
291
|
-
* applies them exactly once.
|
|
292
|
-
*
|
|
293
|
-
* (b) SIDE-EFFECT APPLY — apply the actions itself while translating (e.g. the
|
|
294
|
-
* Quereus vtab path stages rows into the coordinator during `db.exec`) and then
|
|
295
|
-
* RETURN an EMPTY actions array, so the caller re-applies nothing.
|
|
296
|
-
*
|
|
297
|
-
* An engine that BOTH applies as a side effect AND returns those same actions
|
|
298
|
-
* double-applies (the caller re-applies the returned actions). Additionally, a
|
|
299
|
-
* side-effecting engine used for validation must apply only to the validator's
|
|
300
|
-
* ISOLATED coordinator — applying to the main coordinator leaks into the validating
|
|
301
|
-
* node's live state.
|
|
302
|
-
*/
|
|
303
|
-
export interface ITransactionEngine {
|
|
304
|
-
/**
|
|
305
|
-
* Stable identifier for this engine.
|
|
306
|
-
*
|
|
307
|
-
* This is the value stamped into {@link TransactionStamp.engineId} when a
|
|
308
|
-
* {@link TransactionSession} builds a transaction, and the key a
|
|
309
|
-
* {@link TransactionValidator} resolves the engine by. It MUST match the key the
|
|
310
|
-
* engine is registered under in the validator's `engines` map — otherwise a
|
|
311
|
-
* validating node rejects the transaction as `Unknown engine: <id>` before it
|
|
312
|
-
* ever re-executes.
|
|
313
|
-
*/
|
|
314
|
-
readonly id: string;
|
|
315
|
-
|
|
316
|
-
/**
|
|
317
|
-
* Process a transaction statements to produce actions.
|
|
318
|
-
*
|
|
319
|
-
* Used both for:
|
|
320
|
-
* - Initial execution (client creating transaction)
|
|
321
|
-
* - Re-execution (validators verifying transaction)
|
|
322
|
-
*
|
|
323
|
-
* @param transaction - The transaction to process
|
|
324
|
-
* @returns The resulting actions from execution
|
|
325
|
-
*/
|
|
326
|
-
execute(transaction: Transaction): Promise<ExecutionResult>;
|
|
327
|
-
}
|
|
328
|
-
|
|
329
|
-
/**
|
|
330
|
-
* Result of transaction execution.
|
|
331
|
-
*/
|
|
332
|
-
export type ExecutionResult = {
|
|
333
|
-
/** Whether execution succeeded */
|
|
334
|
-
success: boolean;
|
|
335
|
-
/** Actions produced by executing the transaction */
|
|
336
|
-
actions?: CollectionActions[];
|
|
337
|
-
/** Results from executing actions (e.g., return values from reads) */
|
|
338
|
-
results?: Map<CollectionId, any[]>;
|
|
339
|
-
/** Error message if execution failed */
|
|
340
|
-
error?: string;
|
|
341
|
-
/**
|
|
342
|
-
* On a PARTIAL multi-collection commit failure, the collections that DID durably
|
|
343
|
-
* commit through consensus before the failure (and thus CANNOT be rolled back —
|
|
344
|
-
* reconciliation is required). Absent/empty means nothing durably committed, so
|
|
345
|
-
* the caller may treat the failure as a clean abort — including calling
|
|
346
|
-
* `coordinator.rollback(stampId)`, which is still a valid and complete recovery there.
|
|
347
|
-
*
|
|
348
|
-
* When this IS present, the coordinator has already given the committed collections
|
|
349
|
-
* the success-path local treatment and restored the failed ones to their pre-staging
|
|
350
|
-
* state, and has DROPPED the transaction's rollback tracking — so
|
|
351
|
-
* `coordinator.rollback(stampId)` is a deliberate no-op rather than a rewind that
|
|
352
|
-
* would corrupt the collections that did commit. Reconciliation means driving a NEW
|
|
353
|
-
* transaction naming only the failed collections; re-driving THIS transaction through
|
|
354
|
-
* `execute()` would re-stage and re-apply the committed half a second time.
|
|
355
|
-
*
|
|
356
|
-
* See {@link CoordinatorPartialCommitError} for the session-mode (commit) analog.
|
|
357
|
-
*/
|
|
358
|
-
committedCollections?: CollectionId[];
|
|
359
|
-
/** On a partial multi-collection commit failure, the collections that failed to commit. */
|
|
360
|
-
failedCollections?: CollectionId[];
|
|
361
|
-
};
|
|
362
|
-
|
|
363
|
-
/**
|
|
364
|
-
* Actions for a specific collection resulting from transaction execution.
|
|
365
|
-
*/
|
|
366
|
-
export type CollectionActions = {
|
|
367
|
-
/** Collection identifier */
|
|
368
|
-
collectionId: string;
|
|
369
|
-
/** Actions to apply to this collection */
|
|
370
|
-
actions: unknown[];
|
|
371
|
-
};
|
|
372
|
-
|
|
373
|
-
/**
|
|
374
|
-
* Helper to create an actions-based transaction statements array.
|
|
375
|
-
* Each CollectionActions becomes a separate JSON-encoded statement.
|
|
376
|
-
*/
|
|
377
|
-
export function createActionsStatements(collections: CollectionActions[]): string[] {
|
|
378
|
-
return collections.map(c => JSON.stringify(c));
|
|
379
|
-
}
|
|
380
|
-
|
|
381
|
-
/**
|
|
382
|
-
* Statement format for the actions engine (array of CollectionActions).
|
|
383
|
-
* @deprecated Use CollectionActions[] directly
|
|
384
|
-
*/
|
|
385
|
-
export type ActionsStatement = {
|
|
386
|
-
collections: CollectionActions[];
|
|
387
|
-
};
|
|
388
|
-
|
|
389
|
-
/**
|
|
390
|
-
* Result of transaction validation.
|
|
391
|
-
*/
|
|
392
|
-
export type ValidationResult = {
|
|
393
|
-
/** Whether validation succeeded */
|
|
394
|
-
valid: boolean;
|
|
395
|
-
/** Reason for validation failure (if valid=false) */
|
|
396
|
-
reason?: string;
|
|
397
|
-
/** The operations hash computed during validation (for debugging) */
|
|
398
|
-
computedHash?: string;
|
|
399
|
-
};
|
|
400
|
-
|
|
401
|
-
/**
|
|
402
|
-
* Transaction validator interface.
|
|
403
|
-
* Pluggable validators implement this to verify transaction integrity.
|
|
404
|
-
*
|
|
405
|
-
* Validators are invoked when a node receives a PendRequest carrying a `validation`
|
|
406
|
-
* payload (the transaction plus its operations hash). They re-execute the transaction
|
|
407
|
-
* and verify the operations match. A throw out of {@link validate} is treated by
|
|
408
|
-
* callers as a rejection ("validator-fault: …"), never as an approval or an abstain.
|
|
409
|
-
*/
|
|
410
|
-
export interface ITransactionValidator {
|
|
411
|
-
/**
|
|
412
|
-
* Validate a transaction by re-executing and comparing operations hash.
|
|
413
|
-
*
|
|
414
|
-
* Validation steps (see TransactionValidator.validate for the authoritative order):
|
|
415
|
-
* 0.0. Verify stamp.id is the true hash of the stamp fields (integrity — runs first,
|
|
416
|
-
* since every later step trusts a stamp field)
|
|
417
|
-
* 0. Verify the stamp has not expired
|
|
418
|
-
* 0.5. Verify the client signature (only if a signature verifier is wired)
|
|
419
|
-
* 1. Verify stamp.engineId matches a known engine
|
|
420
|
-
* 2. Verify stamp.schemaHash matches local schema
|
|
421
|
-
* 3. Verify read dependencies (no stale reads)
|
|
422
|
-
* 4. Re-execute transaction.statements through engine (isolated state)
|
|
423
|
-
* 5. Collect operations from re-execution
|
|
424
|
-
* 6. Compute hash of operations
|
|
425
|
-
* 7. Compare with sender's operationsHash
|
|
426
|
-
*
|
|
427
|
-
* @param transaction - The transaction to validate
|
|
428
|
-
* @param operationsHash - The hash to compare against
|
|
429
|
-
* @returns Validation result
|
|
430
|
-
*/
|
|
431
|
-
validate(transaction: Transaction, operationsHash: string): Promise<ValidationResult>;
|
|
432
|
-
|
|
433
|
-
/**
|
|
434
|
-
* Get the schema hash for a given engine.
|
|
435
|
-
* Used to verify the sender's schema matches local schema.
|
|
436
|
-
*
|
|
437
|
-
* @param engineId - The engine identifier
|
|
438
|
-
* @returns The schema hash, or undefined if engine not found
|
|
439
|
-
*/
|
|
440
|
-
getSchemaHash(engineId: string): Promise<string | undefined>;
|
|
441
|
-
}
|
|
442
|
-
|
|
1
|
+
import { randomBytes } from "@noble/hashes/utils.js";
|
|
2
|
+
import { toString as uint8ArrayToString } from "uint8arrays/to-string";
|
|
3
|
+
import type { BlockId } from "../blocks/index.js";
|
|
4
|
+
import type { CollectionId } from "../collection/index.js";
|
|
5
|
+
import { hashString } from "../utility/hash-string.js";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Transaction Stamp: Created at BEGIN, stable throughout transaction lifecycle.
|
|
9
|
+
*
|
|
10
|
+
* The stamp contains metadata about the transaction's origin and context.
|
|
11
|
+
* The id is computed as a hash of these fields.
|
|
12
|
+
*/
|
|
13
|
+
export type TransactionStamp = {
|
|
14
|
+
/** Peer that initiated the transaction */
|
|
15
|
+
peerId: string;
|
|
16
|
+
|
|
17
|
+
/** When transaction started (milliseconds since epoch) */
|
|
18
|
+
timestamp: number;
|
|
19
|
+
|
|
20
|
+
/** Hash of schema version(s) for validation */
|
|
21
|
+
schemaHash: string;
|
|
22
|
+
|
|
23
|
+
/** Which engine (e.g., 'quereus@0.5.3', 'actions@1.0.0') */
|
|
24
|
+
engineId: string;
|
|
25
|
+
|
|
26
|
+
/** Absolute ms epoch after which transaction is invalid */
|
|
27
|
+
expiration: number;
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Random per-transaction nonce, folded into {@link TransactionStamp.id}.
|
|
31
|
+
*
|
|
32
|
+
* Anti-replay for read-free transactions: a transaction with no reads has nothing
|
|
33
|
+
* binding it to a point in history beyond {@link expiration}, so without this a
|
|
34
|
+
* captured signed read-free transaction could be re-submitted within the TTL window.
|
|
35
|
+
* The nonce makes two otherwise-identical transactions from the same peer at the
|
|
36
|
+
* same millisecond produce different ids (hence different signed bytes).
|
|
37
|
+
*/
|
|
38
|
+
nonce: string;
|
|
39
|
+
|
|
40
|
+
/** Hash of the stamp fields (computed) - stable identifier throughout transaction */
|
|
41
|
+
id: string;
|
|
42
|
+
};
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Transaction: Finalized at COMMIT with complete statement history.
|
|
46
|
+
*
|
|
47
|
+
* Transactions span multiple collections and use pluggable engines for interpreting the statements.
|
|
48
|
+
* The engine re-executes the statements to verify the resulting operations match what was proposed.
|
|
49
|
+
*/
|
|
50
|
+
export type Transaction = {
|
|
51
|
+
/** The transaction stamp (includes stable id) */
|
|
52
|
+
stamp: TransactionStamp;
|
|
53
|
+
|
|
54
|
+
/** Engine-specific statements (for replay/validation)
|
|
55
|
+
* Array of statements executed during the transaction.
|
|
56
|
+
* - For Quereus: SQL statements
|
|
57
|
+
* - For ActionsEngine: JSON-encoded actions
|
|
58
|
+
*/
|
|
59
|
+
statements: string[];
|
|
60
|
+
|
|
61
|
+
/** Read dependencies for optimistic concurrency control */
|
|
62
|
+
reads: ReadDependency[];
|
|
63
|
+
|
|
64
|
+
/** Transaction identifier (hash of stamp.id + statements + reads)
|
|
65
|
+
* Final transaction identity, used in logs
|
|
66
|
+
*/
|
|
67
|
+
id: string;
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Optional client signature (base64url) over {@link clientSignaturePayload}
|
|
71
|
+
* `(stamp.id, statements, reads)`, produced at commit by an injected
|
|
72
|
+
* {@link TransactionSigner}.
|
|
73
|
+
*
|
|
74
|
+
* A node that wires a {@link ClientSignatureVerifier} into its
|
|
75
|
+
* {@link TransactionValidator} verifies this at pend; where no verifier is wired,
|
|
76
|
+
* unsigned transactions are still accepted (migration / single-node-dev posture).
|
|
77
|
+
* Plain field on the transaction, so it rides along through serialization/persistence
|
|
78
|
+
* for later recovery-time re-verification.
|
|
79
|
+
*
|
|
80
|
+
* NOTE: preservation is verified only through JSON round-trip and an in-memory session commit —
|
|
81
|
+
* NOT yet through the db-p2p cluster-repo on-disk transaction-log serialization. No recovery
|
|
82
|
+
* reader exists today; when one lands, confirm this field survives that path so `verifyPeerSig`
|
|
83
|
+
* can re-run at recovery time.
|
|
84
|
+
*/
|
|
85
|
+
signature?: string;
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Aged, advisory retry priority (default 0 when absent). Rises by one per failed retry
|
|
89
|
+
* attempt (attempt-count-derived — deterministic, no wall clock, clock-skew-free) and is
|
|
90
|
+
* capped at {@link MaxPriority}. A cluster member uses it ONLY as the first tiebreak in a
|
|
91
|
+
* concurrent race between two simultaneously-pending conflicting transactions
|
|
92
|
+
* (`resolveRace`), so a transaction that keeps losing races eventually out-ranks fresh
|
|
93
|
+
* (priority-0) rivals instead of losing at random forever.
|
|
94
|
+
*
|
|
95
|
+
* FAIRNESS-ONLY — MUST NOT influence validity, the operations hash, stale-read checks, the
|
|
96
|
+
* transaction id, or the client signature. It is deliberately excluded from
|
|
97
|
+
* {@link createTransactionId} and {@link clientSignaturePayload} so two attempts of the same
|
|
98
|
+
* logical transaction (differing only in priority) keep the same id and signature; folding it
|
|
99
|
+
* into either would churn identity/anti-replay on every retry. It rides inside the signed
|
|
100
|
+
* cluster `message` (via the pend operation), so it is integrity-protected in transit — a
|
|
101
|
+
* relaying peer cannot strip or inflate it without invalidating the message hash — but the
|
|
102
|
+
* originating coordinator can still self-assert it (a fairness concern, not a safety one; see
|
|
103
|
+
* `docs/correctness.md` Theorem 9).
|
|
104
|
+
*/
|
|
105
|
+
priority?: number;
|
|
106
|
+
};
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Read dependency for optimistic concurrency control.
|
|
110
|
+
* Tracks which block revisions were read during transaction execution.
|
|
111
|
+
*/
|
|
112
|
+
export type ReadDependency = {
|
|
113
|
+
blockId: BlockId;
|
|
114
|
+
/** Expected revision number at time of read */
|
|
115
|
+
revision: number;
|
|
116
|
+
};
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Transaction reference embedded in actions.
|
|
120
|
+
* Just the transaction ID - full transaction can be looked up separately if needed.
|
|
121
|
+
*/
|
|
122
|
+
export type TransactionRef = string; // The transaction ID
|
|
123
|
+
|
|
124
|
+
/** Default transaction time-to-live in milliseconds (30 seconds). */
|
|
125
|
+
export const DEFAULT_TRANSACTION_TTL_MS = 30_000;
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* Upper bound on a transaction's aged {@link Transaction.priority}. Capping is essential: it
|
|
129
|
+
* bounds the fairness effect (an aged transaction cannot accrue unlimited advantage) and bounds
|
|
130
|
+
* the throughput cost (it can impose at most `MaxPriority` extra race-losses on rivals before it
|
|
131
|
+
* commits). Two transactions capped out at `MaxPriority` fall back to the existing approval-count /
|
|
132
|
+
* message-hash tiebreak, so behavior degrades gracefully to the pre-priority status quo.
|
|
133
|
+
*/
|
|
134
|
+
export const MaxPriority = 8;
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* Clamp an attempt-derived priority into `[0, MaxPriority]`. Total: any non-finite / negative
|
|
138
|
+
* input collapses to 0, anything above the cap to {@link MaxPriority}, and the result is floored
|
|
139
|
+
* to an integer. Used both where priority is *set* (the retry loops) and where it is *read* (a
|
|
140
|
+
* cluster member's `resolveRace`), so a Byzantine coordinator self-asserting an out-of-range value
|
|
141
|
+
* cannot exceed the cap.
|
|
142
|
+
*/
|
|
143
|
+
export function clampPriority(priority: number | undefined): number {
|
|
144
|
+
if (typeof priority !== 'number' || Number.isNaN(priority) || priority <= 0) {
|
|
145
|
+
return 0;
|
|
146
|
+
}
|
|
147
|
+
// A positive out-of-range value (including +Infinity, or a Byzantine self-asserted number) clamps
|
|
148
|
+
// DOWN to the cap; anything strictly inside the range is floored to an integer.
|
|
149
|
+
if (priority >= MaxPriority) {
|
|
150
|
+
return MaxPriority;
|
|
151
|
+
}
|
|
152
|
+
return Math.floor(priority);
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** Check whether a transaction stamp has expired. */
|
|
156
|
+
export function isTransactionExpired(stamp: TransactionStamp): boolean {
|
|
157
|
+
return Date.now() > stamp.expiration;
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** The stamp fields that feed the id hash (everything except the id itself). */
|
|
161
|
+
export type StampFields = Omit<TransactionStamp, 'id'>;
|
|
162
|
+
|
|
163
|
+
/**
|
|
164
|
+
* Compute the canonical stamp id from its fields. MUST match the historical field order
|
|
165
|
+
* (peerId, timestamp, schemaHash, engineId, expiration, nonce) — changing it churns every
|
|
166
|
+
* existing stamp id and client signature. Both {@link createTransactionStamp} and the
|
|
167
|
+
* validator's integrity check derive the id through this one function, so a validating node
|
|
168
|
+
* can re-derive the id and reject a stamp whose fields were tampered while id stayed fixed.
|
|
169
|
+
*/
|
|
170
|
+
export async function computeStampId(fields: StampFields): Promise<string> {
|
|
171
|
+
// Destructure and rebuild in fixed order rather than passing `fields` straight to
|
|
172
|
+
// JSON.stringify — this ignores any stray `id` (or extra) property a caller slipped in,
|
|
173
|
+
// so the serialized bytes depend on exactly the six fields and nothing else.
|
|
174
|
+
const { peerId, timestamp, schemaHash, engineId, expiration, nonce } = fields;
|
|
175
|
+
const stampData = JSON.stringify({ peerId, timestamp, schemaHash, engineId, expiration, nonce });
|
|
176
|
+
return `stamp:${await hashString(stampData)}`;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Create a transaction stamp with computed id.
|
|
181
|
+
* The id is a hash of the stamp fields (including expiration).
|
|
182
|
+
*/
|
|
183
|
+
export async function createTransactionStamp(
|
|
184
|
+
peerId: string,
|
|
185
|
+
timestamp: number,
|
|
186
|
+
schemaHash: string,
|
|
187
|
+
engineId: string,
|
|
188
|
+
ttlMs: number = DEFAULT_TRANSACTION_TTL_MS
|
|
189
|
+
): Promise<TransactionStamp> {
|
|
190
|
+
const expiration = timestamp + ttlMs;
|
|
191
|
+
// Cross-platform CSPRNG (Node + browser) via @noble/hashes — matches the rest of
|
|
192
|
+
// db-core (see collection.ts, transactor-source.ts). The nonce is folded into the
|
|
193
|
+
// id hash so two otherwise-identical stamps diverge.
|
|
194
|
+
const nonce = uint8ArrayToString(randomBytes(16), 'base64url');
|
|
195
|
+
const id = await computeStampId({ peerId, timestamp, schemaHash, engineId, expiration, nonce });
|
|
196
|
+
return { peerId, timestamp, schemaHash, engineId, expiration, nonce, id };
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* Create a transaction id from stamp id, statements, and reads.
|
|
201
|
+
* This is the final transaction identity used in logs.
|
|
202
|
+
*
|
|
203
|
+
* NOTE: reads are serialized in their given order here (non-canonical). This differs
|
|
204
|
+
* from {@link clientSignaturePayload}, which canonicalises reads before hashing. That is
|
|
205
|
+
* intentional for this ticket — the signature payload is self-contained — but the
|
|
206
|
+
* non-canonical ordering here is a separate hygiene concern (see
|
|
207
|
+
* design-consensus-hygiene-notes), NOT fixed here to avoid changing existing tx ids.
|
|
208
|
+
*
|
|
209
|
+
* NOTE: {@link Transaction.priority} is deliberately absent from this preimage — the id is a pure
|
|
210
|
+
* function of `(stampId, statements, reads)`, so two retry attempts that differ only in aged
|
|
211
|
+
* priority produce the SAME id. Do not add priority here.
|
|
212
|
+
*/
|
|
213
|
+
export async function createTransactionId(
|
|
214
|
+
stampId: string,
|
|
215
|
+
statements: string[],
|
|
216
|
+
reads: ReadDependency[]
|
|
217
|
+
): Promise<string> {
|
|
218
|
+
const txData = JSON.stringify({ stampId, statements, reads });
|
|
219
|
+
return `tx:${await hashString(txData)}`;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* Version prefix for the client-signature payload, so the signed form can evolve
|
|
224
|
+
* without ambiguity. Distinct from (but consistent in spirit with) the operations-hash
|
|
225
|
+
* canonical form — this covers transaction INPUTS, not operations.
|
|
226
|
+
*/
|
|
227
|
+
export const CLIENT_SIG_VERSION = 'txsig:v1';
|
|
228
|
+
|
|
229
|
+
/**
|
|
230
|
+
* Canonical bytes a client signs and a node verifies. Deterministic: reads are sorted
|
|
231
|
+
* (blockId, then revision); statements keep their sequential order.
|
|
232
|
+
*
|
|
233
|
+
* Binds three things at once: the CLIENT IDENTITY (via `stampId`, which hashes peerId +
|
|
234
|
+
* nonce), the EXACT statements, and the OCC read set (blockId + revision — "tail
|
|
235
|
+
* binding" for anti-replay). Both signer and verifier derive the bytes from
|
|
236
|
+
* `transaction.stamp.id` + `transaction.statements` + `transaction.reads` through this
|
|
237
|
+
* one function, so they reproduce identical bytes regardless of read ordering.
|
|
238
|
+
*
|
|
239
|
+
* NOTE: {@link Transaction.priority} is deliberately absent from the signed bytes — a retry that
|
|
240
|
+
* only bumps priority keeps the same signature, so anti-replay / OCC binding never churns. Do not
|
|
241
|
+
* add priority here.
|
|
242
|
+
*/
|
|
243
|
+
export function clientSignaturePayload(
|
|
244
|
+
stampId: string,
|
|
245
|
+
statements: readonly string[],
|
|
246
|
+
reads: readonly ReadDependency[]
|
|
247
|
+
): Uint8Array {
|
|
248
|
+
const canonicalReads = [...reads].sort(
|
|
249
|
+
(a, b) => a.blockId < b.blockId ? -1 : a.blockId > b.blockId ? 1
|
|
250
|
+
: a.revision - b.revision
|
|
251
|
+
);
|
|
252
|
+
const body = JSON.stringify({ stampId, statements, reads: canonicalReads });
|
|
253
|
+
return new TextEncoder().encode(`${CLIENT_SIG_VERSION}:${body}`);
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
/**
|
|
257
|
+
* Signs the canonical client-signature payload, returning base64url. Async to allow
|
|
258
|
+
* libp2p `PrivateKey.sign`; tests pass a synchronous fake.
|
|
259
|
+
*/
|
|
260
|
+
export type TransactionSigner = (payload: Uint8Array) => Promise<string> | string;
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* Returns true iff `signature` (base64url) is a valid client signature over `payload`
|
|
264
|
+
* for signer identity `peerId`. Total: returns false, never throws, on any malformed
|
|
265
|
+
* input. The p2p wiring backs this with verifyPeerSig + peerIdBindsPublicKey; tests
|
|
266
|
+
* pass a fake.
|
|
267
|
+
*/
|
|
268
|
+
export type ClientSignatureVerifier =
|
|
269
|
+
(peerId: string, payload: Uint8Array, signature: string) => boolean;
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
|
|
273
|
+
/**
|
|
274
|
+
* Transaction engine interface.
|
|
275
|
+
* Pluggable engines implement this to process transaction statements.
|
|
276
|
+
*
|
|
277
|
+
* Engines are responsible for:
|
|
278
|
+
* 1. Parsing the engine-specific statements
|
|
279
|
+
* 2. Executing/re-executing to produce actions
|
|
280
|
+
* 3. Returning the resulting actions per collection
|
|
281
|
+
*
|
|
282
|
+
* CONTRACT — an engine must never cause the same action to be applied twice. The
|
|
283
|
+
* caller (a {@link TransactionSession} on the no-pre-supplied-actions branch, or a
|
|
284
|
+
* {@link TransactionCoordinator} in `execute()`) applies whatever non-empty
|
|
285
|
+
* `CollectionActions[]` this method RETURNS. Therefore `execute()` must satisfy
|
|
286
|
+
* exactly ONE of:
|
|
287
|
+
*
|
|
288
|
+
* (a) PURE TRANSLATOR (preferred; how {@link ActionsEngine} works) — parse the
|
|
289
|
+
* statements, RETURN the actions, and do NOT apply them / do NOT call
|
|
290
|
+
* `coordinator.applyActions` / do NOT mutate any collection state. The caller
|
|
291
|
+
* applies them exactly once.
|
|
292
|
+
*
|
|
293
|
+
* (b) SIDE-EFFECT APPLY — apply the actions itself while translating (e.g. the
|
|
294
|
+
* Quereus vtab path stages rows into the coordinator during `db.exec`) and then
|
|
295
|
+
* RETURN an EMPTY actions array, so the caller re-applies nothing.
|
|
296
|
+
*
|
|
297
|
+
* An engine that BOTH applies as a side effect AND returns those same actions
|
|
298
|
+
* double-applies (the caller re-applies the returned actions). Additionally, a
|
|
299
|
+
* side-effecting engine used for validation must apply only to the validator's
|
|
300
|
+
* ISOLATED coordinator — applying to the main coordinator leaks into the validating
|
|
301
|
+
* node's live state.
|
|
302
|
+
*/
|
|
303
|
+
export interface ITransactionEngine {
|
|
304
|
+
/**
|
|
305
|
+
* Stable identifier for this engine.
|
|
306
|
+
*
|
|
307
|
+
* This is the value stamped into {@link TransactionStamp.engineId} when a
|
|
308
|
+
* {@link TransactionSession} builds a transaction, and the key a
|
|
309
|
+
* {@link TransactionValidator} resolves the engine by. It MUST match the key the
|
|
310
|
+
* engine is registered under in the validator's `engines` map — otherwise a
|
|
311
|
+
* validating node rejects the transaction as `Unknown engine: <id>` before it
|
|
312
|
+
* ever re-executes.
|
|
313
|
+
*/
|
|
314
|
+
readonly id: string;
|
|
315
|
+
|
|
316
|
+
/**
|
|
317
|
+
* Process a transaction statements to produce actions.
|
|
318
|
+
*
|
|
319
|
+
* Used both for:
|
|
320
|
+
* - Initial execution (client creating transaction)
|
|
321
|
+
* - Re-execution (validators verifying transaction)
|
|
322
|
+
*
|
|
323
|
+
* @param transaction - The transaction to process
|
|
324
|
+
* @returns The resulting actions from execution
|
|
325
|
+
*/
|
|
326
|
+
execute(transaction: Transaction): Promise<ExecutionResult>;
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
/**
|
|
330
|
+
* Result of transaction execution.
|
|
331
|
+
*/
|
|
332
|
+
export type ExecutionResult = {
|
|
333
|
+
/** Whether execution succeeded */
|
|
334
|
+
success: boolean;
|
|
335
|
+
/** Actions produced by executing the transaction */
|
|
336
|
+
actions?: CollectionActions[];
|
|
337
|
+
/** Results from executing actions (e.g., return values from reads) */
|
|
338
|
+
results?: Map<CollectionId, any[]>;
|
|
339
|
+
/** Error message if execution failed */
|
|
340
|
+
error?: string;
|
|
341
|
+
/**
|
|
342
|
+
* On a PARTIAL multi-collection commit failure, the collections that DID durably
|
|
343
|
+
* commit through consensus before the failure (and thus CANNOT be rolled back —
|
|
344
|
+
* reconciliation is required). Absent/empty means nothing durably committed, so
|
|
345
|
+
* the caller may treat the failure as a clean abort — including calling
|
|
346
|
+
* `coordinator.rollback(stampId)`, which is still a valid and complete recovery there.
|
|
347
|
+
*
|
|
348
|
+
* When this IS present, the coordinator has already given the committed collections
|
|
349
|
+
* the success-path local treatment and restored the failed ones to their pre-staging
|
|
350
|
+
* state, and has DROPPED the transaction's rollback tracking — so
|
|
351
|
+
* `coordinator.rollback(stampId)` is a deliberate no-op rather than a rewind that
|
|
352
|
+
* would corrupt the collections that did commit. Reconciliation means driving a NEW
|
|
353
|
+
* transaction naming only the failed collections; re-driving THIS transaction through
|
|
354
|
+
* `execute()` would re-stage and re-apply the committed half a second time.
|
|
355
|
+
*
|
|
356
|
+
* See {@link CoordinatorPartialCommitError} for the session-mode (commit) analog.
|
|
357
|
+
*/
|
|
358
|
+
committedCollections?: CollectionId[];
|
|
359
|
+
/** On a partial multi-collection commit failure, the collections that failed to commit. */
|
|
360
|
+
failedCollections?: CollectionId[];
|
|
361
|
+
};
|
|
362
|
+
|
|
363
|
+
/**
|
|
364
|
+
* Actions for a specific collection resulting from transaction execution.
|
|
365
|
+
*/
|
|
366
|
+
export type CollectionActions = {
|
|
367
|
+
/** Collection identifier */
|
|
368
|
+
collectionId: string;
|
|
369
|
+
/** Actions to apply to this collection */
|
|
370
|
+
actions: unknown[];
|
|
371
|
+
};
|
|
372
|
+
|
|
373
|
+
/**
|
|
374
|
+
* Helper to create an actions-based transaction statements array.
|
|
375
|
+
* Each CollectionActions becomes a separate JSON-encoded statement.
|
|
376
|
+
*/
|
|
377
|
+
export function createActionsStatements(collections: CollectionActions[]): string[] {
|
|
378
|
+
return collections.map(c => JSON.stringify(c));
|
|
379
|
+
}
|
|
380
|
+
|
|
381
|
+
/**
|
|
382
|
+
* Statement format for the actions engine (array of CollectionActions).
|
|
383
|
+
* @deprecated Use CollectionActions[] directly
|
|
384
|
+
*/
|
|
385
|
+
export type ActionsStatement = {
|
|
386
|
+
collections: CollectionActions[];
|
|
387
|
+
};
|
|
388
|
+
|
|
389
|
+
/**
|
|
390
|
+
* Result of transaction validation.
|
|
391
|
+
*/
|
|
392
|
+
export type ValidationResult = {
|
|
393
|
+
/** Whether validation succeeded */
|
|
394
|
+
valid: boolean;
|
|
395
|
+
/** Reason for validation failure (if valid=false) */
|
|
396
|
+
reason?: string;
|
|
397
|
+
/** The operations hash computed during validation (for debugging) */
|
|
398
|
+
computedHash?: string;
|
|
399
|
+
};
|
|
400
|
+
|
|
401
|
+
/**
|
|
402
|
+
* Transaction validator interface.
|
|
403
|
+
* Pluggable validators implement this to verify transaction integrity.
|
|
404
|
+
*
|
|
405
|
+
* Validators are invoked when a node receives a PendRequest carrying a `validation`
|
|
406
|
+
* payload (the transaction plus its operations hash). They re-execute the transaction
|
|
407
|
+
* and verify the operations match. A throw out of {@link validate} is treated by
|
|
408
|
+
* callers as a rejection ("validator-fault: …"), never as an approval or an abstain.
|
|
409
|
+
*/
|
|
410
|
+
export interface ITransactionValidator {
|
|
411
|
+
/**
|
|
412
|
+
* Validate a transaction by re-executing and comparing operations hash.
|
|
413
|
+
*
|
|
414
|
+
* Validation steps (see TransactionValidator.validate for the authoritative order):
|
|
415
|
+
* 0.0. Verify stamp.id is the true hash of the stamp fields (integrity — runs first,
|
|
416
|
+
* since every later step trusts a stamp field)
|
|
417
|
+
* 0. Verify the stamp has not expired
|
|
418
|
+
* 0.5. Verify the client signature (only if a signature verifier is wired)
|
|
419
|
+
* 1. Verify stamp.engineId matches a known engine
|
|
420
|
+
* 2. Verify stamp.schemaHash matches local schema
|
|
421
|
+
* 3. Verify read dependencies (no stale reads)
|
|
422
|
+
* 4. Re-execute transaction.statements through engine (isolated state)
|
|
423
|
+
* 5. Collect operations from re-execution
|
|
424
|
+
* 6. Compute hash of operations
|
|
425
|
+
* 7. Compare with sender's operationsHash
|
|
426
|
+
*
|
|
427
|
+
* @param transaction - The transaction to validate
|
|
428
|
+
* @param operationsHash - The hash to compare against
|
|
429
|
+
* @returns Validation result
|
|
430
|
+
*/
|
|
431
|
+
validate(transaction: Transaction, operationsHash: string): Promise<ValidationResult>;
|
|
432
|
+
|
|
433
|
+
/**
|
|
434
|
+
* Get the schema hash for a given engine.
|
|
435
|
+
* Used to verify the sender's schema matches local schema.
|
|
436
|
+
*
|
|
437
|
+
* @param engineId - The engine identifier
|
|
438
|
+
* @returns The schema hash, or undefined if engine not found
|
|
439
|
+
*/
|
|
440
|
+
getSchemaHash(engineId: string): Promise<string | undefined>;
|
|
441
|
+
}
|
|
442
|
+
|