@crediolabs/policy-synth 0.1.4 → 0.1.6

package/dist-cjs/record/index.js

@@ -0,0 +1,191 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordTransaction = recordTransaction;
+const decode_ts_1 = require("./decode.js");
+const freshness_ts_1 = require("./freshness.js");
+const movements_ts_1 = require("./movements.js");
+const rpc_ts_1 = require("./rpc.js");
+const validate_ts_1 = require("./validate.js");
+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 ?? (0, rpc_ts_1.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) {
+            // Item 2: cross-network sanity check. The default NOT_FOUND message
+            // ("transaction X not found on <network>") is not actionable when the
+            // user just used the wrong --network. Probe the OTHER network's
+            // fetcher before giving up: if the hash actually exists there, the
+            // user almost certainly passed the wrong network flag. Trade-off:
+            // one extra RPC round-trip ONLY on the NOT_FOUND path (the happy
+            // path is unchanged; NOT_FOUND is rare). The probe is auto-built
+            // from createRpcServer(otherNetwork) when the caller did not inject
+            // one; tests pass an explicit stub for offline determinism.
+            const otherNetwork = input.network === 'mainnet' ? 'testnet' : 'mainnet';
+            const crossFetcher = input.crossNetworkFetcher ?? (0, rpc_ts_1.createRpcServer)(otherNetwork);
+            const crossFetched = await crossFetcher(hash);
+            if (crossFetched) {
+                return err('RECORDING_FAILED', `transaction ${hash} not found on ${input.network}; it exists on ${otherNetwork}. Re-run with --network ${otherNetwork} (or the corresponding MCP / API field).`, true);
+            }
+            return err('RECORDING_FAILED', `transaction ${hash} not found on ${input.network}`, true);
+        }
+        const events = combineEvents(fetched.events);
+        try {
+            decoded = (0, decode_ts_1.decodeEnvelope)(fetched.envelopeXdr, events, [], fetched.ledger, undefined, input.network);
+        }
+        catch (e) {
+            if (e instanceof decode_ts_1.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 = (0, decode_ts_1.decodeEnvelopeXdr)(xdrStr, [], [], 0, undefined, input.network);
+    }
+    catch (e) {
+        if (e instanceof decode_ts_1.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 = (0, decode_ts_1.transactionEventsToOnChainEvents)(raw.transactionEventsXdr);
+    const b = (0, decode_ts_1.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 = (0, movements_ts_1.extractTokenMovements)(decoded.events, decoded.opaqueScVals);
+    // === Phase 3: validate against events (fail-closed) ===
+    if (decoded.events.length > 0) {
+        const failure = (0, validate_ts_1.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 = (0, freshness_ts_1.computeParseConfidence)({
+        knownContracts: decoded.knownContracts,
+        unknownContracts: decoded.unknownContracts,
+        opaqueScVals: decoded.opaqueScVals,
+    });
+    // Item 1: surface the "zero contract invocations decoded" case explicitly.
+    // The math already pins overall = 1.0 via the `denom === 0` guard; the
+    // marker just makes the silence visible so a downstream synth can refuse
+    // the recording (a policy must scope to an authorized contract call)
+    // without inferring the situation from `invocations: []` next to a
+    // confidence of 1.0. Only set when zero invocations were actually decoded
+    // - the marker is a positive signal, not a default.
+    if (decoded.invocations.length === 0) {
+        confidence = { ...confidence, noInvocations: true };
+    }
+    if (typeof confidenceOverride === 'number') {
+        confidence = { ...confidence, thresholdUsed: confidenceOverride };
+    }
+    if ((0, freshness_ts_1.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: (0, freshness_ts_1.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-cjs/record/movements.d.ts

@@ -0,0 +1,32 @@
+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 U64 (fallback for amount fields encoded as u64)
+ *    - data is a Vec whose [0] (or [1] for SAC transfer) is I128 / U64
+ *    - data is a Vec whose [0] is a Map { 'amount': I128 | U64 }
+ *    - data is a Map whose entry with key "amount" is I128 / U64
+ *
+ *  The Map shapes are the canonical data layout for SAC/SEP-41 `transfer`,
+ *  `mint`, and `burn` events on Stellar mainnet, e.g. the USDC SAC and every
+ *  Stellar Asset Contract. The key `amount` is the SEP-41-defined field name
+ *  (verified empirically against txs 112d2392..., eb39f493..., 50d36f5c...
+ *  where the data is `Map { amount: I128, to_muxed_id: ... }`). The other
+ *  Map entries we observe in the wild (to_muxed_id, from_muxed_id) are
+ *  muxed-address adjuncts that the recorder does not support as topic
+ *  addresses; they are ignored here on purpose. A Map without an `amount`
+ *  entry, or with an `amount` entry that is not I128/U64, returns null
+ *  (fail-closed). */
+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-cjs/record/movements.js

@@ -0,0 +1,227 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractTokenMovements = extractTokenMovements;
+exports.readAmount = readAmount;
+exports.parseContractEventToMovement = parseContractEventToMovement;
+const decode_ts_1 = require("./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. */
+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 U64 (fallback for amount fields encoded as u64)
+ *    - data is a Vec whose [0] (or [1] for SAC transfer) is I128 / U64
+ *    - data is a Vec whose [0] is a Map { 'amount': I128 | U64 }
+ *    - data is a Map whose entry with key "amount" is I128 / U64
+ *
+ *  The Map shapes are the canonical data layout for SAC/SEP-41 `transfer`,
+ *  `mint`, and `burn` events on Stellar mainnet, e.g. the USDC SAC and every
+ *  Stellar Asset Contract. The key `amount` is the SEP-41-defined field name
+ *  (verified empirically against txs 112d2392..., eb39f493..., 50d36f5c...
+ *  where the data is `Map { amount: I128, to_muxed_id: ... }`). The other
+ *  Map entries we observe in the wild (to_muxed_id, from_muxed_id) are
+ *  muxed-address adjuncts that the recorder does not support as topic
+ *  addresses; they are ignored here on purpose. A Map without an `amount`
+ *  entry, or with an `amount` entry that is not I128/U64, returns null
+ *  (fail-closed). */
+function readAmount(data) {
+    if (data.type === 'i128')
+        return data.value;
+    if (data.type === 'u64')
+        return data.value;
+    if (data.type === 'map')
+        return readAmountFromMap(data.value);
+    if (data.type !== 'vec')
+        return null;
+    // Vec shape: walk the elements and accept the first I128/U64 OR a Map whose
+    // 'amount' entry is I128/U64. SAC transfer event data is sometimes
+    // Vec<Address, I128> and sometimes Vec<Map{amount: I128}, ...>; both reach
+    // the same code path below.
+    for (const item of data.value) {
+        if (item.type === 'i128')
+            return item.value;
+        if (item.type === 'u64')
+            return item.value;
+        if (item.type === 'map') {
+            const fromMap = readAmountFromMap(item.value);
+            if (fromMap !== null)
+                return fromMap;
+        }
+    }
+    return null;
+}
+/** Try to extract an I128/U64 amount from a Map's `amount` entry. Returns
+ *  null when the Map lacks an `amount` key or the entry is not a numeric
+ *  ScVal kind this recorder understands. */
+function readAmountFromMap(entries) {
+    for (const entry of entries) {
+        if (entry.key !== 'amount')
+            continue;
+        if (entry.val.type === 'i128')
+            return entry.val.value;
+        if (entry.val.type === 'u64')
+            return entry.val.value;
+        return null;
+    }
+    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. */
+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'
+            ? (0, decode_ts_1.i128PartsToBigInt)(amountScval.i128()).toString()
+            : amountScval.switch().name === 'scvU64'
+                ? (0, decode_ts_1.u64PartsToBigInt)(amountScval.u64()).toString()
+                : null
+        : null;
+    if (amount === null)
+        return null;
+    if (op === TRANSFER) {
+        const from = topics[1] && topics[1].switch().name === 'scvAddress'
+            ? (0, decode_ts_1.decodeScAddressToAnyStrkey)(topics[1].address())
+            : null;
+        const to = topics[2] && topics[2].switch().name === 'scvAddress'
+            ? (0, decode_ts_1.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'
+            ? (0, decode_ts_1.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'
+        ? (0, decode_ts_1.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-cjs/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-cjs/record/rpc.js

@@ -0,0 +1,74 @@
+"use strict";
+// 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`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRpcServer = createRpcServer;
+exports.probeNetwork = probeNetwork;
+const stellar_sdk_1 = require("@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`. */
+function createRpcServer(network) {
+    const server = new stellar_sdk_1.rpc.Server(PUBLIC_RPC_URLS[network], { allowHttp: false });
+    return async (hash) => {
+        const resp = await server.getTransaction(hash);
+        if (resp.status === stellar_sdk_1.rpc.Api.GetTransactionStatus.NOT_FOUND) {
+            return null;
+        }
+        if (resp.status === stellar_sdk_1.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. */
+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-cjs/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-cjs/record/validate.js

@@ -0,0 +1,63 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAgainstEvents = validateAgainstEvents;
+const decode_ts_1 = require("./decode.js");
+const movements_ts_1 = require("./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).
+ */
+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 = (0, movements_ts_1.extractTokenMovements)(events);
+    const eventKeySet = new Set(eventMovements.map(decode_ts_1.tokenMovementKey));
+    const parsedKeySet = new Set(parsedMovements.map(decode_ts_1.tokenMovementKey));
+    // 1. Every parsed movement must appear in the raw events.
+    for (const m of parsedMovements) {
+        if (!eventKeySet.has((0, decode_ts_1.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((0, decode_ts_1.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-cjs/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;