@crediolabs/policy-synth 0.1.4 → 0.1.6

package/dist-cjs/record/decode.js

@@ -0,0 +1,441 @@
+"use strict";
+// src/record/decode.ts - pure XDR -> invocation tree decoder.
+//
+// Inputs: a base64-encoded TransactionEnvelope XDR (or one already decoded),
+// the raw transaction events (used only to identify contract emitters), and
+// (optionally) the auth-entry set.
+//
+// Outputs:
+//   - top-level ContractInvocation (the single Context `Policy::enforce` receives)
+//   - subInvocations captured on each ContractInvocation from
+//     SorobanAuthorizedInvocation.subInvocations - DIAGNOSTIC ONLY;
+//     v1 grammar does NOT walk sub-invocations (see types.ts notes).
+//   - decoded args vector mapped to the normalised `ScVal` subset
+//   - sourceAccount, signers
+//   - raw event list surfaced for downstream validation
+//   - auth entries surfaced for downstream validation
+//
+// No network calls. No randomness. No globals.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DecodeError = void 0;
+exports.decodeEnvelopeXdr = decodeEnvelopeXdr;
+exports.decodeEnvelope = decodeEnvelope;
+exports.decodeScAddressToAnyStrkey = decodeScAddressToAnyStrkey;
+exports.decodeScAddressToC = decodeScAddressToC;
+exports.scValToSubset = scValToSubset;
+exports.i128PartsToBigInt = i128PartsToBigInt;
+exports.u128PartsToBigInt = u128PartsToBigInt;
+exports.u64PartsToBigInt = u64PartsToBigInt;
+exports.scValToTopicString = scValToTopicString;
+exports.contractEventsToOnChainEvents = contractEventsToOnChainEvents;
+exports.transactionEventsToOnChainEvents = transactionEventsToOnChainEvents;
+exports.tokenMovementKey = tokenMovementKey;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const identify_ts_1 = require("../registry/identify.js");
+const types_ts_1 = require("../types.js");
+/** Decode a TransactionEnvelope XDR (base64) into a fully parsed invocation tree. */
+function decodeEnvelopeXdr(envelopeXdrB64, events = [], _authEntries = [], ledgerSequence = 0, knownContracts = new Set(), network = null) {
+    const envelope = stellar_sdk_1.xdr.TransactionEnvelope.fromXDR(envelopeXdrB64, 'base64');
+    return decodeEnvelope(envelope, events, _authEntries, ledgerSequence, knownContracts, network);
+}
+/** Same as `decodeEnvelopeXdr` but accepts an already-decoded envelope. Useful
+ *  for tests that build the envelope via SDK helpers (no XDR round-trip). */
+function decodeEnvelope(envelope, events = [], _authEntries = [], ledgerSequence = 0, knownContracts = new Set(), network = null) {
+    const envType = envelope.switch().name;
+    if (envType === 'envelopeTypeTxFeeBump') {
+        // Fee-bump wraps a normal inner v1 transaction (a different account
+        // pays the fee). The real operations + their authorizers live on the
+        // INNER v1 envelope, so decode that and discard the outer fee-bump
+        // shell. The fee-bump envelope switch arm `v0` is intentionally not
+        // routed here - fee-bump v0 does not exist.
+        const innerV1 = envelope.feeBump().tx().innerTx().v1();
+        return decodeV1Envelope(innerV1, events, ledgerSequence, knownContracts, network);
+    }
+    if (envType !== 'envelopeTypeTx') {
+        // TransactionV0 is out of scope - v1 protocol only. Fee-bump is now
+        // handled above; legacy envelopes reach this branch.
+        throw new DecodeError(`unsupported envelope: ${envType}`);
+    }
+    return decodeV1Envelope(envelope.v1(), events, ledgerSequence, knownContracts, network);
+}
+/** Decode a v1 TransactionEnvelope (either a top-level v1 envelope or the
+ *  inner v1 envelope of a fee-bump wrapper). Source, operations, auth
+ *  entries, signers all come from this v1 envelope. */
+function decodeV1Envelope(v1, events, ledgerSequence, knownContracts, network) {
+    const tx = v1.tx();
+    const sourceAccount = decodeMuxedOrEd25519(tx.sourceAccount());
+    const signers = extractSigners(v1, tx);
+    const invocations = [];
+    const projectedAuthEntries = [];
+    const opaqueScVals = [];
+    const knownContractSet = new Set();
+    const unknownContracts = [];
+    const knownContractsOut = [];
+    for (const op of tx.operations()) {
+        const body = op.body();
+        if (body.switch().name !== 'invokeHostFunction')
+            continue;
+        const invokeOp = body.invokeHostFunctionOp();
+        const auth = invokeOp.auth();
+        projectedAuthEntries.push(...auth.map(projectAuthEntry));
+        const hostFn = invokeOp.hostFunction();
+        if (hostFn.switch().name !== 'hostFunctionTypeInvokeContract')
+            continue;
+        const invokeArgs = hostFn.invokeContract();
+        const contract = decodeScAddressToC(invokeArgs.contractAddress());
+        const fn = symbolValueFromBufferOrString(invokeArgs.functionName());
+        const argsScval = invokeArgs.args();
+        const args = [];
+        argsScval.forEach((a, i) => {
+            args.push(scValToSubset(a, `args[${i}]`, opaqueScVals));
+        });
+        const subInvocations = decodeSubInvocations(auth, opaqueScVals);
+        invocations.push({ contract, fn, args, subInvocations });
+        recordInvocation(contract, fn, args, network, knownContracts, knownContractSet, knownContractsOut, unknownContracts);
+    }
+    return {
+        sourceAccount,
+        signers,
+        invocations,
+        events,
+        authEntries: projectedAuthEntries,
+        opaqueScVals,
+        unknownContracts,
+        knownContracts: knownContractsOut,
+        ledgerSequence,
+    };
+}
+/** Extract the union of signers from:
+ *    - envelope-level signatures (the tx-level signers), and
+ *    - Soroban auth entries that are `SorobanCredentials.sorobanCredentialsAddress`
+ *      (the contract-Caller authorised via ed25519/address credentials).
+ *  Returns G... strkeys (or address strkeys for non-account credentials). */
+function extractSigners(v1, tx) {
+    const set = new Set();
+    for (const sig of v1.signatures()) {
+        // Each signature has a 4-byte hint. We cannot recover the full strkey from
+        // a 4-byte hint alone - so we record it as `hint:<hex>` to preserve signal
+        // for the downstream reviewer without claiming a match we cannot prove.
+        const hintBytes = sig.hint();
+        set.add(`hint:${Buffer.from(hintBytes).toString('hex')}`);
+    }
+    // Soroban address credentials - recover the strkey address.
+    for (const op of tx.operations()) {
+        const body = op.body();
+        if (body.switch().name !== 'invokeHostFunction')
+            continue;
+        const invokeOp = body.invokeHostFunctionOp();
+        for (const entry of invokeOp.auth()) {
+            const creds = entry.credentials();
+            const kind = creds.switch().name;
+            if (kind === 'sorobanCredentialsAddress') {
+                const addrCreds = creds.address();
+                const scAddr = addrCreds.address();
+                try {
+                    const strkey = decodeScAddressToAnyStrkey(scAddr);
+                    if (strkey)
+                        set.add(strkey);
+                }
+                catch {
+                    // ignore - we record it as opaque via freshness
+                }
+            }
+            // sorobanCredentialsSourceAccount -> pulled from tx.sourceAccount() above
+        }
+    }
+    return Array.from(set);
+}
+const MAX_AUTH_TREE_DEPTH = 16;
+function projectAuthEntry(entry) {
+    const credentials = entry.credentials();
+    const authorizingAddress = credentials.switch().name === 'sorobanCredentialsAddress'
+        ? decodeScAddressToAnyStrkey(credentials.address().address())
+        : null;
+    const fn = entry.rootInvocation().function();
+    if (fn.switch().name === 'sorobanAuthorizedFunctionTypeContractFn') {
+        const contractFn = fn.contractFn();
+        return {
+            authorizingAddress,
+            contract: decodeScAddressToC(contractFn.contractAddress()),
+            fn: symbolValueFromBufferOrString(contractFn.functionName()),
+        };
+    }
+    return { authorizingAddress, contract: '', fn: '__create_contract__' };
+}
+function decodeSubInvocations(authEntries, opaqueScVals) {
+    return authEntries.flatMap((entry, index) => {
+        const decoded = decodeAuthorizedInvocation(entry.rootInvocation(), opaqueScVals, `auth[${index}].root`, 0);
+        return decoded ? [decoded] : [];
+    });
+}
+function decodeAuthorizedInvocation(inv, opaqueScVals, path, depth) {
+    if (depth >= MAX_AUTH_TREE_DEPTH) {
+        opaqueScVals.push({ path, type: 'auth-tree-depth-exceeded' });
+        return null;
+    }
+    const fn = inv.function();
+    if (fn.switch().name !== 'sorobanAuthorizedFunctionTypeContractFn')
+        return null;
+    const contractFn = fn.contractFn();
+    const contract = decodeScAddressToC(contractFn.contractAddress());
+    const fnName = symbolValueFromBufferOrString(contractFn.functionName());
+    const args = contractFn
+        .args()
+        .map((arg, index) => scValToSubset(arg, `${path}.args[${index}]`, opaqueScVals));
+    const subInvocations = inv.subInvocations().flatMap((child, index) => {
+        const decoded = decodeAuthorizedInvocation(child, opaqueScVals, `${path}.subInvocations[${index}]`, depth + 1);
+        return decoded ? [decoded] : [];
+    });
+    return { contract, fn: fnName, args, subInvocations };
+}
+/** Decode an ScAddress (either account or contract) to its strkey form. */
+function decodeScAddressToAnyStrkey(scAddr) {
+    const kind = scAddr.switch().name;
+    if (kind === 'scAddressTypeAccount') {
+        return decodePublicKeyToStrkey(scAddr.accountId());
+    }
+    if (kind === 'scAddressTypeContract') {
+        const hashBytes = scAddr.contractId();
+        return stellar_sdk_1.Address.contract(Buffer.from(hashBytes)).toString();
+    }
+    return null;
+}
+/** Decode an ScAddress to a C... contract strkey. */
+function decodeScAddressToC(scAddr) {
+    if (scAddr.switch().name === 'scAddressTypeContract') {
+        const hashBytes = scAddr.contractId();
+        return stellar_sdk_1.Address.contract(Buffer.from(hashBytes)).toString();
+    }
+    if (scAddr.switch().name === 'scAddressTypeAccount') {
+        const strkey = decodePublicKeyToStrkey(scAddr.accountId());
+        if (strkey)
+            return strkey;
+    }
+    throw new DecodeError(`cannot convert ScAddress ${scAddr.switch().name} to contract strkey`);
+}
+/** Decode a tx source account (MuxedEd25519Account OR AccountId OR PublicKey).
+ *  - muxedAccount -> underlying ed25519 account as G...
+ *  - publicKeyTypeEd25519 -> G...
+ */
+function decodeMuxedOrEd25519(src) {
+    const kind = src.switch().name;
+    if (kind === 'keyTypeMuxedEd25519') {
+        const ed = src.med25519().ed25519();
+        return stellar_sdk_1.StrKey.encodeEd25519PublicKey(ed);
+    }
+    const ed = src.ed25519();
+    return stellar_sdk_1.StrKey.encodeEd25519PublicKey(ed);
+}
+/** AccountId is a type alias for PublicKey in this SDK; extract the ed25519
+ *  strkey from a PublicKey union. */
+function decodePublicKeyToStrkey(pubKey) {
+    if (pubKey.switch().name === 'publicKeyTypeEd25519') {
+        return stellar_sdk_1.StrKey.encodeEd25519PublicKey(pubKey.ed25519());
+    }
+    return null;
+}
+/** `functionName()` returns `string | Buffer` per the SDK type definition; we
+ *  accept both and normalise. */
+function symbolValueFromBufferOrString(s) {
+    return Buffer.isBuffer(s) ? s.toString('utf8') : s;
+}
+/** Map an arbitrary ScVal into the normalised `ScVal` subset defined in
+ *  types.ts. Anything outside the subset is wrapped as `{type:'other', value}`
+ *  AND recorded in `opaqueScVals` so the freshness module can reduce
+ *  parseConfidence. Recursion is bounded by `MAX_SCVAL_DEPTH` so a
+ *  hand-crafted nested-vec payload cannot RangeError the JS stack; the
+ *  over-depth branch is collapsed to a single opaque `depth-exceeded` token
+ *  (the recorder's parseConfidence gate then fails the recording closed). */
+function scValToSubset(val, path, opaqueScVals, depth = 0) {
+    const kind = val.switch().name;
+    switch (kind) {
+        case 'scvAddress': {
+            const strkey = decodeScAddressToAnyStrkey(val.address());
+            if (strkey === null) {
+                opaqueScVals.push({ path, type: kind });
+                return { type: 'other', value: kind };
+            }
+            return { type: 'address', value: strkey };
+        }
+        case 'scvI128': {
+            const parts = val.i128();
+            return { type: 'i128', value: i128PartsToBigInt(parts).toString() };
+        }
+        case 'scvU64': {
+            return { type: 'u64', value: u64PartsToBigInt(val.u64()).toString() };
+        }
+        case 'scvU32': {
+            return { type: 'u32', value: val.u32().toString() };
+        }
+        case 'scvSymbol': {
+            return { type: 'symbol', value: val.sym().toString() };
+        }
+        case 'scvVec': {
+            if (depth >= types_ts_1.MAX_SCVAL_DEPTH) {
+                // Over-depth branch: collapse to a single opaque terminal so the
+                // downstream parseConfidence gate sees the fail-closed freshness hit.
+                opaqueScVals.push({ path, type: 'depth-exceeded' });
+                return { type: 'other', value: 'depth-exceeded' };
+            }
+            const arr = (val.vec() ?? []);
+            return {
+                type: 'vec',
+                value: arr.map((v, i) => scValToSubset(v, `${path}[${i}]`, opaqueScVals, depth + 1)),
+            };
+        }
+        case 'scvMap': {
+            if (depth >= types_ts_1.MAX_SCVAL_DEPTH) {
+                opaqueScVals.push({ path, type: 'depth-exceeded' });
+                return { type: 'other', value: 'depth-exceeded' };
+            }
+            // Map<Symbol, ScVal> is the canonical data shape for SAC/SEP-41
+            // transfer/mint/burn events on Stellar mainnet (verified empirically
+            // against txs 112d2392..., eb39f493..., 50d36f5c...). The entry key is
+            // carried forward so readAmount can route to the conventional field
+            // name without re-decoding the full XDR. Non-symbol / non-string keys
+            // are stringified via the same key-to-string rule used for topics.
+            const entries = (val.map() ?? []);
+            return {
+                type: 'map',
+                value: entries.map((entry, i) => ({
+                    key: mapKeyToString(entry.key(), `${path}.key[${i}]`, opaqueScVals),
+                    val: scValToSubset(entry.val(), `${path}.val[${i}]`, opaqueScVals, depth + 1),
+                })),
+            };
+        }
+        case 'scvBytes': {
+            return { type: 'bytes', value: Buffer.from(val.bytes()).toString('hex') };
+        }
+        default: {
+            opaqueScVals.push({ path, type: kind });
+            return { type: 'other', value: kind };
+        }
+    }
+}
+/** Convert Int128Parts (hi: Int64, lo: Uint64) to a BigInt.
+ *  hi is a signed 64-bit value; lo is unsigned. We use the SDK-provided
+ *  `toString()` form which gives the signed decimal representation of the 64-bit
+ *  Int64 directly. */
+function i128PartsToBigInt(parts) {
+    const hiStr = parts.hi().toString();
+    const loStr = parts.lo().toString();
+    const hi = BigInt(hiStr);
+    const lo = BigInt(loStr);
+    return (hi << 64n) + lo;
+}
+/** Convert UInt128Parts (hi: Uint64, lo: Uint64) to an unsigned BigInt. */
+function u128PartsToBigInt(parts) {
+    const hi = BigInt(parts.hi().toString());
+    const lo = BigInt(parts.lo().toString());
+    return (hi << 64n) + lo;
+}
+function u64PartsToBigInt(h) {
+    return BigInt(h.toString());
+}
+function recordInvocation(contract, fn, args, network, knownSet, knownContractSet, knownOut, unknownOut) {
+    // Recognition is evaluated PER INVOCATION using the (contract, fn, args)
+    // triple. The first call to a contract is no more authoritative than the
+    // second: an unrecognized call always contributes to the unknown count
+    // regardless of whether another invocation to the same contract was
+    // recognised. knownOut is deduplicated by contract (so the
+    // parseConfidence denominator isn't inflated by repeat calls), but each
+    // unrecognised invocation is recorded separately so the numerator
+    // reflects every fail-closed hit.
+    if (knownSet.has(contract)) {
+        if (!knownContractSet.has(contract)) {
+            knownContractSet.add(contract);
+            knownOut.push(contract);
+        }
+        return;
+    }
+    if ((0, identify_ts_1.identifyProtocol)(contract, fn, args, network ?? undefined)) {
+        if (!knownContractSet.has(contract)) {
+            knownContractSet.add(contract);
+            knownOut.push(contract);
+        }
+        return;
+    }
+    unknownOut.push({ contract, reason: 'no-abi' });
+}
+/** Convert a ScVal to a friendly string for use in OnChainEvent.topics
+ *  (always-string scalar representation; vectors/bytes are stringified as JSON
+ *  to keep the field string-typed). */
+function scValToTopicString(val) {
+    const kind = val.switch().name;
+    if (kind === 'scvSymbol')
+        return val.sym().toString();
+    if (kind === 'scvString')
+        return val.str().toString();
+    if (kind === 'scvAddress') {
+        const strkey = decodeScAddressToAnyStrkey(val.address());
+        return strkey ?? `<unparsed-address:${kind}>`;
+    }
+    if (kind === 'scvU64')
+        return u64PartsToBigInt(val.u64()).toString();
+    if (kind === 'scvU32')
+        return val.u32().toString();
+    if (kind === 'scvI128')
+        return i128PartsToBigInt(val.i128()).toString();
+    if (kind === 'scvBytes')
+        return Buffer.from(val.bytes()).toString('hex');
+    return `<${kind}>`;
+}
+/** Convert a Map<Symbol, ...> key ScVal to the string used in the normalised
+ *  ScVal map representation. Uses the same string-form rule as
+ *  `scValToTopicString` so SAC/SEP-41 event Map keys ("amount", "to_muxed_id")
+ *  resolve to the same string in both the topic path and the map-entry path.
+ *  Non-symbol / non-string keys record an opaque diagnostic and return a
+ *  placeholder so the Map entry is still carried forward. */
+function mapKeyToString(val, path, opaqueScVals) {
+    const kind = val.switch().name;
+    if (kind === 'scvSymbol')
+        return val.sym().toString();
+    if (kind === 'scvString')
+        return val.str().toString();
+    if (kind === 'scvU64')
+        return u64PartsToBigInt(val.u64()).toString();
+    if (kind === 'scvU32')
+        return val.u32().toString();
+    if (kind === 'scvI128')
+        return i128PartsToBigInt(val.i128()).toString();
+    if (kind === 'scvBytes')
+        return Buffer.from(val.bytes()).toString('hex');
+    opaqueScVals.push({ path, type: `unsupported-map-key:${kind}` });
+    return `<${kind}>`;
+}
+/** Build the OnChainEvent[] view from raw contract events. Diagnostic-only:
+ *  captures the topics + data + emitter contract for the downstream
+ *  validator. */
+function contractEventsToOnChainEvents(contractEvents) {
+    const out = [];
+    for (const group of contractEvents) {
+        for (const evt of group) {
+            const body = evt.body().v0();
+            const emitter = evt.contractId()
+                ? stellar_sdk_1.Address.contract(Buffer.from(evt.contractId())).toString()
+                : '';
+            const topics = body.topics().map((t) => scValToTopicString(t));
+            const data = scValToSubset(body.data(), 'event.data', []);
+            out.push({ contract: emitter, topics, data });
+        }
+    }
+    return out;
+}
+/** Build the OnChainEvent[] view from TransactionEvent[] (which wraps
+ *  ContractEvent with a stage). Same shape as above. */
+function transactionEventsToOnChainEvents(txEvents) {
+    const contractEvents = txEvents.map((e) => [e.event()]);
+    return contractEventsToOnChainEvents(contractEvents);
+}
+/** Tiny typed error so callers can `instanceof DecodeError` without leaking
+ *  SDK internals. */
+class DecodeError extends Error {
+    name = 'DecodeError';
+}
+exports.DecodeError = DecodeError;
+/** Helper used by validate.ts to map a TokenMovement back to a search key
+ *  without re-parsing (the validate module must cross-check against the raw
+ *  events, NOT against the parse). */
+function tokenMovementKey(m) {
+    return `${m.token}|${m.from}|${m.to}|${m.amount}`;
+}

