@fased/fased 0.1.64 → 0.1.66

package/dist/extensions/sat-mining/src/solana-submit.js

@@ -7,7 +7,7 @@ import { resolveWalletProviderId } from "../../../wallet/wallet-provider-resolve
 import { createSignerReviewApprovalRequest } from "../../../wallet/wallet-send-approvals.js";
 import "../../../plugin-sdk/sat-runtime.js";
 import { SAT_BOND_INSTRUCTION_DISCRIMINATORS, SAT_INSTRUCTION_DISCRIMINATORS, SAT_PROTOCOL_CONSTANTS, resolveSatGenesisProfileContract } from "./protocol-contract.js";
-import { inspectSatCycle, inspectSatCycleRegistryMeta, inspectSatMinerCyclesByAddress } from "./rpc-read.js";
+import { inspectSatAddressLookupTable, inspectSatChainSlot, inspectSatCycle, inspectSatCycleRegistryMeta, inspectSatMinerCyclesByAddress } from "./rpc-read.js";
 import { decodeHash32 } from "./hash-spec.js";
 import { resolveSatSignerCodec } from "./signer-codec-manifest.js";
 import { buildSatSubmissionOperationKey, claimSatSubmission, digestSatSubmissionIntent, updateSatSubmission, waitForSatSubmissionLease } from "./submission-ledger.js";
@@ -49,6 +49,8 @@ const MINING_STAKE_SEED = "mining_stake";
 const TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
 const ASSOCIATED_TOKEN_PROGRAM_ID = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
 const SLOT_HASHES_SYSVAR_ID = "SysvarS1otHashes111111111111111111111111111";
+const SAT_DISTRIBUTION_LOOKUP_MIN_MINERS = 16;
+const SAT_LOOKUP_TABLE_EXTEND_CHUNK_SIZE = 20;
 const IX = SAT_INSTRUCTION_DISCRIMINATORS;
 const BOND_IX = SAT_BOND_INSTRUCTION_DISCRIMINATORS;
 const VAULT_BOND_ACTIONS = new Set([
@@ -256,6 +258,7 @@ async function buildLocalSignerInstructionRequest(params) {
 			isSigner: key.isSigner,
 			isWritable: key.isWritable
 		})),
+		...params.spec.addressLookupTables?.length ? { addressLookupTables: params.spec.addressLookupTables } : {},
 		...context ? { context } : {}
 	};
 }
@@ -290,8 +293,9 @@ async function requireTypedSatSignerCapabilities(socketPath, intentType) {
 		"signerOwnedStateRecheck",
 		"durableReviewAuthorization"
 	].filter((feature) => !features.has(feature)) : [];
