@crediolabs/policy-synth 0.1.0

package/src/record/index.ts

@@ -0,0 +1,224 @@
+// src/record/index.ts - the recorder orchestrator.
+//
+// `recordTransaction(input)` is the single public entry point for the
+// synthesizer (the next phase) to consume. Two modes:
+//   - on-chain (hash set): fetch via the injected RPC fetcher (default:
+//     public Soroban RPC for the requested network).
+//   - simulation/XDR (xdr set): decode the provided envelope XDR directly.
+//
+// In both modes the recorder:
+//   1. Decodes the envelope to sourceAccount, signers, invocations (+ diagnostic
+//      subInvocations), args -> ScVal subset.
+//   2. Extracts token movements from raw events (or skips in XDR mode).
+//   3. Validates the parsed movements/invocations against the raw events.
+//   4. Computes parseConfidence.
+//   5. Refuses with ToolError RECORDING_VALIDATION_FAILED when overall < threshold.
+//
+// Returns ToolResponse<RecordedTransaction> per the canonical envelope
+// defined in src/errors.ts.
+
+import type { xdr } from '@stellar/stellar-sdk'
+import type { ToolError, ToolResponse } from '../errors.ts'
+import type { Network, ParseConfidence, RecordedTransaction } from '../types.ts'
+import type { DecodedTransaction } from './decode.ts'
+import {
+  contractEventsToOnChainEvents,
+  DecodeError,
+  decodeEnvelope,
+  decodeEnvelopeXdr,
+  transactionEventsToOnChainEvents,
+} from './decode.ts'
+import {
+  buildLowConfidenceQuestion,
+  computeParseConfidence,
+  isBelowThreshold,
+} from './freshness.ts'
+import { extractTokenMovements } from './movements.ts'
+import { createRpcServer, type RpcFetcher } from './rpc.ts'
+import { validateAgainstEvents } from './validate.ts'
+
+/** Public input shape. The brief pins:
+ *    - exactly one of `hash` / `xdr`
+ *    - `network` for hash mode (selects the public RPC)
+ *    - optional injected `fetcher` for tests + custom RPC endpoints
+ *    - optional `confidenceOverride` to relax the gate (default 1.0)
+ *
+ *  In xdr mode `network` is still required so the caller documents intent
+ *  (the synthesis downstream consumes it).
+ */
+export interface RecordInput {
+  hash?: string
+  xdr?: string
+  network: Network
+  fetcher?: RpcFetcher
+  confidenceOverride?: number
+}
+
+export type RecordResult = ToolResponse<RecordedTransaction>
+
+export async function recordTransaction(input: RecordInput): Promise<RecordResult> {
+  if (!input.network) {
+    return err('RECORDING_FAILED', 'network required', false)
+  }
+  // A confidenceOverride outside [0, 1] would disable the fail-closed gate (a
+  // negative threshold can never be exceeded), so reject it up front.
+  if (
+    input.confidenceOverride !== undefined &&
+    (!Number.isFinite(input.confidenceOverride) ||
+      input.confidenceOverride < 0 ||
+      input.confidenceOverride > 1)
+  ) {
+    return err(
+      'RECORDING_FAILED',
+      'confidenceOverride must be a finite number within [0, 1]',
+      false
+    )
+  }
+  const hasHash = typeof input.hash === 'string' && input.hash.length > 0
+  const hasXdr = typeof input.xdr === 'string' && input.xdr.length > 0
+  if (hasHash && hasXdr) {
+    return err('RECORDING_FAILED', 'provide exactly one of `hash` or `xdr`, not both', false)
+  }
+  if (!hasHash && !hasXdr) {
+    return err('RECORDING_FAILED', 'one of `hash` or `xdr` is required', false)
+  }
+
+  // === Phase 1: fetch + decode ===
+  let decoded: DecodedTransaction
+
+  if (hasHash) {
+    const fetcher = input.fetcher ?? createRpcServer(input.network)
+    const hash = input.hash
+    if (!hash) return err('RECORDING_FAILED', 'hash required for on-chain mode', false)
+    const fetched = await fetcher(hash)
+    if (!fetched) {
+      return err('RECORDING_FAILED', `transaction ${hash} not found on ${input.network}`, true)
+    }
+    const events = combineEvents(fetched.events)
+    try {
+      decoded = decodeEnvelope(
+        fetched.envelopeXdr,
+        events,
+        [],
+        fetched.ledger,
+        undefined,
+        input.network
+      )
+    } catch (e) {
+      if (e instanceof DecodeError) return err('RECORDING_FAILED', e.message, false)
+      throw e
+    }
+    return finish(input.network, decoded, input.confidenceOverride)
+  }
+
+  // XDR mode has no raw on-chain events, so the events-based cross-check is
+  // skipped. parseConfidence reaches 1.0 when every invocation matches a
+  // known protocol interface or pinned address; a confidenceOverride is only
+  // needed when the caller wants to lower the gate below the default 1.0.
+  const xdrStr = input.xdr
+  if (!xdrStr) return err('RECORDING_FAILED', 'xdr required for simulation mode', false)
+  try {
+    decoded = decodeEnvelopeXdr(xdrStr, [], [], 0, undefined, input.network)
+  } catch (e) {
+    if (e instanceof DecodeError) return err('RECORDING_FAILED', e.message, false)
+    return err(
+      'RECORDING_FAILED',
+      `failed to decode base64 envelope XDR: ${(e as Error).message}`,
+      false
+    )
+  }
+  return finish(input.network, decoded, input.confidenceOverride)
+}
+
+function combineEvents(raw: {
+  transactionEventsXdr: xdr.TransactionEvent[]
+  contractEventsXdr: xdr.ContractEvent[][]
+}): ReturnType<typeof contractEventsToOnChainEvents> {
+  const a = transactionEventsToOnChainEvents(raw.transactionEventsXdr)
+  const b = contractEventsToOnChainEvents(raw.contractEventsXdr)
+  const seen = new Set<string>()
+  const merged: typeof a = []
+  for (const e of [...a, ...b]) {
+    const k = `${e.contract}|${e.topics.join(',')}|${JSON.stringify(e.data)}`
+    if (seen.has(k)) continue
+    seen.add(k)
+    merged.push(e)
+  }
+  return merged
+}
+
+/** Apply freshness + validate + refuse gate, then build the RecordedTransaction
+ *  on success. */
+function finish(
+  network: Network,
+  decoded: DecodedTransaction,
+  confidenceOverride: number | undefined
+): RecordResult {
+  // === Phase 2: extract token movements ===
+  const tokenMovements = extractTokenMovements(decoded.events, decoded.opaqueScVals)
+
+  // === Phase 3: validate against events (fail-closed) ===
+  if (decoded.events.length > 0) {
+    const failure = validateAgainstEvents(tokenMovements, decoded.events)
+    if (failure) {
+      const te: ToolError = {
+        code: 'RECORDING_VALIDATION_FAILED',
+        message: failure.message,
+        severity: 'error',
+        retryable: false,
+        details: failure.details,
+        remediation: {
+          userQuestion: {
+            code: failure.code,
+            question: `Recording refused: ${failure.message}. Inspect details and re-run record_transaction against a re-fetched transaction.`,
+          },
+        },
+      }
+      return { ok: false, error: te }
+    }
+  }
+
+  // === Phase 4: parseConfidence + refuse gate ===
+  let confidence: ParseConfidence = computeParseConfidence({
+    knownContracts: decoded.knownContracts,
+    unknownContracts: decoded.unknownContracts,
+    opaqueScVals: decoded.opaqueScVals,
+  })
+  if (typeof confidenceOverride === 'number') {
+    confidence = { ...confidence, thresholdUsed: confidenceOverride }
+  }
+  if (isBelowThreshold(confidence)) {
+    const te: ToolError = {
+      code: 'RECORDING_VALIDATION_FAILED',
+      message: `parseConfidence ${confidence.overall} < threshold ${confidence.thresholdUsed}`,
+      severity: 'error',
+      retryable: false,
+      details: confidence,
+      remediation: {
+        userQuestion: {
+          code: 'PARSE_CONFIDENCE_BELOW_THRESHOLD',
+          question: buildLowConfidenceQuestion(confidence),
+        },
+      },
+    }
+    return { ok: false, error: te }
+  }
+
+  const recorded: RecordedTransaction = {
+    network,
+    signers: decoded.signers,
+    invocations: decoded.invocations,
+    tokenMovements,
+    events: decoded.events,
+    authEntries: decoded.authEntries,
+    ledgerSequence: decoded.ledgerSequence,
+    fetchedAt: Math.floor(Date.now() / 1000),
+    parseConfidence: confidence,
+    sourceAccount: decoded.sourceAccount,
+  }
+  return { ok: true, data: recorded }
+}
+
+function err(code: ToolError['code'], message: string, retryable: boolean): RecordResult {
+  return { ok: false, error: { code, message, severity: 'error', retryable } }
+}

