@fased/fased 0.1.61 → 0.1.64

package/dist/extensions/sat-mining/src/rpc-read.js

@@ -1,4 +1,5 @@
 import { loadConfig } from "../../../config/io.js";
+import { fetchWithSsrFGuard } from "../../../infra/net/fetch-guard.js";
 import { redactSensitiveUrlLikeString } from "../../../shared/net/redact-sensitive-url.js";
 import { readWalletProviderRegistry } from "../../../wallet/wallet-provider-registry.js";
 import { resolveSatBondProgramIdFromEnv, resolveSatMintAddressFromEnv, resolveSatProgramIdFromEnv } from "../../../config/sat-runtime-ids.js";
@@ -6,6 +7,7 @@ import { loadWalletProviderSecret } from "../../../wallet/wallet-secrets-store.j
 import { resolveWalletProviderId } from "../../../wallet/wallet-provider-resolver.js";
 import "../../../plugin-sdk/index.js";
 import "../../../plugin-sdk/sat-runtime.js";
+import { SAT_PROTOCOL_CONSTANTS, resolveSatGenesisProfileContract } from "./protocol-contract.js";
 import { loadSatBondLayout, loadSatBondPolicyLayout, loadSatBondStakingDistributorLayout, loadSatBondStakingPositionLayout } from "./sat-bond-layout.js";
 import { createRequire } from "node:module";
 import { createHash } from "node:crypto";
