@ocap/chain-node 0.0.0-stage → 1.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/env.cjs ADDED
@@ -0,0 +1,221 @@
1
+ const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
2
+ let _arcblock_ledger_core = require("@arcblock/ledger-core");
3
+ let _arcblock_ledger_sqlite = require("@arcblock/ledger-sqlite");
4
+ let _ocap_util_lib_error = require("@ocap/util/lib/error");
5
+
6
+ //#region src/env.ts
7
+ function parseOptionalPositiveInt(raw, label) {
8
+ const trimmed = (raw ?? "").trim();
9
+ if (!trimmed) return void 0;
10
+ if (!/^[1-9]\d*$/.test(trimmed)) throw new _ocap_util_lib_error.CustomError("INVALID_CONFIG", `Invalid ${label}="${raw}": expected a positive integer >= 1`);
11
+ const parsed = Number(trimmed);
12
+ if (!Number.isSafeInteger(parsed) || parsed < 1) throw new _ocap_util_lib_error.CustomError("INVALID_CONFIG", `Invalid ${label}="${raw}": expected a positive safe integer >= 1`);
13
+ return parsed;
14
+ }
15
+ function parseOptionalNonNegativeInt(raw, label) {
16
+ const trimmed = (raw ?? "").trim();
17
+ if (!trimmed) return void 0;
18
+ if (!/^(?:0|[1-9]\d*)$/.test(trimmed)) throw new _ocap_util_lib_error.CustomError("INVALID_CONFIG", `Invalid ${label}="${raw}": expected a non-negative integer >= 0`);
19
+ const parsed = Number(trimmed);
20
+ if (!Number.isSafeInteger(parsed) || parsed < 0) throw new _ocap_util_lib_error.CustomError("INVALID_CONFIG", `Invalid ${label}="${raw}": expected a non-negative safe integer >= 0`);
21
+ return parsed;
22
+ }
23
+ function parseBoolEnv(raw) {
24
+ const norm = (raw ?? "").trim().toLowerCase();
25
+ return norm === "1" || norm === "true";
26
+ }
27
+ function hasSigningSecretKey(signer) {
28
+ return Boolean(signer && typeof signer.secretKey === "string" && signer.secretKey.trim().length > 0);
29
+ }
30
+ function normalizeConsensusKeyType(rawValue) {
31
+ const trimmed = (rawValue ?? "").trim().toLowerCase();
32
+ if (!trimmed) return void 0;
33
+ if (trimmed === "ethereum") return "eth";
34
+ if (trimmed === "ed25519" || trimmed === "secp256k1" || trimmed === "eth") return trimmed;
35
+ throw new _ocap_util_lib_error.CustomError("INVALID_CONFIG", `Unsupported CHAIN_CONSENSUS_KEY_TYPE="${rawValue}": expected ed25519, secp256k1, or eth`);
36
+ }
37
+ function resolveSignerFromEnvRecord(env, explicitSigner) {
38
+ const keyType = normalizeConsensusKeyType(env.CHAIN_CONSENSUS_KEY_TYPE);
39
+ const secretKey = (env.CHAIN_CONSENSUS_SK ?? "").trim();
40
+ const address = (env.CHAIN_CONSENSUS_PROPOSER ?? "").trim();
41
+ if (!secretKey) {
42
+ if (keyType) throw new _ocap_util_lib_error.CustomError("INVALID_CONFIG", `CHAIN_CONSENSUS_KEY_TYPE (${env.CHAIN_CONSENSUS_KEY_TYPE}) requires CHAIN_CONSENSUS_SK to be set`);
43
+ if (address) {
44
+ if (!hasSigningSecretKey(explicitSigner) || (0, _arcblock_ledger_core.normalizeDidForCompare)(explicitSigner.address) !== (0, _arcblock_ledger_core.normalizeDidForCompare)(address)) throw new _ocap_util_lib_error.CustomError("INVALID_CONFIG", `CHAIN_CONSENSUS_PROPOSER (${env.CHAIN_CONSENSUS_PROPOSER}) requires a matching CHAIN_CONSENSUS_SK`);
45
+ }
46
+ return explicitSigner;
47
+ }
48
+ if (hasSigningSecretKey(explicitSigner)) return explicitSigner;
49
+ if (address) {
50
+ const resolved = (0, _arcblock_ledger_core.resolveConsensusProposerFromSigner)({
51
+ address,
52
+ secretKey,
53
+ ...keyType ? { keyType } : {}
54
+ });
55
+ return {
56
+ address: resolved.address,
57
+ secretKey: resolved.secretKey,
58
+ publicKey: resolved.publicKey,
59
+ ...keyType ? { keyType } : {}
60
+ };
61
+ }
62
+ const derived = (0, _arcblock_ledger_core.resolveConsensusProposer)({
63
+ moderator: { address: explicitSigner?.address || "" },
64
+ env: {
65
+ ...env,
66
+ ...keyType ? { CHAIN_CONSENSUS_KEY_TYPE: keyType } : {}
67
+ }
68
+ });
69
+ if (derived.secretKey) return {
70
+ address: derived.address,
71
+ secretKey: derived.secretKey,
72
+ publicKey: derived.publicKey,
73
+ ...keyType ? { keyType } : {}
74
+ };
75
+ return explicitSigner;
76
+ }
77
+ /**
78
+ * Pure environment-to-role parser (`@ocap/chain-node`).
79
+ *
80
+ * Reads ONLY the explicitly supplied `env` dictionary — zero implicit `process.env` reads.
81
+ */
82
+ function roleConfigFromEnv(env, options) {
83
+ if (!env || typeof env !== "object") throw new _ocap_util_lib_error.CustomError("INVALID_CONFIG", "roleConfigFromEnv requires an explicit env record");
84
+ const resolved = (0, _arcblock_ledger_core.resolveNodeRoleConfig)(env);
85
+ const allowPrivatePeers = parseBoolEnv(env.ALLOW_PRIVATE_PEER_URLS);
86
+ const explicitOrEnvSigner = resolveSignerFromEnvRecord(env, options?.signer);
87
+ if (resolved.role === "validator") {
88
+ if (!explicitOrEnvSigner) throw new _ocap_util_lib_error.CustomError("INVALID_CONFIG", "Validator role requires options.signer or explicit CHAIN_CONSENSUS_SK + CHAIN_CONSENSUS_PROPOSER in env");
89
+ if (resolved.consensusMode === "hotstuff") {
90
+ if (!hasSigningSecretKey(explicitOrEnvSigner)) throw new _ocap_util_lib_error.CustomError("INVALID_CONFIG", "HotStuff validator role requires a signing secretKey in options.signer or CHAIN_CONSENSUS_SK");
91
+ if (!resolved.consensusBindHost || resolved.consensusPort === null) throw new _ocap_util_lib_error.CustomError("INVALID_CONFIG", "HotStuff validator role requires CONSENSUS_BIND_HOST and CONSENSUS_PORT");
92
+ return {
93
+ kind: "hotstuff",
94
+ signer: explicitOrEnvSigner,
95
+ validators: resolved.hotstuffValidators,
96
+ ...resolved.hotstuffQuorumThreshold !== void 0 ? { quorumThreshold: resolved.hotstuffQuorumThreshold } : {},
97
+ consensusBindHost: resolved.consensusBindHost,
98
+ consensusPort: resolved.consensusPort,
99
+ allowPublicConsensusBind: resolved.allowPublicConsensusBind,
100
+ writePolicy: resolved.writePolicy,
101
+ allowPrivatePeers,
102
+ retentionMode: resolved.retentionMode,
103
+ hotWindowEntries: resolved.hotWindowEntries,
104
+ hotWindowCheckpoints: resolved.hotWindowCheckpoints,
105
+ snapshotBaseUrl: resolved.snapshotBaseUrl,
106
+ witnessQuorum: resolved.witnessQuorum,
107
+ ...resolved.trustedWitnesses !== void 0 ? { trustedWitnesses: resolved.trustedWitnesses } : {},
108
+ witnessSubmitUrls: resolved.witnessSubmitUrls
109
+ };
110
+ }
111
+ return {
112
+ kind: "validator",
113
+ signer: explicitOrEnvSigner,
114
+ retentionMode: resolved.retentionMode,
115
+ hotWindowEntries: resolved.hotWindowEntries,
116
+ hotWindowCheckpoints: resolved.hotWindowCheckpoints,
117
+ snapshotBaseUrl: resolved.snapshotBaseUrl,
118
+ witnessQuorum: resolved.witnessQuorum,
119
+ ...resolved.trustedWitnesses !== void 0 ? { trustedWitnesses: resolved.trustedWitnesses } : {},
120
+ witnessSubmitUrls: resolved.witnessSubmitUrls,
121
+ anchorWebhookUrl: resolved.anchorWebhookUrl
122
+ };
123
+ }
124
+ const pollIntervalMs = parseOptionalPositiveInt(env.FOLLOWER_POLL_INTERVAL_MS, "FOLLOWER_POLL_INTERVAL_MS");
125
+ const maxSyncLag = parseOptionalNonNegativeInt(env.FOLLOWER_MAX_SYNC_LAG, "FOLLOWER_MAX_SYNC_LAG");
126
+ const maxUpstreamStaleMs = parseOptionalPositiveInt(env.FOLLOWER_MAX_UPSTREAM_STALE_MS, "FOLLOWER_MAX_UPSTREAM_STALE_MS");
127
+ const witnessWallet = (0, _arcblock_ledger_core.resolveEnvWitnessWallet)(env) ?? void 0;
128
+ const snapshotPrefix = (env.SNAPSHOT_S3_PREFIX ?? "").trim() || void 0;
129
+ const disallowKeylessCascadedUpstream = parseBoolEnv(env.DISALLOW_KEYLESS_CASCADED_UPSTREAM);
130
+ return {
131
+ kind: "follower",
132
+ runtimeRole: resolved.role === "standby" ? "standby" : "follower",
133
+ writePolicy: resolved.writePolicy,
134
+ upstreamChainUrl: resolved.upstreamChainUrl,
135
+ clusterPeerUrls: resolved.clusterPeerUrls,
136
+ snapshotBaseUrl: resolved.snapshotBaseUrl,
137
+ ...snapshotPrefix ? { snapshotPrefix } : {},
138
+ trustedProposer: resolved.trustedProposer,
139
+ trustedProposerPublicKey: resolved.trustedProposerPublicKey,
140
+ ...resolved.hotstuffValidators.length > 0 ? { hotstuffValidators: resolved.hotstuffValidators } : {},
141
+ ...resolved.hotstuffQuorumThreshold !== void 0 ? { hotstuffQuorumThreshold: resolved.hotstuffQuorumThreshold } : {},
142
+ allowPrivatePeers,
143
+ disallowKeylessCascadedUpstream,
144
+ allowUnauthenticatedBootstrap: resolved.allowUnauthenticatedBootstrap,
145
+ syncMode: resolved.syncMode,
146
+ ...pollIntervalMs !== void 0 ? { pollIntervalMs } : {},
147
+ ...maxSyncLag !== void 0 ? { maxSyncLag } : {},
148
+ ...maxUpstreamStaleMs !== void 0 ? { maxUpstreamStaleMs } : {},
149
+ retentionMode: resolved.retentionMode,
150
+ hotWindowEntries: resolved.hotWindowEntries,
151
+ hotWindowCheckpoints: resolved.hotWindowCheckpoints,
152
+ ...witnessWallet ? { witnessWallet } : {},
153
+ witnessSubmitUrls: resolved.witnessSubmitUrls,
154
+ ...hasSigningSecretKey(explicitOrEnvSigner) ? { signer: explicitOrEnvSigner } : {}
155
+ };
156
+ }
157
+ /**
158
+ * Pure environment-to-SQLite-writer-lease parser (`@ocap/chain-node`).
159
+ *
160
+ * Reads ONLY the explicitly supplied `env` dictionary — zero implicit `process.env` reads.
161
+ */
162
+ function leaseConfigFromEnv(env) {
163
+ if (!env || typeof env !== "object") throw new _ocap_util_lib_error.CustomError("INVALID_CONFIG", "leaseConfigFromEnv requires an explicit env record");
164
+ const parsed = (0, _arcblock_ledger_sqlite.resolveLedgerLeaseConfig)(env);
165
+ if (!parsed.enabled) return false;
166
+ return {
167
+ enabled: true,
168
+ autoAcquire: true,
169
+ holderId: parsed.holderId,
170
+ ttlMs: parsed.ttlMs,
171
+ startupWaitMs: parsed.startupWaitMs
172
+ };
173
+ }
174
+ /**
175
+ * Install idempotent `SIGTERM` / `SIGINT` graceful shutdown handlers for a running chain node.
176
+ * Returns a cleanup callback that removes the signal listeners.
177
+ */
178
+ function installProcessSignalHandlers(node, options) {
179
+ const timeoutMs = typeof options?.timeoutMs === "number" && Number.isFinite(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : 15e3;
180
+ const signals = options?.signals ?? ["SIGTERM", "SIGINT"];
181
+ const exitProcess = options?.exitProcess !== false;
182
+ const log = options?.logger ?? console;
183
+ let shuttingDown = false;
184
+ const handleSignal = (signal) => {
185
+ if (shuttingDown) return;
186
+ shuttingDown = true;
187
+ log.info(`\n${signal} received, shutting down chain node gracefully...`);
188
+ const forceTimer = setTimeout(() => {
189
+ log.error("Chain node graceful shutdown timed out, forcing exit");
190
+ options?.onExit?.(1);
191
+ if (exitProcess) process.exit(1);
192
+ }, timeoutMs);
193
+ if (typeof forceTimer.unref === "function") forceTimer.unref();
194
+ node.stop().then(() => {
195
+ clearTimeout(forceTimer);
196
+ log.info("Chain node graceful shutdown complete");
197
+ options?.onExit?.(0);
198
+ if (exitProcess) process.exit(0);
199
+ }).catch((err) => {
200
+ clearTimeout(forceTimer);
201
+ log.error("Error during chain node graceful shutdown:", err);
202
+ options?.onExit?.(1);
203
+ if (exitProcess) process.exit(1);
204
+ });
205
+ };
206
+ const listeners = /* @__PURE__ */ new Map();
207
+ for (const sig of signals) {
208
+ const listener = () => handleSignal(sig);
209
+ listeners.set(sig, listener);
210
+ process.on(sig, listener);
211
+ }
212
+ return () => {
213
+ for (const [sig, listener] of listeners) process.off(sig, listener);
214
+ listeners.clear();
215
+ };
216
+ }
217
+
218
+ //#endregion
219
+ exports.installProcessSignalHandlers = installProcessSignalHandlers;
220
+ exports.leaseConfigFromEnv = leaseConfigFromEnv;
221
+ exports.roleConfigFromEnv = roleConfigFromEnv;
package/lib/env.d.cts ADDED
@@ -0,0 +1,32 @@
1
+ import { ChainNodeRoleConfig, ILedgerLeaseOptions, RunningChainNode, ValidatorSignerConfig } from "./types.cjs";
2
+
3
+ //#region src/env.d.ts
4
+
5
+ /**
6
+ * Pure environment-to-role parser (`@ocap/chain-node`).
7
+ *
8
+ * Reads ONLY the explicitly supplied `env` dictionary — zero implicit `process.env` reads.
9
+ */
10
+ declare function roleConfigFromEnv(env: Record<string, string | undefined>, options?: {
11
+ signer?: ValidatorSignerConfig;
12
+ }): ChainNodeRoleConfig;
13
+ /**
14
+ * Pure environment-to-SQLite-writer-lease parser (`@ocap/chain-node`).
15
+ *
16
+ * Reads ONLY the explicitly supplied `env` dictionary — zero implicit `process.env` reads.
17
+ */
18
+ declare function leaseConfigFromEnv(env: Record<string, string | undefined>): ILedgerLeaseOptions | false;
19
+ interface InstallProcessSignalHandlersOptions {
20
+ timeoutMs?: number;
21
+ signals?: NodeJS.Signals[];
22
+ exitProcess?: boolean;
23
+ onExit?: (exitCode: number) => void;
24
+ logger?: Pick<Console, 'info' | 'error'>;
25
+ }
26
+ /**
27
+ * Install idempotent `SIGTERM` / `SIGINT` graceful shutdown handlers for a running chain node.
28
+ * Returns a cleanup callback that removes the signal listeners.
29
+ */
30
+ declare function installProcessSignalHandlers(node: Pick<RunningChainNode, 'stop'>, options?: InstallProcessSignalHandlersOptions): () => void;
31
+ //#endregion
32
+ export { InstallProcessSignalHandlersOptions, installProcessSignalHandlers, leaseConfigFromEnv, roleConfigFromEnv };
package/lib/index.cjs ADDED
@@ -0,0 +1,13 @@
1
+ const require_env = require('./env.cjs');
2
+ const require_start_chain_node = require('./start-chain-node.cjs');
3
+ const require_standalone_env = require('./standalone-env.cjs');
4
+
5
+ exports.BLOCKLET_ENV_CHAIN_FALLBACKS = require_standalone_env.BLOCKLET_ENV_CHAIN_FALLBACKS;
6
+ exports.STANDALONE_ENV_MARKERS = require_standalone_env.STANDALONE_ENV_MARKERS;
7
+ exports.findBlockletEnvLeftovers = require_standalone_env.findBlockletEnvLeftovers;
8
+ exports.formatBlockletEnvLeftoversWarning = require_standalone_env.formatBlockletEnvLeftoversWarning;
9
+ exports.installProcessSignalHandlers = require_env.installProcessSignalHandlers;
10
+ exports.leaseConfigFromEnv = require_env.leaseConfigFromEnv;
11
+ exports.resolveTrustedSubject = require_standalone_env.resolveTrustedSubject;
12
+ exports.roleConfigFromEnv = require_env.roleConfigFromEnv;
13
+ exports.startChainNode = require_start_chain_node.startChainNode;
@@ -0,0 +1,5 @@
1
+ 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
+ import { InstallProcessSignalHandlersOptions, installProcessSignalHandlers, leaseConfigFromEnv, roleConfigFromEnv } from "./env.cjs";
3
+ import { startChainNode } from "./start-chain-node.cjs";
4
+ import { BLOCKLET_ENV_CHAIN_FALLBACKS, BlockletEnvLeftovers, STANDALONE_ENV_MARKERS, findBlockletEnvLeftovers, formatBlockletEnvLeftoversWarning, resolveTrustedSubject } from "./standalone-env.cjs";
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 };
@@ -0,0 +1,76 @@
1
+ const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
2
+ let _arcblock_did = require("@arcblock/did");
3
+
4
+ //#region src/standalone-env.ts
5
+ /**
6
+ * Standalone (non-Blocklet-Server) env helpers shared by the chain apps (#1923, docs/ops/chain-env-mapping.md).
7
+ *
8
+ * Kept free of runtime imports beyond `@arcblock/did` so app key-derivation code can require this module
9
+ * (`@ocap/chain-node/lib/standalone-env.js`) without loading the node runtime.
10
+ */
11
+ /**
12
+ * Standalone replacement for the Blocklet Server app DID that seeds the trusted-storage wallet.
13
+ * Returns '' when unset/blank so callers fall back to BLOCKLET_APP_PID / BLOCKLET_APP_ID / moderator exactly as
14
+ * before. The subject is hashed as a raw string by `fromAppDid`, so a `did:abt:` prefix or a typo would silently
15
+ * yield a different trusted key: only a bare, valid DID address is accepted.
16
+ */
17
+ function resolveTrustedSubject(env = process.env) {
18
+ const subject = String(env.CHAIN_TRUSTED_SUBJECT || "").trim();
19
+ if (!subject) return "";
20
+ if (/^did:/i.test(subject) || !(0, _arcblock_did.isValid)(subject)) throw new Error("Invalid CHAIN_TRUSTED_SUBJECT: must be a bare DID address (no \"did:abt:\" prefix)");
21
+ return subject;
22
+ }
23
+ /**
24
+ * Standalone-only replacements for Blocklet Server variables. Blocklet Server sets none of them on beta or main
25
+ * (checked against both live process envs), so seeing one means the operator runs (or migrates to) a standalone
26
+ * env file. `CHAIN_VAULT_PSK` is deliberately not a marker: main's blocklet.yml declares it, so it is present there.
27
+ */
28
+ const STANDALONE_ENV_MARKERS = [
29
+ "CHAIN_DATA_DIR",
30
+ "CHAIN_PORT",
31
+ "CHAIN_SK",
32
+ "CHAIN_MODERATOR_PK",
33
+ "CHAIN_TRUSTED_SUBJECT"
34
+ ];
35
+ /** Blocklet Server variables both chain apps still read as fallbacks behind a CHAIN_* variable. */
36
+ const BLOCKLET_ENV_CHAIN_FALLBACKS = new Set([
37
+ "BLOCKLET_APP_ASK",
38
+ "BLOCKLET_APP_DIR",
39
+ "BLOCKLET_APP_ID",
40
+ "BLOCKLET_APP_PID",
41
+ "BLOCKLET_APP_PK",
42
+ "BLOCKLET_APP_PPK",
43
+ "BLOCKLET_APP_PSK",
44
+ "BLOCKLET_APP_SK",
45
+ "BLOCKLET_DATA_DIR",
46
+ "BLOCKLET_PORT"
47
+ ]);
48
+ /**
49
+ * Detect a standalone env that still carries Blocklet Server variables, so two key sources are never mixed
50
+ * silently. Returns null under Blocklet Server (no standalone marker) and for a clean standalone env.
51
+ * Only variable names are returned, never values.
52
+ */
53
+ function findBlockletEnvLeftovers(env = process.env, { readByChain = BLOCKLET_ENV_CHAIN_FALLBACKS } = {}) {
54
+ const isSet = (k) => String(env[k] ?? "").trim() !== "";
55
+ const standaloneMarkers = STANDALONE_ENV_MARKERS.filter(isSet);
56
+ if (!standaloneMarkers.length) return null;
57
+ const leftovers = Object.keys(env).filter((k) => /^(BLOCKLET_|ABT_NODE_)/.test(k) && isSet(k)).sort();
58
+ if (!leftovers.length) return null;
59
+ const read = new Set(readByChain);
60
+ return {
61
+ standaloneMarkers,
62
+ leftovers,
63
+ readByChain: leftovers.filter((k) => read.has(k))
64
+ };
65
+ }
66
+ function formatBlockletEnvLeftoversWarning({ standaloneMarkers, leftovers, readByChain }) {
67
+ const read = readByChain.length ? ` ${readByChain.join(", ")} still feed key/path fallbacks when the CHAIN_* equivalent is unset.` : "";
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
+ }
70
+
71
+ //#endregion
72
+ exports.BLOCKLET_ENV_CHAIN_FALLBACKS = BLOCKLET_ENV_CHAIN_FALLBACKS;
73
+ exports.STANDALONE_ENV_MARKERS = STANDALONE_ENV_MARKERS;
74
+ exports.findBlockletEnvLeftovers = findBlockletEnvLeftovers;
75
+ exports.formatBlockletEnvLeftoversWarning = formatBlockletEnvLeftoversWarning;
76
+ exports.resolveTrustedSubject = resolveTrustedSubject;
@@ -0,0 +1,39 @@
1
+ //#region src/standalone-env.d.ts
2
+ type Env = Record<string, string | undefined>;
3
+ /**
4
+ * Standalone replacement for the Blocklet Server app DID that seeds the trusted-storage wallet.
5
+ * Returns '' when unset/blank so callers fall back to BLOCKLET_APP_PID / BLOCKLET_APP_ID / moderator exactly as
6
+ * before. The subject is hashed as a raw string by `fromAppDid`, so a `did:abt:` prefix or a typo would silently
7
+ * yield a different trusted key: only a bare, valid DID address is accepted.
8
+ */
9
+ declare function resolveTrustedSubject(env?: Env): string;
10
+ /**
11
+ * Standalone-only replacements for Blocklet Server variables. Blocklet Server sets none of them on beta or main
12
+ * (checked against both live process envs), so seeing one means the operator runs (or migrates to) a standalone
13
+ * env file. `CHAIN_VAULT_PSK` is deliberately not a marker: main's blocklet.yml declares it, so it is present there.
14
+ */
15
+ declare const STANDALONE_ENV_MARKERS: readonly string[];
16
+ /** Blocklet Server variables both chain apps still read as fallbacks behind a CHAIN_* variable. */
17
+ declare const BLOCKLET_ENV_CHAIN_FALLBACKS: ReadonlySet<string>;
18
+ interface BlockletEnvLeftovers {
19
+ standaloneMarkers: string[];
20
+ leftovers: string[];
21
+ readByChain: string[];
22
+ }
23
+ /**
24
+ * Detect a standalone env that still carries Blocklet Server variables, so two key sources are never mixed
25
+ * silently. Returns null under Blocklet Server (no standalone marker) and for a clean standalone env.
26
+ * Only variable names are returned, never values.
27
+ */
28
+ declare function findBlockletEnvLeftovers(env?: Env, {
29
+ readByChain
30
+ }?: {
31
+ readByChain?: Iterable<string>;
32
+ }): BlockletEnvLeftovers | null;
33
+ declare function formatBlockletEnvLeftoversWarning({
34
+ standaloneMarkers,
35
+ leftovers,
36
+ readByChain
37
+ }: BlockletEnvLeftovers): string;
38
+ //#endregion
39
+ export { BLOCKLET_ENV_CHAIN_FALLBACKS, BlockletEnvLeftovers, STANDALONE_ENV_MARKERS, findBlockletEnvLeftovers, formatBlockletEnvLeftoversWarning, resolveTrustedSubject };