@fased/fased 0.1.64 → 0.1.66

package/extensions/sat-mining/src/solana-submit.ts

@@ -27,6 +27,8 @@ import {
   SAT_PROTOCOL_CONSTANTS,
 } from "./protocol-contract.js";
 import {
+  inspectSatAddressLookupTable,
+  inspectSatChainSlot,
   inspectSatCycle,
   inspectSatCycleRegistryMeta,
   inspectSatMinerCyclesByAddress,
@@ -74,6 +76,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;
 
@@ -324,12 +328,32 @@ export async function resolveSatValidatorAuthority(_config: SatMiningConfig) {
 type SatInstructionSubmitSpec = {
   data: Buffer;
   programId?: string;
+  addressLookupTables?: string[];
+  manageAddressLookupTable?: {
+    lookupTableAddress?: string;
+    cycleId: number;
+    pageIndex: number;
+    onLookupTableResolved?: (lookupTableAddress: string) => Promise<void>;
+  };
   accountResolver: (
     solana: SolanaModuleLike,
     signer: import("@solana/web3.js").PublicKey,
   ) => Promise<SolanaAccountMeta[] | SatResolvedInstruction>;
 };
 
+type SatInstructionSubmitResult = {
+  txHash: string;
+  signer: string;
+  signerState: SatSignerOperation["state"];
+  requestId: string;
+  transactionVersion: "legacy" | "v0";
+  lookupTableAddress?: string;
+  lookupTableCreated?: boolean;
+  lookupTableExtended?: boolean;
+  lookupTableAddressCount?: number;
+  lookupTableTransactionHashes?: string[];
+};
+
 async function prepareLocalSignerSubmitContext(cfg: FasedAgentConfig, env: NodeJS.ProcessEnv) {
   const effectiveEnv = resolveSatEffectiveEnv(cfg, env);
   const solana = await loadSolanaWeb3();
@@ -375,6 +399,9 @@ async function buildLocalSignerInstructionRequest(params: {
       isSigner: key.isSigner,
       isWritable: key.isWritable,
     })),
+    ...(params.spec.addressLookupTables?.length
+      ? { addressLookupTables: params.spec.addressLookupTables }
+      : {}),
     ...(context ? { context } : {}),
   };
 }
@@ -399,7 +426,7 @@ const REQUIRED_SAT_SIGNER_FEATURES = [
 
 async function requireTypedSatSignerCapabilities(
   socketPath: string,
-  intentType: "solana.satAction" | "solana.vaultBondAction",
+  intentType: "solana.satAction" | "solana.satLookupTable" | "solana.vaultBondAction",
 ) {
   const result = await callLocalSocketSigner<{
     ready?: boolean;
@@ -428,6 +455,10 @@ async function requireTypedSatSignerCapabilities(
           "durableReviewAuthorization",
         ].filter((feature) => !features.has(feature))
       : [];
+  const missingLookupFeatures =
+    intentType === "solana.satLookupTable" && !features.has("typedSATAddressLookupTables")
+      ? ["typedSATAddressLookupTables"]
+      : [];
   if (
     result.ready !== true ||
     protocol?.current !== 2 ||
@@ -437,6 +468,7 @@ async function requireTypedSatSignerCapabilities(
     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
@@ -445,8 +477,10 @@ async function requireTypedSatSignerCapabilities(
       `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(", ")}` : ""
-      }`,
+        missingLookupFeatures.length > 0
+          ? `; missing SAT lookup features: ${missingLookupFeatures.join(", ")}`
+          : ""
+      }${missingStates.length > 0 ? `; missing states: ${missingStates.join(", ")}` : ""}`,
     );
   }
 }
@@ -495,6 +529,14 @@ function signerStateForLedger(state: SatSignerOperation["state"]): SatSubmission
   return state;
 }
 
+type SatLookupTableAction = "create" | "extend" | "deactivate" | "close";
+
+function assertSatLookupTableAction(value: string): asserts value is SatLookupTableAction {
+  if (value !== "create" && value !== "extend" && value !== "deactivate" && value !== "close") {
+    throw new Error(`unsupported SAT lookup-table action ${value}`);
+  }
+}
+
 class SatSubmissionUnresolvedError extends Error {
   readonly requestId: string;
   readonly signature?: string;
@@ -513,35 +555,71 @@ class SatSubmissionUnresolvedError extends Error {
   }
 }
 
+class SatSubmissionDefinitiveFailureError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SatSubmissionDefinitiveFailureError";
+  }
+}
+
 async function executeTypedSatIntent(params: {
   socketPath: string;
   walletId: string;
-  action: SatSignerAction | "cleanupBatch";
+  action: SatSignerAction | "cleanupBatch" | "create" | "extend" | "deactivate" | "close";
   instruction?: Awaited<ReturnType<typeof buildLocalSignerInstructionRequest>>;
   instructions?: Array<Awaited<ReturnType<typeof buildLocalSignerInstructionRequest>>>;
+  lookupTable?: {
+    address: string;
+    cycleId: string;
+    pageIndex: string;
+    recentSlot?: string;
+    addresses?: string[];
+    parent?: Awaited<ReturnType<typeof buildLocalSignerInstructionRequest>>;
+  };
   cluster: "local" | "devnet" | "mainnet-beta";
   env: NodeJS.ProcessEnv;
 }) {
-  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 as SatSignerAction);
+  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) {
-          throw new Error("typed Vault bond execution requires exactly one semantic instruction");
+        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.vaultBondAction" as const,
-          cluster: params.cluster,
-          ...params.instruction,
+          type: "solana.satLookupTable" as const,
+          action,
+          lookupTable: params.lookupTable,
         };
       })()
