@crediolabs/policy-synth 0.1.3 → 0.1.5

package/dist-cjs/errors.js

@@ -0,0 +1,3 @@
+"use strict";
+// src/errors.ts
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist-cjs/index.d.ts

@@ -0,0 +1,11 @@
+export * from './adapters/oz/index.ts';
+export * from './errors.ts';
+export * from './ir/index.ts';
+export * from './mandate/index.ts';
+export * from './predicate/index.ts';
+export * from './record/index.ts';
+export * from './registry/index.ts';
+export * from './review-card/index.ts';
+export * from './seams/index.ts';
+export * from './synth/index.ts';
+export * from './types.ts';

package/dist-cjs/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./adapters/oz/index.js"), exports);
+__exportStar(require("./errors.js"), exports);
+__exportStar(require("./ir/index.js"), exports);
+__exportStar(require("./mandate/index.js"), exports);
+__exportStar(require("./predicate/index.js"), exports);
+__exportStar(require("./record/index.js"), exports);
+__exportStar(require("./registry/index.js"), exports);
+__exportStar(require("./review-card/index.js"), exports);
+__exportStar(require("./seams/index.js"), exports);
+__exportStar(require("./synth/index.js"), exports);
+__exportStar(require("./types.js"), exports);

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

@@ -0,0 +1 @@
+export type { IRCompare, IRCompOp, IRCondition, IRLogic, IRPolicyRule, IRScalarType, IRSelector, IRVecMode, PolicyIR, } from './types.ts';

package/dist-cjs/ir/index.js

@@ -0,0 +1,3 @@
+"use strict";
+// src/ir/index.ts - re-export the PolicyIR ("Policy Tree") types.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist-cjs/ir/types.d.ts

@@ -0,0 +1,108 @@
+/** Comparison operator. Mirrors NEAR-V2 `CompOp`. */
+export type IRCompOp = 'eq' | 'lt' | 'lte' | 'gt' | 'gte';
+/** Boolean combinator. Mirrors NEAR-V2 `LogicOp`. */
+export type IRLogic = 'and' | 'or';
+/** Vector match mode for a repeated arg. Mirrors NEAR-V2 `VecMode`. */
+export type IRVecMode = 'all' | 'any';
+/** Scalar value type. Mirrors NEAR-V2 `ScValType`, superset for OZ. */
+export type IRScalarType = 'address' | 'i128' | 'u128' | 'u32' | 'u64' | 'i64' | 'symbol' | 'bytes' | 'bool';
+/** WHERE in the authorized call a value is read. NEAR-V2 selectors first, OZ
+ *  extensions after (an adapter that cannot express an extension flags it). */
+export type IRSelector = {
+    kind: 'arg';
+    argIndex: number;
+    fieldIndex?: number;
+    vecMode?: IRVecMode;
+    scalarType: IRScalarType;
+} | {
+    kind: 'calldata';
+    offset: number;
+    length: number;
+} | {
+    kind: 'value';
+} | {
+    kind: 'amount';
+    token: string;
+} | {
+    kind: 'window_spent';
+    token: string;
+    windowSeconds: number;
+} | {
+    kind: 'invocation_count';
+    windowSeconds: number;
+} | {
+    kind: 'now';
+} | {
+    kind: 'valid_until';
+} | {
+    kind: 'oracle_price';
+    asset: string;
+};
+/** A single comparison leaf. `value` is a decimal/hex string (i128-safe;
+ *  never a JS number). */
+export interface IRCompare {
+    selector: IRSelector;
+    operator: IRCompOp;
+    value: string;
+}
+/** Condition tree. NEAR-V2 guard/constraint are flat And/Or; the IR allows
+ *  nesting + `not` + `in` + `eq_seq` so the same IR can later lower to the OZ
+ *  predicate DSL. Week-1 adapters only lower the flat supported subset and flag
+ *  the rest. */
+export type IRCondition = {
+    op: 'and' | 'or';
+    children: IRCondition[];
+} | {
+    op: 'not';
+    child: IRCondition;
+} | {
+    op: 'compare';
+    compare: IRCompare;
+} | {
+    op: 'in';
+    selector: IRSelector;
+    values: string[];
+}
+/** Exact ordered sequence equality. The IR-level selector value MUST EQUAL
+ *  `values` as an ORDERED sequence (e.g. a swap hop `path`). `in` is pure
+ *  set membership and cannot express order; `eq_seq` is the construct that
+ *  does. Adapters that cannot express an exact ordered vector (OZ built-ins)
+ *  flag this as `uncovered` rather than silently dropping it. */
+ | {
+    op: 'eq_seq';
+    selector: IRSelector;
+    values: string[];
+};
+export interface IRPolicyRule {
+    /** NEAR-V2 roles whitelist (empty = any; owner exempt). */
+    roles: string[];
+    /** NEAR-V2 scope filter; each field optional (absent = wildcard). */
+    scope: {
+        chainId?: number;
+        contract?: string;
+        method?: string;
+    };
+    /** NEAR-V2 guard (applicability; skip the rule when it fails). */
+    guard?: IRCondition;
+    /** NEAR-V2 constraint (AND; reject the transaction when any fails). */
+    constraints: IRCondition[];
+    /** M-of-N approval (OZ threshold primitives). */
+    approval?: {
+        kind: 'threshold';
+        threshold: number;
+        weights?: Record<string, number>;
+    };
+    /** OZ context-rule expiry. */
+    expiry?: {
+        validUntilLedger?: number;
+        validUntilUnixSeconds?: number;
+    };
+}
+export interface PolicyIR {
+    /** NEAR-V2 PolicyChain. */
+    chain: 'stellar' | 'evm';
+    /** NEAR-V2 DefaultBehavior. OZ context rules are deny-by-default, so
+     *  `deny_all` is the OZ default fallback when no rule matches. */
+    defaultBehavior: 'allow_all' | 'deny_all';
+    rules: IRPolicyRule[];
+}