package/src/record/movements.ts

@@ -0,0 +1,188 @@
+// src/record/movements.ts - raw on-chain contract events -> TokenMovement[].
+//
+// SEP-41 / SAC `transfer` / `mint` / `burn` events emit topics shaped as:
+//   topics[0] = Symbol("transfer") | "mint" | "burn"
+//   topics[1] = Address (from)            (transfer only - omitted for mint; burn "from" is the caller)
+//   topics[2] = Address (to)               (transfer + mint; burn uses a single from)
+//   data      = Vec<ScVal> { Address to, I128 amount }  (for transfer on classic SAC)
+//                OR I128 amount directly                 (for some token flavours)
+//
+// We accept both shapes; the validator reuses these as keys to cross-check
+// against the parsed invocation args.
+
+import type { xdr } from '@stellar/stellar-sdk'
+import type { OnChainEvent, TokenMovement } from '../types.ts'
+import { decodeScAddressToAnyStrkey, i128PartsToBigInt, u64PartsToBigInt } from './decode.ts'
+
+const TRANSFER = 'transfer'
+const MINT = 'mint'
+const BURN = 'burn'
+
+/** Extract TokenMovement[] from a list of raw on-chain events. Pure: no IO,
+ *  no network. Non-movement events are ignored; malformed movement events are
+ *  recorded as opaque so the recorder can fail closed. */
+export function extractTokenMovements(
+  events: OnChainEvent[],
+  opaqueScVals: Array<{ path: string; type: string }> = []
+): TokenMovement[] {
+  const out: TokenMovement[] = []
+  events.forEach((evt, index) => {
+    try {
+      const moved = parseSingleEvent(evt)
+      if (moved) {
+        out.push(moved)
+      } else if (isMovementEvent(evt)) {
+        opaqueScVals.push({ path: `events[${index}]`, type: movementDecodeFailure(evt) })
+      }
+    } catch {
+      opaqueScVals.push({ path: `events[${index}]`, type: 'undecodable-token-movement' })
+    }
+  })
+  return out
+}
+
+function isMovementEvent(evt: OnChainEvent): boolean {
+  const op = evt.topics[0]
+  return op === TRANSFER || op === MINT || op === BURN
+}
+
+function movementDecodeFailure(evt: OnChainEvent): string {
+  const address = evt.topics.slice(1).find((topic) => topic.startsWith('M'))
+  return address ? 'unsupported-muxed-address-topic' : 'undecodable-token-movement'
+}
+
+function parseSingleEvent(evt: OnChainEvent): TokenMovement | null {
+  const [head, second, third] = evt.topics
+  if (!head) return null
+  const op = head
+  if (op !== TRANSFER && op !== MINT && op !== BURN) return null
+
+  // Read the `amount` from the event data; the contract address is the emitter.
+  const token = evt.contract
+  if (!token) return null
+
+  const amount = readAmount(evt.data)
+  if (amount === null) return null
+
+  if (op === TRANSFER) {
+    // topics[1] = from, topics[2] = to
+    const from = second ? addressTopic(second) : null
+    const to = third ? addressTopic(third) : null
+    if (!from || !to) return null
+    return { token, from, to, amount }
+  }
+  if (op === MINT) {
+    // topics[1] = admin (optional), topics[2] = to (sometimes). Some SEP-41 mints
+    // only emit one address topic. Best-effort: prefer topics[2], then data.to.
+    const to = third ? addressTopic(third) : readDataAddress(evt.data, 0)
+    if (!to) return null
+    return { token, from: 'mint', to, amount }
+  }
+  // BURN
+  // topics[1] = from (the burned holder). Some burns also surface a "from" in data.
+  const from = second ? addressTopic(second) : readDataAddress(evt.data, 0)
+  if (!from) return null
+  return { token, from, to: 'burn', amount }
+}
+
+/** Read an I128 amount from an event data ScVal. Supports:
+ *    - data is I128 directly
+ *    - data is a Vec whose [0] (or [1] for SAC transfer) is I128
+ *    - data is a Vec whose [0] is a Map { 'amount': I128 }
+ *    - data is U64 (fallback for amount fields encoded as u64) */
+export function readAmount(data: OnChainEvent['data']): string | null {
+  if (data.type === 'i128') return data.value
+  if (data.type === 'u64') return data.value
+  if (data.type !== 'vec') return null
+  const v = data.value
+  // SAC transfer event data shape (some clients): Vec<Address, I128>
+  for (const item of v) {
+    if (item.type === 'i128') return item.value
+    if (item.type === 'u64') return item.value
+  }
+  // Some flavours wrap in a Map. We expose Map entries as other; bail.
+  return null
+}
+
+/** Extract a single address from an event data ScVal at the given vec index. */
+function readDataAddress(data: OnChainEvent['data'], index: number): string | null {
+  if (data.type !== 'vec') return null
+  const item = data.value[index]
+  if (item?.type !== 'address') return null
+  return item.value
+}
+
+/** Convert a topic-string back into an address strkey if it looks like one.
+ *  Topics we previously encoded as `<kind>` (non-address fallback) are left
+ *  alone. */
+function addressTopic(s: string): string | null {
+  if (s.startsWith('G') || s.startsWith('C')) return s
+  return null
+}
+
+/** Re-decode a single ContractEvent body into a TokenMovement-shaped tuple,
+ *  given the raw xdr.ScVal form (NOT the OnChainEvent subset). Used by the
+ *  integration test to compare against the parse path without depending on
+ *  the OnChainEvent subset. */
+export function parseContractEventToMovement(
+  emitterC: string,
+  body: xdr.ContractEventV0
+): TokenMovement | null {
+  const topics = body.topics()
+  if (topics.length === 0) return null
+  const head = topics[0]
+  if (!head) return null
+  const op = head.switch().name === 'scvSymbol' ? head.sym().toString() : ''
+  if (op !== TRANSFER && op !== MINT && op !== BURN) return null
+
+  const data = body.data()
+  const amountScval = pickAmountScval(data)
+  const amount = amountScval
+    ? amountScval.switch().name === 'scvI128'
+      ? i128PartsToBigInt(amountScval.i128()).toString()
+      : amountScval.switch().name === 'scvU64'
+        ? u64PartsToBigInt(amountScval.u64()).toString()
+        : null
+    : null
+  if (amount === null) return null
+
+  if (op === TRANSFER) {
+    const from =
+      topics[1] && topics[1].switch().name === 'scvAddress'
+        ? decodeScAddressToAnyStrkey(topics[1].address())
+        : null
+    const to =
+      topics[2] && topics[2].switch().name === 'scvAddress'
+        ? decodeScAddressToAnyStrkey(topics[2].address())
+        : null
+    if (!from || !to) return null
+    return { token: emitterC, from, to, amount }
+  }
+  if (op === MINT) {
+    const to =
+      topics[2] && topics[2].switch().name === 'scvAddress'
+        ? decodeScAddressToAnyStrkey(topics[2].address())
+        : null
+    if (!to) return null
+    return { token: emitterC, from: 'mint', to, amount }
+  }
+  // BURN
+  const from =
+    topics[1] && topics[1].switch().name === 'scvAddress'
+      ? decodeScAddressToAnyStrkey(topics[1].address())
+      : null
+  if (!from) return null
+  return { token: emitterC, from, to: 'burn', amount }
+}
+
+function pickAmountScval(data: xdr.ScVal): xdr.ScVal | null {
+  const kind = data.switch().name
+  if (kind === 'scvI128' || kind === 'scvU64') return data
+  if (kind !== 'scvVec') return null
+  const arr = data.vec() ?? []
+  for (const item of arr) {
+    const k = item.switch().name
+    if (k === 'scvI128' || k === 'scvU64') return item
+  }
+  return null
+}