package/dist-cjs/record/freshness.d.ts

@@ -0,0 +1,30 @@
+import type { ParseConfidence } from '../types.ts';
+/** Inputs to the freshness computation. The decode module produces the raw
+ *  counters; this module applies the rule. */
+export interface FreshnessInput {
+    knownContracts: string[];
+    unknownContracts: ParseConfidence['unknownContracts'];
+    opaqueScVals: ParseConfidence['opaqueScVals'];
+}
+/** Compute parseConfidence per the pinned rule. Pure: no IO. */
+export declare function computeParseConfidence(input: FreshnessInput): ParseConfidence;
+/** Refuse-on-low-confidence gate. Returns true when the recording must be
+ *  refused (overall < thresholdUsed). The orchestrator wraps this in a
+ *  ToolError with the ParseConfidence payload attached as `details`. */
+export declare function isBelowThreshold(c: ParseConfidence): boolean;
+/** Convenience: build the user-facing remediation question for an
+ *  under-confidence recording.
+ *
+ *  The remediation text branches on which diagnostic bucket is non-empty:
+ *    - unknownContracts only -> user MUST supply an ABI (or re-capture
+ *      against a known protocol version). The contract is real, the
+ *      recorder just cannot decode it.
+ *    - opaqueScVals only -> the recorder encountered a value shape it
+ *      should support but did not decode. The user cannot supply an ABI
+ *      to fix a decoder bug; the guidance explicitly says so and points at
+ *      re-running after a tool upgrade / reporting the path.
+ *    - both -> list both diagnostics AND chain the right remediation for
+ *      each (the user supplies an ABI AND reports the decoder gap).
+ *    - neither (the "denom === 0" path) -> unchanged from the pre-fix
+ *      text; the user did not actually hit a code-level barrier. */
+export declare function buildLowConfidenceQuestion(c: ParseConfidence): string;