package/dist-cjs/ir/types.js

@@ -0,0 +1,12 @@
+"use strict";
+// src/ir/types.ts - the PolicyIR ("Policy Tree").
+//
+// `PolicyIR` is the custody-agnostic "Policy Tree" hub (the diagram's Policy
+// Tree) that every CustodyAdapter compiles FROM. It generalizes the NEAR-V2
+// policy schema (roles / scope filter / guard / constraint / comparison leaves /
+// default behaviour) into one chain-neutral shape and extends it with the
+// OZ-only selectors (spend window, oracle price, invocation count, time) so a
+// single IR can serve every backend. NEAR-V2 has no stateful spend window,
+// oracle, time/expiry, or invocation-count; those are marked as OZ extensions
+// below and are only lowered by adapters that declare support for them.
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,2 @@
+export { mandateToPolicyIR } from './to-ir.ts';
+export type { MandateSpec } from './types.ts';

package/dist-cjs/mandate/index.js

@@ -0,0 +1,6 @@
+"use strict";
+// src/mandate/index.ts - re-export the Mandate source.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mandateToPolicyIR = void 0;
+var to_ir_ts_1 = require("./to-ir.js");
+Object.defineProperty(exports, "mandateToPolicyIR", { enumerable: true, get: function () { return to_ir_ts_1.mandateToPolicyIR; } });

package/dist-cjs/mandate/to-ir.d.ts

@@ -0,0 +1,3 @@
+import type { PolicyIR } from '../ir/types.ts';
+import type { MandateSpec } from './types.ts';
+export declare function mandateToPolicyIR(spec: MandateSpec): PolicyIR;

package/dist-cjs/mandate/to-ir.js