package/src/record/rpc.ts

@@ -0,0 +1,88 @@
+// src/record/rpc.ts - isolates the network side-effect from the rest of the recorder.
+//
+// Everything else in the recorder (decode, movements, freshness, validate) is pure.
+// Unit tests inject a fetcher so they never hit the network; the integration test
+// uses the real Soroban RPC through `createRpcServer`.
+
+import { rpc, type xdr } from '@stellar/stellar-sdk'
+import type { Network } from '../types.ts'
+
+/** A trimmed-down view of `rpc.Api.GetSuccessfulTransactionResponse` plus the
+ *  failed-shape variant. Both are produced by Soroban RPC `getTransaction` on
+ *  a successful or failed tx; missing/pending returns `null`. */
+export interface SorobanTxResponse {
+  status: 'SUCCESS' | 'FAILED'
+  ledger: number
+  createdAt: number
+  txHash: string
+  envelopeXdr: xdr.TransactionEnvelope
+  resultXdr?: xdr.TransactionResult
+  resultMetaXdr?: xdr.TransactionMeta
+  events: rpc.Api.TransactionEvents
+}
+
+export type RpcFetcher = (hash: string) => Promise<SorobanTxResponse | null>
+
+const PUBLIC_RPC_URLS: Record<Network, string> = {
+  testnet: 'https://soroban-testnet.stellar.org',
+  // The brief pins testnet; mainnet is left to the caller via injection. We keep
+  // a public default that matches the brief's note ("e.g. https://mainnet.sorobanrpc.com").
+  mainnet: 'https://mainnet.sorobanrpc.com',
+}
+
+/** Build a fetcher backed by the public Soroban RPC for the given network.
+ *  Injectable by tests via the `fetcher` parameter to `recordTransaction`. */
+export function createRpcServer(network: Network): RpcFetcher {
+  const server = new rpc.Server(PUBLIC_RPC_URLS[network], { allowHttp: false })
+  return async (hash: string): Promise<SorobanTxResponse | null> => {
+    const resp = await server.getTransaction(hash)
+    if (resp.status === rpc.Api.GetTransactionStatus.NOT_FOUND) {
+      return null
+    }
+    if (resp.status === rpc.Api.GetTransactionStatus.SUCCESS) {
+      return {
+        status: 'SUCCESS',
+        ledger: resp.ledger,
+        createdAt: resp.createdAt,
+        txHash: resp.txHash,
+        envelopeXdr: resp.envelopeXdr,
+        resultXdr: resp.resultXdr,
+        resultMetaXdr: resp.resultMetaXdr,
+        events: resp.events,
+      }
+    }
+    return {
+      status: 'FAILED',
+      ledger: resp.ledger,
+      createdAt: resp.createdAt,
+      txHash: resp.txHash,
+      envelopeXdr: resp.envelopeXdr,
+      resultXdr: resp.resultXdr,
+      resultMetaXdr: resp.resultMetaXdr,
+      events: resp.events,
+    }
+  }
+}
+
+/** Lightweight reachability probe used by the integration test to decide whether
+ *  to run or self-skip. Sends a JSON-RPC `getHealth` to the public endpoint. */
+export async function probeNetwork(network: Network, timeoutMs = 3000): Promise<boolean> {
+  const url = PUBLIC_RPC_URLS[network]
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const resp = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getHealth' }),
+      signal: controller.signal,
+    })
+    if (!resp.ok) return false
+    const json = (await resp.json()) as { result?: { status?: string } }
+    return json.result?.status === 'healthy'
+  } catch {
+    return false
+  } finally {
+    clearTimeout(timer)
+  }
+}

