@crediolabs/policy-synth 0.1.4 → 0.1.5

package/dist-cjs/record/decode.js

@@ -0,0 +1,398 @@
+"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 '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}>`;
+}
+/** 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,17 @@
+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. */
+export declare function buildLowConfidenceQuestion(c: ParseConfidence): string;

package/dist-cjs/record/freshness.js

@@ -0,0 +1,55 @@
+"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. */
+function buildLowConfidenceQuestion(c) {
+    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('; ');
+    return `Recording refused: parseConfidence ${c.overall.toFixed(3)} is below the threshold ${c.thresholdUsed.toFixed(3)}. Diagnostic: ${why}. Supply an ABI for the unknown contract(s) or re-capture the transaction against a known protocol version, then re-run record_transaction.`;
+}

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

@@ -0,0 +1,21 @@
+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 `confidenceOverride` to relax the gate (default 1.0)
+ *
+ *  In xdr mode `network` is still required so the caller documents intent
+ *  (the synthesis downstream consumes it).
+ */
+export interface RecordInput {
+    hash?: string;
+    xdr?: string;
+    network: Network;
+    fetcher?: RpcFetcher;
+    confidenceOverride?: number;
+}
+export type RecordResult = ToolResponse<RecordedTransaction>;
+export declare function recordTransaction(input: RecordInput): Promise<RecordResult>;

package/dist-cjs/record/index.js

@@ -0,0 +1,166 @@
+"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) {
+            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,
+    });
+    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,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;