@@ -0,0 +1,63 @@
+"use strict";
+// src/mandate/to-ir.ts - deterministic lowering of a MandateSpec to a PolicyIR.
+//
+// `mandateToPolicyIR` is pure and total: the same spec always lowers to a
+// byte-identical PolicyIR. No decoding, no inference, no clock. Each mandate
+// field maps to exactly one IR construct:
+//   contract/method  -> rule.scope
+//   spendingLimit    -> a `window_spent(token,window) <= limit` compare
+//   approvalThreshold-> rule.approval.threshold
+//   recipients       -> an `in` condition on the recipient arg (flagged as not
+//                       covered by the OZ adapter; that is expected)
+//   expiry           -> rule.expiry
+// The top-level default is `deny_all` (OZ context rules are deny-by-default).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mandateToPolicyIR = mandateToPolicyIR;
+/** Arg index the recipient allowlist constrains. Pinned to the SEP-41
+ *  `transfer(from, to, amount)` convention where `to` is arg 1. This condition
+ *  is flagged as not covered by the OZ adapter (no built-in primitive expresses
+ *  an arg allowlist), so the index only needs to be deterministic in week-1. */
+const RECIPIENT_ARG_INDEX = 1;
+function mandateToPolicyIR(spec) {
+    const scope = { contract: spec.contract };
+    if (spec.method !== undefined)
+        scope.method = spec.method;
+    const constraints = [];
+    if (spec.spendingLimit) {
+        constraints.push({
+            op: 'compare',
+            compare: {
+                selector: {
+                    kind: 'window_spent',
+                    token: spec.spendingLimit.token,
+                    windowSeconds: spec.spendingLimit.windowSeconds,
+                },
+                operator: 'lte',
+                value: spec.spendingLimit.limit,
+            },
+        });
+    }
+    if (spec.recipients && spec.recipients.length > 0) {
+        const selector = {
+            kind: 'arg',
+            argIndex: RECIPIENT_ARG_INDEX,
+            scalarType: 'address',
+        };
+        constraints.push({ op: 'in', selector, values: [...spec.recipients] });
+    }
+    const rule = { roles: [], scope, constraints };
+    if (spec.approvalThreshold !== undefined) {
+        rule.approval = { kind: 'threshold', threshold: spec.approvalThreshold };
+    }
+    if (spec.expiry) {
+        const expiry = {};
+        if (spec.expiry.validUntilLedger !== undefined) {
+            expiry.validUntilLedger = spec.expiry.validUntilLedger;
+        }
+        if (spec.expiry.validUntilUnixSeconds !== undefined) {
+            expiry.validUntilUnixSeconds = spec.expiry.validUntilUnixSeconds;
+        }
+        rule.expiry = expiry;
+    }
+    return { chain: spec.chain, defaultBehavior: 'deny_all', rules: [rule] };
+}

package/dist-cjs/mandate/types.d.ts

@@ -0,0 +1,20 @@
+export interface MandateSpec {
+    chain: 'stellar';
+    contract: string;
+    method?: string;
+    /** -> OZ `spending_limit` primitive. `limit` is an i128 decimal string. */
+    spendingLimit?: {
+        token: string;
+        limit: string;
+        windowSeconds: number;
+    };
+    /** -> OZ `simple_threshold` / `weighted_threshold` primitive. */
+    approvalThreshold?: number;
+    /** Recipient allowlist -> an `in` arg condition (not covered by an OZ built-in). */
+    recipients?: string[];
+    /** -> OZ context-rule expiry. */
+    expiry?: {
+        validUntilLedger?: number;
+        validUntilUnixSeconds?: number;
+    };
+}

package/dist-cjs/mandate/types.js

@@ -0,0 +1,9 @@
+"use strict";
+// src/mandate/types.ts - the deterministic Mandate source.
+//
+// A MandateSpec is a declarative policy statement: "this account may call this
+// contract, spending at most L per window, requiring M approvals, to these
+// recipients, until this expiry". It carries NO transaction to decode, NO
+// parseConfidence, and NO inference - it lowers deterministically to a
+// PolicyIR. It is the clean end-to-end demo path, co-equal with the recorder.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist-cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist-cjs/predicate/encode.d.ts

