@crediolabs/policy-synth 0.3.1 → 0.5.0

package/dist/install/read-account-rules.js

@@ -0,0 +1,241 @@
+//! Reading an OpenZeppelin smart account's context rules back off chain.
+//!
+//! `authority-overlap.ts` needs to know what a signer can already do before a
+//! new policy is installed. That means every rule on the account: its context
+//! type, its signers, its attached policies, and - for rules our interpreter
+//! polices - the predicate itself.
+//!
+//! Without this, the overlap scan can only report on rules the CALLER supplied,
+//! which means it answers "what did you tell me about" rather than "what is on
+//! the account". Those are different questions, and only the second one is
+//! worth anything to someone deciding whether to sign.
+//!
+//! The predicate is NOT reachable through a contract call. The interpreter
+//! publishes only `grammar_version`, `install`, `enforce`, `uninstall` and
+//! `rotate_master_signer_set`, so the stored document is read as a ledger entry
+//! instead. That keeps this a purely client-side capability: adding a getter
+//! would change a deployed contract's ABI and force a redeploy plus re-audit to
+//! obtain data the ledger already exposes.
+//!
+//! The decoders are pure so they can be tested without a network; the caller
+//! supplies raw `ScVal`s.
+import { Account, Address, BASE_FEE, Contract, Keypair, rpc, TransactionBuilder, xdr, } from '@stellar/stellar-sdk';
+import { decodePredicate } from "../predicate/decode.js";
+/** `storage.rs` - the third element of the persistent doc key tuple. */
+export const K_DOC = 1;
+/** Persistent-storage key for a rule's stored document:
+ *  `(account, rule_id, K_DOC)`. */
+export function docKeyScVal(smartAccount, ruleId) {
+    return xdr.ScVal.scvVec([
+        new Address(smartAccount).toScVal(),
+        xdr.ScVal.scvU32(ruleId),
+        xdr.ScVal.scvU32(K_DOC),
+    ]);
+}
+/** Ledger key for the interpreter's persistent entry holding that document. */
+export function docLedgerKey(interpreter, smartAccount, ruleId) {
+    return xdr.LedgerKey.contractData(new xdr.LedgerKeyContractData({
+        contract: new Address(interpreter).toScAddress(),
+        key: docKeyScVal(smartAccount, ruleId),
+        durability: xdr.ContractDataDurability.persistent(),
+    }));
+}
+// ---- ScVal helpers -----
+/** Field of a `#[contracttype]` struct, which the host encodes as a map keyed
+ *  by field-name symbol. Returns undefined when the field is absent so a
+ *  caller can distinguish "not there" from "there and empty". */
+function mapField(v, name) {
+    if (v.switch() !== xdr.ScValType.scvMap())
+        return undefined;
+    for (const entry of v.map() ?? []) {
+        const key = entry.key();
+        if (key.switch() === xdr.ScValType.scvSymbol() && key.sym().toString() === name) {
+            return entry.val();
+        }
+    }
+    return undefined;
+}
+function u32Of(v) {
+    return v?.switch() === xdr.ScValType.scvU32() ? v.u32() : undefined;
+}
+function addressOf(v) {
+    if (!v || v.switch() !== xdr.ScValType.scvAddress())
+        return undefined;
+    return Address.fromScAddress(v.address()).toString();
+}
+/** An enum variant of a `#[contracttype]` enum: `ScVal::Vec([Symbol, ...args])`. */
+function enumVariant(v) {
+    if (!v || v.switch() !== xdr.ScValType.scvVec())
+        return undefined;
+    const items = v.vec() ?? [];
+    const head = items[0];
+    if (!head || head.switch() !== xdr.ScValType.scvSymbol())
+        return undefined;
+    return { tag: head.sym().toString(), args: items.slice(1) };
+}
+// ---- decoders -----
+/** OZ `ContextRuleType`. An unrecognised tag is reported as `default`, which
+ *  is the widest reading and therefore the safe one: it makes the rule look
+ *  like it could serve any call, so overlap is over-reported, never missed. */
+export function decodeContextType(v) {
+    const variant = enumVariant(v);
+    if (!variant)
+        return { kind: 'default' };
+    if (variant.tag === 'CallContract') {
+        const addr = addressOf(variant.args[0]);
+        return addr ? { kind: 'call_contract', contract: addr } : { kind: 'default' };
+    }
+    if (variant.tag === 'CreateContract') {
+        const arg = variant.args[0];
+        const hash = arg?.switch() === xdr.ScValType.scvBytes() ? arg.bytes().toString('hex') : '';
+        return { kind: 'create_contract', wasmHash: hash };
+    }
+    return { kind: 'default' };
+}
+/** OZ `Signer::Delegated(Address) | Signer::External(Address, Bytes)`. */
+export function decodeSigner(v) {
+    const variant = enumVariant(v);
+    if (!variant)
+        return undefined;
+    if (variant.tag === 'Delegated') {
+        const addr = addressOf(variant.args[0]);
+        return addr ? { kind: 'delegated', address: addr } : undefined;
+    }
+    if (variant.tag === 'External') {
+        const verifier = addressOf(variant.args[0]);
+        const keyArg = variant.args[1];
+        const keyBytes = keyArg?.switch() === xdr.ScValType.scvBytes() ? keyArg.bytes().toString('hex') : '';
+        return verifier ? { kind: 'external', verifier, keyBytes } : undefined;
+    }
+    return undefined;
+}
+/** A full OZ `ContextRule` as returned by `get_context_rule(id)`.
+ *  `predicate` is filled in separately from the ledger entry. */
+export function decodeContextRule(v) {
+    const id = u32Of(mapField(v, 'id'));
+    if (id === undefined)
+        return undefined;
+    const signersVal = mapField(v, 'signers');
+    const signers = [];
+    if (signersVal?.switch() === xdr.ScValType.scvVec()) {
+        for (const s of signersVal.vec() ?? []) {
+            const decoded = decodeSigner(s);
+            if (decoded)
+                signers.push(decoded);
+        }
+    }
+    const policiesVal = mapField(v, 'policies');
+    const policyAddresses = [];
+    if (policiesVal?.switch() === xdr.ScValType.scvVec()) {
+        for (const p of policiesVal.vec() ?? []) {
+            const addr = addressOf(p);
+            if (addr)
+                policyAddresses.push(addr);
+        }
+    }
+    return {
+        id,
+        contextType: decodeContextType(mapField(v, 'context_type')),
+        signers,
+        policyAddresses,
+    };
+}
+/** The interpreter's `StoredDoc { predicate_bytes }`. */
+export function decodeStoredPredicateBytes(v) {
+    const field = mapField(v, 'predicate_bytes');
+    if (!field || field.switch() !== xdr.ScValType.scvBytes())
+        return undefined;
+    return field.bytes();
+}
+/** How far the id scan will probe before giving up. OZ imposes no per-account
+ *  rule cap, so there is no exact bound to derive; this one is far above any
+ *  realistic account and keeps a malformed `Count` from spinning forever. */
+export const MAX_RULE_ID_SCAN = 512;
+/**
+ * Every context rule on the account, with predicates filled in for the rules
+ * our interpreter polices.
+ *
+ * Rule ids are NOT contiguous. OZ assigns them from a monotonic `NextId` and
+ * decrements `Count` on removal without ever reusing an id, so after any
+ * removal `Count < NextId` and the live ids have gaps. Iterating `0..Count-1`
+ * would silently skip live rules at higher ids, and a skipped rule is a missed
+ * overlap - the one error that reports safety which does not exist. Instead the
+ * scan walks ids upward until it has accounted for `Count` live rules.
+ *
+ * A rule whose predicate cannot be read is deliberately left without one. That
+ * demotes it to the `foreign` class, so the scan reports it as opaque instead
+ * of assuming it is narrow.
+ */
+export async function collectObservedRules(args) {
+    const count = await args.reader.getContextRuleCount(args.smartAccount);
+    const limit = args.maxRuleIdScan ?? MAX_RULE_ID_SCAN;
+    const rules = [];
+    const unreadablePredicateRuleIds = [];
+    let id = 0;
+    while (rules.length < count && id < limit) {
+        const raw = await args.reader.getContextRule(args.smartAccount, id);
+        id++;
+        if (!raw)
+            continue;
+        const rule = decodeContextRule(raw);
+        if (!rule)
+            continue;
+        if (rule.policyAddresses.includes(args.interpreterAddress)) {
+            const doc = await args.reader.getStoredDoc(args.interpreterAddress, args.smartAccount, rule.id);
+            const bytes = doc ? decodeStoredPredicateBytes(doc) : undefined;
+            if (bytes) {
+                try {
+                    rule.predicate = decodePredicate(bytes);
+                }
+                catch {
+                    unreadablePredicateRuleIds.push(rule.id);
+                }
+            }
+            else {
+                unreadablePredicateRuleIds.push(rule.id);
+            }
+        }
+        rules.push(rule);
+    }
+    return { rules, unreadablePredicateRuleIds, incomplete: rules.length < count };
+}
+/**
+ * An `AccountRuleReader` over a live RPC server.
+ *
+ * The two OZ getters are read-only simulations: the source account is
+ * constructed locally because a simulation never checks its sequence number,
+ * and asking the network for a random key would 404.
+ *
+ * The stored document is fetched as a ledger entry rather than a contract
+ * call, because the interpreter publishes no getter for it.
+ */
+export function accountRuleReaderFromServer(server, networkPassphrase) {
+    async function simulateCall(contract, method, ...args) {
+        const account = new Account(Keypair.random().publicKey(), '0');
+        const tx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase })
+            .addOperation(new Contract(contract).call(method, ...args))
+            .setTimeout(30)
+            .build();
+        const sim = await server.simulateTransaction(tx);
+        if (rpc.Api.isSimulationError(sim))
+            return undefined;
+        return sim.result?.retval;
+    }
+    return {
+        async getContextRuleCount(smartAccount) {
+            const val = await simulateCall(smartAccount, 'get_context_rules_count');
+            return u32Of(val) ?? 0;
+        },
+        async getContextRule(smartAccount, ruleId) {
+            return simulateCall(smartAccount, 'get_context_rule', xdr.ScVal.scvU32(ruleId));
+        },
+        async getStoredDoc(interpreter, smartAccount, ruleId) {
+            const key = docLedgerKey(interpreter, smartAccount, ruleId);
+            const res = await server.getLedgerEntries(key);
+            const entry = res.entries?.[0]?.val;
+            if (!entry || entry.switch() !== xdr.LedgerEntryType.contractData())
+                return undefined;
+            return entry.contractData().val();
+        },
+    };
+}

