@exponent-labs/exponent-sdk 0.1.8 → 0.9.0

package/src/exponentVaults/syncTransaction.ts

@@ -0,0 +1,495 @@
+/**
+ * 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 key of ix.keys) {
+      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
+}