@fased/fased 0.1.62 → 0.1.64

package/dist/wallet/wallet-send-execution-ledger.js

@@ -0,0 +1,292 @@
+import { resolveProcessScopedMap } from "../shared/process-scoped-map.js";
+import { acquireFileLock, withFileLock } from "../plugin-sdk/file-lock.js";
+import "../infra/file-lock.js";
+import { ensureWalletStateDir } from "./wallet-runtime-config.js";
+import { serializeWalletState, writeWalletStateFileAtomically } from "./wallet-atomic-state.js";
+import syncFs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+//#region src/wallet/wallet-send-execution-ledger.ts
+const STATES = new Set([
+	"reserved",
+	"approval_pending",
+	"executing",
+	"unknown",
+	"executed",
+	"failed"
+]);
+const TRANSITIONS = {
+	reserved: new Set([
+		"reserved",
+		"approval_pending",
+		"executing",
+		"unknown",
+		"failed"
+	]),
+	approval_pending: new Set([
+		"approval_pending",
+		"executed",
+		"unknown",
+		"failed"
+	]),
+	executing: new Set([
+		"executing",
+		"unknown",
+		"executed",
+		"failed"
+	]),
+	unknown: new Set([
+		"unknown",
+		"executed",
+		"failed"
+	]),
+	executed: new Set(["executed"]),
+	failed: new Set(["failed"])
+};
+const MUTATION_LOCK_OPTIONS = {
+	retries: {
+		retries: 100,
+		factor: 1.15,
+		minTimeout: 10,
+		maxTimeout: 200,
+		randomize: true
+	},
+	stale: 3e4
+};
+const EXECUTION_LOCK_OPTIONS = {
+	retries: {
+		retries: 1,
+		factor: 1,
+		minTimeout: 10,
+		maxTimeout: 10,
+		randomize: false
+	},
+	stale: 3e4
+};
+const MUTATION_QUEUES = resolveProcessScopedMap(Symbol.for("fased.wallet.sendExecution.mutationQueues"));
+const ACTIVE_EXECUTIONS = resolveProcessScopedMap(Symbol.for("fased.wallet.sendExecution.activeExecutions"));
+function containsControlCharacter(value) {
+	for (let index = 0; index < value.length; index += 1) {
+		if (value.charCodeAt(index) <= 31) {
+			return true;
+		}
+	}
+	return false;
+}
+function canonicalJson(value) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") {
+		return JSON.stringify(value);
+	}
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) {
+			throw new Error("wallet send intent contains a non-finite number");
+		}
+		return JSON.stringify(value);
+	}
+	if (Array.isArray(value)) {
+		return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+	}
+	if (value && typeof value === "object") {
+		const record = value;
+		return `{${Object.keys(record).filter((key) => record[key] !== undefined).toSorted().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+	}
+	throw new Error("wallet send intent contains an unsupported value");
+}
+function walletSendIntentDigest(intent) {
+	return `sha256:${createHash("sha256").update(canonicalJson(intent)).digest("hex")}`;
+}
+function walletSendRequestId(executionIntentId) {
+	const normalized = executionIntentId.trim();
+	if (!normalized || normalized.length > 240 || containsControlCharacter(normalized)) {
+		throw new Error("wallet send executionIntentId is invalid");
+	}
+	return `wallet-send-${createHash("sha256").update(normalized).digest("hex")}`;
+}
+function ledgerPath(env) {
+	return path.join(ensureWalletStateDir(env).rootDir, "wallet-send-executions.json");
+}
+function executionLockTarget(executionIntentId, env) {
+	return path.join(path.dirname(ledgerPath(env)), ".wallet-send-executions", createHash("sha256").update(executionIntentId).digest("hex"));
+}
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function validateResult(value) {
+	if (value === undefined) {
+		return undefined;
+	}
+	if (!isRecord(value) || value.chain !== "solana" || typeof value.txHash !== "string" || !value.txHash.trim() || value.signer !== undefined && typeof value.signer !== "string" || value.metadata !== undefined && !isRecord(value.metadata)) {
+		throw new Error("wallet send execution ledger contains an invalid result");
+	}
+	return value;
+}
+function validateEntry(value) {
+	if (!isRecord(value)) {
+		throw new Error("wallet send execution ledger contains an invalid entry");
+	}
+	if (typeof value.executionIntentId !== "string" || !value.executionIntentId.trim() || typeof value.intentDigest !== "string" || !/^sha256:[0-9a-f]{64}$/u.test(value.intentDigest) || typeof value.requestId !== "string" || !value.requestId.trim() || typeof value.walletId !== "string" || !value.walletId.trim() || typeof value.providerId !== "string" || !value.providerId.trim() || typeof value.state !== "string" || !STATES.has(value.state) || typeof value.createdAt !== "string" || typeof value.updatedAt !== "string") {
+		throw new Error("wallet send execution ledger contains an invalid entry");
+	}
+	for (const field of [
+		"approvalRequestId",
+		"signature",
+		"reason"
+	]) {
+		if (value[field] !== undefined && typeof value[field] !== "string") {
+			throw new Error(`wallet send execution ledger contains an invalid ${field}`);
+		}
+	}
+	const expectedRequestId = walletSendRequestId(value.executionIntentId);
+	if (value.requestId !== expectedRequestId) {
+		throw new Error("wallet send execution ledger contains a mismatched request ID");
+	}
+	const result = validateResult(value.result);
+	if (value.state === "executed" && (!result || typeof value.signature !== "string" || value.signature !== result.txHash)) {
+		throw new Error("wallet send execution ledger contains an incomplete executed result");
+	}
+	return value;
+}
+function loadLedger(env) {
+	const filePath = ledgerPath(env);
+	if (!syncFs.existsSync(filePath)) {
+		return {
+			version: 1,
+			entries: []
+		};
+	}
+	try {
+		const parsed = JSON.parse(syncFs.readFileSync(filePath, "utf8"));
+		if (parsed.version !== 1 || !Array.isArray(parsed.entries)) {
+			throw new Error("unsupported shape");
+		}
+		const entries = parsed.entries.map(validateEntry);
+		if (new Set(entries.map((entry) => entry.executionIntentId)).size !== entries.length || new Set(entries.map((entry) => entry.requestId)).size !== entries.length) {
+			throw new Error("duplicate execution identity");
+		}
+		return {
+			version: 1,
+			entries
+		};
+	} catch (error) {
+		throw new Error("wallet send execution ledger is unreadable; refusing to reset it", { cause: error });
+	}
+}
+function saveLedger(file, env) {
+	writeWalletStateFileAtomically(ledgerPath(env), serializeWalletState(file));
+}
+async function withMutationLock(env, task) {
+	const filePath = ledgerPath(env);
+	const previous = MUTATION_QUEUES.get(filePath) ?? Promise.resolve();
+	let releaseQueue;
+	const turn = new Promise((resolve) => {
+		releaseQueue = resolve;
+	});
+	const queued = previous.then(() => turn, () => turn);
+	MUTATION_QUEUES.set(filePath, queued);
+	await previous.catch(() => undefined);
+	try {
+		return await withFileLock(filePath, MUTATION_LOCK_OPTIONS, async () => await task());
+	} finally {
+		releaseQueue();
+		if (MUTATION_QUEUES.get(filePath) === queued) {
+			MUTATION_QUEUES.delete(filePath);
+		}
+	}
+}
+function getWalletSendExecution(params) {
+	const executionIntentId = params.executionIntentId.trim();
+	if (!executionIntentId) {
+		return undefined;
+	}
+	return loadLedger(params.env ?? process.env).entries.find((entry) => entry.executionIntentId === executionIntentId);
+}
+async function beginWalletSendExecution(params) {
+	const env = params.env ?? process.env;
+	const executionIntentId = params.executionIntentId.trim();
+	const walletId = params.walletId.trim();
+	const providerId = params.providerId.trim();
+	const requestId = walletSendRequestId(executionIntentId);
+	if (!walletId || !providerId || !/^sha256:[0-9a-f]{64}$/u.test(params.intentDigest)) {
+		throw new Error("wallet send execution identity is incomplete");
+	}
+	return await withMutationLock(env, () => {
+		const file = loadLedger(env);
+		const existing = file.entries.find((entry) => entry.executionIntentId === executionIntentId);
+		if (existing) {
+			if (existing.intentDigest !== params.intentDigest || existing.walletId !== walletId || existing.providerId !== providerId || existing.requestId !== requestId) {
+				throw new Error("wallet send executionIntentId is already bound to a different immutable intent");
+			}
+			return {
+				entry: existing,
+				created: false
+			};
+		}
+		const now = new Date().toISOString();
+		const entry = {
+			executionIntentId,
+			intentDigest: params.intentDigest,
+			requestId,
+			walletId,
+			providerId,
+			state: "reserved",
+			createdAt: now,
+			updatedAt: now
+		};
+		file.entries.push(entry);
+		saveLedger(file, env);
+		return {
+			entry,
+			created: true
+		};
+	});
+}
+async function updateWalletSendExecution(params) {
+	const env = params.env ?? process.env;
+	return await withMutationLock(env, () => {
+		const file = loadLedger(env);
+		const entry = file.entries.find((candidate) => candidate.executionIntentId === params.executionIntentId.trim());
+		if (!entry) {
+			throw new Error("wallet send execution entry not found");
+		}
+		if (!params.expectedStates.includes(entry.state)) {
+			throw new Error(`wallet send execution is ${entry.state}; expected ${params.expectedStates.join(" or ")}`);
+		}
+		if (!TRANSITIONS[entry.state].has(params.state)) {
+			throw new Error(`wallet send execution cannot transition from ${entry.state} to ${params.state}`);
+		}
+		Object.assign(entry, params.patch ?? {});
+		entry.state = params.state;
+		entry.updatedAt = new Date().toISOString();
+		saveLedger(file, env);
+		return entry;
+	});
+}
+async function claimWalletSendExecution(executionIntentIdRaw, env = process.env) {
+	const executionIntentId = executionIntentIdRaw.trim();
+	walletSendRequestId(executionIntentId);
+	const executionKey = `${ledgerPath(env)}\0${executionIntentId}`;
+	if (ACTIVE_EXECUTIONS.has(executionKey)) {
+		throw new Error("wallet send execution is already in progress");
+	}
+	ACTIVE_EXECUTIONS.set(executionKey, true);
+	let lock;
+	try {
+		lock = await acquireFileLock(executionLockTarget(executionIntentId, env), EXECUTION_LOCK_OPTIONS);
+	} catch (error) {
+		ACTIVE_EXECUTIONS.delete(executionKey);
+		throw new Error("wallet send execution is already in progress", { cause: error });
+	}
+	let released = false;
+	return async () => {
+		if (released) {
+			return;
+		}
+		released = true;
+		ACTIVE_EXECUTIONS.delete(executionKey);
+		await lock.release();
+	};
+}
+
+//#endregion
+export { beginWalletSendExecution, claimWalletSendExecution, getWalletSendExecution, updateWalletSendExecution, walletSendIntentDigest, walletSendRequestId };

package/dist/wallet/wallet-settlement-links.js

@@ -1,4 +1,5 @@
 import { ensureWalletStateDir } from "./wallet-runtime-config.js";
+import { serializeWalletState, writeWalletStateFileAtomically } from "./wallet-atomic-state.js";
 import syncFs from "node:fs";
 import path from "node:path";
 
@@ -6,6 +7,13 @@ import path from "node:path";
 function linksFilePath(env = process.env) {
 	return path.join(ensureWalletStateDir(env).rootDir, "wallet-settlement-links.json");
 }
+function isWalletSettlementLink(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return false;
+	}
+	const entry = value;
+	return typeof entry.requestId === "string" && Boolean(entry.requestId.trim()) && typeof entry.taskId === "string" && Boolean(entry.taskId.trim()) && (entry.mode === "manual" || entry.mode === "autonomous") && (entry.status === "pending" || entry.status === "unknown" || entry.status === "executed" || entry.status === "failed" || entry.status === "rejected") && typeof entry.createdAt === "string" && Boolean(entry.createdAt) && typeof entry.updatedAt === "string" && Boolean(entry.updatedAt);
+}
 function loadFile(env = process.env) {
 	const filePath = linksFilePath(env);
 	if (!syncFs.existsSync(filePath)) {
@@ -16,27 +24,20 @@ function loadFile(env = process.env) {
 	}
 	try {
 		const parsed = JSON.parse(syncFs.readFileSync(filePath, "utf8"));
-		if (parsed?.version === 1 && Array.isArray(parsed.links)) {
+		if (parsed?.version === 1 && Array.isArray(parsed.links) && parsed.links.every(isWalletSettlementLink)) {
 			return {
 				version: 1,
 				links: parsed.links
 			};
 		}
-	} catch {}
-	return {
-		version: 1,
-		links: []
-	};
+	} catch (error) {
+		throw new Error("wallet settlement state is unreadable; refusing to reset request links", { cause: error });
+	}
+	throw new Error("wallet settlement state has an unsupported shape; refusing to reset links");
 }
 function saveFile(file, env = process.env) {
 	const filePath = linksFilePath(env);
-	syncFs.writeFileSync(filePath, `${JSON.stringify(file, null, 2)}\n`, {
-		encoding: "utf8",
-		mode: 384
-	});
-	try {
-		syncFs.chmodSync(filePath, 384);
-	} catch {}
+	writeWalletStateFileAtomically(filePath, serializeWalletState(file));
 }
 function upsertWalletSettlementLink(params) {
 	const env = params.env ?? process.env;

package/dist/wallet/wallet-standard-review.js

@@ -0,0 +1,353 @@
+import { withFileLock } from "../plugin-sdk/file-lock.js";
+import "../infra/file-lock.js";
+import { ensureWalletStateDir } from "./wallet-runtime-config.js";
+import { fetchSolanaRpc } from "./solana-assets.js";
+import { WalletProviderError } from "./wallet-provider-adapter.js";
+import { broadcastReviewedSolanaTransaction, buildReviewedSolanaTransaction, computeReviewedSolanaRequestDigest, reconcileReviewedSolanaTransaction, validateReviewedSolanaSignedTransaction } from "./solana-reviewed-transaction.js";
+import syncFs from "node:fs";
+import path from "node:path";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+
+//#region src/wallet/wallet-standard-review.ts
+const REVIEW_FILE_NAME = "wallet-standard-reviews.v1.json";
+const REVIEW_TTL_MS = 2 * 60 * 1e3;
+const REVIEW_FILE_MODE = 384;
+const MAX_REVIEW_RECORDS = 1e4;
+const MAX_RETAINED_TERMINAL_REVIEWS = 5e3;
+const TERMINAL_REVIEW_RETENTION_MS = 30 * 24 * 60 * 6e4;
+const REVIEW_LOCK_OPTIONS = {
+	retries: {
+		retries: 80,
+		factor: 1.15,
+		minTimeout: 20,
+		maxTimeout: 200,
+		randomize: true
+	},
+	stale: 3e4
+};
+const SOLANA_MAINNET_GENESIS_HASH = "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+const SOLANA_DEVNET_GENESIS_HASH = "EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+let reviewStateLock = Promise.resolve();
+function reviewPath(env) {
+	return path.join(ensureWalletStateDir(env).rootDir, REVIEW_FILE_NAME);
+}
+function readFile(env) {
+	const filePath = reviewPath(env);
+	if (!syncFs.existsSync(filePath)) {
+		return {
+			version: 1,
+			reviews: []
+		};
+	}
+	try {
+		const parsed = JSON.parse(syncFs.readFileSync(filePath, "utf8"));
+		if (parsed.version === 1 && Array.isArray(parsed.reviews)) {
+			return parsed;
+		}
+	} catch {}
+	throw new WalletProviderError({
+		code: "wallet_provider_unavailable",
+		message: "Wallet Standard review state is invalid; repair it before approving Vault sends",
+		retryable: false
+	});
+}
+function saveFile(file, env) {
+	const filePath = reviewPath(env);
+	const temporary = `${filePath}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+	let descriptor;
+	try {
+		descriptor = syncFs.openSync(temporary, "wx", REVIEW_FILE_MODE);
+		syncFs.writeFileSync(descriptor, `${JSON.stringify(file, null, 2)}\n`, "utf8");
+		syncFs.fsyncSync(descriptor);
+		syncFs.closeSync(descriptor);
+		descriptor = undefined;
+		syncFs.renameSync(temporary, filePath);
+		try {
+			syncFs.chmodSync(filePath, REVIEW_FILE_MODE);
+		} catch {}
+		try {
+			const directory = syncFs.openSync(path.dirname(filePath), "r");
+			try {
+				syncFs.fsyncSync(directory);
+			} finally {
+				syncFs.closeSync(directory);
+			}
+		} catch {}
+	} catch (error) {
+		if (descriptor !== undefined) {
+			syncFs.closeSync(descriptor);
+		}
+		try {
+			syncFs.unlinkSync(temporary);
+		} catch {}
+		throw error;
+	}
+}
+function compactReviewState(file, nowMs = Date.now()) {
+	const terminal = file.reviews.filter((review) => review.status === "broadcast" || review.status === "failed").toSorted((left, right) => Date.parse(left.createdAt) - Date.parse(right.createdAt));
+	const removable = new Set(terminal.filter((review, index) => nowMs - Date.parse(review.createdAt) > TERMINAL_REVIEW_RETENTION_MS || terminal.length - index > MAX_RETAINED_TERMINAL_REVIEWS).map((review) => review.requestId));
+	return {
+		version: 1,
+		reviews: file.reviews.filter((review) => !removable.has(review.requestId))
+	};
+}
+function requireReviewCapacity(file) {
+	if (file.reviews.length >= MAX_REVIEW_RECORDS) {
+		throw new WalletProviderError({
+			code: "wallet_provider_unavailable",
+			message: "Wallet Standard review state reached its durable safety limit; reconcile unresolved reviews",
+			retryable: false
+		});
+	}
+}
+function secureEqual(left, right) {
+	const leftBytes = Buffer.from(left, "utf8");
+	const rightBytes = Buffer.from(right, "utf8");
+	return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes);
+}
+function rpcUrlDigest(rpcUrl) {
+	let normalized;
+	try {
+		const parsed = new URL(rpcUrl.trim());
+		if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+			throw new Error("unsupported protocol");
+		}
+		normalized = parsed.toString();
+	} catch {
+		throw new WalletProviderError({
+			code: "wallet_provider_invalid_config",
+			message: "Wallet Standard review requires a valid HTTP(S) Solana RPC URL"
+		});
+	}
+	return createHash("sha256").update(normalized, "utf8").digest("base64url");
+}
+async function resolveWalletStandardChain(rpcUrl) {
+	const genesisHash = await fetchSolanaRpc(rpcUrl, "getGenesisHash", []);
+	if (genesisHash === SOLANA_MAINNET_GENESIS_HASH) {
+		return "solana:mainnet";
+	}
+	if (genesisHash === SOLANA_DEVNET_GENESIS_HASH) {
+		return "solana:devnet";
+	}
+	throw new WalletProviderError({
+		code: "wallet_provider_invalid_config",
+		message: "Hardware Vault supports only verified Solana mainnet or devnet RPC endpoints"
+	});
+}
+async function withReviewLock(env, task) {
+	const run = async () => await withFileLock(reviewPath(env), REVIEW_LOCK_OPTIONS, async () => await task());
+	const current = reviewStateLock.then(run, run);
+	reviewStateLock = current.then(() => undefined, () => undefined);
+	return await current;
+}
+function toPrepareResult(record) {
+	return {
+		requestId: record.requestId,
+		preparedId: record.preparedId,
+		signer: record.signer,
+		unsignedTxBase64: record.unsignedTxBase64,
+		messageBase64: record.messageBase64,
+		intentDigest: record.intentDigest,
+		expiresAt: record.expiresAt,
+		chain: record.chain,
+		simulation: {
+			ok: true,
+			...typeof record.simulationUnitsConsumed === "number" && Number.isFinite(record.simulationUnitsConsumed) ? { unitsConsumed: record.simulationUnitsConsumed } : {}
+		}
+	};
+}
+async function prepareWalletStandardReview(params) {
+	const env = params.env ?? process.env;
+	const requestId = params.requestId.trim();
+	if (!requestId) {
+		throw new WalletProviderError({
+			code: "wallet_provider_invalid_config",
+			message: "Wallet Standard review requires an approval request ID"
+		});
+	}
+	return await withReviewLock(env, async () => {
+		const requestDigest = computeReviewedSolanaRequestDigest({
+			request: params.payload,
+			signer: params.signerAddress.trim()
+		});
+		const expectedRpcUrlDigest = rpcUrlDigest(params.rpcUrl);
+		const file = compactReviewState(readFile(env));
+		const existing = file.reviews.find((review) => review.requestId === requestId);
+		if (existing) {
+			const sameRequest = Boolean(existing.requestDigest) && secureEqual(existing.requestDigest, requestDigest);
+			const sameRpc = Boolean(existing.rpcUrlDigest) && secureEqual(existing.rpcUrlDigest, expectedRpcUrlDigest);
+			if (sameRequest && sameRpc && existing.status === "prepared" && Date.parse(existing.expiresAt) > Date.now()) {
+				return toPrepareResult(existing);
+			}
+			throw new WalletProviderError({
+				code: existing.status === "broadcasting" || existing.status === "unknown" ? "wallet_provider_ambiguous" : "wallet_provider_invalid_config",
+				message: "This approval request ID already has an immutable Wallet Standard review; create a new approval request",
+				retryable: false
+			});
+		}
+		requireReviewCapacity(file);
+		const chain = await resolveWalletStandardChain(params.rpcUrl);
+		const prepared = await buildReviewedSolanaTransaction({
+			request: params.payload,
+			signerAddress: params.signerAddress,
+			rpcUrl: params.rpcUrl
+		});
+		const now = Date.now();
+		const record = {
+			requestId,
+			preparedId: randomBytes(32).toString("base64url"),
+			createdAt: new Date(now).toISOString(),
+			expiresAt: new Date(now + REVIEW_TTL_MS).toISOString(),
+			status: "prepared",
+			signer: prepared.signer,
+			requestDigest,
+			intentDigest: prepared.intentDigest,
+			unsignedTxBase64: prepared.unsignedTxBase64,
+			messageBase64: prepared.messageBase64,
+			recentBlockhash: prepared.recentBlockhash,
+			lastValidBlockHeight: prepared.lastValidBlockHeight,
+			chain,
+			rpcUrlDigest: expectedRpcUrlDigest,
+			simulationUnitsConsumed: prepared.simulation.unitsConsumed
+		};
+		file.reviews.push(record);
+		saveFile(file, env);
+		return toPrepareResult(record);
+	});
+}
+async function executeLocked(params) {
+	const file = readFile(params.env);
+	const review = file.reviews.find((entry) => entry.requestId === params.requestId);
+	if (!review || !secureEqual(review.preparedId, params.preparedId)) {
+		throw new WalletProviderError({
+			code: "wallet_provider_invalid_config",
+			message: "Wallet Standard review is missing or does not match this approval"
+		});
+	}
+	if (!secureEqual(review.intentDigest, params.intentDigest)) {
+		throw new WalletProviderError({
+			code: "wallet_provider_invalid_config",
+			message: "Wallet Standard intent digest does not match the approved transaction"
+		});
+	}
+	if (!review.rpcUrlDigest || !secureEqual(review.rpcUrlDigest, rpcUrlDigest(params.rpcUrl))) {
+		throw new WalletProviderError({
+			code: "wallet_provider_invalid_config",
+			message: "Solana RPC configuration changed after review; approve again"
+		});
+	}
+	if (review.status === "broadcast" && review.txHash) {
+		return {
+			ok: true,
+			txHash: review.txHash,
+			signer: review.signer,
+			idempotent: true
+		};
+	}
+	if (review.status === "broadcasting" || review.status === "unknown") {
+		if (!review.txHash) {
+			throw new WalletProviderError({
+				code: "wallet_provider_ambiguous",
+				message: "Hardware-wallet broadcast is already in progress or unknown; do not submit it again",
+				retryable: false
+			});
+		}
+		let reconciled;
+		try {
+			reconciled = await reconcileReviewedSolanaTransaction({
+				rpcUrl: params.rpcUrl,
+				expectedTxHash: review.txHash,
+				lastValidBlockHeight: review.lastValidBlockHeight
+			});
+		} catch {
+			throw new WalletProviderError({
+				code: "wallet_provider_ambiguous",
+				message: `Hardware-wallet broadcast remains unknown; reconcile signature ${review.txHash} before any new send`,
+				retryable: false
+			});
+		}
+		if (reconciled.state === "landed") {
+			review.status = "broadcast";
+			saveFile(file, params.env);
+			return {
+				ok: true,
+				txHash: review.txHash,
+				signer: review.signer,
+				idempotent: true
+			};
+		}
+		if (reconciled.state === "failed" || reconciled.state === "expired") {
+			review.status = "failed";
+			review.failureReason = reconciled.state === "failed" ? reconciled.reason : `reviewed transaction expired at block height ${review.lastValidBlockHeight} without landing`;
+			saveFile(file, params.env);
+			throw new WalletProviderError({
+				code: "wallet_provider_unavailable",
+				message: `${review.failureReason}; create and approve a new Wallet Standard review`,
+				retryable: false
+			});
+		}
+		throw new WalletProviderError({
+			code: "wallet_provider_ambiguous",
+			message: `Hardware-wallet broadcast remains pending; reconcile signature ${review.txHash} before any new send`,
+			retryable: false
+		});
+	}
+	if (review.status === "failed") {
+		throw new WalletProviderError({
+			code: "wallet_provider_unavailable",
+			message: `${review.failureReason ?? "Wallet Standard transaction failed"}; create and approve a new Wallet Standard review`,
+			retryable: false
+		});
+	}
+	if (Date.parse(review.expiresAt) <= Date.now()) {
+		throw new WalletProviderError({
+			code: "wallet_provider_invalid_config",
+			message: "Hardware-wallet review expired; approve again to receive a fresh blockhash"
+		});
+	}
+	const verified = validateReviewedSolanaSignedTransaction({
+		unsignedTxBase64: review.unsignedTxBase64,
+		signedTxBase64: params.signedTxBase64,
+		signerAddress: review.signer
+	});
+	review.status = "broadcasting";
+	review.txHash = verified.txHash;
+	review.signedTxBase64 = verified.signedBytes.toString("base64");
+	saveFile(file, params.env);
+	try {
+		const txHash = await broadcastReviewedSolanaTransaction({
+			rpcUrl: params.rpcUrl,
+			signedTxBase64: review.signedTxBase64,
+			expectedTxHash: verified.txHash
+		});
+		review.status = "broadcast";
+		review.txHash = txHash;
+		saveFile(file, params.env);
+		return {
+			ok: true,
+			txHash,
+			signer: review.signer,
+			idempotent: false
+		};
+	} catch (error) {
+		review.status = "unknown";
+		saveFile(file, params.env);
+		throw error;
+	}
+}
+async function executeWalletStandardReview(params) {
+	const env = params.env ?? process.env;
+	const requestId = params.requestId.trim();
+	return await withReviewLock(env, async () => await executeLocked({
+		...params,
+		requestId,
+		env
+	}));
+}
+function readWalletStandardReviewTxHash(params) {
+	const file = readFile(params.env ?? process.env);
+	return file.reviews.find((review) => review.requestId === params.requestId.trim())?.txHash;
+}
+
+//#endregion
+export { executeWalletStandardReview, prepareWalletStandardReview, readWalletStandardReviewTxHash };