@exponent-labs/exponent-sdk 0.9.2 → 0.9.3

package/src/exponentVaults/syncTransaction.ts

@@ -1,500 +0,0 @@
-/**
- * Sync Transaction utilities for Squads Smart Account Program
- *
- * This module provides utilities to wrap arbitrary Solana instructions
- * into Squads `sync_transaction` format, allowing authorized signers
- * to execute transactions through a Squads policy.
- *
- * The payload format depends on the consensus account type:
- * - Settings: SyncPayload::Transaction(compiled_instructions_bytes)
- * - Policy:   SyncPayload::Policy(PolicyPayload::ProgramInteraction(...))
- *
- * Based on: https://github.com/Squads-Protocol/smart-account-program
- */
-
-import { AccountMeta, PublicKey, TransactionInstruction } from "@solana/web3.js"
-
-/** Squads Smart Account Program ID (mainnet) */
-export const SQUADS_PROGRAM_ID = new PublicKey("SMRTzfY6DfH5ik3TKiyLFfXexV8uSG3d2UksSCYdunG")
-
-/** Set DEBUG_SYNC_TX=1 to log detailed account mapping for debugging ProgramInteractionProgramIdMismatch */
-const DEBUG = typeof process !== "undefined" && process.env?.DEBUG_SYNC_TX === "1"
-
-function logSyncTx(...args: unknown[]) {
-  if (DEBUG) {
-    console.log("[SYNC_TX]", ...args)
-  }
-}
-
-// ============================================================================
-// Types
-// ============================================================================
-
-/**
- * Compiled instruction format expected by Squads program
- * Matches the Rust struct:
- * ```rust
- * pub struct CompiledInstruction {
- *   pub program_id_index: u8,
- *   pub account_indexes: SmallVec<u8, u8>,
- *   pub data: SmallVec<u16, u8>,
- * }
- * ```
- */
-interface CompiledInstruction {
-  programIdIndex: number
-  accountIndexes: number[]
-  data: Buffer | Uint8Array
-}
-
-/**
- * Result of compiling instructions for sync_transaction
- */
-export interface SyncTransactionPayload {
-  /** Serialized instructions (SmallVec<u8, CompiledInstruction>) */
-  instructions: Uint8Array
-  /** Account metas for remaining_accounts (signers, optional leading/hook accounts, then instruction accounts) */
-  accounts: AccountMeta[]
-}
-
-// ============================================================================
-// Instruction discriminator for sync_transaction (executeTransactionSyncV2)
-// ============================================================================
-
-const EXECUTE_TRANSACTION_SYNC_V2_DISCRIMINATOR = Buffer.from([90, 81, 187, 81, 39, 70, 128, 78])
-
-// ============================================================================
-// Core Functions
-// ============================================================================
-
-/**
- * Compile transaction instructions into the format required by sync_transaction
- *
- * Account order in remaining_accounts:
- * 1. Signers
- * 2. Policy prefix accounts (if any, e.g. settings for SettingsState expiration)
- * 3. Pre-hook accounts (if any)
- * 4. Post-hook accounts (if any)
- * 5. Instruction accounts (from the compiled instructions)
- */
-export function compileToSyncTransactionPayload({
-  vaultPda,
-  signers,
-  instructions,
-  leadingAccounts = [],
-  preHookAccounts = [],
-  postHookAccounts = [],
-}: {
-  vaultPda: PublicKey
-  signers: PublicKey[]
-  instructions: TransactionInstruction[]
-  /** Accounts required before hook parsing (e.g. policy expiration settings account). */
-  leadingAccounts?: PublicKey[] | AccountMeta[]
-  /** Accounts required by the policy's pre_hook (in order: program_id, then extra accounts) */
-  preHookAccounts?: PublicKey[] | AccountMeta[]
-  /** Accounts required by the policy's post_hook (in order: program_id, then extra accounts). Use AccountMeta[] to set isWritable (e.g. vault for validate_interaction_hook). */
-  postHookAccounts?: PublicKey[] | AccountMeta[]
-}): SyncTransactionPayload {
-  logSyncTx("=== compileToSyncTransactionPayload START ===")
-  logSyncTx("Input: vaultPda=", vaultPda.toBase58().slice(0, 12), " signers=", signers.length, " instructions=", instructions.length)
-  logSyncTx("  preHookAccounts=", preHookAccounts.length, " postHookAccounts=", postHookAccounts.length, " leadingAccounts=", leadingAccounts.length)
-
-  // Build account list from all instructions
-  const accountMap = new Map<string, AccountMeta>()
-
-  // First pass: collect all unique accounts from instructions
-  for (const ix of instructions) {
-    // Add program ID
-    const programKey = ix.programId.toBase58()
-    if (!accountMap.has(programKey)) {
-      accountMap.set(programKey, {
-        pubkey: ix.programId,
-        isSigner: false,
-        isWritable: false,
-      })
-    }
-
-    // Add instruction accounts
-    for (const [keyIndex, key] of ix.keys.entries()) {
-      if (!key?.pubkey) {
-        throw new Error(
-          `Instruction ${ix.programId.toBase58()} is missing account meta at index ${keyIndex}`,
-        )
-      }
-      const keyStr = key.pubkey.toBase58()
-      const existing = accountMap.get(keyStr)
-      if (existing) {
-        existing.isWritable = existing.isWritable || key.isWritable
-        existing.isSigner = existing.isSigner || key.isSigner
-      } else {
-        accountMap.set(keyStr, { ...key })
-      }
-    }
-  }
-
-  // Convert to array
-  const allAccounts = Array.from(accountMap.values())
-  logSyncTx("allAccounts (before sort):", allAccounts.length, "unique accounts from instructions")
-
-  // Mark the vault PDA as non-signer (it will be signed by Squads via CPI for the inner instruction)
-  const vaultKey = vaultPda.toBase58()
-  const vaultAccount = allAccounts.find((acc) => acc.pubkey.toBase58() === vaultKey)
-  if (vaultAccount) {
-    vaultAccount.isSigner = false
-  }
-
-  // Sort: writable signers, readonly signers, writable non-signers, readonly non-signers
-  // (Matches Squads CompiledKeys.getMessageComponents order)
-  allAccounts.sort((a, b) => {
-    const aScore = (a.isSigner ? 0 : 2) + (a.isWritable ? 0 : 1)
-    const bScore = (b.isSigner ? 0 : 2) + (b.isWritable ? 0 : 1)
-    return aScore - bScore
-  })
-
-  // For sync policy execution, Squads strips signers, optional leading policy
-  // account(s), and hook account prefixes before evaluating instruction indices.
-  // Therefore compiled instruction indices are relative only to instruction accounts.
-  const accountOffset = 0
-  logSyncTx("accountOffset (instruction accounts only) =", accountOffset)
-
-  const accountIndexMap = new Map<string, number>()
-  allAccounts.forEach((acc, idx) => {
-    const mappedIdx = accountOffset + idx
-    accountIndexMap.set(acc.pubkey.toBase58(), mappedIdx)
-    logSyncTx("  allAccounts[", idx, "] -> remainder[", mappedIdx, "] =", acc.pubkey.toBase58().slice(0, 16), "isSigner=", acc.isSigner, "isWritable=", acc.isWritable)
-  })
-
-  // Compile instructions
-  const compiledInstructions: CompiledInstruction[] = instructions.map((ix, ixIdx) => {
-    const programIdIndex = accountIndexMap.get(ix.programId.toBase58())
-    if (programIdIndex === undefined) {
-      throw new Error(`Program ID ${ix.programId.toBase58()} not found in account map`)
-    }
-    logSyncTx("Instruction", ixIdx, ": programId=", ix.programId.toBase58().slice(0, 12), "-> programIdIndex=", programIdIndex, "(remainder[", programIdIndex, "] should be Exponent program)")
-    const accountIndexes = ix.keys.map((key) => {
-      const idx = accountIndexMap.get(key.pubkey.toBase58())
-      if (idx === undefined) {
-        throw new Error(`Account ${key.pubkey.toBase58()} not found in account map`)
-      }
-      return idx
-    })
-
-    return {
-      programIdIndex,
-      accountIndexes,
-      data: ix.data,
-    }
-  })
-
-  // Serialize compiled instructions
-  const serializedInstructions = serializeCompiledInstructions(compiledInstructions)
-
-  // Build remaining accounts in the order expected by sync-v2:
-  // [signers, leading policy accounts, pre_hook, post_hook, instruction_accounts].
-  // Squads validates signers from the first numSigners remaining accounts before
-  // any hook parsing, then strips leading policy accounts and hooks before
-  // compiled instruction evaluation/execution.
-  const remainingAccounts: AccountMeta[] = []
-
-  // Add signers first (validated before any hook parsing)
-  for (const signer of signers) {
-    remainingAccounts.push({
-      pubkey: signer,
-      isSigner: true,
-      isWritable: false,
-    })
-  }
-
-  // Add policy prefix / leading accounts (if any, e.g. settings-state expiration)
-  for (const account of leadingAccounts) {
-    remainingAccounts.push(
-      "pubkey" in account && account.pubkey != null
-        ? { pubkey: account.pubkey, isSigner: account.isSigner ?? false, isWritable: account.isWritable ?? false }
-        : { pubkey: account as PublicKey, isSigner: false, isWritable: false },
-    )
-  }
-
-  // Add pre-hook accounts (stripped first by parse_hook_accounts)
-  for (const hookAccount of preHookAccounts) {
-    remainingAccounts.push(
-      "pubkey" in hookAccount && hookAccount.pubkey != null
-        ? { pubkey: hookAccount.pubkey, isSigner: hookAccount.isSigner ?? false, isWritable: hookAccount.isWritable ?? false }
-        : { pubkey: hookAccount as PublicKey, isSigner: false, isWritable: false },
-    )
-  }
-
-  // Add post-hook accounts (stripped second by parse_hook_accounts)
-  for (const hookAccount of postHookAccounts) {
-    remainingAccounts.push(
-      "pubkey" in hookAccount && hookAccount.pubkey != null
-        ? { pubkey: hookAccount.pubkey, isSigner: hookAccount.isSigner ?? false, isWritable: hookAccount.isWritable ?? false }
-        : { pubkey: hookAccount as PublicKey, isSigner: false, isWritable: false },
-    )
-  }
-
-  // Add instruction accounts
-  remainingAccounts.push(...allAccounts)
-
-  // Log transaction accounts that Squads will use for instruction constraint checks:
-  // strip signers -> strip leading -> strip pre/post hook accounts.
-  const signersLen = signers.length
-  const leadingLen = leadingAccounts.length
-  const preLen = preHookAccounts.length
-  const postLen = postHookAccounts.length
-  const transactionAccounts = remainingAccounts.slice(signersLen + leadingLen + preLen + postLen)
-  logSyncTx("=== TRANSACTION ACCOUNTS (after stripping signers/leading/hooks) ===")
-  logSyncTx(
-    "Stripped: signers",
-    signersLen,
-    "leading",
-    leadingLen,
-    "pre_hook",
-    preLen,
-    "post_hook",
-    postLen,
-    "-> transaction length =",
-    transactionAccounts.length,
-  )
-  transactionAccounts.forEach((acc, i) => {
-    logSyncTx("  txAccounts[", i, "] =", acc.pubkey.toBase58().slice(0, 16), "isSigner=", acc.isSigner)
-  })
-  compiledInstructions.forEach((cix, i) => {
-    const accAtProgIdx = transactionAccounts[cix.programIdIndex]
-    logSyncTx("CRITICAL: instruction", i, "programIdIndex=", cix.programIdIndex, "-> txAccounts[", cix.programIdIndex, "] =", accAtProgIdx?.pubkey.toBase58() ?? "OUT_OF_BOUNDS")
-    logSyncTx("  Expected: ExponentnaRg3CQbW6dqQNZKXp7gtZ9DGMp1cwC4HAS7")
-  })
-  logSyncTx("=== compileToSyncTransactionPayload END ===")
-
-  return {
-    instructions: serializedInstructions,
-    accounts: remainingAccounts,
-  }
-}
-
-/**
- * Build the sync_transaction instruction using the Policy payload format.
- *
- * When the consensus account is a Policy (not Settings), the SyncPayload
- * must be SyncPayload::Policy(PolicyPayload::ProgramInteraction(...))
- */
-export function buildSyncTransactionInstruction({
-  policyPda,
-  accountIndex,
-  numSigners,
-  payload,
-  constraintIndices,
-  squadsProgram = SQUADS_PROGRAM_ID,
-}: {
-  policyPda: PublicKey
-  accountIndex: number
-  numSigners: number
-  payload: SyncTransactionPayload
-  /** Optional constraint indices mapping each instruction to a constraint in the policy */
-  constraintIndices?: number[]
-  squadsProgram?: PublicKey
-}): TransactionInstruction {
-  // Serialize args with Policy payload format
-  const argsData = serializeSyncTransactionArgsForPolicy({
-    accountIndex,
-    numSigners,
-    constraintIndices: constraintIndices ?? null,
-    compiledInstructions: payload.instructions,
-  })
-
-  // Build instruction data: discriminator + args
-  const data = Buffer.concat([EXECUTE_TRANSACTION_SYNC_V2_DISCRIMINATOR, argsData])
-
-  // Build account keys
-  const keys: AccountMeta[] = [
-    {
-      pubkey: policyPda,
-      isWritable: true,
-      isSigner: false,
-    },
-    {
-      pubkey: squadsProgram,
-      isWritable: false,
-      isSigner: false,
-    },
-    ...payload.accounts,
-  ]
-
-  return new TransactionInstruction({
-    programId: squadsProgram,
-    keys,
-    data,
-  })
-}
-
-/**
- * Convenience function to wrap instructions in a sync_transaction via Policy
- *
- * IMPORTANT: Hook accounts must be passed in the correct order:
- * 1. Leading policy accounts (if any)
- * 2. Pre-hook accounts (if policy has pre_hook)
- * 3. Post-hook accounts (if policy has post_hook)
- * They are appended after signers and before instruction accounts in remaining_accounts.
- */
-export function wrapInstructionsInSyncTransaction({
-  policyPda,
-  vaultPda,
-  signer,
-  instructions,
-  accountIndex = 0,
-  constraintIndices,
-  leadingAccounts = [],
-  preHookAccounts = [],
-  postHookAccounts = [],
-  squadsProgram = SQUADS_PROGRAM_ID,
-}: {
-  policyPda: PublicKey
-  vaultPda: PublicKey
-  signer: PublicKey
-  instructions: TransactionInstruction[]
-  accountIndex?: number
-  constraintIndices?: number[]
-  leadingAccounts?: PublicKey[] | AccountMeta[]
-  /** Accounts required by the policy's pre_hook (in order: program_id, then extra accounts) */
-  preHookAccounts?: PublicKey[] | AccountMeta[]
-  /** Accounts required by the policy's post_hook (in order: program_id, then extra accounts). Use AccountMeta[] to set isWritable. */
-  postHookAccounts?: PublicKey[] | AccountMeta[]
-  squadsProgram?: PublicKey
-}): TransactionInstruction {
-  // For execute_transaction_sync_v2 with ProgramInteraction policies, `numSigners`
-  // applies to the explicit signer prefix in remaining accounts. The smart account
-  // selected by `accountIndex` is resolved from policy/settings state and MUST NOT be
-  // injected into that signer prefix.
-  const signers = [signer]
-
-  const payload = compileToSyncTransactionPayload({
-    vaultPda,
-    signers,
-    instructions,
-    leadingAccounts,
-    preHookAccounts,
-    postHookAccounts,
-  })
-
-  return buildSyncTransactionInstruction({
-    policyPda,
-    accountIndex,
-    numSigners: signers.length,
-    payload,
-    constraintIndices,
-    squadsProgram,
-  })
-}
-
-// ============================================================================
-// Serialization Helpers
-// ============================================================================
-
-/**
- * Serialize compiled instructions as SmallVec<u8, CompiledInstruction>
- */
-function serializeCompiledInstructions(instructions: CompiledInstruction[]): Uint8Array {
-  let buffer = Buffer.alloc(0)
-
-  // Length prefix as u8
-  buffer = Buffer.concat([buffer, Buffer.from([instructions.length])])
-
-  // Serialize each instruction
-  for (const ix of instructions) {
-    const serializedIx = serializeCompiledInstruction(ix)
-    buffer = Buffer.concat([buffer, serializedIx])
-  }
-
-  return Uint8Array.from(buffer)
-}
-
-/**
- * Serialize a single CompiledInstruction
- */
-function serializeCompiledInstruction(ix: CompiledInstruction): Buffer {
-  let buffer = Buffer.alloc(0)
-
-  // program_id_index: u8
-  buffer = Buffer.concat([buffer, Buffer.from([ix.programIdIndex])])
-
-  // account_indexes: SmallVec<u8, u8>
-  buffer = Buffer.concat([
-    buffer,
-    Buffer.from([ix.accountIndexes.length]), // length prefix as u8
-    Buffer.from(ix.accountIndexes), // the indexes
-  ])
-
-  // data: SmallVec<u16, u8>
-  const dataLenBuffer = Buffer.alloc(2)
-  dataLenBuffer.writeUInt16LE(ix.data.length, 0)
-  buffer = Buffer.concat([
-    buffer,
-    dataLenBuffer, // length prefix as u16 LE
-    ix.data instanceof Buffer ? ix.data : Buffer.from(ix.data), // the data
-  ])
-
-  return buffer
-}
-
-/**
- * Serialize SyncTransactionArgs for instruction data using Policy payload format.
- *
- * The wire format is:
- *   accountIndex: u8
- *   numSigners: u8
- *   SyncPayload::Policy = variant 1:
- *     PolicyPayload::ProgramInteraction = variant 1:
- *       ProgramInteractionPayload:
- *         instruction_constraint_indices: Option<Vec<u8>>
- *         transaction_payload: ProgramInteractionTransactionPayload::SyncTransaction = variant 1:
- *           SyncTransactionPayloadDetails:
- *             account_index: u8
- *             instructions: Vec<u8> (4-byte LE length prefix + bytes)
- */
-function serializeSyncTransactionArgsForPolicy(args: {
-  accountIndex: number
-  numSigners: number
-  constraintIndices: number[] | null
-  compiledInstructions: Uint8Array
-}): Buffer {
-  let buffer = Buffer.alloc(0)
-
-  // accountIndex: u8
-  buffer = Buffer.concat([buffer, Buffer.from([args.accountIndex])])
-
-  // numSigners: u8
-  buffer = Buffer.concat([buffer, Buffer.from([args.numSigners])])
-
-  // SyncPayload enum variant: Policy = 1
-  buffer = Buffer.concat([buffer, Buffer.from([1])])
-
-  // PolicyPayload enum variant: ProgramInteraction = 1
-  buffer = Buffer.concat([buffer, Buffer.from([1])])
-
-  // ProgramInteractionPayload:
-  // 1. instruction_constraint_indices: Option<Vec<u8>>
-  if (args.constraintIndices === null) {
-    // None
-    buffer = Buffer.concat([buffer, Buffer.from([0])])
-  } else {
-    // Some(Vec<u8>)
-    buffer = Buffer.concat([buffer, Buffer.from([1])])
-    const vecLenBuf = Buffer.alloc(4)
-    vecLenBuf.writeUInt32LE(args.constraintIndices.length, 0)
-    buffer = Buffer.concat([buffer, vecLenBuf, Buffer.from(args.constraintIndices)])
-  }
-
-  // 2. transaction_payload: ProgramInteractionTransactionPayload::SyncTransaction = variant 1
-  buffer = Buffer.concat([buffer, Buffer.from([1])])
-
-  // SyncTransactionPayloadDetails:
-  //   account_index: u8
-  buffer = Buffer.concat([buffer, Buffer.from([args.accountIndex])])
-
-  //   instructions: Vec<u8> (bytes = 4-byte LE length prefix + data)
-  const instructionsLen = args.compiledInstructions.length
-  const lenBuffer = Buffer.alloc(4)
-  lenBuffer.writeUInt32LE(instructionsLen, 0)
-  buffer = Buffer.concat([buffer, lenBuffer, Buffer.from(args.compiledInstructions)])
-
-  return buffer
-}