@@ -0,0 +1,10 @@
+import { type PredicateNode } from '../types.ts';
+export interface EncodedPredicate {
+    /** base64 of the canonical ScVal XDR of the predicate root. */
+    encodedPredicate: string;
+    /** sha256 hex digest of the raw XDR bytes (post-canonicalisation). */
+    predicateHash: string;
+}
+/** Encode a `PredicateNode` to the canonical ScVal wire format and hash it.
+ *  Pure function: same input -> byte-identical output every run. */
+export declare function encodePredicate(node: PredicateNode): EncodedPredicate;

package/dist-cjs/predicate/encode.js

@@ -0,0 +1,252 @@
+"use strict";
+// src/predicate/encode.ts - canonical predicate encoder.
+//
+// Pure function. Maps a `PredicateNode` AST to the canonical ScVal wire format
+// described in `packages/policy-interpreter/INTERPRETER_INSTALL_PARAMS.md`:
+//   - every node is a `ScVal::Vec` whose head element is the tag `ScVal::Symbol`
+//   - children of `and` / `or` are sorted ascending by their canonical XDR bytes
+//   - `in` haystacks are ALWAYS sorted by canonical XDR bytes (pure set
+//     membership); an EXACT ordered sequence is expressed as
+//     `eq(selector, literal_vec)` where the `literal_vec` element order is
+//     preserved verbatim (the order IS the semantic)
+//   - `literal_vec` encodes to a bare `ScVal::Vec` of its element encodings;
+//     order is preserved, NOT sorted
+//   - i128 uses `Int128Parts{hi: Int64 (signed), lo: Uint64 (unsigned)}`,
+//     value = hi*2^64 + lo (NOT signed-magnitude)
+//   - no `ScMap` anywhere in the predicate
+//   - `encodedPredicate = base64(root.toXDR())`,
+//     `predicateHash = sha256(raw XDR bytes)` as hex
+//
+// Caps from `PREDICATE_CAPS` are enforced BEFORE returning; a cap breach throws
+// a `ToolError` with the matching error code and `severity: 'error'`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodePredicate = encodePredicate;
+const node_crypto_1 = require("node:crypto");
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const types_ts_1 = require("../types.js");
+const INT64_MAX = (1n << 63n) - 1n;
+const INT64_MIN = -(1n << 63n);
+const UINT64_MAX = (1n << 64n) - 1n;
+/** Encode a `PredicateNode` to the canonical ScVal wire format and hash it.
+ *  Pure function: same input -> byte-identical output every run. */
+function encodePredicate(node) {
+    // --- pass 1: structural cap checks (no encoding needed) ---
+    const stats = computeStats(node);
+    if (stats.depth > types_ts_1.PREDICATE_CAPS.MAX_DEPTH) {
+        throw capError('PREDICATE_TOO_DEEP', `predicate depth ${stats.depth} exceeds MAX_DEPTH ${types_ts_1.PREDICATE_CAPS.MAX_DEPTH}`);
+    }
+    if (stats.leaves > types_ts_1.PREDICATE_CAPS.MAX_LEAVES) {
+        throw capError('TOO_MANY_LEAVES', `predicate leaf count ${stats.leaves} exceeds MAX_LEAVES ${types_ts_1.PREDICATE_CAPS.MAX_LEAVES}`);
+    }
+    for (const c of stats.inCounts) {
+        if (c.count > types_ts_1.PREDICATE_CAPS.MAX_IN_OPERAND_COUNT) {
+            throw capError('IN_OPERAND_LIMIT', `\`in\` operand count ${c.count} exceeds MAX_IN_OPERAND_COUNT ${types_ts_1.PREDICATE_CAPS.MAX_IN_OPERAND_COUNT}`);
+        }
+    }
+    // Two-round confirmation costs 2 oracle reads per UNIQUE asset referenced.
+    const oracleReads = stats.oracleAssets.size * 2;
+    if (oracleReads > types_ts_1.PREDICATE_CAPS.MAX_ORACLE_READS) {
+        throw capError('PREDICATE_ORACLE_OVER_LIMIT', `oracle reads ${oracleReads} exceed MAX_ORACLE_READS ${types_ts_1.PREDICATE_CAPS.MAX_ORACLE_READS}`);
+    }
+    // --- pass 2: build + canonicalise the ScVal ---
+    const root = encodeNode(node);
+    const rawBytes = root.toXDR();
+    if (rawBytes.length > types_ts_1.PREDICATE_CAPS.MAX_PREDICATE_BYTES) {
+        throw capError('PREDICATE_TOO_LARGE', `predicate bytes ${rawBytes.length} exceed MAX_PREDICATE_BYTES ${types_ts_1.PREDICATE_CAPS.MAX_PREDICATE_BYTES}`);
+    }
+    const encodedPredicate = rawBytes.toString('base64');
+    const predicateHash = (0, node_crypto_1.createHash)('sha256').update(rawBytes).digest('hex');
+    return { encodedPredicate, predicateHash };
+}
+function computeStats(node) {
+    const inCounts = [];
+    const oracleAssets = new Set();
+    const { depth, leaves } = walk(node, inCounts, oracleAssets);
+    return { depth, leaves, inCounts, oracleAssets };
+}
+function walk(node, inCounts, oracleAssets) {
+    switch (node.op) {
+        case 'and':
+        case 'or': {
+            if (node.children.length === 0)
+                return { depth: 1, leaves: 0 };
+            let maxChildDepth = 0;
+            let totalLeaves = 0;
+            for (const c of node.children) {
+                const child = walk(c, inCounts, oracleAssets);
+                if (child.depth > maxChildDepth)
+                    maxChildDepth = child.depth;
+                totalLeaves += child.leaves;
+            }
+            return { depth: maxChildDepth + 1, leaves: totalLeaves };
+        }
+        case 'not': {
+            const child = walk(node.child, inCounts, oracleAssets);
+            return { depth: child.depth + 1, leaves: child.leaves };
+        }
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte': {
+            collectOracle(node.left, oracleAssets);
+            collectOracle(node.right, oracleAssets);
+            return { depth: 1, leaves: leafCount(node.left) + leafCount(node.right) };
+        }
+        case 'in': {
+            inCounts.push({ count: node.haystack.length });
+            collectOracle(node.needle, oracleAssets);
+            let haystackLeaves = 0;
+            for (const h of node.haystack) {
+                collectOracle(h, oracleAssets);
+                haystackLeaves += leafCount(h);
+            }
+            return {
+                depth: 1,
+                leaves: leafCount(node.needle) + haystackLeaves,
+            };
+        }
+    }
+}
+/** Leaf-count contribution of one PredicateLeaf: 1 for any flat leaf, and the
+ *  sum of element leaf counts for `literal_vec` so MAX_LEAVES caps see nested
+ *  vector elements. */
+function leafCount(leaf) {
+    if (leaf.kind === 'literal_vec') {
+        let total = 1; // the literal_vec itself counts as one leaf node
+        for (const el of leaf.elements)
+            total += leafCount(el);
+        return total;
+    }
+    return 1;
+}
+function collectOracle(leaf, oracleAssets) {
+    // literal_vec is the only nested leaf; recurse so an oracle_price buried in a
+    // vector literal (which the lowering would forbid, but the cap-walker must
+    // still see) is counted toward the oracle-read budget.
+    if (leaf.kind === 'oracle_price') {
+        oracleAssets.add(leaf.asset);
+    }
+    else if (leaf.kind === 'literal_vec') {
+        for (const el of leaf.elements)
+            collectOracle(el, oracleAssets);
+    }
+}
+function encodeNode(node) {
+    switch (node.op) {
+        case 'and':
+        case 'or': {
+            const encoded = node.children.map(encodeNode);
+            // sort children by their canonical XDR bytes ascending.
+            const sorted = sortByCanonicalBytes(encoded);
+            return stellar_sdk_1.xdr.ScVal.scvVec([symbol(node.op), stellar_sdk_1.xdr.ScVal.scvVec(sorted)]);
+        }
+        case 'not': {
+            return stellar_sdk_1.xdr.ScVal.scvVec([symbol('not'), encodeNode(node.child)]);
+        }
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte': {
+            return stellar_sdk_1.xdr.ScVal.scvVec([symbol(node.op), encodeLeaf(node.left), encodeLeaf(node.right)]);
+        }
+        case 'in': {
+            const needle = encodeLeaf(node.needle);
+            // `in` is PURE set membership: the haystack is ALWAYS sorted by canonical
+            // XDR bytes ascending. An exact ordered sequence (e.g. a swap hop path)
+            // is expressed as `eq(selector, literal_vec)` where the vec's element
+            // order is preserved verbatim (handled in `encodeLeaf(literal_vec)`).
+            const haystack = sortByCanonicalBytes(node.haystack.map(encodeLeaf));
+            return stellar_sdk_1.xdr.ScVal.scvVec([symbol('in'), needle, stellar_sdk_1.xdr.ScVal.scvVec(haystack)]);
+        }
+    }
+}
+function encodeLeaf(leaf) {
+    switch (leaf.kind) {
+        case 'call_contract':
+            return stellar_sdk_1.xdr.ScVal.scvVec([symbol('call_contract')]);
+        case 'call_fn':
+            return stellar_sdk_1.xdr.ScVal.scvVec([symbol('call_fn')]);
+        case 'call_arg':
+            return stellar_sdk_1.xdr.ScVal.scvVec([symbol('call_arg'), stellar_sdk_1.xdr.ScVal.scvU32(leaf.index)]);
+        case 'amount':
+            return stellar_sdk_1.xdr.ScVal.scvVec([symbol('amount'), scvAddressFromStrkey(leaf.token)]);
+        case 'window_spent':
+            return stellar_sdk_1.xdr.ScVal.scvVec([
+                symbol('window_spent'),
+                scvAddressFromStrkey(leaf.token),
+                scvU64FromValue(leaf.windowSeconds),
+            ]);
+        case 'now':
+            return stellar_sdk_1.xdr.ScVal.scvVec([symbol('now')]);
+        case 'valid_until':
+            return stellar_sdk_1.xdr.ScVal.scvVec([symbol('valid_until')]);
+        case 'invocation_count_in_window':
+            return stellar_sdk_1.xdr.ScVal.scvVec([symbol('invocation_count'), scvU64FromValue(leaf.windowSecs)]);
+        case 'oracle_price':
+            return stellar_sdk_1.xdr.ScVal.scvVec([symbol('oracle_price'), scvAddressFromStrkey(leaf.asset)]);
+        case 'literal_address':
+            return scvAddressFromStrkey(leaf.value);
+        case 'literal_i128':
+            return scvI128FromDecimal(leaf.value);
+        case 'literal_symbol':
+            return stellar_sdk_1.xdr.ScVal.scvSymbol(leaf.value);
+        case 'literal_u32':
+            return stellar_sdk_1.xdr.ScVal.scvU32(leaf.value);
+        case 'literal_u64':
+            return scvU64FromValue(leaf.value);
+        case 'literal_bytes':
+            return stellar_sdk_1.xdr.ScVal.scvBytes(Buffer.from(leaf.value, 'hex'));
+        case 'literal_vec':
+            // Bare ScVal::Vec of element encodings - order is preserved verbatim
+            // because the order IS the semantic (exact ordered sequence equality).
+            return stellar_sdk_1.xdr.ScVal.scvVec(leaf.elements.map(encodeLeaf));
+    }
+}
+function symbol(s) {
+    return stellar_sdk_1.xdr.ScVal.scvSymbol(s);
+}
+function sortByCanonicalBytes(values) {
+    const pairs = values.map((v) => ({ v, bytes: v.toXDR() }));
+    pairs.sort((a, b) => Buffer.compare(a.bytes, b.bytes));
+    return pairs.map((p) => p.v);
+}
+function scvAddressFromStrkey(strkey) {
+    return stellar_sdk_1.xdr.ScVal.scvAddress(stellar_sdk_1.Address.fromString(strkey).toScAddress());
+}
+function scvU64FromValue(value) {
+    // The Uint64 (UnsignedHyper) constructor accepts string | bigint | number;
+    // string is safest for values > 2^53.
+    return stellar_sdk_1.xdr.ScVal.scvU64(new stellar_sdk_1.xdr.Uint64(String(value)));
+}
+/** Build `ScVal::I128(Int128Parts{hi, lo})` from a signed decimal string.
+ *  `Int128Parts` encodes the value as `(hi << 64) + lo` with `hi` a SIGNED
+ *  64-bit int and `lo` an UNSIGNED 64-bit int (this is NOT signed-magnitude).
+ *  The inverse split is `hi = v >> 64n` (arithmetic right shift) and
+ *  `lo = v & 0xFFFF...`. The SDK's `Int64` constructor takes a signed
+ *  bigint/string/number. */
+function scvI128FromDecimal(decimal) {
+    const v = BigInt(decimal);
+    const hi = v >> 64n;
+    const lo = v & UINT64_MAX;
+    // Guard against accidental over-range. Int128Parts.hi must be a valid Int64
+    // (-2^63 .. 2^63-1); values outside this range are invalid i128 entirely.
+    if (hi < INT64_MIN || hi > INT64_MAX) {
+        throw capError('MALFORMED_PREDICATE', `literal_i128 value ${decimal} is outside the Int128 range`);
+    }
+    if (lo < 0n || lo > UINT64_MAX) {
+        throw capError('MALFORMED_PREDICATE', `literal_i128 value ${decimal} has an invalid Int128Parts.lo`);
+    }
+    return stellar_sdk_1.xdr.ScVal.scvI128(new stellar_sdk_1.xdr.Int128Parts({
+        hi: new stellar_sdk_1.xdr.Int64(hi),
+        lo: new stellar_sdk_1.xdr.Uint64(lo),
+    }));
+}
+function capError(code, message) {
+    const err = new Error(message);
+    err.code = code;
+    err.severity = 'error';
+    err.retryable = false;
+    throw err;
+}

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