package/src/record/validate.ts

@@ -0,0 +1,75 @@
+// src/record/validate.ts - cross-check parsed TokenMovements against the raw
+// on-chain events. NOT by re-parsing.
+//
+// Why events-based validation matters: the parse path is the thing we are
+// trying to harden. Validating parse output by re-running the parser can only
+// catch a parser bug that manifests the same way twice. Cross-checking against
+// the canonical event stream is what catches real drift.
+//
+// Skips:
+//   - simulation/XDR mode: there are no raw events to compare against. The
+//     orchestrator reflects the reduced certainty in parseConfidence (any
+//     unknown contract or opaque ScVal reduces overall below 1) and the gate
+//     refuses the recording.
+
+import type { OnChainEvent, TokenMovement } from '../types.ts'
+import { tokenMovementKey } from './decode.ts'
+import { extractTokenMovements } from './movements.ts'
+
+export interface ValidationFailure {
+  code: 'MOVEMENT_PARSE_NOT_IN_EVENTS' | 'MOVEMENT_EVENT_NOT_PARSED'
+  message: string
+  details: unknown
+}
+
+/** Cross-check parsed movements against the raw on-chain events.
+ *  Returns null when validation passes; otherwise the first failure found.
+ *
+ *  Mode:
+ *   - on-chain mode (events.length > 0): full movement cross-check, fail-closed.
+ *   - simulation/XDR mode (events.length === 0): SKIPPED - the caller surfaces
+ *     the reduced certainty via parseConfidence.
+ *
+ *  We intentionally do NOT require every invocation to have an attributable
+ *  event. A Soroban call's events are commonly emitted by inner contracts
+ *  (token SACs) that are not in the auth-derived invocation tree, so a
+ *  per-invocation "did it emit an event" check produces false refusals on
+ *  legitimate transactions. The real guards are the movement cross-check below
+ *  plus parseConfidence (unknown contracts / opaque ScVals).
+ */
+export function validateAgainstEvents(
+  parsedMovements: TokenMovement[],
+  events: OnChainEvent[]
+): ValidationFailure | null {
+  // Simulation/XDR mode - skip cross-check, return null (no failure).
+  if (events.length === 0) return null
+
+  // Compute the set of movements the raw events IMPLY.
+  const eventMovements = extractTokenMovements(events)
+  const eventKeySet = new Set(eventMovements.map(tokenMovementKey))
+  const parsedKeySet = new Set(parsedMovements.map(tokenMovementKey))
+
+  // 1. Every parsed movement must appear in the raw events.
+  for (const m of parsedMovements) {
+    if (!eventKeySet.has(tokenMovementKey(m))) {
+      return {
+        code: 'MOVEMENT_PARSE_NOT_IN_EVENTS',
+        message: `parsed TokenMovement not present in raw events`,
+        details: { movement: m },
+      }
+    }
+  }
+
+  // 2. Every raw-event movement must appear in the parsed set.
+  for (const m of eventMovements) {
+    if (!parsedKeySet.has(tokenMovementKey(m))) {
+      return {
+        code: 'MOVEMENT_EVENT_NOT_PARSED',
+        message: `raw event implies a movement that the parse missed`,
+        details: { movement: m },
+      }
+    }
+  }
+
+  return null
+}