package/dist/predicate/decode.js

@@ -55,6 +55,15 @@ function expectSymbol(v, what) {
         throw malformed(`${what} is not a symbol`);
     return v.sym().toString();
 }
+/** Strict i128, returned as a decimal string. Strict on purpose: the Rust
+ *  decoder refuses a u32 in an i128 slot rather than widening it, so
+ *  accepting one here would let a predicate decode off chain and be refused
+ *  on chain. */
+function expectI128(v, what) {
+    if (!v || v.switch() !== xdr.ScValType.scvI128())
+        throw malformed(`${what} is not an i128`);
+    return scValToBigInt(v).toString();
+}
 /** Arity check with the same intent as the Rust `check_arity`: a selector with
  *  the wrong element count is malformed, not silently truncated. */
 function arity(items, n, selector) {
@@ -84,6 +93,14 @@ function decodeSelectorLeaf(items, sym) {
                 element: expectU32(items[2], 'call_arg_field element'),
                 field: expectSymbol(items[3], 'call_arg_field field'),
             };
+        case 'call_arg_scaled':
+            arity(items, 4, sym);
+            return {
+                kind: 'call_arg_scaled',
+                index: expectU32(items[1], 'call_arg_scaled index'),
+                num: expectI128(items[2], 'call_arg_scaled num'),
+                den: expectI128(items[3], 'call_arg_scaled den'),
+            };
         default:
             // Deliberately NOT a literal_vec fallback - see the header note.
             throw malformed(`unknown selector symbol '${sym}'`);
@@ -120,7 +137,8 @@ export function decodeNode(v) {
     if (op === null)
         throw malformed('node does not start with an operator symbol');
     switch (op) {
-        case 'and': {
+        case 'and':
+        case 'or': {
             arity(items, 2, op);
             const children = expectVec(items[1], `${op} children`).map(decodeNode);
             if (children.length === 0)
@@ -128,7 +146,10 @@ export function decodeNode(v) {
             return { op, children };
         }
         case 'eq':
+        case 'lt':
         case 'lte':
+        case 'gt':
+        case 'gte':
             arity(items, 3, op);
             return {
                 op,

package/dist/predicate/encode.js

@@ -80,7 +80,8 @@ function computeStats(node) {
 }
 function walk(node, inCounts, counters) {
     switch (node.op) {
-        case 'and': {
+        case 'and':
+        case 'or': {
             if (node.children.length === 0) {
                 throw capError('MALFORMED_PREDICATE', `\`${node.op}\` with no children: the contract refuses it at decode (MALFORMED_PREDICATE), so it can never be installed`);
             }
@@ -95,7 +96,10 @@ function walk(node, inCounts, counters) {
             return { depth: maxChildDepth + 1, leaves: totalLeaves };
         }
         case 'eq':
-        case 'lte': {
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte': {
             collectSelector(node.left, counters);
             collectSelector(node.right, counters);
             return { depth: 1, leaves: leafCount(node.left) + leafCount(node.right) };
@@ -143,14 +147,20 @@ function collectSelector(leaf, counters) {
 }
 function encodeNode(node) {
     switch (node.op) {
-        case 'and': {
+        case 'and':
+        case 'or': {
             const encoded = node.children.map(encodeNode);
-            // sort children by their canonical XDR bytes ascending.
+            // sort children by their canonical XDR bytes ascending. Both operators
+            // are commutative for the permit decision, so sorting costs no meaning
+            // and buys a stable hash for logically-identical predicates.
             const sorted = sortByCanonicalBytes(encoded);
             return xdr.ScVal.scvVec([symbol(node.op), xdr.ScVal.scvVec(sorted)]);
         }
         case 'eq':
-        case 'lte': {
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte': {
             return xdr.ScVal.scvVec([symbol(node.op), encodeLeaf(node.left), encodeLeaf(node.right)]);
         }
         case 'in': {
@@ -181,6 +191,15 @@ function encodeLeaf(leaf) {
                 xdr.ScVal.scvU32(leaf.element),
                 xdr.ScVal.scvSymbol(leaf.field),
             ]);
+        case 'call_arg_scaled':
+            // num/den are i128 on the wire. The Rust decoder type-checks both
+            // slots, so a u32 here would be refused rather than widened.
+            return xdr.ScVal.scvVec([
+                symbol('call_arg_scaled'),
+                xdr.ScVal.scvU32(leaf.index),
+                scvI128FromDecimal(leaf.num),
+                scvI128FromDecimal(leaf.den),
+            ]);
         case 'literal_address':
             return scvAddressFromStrkey(leaf.value);
         case 'literal_i128':
@@ -266,6 +285,30 @@ function validateLeafValues(node) {
                     throw malformed(`call_arg_field.element out of u32 range at ${path}`);
                 }
                 return;
+            case 'call_arg_scaled': {
+                if (!Number.isInteger(leaf.index) || leaf.index < 0 || leaf.index > U32_MAX) {
+                    throw malformed(`call_arg_scaled.index out of u32 range at ${path}`);
+                }
+                // Mirror of the contract's install gate (214). Without it the TS
+                // self-verify would green-light a ratio the chain refuses, which is
+                // exactly the divergence this validator exists to prevent.
+                let num;
+                let den;
+                try {
+                    num = BigInt(leaf.num);
+                    den = BigInt(leaf.den);
+                }
+                catch {
+                    throw malformed(`call_arg_scaled num/den must be i128 decimal strings at ${path}`);
+                }
+                if (den === 0n) {
+                    throw malformed(`call_arg_scaled.den is zero at ${path}: the contract refuses it at install (INVALID_SCALED_RATIO)`);
+                }
+                if (num <= 0n || den < 0n) {
+                    throw malformed(`call_arg_scaled ratio ${leaf.num}/${leaf.den} at ${path} is not positive: a negative ratio inverts the comparison, so the floor would permit what it was written to refuse. The contract refuses it at install (INVALID_SCALED_RATIO)`);
+                }
+                return;
+            }
             case 'call_contract':
             case 'call_fn':
             case 'literal_address':
@@ -276,12 +319,16 @@ function validateLeafValues(node) {
     function walkNode(n, path) {
         switch (n.op) {
             case 'and':
+            case 'or':
                 n.children.forEach((c, i) => {
                     walkNode(c, `${path}.children[${i}]`);
                 });
                 return;
             case 'eq':
+            case 'lt':
             case 'lte':
+            case 'gt':
+            case 'gte':
                 walkLeaf(n.left, `${path}.left`);
                 walkLeaf(n.right, `${path}.right`);
                 return;

package/dist/predicate/from-json.js

@@ -17,9 +17,13 @@ export function jsonToAst(value) {
     const v = value;
     switch (v.op) {
         case 'and':
-            return { op: 'and', children: arrayOf(v.children, jsonToAst) };
+        case 'or':
+            return { op: v.op, children: arrayOf(v.children, jsonToAst) };
         case 'eq':
+        case 'lt':
         case 'lte':
+        case 'gt':
+        case 'gte':
             return { op: v.op, left: jsonToLeaf(v.left), right: jsonToLeaf(v.right) };
         case 'in':
             return { op: 'in', needle: jsonToLeaf(v.needle), haystack: arrayOf(v.haystack, jsonToLeaf) };
@@ -44,6 +48,15 @@ function jsonToLeaf(value) {
             return { kind: 'call_arg', index: numberField(v, 'index') };
         case 'call_arg_len':
             return { kind: 'call_arg_len', index: numberField(v, 'index') };
+        case 'call_arg_scaled':
+            // num/den stay decimal STRINGS: an i128 ratio does not survive a JS
+            // number, and silently rounding one would change the floor.
+            return {
+                kind: 'call_arg_scaled',
+                index: numberField(v, 'index'),
+                num: stringField(v, 'num'),
+                den: stringField(v, 'den'),
+            };
         case 'literal_address':
             return { kind: 'literal_address', value: stringField(v, 'value') };
         case 'literal_i128':

package/dist/record/index.d.ts

@@ -1,4 +1,5 @@
 import type { ToolResponse } from '../errors.ts';
+import { type SpecFetcher } from '../registry/on-chain-spec.ts';
 import type { Network, RecordedTransaction } from '../types.ts';
 import { type RpcFetcher } from './rpc.ts';
 /** Public input shape. The brief pins:
@@ -27,6 +28,15 @@ export interface RecordInput {
      *  automatically; tests can pass a deterministic stub. */
     crossNetworkFetcher?: RpcFetcher;
     confidenceOverride?: number;
+    /** Read a contract's own interface off chain when the compiled-in registry
+     *  does not recognise it. Default ON: the registry covers the protocols we
+     *  pinned by hand, and refusing everything else reported `no-abi` for
+     *  contracts that publish a full typed spec. Set false to record against
+     *  the registry alone (no extra RPC). */
+    resolveContractSpecs?: boolean;
+    /** Test seam for the spec lookup. Unset in production, where it is built
+     *  from the network's pinned RPC URL. */
+    specFetcher?: SpecFetcher;
 }
 export type RecordResult = ToolResponse<RecordedTransaction>;
 export declare function recordTransaction(input: RecordInput): Promise<RecordResult>;

package/dist/record/index.js

@@ -16,11 +16,40 @@
 //
 // Returns ToolResponse<RecordedTransaction> per the canonical envelope
 // defined in src/errors.ts.
+import { Networks } from '@stellar/stellar-sdk';
+import { resolveContractsByOnChainSpec, specFetcherFromRpc, } from "../registry/on-chain-spec.js";
 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 { createRpcServer, PUBLIC_RPC_URLS } from "./rpc.js";
 import { validateAgainstEvents } from "./validate.js";
+/** Second pass over the contracts the compiled-in registry did not recognise.
+ *
+ *  Each candidate's own interface is read off chain and every call it received
+ *  is checked against it; the ones that verify are fed back through the decoder
+ *  as known. Re-decoding rather than patching the first result keeps ONE code
+ *  path computing parseConfidence - a hand-adjusted count here would be a
+ *  second implementation of the gate, free to drift from the real one.
+ *
+ *  Only ever ADDS recognition. A missing spec, an unreachable RPC or a call the
+ *  interface does not describe all leave the recording exactly as it was. */
+async function resolveByOnChainSpec(input, decoded, redecode) {
+    if (input.resolveContractSpecs === false)
+        return decoded;
+    if (decoded.unknownContracts.length === 0)
+        return decoded;
+    const fetcher = input.specFetcher ??
+        specFetcherFromRpc(PUBLIC_RPC_URLS[input.network], input.network === 'mainnet' ? Networks.PUBLIC : Networks.TESTNET);
+    let resolved;
+    try {
+        resolved = await resolveContractsByOnChainSpec(decoded.invocations, decoded.unknownContracts.map((u) => u.contract), fetcher);
+    }
+    catch {
+        // A lookup failure must not fail the recording that already succeeded.
+        return decoded;
+    }
+    return resolved.size === 0 ? decoded : redecode(resolved);
+}
 export async function recordTransaction(input) {
     if (!input.network) {
         return err('RECORDING_FAILED', 'network required', false);
@@ -76,6 +105,7 @@ export async function recordTransaction(input) {
                 return err('RECORDING_FAILED', e.message, false);
             throw e;
         }
+        decoded = await resolveByOnChainSpec(input, decoded, (known) => decodeEnvelope(fetched.envelopeXdr, events, [], fetched.ledger, known, input.network));
         return finish(input.network, decoded, input.confidenceOverride);
     }
     // XDR mode has no raw on-chain events, so the events-based cross-check is
@@ -93,6 +123,7 @@ export async function recordTransaction(input) {
             return err('RECORDING_FAILED', e.message, false);
         return err('RECORDING_FAILED', `failed to decode base64 envelope XDR: ${e.message}`, false);
     }
+    decoded = await resolveByOnChainSpec(input, decoded, (known) => decodeEnvelopeXdr(xdrStr, [], [], 0, known, input.network));
     return finish(input.network, decoded, input.confidenceOverride);
 }
 function combineEvents(raw) {

package/dist/record/rpc.d.ts

@@ -14,6 +14,10 @@ export interface SorobanTxResponse {
     events: rpc.Api.TransactionEvents;
 }
 export type RpcFetcher = (hash: string) => Promise<SorobanTxResponse | null>;
+/** Exported so the on-chain spec lookup reads from the SAME endpoint the
+ *  recorder fetched the transaction from. Two different endpoints could
+ *  disagree about what a contract is. */
+export declare const PUBLIC_RPC_URLS: Record<Network, string>;
 /** 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;

package/dist/record/rpc.js

@@ -4,7 +4,10 @@
 // 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 = {
+/** Exported so the on-chain spec lookup reads from the SAME endpoint the
+ *  recorder fetched the transaction from. Two different endpoints could
+ *  disagree about what a contract is. */
+export 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").

package/dist/registry/identify.d.ts

@@ -1,5 +1,5 @@
 import type { ScVal } from '../types.ts';
-import type { ProtocolId } from './protocols.ts';
+import type { AbiArg, ProtocolId } from './protocols.ts';
 export interface IdentifiedProtocol {
     protocol: ProtocolId;
     fn: string;
@@ -9,3 +9,12 @@ export interface IdentifiedProtocol {
  *  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;
+/** 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. */
+/** Exported so the on-chain-spec path checks a call the SAME way a pinned
+ *  protocol does. Reimplementing it there would let the two drift, and a
+ *  looser copy would be the fail-OPEN direction. */
+export declare function argsMatchAbi(expected: AbiArg[], actual: ScVal[]): boolean;

package/dist/registry/identify.js

@@ -88,7 +88,10 @@ export function identifyProtocol(contract, method, args, network) {
  *  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) {
+/** Exported so the on-chain-spec path checks a call the SAME way a pinned
+ *  protocol does. Reimplementing it there would let the two drift, and a
+ *  looser copy would be the fail-OPEN direction. */
+export function argsMatchAbi(expected, actual) {
     if (expected.length !== actual.length)
         return false;
     for (let i = 0; i < expected.length; i += 1) {

package/dist/registry/on-chain-spec.d.ts

@@ -0,0 +1,37 @@
+import { contract as sdkContract } from '@stellar/stellar-sdk';
+import type { ContractInvocation } from '../types.ts';
+import type { AbiArgType, ProtocolAbi } from './protocols.ts';
+/** Map an XDR spec type to the ScVal subset vocabulary the matcher uses.
+ *
+ *  Returns null for a type the recorder's ScVal subset cannot represent. That
+ *  is deliberate: an argument we cannot type is an argument we cannot check,
+ *  and claiming a match on it would be the fail-OPEN direction. A function
+ *  with any such argument is dropped from the derived ABI, so a call to it
+ *  stays unrecognised rather than being waved through. */
+export declare function abiTypeFromSpecType(specTypeName: string): AbiArgType | null;
+/** The RPC surface this module needs. Narrowed to one method so a test can
+ *  supply a stub without standing up a server, and so the recorder's existing
+ *  RPC client can be passed straight in. */
+export interface SpecFetcher {
+    contractSpec(contractId: string): Promise<sdkContract.Spec | null>;
+}
+/** Build a `SpecFetcher` over the SDK's contract client. */
+export declare function specFetcherFromRpc(rpcUrl: string, networkPassphrase: string): SpecFetcher;
+/** Convert a fetched spec into the ABI shape `identifyProtocol` already
+ *  matches against. Functions with an argument outside the ScVal subset are
+ *  OMITTED rather than partially typed. */
+export declare function abiFromSpec(spec: sdkContract.Spec): ProtocolAbi;
+/** Fetch and convert in one step. Returns null when no usable interface was
+ *  obtained, which the caller must treat as "unrecognised". */
+export declare function fetchContractAbi(contractId: string, fetcher: SpecFetcher): Promise<ProtocolAbi | null>;
+/** Contracts whose EVERY recorded call matches their own published interface.
+ *
+ *  All-or-nothing per contract, deliberately. A contract where one call
+ *  verifies and another does not is a contract we do not understand, and
+ *  marking it recognised would raise confidence on the strength of the call
+ *  we happened to check. The unverified call is the one that matters.
+ *
+ *  A contract with no fetchable spec, or a call naming a function absent from
+ *  it, simply stays unknown - this only ever ADDS recognition, so a failure
+ *  here degrades to today's behaviour rather than to a wrong answer. */
+export declare function resolveContractsByOnChainSpec(invocations: ReadonlyArray<ContractInvocation>, candidates: ReadonlyArray<string>, fetcher: SpecFetcher): Promise<Set<string>>;