@@ -0,0 +1 @@
+export { type EncodedPredicate, encodePredicate } from './encode.ts';

package/dist-cjs/predicate/index.js

@@ -0,0 +1,6 @@
+"use strict";
+// src/predicate/index.ts - re-export the canonical predicate encoder.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodePredicate = void 0;
+var encode_ts_1 = require("./encode.js");
+Object.defineProperty(exports, "encodePredicate", { enumerable: true, get: function () { return encode_ts_1.encodePredicate; } });

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

@@ -0,0 +1,79 @@
+import { xdr } from '@stellar/stellar-sdk';
+import { type ContractInvocation, type Network, type OnChainEvent, type ParseConfidence, type ScVal, type TokenMovement } from '../types.ts';
+/** Result of decoding an envelope XDR plus the surrounding metadata from
+ *  `getTransaction` (events + auth entries). All fields are plain JSON; the
+ *  caller decides how to interpret them. */
+export interface SerializableAuthEntry {
+    authorizingAddress: string | null;
+    contract: string;
+    fn: string;
+}
+export interface DecodedTransaction {
+    sourceAccount: string;
+    /** Authorising signers from the envelope signatures (hex-encoded ed25519
+     *  pubkey hints expanded to G... strkeys). The recorder cannot recover the
+     *  strkey from the 4-byte hint alone; we record the hint bytes hex instead
+     *  when no full strkey is available. */
+    signers: string[];
+    invocations: ContractInvocation[];
+    /** Raw on-chain events (from getTransaction.events). Used by validate.ts to
+     *  cross-check the parsed TokenMovement[] and ContractInvocation[]. */
+    events: OnChainEvent[];
+    /** Plain JSON projection of InvokeHostFunctionOp.auth(). */
+    authEntries: SerializableAuthEntry[];
+    /** Records that include at least one `ContractInvocation` whose decoded args
+     *  vector or whose auth-tree contained an opaque ScVal. Empty list = full
+     *  parseConfidence = 1.0 (modulo unknown contracts). */
+    opaqueScVals: ParseConfidence['opaqueScVals'];
+    /** Contracts referenced in invocations whose (fn, args) did not match any
+     *  known protocol ABI. Each unrecognised invocation is recorded separately
+     *  so the freshness gate stays fail-closed regardless of operation order. */
+    unknownContracts: ParseConfidence['unknownContracts'];
+    knownContracts: string[];
+    ledgerSequence: number;
+}
+/** Decode a TransactionEnvelope XDR (base64) into a fully parsed invocation tree. */
+export declare function decodeEnvelopeXdr(envelopeXdrB64: string, events?: OnChainEvent[], _authEntries?: unknown[], ledgerSequence?: number, knownContracts?: ReadonlySet<string>, network?: Network | null): DecodedTransaction;
+/** Same as `decodeEnvelopeXdr` but accepts an already-decoded envelope. Useful
+ *  for tests that build the envelope via SDK helpers (no XDR round-trip). */
+export declare function decodeEnvelope(envelope: xdr.TransactionEnvelope, events?: OnChainEvent[], _authEntries?: unknown[], ledgerSequence?: number, knownContracts?: ReadonlySet<string>, network?: Network | null): DecodedTransaction;
+/** Decode an ScAddress (either account or contract) to its strkey form. */
+export declare function decodeScAddressToAnyStrkey(scAddr: xdr.ScAddress): string | null;
+/** Decode an ScAddress to a C... contract strkey. */
+export declare function decodeScAddressToC(scAddr: xdr.ScAddress): string;
+/** 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). */
+export declare function scValToSubset(val: xdr.ScVal, path: string, opaqueScVals: ParseConfidence['opaqueScVals'], depth?: number): ScVal;
+/** 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. */
+export declare function i128PartsToBigInt(parts: xdr.Int128Parts): bigint;
+/** Convert UInt128Parts (hi: Uint64, lo: Uint64) to an unsigned BigInt. */
+export declare function u128PartsToBigInt(parts: xdr.UInt128Parts): bigint;
+export declare function u64PartsToBigInt(h: xdr.UnsignedHyper | xdr.Hyper): bigint;
+/** 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). */
+export declare function scValToTopicString(val: xdr.ScVal): string;
+/** Build the OnChainEvent[] view from raw contract events. Diagnostic-only:
+ *  captures the topics + data + emitter contract for the downstream
+ *  validator. */
+export declare function contractEventsToOnChainEvents(contractEvents: xdr.ContractEvent[][]): OnChainEvent[];
+/** Build the OnChainEvent[] view from TransactionEvent[] (which wraps
+ *  ContractEvent with a stage). Same shape as above. */
+export declare function transactionEventsToOnChainEvents(txEvents: xdr.TransactionEvent[]): OnChainEvent[];
+/** Tiny typed error so callers can `instanceof DecodeError` without leaking
+ *  SDK internals. */
+export declare class DecodeError extends Error {
+    readonly name = "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). */
+export declare function tokenMovementKey(m: TokenMovement): string;