@exponent-labs/exponent-sdk 0.1.8 → 0.9.0

package/src/exponentVaults/policyMatcher.ts

@@ -0,0 +1,895 @@
+/**
+ * Policy Matcher for Squads Smart Account Program
+ *
+ * Fetches and deserializes a Squads policy account, then matches
+ * transaction instructions against the policy's instruction constraints
+ * to produce `constraintIndices` for `ExecuteTransactionSyncV2`.
+ *
+ * Ported from v2/admin-app/src/lib/vault-policies/policyChecker.ts
+ */
+import {
+  AccountMeta,
+  Connection,
+  PublicKey,
+  SYSVAR_INSTRUCTIONS_PUBKEY,
+  SystemProgram,
+  TransactionInstruction,
+} from "@solana/web3.js"
+
+import { LOCAL_ENV } from "../environment"
+import { SQUADS_PROGRAM_ID } from "./syncTransaction"
+import { ExponentVault as StrategyVault } from "./vault"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface InstructionConstraint {
+  programId: PublicKey
+  accountConstraints: Array<{
+    index: number
+    addresses: PublicKey[]
+    dataConstraints: Array<{ offset: number; data: Uint8Array; operator: number }>
+    owner: PublicKey | null
+  }>
+  dataConstraints: Array<{ offset: number; data: Uint8Array; operator: number }>
+}
+
+interface HookInfo {
+  programId: PublicKey
+  numExtraAccounts: number
+}
+
+interface ProgramInteractionPolicy {
+  address?: PublicKey
+  settings: PublicKey
+  signers: PublicKey[]
+  accountIndex: number
+  instructionsConstraints: InstructionConstraint[]
+  preHook: HookInfo | null
+  postHook: HookInfo | null
+  requiresSettingsStateAccount: boolean
+}
+
+type CachedInstructionAccountInfo = {
+  data: Buffer
+  owner: PublicKey
+} | null
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Fetch the on-chain Squads policy, parse its instruction constraints,
+ * and compute `constraintIndices` by matching each instruction to the
+ * first constraint that allows it.
+ *
+ * @throws if the policy account cannot be fetched, parsed, or if any
+ *         instruction has no matching constraint.
+ */
+export async function resolveConstraintIndices(
+  connection: Connection,
+  policyPda: PublicKey,
+  instructions: TransactionInstruction[],
+): Promise<number[]> {
+  const accountInfo = await connection.getAccountInfo(policyPda)
+  if (!accountInfo) {
+    throw new Error(`Policy account not found: ${policyPda.toBase58()}`)
+  }
+
+  const policy = deserializeProgramInteractionPolicyFromAccount(accountInfo.data)
+  if (!policy) {
+    throw new Error(`Failed to deserialize ProgramInteraction policy from ${policyPda.toBase58()}`)
+  }
+
+  const constraints = policy.instructionsConstraints
+  if (constraints.length === 0) {
+    // No constraints means everything is allowed — no indices needed
+    return []
+  }
+
+  const constraintIndices: number[] = []
+  const accountInfoCache = new Map<string, CachedInstructionAccountInfo>()
+
+  for (let ixIdx = 0; ixIdx < instructions.length; ixIdx++) {
+    const ix = instructions[ixIdx]
+    let matchedIdx = -1
+
+    for (let cIdx = 0; cIdx < constraints.length; cIdx++) {
+      if (await checkInstructionAgainstConstraint(connection, ix, constraints[cIdx], accountInfoCache)) {
+        matchedIdx = cIdx
+        break
+      }
+    }
+
+    if (matchedIdx < 0) {
+      throw new Error(`Instruction #${ixIdx} (program ${ix.programId.toBase58()}) does not match any policy constraint`)
+    }
+
+    constraintIndices.push(matchedIdx)
+  }
+
+  return constraintIndices
+}
+
+export async function fetchProgramInteractionPolicies(
+  connection: Connection,
+  settingsPda: PublicKey,
+): Promise<ProgramInteractionPolicy[]> {
+  const accounts = await connection.getProgramAccounts(SQUADS_PROGRAM_ID, {
+    filters: [
+      {
+        memcmp: {
+          offset: 8,
+          bytes: settingsPda.toBase58(),
+        },
+      },
+    ],
+  })
+
+  return accounts
+    .map(({ pubkey, account }) => deserializeProgramInteractionPolicyFromAccount(account.data, pubkey))
+    .filter((policy): policy is ProgramInteractionPolicy => policy != null)
+}
+
+export async function resolvePolicyMatch(
+  connection: Connection,
+  settingsPda: PublicKey,
+  signer: PublicKey,
+  instructions: TransactionInstruction[],
+): Promise<{ policyPda: PublicKey; constraintIndices: number[] }> {
+  const policies = await fetchProgramInteractionPolicies(connection, settingsPda)
+  const authorizedPolicies = policies
+    .filter((policy) => policy.signers.some((policySigner) => policySigner.equals(signer)))
+    .sort((left, right) => right.instructionsConstraints.length - left.instructionsConstraints.length)
+
+  for (const policy of authorizedPolicies) {
+    const constraintIndices: number[] = []
+    let matchedAll = true
+    const accountInfoCache = new Map<string, CachedInstructionAccountInfo>()
+
+    for (const ix of instructions) {
+      let matchedIdx = -1
+      for (let constraintIdx = 0; constraintIdx < policy.instructionsConstraints.length; constraintIdx++) {
+        if (
+          await checkInstructionAgainstConstraint(
+            connection,
+            ix,
+            policy.instructionsConstraints[constraintIdx],
+            accountInfoCache,
+          )
+        ) {
+          matchedIdx = constraintIdx
+          break
+        }
+      }
+
+      if (policy.instructionsConstraints.length === 0) {
+        matchedIdx = 0
+      }
+
+      if (matchedIdx < 0) {
+        matchedAll = false
+        break
+      }
+
+      if (policy.instructionsConstraints.length > 0) {
+        constraintIndices.push(matchedIdx)
+      }
+    }
+
+    if (matchedAll && policy.address) {
+      return { policyPda: policy.address, constraintIndices }
+    }
+  }
+
+  throw new Error(
+    `No authorized policy for signer ${signer.toBase58()} matched all ${instructions.length} instruction(s)`,
+  )
+}
+
+export async function resolvePolicyMatchForVault(
+  connection: Connection,
+  vaultAddress: PublicKey,
+  signer: PublicKey,
+  instructions: TransactionInstruction[],
+): Promise<{ policyPda: PublicKey; constraintIndices: number[] }> {
+  const strategyVault = await StrategyVault.load({ env: LOCAL_ENV, connection, address: vaultAddress })
+  return resolvePolicyMatch(connection, strategyVault.state.squadsSettings, signer, instructions)
+}
+
+// ============================================================================
+// Constraint Matching
+// ============================================================================
+
+async function checkInstructionAgainstConstraint(
+  connection: Connection,
+  ix: TransactionInstruction,
+  constraint: InstructionConstraint,
+  accountInfoCache: Map<string, CachedInstructionAccountInfo>,
+): Promise<boolean> {
+  // Program ID must match
+  if (!ix.programId.equals(constraint.programId)) return false
+
+  // Account constraints (AND — all must pass)
+  for (const ac of constraint.accountConstraints) {
+    if (ac.index >= ix.keys.length) return false
+    const accountPubkey = ix.keys[ac.index].pubkey
+    if (ac.addresses.length > 0 && !ac.addresses.some((address) => accountPubkey.equals(address))) {
+      return false
+    }
+
+    if (ac.dataConstraints.length > 0 || ac.owner) {
+      const accountInfo = await getInstructionAccountInfo(connection, accountPubkey, accountInfoCache)
+      if (!accountInfo) {
+        return false
+      }
+
+      if (ac.owner && !accountInfo.owner.equals(ac.owner)) {
+        return false
+      }
+
+      for (const dataConstraint of ac.dataConstraints) {
+        if (!checkDataConstraintAgainstBytes(accountInfo.data, dataConstraint)) {
+          return false
+        }
+      }
+    }
+  }
+
+  // Data constraints (AND — all must pass)
+  for (const dc of constraint.dataConstraints) {
+    if (!checkDataConstraintAgainstBytes(ix.data, dc)) {
+      return false
+    }
+  }
+
+  return true
+}
+
+async function getInstructionAccountInfo(
+  connection: Connection,
+  address: PublicKey,
+  cache: Map<string, CachedInstructionAccountInfo>,
+): Promise<CachedInstructionAccountInfo> {
+  const cacheKey = address.toBase58()
+  if (cache.has(cacheKey)) {
+    return cache.get(cacheKey) ?? null
+  }
+
+  const accountInfo = await connection.getAccountInfo(address)
+  const normalized = accountInfo
+    ? {
+        data: Buffer.from(accountInfo.data),
+        owner: accountInfo.owner,
+      }
+    : null
+  cache.set(cacheKey, normalized)
+  return normalized
+}
+
+function checkDataConstraintAgainstBytes(
+  source: Uint8Array,
+  constraint: { offset: number; data: Uint8Array; operator: number },
+): boolean {
+  if (constraint.offset < 0 || constraint.offset + constraint.data.length > source.length) {
+    return false
+  }
+
+  const actual = source.slice(constraint.offset, constraint.offset + constraint.data.length)
+  return compareDataConstraintValues(actual, constraint.data, constraint.operator)
+}
+
+function compareDataConstraintValues(actual: Uint8Array, expected: Uint8Array, operator: number): boolean {
+  const actualBuffer = Buffer.from(actual)
+  const expectedBuffer = Buffer.from(expected)
+  const matches = actualBuffer.equals(expectedBuffer)
+
+  if (operator === 0) return matches
+  if (operator === 1) return !matches
+
+  const actualNumeric = parseNumericConstraintBytes(actualBuffer)
+  const expectedNumeric = parseNumericConstraintBytes(expectedBuffer)
+  if (actualNumeric === null || expectedNumeric === null) {
+    return false
+  }
+
+  if (operator === 2) return actualNumeric > expectedNumeric
+  if (operator === 3) return actualNumeric >= expectedNumeric
+  if (operator === 4) return actualNumeric < expectedNumeric
+  if (operator === 5) return actualNumeric <= expectedNumeric
+
+  return false
+}
+
+function parseNumericConstraintBytes(data: Uint8Array): bigint | null {
+  const buffer = Buffer.from(data)
+
+  if (buffer.length === 1) return BigInt(buffer.readUInt8(0))
+  if (buffer.length === 2) return BigInt(buffer.readUInt16LE(0))
+  if (buffer.length === 4) return BigInt(buffer.readUInt32LE(0))
+  if (buffer.length === 8) return buffer.readBigUInt64LE(0)
+  if (buffer.length === 16) {
+    const low = buffer.readBigUInt64LE(0)
+    const high = buffer.readBigUInt64LE(8)
+    return low + (high << 64n)
+  }
+
+  return null
+}
+
+// ============================================================================
+// Policy Deserialization
+// ============================================================================
+
+/**
+ * Deserialize a Squads Policy account and extract the ProgramInteraction data.
+ *
+ * Account layout:
+ *   8   bytes: discriminator
+ *   32  bytes: settings (Pubkey)
+ *   8   bytes: seed (u64)
+ *   1   byte:  bump (u8)
+ *   8   bytes: transaction_index (u64)
+ *   8   bytes: stale_transaction_index (u64)
+ *   4   bytes: signers vec length
+ *   N*(32+1): signers (Pubkey + Permissions{mask: u8})
+ *   2   bytes: threshold (u16)
+ *   4   bytes: time_lock (u32)
+ *   ...       policy_state (enum)
+ */
+function deserializeProgramInteractionPolicyFromAccount(
+  data: Buffer,
+  address?: PublicKey,
+): ProgramInteractionPolicy | null {
+  if (data.length < 65) return null
+
+  let offset = 8 // skip discriminator
+
+  // settings: Pubkey
+  const settings = new PublicKey(data.subarray(offset, offset + 32))
+  offset += 32
+
+  // seed: u64
+  offset += 8
+
+  // bump: u8
+  offset += 1
+
+  // transaction_index: u64
+  offset += 8
+
+  // stale_transaction_index: u64
+  offset += 8
+
+  // signers: Vec<SmartAccountSigner>
+  const signersLen = data.readUInt32LE(offset)
+  offset += 4
+  if (signersLen > 100) return null
+  const signers: PublicKey[] = []
+  for (let i = 0; i < signersLen; i++) {
+    signers.push(new PublicKey(data.subarray(offset, offset + 32)))
+    offset += 32
+    offset += 1
+  }
+
+  // threshold: u16
+  offset += 2
+
+  // time_lock: u32
+  offset += 4
+
+  // policy_state: enum variant
+  if (offset >= data.length) return null
+  const variant = data[offset]
+  offset += 1
+
+  // We only care about ProgramInteraction (variant 3)
+  if (variant !== 3) return null
+
+  return deserializeProgramInteractionPolicy(data, offset, settings, signers, address)
+}
+
+function deserializeProgramInteractionPolicy(
+  data: Buffer,
+  offset: number,
+  settings: PublicKey,
+  signers: PublicKey[],
+  address?: PublicKey,
+): ProgramInteractionPolicy | null {
+  if (offset >= data.length) return null
+
+  // account_index: u8
+  const accountIndex = data[offset]
+  offset += 1
+
+  // instructions_constraints: Vec<InstructionConstraint>
+  const constraintsLen = data.readUInt32LE(offset)
+  offset += 4
+
+  const instructionsConstraints: InstructionConstraint[] = []
+  for (let i = 0; i < constraintsLen; i++) {
+    const result = deserializeInstructionConstraint(data, offset)
+    if (!result) break
+    instructionsConstraints.push(result.constraint)
+    offset = result.newOffset
+  }
+
+  // pre_hook: Option<Hook>
+  const preHookResult = deserializeOptionHook(data, offset)
+  const preHook = preHookResult?.hook ?? null
+  if (preHookResult) offset = preHookResult.newOffset
+
+  // post_hook: Option<Hook>
+  const postHookResult = deserializeOptionHook(data, offset)
+  const postHook = postHookResult?.hook ?? null
+  if (postHookResult) offset = postHookResult.newOffset
+
+  // spending_limits: Vec<SpendingLimitV2>
+  if (offset + 4 > data.length) return null
+  const spendingLimitsLen = data.readUInt32LE(offset)
+  offset += 4
+  for (let i = 0; i < spendingLimitsLen; i++) {
+    offset = skipSpendingLimitV2(data, offset)
+    if (offset < 0) return null
+  }
+
+  // start: i64
+  if (offset + 8 > data.length) return null
+  offset += 8
+
+  const expirationResult = deserializePolicyExpirationOption(data, offset)
+  if (!expirationResult) return null
+
+  return {
+    address,
+    settings,
+    signers,
+    accountIndex,
+    instructionsConstraints,
+    preHook,
+    postHook,
+    requiresSettingsStateAccount: expirationResult.requiresSettingsStateAccount,
+  }
+}
+
+function skipSpendingLimitV2(data: Buffer, offset: number): number {
+  // mint: Pubkey
+  if (offset + 32 > data.length) return -1
+  offset += 32
+
+  // time_constraints.start: i64
+  if (offset + 8 > data.length) return -1
+  offset += 8
+
+  // time_constraints.expiration: Option<i64>
+  if (offset >= data.length) return -1
+  const hasExpiration = data[offset]
+  offset += 1
+  if (hasExpiration === 1) {
+    if (offset + 8 > data.length) return -1
+    offset += 8
+  } else if (hasExpiration !== 0) {
+    return -1
+  }
+
+  // time_constraints.period: PeriodV2
+  if (offset >= data.length) return -1
+  const periodVariant = data[offset]
+  offset += 1
+  if (periodVariant === 4) {
+    if (offset + 8 > data.length) return -1
+    offset += 8
+  } else if (periodVariant > 4) {
+    return -1
+  }
+
+  // time_constraints.accumulate_unused: bool
+  if (offset + 1 > data.length) return -1
+  offset += 1
+
+  // quantity_constraints: u64 + u64 + bool
+  if (offset + 17 > data.length) return -1
+  offset += 17
+
+  // usage: u64 + i64
+  if (offset + 16 > data.length) return -1
+  offset += 16
+
+  return offset
+}
+
+function deserializePolicyExpirationOption(
+  data: Buffer,
+  offset: number,
+): { requiresSettingsStateAccount: boolean; newOffset: number } | null {
+  if (offset >= data.length) return null
+
+  const hasExpiration = data[offset]
+  offset += 1
+  if (hasExpiration === 0) {
+    return { requiresSettingsStateAccount: false, newOffset: offset }
+  }
+  if (hasExpiration !== 1 || offset >= data.length) {
+    return null
+  }
+
+  const variant = data[offset]
+  offset += 1
+  if (variant === 0) {
+    if (offset + 8 > data.length) return null
+    return { requiresSettingsStateAccount: false, newOffset: offset + 8 }
+  }
+  if (variant === 1) {
+    if (offset + 32 > data.length) return null
+    return { requiresSettingsStateAccount: true, newOffset: offset + 32 }
+  }
+
+  return null
+}
+
+function deserializeInstructionConstraint(
+  data: Buffer,
+  offset: number,
+): { constraint: InstructionConstraint; newOffset: number } | null {
+  if (offset + 32 >= data.length) return null
+
+  // program_id: Pubkey
+  const programId = new PublicKey(data.slice(offset, offset + 32))
+  offset += 32
+
+  // account_constraints: Vec<AccountConstraintEntry>
+  const accountConstraintsLen = data.readUInt32LE(offset)
+  offset += 4
+  const accountConstraints: InstructionConstraint["accountConstraints"] = []
+  for (let i = 0; i < accountConstraintsLen; i++) {
+    if (offset >= data.length) return null
+
+    // account_index: u8
+    const index = data[offset]
+    offset += 1
+
+    // account_constraint: AccountConstraintType enum
+    const constraintVariant = data[offset]
+    offset += 1
+
+    if (constraintVariant === 0) {
+      // Pubkey variant: Vec<Pubkey>
+      const pubkeysLen = data.readUInt32LE(offset)
+      offset += 4
+      const addresses: PublicKey[] = []
+      for (let j = 0; j < pubkeysLen; j++) {
+        if (offset + 32 > data.length) return null
+        const address = new PublicKey(data.slice(offset, offset + 32))
+        offset += 32
+        addresses.push(address)
+      }
+      accountConstraints.push({ index, addresses, dataConstraints: [], owner: null })
+    } else if (constraintVariant === 1) {
+      if (offset + 4 > data.length) return null
+
+      const accountDataConstraintsLen = data.readUInt32LE(offset)
+      offset += 4
+      const dataConstraints: InstructionConstraint["accountConstraints"][number]["dataConstraints"] = []
+      for (let j = 0; j < accountDataConstraintsLen; j++) {
+        const result = deserializeDataConstraint(data, offset)
+        if (!result) return null
+        dataConstraints.push(result.constraint)
+        offset = result.newOffset
+      }
+
+      accountConstraints.push({ index, addresses: [], dataConstraints, owner: null })
+    } else {
+      return null // Unknown variant
+    }
+
+    // owner: Option<Pubkey>
+    if (offset >= data.length) return null
+    const hasOwner = data[offset]
+    offset += 1
+    if (hasOwner === 1) {
+      if (offset + 32 > data.length) return null
+      accountConstraints[accountConstraints.length - 1].owner = new PublicKey(data.slice(offset, offset + 32))
+      offset += 32
+    }
+  }
+
+  // data_constraints: Vec<DataConstraint>
+  const dataConstraintsLen = data.readUInt32LE(offset)
+  offset += 4
+  const dataConstraints: InstructionConstraint["dataConstraints"] = []
+  for (let i = 0; i < dataConstraintsLen; i++) {
+    const result = deserializeDataConstraint(data, offset)
+    if (!result) break
+    dataConstraints.push(result.constraint)
+    offset = result.newOffset
+  }
+
+  return {
+    constraint: { programId, accountConstraints, dataConstraints },
+    newOffset: offset,
+  }
+}
+
+function deserializeDataConstraint(
+  data: Buffer,
+  offset: number,
+): { constraint: InstructionConstraint["dataConstraints"][0]; newOffset: number } | null {
+  if (offset + 9 >= data.length) return null
+
+  // data_offset: u64
+  const dataOffset = Number(data.readBigUInt64LE(offset))
+  offset += 8
+
+  // data_value: DataValue enum
+  const valueResult = deserializeDataValue(data, offset)
+  if (!valueResult) return null
+  offset = valueResult.newOffset
+
+  // operator: u8
+  if (offset >= data.length) return null
+  const operator = data[offset]
+  offset += 1
+
+  return {
+    constraint: { offset: dataOffset, data: valueResult.bytes, operator },
+    newOffset: offset,
+  }
+}
+
+function deserializeDataValue(data: Buffer, offset: number): { bytes: Uint8Array; newOffset: number } | null {
+  if (offset >= data.length) return null
+
+  const variant = data[offset]
+  offset += 1
+
+  let byteLen: number
+  switch (variant) {
+    case 0:
+      byteLen = 1
+      break // U8
+    case 1:
+      byteLen = 2
+      break // U16Le
+    case 2:
+      byteLen = 4
+      break // U32Le
+    case 3:
+      byteLen = 8
+      break // U64Le
+    case 4:
+      byteLen = 16
+      break // U128Le
+    case 5: {
+      // U8Slice
+      if (offset + 4 > data.length) return null
+      byteLen = data.readUInt32LE(offset)
+      offset += 4
+      if (offset + byteLen > data.length) return null
+      const slice = data.slice(offset, offset + byteLen)
+      offset += byteLen
+      return { bytes: new Uint8Array(slice), newOffset: offset }
+    }
+    default:
+      return null
+  }
+
+  if (offset + byteLen > data.length) return null
+  const fixedBytes = data.slice(offset, offset + byteLen)
+  offset += byteLen
+  return { bytes: new Uint8Array(fixedBytes), newOffset: offset }
+}
+
+// ============================================================================
+// Hook Deserialization
+// ============================================================================
+
+/**
+ * Deserialize an Option<Hook> from policy data.
+ *
+ * Hook layout:
+ *   num_extra_accounts: u8
+ *   account_constraints: Vec<AccountConstraint>  (skip)
+ *   instruction_data: bytes (Vec<u8>)            (skip)
+ *   program_id: Pubkey                           (extract)
+ *   pass_inner_instructions: bool                (skip)
+ */
+function deserializeOptionHook(data: Buffer, offset: number): { hook: HookInfo | null; newOffset: number } | null {
+  if (offset >= data.length) return null
+
+  // Option discriminant: 0 = None, 1 = Some
+  const hasHook = data[offset]
+  offset += 1
+
+  if (hasHook === 0) {
+    return { hook: null, newOffset: offset }
+  }
+  if (hasHook !== 1) return null
+
+  // num_extra_accounts: u8
+  if (offset >= data.length) return null
+  const numExtraAccounts = data[offset]
+  offset += 1
+
+  // account_constraints: Vec<AccountConstraint> — skip over
+  if (offset + 4 > data.length) return null
+  const acLen = data.readUInt32LE(offset)
+  offset += 4
+  for (let i = 0; i < acLen; i++) {
+    offset = skipAccountConstraint(data, offset)
+    if (offset < 0) return null
+  }
+
+  // instruction_data: bytes (Vec<u8> = 4-byte LE length + data)
+  if (offset + 4 > data.length) return null
+  const instrDataLen = data.readUInt32LE(offset)
+  offset += 4
+  offset += instrDataLen
+  if (offset > data.length) return null
+
+  // program_id: Pubkey
+  if (offset + 32 > data.length) return null
+  const programId = new PublicKey(data.slice(offset, offset + 32))
+  offset += 32
+
+  // pass_inner_instructions: bool
+  if (offset >= data.length) return null
+  offset += 1
+
+  return { hook: { programId, numExtraAccounts }, newOffset: offset }
+}
+
+/**
+ * Skip over a single AccountConstraint in the buffer.
+ * Returns new offset, or -1 on failure.
+ */
+function skipAccountConstraint(data: Buffer, offset: number): number {
+  if (offset >= data.length) return -1
+
+  // account_index: u8
+  offset += 1
+
+  // account_constraint: AccountConstraintType enum
+  if (offset >= data.length) return -1
+  const variant = data[offset]
+  offset += 1
+
+  if (variant === 0) {
+    // Pubkey variant: Vec<Pubkey>
+    if (offset + 4 > data.length) return -1
+    const pubkeysLen = data.readUInt32LE(offset)
+    offset += 4
+    offset += pubkeysLen * 32
+  } else if (variant === 1) {
+    // AccountData variant: Vec<DataConstraint>
+    if (offset + 4 > data.length) return -1
+    const dcLen = data.readUInt32LE(offset)
+    offset += 4
+    for (let i = 0; i < dcLen; i++) {
+      const result = deserializeDataConstraint(data, offset)
+      if (!result) return -1
+      offset = result.newOffset
+    }
+  } else {
+    return -1
+  }
+
+  // owner: Option<Pubkey>
+  if (offset >= data.length) return -1
+  const hasOwner = data[offset]
+  offset += 1
+  if (hasOwner === 1) {
+    offset += 32
+  }
+
+  if (offset > data.length) return -1
+  return offset
+}
+
+// ============================================================================
+// Hook Account Resolution
+// ============================================================================
+
+/** Exponent Vaults program ID (validate_interaction_hook program) */
+const EXPONENT_VAULTS_PROGRAM_ID = new PublicKey("sVau1tXvayVWfotzm9Ahcv2qfnnfRWttt78BCnNC6dD")
+
+/**
+ * Fetch the on-chain Squads policy and resolve the extra remaining accounts it
+ * expects before the actual instruction account list.
+ *
+ * For the Exponent Vaults validate_interaction_hook post_hook, the accounts are:
+ *   [hook_program_id, vault_address (writable)]
+ *
+ * @param vaultAddress - The ExponentStrategyVault PDA (not the Squads vault PDA)
+ * @throws if the policy has an unrecognized hook program
+ */
+export async function resolveHookAccounts(
+  connection: Connection,
+  policyPda: PublicKey,
+  vaultAddress: PublicKey,
+  payer: PublicKey,
+): Promise<{ leadingAccounts: AccountMeta[]; preHookAccounts: AccountMeta[]; postHookAccounts: AccountMeta[] }> {
+  const accountInfo = await connection.getAccountInfo(policyPda)
+  if (!accountInfo) {
+    throw new Error(`Policy account not found: ${policyPda.toBase58()}`)
+  }
+
+  const policy = deserializeProgramInteractionPolicyFromAccount(accountInfo.data)
+  if (!policy) {
+    throw new Error(`Failed to deserialize ProgramInteraction policy from ${policyPda.toBase58()}`)
+  }
+
+  const leadingAccounts: AccountMeta[] = []
+  const preHookAccounts: AccountMeta[] = []
+  const postHookAccounts: AccountMeta[] = []
+  const strategyVault =
+    policy.preHook || policy.postHook
+      ? await StrategyVault.load({ env: LOCAL_ENV, connection, address: vaultAddress })
+      : null
+
+  if (policy.requiresSettingsStateAccount) {
+    leadingAccounts.push({ pubkey: policy.settings, isSigner: false, isWritable: false })
+  }
+
+  if (policy.preHook) {
+    preHookAccounts.push(...buildHookAccounts(policy.preHook, strategyVault, vaultAddress, payer, null))
+  }
+
+  if (policy.postHook) {
+    postHookAccounts.push(...buildHookAccounts(policy.postHook, strategyVault, vaultAddress, payer, policyPda))
+  }
+
+  return { leadingAccounts, preHookAccounts, postHookAccounts }
+}
+
+function buildHookAccounts(
+  hook: HookInfo,
+  strategyVault: StrategyVault | null,
+  vaultAddress: PublicKey,
+  payer: PublicKey,
+  /** For post_hook only: Squads policy (consensus_account) for validate_interaction policy.settings check */
+  squadsPolicyPda: PublicKey | null,
+): AccountMeta[] {
+  const accounts: AccountMeta[] = [{ pubkey: hook.programId, isSigner: false, isWritable: false }]
+
+  if (hook.programId.equals(EXPONENT_VAULTS_PROGRAM_ID)) {
+    if (!strategyVault) {
+      throw new Error(`Strategy vault ${vaultAddress.toBase58()} is required to resolve Exponent hook accounts`)
+    }
+
+    const [exponentPrices] = strategyVault.deriveExponentPricesAddress()
+    accounts.push(
+      { pubkey: vaultAddress, isSigner: false, isWritable: true },
+      { pubkey: exponentPrices, isSigner: false, isWritable: false },
+      { pubkey: strategyVault.mintLp, isSigner: false, isWritable: false },
+      { pubkey: payer, isSigner: true, isWritable: true },
+      { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+      { pubkey: SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false },
+    )
+    if (squadsPolicyPda) {
+      accounts.push({ pubkey: squadsPolicyPda, isSigner: false, isWritable: false })
+    }
+  } else if (hook.numExtraAccounts > 0) {
+    throw new Error(
+      `Hook program ${hook.programId.toBase58()} requires ${hook.numExtraAccounts} extra accounts but auto-resolution is not supported for this program. Pass hook accounts manually.`,
+    )
+  }
+
+  return accounts
+}
+
+/**
+ * Fetch a policy's post_hook num_extra_accounts from chain.
+ * Use for diagnostics: Exponent's validate_interaction post_hook expects 7.
+ * If this returns 6, policies were created with an older SDK/program — rebuild and create a fresh vault.
+ */
+export async function getPolicyPostHookNumExtraAccounts(
+  connection: Connection,
+  policyPda: PublicKey,
+): Promise<number | null> {
+  const accountInfo = await connection.getAccountInfo(policyPda)
+  if (!accountInfo) return null
+  const policy = deserializeProgramInteractionPolicyFromAccount(accountInfo.data)
+  return policy?.postHook?.numExtraAccounts ?? null
+}