-	if (result.ready !== true || protocol?.current !== 2 || typeof protocol.min !== "number" || protocol.min > 2 || typeof protocol.max !== "number" || protocol.max < 2 || !capabilities?.intentTypes?.includes(intentType) || missingFeatures.length > 0 || intentType === "solana.vaultBondAction" && !features.has("typedVaultBondActions") || missingVaultReviewFeatures.length > 0 || missingStates.length > 0) {
-		throw new Error(`local-socket-signer does not support the required typed SAT protocol-v2 contract${missingFeatures.length > 0 ? `; missing features: ${missingFeatures.join(", ")}` : ""}${missingVaultReviewFeatures.length > 0 ? `; missing reviewed Vault features: ${missingVaultReviewFeatures.join(", ")}` : ""}${missingStates.length > 0 ? `; missing states: ${missingStates.join(", ")}` : ""}`);
+	const missingLookupFeatures = intentType === "solana.satLookupTable" && !features.has("typedSATAddressLookupTables") ? ["typedSATAddressLookupTables"] : [];
+	if (result.ready !== true || protocol?.current !== 2 || typeof protocol.min !== "number" || protocol.min > 2 || typeof protocol.max !== "number" || protocol.max < 2 || !capabilities?.intentTypes?.includes(intentType) || missingFeatures.length > 0 || missingLookupFeatures.length > 0 || intentType === "solana.vaultBondAction" && !features.has("typedVaultBondActions") || missingVaultReviewFeatures.length > 0 || missingStates.length > 0) {
+		throw new Error(`local-socket-signer does not support the required typed SAT protocol-v2 contract${missingFeatures.length > 0 ? `; missing features: ${missingFeatures.join(", ")}` : ""}${missingVaultReviewFeatures.length > 0 ? `; missing reviewed Vault features: ${missingVaultReviewFeatures.join(", ")}` : ""}${missingLookupFeatures.length > 0 ? `; missing SAT lookup features: ${missingLookupFeatures.join(", ")}` : ""}${missingStates.length > 0 ? `; missing states: ${missingStates.join(", ")}` : ""}`);
 	}
 }
 async function reconcileTypedSatOperation(params) {
@@ -320,6 +324,11 @@ function assertSatSignerOperationIdentity(operation, requestId) {
 function signerStateForLedger(state) {
 	return state;
 }
+function assertSatLookupTableAction(value) {
+	if (value !== "create" && value !== "extend" && value !== "deactivate" && value !== "close") {
+		throw new Error(`unsupported SAT lookup-table action ${value}`);
+	}
+}
 var SatSubmissionUnresolvedError = class extends Error {
 	constructor(params) {
 		super(`SAT signer operation ${params.requestId} remains ${params.state}${params.signature ? ` with signature ${params.signature}` : ""}; it is unresolved and must be reconciled with the same idempotency key before any new submission${params.detail ? ` (${params.detail})` : ""}`);
@@ -328,11 +337,29 @@ var SatSubmissionUnresolvedError = class extends Error {
 		this.signature = params.signature;
 	}
 };
+var SatSubmissionDefinitiveFailureError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "SatSubmissionDefinitiveFailureError";
+	}
+};
 async function executeTypedSatIntent(params) {
-	const isVaultBond = params.action !== "cleanupBatch" && VAULT_BOND_ACTIONS.has(params.action);
-	const intentType = isVaultBond ? "solana.vaultBondAction" : "solana.satAction";
+	const isLookupTable = params.lookupTable != null;
+	const isVaultBond = !isLookupTable && params.action !== "cleanupBatch" && VAULT_BOND_ACTIONS.has(params.action);
+	const intentType = isLookupTable ? "solana.satLookupTable" : isVaultBond ? "solana.vaultBondAction" : "solana.satAction";
 	await requireTypedSatSignerCapabilities(params.socketPath, intentType);
-	const intent = isVaultBond ? (() => {
+	const intent = isLookupTable ? (() => {
+		if (params.instruction || params.instructions || !params.lookupTable) {
+			throw new Error("typed SAT lookup-table execution accepts only semantic lookup details");
+		}
+		const action = params.action;
+		assertSatLookupTableAction(action);
+		return {
+			type: "solana.satLookupTable",
+			action,
+			lookupTable: params.lookupTable
+		};
+	})() : isVaultBond ? (() => {
 		if (!params.instruction || params.instructions) {
 			throw new Error("typed Vault bond execution requires exactly one semantic instruction");
 		}
@@ -364,6 +391,7 @@ async function executeTypedSatIntent(params) {
 		operationKey,
 		intentDigest,
 		action: params.action,
+		allowFailedRetry: isLookupTable,
 		env: params.env
 	});
 	if (!claim.claimed) {
@@ -378,6 +406,7 @@ async function executeTypedSatIntent(params) {
 			operationKey,
 			intentDigest,
 			action: params.action,
+			allowFailedRetry: isLookupTable,
 			env: params.env,
 			owner: claim.owner
 		});
@@ -622,7 +651,7 @@ async function executeTypedSatIntent(params) {
 		env: params.env
 	});
 	if (operation.state === "failed") {
-		throw new Error(operation.error || `SAT signer operation ${requestId} failed`);
+		throw new SatSubmissionDefinitiveFailureError(operation.error || `SAT signer operation ${requestId} failed`);
 	}
 	if (operation.state !== "confirmed" || !operation.signature) {
 		throw new SatSubmissionUnresolvedError({
@@ -637,9 +666,288 @@ async function executeTypedSatIntent(params) {
 		signature: operation.signature
 	};
 }
+function assertSatLookupTableEnabled(env) {
+	if (String(env.FASED_SAT_ENABLE_ALT_V0 ?? "").trim() !== "1") {
+		throw new Error("SAT ALT/v0 support is disabled; set FASED_SAT_ENABLE_ALT_V0=1");
+	}
+}
+async function executeTypedSatLookupOperation(params) {
+	return await executeTypedSatIntent({
+		socketPath: params.context.socketPath,
+		walletId: params.context.walletId,
+		action: params.action,
+		lookupTable: {
+			address: params.address,
+			cycleId: String(params.cycleId),
+			pageIndex: String(params.pageIndex),
+			...params.recentSlot == null ? {} : { recentSlot: String(params.recentSlot) },
+			...params.addresses?.length ? { addresses: params.addresses } : {},
+			...params.parent ? { parent: params.parent } : {}
+		},
+		cluster: resolveSatCluster(params.cfg),
+		env: params.context.effectiveEnv
+	});
+}
+async function readValidatedSatLookupTable(params) {
+	const state = await inspectSatAddressLookupTable(params.config, { address: params.address });
+	if (!state) {
+		return null;
+	}
+	if (state.authority !== params.authority) {
+		throw new Error("SAT distribution lookup table is not controlled by the Mining signer");
+	}
+	if (!state.active) {
+		throw new Error("SAT distribution lookup table is not active");
+	}
+	return state;
+}
+async function waitForSatLookupTable(params) {
+	let lastError;
+	for (let attempt = 0; attempt < 24; attempt += 1) {
+		try {
+			const state = await readValidatedSatLookupTable(params);
+			if (state) {
+				const currentSlot = await inspectSatChainSlot(params.config);
+				if (!params.requireNextSlot || currentSlot > state.lastExtendedSlot) {
+					return state;
+				}
+			}
+		} catch (error) {
+			lastError = error;
+		}
+		await new Promise((resolve) => setTimeout(resolve, 250));
+	}
+	throw new Error(`SAT distribution lookup table did not become active for use within 6s${lastError instanceof Error ? `: ${lastError.message}` : ""}`);
+}
+const SAT_LOOKUP_TABLE_CREATE_SLOT_WINDOW = 128;
+function recoverSatLookupTableRecentSlot(params) {
+	const oldestSlot = Math.max(0, params.currentSlot - SAT_LOOKUP_TABLE_CREATE_SLOT_WINDOW);
+	for (let recentSlot = params.currentSlot; recentSlot >= oldestSlot; recentSlot -= 1) {
+		const [, derivedAddress] = params.context.solana.AddressLookupTableProgram.createLookupTable({
+			authority: params.context.signer,
+			payer: params.context.signer,
+			recentSlot
+		});
+		if (derivedAddress.toBase58() === params.lookupTable) {
+			return recentSlot;
+		}
+	}
+	return undefined;
+}
+async function readReconciledSatLookupBinding(params) {
+	const request = {
+		cycleId: String(params.cycleId),
+		pageIndex: String(params.pageIndex)
+	};
+	const readBinding = async () => await callLocalSocketSigner(params.context.socketPath, {
+		op: "v2.satLookup.binding.get",
+		walletId: params.context.walletId,
+		request
+	});
+	const binding = await readBinding();
+	if (binding.cycleId !== request.cycleId || binding.pageIndex !== request.pageIndex || binding.bound !== Boolean(binding.address) || Boolean(binding.mutationRequestId) !== Boolean(binding.mutationState)) {
+		throw new Error("signer returned an invalid SAT lookup-table binding");
+	}
+	if (binding.mutationState === "reserved") {
+		throw new Error("SAT lookup-table mutation is already in progress");
+	}
+	if ((binding.mutationState === "broadcast" || binding.mutationState === "unknown") && binding.mutationRequestId) {
+		const operation = assertSatSignerOperationIdentity(await callLocalSocketSigner(params.context.socketPath, {
+			op: "v2.operation.reconcile",
+			walletId: params.context.walletId,
+			request: { requestId: binding.mutationRequestId }
+		}), binding.mutationRequestId);
+		if (operation.state === "reserved" || operation.state === "broadcast" || operation.state === "unknown") {
+			throw new SatSubmissionUnresolvedError({
+				requestId: operation.requestId,
+				state: operation.state,
+				signature: operation.signature,
+				detail: operation.error
+			});
+		}
+		const reconciled = await readBinding();
+		if (reconciled.cycleId !== request.cycleId || reconciled.pageIndex !== request.pageIndex || reconciled.bound !== Boolean(reconciled.address) || Boolean(reconciled.mutationRequestId) !== Boolean(reconciled.mutationState)) {
+			throw new Error("signer returned an invalid reconciled SAT lookup-table binding");
+		}
+		return reconciled;
+	}
+	return binding;
+}
+async function ensureSatDistributionLookupTable(params) {
+	assertSatLookupTableEnabled(params.context.effectiveEnv);
+	const desiredAddresses = [...new Set(params.addresses.map((entry) => entry.trim()))].filter(Boolean);
+	if (desiredAddresses.length === 0 || desiredAddresses.length > 256) {
+		throw new Error("SAT distribution lookup table requires 1-256 exact account addresses");
+	}
+	const signerBinding = await readReconciledSatLookupBinding({
+		context: params.context,
+		cycleId: params.cycleId,
+		pageIndex: params.pageIndex
+	});
+	let lookupTable = signerBinding.address?.trim() || "";
+	if (signerBinding.bound && lookupTable) {
+		await params.onLookupTableResolved?.(lookupTable);
+	}
+	let state = lookupTable ? await readValidatedSatLookupTable({
+		config: params.config,
+		address: lookupTable,
+		authority: params.context.signerAddress
+	}) : null;
+	if (lookupTable && state) {
+		await params.onLookupTableResolved?.(lookupTable);
+	}
+	let created = false;
+	const transactionHashes = [];
+	let createRecentSlot;
+	const attemptedCreateAddresses = new Set();
+	if (lookupTable && !state) {
+		const currentSlot = await inspectSatChainSlot(params.config);
+		createRecentSlot = recoverSatLookupTableRecentSlot({
+			context: params.context,
+			lookupTable,
+			currentSlot
+		});
+		if (createRecentSlot == null) {
+			if (signerBinding.bound) {
+				throw new Error("SAT distribution lookup table identity is not recoverable within the signer freshness window");
+			}
+			lookupTable = "";
+		} else {
+			attemptedCreateAddresses.add(lookupTable);
+			await params.onLookupTableResolved?.(lookupTable);
+		}
+	}
+	while (!state) {
+		if (!lookupTable || createRecentSlot == null) {
+			const currentSlot = await inspectSatChainSlot(params.config);
+			const oldestSlot = Math.max(0, currentSlot - SAT_LOOKUP_TABLE_CREATE_SLOT_WINDOW);
+			let selected = false;
+			for (let recentSlot = Math.max(0, currentSlot - 1); recentSlot >= oldestSlot; recentSlot -= 1) {
+				const [, derivedAddress] = params.context.solana.AddressLookupTableProgram.createLookupTable({
+					authority: params.context.signer,
+					payer: params.context.signer,
+					recentSlot
+				});
+				const candidate = derivedAddress.toBase58();
+				if (attemptedCreateAddresses.has(candidate)) {
+					continue;
+				}
+				attemptedCreateAddresses.add(candidate);
+				const existingCandidate = await readValidatedSatLookupTable({
+					config: params.config,
+					address: candidate,
+					authority: params.context.signerAddress
+				});
+				if (existingCandidate) {
+					continue;
+				}
+				lookupTable = candidate;
+				createRecentSlot = recentSlot;
+				await params.onLookupTableResolved?.(lookupTable);
+				selected = true;
+				break;
+			}
+			if (!selected) {
+				throw new Error("SAT distribution lookup table has no free signer-owned address in the freshness window");
+			}
+		}
+		try {
+			const submitted = await executeTypedSatLookupOperation({
+				context: params.context,
+				cfg: params.cfg,
+				action: "create",
+				address: lookupTable,
+				cycleId: params.cycleId,
+				pageIndex: params.pageIndex,
+				recentSlot: createRecentSlot,
+				parent: params.parent
+			});
+			transactionHashes.push(submitted.signature);
+			created = true;
+		} catch (error) {
+			if (error instanceof SatSubmissionDefinitiveFailureError && error.message.includes("address is already bound to another cycle and page")) {
+				lookupTable = "";
+				createRecentSlot = undefined;
+				continue;
+			}
+			if (error instanceof SatSubmissionUnresolvedError || error instanceof SatSubmissionDefinitiveFailureError) {
+				throw error;
+			}
+			try {
+				state = await waitForSatLookupTable({
+					config: params.config,
+					address: lookupTable,
+					authority: params.context.signerAddress,
+					requireNextSlot: false
+				});
+			} catch {
+				throw error;
+			}
+		}
+		state ??= await waitForSatLookupTable({
+			config: params.config,
+			address: lookupTable,
+			authority: params.context.signerAddress,
+			requireNextSlot: false
+		});
+		break;
+	}
+	if (!state) {
+		throw new Error("SAT distribution lookup table was not found at the confirmed commitment");
+	}
+	const existing = new Set(state.addresses);
+	const missing = desiredAddresses.filter((entry) => !existing.has(entry));
+	for (let offset = 0; offset < missing.length; offset += SAT_LOOKUP_TABLE_EXTEND_CHUNK_SIZE) {
+		const addresses = missing.slice(offset, offset + SAT_LOOKUP_TABLE_EXTEND_CHUNK_SIZE);
+		try {
+			const submitted = await executeTypedSatLookupOperation({
+				context: params.context,
+				cfg: params.cfg,
+				action: "extend",
+				address: lookupTable,
+				cycleId: params.cycleId,
+				pageIndex: params.pageIndex,
+				addresses,
+				parent: params.parent
+			});
+			transactionHashes.push(submitted.signature);
+		} catch (error) {
+			if (error instanceof SatSubmissionUnresolvedError) {
+				throw error;
+			}
+			const concurrentState = await waitForSatLookupTable({
+				config: params.config,
+				address: lookupTable,
+				authority: params.context.signerAddress,
+				requireNextSlot: false
+			}).catch(() => null);
+			if (!concurrentState || addresses.some((address) => !concurrentState.addresses.includes(address))) {
+				throw error;
+			}
+		}
+	}
+	const ready = await waitForSatLookupTable({
+		config: params.config,
+		address: lookupTable,
+		authority: params.context.signerAddress,
+		requireNextSlot: true
+	});
+	for (const address of desiredAddresses) {
+		if (!ready.addresses.includes(address)) {
+			throw new Error(`SAT distribution lookup table did not persist required account ${address}`);
+		}
+	}
+	return {
+		lookupTable,
+		created,
+		extended: missing.length > 0,
+		addressCount: ready.addresses.length,
+		transactionHashes
+	};
+}
 async function submitInstructionViaLocalSigner(params) {
 	const context = await prepareLocalSignerSubmitContext(params.cfg, params.env);
-	const request = await buildLocalSignerInstructionRequest({
+	const baseRequest = await buildLocalSignerInstructionRequest({
 		solana: context.solana,
 		signer: context.signer,
 		env: context.effectiveEnv,
@@ -648,6 +956,27 @@ async function submitInstructionViaLocalSigner(params) {
 	if (!context.walletId) {
 		throw new Error("typed SAT signing requires an explicit mining walletId");
 	}
+	let managedLookupTable;
+	if (params.manageAddressLookupTable) {
+		managedLookupTable = await ensureSatDistributionLookupTable({
+			context: {
+				...context,
+				walletId: context.walletId
+			},
+			cfg: params.cfg,
+			config: params.cfg,
+			lookupTableAddress: params.manageAddressLookupTable.lookupTableAddress,
+			cycleId: params.manageAddressLookupTable.cycleId,
+			pageIndex: params.manageAddressLookupTable.pageIndex,
+			addresses: baseRequest.keys.filter((key) => !key.isSigner).map((key) => key.pubkey),
+			parent: baseRequest,
+			onLookupTableResolved: params.manageAddressLookupTable.onLookupTableResolved
+		});
+	}
+	const request = managedLookupTable ? {
+		...baseRequest,
+		addressLookupTables: [managedLookupTable.lookupTable]
+	} : baseRequest;
 	const submitted = await executeTypedSatIntent({
 		socketPath: context.socketPath,
 		walletId: context.walletId,
@@ -660,7 +989,17 @@ async function submitInstructionViaLocalSigner(params) {
 		txHash: submitted.signature,
 		signer: context.signerAddress,
 		signerState: submitted.state,
-		requestId: submitted.requestId
+		requestId: submitted.requestId,
+		...request.addressLookupTables?.length ? {
+			transactionVersion: "v0",
+			lookupTableAddress: request.addressLookupTables[0]
+		} : { transactionVersion: "legacy" },
+		...managedLookupTable ? {
+			lookupTableCreated: managedLookupTable.created,
+			lookupTableExtended: managedLookupTable.extended,
+			lookupTableAddressCount: managedLookupTable.addressCount,
+			lookupTableTransactionHashes: managedLookupTable.transactionHashes
+		} : {}
 	};
 }
 async function submitInstruction(params) {
@@ -673,6 +1012,8 @@ async function submitInstruction(params) {
 		env: effectiveEnv,
 		data: params.data,
 		programId: params.programId,
+		addressLookupTables: params.addressLookupTables,
+		manageAddressLookupTable: params.manageAddressLookupTable,
 		accountResolver: params.accountResolver
 	});
 }
@@ -2530,10 +2871,18 @@ async function submitSatScoreCyclePage(_config, params) {
 }
 async function submitSatDistributeCyclePage(_config, params) {
 	const cfg = loadConfigForSatRuntime(_config);
+	const lookupTableAddress = params.lookupTableAddress?.trim() ?? "";
+	const requiresLookupTable = (params.minerCycleAccounts?.length ?? 0) >= SAT_DISTRIBUTION_LOOKUP_MIN_MINERS;
 	return submitInstruction({
 		cfg,
 		env: process.env,
 		data: buildDistributeCyclePageData(params),
+		...lookupTableAddress || requiresLookupTable ? { manageAddressLookupTable: {
+			cycleId: params.cycleId,
+			pageIndex: params.pageIndex,
+			...lookupTableAddress ? { lookupTableAddress } : {},
+			...params.onLookupTableResolved ? { onLookupTableResolved: params.onLookupTableResolved } : {}
+		} } : {},
 		accountResolver: async (solana, signer) => {
 			const programId = new solana.PublicKey(SAT_PROGRAM_ID());
 			const [satCycleState] = solana.PublicKey.findProgramAddressSync([Buffer.from(SAT_CYCLE_STATE_SEED), encodeU64(params.cycleId)], programId);
@@ -2635,6 +2984,44 @@ async function submitSatDistributeCyclePage(_config, params) {
 		}
 	});
 }
+async function submitSatCleanupDistributionLookupTable(_config, params) {
+	const cfg = loadConfigForSatRuntime(_config);
+	const context = await prepareLocalSignerSubmitContext(cfg, process.env);
+	assertSatLookupTableEnabled(context.effectiveEnv);
+	if (!context.walletId) {
+		throw new Error("typed SAT lookup-table cleanup requires an explicit mining walletId");
+	}
+	const binding = await readReconciledSatLookupBinding({
+		context: {
+			...context,
+			walletId: context.walletId
+		},
+		cycleId: params.cycleId,
+		pageIndex: params.pageIndex
+	});
+	const lookupTable = binding.address?.trim() ?? "";
+	if (binding.cycleId !== String(params.cycleId) || binding.pageIndex !== String(params.pageIndex) || !binding.bound || !lookupTable) {
+		throw new Error("SAT distribution lookup table is not bound to this wallet, cycle, and page");
+	}
+	const submitted = await executeTypedSatLookupOperation({
+		context: {
+			...context,
+			walletId: context.walletId
+		},
+		cfg,
+		action: params.action,
+		address: lookupTable,
+		cycleId: params.cycleId,
+		pageIndex: params.pageIndex
+	});
+	return {
+		lookupTable,
+		action: params.action,
+		transactionHashes: [submitted.signature],
+		signerState: submitted.state,
+		requestId: submitted.requestId
+	};
+}
 async function submitSatClaimCycleRewards(_config, params) {
 	const cfg = loadConfigForSatRuntime(_config);
 	return submitInstruction({

package/dist/extensions/sat-mining/src/submission-ledger.js

@@ -63,7 +63,7 @@ function buildSatSubmissionOperationKey(intent) {
 			action: candidate.action,
 			keys: candidate.keys
 		};
-	}) : intent.keys;
+	}) : intent.keys ?? intent.lookupTable;
 	return `${action}:${sha256(JSON.stringify(canonicalize(accountShape))).slice(0, 24)}`;
 }
 function normalizeStateKey(value) {
@@ -223,13 +223,33 @@ async function claimSatSubmission(params) {
 		walletId: params.walletId,
 		env
 	});
-	const requestId = buildSatSubmissionRequestId(params);
 	const owner = params.owner ?? `${process.pid}:${randomUUID()}`;
 	return await withSatSubmissionLedgerLock(filePath, async () => {
 		const ledger = await readLedger(filePath);
+		let operationKey = params.operationKey;
+		let requestId = buildSatSubmissionRequestId({
+			...params,
+			operationKey
+		});
+		if (params.allowFailedRetry) {
+			for (let retry = 1; retry <= 32; retry += 1) {
+				const prior = ledger.records[requestId];
+				if (!prior || prior.state !== "failed") {
+					break;
+				}
+				operationKey = `${params.operationKey}:retry:${retry}`;
+				requestId = buildSatSubmissionRequestId({
+					...params,
+					operationKey
+				});
+				if (retry === 32 && ledger.records[requestId]?.state === "failed") {
+					throw new Error("SAT submission exhausted its safe pre-broadcast retry limit");
+				}
+			}
+		}
 		const existing = ledger.records[requestId];
 		if (existing) {
-			if (existing.intentDigest !== params.intentDigest || existing.walletId !== params.walletId || existing.workflowId !== params.workflowId || existing.operationKey !== params.operationKey) {
+			if (existing.intentDigest !== params.intentDigest || existing.walletId !== params.walletId || existing.workflowId !== params.workflowId || existing.operationKey !== operationKey) {
 				throw new Error(`SAT idempotency collision for ${requestId}: the workflow key is already bound to a different immutable intent digest`);
 			}
 			if (leaseIsLive(existing.lease) && existing.lease?.owner !== owner) {
@@ -261,7 +281,7 @@ async function claimSatSubmission(params) {
 		const record = {
 			requestId,
 			workflowId: params.workflowId,
-			operationKey: params.operationKey,
+			operationKey,
 			intentDigest: params.intentDigest,
 			walletId: params.walletId,
 			action: params.action,

package/dist/federation/marketplace-delivery-outbox.js

@@ -3,7 +3,7 @@ import { resolveProcessScopedMap } from "../shared/process-scoped-map.js";
 import { acquireFileLock, withFileLock } from "../plugin-sdk/file-lock.js";
 import "../infra/file-lock.js";
 import { serializeWalletState, writeWalletStateFileAtomically } from "../wallet/wallet-atomic-state.js";
-import syncFs from "node:fs";
+import fs from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
 
@@ -85,17 +85,17 @@ function readMarketplaceDeliveryOutbox(params) {
 		return null;
 	}
 	const filePath = recordPath(deliveryId, params.env ?? process.env);
-	if (!syncFs.existsSync(filePath)) {
+	if (!fs.existsSync(filePath)) {
 		return null;
 	}
 	try {
-		return validateRecord(JSON.parse(syncFs.readFileSync(filePath, "utf8")), deliveryId);
+		return validateRecord(JSON.parse(fs.readFileSync(filePath, "utf8")), deliveryId);
 	} catch (error) {
 		throw new Error("marketplace delivery outbox is unreadable; refusing to resend", { cause: error });
 	}
 }
 function writeRecord(record, env) {
-	syncFs.mkdirSync(outboxDirectory(env), {
+	fs.mkdirSync(outboxDirectory(env), {
 		recursive: true,
 		mode: 448
 	});
@@ -109,7 +109,7 @@ async function reserveMarketplaceDelivery(params) {
 		throw new Error("marketplace delivery identity is incomplete");
 	}
 	const intentDigest = marketplaceDeliveryIntentDigest(params.intent);
-	syncFs.mkdirSync(outboxDirectory(env), {
+	fs.mkdirSync(outboxDirectory(env), {
 		recursive: true,
 		mode: 448
 	});

package/dist/federation/marketplace-settlement-ledger.js

@@ -3,7 +3,7 @@ import { acquireFileLock } from "../plugin-sdk/file-lock.js";
 import "../infra/file-lock.js";
 import { ensureWalletStateDir } from "../wallet/wallet-runtime-config.js";
 import { serializeWalletState, writeWalletStateFileAtomically } from "../wallet/wallet-atomic-state.js";
-import syncFs from "node:fs";
+import fs from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
 
@@ -119,11 +119,11 @@ function lockTarget(orderId, env) {
 }
 function readEntry(orderId, env) {
 	const filePath = entryPath(orderId, env);
-	if (!syncFs.existsSync(filePath)) {
+	if (!fs.existsSync(filePath)) {
 		return null;
 	}
 	try {
-		const value = JSON.parse(syncFs.readFileSync(filePath, "utf8"));
+		const value = JSON.parse(fs.readFileSync(filePath, "utf8"));
 		if (value.version !== 1 || value.orderId !== orderId || typeof value.phase !== "string" || !PHASES.has(value.phase) || !value.actions || Array.isArray(value.actions) || typeof value.actions !== "object" || typeof value.createdAt !== "string" || typeof value.updatedAt !== "string") {
 			throw new Error("invalid shape");
 		}
@@ -148,7 +148,7 @@ function readEntry(orderId, env) {
 	}
 }
 function writeEntry(entry, env) {
-	syncFs.mkdirSync(stateDirectory(env), {
+	fs.mkdirSync(stateDirectory(env), {
 		recursive: true,
 		mode: 448
 	});