@@ -311,15 +313,19 @@ function decodeSatGlobalState(data, address) {
 }
 function decodeSatCycle(data, address) {
 	const body = expectAccountData(data, ACCOUNT_DISCRIMINATOR.satCycleState, "SAT cycle state");
+	const validMinerCount = readU64String(body, 192);
+	const cycleSeed = readHash32(body, 40);
 	return {
 		address,
 		cycleId: readU64Number(body, 0),
 		openTs: readI64Number(body, 8),
 		closeTs: readI64Number(body, 16),
 		status: body.readUInt8(24),
+		cycleSeed,
+		entropyUnavailable: cycleSeed === SAT_PROTOCOL_CONSTANTS.entropyUnavailableSeedHex,
 		unlockTargetLamports: readU64String(body, 176),
 		totalCommittedLamports: readU64String(body, 184),
-		validMinerCount: readU64String(body, 192),
+		validMinerCount,
 		unlockRatioFp: readU64String(body, 200),
 		issuedCycleMinerSatRaw: readU64String(body, 208),
 		unissuedCycleMinerSatRaw: readU64String(body, 216),
@@ -328,7 +334,22 @@ function decodeSatCycle(data, address) {
 		performanceRebatePoolLamports: readU64String(body, 240),
 		treasurySolLamports: readU64String(body, 248),
 		submittedSolErosionPoolLamports: readU64String(body, 256),
-		keeperBountyPaidLamports: readU64String(body, 264)
+		keeperBountyPaidLamports: readU64String(body, 264),
+		commitDeadlineTs: readI64Number(body, 272),
+		revealDeadlineTs: readI64Number(body, 280),
+		entropyTargetSlot: readU64Number(body, 288),
+		committedMinerCount: readU64String(body, 296),
+		revealedMinerCount: validMinerCount,
+		resolvedCommitCount: readU64String(body, 304),
+		entropySealedSlot: readU64Number(body, 312),
+		...body.length >= 368 ? {
+			openSlot: readU64Number(body, 320),
+			commitDeadlineSlot: readU64Number(body, 328),
+			revealDeadlineSlot: readU64Number(body, 336),
+			entropyHashCount: readU64Number(body, 344),
+			unlockIntervalStartCycleId: readU64Number(body, 352),
+			releasedCommitCount: readU64String(body, 360)
+		} : {}
 	};
 }
 function decodeSatMinerCycle(data, address) {
@@ -351,7 +372,13 @@ function decodeSatMinerCycle(data, address) {
 		claimedDetRebateLamports: readU64String(body, 160),
 		claimedPerfRebateLamports: readU64String(body, 168),
 		validParticipation: body.readUInt8(176) === 1,
-		capitalLockReleased: body.readUInt8(177) === 1
+		capitalLockReleased: body.readUInt8(177) === 1,
+		...body.length >= 336 ? {
+			commitment: readHash32(body, 184),
+			commitSlot: readU64Number(body, 216),
+			revealSlot: readU64Number(body, 224)
+		} : {},
+		...body.length >= 344 ? { lockedCollateralLamports: readU64String(body, 232) } : {}
 	};
 }
 function decodeSatMinerCapital(data, address) {
@@ -476,6 +503,8 @@ function decodeSatBondStakingDistributor(data, address) {
 		totalActiveStakeRaw: readU64String(body, layout.offsets.totalActiveStakeRaw),
 		rewardIndexFp: readU128String(body, layout.offsets.rewardIndexFp),
 		observedRewardVaultRaw: readU64String(body, layout.offsets.observedRewardVaultRaw),
+		unallocatedRewardRaw: readU64String(body, layout.offsets.unallocatedRewardRaw),
+		fractionalRemainderFp: readU64String(body, layout.offsets.fractionalRemainderFp),
 		lastSyncedSlot: readU64Number(body, layout.offsets.lastSyncedSlot),
 		mintMatchesRuntime: rewardMint === SAT_MINT_ADDRESS(),
 		vaultMatchesExpected: rewardVault === expectedRewardVault
@@ -497,6 +526,7 @@ function decodeSatBondStakingPosition(data, address) {
 		activeStakeRaw: readU64String(body, layout.offsets.activeStakeRaw),
 		claimableRewardRaw: readU64String(body, layout.offsets.claimableRewardRaw),
 		rewardDebtFp: readU128String(body, layout.offsets.rewardDebtFp),
+		fractionalRemainderFp: readU64String(body, layout.offsets.fractionalRemainderFp),
 		lastSyncedSlot: readU64Number(body, layout.offsets.lastSyncedSlot)
 	};
 }
@@ -723,6 +753,7 @@ const satReadRpcRuntimeState = {
 	lastRpcUrl: null,
 	quotaLikely: false
 };
+const satReadRpcEndpointStates = new Map();
 function readPositiveIntEnv(name, fallback) {
 	const value = Number.parseInt(String(process.env[name] ?? ""), 10);
 	return Number.isFinite(value) && value > 0 ? value : fallback;
@@ -736,6 +767,13 @@ const SAT_RPC_RENT_EXEMPTION_CACHE_TTL_MS = 5 * 6e4;
 const SAT_RPC_METHOD_METRIC_BUCKET_MS = 60 * 6e4;
 const SAT_RPC_METHOD_METRIC_RETENTION_MS = 24 * 60 * 6e4;
 const SAT_RPC_QUOTA_BACKOFF_MS = 3e4;
+const SAT_RPC_FAILURE_BACKOFF_THRESHOLD = 2;
+const SAT_RPC_FAILURE_BACKOFF_BASE_MS = 5e3;
+const SAT_RPC_FAILURE_BACKOFF_MAX_MS = 3e4;
+const SAT_RPC_MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
+function satRpcRequestTimeoutMs() {
+	return readPositiveIntEnv("FASED_SAT_RPC_REQUEST_TIMEOUT_MS", 1e4);
+}
 const satRpcReadCache = new Map();
 const satRpcReadInFlight = new Map();
 const satRpcMethodMetrics = new Map();
@@ -894,36 +932,75 @@ function looksLikeRpcQuotaFailure(value) {
 	}
 	return message.includes("429") || message.includes("rate limit") || message.includes("too many requests") || message.includes("quota") || message.includes("credit") || message.includes("credits exhausted") || message.includes("resource exhausted");
 }
-function currentReadRpcQuotaBackoffMs(nowMs = Date.now()) {
-	if (!satReadRpcRuntimeState.quotaLikely || !satReadRpcRuntimeState.lastFailureAt) {
-		return 0;
+function getOrCreateReadRpcEndpointState(rpcUrl) {
+	const key = normalizeRpcUrlForComparison(rpcUrl);
+	const existing = satReadRpcEndpointStates.get(key);
+	if (existing) {
+		return existing;
 	}
-	const failedAtMs = Date.parse(satReadRpcRuntimeState.lastFailureAt);
-	if (!Number.isFinite(failedAtMs)) {
+	const created = {
+		consecutiveFailures: 0,
+		backoffUntilMs: 0,
+		quotaLikely: false,
+		lastError: null,
+		lastFailureAt: null,
+		lastSuccessAt: null
+	};
+	satReadRpcEndpointStates.set(key, created);
+	return created;
+}
+function currentReadRpcBackoffMs(rpcUrl, nowMs = Date.now()) {
+	const state = satReadRpcEndpointStates.get(normalizeRpcUrlForComparison(rpcUrl));
+	if (!state) {
 		return 0;
 	}
-	const remainingMs = SAT_RPC_QUOTA_BACKOFF_MS - (nowMs - failedAtMs);
-	return remainingMs > 0 ? remainingMs : 0;
+	return Math.max(0, state.backoffUntilMs - nowMs);
+}
+function makeReadRpcBackoffError(method, remainingMs) {
+	return new Error(`rpc ${method} skipped during endpoint circuit backoff; retry in ${Math.ceil(remainingMs / 1e3)}s`);
 }
-function makeReadRpcQuotaBackoffError(method, remainingMs) {
-	return new Error(`rpc ${method} skipped during provider quota backoff; retry in ${Math.ceil(remainingMs / 1e3)}s`);
+function markReadRpcEndpointSuccess(rpcUrl) {
+	const state = getOrCreateReadRpcEndpointState(rpcUrl);
+	state.consecutiveFailures = 0;
+	state.backoffUntilMs = 0;
+	state.quotaLikely = false;
+	state.lastError = null;
+	state.lastSuccessAt = new Date().toISOString();
+}
+function markReadRpcEndpointFailure(rpcUrl, error) {
+	const state = getOrCreateReadRpcEndpointState(rpcUrl);
+	const message = error instanceof Error ? error.message : String(error);
+	const quotaLikely = looksLikeRpcQuotaFailure(message);
+	state.consecutiveFailures += 1;
+	state.quotaLikely = quotaLikely;
+	state.lastError = message;
+	state.lastFailureAt = new Date().toISOString();
+	if (quotaLikely) {
+		state.backoffUntilMs = Date.now() + SAT_RPC_QUOTA_BACKOFF_MS;
+	} else if (state.consecutiveFailures >= SAT_RPC_FAILURE_BACKOFF_THRESHOLD) {
+		const exponent = state.consecutiveFailures - SAT_RPC_FAILURE_BACKOFF_THRESHOLD;
+		state.backoffUntilMs = Date.now() + Math.min(SAT_RPC_FAILURE_BACKOFF_MAX_MS, SAT_RPC_FAILURE_BACKOFF_BASE_MS * 2 ** exponent);
+	}
 }
 function markReadRpcSuccess(mode, rpcUrl) {
+	markReadRpcEndpointSuccess(rpcUrl);
 	satReadRpcRuntimeState.lastMode = mode;
 	satReadRpcRuntimeState.lastRpcUrl = rpcUrl;
-	satReadRpcRuntimeState.lastError = null;
 	satReadRpcRuntimeState.lastSuccessAt = new Date().toISOString();
-	satReadRpcRuntimeState.quotaLikely = false;
-	if (mode === "fallback") {
+	if (mode === "primary") {
+		satReadRpcRuntimeState.lastError = null;
+		satReadRpcRuntimeState.quotaLikely = false;
+	} else {
 		satReadRpcRuntimeState.fallbackCount += 1;
 	}
 }
-function markReadRpcFailure(error) {
+function markReadRpcFailure(error, rpcUrl) {
 	const message = error instanceof Error ? error.message : String(error);
+	markReadRpcEndpointFailure(rpcUrl, error);
 	satReadRpcRuntimeState.lastMode = "unavailable";
 	satReadRpcRuntimeState.lastError = message;
 	satReadRpcRuntimeState.lastFailureAt = new Date().toISOString();
-	satReadRpcRuntimeState.quotaLikely = looksLikeRpcQuotaFailure(message);
+	satReadRpcRuntimeState.quotaLikely = satReadRpcRuntimeState.quotaLikely || looksLikeRpcQuotaFailure(message);
 }
 function firstNonEmpty(...values) {
 	for (const value of values) {
@@ -1044,9 +1121,9 @@ function resolveReadRpcConfig(cfg, env) {
 	const walletId = typeof satMiningConfig.walletId === "string" ? String(satMiningConfig.walletId).trim() : undefined;
 	const registryProviderId = walletId ? readWalletProviderRegistry(env).wallets.find((wallet) => wallet.id === walletId)?.providerId : undefined;
 	const providerId = registryProviderId || resolveWalletProviderId(cfg, env);
-	const walletReadRpcUrl = walletEnvValue(env, "FASED_WALLET_SOLANA_READ_RPC_URL", walletId) || walletEnvValue(env, "FASED_WALLET_EMBEDDED_KEYSTORE_READ_RPC_URL", walletId);
-	const walletRpcUrl = walletEnvValue(env, "FASED_WALLET_SOLANA_RPC_URL", walletId) || walletEnvValue(env, "FASED_WALLET_EMBEDDED_KEYSTORE_RPC_URL", walletId);
-	const walletReadRpcFallbackUrl = walletEnvValue(env, "FASED_WALLET_SOLANA_READ_RPC_FALLBACK_URL", walletId) || walletEnvValue(env, "FASED_WALLET_SOLANA_RPC_FALLBACK_URL", walletId) || walletEnvValue(env, "FASED_WALLET_EMBEDDED_KEYSTORE_READ_RPC_FALLBACK_URL", walletId) || walletEnvValue(env, "FASED_WALLET_EMBEDDED_KEYSTORE_RPC_FALLBACK_URL", walletId);
+	const walletReadRpcUrl = walletEnvValue(env, "FASED_WALLET_SOLANA_READ_RPC_URL", walletId);
+	const walletRpcUrl = walletEnvValue(env, "FASED_WALLET_SOLANA_RPC_URL", walletId);
+	const walletReadRpcFallbackUrl = walletEnvValue(env, "FASED_WALLET_SOLANA_READ_RPC_FALLBACK_URL", walletId) || walletEnvValue(env, "FASED_WALLET_SOLANA_RPC_FALLBACK_URL", walletId);
 	if (providerId === "local-socket-signer") {
 		const primaryUrl = firstNonEmpty(walletReadRpcUrl, walletRpcUrl);
 		if (!primaryUrl) {
@@ -1101,50 +1178,98 @@ function resolveEffectiveReadRpcConfig() {
 	};
 	return resolveReadRpcConfig(cfg, mergedEnv);
 }
+function createAbortableReadRpcFetch() {
+	return (async (input, init) => {
+		const timeoutMs = satRpcRequestTimeoutMs();
+		const requestUrl = typeof input === "string" || input instanceof URL ? input.toString() : input.url;
+		let guardedFetch;
+		try {
+			guardedFetch = await fetchWithSsrFGuard({
+				url: requestUrl,
+				init,
+				timeoutMs,
+				signal: init?.signal ?? (input instanceof Request ? input.signal : undefined),
+				policy: { allowPrivateNetwork: true },
+				auditContext: "sat-mining-read-rpc"
+			});
+		} catch (error) {
+			const reason = redactSensitiveUrlLikeString(error instanceof Error ? `${error.name}: ${error.message}` : String(error));
+			throw new Error(`rpc fetch failed after at most ${timeoutMs}ms (${redactSensitiveUrlLikeString(requestUrl)}): ${reason}`);
+		}
+		const { response, release } = guardedFetch;
+		try {
+			const body = await response.arrayBuffer();
+			return new Response(body, {
+				headers: response.headers,
+				status: response.status,
+				statusText: response.statusText
+			});
+		} finally {
+			await release();
+		}
+	});
+}
+async function withReadRpcTimeout(task, method, rpcUrl) {
+	const timeoutMs = satRpcRequestTimeoutMs();
+	let timer;
+	try {
+		return await Promise.race([task, new Promise((_resolve, reject) => {
+			timer = setTimeout(() => reject(new Error(`rpc ${method} timed out after ${timeoutMs}ms (${redactSensitiveUrlLikeString(rpcUrl)})`)), timeoutMs);
+			timer.unref?.();
+		})]);
+	} finally {
+		if (timer) {
+			clearTimeout(timer);
+		}
+	}
+}
 function createReadConnection(solana, rpc) {
-	const primary = new solana.Connection(rpc.primaryUrl);
-	const secondary = rpc.secondaryUrl ? new solana.Connection(rpc.secondaryUrl) : null;
+	const primary = new solana.Connection(rpc.primaryUrl, {
+		disableRetryOnRateLimit: true,
+		fetch: createAbortableReadRpcFetch()
+	});
+	const secondary = rpc.secondaryUrl ? new solana.Connection(rpc.secondaryUrl, {
+		disableRetryOnRateLimit: true,
+		fetch: createAbortableReadRpcFetch()
+	}) : null;
 	const withFallback = (method) => {
 		return (async (...args) => {
-			const quotaBackoffMs = currentReadRpcQuotaBackoffMs();
-			if (quotaBackoffMs > 0) {
-				if (!secondary) {
-					throw makeReadRpcQuotaBackoffError(method, quotaBackoffMs);
-				}
+			const primaryBackoffMs = currentReadRpcBackoffMs(rpc.primaryUrl);
+			const secondaryBackoffMs = rpc.secondaryUrl ? currentReadRpcBackoffMs(rpc.secondaryUrl) : 0;
+			const callEndpoint = async (connection, mode, rpcUrl) => {
+				updateSatRpcMethodMetric(method, "request");
 				try {
-					updateSatRpcMethodMetric(method, "request");
-					const result = await secondary[method](...args);
+					const task = connection[method](...args);
+					const result = await withReadRpcTimeout(task, method, rpcUrl);
 					updateSatRpcMethodMetric(method, "success");
-					markReadRpcSuccess("fallback", rpc.secondaryUrl ?? rpc.primaryUrl);
+					markReadRpcSuccess(mode, rpcUrl);
 					return result;
-				} catch (secondaryError) {
+				} catch (error) {
 					updateSatRpcMethodMetric(method, "failure");
-					markReadRpcFailure(secondaryError);
-					throw secondaryError;
+					markReadRpcFailure(error, rpcUrl);
+					throw error;
 				}
+			};
+			if (primaryBackoffMs > 0) {
+				if (!secondary || !rpc.secondaryUrl || secondaryBackoffMs > 0) {
+					throw makeReadRpcBackoffError(method, Math.min(primaryBackoffMs, secondaryBackoffMs > 0 ? secondaryBackoffMs : primaryBackoffMs));
+				}
+				return await callEndpoint(secondary, "fallback", rpc.secondaryUrl);
 			}
 			try {
-				updateSatRpcMethodMetric(method, "request");
-				const result = await primary[method](...args);
-				updateSatRpcMethodMetric(method, "success");
-				markReadRpcSuccess("primary", rpc.primaryUrl);
-				return result;
+				return await callEndpoint(primary, "primary", rpc.primaryUrl);
 			} catch (primaryError) {
-				updateSatRpcMethodMetric(method, "failure");
-				if (!secondary) {
-					markReadRpcFailure(primaryError);
+				if (!secondary || !rpc.secondaryUrl) {
 					throw primaryError;
 				}
+				const fallbackBackoffMs = currentReadRpcBackoffMs(rpc.secondaryUrl);
+				if (fallbackBackoffMs > 0) {
+					throw makeReadRpcBackoffError(method, fallbackBackoffMs);
+				}
 				try {
-					updateSatRpcMethodMetric(method, "request");
-					const result = await secondary[method](...args);
-					updateSatRpcMethodMetric(method, "success");
-					markReadRpcSuccess("fallback", rpc.secondaryUrl ?? rpc.primaryUrl);
-					return result;
+					return await callEndpoint(secondary, "fallback", rpc.secondaryUrl);
 				} catch (secondaryError) {
-					updateSatRpcMethodMetric(method, "failure");
-					markReadRpcFailure(new Error(`${String(primaryError instanceof Error ? primaryError.message : primaryError)}; ${String(secondaryError instanceof Error ? secondaryError.message : secondaryError)}`));
-					throw secondaryError;
+					throw new Error(`rpc ${method} failed on primary (${String(primaryError instanceof Error ? primaryError.message : primaryError)}) and fallback (${String(secondaryError instanceof Error ? secondaryError.message : secondaryError)})`);
 				}
 			}
 		});
@@ -1187,7 +1312,6 @@ async function resolveBondProgramContext(env) {
 		programId: new solana.PublicKey(SAT_BOND_PROGRAM_ID())
 	};
 }
-const SAT_REGISTRY_RESERVE_TARGET_LAMPORTS = 2e8;
 const SAT_PROTOCOL_VAULT_ACCOUNT_SPACE = 0;
 const SAT_CYCLE_STATE_ACCOUNT_SPACE = 336;
 const SAT_CYCLE_REGISTRY_META_ACCOUNT_SPACE = 88;
@@ -1212,6 +1336,14 @@ async function rpcRequestOnce(rpcUrl, method, params) {
 		const target = new URL(rpcUrl);
 		const transport = target.protocol === "https:" ? https : http;
 		const payload = await new Promise((resolve, reject) => {
+			let settled = false;
+			const finishReject = (error) => {
+				if (settled) {
+					return;
+				}
+				settled = true;
+				reject(error);
+			};
 			const req = transport.request(target, {
 				method: "POST",
 				headers: {
@@ -1220,17 +1352,33 @@ async function rpcRequestOnce(rpcUrl, method, params) {
 				}
 			}, (res) => {
 				const chunks = [];
-				res.on("data", (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+				let responseBytes = 0;
+				res.on("data", (chunk) => {
+					const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+					responseBytes += buffer.length;
+					if (responseBytes > SAT_RPC_MAX_RESPONSE_BYTES) {
+						req.destroy(new Error(`rpc ${method} response exceeded size limit`));
+						return;
+					}
+					chunks.push(buffer);
+				});
 				res.on("end", () => {
+					if (settled) {
+						return;
+					}
 					const text = Buffer.concat(chunks).toString("utf8");
 					if ((res.statusCode ?? 500) >= 400) {
-						reject(new Error(text || `rpc ${method} failed`));
+						finishReject(new Error(text || `rpc ${method} failed`));
 						return;
 					}
+					settled = true;
 					resolve(text);
 				});
 			});
-			req.on("error", reject);
+			req.setTimeout(satRpcRequestTimeoutMs(), () => {
+				req.destroy(new Error(`rpc ${method} timed out after ${satRpcRequestTimeoutMs()}ms (${rpcUrl})`));
+			});
+			req.on("error", (error) => finishReject(error));
 			req.write(body);
 			req.end();
 		});
@@ -1247,29 +1395,35 @@ async function rpcRequestOnce(rpcUrl, method, params) {
 }
 async function rpcRequest(rpc, method, params) {
 	const normalized = normalizeReadRpcConfig(rpc);
-	const quotaBackoffMs = currentReadRpcQuotaBackoffMs();
-	if (quotaBackoffMs > 0 && !normalized.secondaryUrl) {
-		throw makeReadRpcQuotaBackoffError(method, quotaBackoffMs);
+	const primaryBackoffMs = currentReadRpcBackoffMs(normalized.primaryUrl);
+	const secondaryBackoffMs = normalized.secondaryUrl ? currentReadRpcBackoffMs(normalized.secondaryUrl) : 0;
+	if (primaryBackoffMs > 0 && (!normalized.secondaryUrl || secondaryBackoffMs > 0)) {
+		throw makeReadRpcBackoffError(method, Math.min(primaryBackoffMs, secondaryBackoffMs > 0 ? secondaryBackoffMs : primaryBackoffMs));
 	}
-	const useFallbackDueToQuota = quotaBackoffMs > 0 && Boolean(normalized.secondaryUrl);
+	const useFallbackDueToBackoff = primaryBackoffMs > 0 && Boolean(normalized.secondaryUrl);
 	try {
-		const rpcUrl = useFallbackDueToQuota && normalized.secondaryUrl ? normalized.secondaryUrl : normalized.primaryUrl;
+		const rpcUrl = useFallbackDueToBackoff && normalized.secondaryUrl ? normalized.secondaryUrl : normalized.primaryUrl;
 		const result = await rpcRequestOnce(rpcUrl, method, params);
-		markReadRpcSuccess(useFallbackDueToQuota && normalized.secondaryUrl ? "fallback" : "primary", rpcUrl);
+		markReadRpcSuccess(useFallbackDueToBackoff && normalized.secondaryUrl ? "fallback" : "primary", rpcUrl);
 		return result;
 	} catch (primaryError) {
-		if (!normalized.secondaryUrl || useFallbackDueToQuota) {
-			markReadRpcFailure(primaryError);
+		const failedRpcUrl = useFallbackDueToBackoff && normalized.secondaryUrl ? normalized.secondaryUrl : normalized.primaryUrl;
+		markReadRpcFailure(primaryError, failedRpcUrl);
+		if (!normalized.secondaryUrl || useFallbackDueToBackoff) {
 			throw primaryError;
 		}
+		const fallbackBackoffMs = currentReadRpcBackoffMs(normalized.secondaryUrl);
+		if (fallbackBackoffMs > 0) {
+			throw makeReadRpcBackoffError(method, fallbackBackoffMs);
+		}
 		try {
 			const result = await rpcRequestOnce(normalized.secondaryUrl, method, params);
 			markReadRpcSuccess("fallback", normalized.secondaryUrl);
 			return result;
 		} catch (secondaryError) {
+			markReadRpcFailure(secondaryError, normalized.secondaryUrl);
 			const primaryMessage = primaryError instanceof Error ? primaryError.message : String(primaryError);
 			const secondaryMessage = secondaryError instanceof Error ? secondaryError.message : String(secondaryError);
-			markReadRpcFailure(new Error(`rpc ${method} failed on primary (${primaryMessage}) and fallback (${secondaryMessage})`));
 			throw new Error(`rpc ${method} failed on primary (${primaryMessage}) and fallback (${secondaryMessage})`);
 		}
 	}
@@ -2013,10 +2167,11 @@ async function inspectSatTreasuryVaultLamports(_config) {
 		lamports: await fetchLamportBalanceRaw(rpc, address.toBase58())
 	};
 }
-async function inspectSatRentExemptionLamports(_config) {
+async function inspectSatRentExemptionLamports(config) {
 	const { connection } = await resolveConnection(process.env);
 	const rpc = resolveEffectiveReadRpcConfig();
-	return await getOrLoadRpcCacheValue(`view:rent-exemption:${rpcCacheScope(rpc)}`, SAT_RPC_RENT_EXEMPTION_CACHE_TTL_MS, async () => {
+	const registryReserveTargetLamports = resolveSatGenesisProfileContract(config.network).registryReserveTargetLamports;
+	return await getOrLoadRpcCacheValue(`view:rent-exemption:${rpcCacheScope(rpc)}:${registryReserveTargetLamports}`, SAT_RPC_RENT_EXEMPTION_CACHE_TTL_MS, async () => {
 		const [protocolVaultLamports, cycleStateLamports, cycleRegistryMetaLamports, cycleRegistryPageLamports, cycleSettlementProgressLamports, minerCycleLamports] = await Promise.all([
 			connection.getMinimumBalanceForRentExemption(SAT_PROTOCOL_VAULT_ACCOUNT_SPACE),
 			connection.getMinimumBalanceForRentExemption(SAT_CYCLE_STATE_ACCOUNT_SPACE),
@@ -2028,7 +2183,7 @@ async function inspectSatRentExemptionLamports(_config) {
 		const openCycleLamports = cycleStateLamports + cycleRegistryMetaLamports;
 		const submitCycleSharedLamports = cycleSettlementProgressLamports + cycleRegistryPageLamports;
 		return {
-			registryReserveTargetLamports: String(SAT_REGISTRY_RESERVE_TARGET_LAMPORTS),
+			registryReserveTargetLamports: String(registryReserveTargetLamports),
 			protocolVaultLamports: String(protocolVaultLamports),
 			cycleStateLamports: String(cycleStateLamports),
 			cycleRegistryMetaLamports: String(cycleRegistryMetaLamports),
@@ -2158,6 +2313,18 @@ async function inspectSatRoundState(_config, params) {
 }
 function inspectSatConnectionDetails() {
 	const rpc = resolveEffectiveReadRpcConfig();
+	const endpointStates = [rpc.primaryUrl, rpc.secondaryUrl].filter((rpcUrl) => Boolean(rpcUrl)).map((rpcUrl) => {
+		const state = satReadRpcEndpointStates.get(normalizeRpcUrlForComparison(rpcUrl));
+		return {
+			rpcUrl: redactSensitiveUrlLikeString(rpcUrl),
+			consecutiveFailures: state?.consecutiveFailures ?? 0,
+			backoffRemainingMs: currentReadRpcBackoffMs(rpcUrl),
+			quotaLikely: state?.quotaLikely ?? false,
+			lastError: state?.lastError ? redactSensitiveUrlLikeString(state.lastError) : null,
+			lastFailureAt: state?.lastFailureAt ?? null,
+			lastSuccessAt: state?.lastSuccessAt ?? null
+		};
+	});
 	return {
 		programId: SAT_PROGRAM_ID(),
 		bondProgramId: SAT_BOND_PROGRAM_ID(),
@@ -2167,7 +2334,8 @@ function inspectSatConnectionDetails() {
 			...satReadRpcRuntimeState,
 			lastError: satReadRpcRuntimeState.lastError ? redactSensitiveUrlLikeString(satReadRpcRuntimeState.lastError) : null,
 			lastRpcUrl: satReadRpcRuntimeState.lastRpcUrl ? redactSensitiveUrlLikeString(satReadRpcRuntimeState.lastRpcUrl) : null,
-			quotaLikely: satReadRpcRuntimeState.quotaLikely || looksLikeRpcQuotaFailure(satReadRpcRuntimeState.lastError)
+			quotaLikely: satReadRpcRuntimeState.quotaLikely || looksLikeRpcQuotaFailure(satReadRpcRuntimeState.lastError),
+			endpoints: endpointStates
 		},
 		rpcMetrics: summarizeSatRpcMethodMetrics()
 	};
@@ -2286,4 +2454,4 @@ function sortableValue(row, sortBy) {
 }
 
 //#endregion
-export { inspectSatBondPosition, inspectSatBondStakingDistributor, inspectSatBondStakingPosition, inspectSatBondTierPolicy, inspectSatChainSlot, inspectSatCycleRegistryMeta, inspectSatMinerCyclesByAddress, invalidateSatReadCaches };
+export { inspectSatBondPosition, inspectSatBondStakingDistributor, inspectSatBondStakingPosition, inspectSatChainSlot, inspectSatCycle, inspectSatCycleRegistryMeta, inspectSatMinerCyclesByAddress, invalidateSatReadCaches };

package/dist/extensions/sat-mining/src/sat-bond-layout.js

@@ -1,6 +1,6 @@
 import { SAT_RUNTIME_DEFAULTS } from "../../../config/sat-runtime-ids.js";
 import "../../../plugin-sdk/sat-runtime.js";
-import fs from "node:fs";
+import syncFs from "node:fs";
 import path from "node:path";
 
 //#region extensions/sat-mining/src/sat-bond-layout.ts
@@ -122,7 +122,9 @@ const DEDICATED_FALLBACK_STAKING_DISTRIBUTOR_LAYOUT = {
 		totalActiveStakeRaw: 120,
 		rewardIndexFp: 128,
 		observedRewardVaultRaw: 144,
-		lastSyncedSlot: 152
+		lastSyncedSlot: 152,
+		unallocatedRewardRaw: 160,
+		fractionalRemainderFp: 168
 	}
 };
 const DEDICATED_FALLBACK_STAKING_POSITION_LAYOUT = {
@@ -142,7 +144,8 @@ const DEDICATED_FALLBACK_STAKING_POSITION_LAYOUT = {
 		activeStakeRaw: 80,
 		claimableRewardRaw: 88,
 		rewardDebtFp: 96,
-		lastSyncedSlot: 112
+		lastSyncedSlot: 112,
+		fractionalRemainderFp: 120
 	}
 };
 function hasDedicatedBondProgram(env = process.env) {
@@ -162,7 +165,7 @@ function resolveLayoutPath(env = process.env) {
 		path.resolve(import.meta.dirname, "..", "..", "..", "..", "..", "token", "sat", "bond-api", "bond-position-layout.json")
 	];
 	for (const candidate of candidates) {
-		if (candidate && fs.existsSync(candidate)) {
+		if (candidate && syncFs.existsSync(candidate)) {
 			return candidate;
 		}
 	}
@@ -178,7 +181,7 @@ function resolvePolicyLayoutPath(env = process.env) {
 		path.resolve(import.meta.dirname, "..", "..", "..", "..", "..", "token", "sat", "bond-api", "bond-tier-policy-layout.json")
 	];
 	for (const candidate of candidates) {
-		if (candidate && fs.existsSync(candidate)) {
+		if (candidate && syncFs.existsSync(candidate)) {
 			return candidate;
 		}
 	}
@@ -194,7 +197,7 @@ function resolveStakingDistributorLayoutPath(env = process.env) {
 		path.resolve(import.meta.dirname, "..", "..", "..", "..", "..", "token", "sat", "bond-api", "bond-staking-distributor-layout.json")
 	];
 	for (const candidate of candidates) {
-		if (candidate && fs.existsSync(candidate)) {
+		if (candidate && syncFs.existsSync(candidate)) {
 			return candidate;
 		}
 	}
@@ -210,7 +213,7 @@ function resolveStakingPositionLayoutPath(env = process.env) {
 		path.resolve(import.meta.dirname, "..", "..", "..", "..", "..", "token", "sat", "bond-api", "bond-staking-position-layout.json")
 	];
 	for (const candidate of candidates) {
-		if (candidate && fs.existsSync(candidate)) {
+		if (candidate && syncFs.existsSync(candidate)) {
 			return candidate;
 		}
 	}
@@ -224,7 +227,7 @@ function loadSatBondLayout(env = process.env) {
 	}
 	const layoutPath = resolveLayoutPath(env);
 	if (layoutPath) {
-		const loaded = JSON.parse(fs.readFileSync(layoutPath, "utf-8"));
+		const loaded = JSON.parse(syncFs.readFileSync(layoutPath, "utf-8"));
 		cachedLayout = {
 			mode,
 			value: loaded
@@ -244,7 +247,7 @@ function loadSatBondPolicyLayout(env = process.env) {
 	}
 	const layoutPath = resolvePolicyLayoutPath(env);
 	if (layoutPath) {
-		cachedPolicyLayout = JSON.parse(fs.readFileSync(layoutPath, "utf-8"));
+		cachedPolicyLayout = JSON.parse(syncFs.readFileSync(layoutPath, "utf-8"));
 		return cachedPolicyLayout;
 	}
 	cachedPolicyLayout = DEDICATED_FALLBACK_POLICY_LAYOUT;
@@ -257,7 +260,7 @@ function loadSatBondStakingDistributorLayout(env = process.env) {
 	}
 	const layoutPath = resolveStakingDistributorLayoutPath(env);
 	if (layoutPath) {
-		cachedStakingDistributorLayout = JSON.parse(fs.readFileSync(layoutPath, "utf-8"));
+		cachedStakingDistributorLayout = JSON.parse(syncFs.readFileSync(layoutPath, "utf-8"));
 		return cachedStakingDistributorLayout;
 	}
 	cachedStakingDistributorLayout ??= DEDICATED_FALLBACK_STAKING_DISTRIBUTOR_LAYOUT;
@@ -270,7 +273,7 @@ function loadSatBondStakingPositionLayout(env = process.env) {
 	}
 	const layoutPath = resolveStakingPositionLayoutPath(env);
 	if (layoutPath) {
-		cachedStakingPositionLayout = JSON.parse(fs.readFileSync(layoutPath, "utf-8"));
+		cachedStakingPositionLayout = JSON.parse(syncFs.readFileSync(layoutPath, "utf-8"));
 		return cachedStakingPositionLayout;
 	}
 	cachedStakingPositionLayout ??= DEDICATED_FALLBACK_STAKING_POSITION_LAYOUT;