-    : {
-        type: "solana.satAction" as const,
-        action: params.action,
-        ...(params.instruction ?? {}),
-        ...(params.instructions ? { instructions: params.instructions } : {}),
-      };
+    : isVaultBond
+      ? (() => {
+          if (!params.instruction || params.instructions) {
+            throw new Error("typed Vault bond execution requires exactly one semantic instruction");
+          }
+          return {
+            type: "solana.vaultBondAction" as const,
+            cluster: params.cluster,
+            ...params.instruction,
+          };
+        })()
+      : {
+          type: "solana.satAction" as const,
+          action: params.action,
+          ...(params.instruction ?? {}),
+          ...(params.instructions ? { instructions: params.instructions } : {}),
+        };
   const policy = await callLocalSocketSigner<{ hash: string }>(params.socketPath, {
     op: "v2.policy.get",
     walletId: params.walletId,
@@ -560,6 +638,7 @@ async function executeTypedSatIntent(params: {
     operationKey,
     intentDigest,
     action: params.action,
+    allowFailedRetry: isLookupTable,
     env: params.env,
   });
   if (!claim.claimed) {
@@ -574,6 +653,7 @@ async function executeTypedSatIntent(params: {
       operationKey,
       intentDigest,
       action: params.action,
+      allowFailedRetry: isLookupTable,
       env: params.env,
       owner: claim.owner,
     });
@@ -841,7 +921,9 @@ 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({
@@ -854,14 +936,403 @@ async function executeTypedSatIntent(params: {
   return { ...operation, signature: operation.signature };
 }
 
+type SatLookupSubmitContext = Awaited<ReturnType<typeof prepareLocalSignerSubmitContext>> & {
+  walletId: string;
+};
+
+function assertSatLookupTableEnabled(env: NodeJS.ProcessEnv): void {
+  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: {
+  context: SatLookupSubmitContext;
+  cfg: FasedAgentConfig;
+  action: "create" | "extend" | "deactivate" | "close";
+  address: string;
+  cycleId: number;
+  pageIndex: number;
+  recentSlot?: number;
+  addresses?: string[];
+  parent?: Awaited<ReturnType<typeof buildLocalSignerInstructionRequest>>;
+}) {
+  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: {
+  config: SatMiningConfig;
+  address: string;
+  authority: string;
+}) {
+  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: {
+  config: SatMiningConfig;
+  address: string;
+  authority: string;
+  requireNextSlot: boolean;
+}) {
+  let lastError: unknown;
+  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: {
+  context: SatLookupSubmitContext;
+  lookupTable: string;
+  currentSlot: number;
+}): number | undefined {
+  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;
+}
+
+type SatLookupBinding = {
+  cycleId: string;
+  pageIndex: string;
+  address?: string;
+  bound: boolean;
+  mutationRequestId?: string;
+  mutationState?: SatSignerOperation["state"];
+};
+
+async function readReconciledSatLookupBinding(params: {
+  context: SatLookupSubmitContext;
+  cycleId: number;
+  pageIndex: number;
+}): Promise<SatLookupBinding> {
+  const request = { cycleId: String(params.cycleId), pageIndex: String(params.pageIndex) };
+  const readBinding = async () =>
+    await callLocalSocketSigner<SatLookupBinding>(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<SatSignerOperation>(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: {
+  context: SatLookupSubmitContext;
+  cfg: FasedAgentConfig;
+  config: SatMiningConfig;
+  lookupTableAddress?: string;
+  cycleId: number;
+  pageIndex: number;
+  addresses: string[];
+  parent: Awaited<ReturnType<typeof buildLocalSignerInstructionRequest>>;
+  onLookupTableResolved?: (lookupTableAddress: string) => Promise<void>;
+}) {
+  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: string[] = [];
+  let createRecentSlot: number | undefined;
+  const attemptedCreateAddresses = new Set<string>();
+  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",
+        );
+      }
+      // The signer clears a create binding only after two independent RPC
+      // origins prove both blockhash expiry and table absence. Discard the
+      // stale Gateway cache so the next exact workflow attempt can derive and
+      // persist a fresh signer-owned table identity.
+      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;
+        // Persist each deterministic candidate before its first possible
+        // broadcast. Signer reverse binding prevents two page identities from
+        // ever sharing one address; a collision advances to the next fresh slot.
+        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: {
     cfg: FasedAgentConfig;
     env: NodeJS.ProcessEnv;
   } & SatInstructionSubmitSpec,
-) {
+): Promise<SatInstructionSubmitResult> {
   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,
@@ -870,6 +1341,23 @@ async function submitInstructionViaLocalSigner(
   if (!context.walletId) {
     throw new Error("typed SAT signing requires an explicit mining walletId");
   }
+  let managedLookupTable: Awaited<ReturnType<typeof ensureSatDistributionLookupTable>> | undefined;
+  if (params.manageAddressLookupTable) {
+    managedLookupTable = await ensureSatDistributionLookupTable({
+      context: { ...context, walletId: context.walletId },
+      cfg: params.cfg,
+      config: params.cfg as unknown as SatMiningConfig,
+      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,
@@ -883,6 +1371,20 @@ async function submitInstructionViaLocalSigner(
     signer: context.signerAddress,
     signerState: submitted.state,
     requestId: submitted.requestId,
+    ...(request.addressLookupTables?.length
+      ? {
+          transactionVersion: "v0" as const,
+          lookupTableAddress: request.addressLookupTables[0],
+        }
+      : { transactionVersion: "legacy" as const }),
+    ...(managedLookupTable
+      ? {
+          lookupTableCreated: managedLookupTable.created,
+          lookupTableExtended: managedLookupTable.extended,
+          lookupTableAddressCount: managedLookupTable.addressCount,
+          lookupTableTransactionHashes: managedLookupTable.transactionHashes,
+        }
+      : {}),
   };
 }
 
@@ -901,6 +1403,8 @@ async function submitInstruction(
     env: effectiveEnv,
     data: params.data,
     programId: params.programId,
+    addressLookupTables: params.addressLookupTables,
+    manageAddressLookupTable: params.manageAddressLookupTable,
     accountResolver: params.accountResolver,
   });
 }
@@ -2702,13 +3206,35 @@ export async function submitSatScoreCyclePage(
 
 export async function submitSatDistributeCyclePage(
   _config: SatMiningConfig,
-  params: { cycleId: number; pageIndex: number; chunkIndex: number; minerCycleAccounts?: string[] },
+  params: {
+    cycleId: number;
+    pageIndex: number;
+    chunkIndex: number;
+    minerCycleAccounts?: string[];
+    lookupTableAddress?: string;
+    onLookupTableResolved?: (lookupTableAddress: string) => Promise<void>;
+  },
 ) {
   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(
@@ -2798,6 +3324,51 @@ export async function submitSatDistributeCyclePage(
   });
 }
 
+export async function submitSatCleanupDistributionLookupTable(
+  _config: SatMiningConfig,
+  params: {
+    cycleId: number;
+    pageIndex: number;
+    action: "deactivate" | "close";
+  },
+) {
+  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,
+  };
+}
+
 export async function submitSatClaimCycleRewards(
   _config: SatMiningConfig,
   params: { cycleId: number },