@crediolabs/policy-synth 0.1.0

package/dist/record/index.js

@@ -0,0 +1,163 @@
+// 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 { contractEventsToOnChainEvents, DecodeError, decodeEnvelope, decodeEnvelopeXdr, transactionEventsToOnChainEvents, } from "./decode.js";
+import { buildLowConfidenceQuestion, computeParseConfidence, isBelowThreshold, } from "./freshness.js";
+import { extractTokenMovements } from "./movements.js";
+import { createRpcServer } from "./rpc.js";
+import { validateAgainstEvents } from "./validate.js";
+export async function recordTransaction(input) {
+    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;
+    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.message}`, false);
+    }
+    return finish(input.network, decoded, input.confidenceOverride);
+}
+function combineEvents(raw) {
+    const a = transactionEventsToOnChainEvents(raw.transactionEventsXdr);
+    const b = contractEventsToOnChainEvents(raw.contractEventsXdr);
+    const seen = new Set();
+    const merged = [];
+    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, decoded, confidenceOverride) {
+    // === 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 = {
+                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 = computeParseConfidence({
+        knownContracts: decoded.knownContracts,
+        unknownContracts: decoded.unknownContracts,
+        opaqueScVals: decoded.opaqueScVals,
+    });
+    if (typeof confidenceOverride === 'number') {
+        confidence = { ...confidence, thresholdUsed: confidenceOverride };
+    }
+    if (isBelowThreshold(confidence)) {
+        const te = {
+            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 = {
+        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, message, retryable) {
+    return { ok: false, error: { code, message, severity: 'error', retryable } };
+}

package/dist/record/movements.d.ts

@@ -0,0 +1,20 @@
+import type { xdr } from '@stellar/stellar-sdk';
+import type { OnChainEvent, TokenMovement } from '../types.ts';
+/** 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 declare function extractTokenMovements(events: OnChainEvent[], opaqueScVals?: Array<{
+    path: string;
+    type: string;
+}>): TokenMovement[];
+/** 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 declare function readAmount(data: OnChainEvent['data']): string | 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 declare function parseContractEventToMovement(emitterC: string, body: xdr.ContractEventV0): TokenMovement | null;

package/dist/record/movements.js

@@ -0,0 +1,187 @@
+// 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 { decodeScAddressToAnyStrkey, i128PartsToBigInt, u64PartsToBigInt } from "./decode.js";
+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, opaqueScVals = []) {
+    const out = [];
+    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) {
+    const op = evt.topics[0];
+    return op === TRANSFER || op === MINT || op === BURN;
+}
+function movementDecodeFailure(evt) {
+    const address = evt.topics.slice(1).find((topic) => topic.startsWith('M'));
+    return address ? 'unsupported-muxed-address-topic' : 'undecodable-token-movement';
+}
+function parseSingleEvent(evt) {
+    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) {
+    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, index) {
+    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) {
+    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, body) {
+    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) {
+    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/dist/record/rpc.d.ts

@@ -0,0 +1,22 @@
+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>;
+/** Build a fetcher backed by the public Soroban RPC for the given network.
+ *  Injectable by tests via the `fetcher` parameter to `recordTransaction`. */
+export declare function createRpcServer(network: Network): RpcFetcher;
+/** 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 declare function probeNetwork(network: Network, timeoutMs?: number): Promise<boolean>;

package/dist/record/rpc.js

@@ -0,0 +1,70 @@
+// 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 } from '@stellar/stellar-sdk';
+const PUBLIC_RPC_URLS = {
+    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) {
+    const server = new rpc.Server(PUBLIC_RPC_URLS[network], { allowHttp: false });
+    return async (hash) => {
+        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, timeoutMs = 3000) {
+    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());
+        return json.result?.status === 'healthy';
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/record/validate.d.ts

@@ -0,0 +1,22 @@
+import type { OnChainEvent, TokenMovement } from '../types.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 declare function validateAgainstEvents(parsedMovements: TokenMovement[], events: OnChainEvent[]): ValidationFailure | null;

package/dist/record/validate.js

@@ -0,0 +1,60 @@
+// 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 { tokenMovementKey } from "./decode.js";
+import { extractTokenMovements } from "./movements.js";
+/** 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, events) {
+    // 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/dist/registry/identify.d.ts

@@ -0,0 +1,11 @@
+import type { ScVal } from '../types.ts';
+import type { ProtocolId } 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 declare function identifyProtocol(contract: string, method: string, args: ScVal[], network?: 'mainnet' | 'testnet'): IdentifiedProtocol | null;

package/dist/registry/identify.js

@@ -0,0 +1,84 @@
+// 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 { addressToProtocol } from "./known-addresses.js";
+import { BLEND_ABI, SEP41_ABI, SOROSWAP_ABI } from "./protocols.js";
+/** 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, method, args, network) {
+    // 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, actual) {
+    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;
+}

package/dist/registry/index.d.ts

@@ -0,0 +1,3 @@
+export { type IdentifiedProtocol, identifyProtocol, } from './identify.ts';
+export { addressToProtocol, KNOWN_ADDRESSES, type KnownAddressesByNetwork, type KnownAddressesByProtocol, } from './known-addresses.ts';
+export { type AbiArg, type AbiEntry, BLEND_ABI, getAbi, PROTOCOL_ABIS, type ProtocolAbi, type ProtocolId, SEP41_ABI, SOROSWAP_ABI, } from './protocols.ts';

package/dist/registry/index.js

@@ -0,0 +1,4 @@
+// src/registry/index.ts - re-export the protocol adjacency registry.
+export { identifyProtocol, } from "./identify.js";
+export { addressToProtocol, KNOWN_ADDRESSES, } from "./known-addresses.js";
+export { BLEND_ABI, getAbi, PROTOCOL_ABIS, SEP41_ABI, SOROSWAP_ABI, } from "./protocols.js";