@ocap/chain-node 1.32.0 → 1.32.1
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/esm/config-consistency.d.mts +59 -0
- package/esm/config-consistency.mjs +220 -0
- package/esm/env.mjs +1 -1
- package/esm/follower-config.d.mts +25 -0
- package/esm/follower-config.mjs +57 -0
- package/esm/index.d.mts +4 -2
- package/esm/index.mjs +4 -2
- package/esm/standalone-env.d.mts +54 -1
- package/esm/standalone-env.mjs +82 -1
- package/esm/start-chain-node.mjs +17 -12
- package/esm/types.d.mts +18 -1
- package/lib/config-consistency.cjs +227 -0
- package/lib/config-consistency.d.cts +59 -0
- package/lib/env.cjs +1 -1
- package/lib/follower-config.cjs +63 -0
- package/lib/follower-config.d.cts +25 -0
- package/lib/index.cjs +20 -1
- package/lib/index.d.cts +4 -2
- package/lib/standalone-env.cjs +89 -0
- package/lib/standalone-env.d.cts +54 -1
- package/lib/start-chain-node.cjs +19 -15
- package/lib/types.d.cts +18 -1
- package/package.json +16 -16
package/esm/types.d.mts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { FutureTimestampGuardConfig, TChainConfigCheckMode } from "./standalone-env.mjs";
|
|
1
2
|
import { CHAIN_NODE_TEST_HOOKS_TOKEN } from "./test-hooks-token.mjs";
|
|
2
3
|
import { AnchorPublisher, ICheckpointSignerWallet, IHotStuffRuntimeValidatorMember, ILedgerHealth, INodeRoleConfig, ISegmentArchiveStore, IWriterLeaseConfig, Ledger, LedgerConfig } from "@arcblock/ledger-core";
|
|
3
4
|
import { SqliteLedgerStorage } from "@arcblock/ledger-sqlite";
|
|
@@ -6,8 +7,8 @@ import OCAPResolver, { FollowerSyncService, HotStuffNodeRuntime, HotStuffNodeRun
|
|
|
6
7
|
import SqliteStateDB from "@ocap/statedb-sqlite";
|
|
7
8
|
import { SqliteTrustedStorage } from "@ocap/trusted-storage";
|
|
8
9
|
import express from "express";
|
|
9
|
-
import http from "node:http";
|
|
10
10
|
import { IChainConfig, IPipelineLogger, TFollowerSyncMode, TNodeWritePolicy } from "@ocap/types";
|
|
11
|
+
import http from "node:http";
|
|
11
12
|
|
|
12
13
|
//#region src/types.d.ts
|
|
13
14
|
type ILedgerLeaseOptions = IWriterLeaseConfig;
|
|
@@ -190,6 +191,22 @@ interface ChainProfileBase {
|
|
|
190
191
|
env?: Record<string, string | undefined>;
|
|
191
192
|
};
|
|
192
193
|
validateTokenConfig?: boolean;
|
|
194
|
+
/**
|
|
195
|
+
* Follower only (#1961): before any replay, compare the consensus config this node replays with against the
|
|
196
|
+
* upstream leader's `getConfig`. Default `off` (no request). `enforce` refuses to start on a difference.
|
|
197
|
+
*/
|
|
198
|
+
configCheck?: {
|
|
199
|
+
mode: TChainConfigCheckMode;
|
|
200
|
+
/** Stub upstream for tests; defaults to `getConfig` over `<upstreamChainUrl>/api/gql`. */
|
|
201
|
+
fetchUpstreamConfig?: (upstreamUrl: string) => Promise<unknown>;
|
|
202
|
+
/** `enforce`: how long an unavailable upstream is retried before deciding (default 60 s). */
|
|
203
|
+
retryDeadlineMs?: number;
|
|
204
|
+
};
|
|
205
|
+
/** Follower only (#1961): acceptance guards on replayed ledger entries. Default: none (today's behavior). */
|
|
206
|
+
replayGuards?: {
|
|
207
|
+
/** Refuse (retryably) entries at or after `activationSequence` whose timestamp is ahead of the local clock. */
|
|
208
|
+
futureTimestamp?: FutureTimestampGuardConfig;
|
|
209
|
+
};
|
|
193
210
|
logger?: IPipelineLogger;
|
|
194
211
|
configureApp?: (app: express.Express, ctx: ChainAppHookContext) => void | Promise<void>;
|
|
195
212
|
}
|
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
|
|
2
|
+
let _ocap_config = require("@ocap/config");
|
|
3
|
+
let _ocap_config_lib_default = require("@ocap/config/lib/default");
|
|
4
|
+
_ocap_config_lib_default = require_rolldown_runtime.__toESM(_ocap_config_lib_default);
|
|
5
|
+
let _ocap_util_lib_error = require("@ocap/util/lib/error");
|
|
6
|
+
|
|
7
|
+
//#region src/config-consistency.ts
|
|
8
|
+
/**
|
|
9
|
+
* Follower startup consistency check (#1961): before a follower replays anything it asks the upstream leader for
|
|
10
|
+
* its in-memory chain config (`getConfig`, core/resolver `getConfig()` returns `JSON.stringify(this.config)`) and
|
|
11
|
+
* compares every consensus-relevant key, both sides normalized with the same defaults. A follower that replays with
|
|
12
|
+
* a different config computes different state commits (e.g. `transaction.bridge.enabled` off rejects the first
|
|
13
|
+
* bridge reserve entry in `bridge-reserve-v2-gate.ts`) and halts; this check turns that into a clear startup error.
|
|
14
|
+
*
|
|
15
|
+
* Consensus-relevant keys (`CONSENSUS_CONFIG_KEYS`) are what the tx pipeline / replayer reads from `context.config`:
|
|
16
|
+
* - `chainId` every protocol (`tx.chainId` checks), replayer entry chain id
|
|
17
|
+
* - `mode` `Config.create` defaults (`ledger` zeroes fees and gas)
|
|
18
|
+
* - `moderator.address` moderator-only protocols (token / factory / rollup governance)
|
|
19
|
+
* - `token.address/symbol/decimal` official token, fee and stake units, reserved base symbol
|
|
20
|
+
* - `vaults` where fees, gas and slashed stake go (`txFee`, `txFees`, `txGas`, `slashedStake`)
|
|
21
|
+
* - `reservedSymbols` `create_token_factory` verification (compared as a case-insensitive set)
|
|
22
|
+
* - `transaction` the whole section: `txFee`, `txGas` (+ free-gas / burst knobs), `txStake`,
|
|
23
|
+
* `maxTxSize`, `maxAssetSize`, `maxListSize`, `maxMultisig`, `delegate`, `supportedTxs`,
|
|
24
|
+
* `multiSignV2Txs`, `maxWriteSetSize`, `security`, `bridge`, `rollupV1`, `exchangeV2`
|
|
25
|
+
* Not compared: `version` (software), `accounts` and token metadata/supply (genesis only: a follower never re-runs
|
|
26
|
+
* genesis, it starts from a verified snapshot), `moderator.pk` (protocols compare the address), `genesisTime`.
|
|
27
|
+
*/
|
|
28
|
+
const CONSENSUS_CONFIG_KEYS = [
|
|
29
|
+
"chainId",
|
|
30
|
+
"mode",
|
|
31
|
+
"moderator.address",
|
|
32
|
+
"token.address",
|
|
33
|
+
"token.symbol",
|
|
34
|
+
"token.decimal",
|
|
35
|
+
"vaults",
|
|
36
|
+
"reservedSymbols",
|
|
37
|
+
"transaction"
|
|
38
|
+
];
|
|
39
|
+
/** Protocol fallback of `transaction.exchangeV2.defaultTtlSeconds` (core/tx-protocols exchange-v2.ts). */
|
|
40
|
+
const DEFAULT_EXCHANGE_V2_TTL_SECONDS = 720 * 60 * 60;
|
|
41
|
+
const isPlainObject = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
|
|
42
|
+
/** JSON round trip: drops `undefined`, functions and frozen-ness, so both sides compare as the wire would. */
|
|
43
|
+
function toJsonValue(value) {
|
|
44
|
+
if (value === void 0) return void 0;
|
|
45
|
+
return JSON.parse(JSON.stringify(value));
|
|
46
|
+
}
|
|
47
|
+
function getPath(obj, dotted) {
|
|
48
|
+
let cur = obj;
|
|
49
|
+
for (const seg of dotted.split(".")) {
|
|
50
|
+
if (!isPlainObject(cur)) return void 0;
|
|
51
|
+
cur = cur[seg];
|
|
52
|
+
}
|
|
53
|
+
return cur;
|
|
54
|
+
}
|
|
55
|
+
function setPath(obj, dotted, value) {
|
|
56
|
+
const segs = dotted.split(".");
|
|
57
|
+
let cur = obj;
|
|
58
|
+
for (const seg of segs.slice(0, -1)) {
|
|
59
|
+
if (!isPlainObject(cur[seg])) cur[seg] = {};
|
|
60
|
+
cur = cur[seg];
|
|
61
|
+
}
|
|
62
|
+
cur[segs[segs.length - 1]] = value;
|
|
63
|
+
}
|
|
64
|
+
/** Fill only keys that are absent (`undefined`); present values, records and arrays are kept as they are. */
|
|
65
|
+
function fillAbsent(target, defaults) {
|
|
66
|
+
const out = { ...target };
|
|
67
|
+
for (const [k, v] of Object.entries(defaults)) if (out[k] === void 0) out[k] = toJsonValue(v);
|
|
68
|
+
return out;
|
|
69
|
+
}
|
|
70
|
+
function normalizeTransaction(raw) {
|
|
71
|
+
const tx = fillAbsent(isPlainObject(raw) ? toJsonValue(raw) : {}, _ocap_config_lib_default.default.transaction);
|
|
72
|
+
tx.txGas = fillAbsent(isPlainObject(tx.txGas) ? tx.txGas : {}, _ocap_config.defaultGasSecurityKnobs.txGas);
|
|
73
|
+
tx.security = fillAbsent(isPlainObject(tx.security) ? tx.security : {}, _ocap_config.defaultGasSecurityKnobs.security);
|
|
74
|
+
tx.bridge = { enabled: isPlainObject(tx.bridge) && tx.bridge.enabled === true };
|
|
75
|
+
tx.rollupV1 = { enabled: !(isPlainObject(tx.rollupV1) && tx.rollupV1.enabled === false) };
|
|
76
|
+
const exchangeV2 = isPlainObject(tx.exchangeV2) ? tx.exchangeV2 : {};
|
|
77
|
+
tx.exchangeV2 = {
|
|
78
|
+
...exchangeV2,
|
|
79
|
+
defaultTtlSeconds: typeof exchangeV2.defaultTtlSeconds === "number" ? exchangeV2.defaultTtlSeconds : DEFAULT_EXCHANGE_V2_TTL_SECONDS
|
|
80
|
+
};
|
|
81
|
+
return tx;
|
|
82
|
+
}
|
|
83
|
+
/** The consensus-relevant projection of a chain config, with defaults applied identically on both sides. */
|
|
84
|
+
function normalizeConsensusConfig(config) {
|
|
85
|
+
const out = {};
|
|
86
|
+
for (const key of CONSENSUS_CONFIG_KEYS) {
|
|
87
|
+
const value = toJsonValue(getPath(config, key));
|
|
88
|
+
switch (key) {
|
|
89
|
+
case "mode":
|
|
90
|
+
setPath(out, key, value === "ledger" ? "ledger" : "chain");
|
|
91
|
+
break;
|
|
92
|
+
case "token.address":
|
|
93
|
+
setPath(out, key, typeof value === "string" ? value : "");
|
|
94
|
+
break;
|
|
95
|
+
case "vaults":
|
|
96
|
+
setPath(out, key, isPlainObject(value) ? value : {});
|
|
97
|
+
break;
|
|
98
|
+
case "reservedSymbols":
|
|
99
|
+
setPath(out, key, Array.from(new Set((Array.isArray(value) ? value : []).map((s) => String(s ?? "").trim().toUpperCase()).filter(Boolean))).sort());
|
|
100
|
+
break;
|
|
101
|
+
case "transaction":
|
|
102
|
+
setPath(out, key, normalizeTransaction(value));
|
|
103
|
+
break;
|
|
104
|
+
default: setPath(out, key, value === void 0 ? null : value);
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
return out;
|
|
108
|
+
}
|
|
109
|
+
function collectDiff(local, upstream, prefix, out) {
|
|
110
|
+
if (isPlainObject(local) && isPlainObject(upstream)) {
|
|
111
|
+
const keys = Array.from(new Set([...Object.keys(local), ...Object.keys(upstream)])).sort();
|
|
112
|
+
for (const k of keys) collectDiff(local[k], upstream[k], prefix ? `${prefix}.${k}` : k, out);
|
|
113
|
+
return;
|
|
114
|
+
}
|
|
115
|
+
if (JSON.stringify(local) !== JSON.stringify(upstream)) out.push({
|
|
116
|
+
path: prefix,
|
|
117
|
+
local: local === void 0 ? null : local,
|
|
118
|
+
upstream: upstream === void 0 ? null : upstream
|
|
119
|
+
});
|
|
120
|
+
}
|
|
121
|
+
/** Differences between two configs' consensus projections, by dotted path (arrays compare as a whole). */
|
|
122
|
+
function diffConsensusConfig(local, upstream) {
|
|
123
|
+
const out = [];
|
|
124
|
+
collectDiff(normalizeConsensusConfig(local), normalizeConsensusConfig(upstream), "", out);
|
|
125
|
+
return out;
|
|
126
|
+
}
|
|
127
|
+
const MAX_CONFIG_RESPONSE_BYTES = 8 * 1024 * 1024;
|
|
128
|
+
const GET_CONFIG_QUERY = "{ getConfig { code config } }";
|
|
129
|
+
/** POST `{ getConfig }` to `<upstreamUrl>/api/gql` and return the parsed in-memory config of the upstream. */
|
|
130
|
+
async function fetchUpstreamChainConfig(upstreamUrl, { fetchImpl = fetch, timeoutMs = 1e4 } = {}) {
|
|
131
|
+
const url = `${String(upstreamUrl).trim().replace(/\/+$/, "")}/api/gql`;
|
|
132
|
+
const res = await fetchImpl(url, {
|
|
133
|
+
method: "POST",
|
|
134
|
+
headers: {
|
|
135
|
+
"content-type": "application/json",
|
|
136
|
+
accept: "application/json"
|
|
137
|
+
},
|
|
138
|
+
body: JSON.stringify({ query: GET_CONFIG_QUERY }),
|
|
139
|
+
redirect: "error",
|
|
140
|
+
signal: AbortSignal.timeout(timeoutMs)
|
|
141
|
+
});
|
|
142
|
+
const text = await res.text();
|
|
143
|
+
if (!res.ok) throw new Error(`getConfig from ${url} failed: HTTP ${res.status}`);
|
|
144
|
+
if (text.length > MAX_CONFIG_RESPONSE_BYTES) throw new Error(`getConfig from ${url} failed: response larger than ${MAX_CONFIG_RESPONSE_BYTES} bytes`);
|
|
145
|
+
const body = JSON.parse(text);
|
|
146
|
+
if (body.errors?.length) throw new Error(`getConfig from ${url} failed: ${body.errors.map((e) => e.message).join("; ")}`);
|
|
147
|
+
const raw = body.data?.getConfig?.config;
|
|
148
|
+
if (typeof raw !== "string" || !raw) throw new Error(`getConfig from ${url} failed: no config in the response (code=${body.data?.getConfig?.code})`);
|
|
149
|
+
return assertUpstreamConfigShape(JSON.parse(raw), url);
|
|
150
|
+
}
|
|
151
|
+
/** A response that is not a chain config is a bad body ("unavailable"), never a definite mismatch. */
|
|
152
|
+
function assertUpstreamConfigShape(parsed, source) {
|
|
153
|
+
if (!isPlainObject(parsed)) throw new Error(`getConfig from ${source} failed: config is not an object`);
|
|
154
|
+
if (typeof parsed.chainId !== "string" || !parsed.chainId.trim() || !isPlainObject(parsed.transaction)) throw new Error(`getConfig from ${source} failed: config has no chainId / transaction section`);
|
|
155
|
+
return parsed;
|
|
156
|
+
}
|
|
157
|
+
const formatValue = (v) => {
|
|
158
|
+
const s = JSON.stringify(v);
|
|
159
|
+
return s.length > 160 ? `${s.slice(0, 157)}...` : s;
|
|
160
|
+
};
|
|
161
|
+
function formatConfigDifferences(diff) {
|
|
162
|
+
return diff.map((d) => `${d.path} (local=${formatValue(d.local)}, upstream=${formatValue(d.upstream)})`).join("; ");
|
|
163
|
+
}
|
|
164
|
+
/**
|
|
165
|
+
* Compare the follower's replay config with the upstream leader's. `off`: no request. `warn`: one attempt, log
|
|
166
|
+
* any difference or failure and continue. `enforce`: a definite difference throws `CHAIN_CONFIG_MISMATCH` (lists
|
|
167
|
+
* every differing key). An unavailable upstream (down, HTTP error such as 429, bad body) is retried with backoff
|
|
168
|
+
* until `retryDeadlineMs`; then a node with existing local state starts with a warning, and only a fresh bootstrap
|
|
169
|
+
* throws `CHAIN_CONFIG_CHECK_UNAVAILABLE`.
|
|
170
|
+
*/
|
|
171
|
+
async function verifyFollowerConfigAgainstUpstream(opts) {
|
|
172
|
+
if (opts.mode === "off") return {
|
|
173
|
+
status: "skipped",
|
|
174
|
+
diff: []
|
|
175
|
+
};
|
|
176
|
+
const enforce = opts.mode === "enforce";
|
|
177
|
+
const now = opts.now ?? (() => Date.now());
|
|
178
|
+
const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
|
|
179
|
+
const unavailable = (reason) => {
|
|
180
|
+
const message$1 = `Follower config check (CHAIN_CONFIG_CHECK=${opts.mode}) could not read the upstream config: ${reason}`;
|
|
181
|
+
if (enforce && !opts.hasLocalState) throw new _ocap_util_lib_error.CustomError("CHAIN_CONFIG_CHECK_UNAVAILABLE", `${message$1}; refusing to start a fresh bootstrap before replay`);
|
|
182
|
+
opts.logger.warn(`[chain-node] ${message$1}; starting without the check${enforce ? " (existing local state)" : ""}`);
|
|
183
|
+
return {
|
|
184
|
+
status: "unavailable",
|
|
185
|
+
diff: []
|
|
186
|
+
};
|
|
187
|
+
};
|
|
188
|
+
const upstreamUrl = String(opts.upstreamUrl ?? "").trim();
|
|
189
|
+
if (!upstreamUrl) return unavailable("no upstream URL (UPSTREAM_CHAIN_URL) is configured");
|
|
190
|
+
const fetchConfig = opts.fetchUpstreamConfig ?? ((u) => fetchUpstreamChainConfig(u));
|
|
191
|
+
const deadline = now() + Math.max(0, opts.retryDeadlineMs ?? 6e4);
|
|
192
|
+
const maxDelay = Math.max(0, opts.retryMaxDelayMs ?? 1e4);
|
|
193
|
+
let delay = Math.max(0, opts.retryDelayMs ?? 1e3);
|
|
194
|
+
let upstreamConfig = null;
|
|
195
|
+
while (upstreamConfig === null) try {
|
|
196
|
+
upstreamConfig = assertUpstreamConfigShape(await fetchConfig(upstreamUrl), upstreamUrl);
|
|
197
|
+
} catch (err) {
|
|
198
|
+
const reason = err instanceof Error ? err.message : String(err);
|
|
199
|
+
if (!enforce || now() + delay > deadline) return unavailable(reason);
|
|
200
|
+
opts.logger.warn(`[chain-node] follower config check: upstream unavailable (${reason}); retrying in ${delay} ms`);
|
|
201
|
+
await sleep(delay);
|
|
202
|
+
delay = Math.min(maxDelay, delay * 2);
|
|
203
|
+
}
|
|
204
|
+
const diff = diffConsensusConfig(opts.localConfig, upstreamConfig);
|
|
205
|
+
if (diff.length === 0) {
|
|
206
|
+
opts.logger.info(`[chain-node] follower consensus config matches upstream ${upstreamUrl}`);
|
|
207
|
+
return {
|
|
208
|
+
status: "match",
|
|
209
|
+
diff
|
|
210
|
+
};
|
|
211
|
+
}
|
|
212
|
+
const message = `Follower consensus config differs from upstream ${upstreamUrl} in ${diff.length} key(s): ${formatConfigDifferences(diff)}`;
|
|
213
|
+
if (enforce) throw new _ocap_util_lib_error.CustomError("CHAIN_CONFIG_MISMATCH", `${message}; refusing to start before replay (#1961)`);
|
|
214
|
+
opts.logger.warn(`[chain-node] ${message}`);
|
|
215
|
+
return {
|
|
216
|
+
status: "mismatch",
|
|
217
|
+
diff
|
|
218
|
+
};
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
//#endregion
|
|
222
|
+
exports.CONSENSUS_CONFIG_KEYS = CONSENSUS_CONFIG_KEYS;
|
|
223
|
+
exports.diffConsensusConfig = diffConsensusConfig;
|
|
224
|
+
exports.fetchUpstreamChainConfig = fetchUpstreamChainConfig;
|
|
225
|
+
exports.formatConfigDifferences = formatConfigDifferences;
|
|
226
|
+
exports.normalizeConsensusConfig = normalizeConsensusConfig;
|
|
227
|
+
exports.verifyFollowerConfigAgainstUpstream = verifyFollowerConfigAgainstUpstream;
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { TChainConfigCheckMode } from "./standalone-env.cjs";
|
|
2
|
+
import { IPipelineLogger } from "@ocap/types";
|
|
3
|
+
|
|
4
|
+
//#region src/config-consistency.d.ts
|
|
5
|
+
declare const CONSENSUS_CONFIG_KEYS: readonly ["chainId", "mode", "moderator.address", "token.address", "token.symbol", "token.decimal", "vaults", "reservedSymbols", "transaction"];
|
|
6
|
+
type Plain = Record<string, unknown>;
|
|
7
|
+
/** The consensus-relevant projection of a chain config, with defaults applied identically on both sides. */
|
|
8
|
+
declare function normalizeConsensusConfig(config: unknown): Plain;
|
|
9
|
+
interface ConfigDifference {
|
|
10
|
+
path: string;
|
|
11
|
+
local: unknown;
|
|
12
|
+
upstream: unknown;
|
|
13
|
+
}
|
|
14
|
+
/** Differences between two configs' consensus projections, by dotted path (arrays compare as a whole). */
|
|
15
|
+
declare function diffConsensusConfig(local: unknown, upstream: unknown): ConfigDifference[];
|
|
16
|
+
/** POST `{ getConfig }` to `<upstreamUrl>/api/gql` and return the parsed in-memory config of the upstream. */
|
|
17
|
+
declare function fetchUpstreamChainConfig(upstreamUrl: string, {
|
|
18
|
+
fetchImpl,
|
|
19
|
+
timeoutMs
|
|
20
|
+
}?: {
|
|
21
|
+
fetchImpl?: typeof fetch;
|
|
22
|
+
timeoutMs?: number;
|
|
23
|
+
}): Promise<unknown>;
|
|
24
|
+
declare function formatConfigDifferences(diff: ConfigDifference[]): string;
|
|
25
|
+
interface VerifyFollowerConfigOptions {
|
|
26
|
+
mode: TChainConfigCheckMode;
|
|
27
|
+
/** The config the follower will replay with (`resolver.config`). */
|
|
28
|
+
localConfig: unknown;
|
|
29
|
+
upstreamUrl: string | null | undefined;
|
|
30
|
+
/** Defaults to `fetchUpstreamChainConfig`; tests pass a stub upstream. */
|
|
31
|
+
fetchUpstreamConfig?: (upstreamUrl: string) => Promise<unknown>;
|
|
32
|
+
logger: Pick<IPipelineLogger, 'info' | 'warn'>;
|
|
33
|
+
/**
|
|
34
|
+
* The data dir already held this node's chain state before this start (not a fresh snapshot bootstrap). With
|
|
35
|
+
* `enforce`, an upstream that stays unavailable past the deadline is then a warning, not a refusal.
|
|
36
|
+
*/
|
|
37
|
+
hasLocalState?: boolean;
|
|
38
|
+
/** `enforce` only: keep retrying an unavailable upstream this long (default 60 s, CHAIN_CONFIG_CHECK_TIMEOUT_SEC). */
|
|
39
|
+
retryDeadlineMs?: number;
|
|
40
|
+
/** First backoff delay (default 1 s), doubled per attempt up to `retryMaxDelayMs` (default 10 s). */
|
|
41
|
+
retryDelayMs?: number;
|
|
42
|
+
retryMaxDelayMs?: number;
|
|
43
|
+
now?: () => number;
|
|
44
|
+
sleep?: (ms: number) => Promise<void>;
|
|
45
|
+
}
|
|
46
|
+
interface VerifyFollowerConfigResult {
|
|
47
|
+
status: 'skipped' | 'match' | 'mismatch' | 'unavailable';
|
|
48
|
+
diff: ConfigDifference[];
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Compare the follower's replay config with the upstream leader's. `off`: no request. `warn`: one attempt, log
|
|
52
|
+
* any difference or failure and continue. `enforce`: a definite difference throws `CHAIN_CONFIG_MISMATCH` (lists
|
|
53
|
+
* every differing key). An unavailable upstream (down, HTTP error such as 429, bad body) is retried with backoff
|
|
54
|
+
* until `retryDeadlineMs`; then a node with existing local state starts with a warning, and only a fresh bootstrap
|
|
55
|
+
* throws `CHAIN_CONFIG_CHECK_UNAVAILABLE`.
|
|
56
|
+
*/
|
|
57
|
+
declare function verifyFollowerConfigAgainstUpstream(opts: VerifyFollowerConfigOptions): Promise<VerifyFollowerConfigResult>;
|
|
58
|
+
//#endregion
|
|
59
|
+
export { CONSENSUS_CONFIG_KEYS, ConfigDifference, VerifyFollowerConfigOptions, VerifyFollowerConfigResult, diffConsensusConfig, fetchUpstreamChainConfig, formatConfigDifferences, normalizeConsensusConfig, verifyFollowerConfigAgainstUpstream };
|
package/lib/env.cjs
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
|
|
2
|
+
let _ocap_util_lib_error = require("@ocap/util/lib/error");
|
|
2
3
|
let _arcblock_ledger_core = require("@arcblock/ledger-core");
|
|
3
4
|
let _arcblock_ledger_sqlite = require("@arcblock/ledger-sqlite");
|
|
4
|
-
let _ocap_util_lib_error = require("@ocap/util/lib/error");
|
|
5
5
|
|
|
6
6
|
//#region src/env.ts
|
|
7
7
|
function parseOptionalPositiveInt(raw, label) {
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
|
|
2
|
+
let _ocap_config = require("@ocap/config");
|
|
3
|
+
_ocap_config = require_rolldown_runtime.__toESM(_ocap_config);
|
|
4
|
+
|
|
5
|
+
//#region src/follower-config.ts
|
|
6
|
+
/**
|
|
7
|
+
* How a follower obtains the chain config it replays with (#1961). Shared by `startChainNode` and the read-only
|
|
8
|
+
* `scripts/ops/chain-config-diff.mjs` dry-run, so the dry-run compares exactly what the node would replay with.
|
|
9
|
+
*/
|
|
10
|
+
const isPlainRecord = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
|
|
11
|
+
/**
|
|
12
|
+
* A profile config is only "complete" with its `transaction` section (#1961): a follower profile that lacks it
|
|
13
|
+
* would otherwise replay with whatever the code defaults are (e.g. bridge off) instead of the leader's switches.
|
|
14
|
+
*/
|
|
15
|
+
function isCompleteChainConfig(candidate) {
|
|
16
|
+
return Boolean(candidate && typeof candidate.chainId === "string" && candidate.chainId.trim() && candidate.moderator?.address && candidate.token?.symbol && candidate.vaults?.slashedStake && isPlainRecord(candidate.transaction));
|
|
17
|
+
}
|
|
18
|
+
/** Deep merge of plain objects (arrays and scalars of `overlay` replace); inputs are not mutated. */
|
|
19
|
+
function mergeTransactionOverlay(base, overlay) {
|
|
20
|
+
if (!isPlainRecord(overlay)) return overlay === void 0 ? base : overlay;
|
|
21
|
+
const out = isPlainRecord(base) ? { ...base } : {};
|
|
22
|
+
for (const [k, v] of Object.entries(overlay)) {
|
|
23
|
+
if (v === void 0) continue;
|
|
24
|
+
out[k] = mergeTransactionOverlay(out[k], v);
|
|
25
|
+
}
|
|
26
|
+
return out;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Keyless follower: the stored chain row (`statedb.chain`) plus the profile's `transaction` overlay. A keyless
|
|
30
|
+
* follower cannot rebuild the full config (no vault keys), but its profile may carry the leader's transaction
|
|
31
|
+
* variables from env (e.g. CHAIN_TX_BRIDGE_ENABLED): the stored row is not rewritten on a ledger-anchored leader
|
|
32
|
+
* restart, so it still holds the values of the last genesis/config write.
|
|
33
|
+
*/
|
|
34
|
+
function rehydrateFollowerChainConfig(storedChain, profileChainConfig) {
|
|
35
|
+
const storedChainPartial = storedChain;
|
|
36
|
+
const storedChainId = typeof storedChainPartial.chainId === "string" ? storedChainPartial.chainId.trim() : "";
|
|
37
|
+
const baseSymbol = storedChainPartial.token?.symbol || "TBA";
|
|
38
|
+
const reservedSymbols = Array.from(new Set([baseSymbol, ...storedChainPartial.reservedSymbols ?? []].map((s) => String(s || "").trim().toUpperCase()).filter(Boolean)));
|
|
39
|
+
const transactionOverlay = isPlainRecord(profileChainConfig?.transaction) ? profileChainConfig.transaction : void 0;
|
|
40
|
+
return _ocap_config.create({
|
|
41
|
+
...storedChain,
|
|
42
|
+
...storedChainId ? { chainId: storedChainId } : {},
|
|
43
|
+
...transactionOverlay ? { transaction: mergeTransactionOverlay(storedChainPartial.transaction, transactionOverlay) } : {},
|
|
44
|
+
reservedSymbols
|
|
45
|
+
});
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* The config a resolver actually runs with (`OCAPResolver` constructor): validated, with `token.address` set to the
|
|
49
|
+
* genesis token address. This is what the leader's `getConfig` returns and what the follower's replayer reads.
|
|
50
|
+
*/
|
|
51
|
+
function toResolverConfig(config) {
|
|
52
|
+
const validated = _ocap_config.validate(JSON.parse(JSON.stringify(config)));
|
|
53
|
+
const tokenItx = _ocap_config.genTokenItx(validated);
|
|
54
|
+
if (tokenItx) validated.token.address = tokenItx.address;
|
|
55
|
+
return validated;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
//#endregion
|
|
59
|
+
exports.isCompleteChainConfig = isCompleteChainConfig;
|
|
60
|
+
exports.isPlainRecord = isPlainRecord;
|
|
61
|
+
exports.mergeTransactionOverlay = mergeTransactionOverlay;
|
|
62
|
+
exports.rehydrateFollowerChainConfig = rehydrateFollowerChainConfig;
|
|
63
|
+
exports.toResolverConfig = toResolverConfig;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { IChainConfig } from "@ocap/types";
|
|
2
|
+
|
|
3
|
+
//#region src/follower-config.d.ts
|
|
4
|
+
declare const isPlainRecord: (v: unknown) => v is Record<string, unknown>;
|
|
5
|
+
/**
|
|
6
|
+
* A profile config is only "complete" with its `transaction` section (#1961): a follower profile that lacks it
|
|
7
|
+
* would otherwise replay with whatever the code defaults are (e.g. bridge off) instead of the leader's switches.
|
|
8
|
+
*/
|
|
9
|
+
declare function isCompleteChainConfig(candidate: Partial<IChainConfig> | undefined): candidate is IChainConfig;
|
|
10
|
+
/** Deep merge of plain objects (arrays and scalars of `overlay` replace); inputs are not mutated. */
|
|
11
|
+
declare function mergeTransactionOverlay(base: unknown, overlay: unknown): unknown;
|
|
12
|
+
/**
|
|
13
|
+
* Keyless follower: the stored chain row (`statedb.chain`) plus the profile's `transaction` overlay. A keyless
|
|
14
|
+
* follower cannot rebuild the full config (no vault keys), but its profile may carry the leader's transaction
|
|
15
|
+
* variables from env (e.g. CHAIN_TX_BRIDGE_ENABLED): the stored row is not rewritten on a ledger-anchored leader
|
|
16
|
+
* restart, so it still holds the values of the last genesis/config write.
|
|
17
|
+
*/
|
|
18
|
+
declare function rehydrateFollowerChainConfig(storedChain: unknown, profileChainConfig?: Partial<IChainConfig>): IChainConfig;
|
|
19
|
+
/**
|
|
20
|
+
* The config a resolver actually runs with (`OCAPResolver` constructor): validated, with `token.address` set to the
|
|
21
|
+
* genesis token address. This is what the leader's `getConfig` returns and what the follower's replayer reads.
|
|
22
|
+
*/
|
|
23
|
+
declare function toResolverConfig(config: IChainConfig): IChainConfig;
|
|
24
|
+
//#endregion
|
|
25
|
+
export { isCompleteChainConfig, isPlainRecord, mergeTransactionOverlay, rehydrateFollowerChainConfig, toResolverConfig };
|
package/lib/index.cjs
CHANGED
|
@@ -1,13 +1,32 @@
|
|
|
1
|
+
const require_config_consistency = require('./config-consistency.cjs');
|
|
1
2
|
const require_env = require('./env.cjs');
|
|
3
|
+
const require_follower_config = require('./follower-config.cjs');
|
|
2
4
|
const require_start_chain_node = require('./start-chain-node.cjs');
|
|
3
5
|
const require_standalone_env = require('./standalone-env.cjs');
|
|
4
6
|
|
|
5
7
|
exports.BLOCKLET_ENV_CHAIN_FALLBACKS = require_standalone_env.BLOCKLET_ENV_CHAIN_FALLBACKS;
|
|
8
|
+
exports.CONSENSUS_CONFIG_KEYS = require_config_consistency.CONSENSUS_CONFIG_KEYS;
|
|
9
|
+
exports.DEFAULT_CONFIG_CHECK_TIMEOUT_SECONDS = require_standalone_env.DEFAULT_CONFIG_CHECK_TIMEOUT_SECONDS;
|
|
10
|
+
exports.DEFAULT_FUTURE_TIMESTAMP_SKEW_SECONDS = require_standalone_env.DEFAULT_FUTURE_TIMESTAMP_SKEW_SECONDS;
|
|
6
11
|
exports.STANDALONE_ENV_MARKERS = require_standalone_env.STANDALONE_ENV_MARKERS;
|
|
12
|
+
exports.TRANSACTION_SWITCH_ENV = require_standalone_env.TRANSACTION_SWITCH_ENV;
|
|
13
|
+
exports.diffConsensusConfig = require_config_consistency.diffConsensusConfig;
|
|
14
|
+
exports.fetchUpstreamChainConfig = require_config_consistency.fetchUpstreamChainConfig;
|
|
7
15
|
exports.findBlockletEnvLeftovers = require_standalone_env.findBlockletEnvLeftovers;
|
|
8
16
|
exports.formatBlockletEnvLeftoversWarning = require_standalone_env.formatBlockletEnvLeftoversWarning;
|
|
17
|
+
exports.formatConfigDifferences = require_config_consistency.formatConfigDifferences;
|
|
9
18
|
exports.installProcessSignalHandlers = require_env.installProcessSignalHandlers;
|
|
19
|
+
exports.isCompleteChainConfig = require_follower_config.isCompleteChainConfig;
|
|
10
20
|
exports.leaseConfigFromEnv = require_env.leaseConfigFromEnv;
|
|
21
|
+
exports.normalizeConsensusConfig = require_config_consistency.normalizeConsensusConfig;
|
|
22
|
+
exports.parseNonNegativeNumberEnv = require_standalone_env.parseNonNegativeNumberEnv;
|
|
23
|
+
exports.rehydrateFollowerChainConfig = require_follower_config.rehydrateFollowerChainConfig;
|
|
24
|
+
exports.resolveConfigCheckModeFromEnv = require_standalone_env.resolveConfigCheckModeFromEnv;
|
|
25
|
+
exports.resolveConfigCheckTimeoutMsFromEnv = require_standalone_env.resolveConfigCheckTimeoutMsFromEnv;
|
|
26
|
+
exports.resolveFutureTimestampGuardFromEnv = require_standalone_env.resolveFutureTimestampGuardFromEnv;
|
|
27
|
+
exports.resolveTransactionSwitchesFromEnv = require_standalone_env.resolveTransactionSwitchesFromEnv;
|
|
11
28
|
exports.resolveTrustedSubject = require_standalone_env.resolveTrustedSubject;
|
|
12
29
|
exports.roleConfigFromEnv = require_env.roleConfigFromEnv;
|
|
13
|
-
exports.startChainNode = require_start_chain_node.startChainNode;
|
|
30
|
+
exports.startChainNode = require_start_chain_node.startChainNode;
|
|
31
|
+
exports.toResolverConfig = require_follower_config.toResolverConfig;
|
|
32
|
+
exports.verifyFollowerConfigAgainstUpstream = require_config_consistency.verifyFollowerConfigAgainstUpstream;
|
package/lib/index.d.cts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
|
+
import { BLOCKLET_ENV_CHAIN_FALLBACKS, BlockletEnvLeftovers, DEFAULT_CONFIG_CHECK_TIMEOUT_SECONDS, DEFAULT_FUTURE_TIMESTAMP_SKEW_SECONDS, FutureTimestampGuardConfig, STANDALONE_ENV_MARKERS, TChainConfigCheckMode, TRANSACTION_SWITCH_ENV, TransactionSwitches, findBlockletEnvLeftovers, formatBlockletEnvLeftoversWarning, parseNonNegativeNumberEnv, resolveConfigCheckModeFromEnv, resolveConfigCheckTimeoutMsFromEnv, resolveFutureTimestampGuardFromEnv, resolveTransactionSwitchesFromEnv, resolveTrustedSubject } from "./standalone-env.cjs";
|
|
2
|
+
import { CONSENSUS_CONFIG_KEYS, ConfigDifference, VerifyFollowerConfigOptions, VerifyFollowerConfigResult, diffConsensusConfig, fetchUpstreamChainConfig, formatConfigDifferences, normalizeConsensusConfig, verifyFollowerConfigAgainstUpstream } from "./config-consistency.cjs";
|
|
1
3
|
import { ChainAppHookContext, ChainNodeHandle, ChainNodeProfile, ChainNodeRoleConfig, ChainNodeSegmentPublisher, ChainNodeSignerConfig, ChainNodeTestHooks, ChainNodeTestHooksInput, ChainProfile, ChainProfileBase, FollowerRoleConfig, FollowerSyncTestController, FollowerUpstreamInterceptorContext, HotStuffValidatorRoleConfig, ILedgerHealthStatus, ILedgerLeaseOptions, PublicKeyOnlyValidatorSignerConfig, RunningChainNode, StartChainNodeOptions, TNodeRetentionMode, TrustedAccountConfig, ValidatorRoleConfig, ValidatorSignerConfig } from "./types.cjs";
|
|
2
4
|
import { InstallProcessSignalHandlersOptions, installProcessSignalHandlers, leaseConfigFromEnv, roleConfigFromEnv } from "./env.cjs";
|
|
5
|
+
import { isCompleteChainConfig, rehydrateFollowerChainConfig, toResolverConfig } from "./follower-config.cjs";
|
|
3
6
|
import { startChainNode } from "./start-chain-node.cjs";
|
|
4
|
-
|
|
5
|
-
export { BLOCKLET_ENV_CHAIN_FALLBACKS, type BlockletEnvLeftovers, type ChainAppHookContext, type ChainNodeHandle, type ChainNodeProfile, type ChainNodeRoleConfig, type ChainNodeSegmentPublisher, type ChainNodeSignerConfig, type ChainNodeTestHooks, type ChainNodeTestHooksInput, type ChainProfile, type ChainProfileBase, type FollowerRoleConfig, type FollowerSyncTestController, type FollowerUpstreamInterceptorContext, type HotStuffValidatorRoleConfig, type ILedgerHealthStatus, type ILedgerLeaseOptions, type InstallProcessSignalHandlersOptions, type PublicKeyOnlyValidatorSignerConfig, type RunningChainNode, STANDALONE_ENV_MARKERS, type StartChainNodeOptions, type TNodeRetentionMode, type TrustedAccountConfig, type ValidatorRoleConfig, type ValidatorSignerConfig, findBlockletEnvLeftovers, formatBlockletEnvLeftoversWarning, installProcessSignalHandlers, leaseConfigFromEnv, resolveTrustedSubject, roleConfigFromEnv, startChainNode };
|
|
7
|
+
export { BLOCKLET_ENV_CHAIN_FALLBACKS, type BlockletEnvLeftovers, CONSENSUS_CONFIG_KEYS, type ChainAppHookContext, type ChainNodeHandle, type ChainNodeProfile, type ChainNodeRoleConfig, type ChainNodeSegmentPublisher, type ChainNodeSignerConfig, type ChainNodeTestHooks, type ChainNodeTestHooksInput, type ChainProfile, type ChainProfileBase, type ConfigDifference, DEFAULT_CONFIG_CHECK_TIMEOUT_SECONDS, DEFAULT_FUTURE_TIMESTAMP_SKEW_SECONDS, type FollowerRoleConfig, type FollowerSyncTestController, type FollowerUpstreamInterceptorContext, type FutureTimestampGuardConfig, type HotStuffValidatorRoleConfig, type ILedgerHealthStatus, type ILedgerLeaseOptions, type InstallProcessSignalHandlersOptions, type PublicKeyOnlyValidatorSignerConfig, type RunningChainNode, STANDALONE_ENV_MARKERS, type StartChainNodeOptions, type TChainConfigCheckMode, type TNodeRetentionMode, TRANSACTION_SWITCH_ENV, type TransactionSwitches, type TrustedAccountConfig, type ValidatorRoleConfig, type ValidatorSignerConfig, type VerifyFollowerConfigOptions, type VerifyFollowerConfigResult, diffConsensusConfig, fetchUpstreamChainConfig, findBlockletEnvLeftovers, formatBlockletEnvLeftoversWarning, formatConfigDifferences, installProcessSignalHandlers, isCompleteChainConfig, leaseConfigFromEnv, normalizeConsensusConfig, parseNonNegativeNumberEnv, rehydrateFollowerChainConfig, resolveConfigCheckModeFromEnv, resolveConfigCheckTimeoutMsFromEnv, resolveFutureTimestampGuardFromEnv, resolveTransactionSwitchesFromEnv, resolveTrustedSubject, roleConfigFromEnv, startChainNode, toResolverConfig, verifyFollowerConfigAgainstUpstream };
|
package/lib/standalone-env.cjs
CHANGED
|
@@ -67,10 +67,99 @@ function formatBlockletEnvLeftoversWarning({ standaloneMarkers, leftovers, readB
|
|
|
67
67
|
const read = readByChain.length ? ` ${readByChain.join(", ")} still feed key/path fallbacks when the CHAIN_* equivalent is unset.` : "";
|
|
68
68
|
return `[chain] standalone env (${standaloneMarkers.join(", ")}) also carries Blocklet Server variables: ${leftovers.join(", ")}.${read} Remove them so CHAIN_* is the only source (docs/ops/chain-env-mapping.md, #1923)`;
|
|
69
69
|
}
|
|
70
|
+
/** Env names of the `transaction.*` master switches a chain app maps into its chain config. */
|
|
71
|
+
const TRANSACTION_SWITCH_ENV = {
|
|
72
|
+
bridge: "CHAIN_TX_BRIDGE_ENABLED",
|
|
73
|
+
rollupV1: "CHAIN_TX_ROLLUP_V1_ENABLED"
|
|
74
|
+
};
|
|
75
|
+
/** `1`/`true` -> true, `0`/`false` -> false, unset/blank -> undefined; anything else fails startup. */
|
|
76
|
+
function parseStrictBoolEnv(env, name) {
|
|
77
|
+
const raw = String(env[name] ?? "").trim().toLowerCase();
|
|
78
|
+
if (!raw) return void 0;
|
|
79
|
+
if (raw === "1" || raw === "true") return true;
|
|
80
|
+
if (raw === "0" || raw === "false") return false;
|
|
81
|
+
throw new Error(`Invalid ${name}="${env[name]}": expected 1/true or 0/false (or leave it empty for the default)`);
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* `transaction.bridge` / `transaction.rollupV1` from env. Only explicitly set switches are returned, so an env
|
|
85
|
+
* without them leaves the chain config exactly as before (bridge absent = disabled, rollupV1 absent = enabled).
|
|
86
|
+
*/
|
|
87
|
+
function resolveTransactionSwitchesFromEnv(env = process.env) {
|
|
88
|
+
const out = {};
|
|
89
|
+
const bridge = parseStrictBoolEnv(env, TRANSACTION_SWITCH_ENV.bridge);
|
|
90
|
+
if (bridge !== void 0) out.bridge = { enabled: bridge };
|
|
91
|
+
const rollupV1 = parseStrictBoolEnv(env, TRANSACTION_SWITCH_ENV.rollupV1);
|
|
92
|
+
if (rollupV1 !== void 0) out.rollupV1 = { enabled: rollupV1 };
|
|
93
|
+
return out;
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* `CHAIN_CONFIG_CHECK`: what a follower does with the startup comparison of its consensus config against the
|
|
97
|
+
* upstream leader's `getConfig` (`off` default: no request at all; `warn`: log differences and start; `enforce`:
|
|
98
|
+
* refuse to start on any difference or when the upstream cannot be asked).
|
|
99
|
+
*/
|
|
100
|
+
function resolveConfigCheckModeFromEnv(env = process.env) {
|
|
101
|
+
const raw = String(env.CHAIN_CONFIG_CHECK ?? "").trim().toLowerCase();
|
|
102
|
+
if (!raw) return "off";
|
|
103
|
+
if (raw === "off" || raw === "warn" || raw === "enforce") return raw;
|
|
104
|
+
throw new Error(`Invalid CHAIN_CONFIG_CHECK="${env.CHAIN_CONFIG_CHECK}": expected off, warn or enforce`);
|
|
105
|
+
}
|
|
106
|
+
const DEFAULT_CONFIG_CHECK_TIMEOUT_SECONDS = 60;
|
|
107
|
+
/**
|
|
108
|
+
* `CHAIN_CONFIG_CHECK_TIMEOUT_SEC` (non-negative integer seconds, default 60): how long `enforce` keeps retrying an
|
|
109
|
+
* unreachable / bad upstream before it decides (start with a warning on existing local state, refuse when fresh).
|
|
110
|
+
*/
|
|
111
|
+
function resolveConfigCheckTimeoutMsFromEnv(env = process.env) {
|
|
112
|
+
const raw = env.CHAIN_CONFIG_CHECK_TIMEOUT_SEC;
|
|
113
|
+
if (raw === void 0 || raw === "") return DEFAULT_CONFIG_CHECK_TIMEOUT_SECONDS * 1e3;
|
|
114
|
+
if (!/^(?:0|[1-9]\d*)$/.test(raw) || !Number.isSafeInteger(Number(raw) * 1e3)) throw new Error(`Invalid CHAIN_CONFIG_CHECK_TIMEOUT_SEC="${raw}": expected a non-negative integer (seconds)`);
|
|
115
|
+
return Number(raw) * 1e3;
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* A fee / gas env value (`CHAIN_GAS_PRICE`, `CREATE_*_TX_FEE`), parsed identically on leader and follower:
|
|
119
|
+
* unset or empty -> undefined (the caller's default / no overlay); otherwise a plain non-negative decimal
|
|
120
|
+
* (`integer`: digits only). Whitespace, NaN, negatives, exponents and hex fail startup instead of becoming `0`.
|
|
121
|
+
*/
|
|
122
|
+
function parseNonNegativeNumberEnv(env, name, { integer = false } = {}) {
|
|
123
|
+
const raw = env[name];
|
|
124
|
+
if (raw === void 0 || raw === "") return void 0;
|
|
125
|
+
const re = integer ? /^(?:0|[1-9]\d*)$/ : /^(?:0|[1-9]\d*)(?:\.\d+)?$/;
|
|
126
|
+
const value = Number(raw);
|
|
127
|
+
if (!re.test(raw) || !Number.isFinite(value) || integer && !Number.isSafeInteger(value)) throw new Error(`Invalid ${name}="${raw}": expected a non-negative ${integer ? "integer" : "number"} (or leave it empty)`);
|
|
128
|
+
return value;
|
|
129
|
+
}
|
|
130
|
+
/** Default clock skew a replayed entry's timestamp may be ahead of the local clock (#1961; #1965 owns the value). */
|
|
131
|
+
const DEFAULT_FUTURE_TIMESTAMP_SKEW_SECONDS = 300;
|
|
132
|
+
/**
|
|
133
|
+
* `LEDGER_FUTURE_TIMESTAMP_FROM_SEQ` (positive integer; unset = guard disabled, today's behavior) and
|
|
134
|
+
* `LEDGER_FUTURE_TIMESTAMP_SKEW_SEC` (non-negative integer seconds, default 300; ignored while the guard is off).
|
|
135
|
+
*/
|
|
136
|
+
function resolveFutureTimestampGuardFromEnv(env = process.env) {
|
|
137
|
+
const rawSeq = String(env.LEDGER_FUTURE_TIMESTAMP_FROM_SEQ ?? "").trim();
|
|
138
|
+
if (!rawSeq) return void 0;
|
|
139
|
+
if (!/^[1-9]\d*$/.test(rawSeq) || !Number.isSafeInteger(Number(rawSeq))) throw new Error(`Invalid LEDGER_FUTURE_TIMESTAMP_FROM_SEQ="${env.LEDGER_FUTURE_TIMESTAMP_FROM_SEQ}": expected a positive integer`);
|
|
140
|
+
const rawSkew = String(env.LEDGER_FUTURE_TIMESTAMP_SKEW_SEC ?? "").trim();
|
|
141
|
+
let skewSeconds = DEFAULT_FUTURE_TIMESTAMP_SKEW_SECONDS;
|
|
142
|
+
if (rawSkew) {
|
|
143
|
+
if (!/^(?:0|[1-9]\d*)$/.test(rawSkew) || !Number.isSafeInteger(Number(rawSkew) * 1e3)) throw new Error(`Invalid LEDGER_FUTURE_TIMESTAMP_SKEW_SEC="${env.LEDGER_FUTURE_TIMESTAMP_SKEW_SEC}": expected a non-negative integer`);
|
|
144
|
+
skewSeconds = Number(rawSkew);
|
|
145
|
+
}
|
|
146
|
+
return {
|
|
147
|
+
activationSequence: Number(rawSeq),
|
|
148
|
+
maxSkewMs: skewSeconds * 1e3
|
|
149
|
+
};
|
|
150
|
+
}
|
|
70
151
|
|
|
71
152
|
//#endregion
|
|
72
153
|
exports.BLOCKLET_ENV_CHAIN_FALLBACKS = BLOCKLET_ENV_CHAIN_FALLBACKS;
|
|
154
|
+
exports.DEFAULT_CONFIG_CHECK_TIMEOUT_SECONDS = DEFAULT_CONFIG_CHECK_TIMEOUT_SECONDS;
|
|
155
|
+
exports.DEFAULT_FUTURE_TIMESTAMP_SKEW_SECONDS = DEFAULT_FUTURE_TIMESTAMP_SKEW_SECONDS;
|
|
73
156
|
exports.STANDALONE_ENV_MARKERS = STANDALONE_ENV_MARKERS;
|
|
157
|
+
exports.TRANSACTION_SWITCH_ENV = TRANSACTION_SWITCH_ENV;
|
|
74
158
|
exports.findBlockletEnvLeftovers = findBlockletEnvLeftovers;
|
|
75
159
|
exports.formatBlockletEnvLeftoversWarning = formatBlockletEnvLeftoversWarning;
|
|
160
|
+
exports.parseNonNegativeNumberEnv = parseNonNegativeNumberEnv;
|
|
161
|
+
exports.resolveConfigCheckModeFromEnv = resolveConfigCheckModeFromEnv;
|
|
162
|
+
exports.resolveConfigCheckTimeoutMsFromEnv = resolveConfigCheckTimeoutMsFromEnv;
|
|
163
|
+
exports.resolveFutureTimestampGuardFromEnv = resolveFutureTimestampGuardFromEnv;
|
|
164
|
+
exports.resolveTransactionSwitchesFromEnv = resolveTransactionSwitchesFromEnv;
|
|
76
165
|
exports.resolveTrustedSubject = resolveTrustedSubject;
|
package/lib/standalone-env.d.cts
CHANGED
|
@@ -35,5 +35,58 @@ declare function formatBlockletEnvLeftoversWarning({
|
|
|
35
35
|
leftovers,
|
|
36
36
|
readByChain
|
|
37
37
|
}: BlockletEnvLeftovers): string;
|
|
38
|
+
/** Env names of the `transaction.*` master switches a chain app maps into its chain config. */
|
|
39
|
+
declare const TRANSACTION_SWITCH_ENV: {
|
|
40
|
+
readonly bridge: "CHAIN_TX_BRIDGE_ENABLED";
|
|
41
|
+
readonly rollupV1: "CHAIN_TX_ROLLUP_V1_ENABLED";
|
|
42
|
+
};
|
|
43
|
+
interface TransactionSwitches {
|
|
44
|
+
bridge?: {
|
|
45
|
+
enabled: boolean;
|
|
46
|
+
};
|
|
47
|
+
rollupV1?: {
|
|
48
|
+
enabled: boolean;
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* `transaction.bridge` / `transaction.rollupV1` from env. Only explicitly set switches are returned, so an env
|
|
53
|
+
* without them leaves the chain config exactly as before (bridge absent = disabled, rollupV1 absent = enabled).
|
|
54
|
+
*/
|
|
55
|
+
declare function resolveTransactionSwitchesFromEnv(env?: Env): TransactionSwitches;
|
|
56
|
+
type TChainConfigCheckMode = 'off' | 'warn' | 'enforce';
|
|
57
|
+
/**
|
|
58
|
+
* `CHAIN_CONFIG_CHECK`: what a follower does with the startup comparison of its consensus config against the
|
|
59
|
+
* upstream leader's `getConfig` (`off` default: no request at all; `warn`: log differences and start; `enforce`:
|
|
60
|
+
* refuse to start on any difference or when the upstream cannot be asked).
|
|
61
|
+
*/
|
|
62
|
+
declare function resolveConfigCheckModeFromEnv(env?: Env): TChainConfigCheckMode;
|
|
63
|
+
declare const DEFAULT_CONFIG_CHECK_TIMEOUT_SECONDS = 60;
|
|
64
|
+
/**
|
|
65
|
+
* `CHAIN_CONFIG_CHECK_TIMEOUT_SEC` (non-negative integer seconds, default 60): how long `enforce` keeps retrying an
|
|
66
|
+
* unreachable / bad upstream before it decides (start with a warning on existing local state, refuse when fresh).
|
|
67
|
+
*/
|
|
68
|
+
declare function resolveConfigCheckTimeoutMsFromEnv(env?: Env): number;
|
|
69
|
+
/**
|
|
70
|
+
* A fee / gas env value (`CHAIN_GAS_PRICE`, `CREATE_*_TX_FEE`), parsed identically on leader and follower:
|
|
71
|
+
* unset or empty -> undefined (the caller's default / no overlay); otherwise a plain non-negative decimal
|
|
72
|
+
* (`integer`: digits only). Whitespace, NaN, negatives, exponents and hex fail startup instead of becoming `0`.
|
|
73
|
+
*/
|
|
74
|
+
declare function parseNonNegativeNumberEnv(env: Env, name: string, {
|
|
75
|
+
integer
|
|
76
|
+
}?: {
|
|
77
|
+
integer?: boolean;
|
|
78
|
+
}): number | undefined;
|
|
79
|
+
/** Default clock skew a replayed entry's timestamp may be ahead of the local clock (#1961; #1965 owns the value). */
|
|
80
|
+
declare const DEFAULT_FUTURE_TIMESTAMP_SKEW_SECONDS = 300;
|
|
81
|
+
interface FutureTimestampGuardConfig {
|
|
82
|
+
/** Entries with `sequence >= activationSequence` are checked; earlier history is always accepted. */
|
|
83
|
+
activationSequence: number;
|
|
84
|
+
maxSkewMs: number;
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* `LEDGER_FUTURE_TIMESTAMP_FROM_SEQ` (positive integer; unset = guard disabled, today's behavior) and
|
|
88
|
+
* `LEDGER_FUTURE_TIMESTAMP_SKEW_SEC` (non-negative integer seconds, default 300; ignored while the guard is off).
|
|
89
|
+
*/
|
|
90
|
+
declare function resolveFutureTimestampGuardFromEnv(env?: Env): FutureTimestampGuardConfig | undefined;
|
|
38
91
|
//#endregion
|
|
39
|
-
export { BLOCKLET_ENV_CHAIN_FALLBACKS, BlockletEnvLeftovers, STANDALONE_ENV_MARKERS, findBlockletEnvLeftovers, formatBlockletEnvLeftoversWarning, resolveTrustedSubject };
|
|
92
|
+
export { BLOCKLET_ENV_CHAIN_FALLBACKS, BlockletEnvLeftovers, DEFAULT_CONFIG_CHECK_TIMEOUT_SECONDS, DEFAULT_FUTURE_TIMESTAMP_SKEW_SECONDS, FutureTimestampGuardConfig, STANDALONE_ENV_MARKERS, TChainConfigCheckMode, TRANSACTION_SWITCH_ENV, TransactionSwitches, findBlockletEnvLeftovers, formatBlockletEnvLeftoversWarning, parseNonNegativeNumberEnv, resolveConfigCheckModeFromEnv, resolveConfigCheckTimeoutMsFromEnv, resolveFutureTimestampGuardFromEnv, resolveTransactionSwitchesFromEnv, resolveTrustedSubject };
|