package/src/registry/identify.ts

@@ -0,0 +1,99 @@
+// src/registry/identify.ts - protocol identification (fail-closed).
+//
+// Given a (contract, method, args) triple, decide whether the call belongs
+// to a known protocol. Returns null when it does NOT - the caller MUST
+// preserve the fail-closed posture for null results.
+//
+// Recognition rules:
+//   1. SEP-41: recognised by INTERFACE - any contract calling one of the
+//      SEP-41 fns (transfer / mint / burn / approve) with a matching arg
+//      shape is a SEP-41 token. No address pin is needed.
+//   2. Blend: recognised by INTERFACE - real pool `submit` / `claim` calls
+//      hit per-pool instances, not the factory. The arg shape must match
+//      the Blend pool ABI (verified against the pool contract source).
+//      Address recognition still applies when the call is against the
+//      pinned factory address, with the same arg-shape check.
+//   3. SoroSwap: recognised by ADDRESS only - the router is a single pinned
+//      contract. FIX 4: the method must ALSO be present in the protocol's
+//      ABI; an unknown method on a pinned router -> null (fail-closed).
+//
+// Method lookup uses `Object.hasOwn` rather than `in` so prototype-chain
+// names like `constructor`, `toString`, `hasOwnProperty` do NOT register as
+// valid method calls. Arg-shape validation compares arg count + each arg's
+// ScVal subset type against the ABI signature; mismatch -> null.
+
+import type { ScVal } from '../types.ts'
+import { addressToProtocol } from './known-addresses.ts'
+import type { AbiArg, ProtocolId } from './protocols.ts'
+import { BLEND_ABI, SEP41_ABI, SOROSWAP_ABI } from './protocols.ts'
+
+export interface IdentifiedProtocol {
+  protocol: ProtocolId
+  fn: string
+}
+
+/** Identify the protocol for a single (contract, method, args) invocation.
+ *  Returns null on ANY mismatch (method not in ABI, arg count off, arg type
+ *  off, or unknown method on a pinned address). The caller MUST keep the
+ *  null path fail-closed. */
+export function identifyProtocol(
+  contract: string,
+  method: string,
+  args: ScVal[],
+  network?: 'mainnet' | 'testnet'
+): IdentifiedProtocol | null {
+  // 1) SEP-41 by interface. Any contract whose (method, args) matches a
+  //    SEP-41 ABI signature is a SEP-41 token.
+  if (Object.hasOwn(SEP41_ABI, method)) {
+    const sig = SEP41_ABI[method]
+    if (sig && argsMatchAbi(sig.args, args)) {
+      return { protocol: 'sep41', fn: method }
+    }
+    return null
+  }
+
+  // 2) Blend by interface. Real pool calls hit per-pool instances; pinned
+  //    factory calls also match here when the method is in the pool ABI.
+  if (Object.hasOwn(BLEND_ABI, method)) {
+    const sig = BLEND_ABI[method]
+    if (sig && argsMatchAbi(sig.args, args)) {
+      return { protocol: 'blend', fn: method }
+    }
+    return null
+  }
+
+  // 3) Pinned-address recognition (Blend factory + SoroSwap router/factory).
+  //    FIX 4: the method must also be in the protocol's ABI; an unknown
+  //    method on a pinned address -> null.
+  if (network) {
+    const pinned = addressToProtocol(contract, network)
+    if (pinned) {
+      const abi = pinned === 'blend' ? BLEND_ABI : SOROSWAP_ABI
+      if (Object.hasOwn(abi, method)) {
+        const sig = abi[method]
+        if (sig && argsMatchAbi(sig.args, args)) {
+          return { protocol: pinned, fn: method }
+        }
+      }
+    }
+  }
+
+  void contract
+  return null
+}
+
+/** Compare the decoded args against the ABI signature. Returns true only when
+ *  the arg count matches AND every arg's ScVal subset type matches the ABI's
+ *  declared type. `other` is intentionally NOT a valid ABI match - it means
+ *  the decoder couldn't classify the value, which is exactly the signal
+ *  fail-closed should refuse. */
+function argsMatchAbi(expected: AbiArg[], actual: ScVal[]): boolean {
+  if (expected.length !== actual.length) return false
+  for (let i = 0; i < expected.length; i += 1) {
+    const want = expected[i]
+    const got = actual[i]
+    if (!want || !got) return false
+    if (want.type !== got.type) return false
+  }
+  return true
+}