package/dist-cjs/record/freshness.js

@@ -0,0 +1,85 @@
+"use strict";
+// src/record/freshness.ts - compute parseConfidence for a DecodedTransaction.
+//
+// The pinned rule (see ParseConfidence in src/types.ts):
+//   overall = 1 - (unknownContracts + opaqueScVals) / total
+// where total = unique contracts referenced + opaque ScVal count.
+// In v1 every contract is "unknown" by default (no adjacency ABI hint is
+// bundled with the recorder); the freshness module still computes the value
+// honestly so callers can see why the gate fires.
+//
+// thresholdUsed defaults to 1.0 - a stricter gate. Callers can opt to lower
+// it via confidence_override but v1 ships only the default.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeParseConfidence = computeParseConfidence;
+exports.isBelowThreshold = isBelowThreshold;
+exports.buildLowConfidenceQuestion = buildLowConfidenceQuestion;
+/** Compute parseConfidence per the pinned rule. Pure: no IO. */
+function computeParseConfidence(input) {
+    const unknown = input.unknownContracts.length;
+    const opaque = input.opaqueScVals.length;
+    const known = input.knownContracts.length;
+    // Pinned rule: overall = 1 - (unknown + opaque) / (known + unknown + opaque).
+    // Only the empty-decode case (nothing referenced) is guarded to avoid 0/0; it
+    // means "nothing to decode", so full confidence. A fully-unknown tx therefore
+    // scores 0, not an inflated value.
+    const denom = known + unknown + opaque;
+    const total = denom === 0 ? 1 : denom;
+    const overall = Math.max(0, Math.min(1, 1 - (unknown + opaque) / total));
+    return {
+        overall,
+        knownContracts: [...input.knownContracts],
+        unknownContracts: [...input.unknownContracts],
+        opaqueScVals: [...input.opaqueScVals],
+        thresholdUsed: 1.0,
+    };
+}
+/** Refuse-on-low-confidence gate. Returns true when the recording must be
+ *  refused (overall < thresholdUsed). The orchestrator wraps this in a
+ *  ToolError with the ParseConfidence payload attached as `details`. */
+function isBelowThreshold(c) {
+    return c.overall < c.thresholdUsed;
+}
+/** Convenience: build the user-facing remediation question for an
+ *  under-confidence recording.
+ *
+ *  The remediation text branches on which diagnostic bucket is non-empty:
+ *    - unknownContracts only -> user MUST supply an ABI (or re-capture
+ *      against a known protocol version). The contract is real, the
+ *      recorder just cannot decode it.
+ *    - opaqueScVals only -> the recorder encountered a value shape it
+ *      should support but did not decode. The user cannot supply an ABI
+ *      to fix a decoder bug; the guidance explicitly says so and points at
+ *      re-running after a tool upgrade / reporting the path.
+ *    - both -> list both diagnostics AND chain the right remediation for
+ *      each (the user supplies an ABI AND reports the decoder gap).
+ *    - neither (the "denom === 0" path) -> unchanged from the pre-fix
+ *      text; the user did not actually hit a code-level barrier. */
+function buildLowConfidenceQuestion(c) {
+    const hasUnknown = c.unknownContracts.length > 0;
+    const hasOpaque = c.opaqueScVals.length > 0;
+    const reasons = [];
+    for (const u of c.unknownContracts) {
+        reasons.push(`unknown contract ${u.contract} (${u.reason})`);
+    }
+    for (const o of c.opaqueScVals) {
+        reasons.push(`opaque ScVal at ${o.path} (${o.type})`);
+    }
+    const why = reasons.length === 0 ? 'no diagnostic reason available' : reasons.join('; ');
+    const header = `Recording refused: parseConfidence ${c.overall.toFixed(3)} is below the threshold ${c.thresholdUsed.toFixed(3)}. Diagnostic: ${why}.`;
+    // The two remediation branches are explicit so the user (or the agent)
+    // can dispatch on the verb. The "unknown contract" branch is the only
+    // one that asks for an ABI; the "opaque ScVal" branch asks the user to
+    // report the path and re-run after a tool upgrade.
+    if (hasUnknown && hasOpaque) {
+        return (`${header} Supply an ABI for the unknown contract(s) or re-capture the transaction against a known protocol version; ` +
+            `also file the opaque ScVal path against the recorder (decoder limitation) and re-run record_transaction after a tool upgrade.`);
+    }
+    if (hasUnknown) {
+        return `${header} Supply an ABI for the unknown contract(s) or re-capture the transaction against a known protocol version, then re-run record_transaction.`;
+    }
+    if (hasOpaque) {
+        return `${header} This is a recorder decoder limitation (the value shape is supported in principle but not yet decoded) - the agent cannot fix it by supplying an ABI. Report the opaque ScVal path above against the recorder and re-run record_transaction after a tool upgrade.`;
+    }
+    return `${header} No actionable diagnostic was recorded; re-run record_transaction against a fresh fetch and inspect the events.`;
+}

package/dist-cjs/record/index.d.ts

@@ -0,0 +1,32 @@
+import type { ToolResponse } from '../errors.ts';
+import type { Network, RecordedTransaction } from '../types.ts';
+import { type RpcFetcher } from './rpc.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 `crossNetworkFetcher` (item 2) for tests + offline use;
+ *      production builds the cross-network probe from `createRpcServer` when
+ *      this field is absent
+ *    - 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;
+    /** Test-only seam + explicit production override for the cross-network
+     *  probe (item 2). When the primary fetcher returns null on hash mode,
+     *  the recorder also tries this fetcher against the OTHER network. If it
+     *  finds the hash there, the recorder returns a specific actionable
+     *  error mentioning the actual network. When unset, the recorder builds
+     *  this fetcher from `createRpcServer(otherNetwork)` so the help fires
+     *  automatically; tests can pass a deterministic stub. */
+    crossNetworkFetcher?: RpcFetcher;
+    confidenceOverride?: number;
+}
+export type RecordResult = ToolResponse<RecordedTransaction>;
+export declare function recordTransaction(input: RecordInput): Promise<RecordResult>;