@crediolabs/policy-synth 0.1.3 → 0.1.5

package/dist-cjs/record/movements.js

@@ -0,0 +1,192 @@
+"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 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) */
+function readAmount(data) {
+    if (data.type === 'i128')
+        return data.value;
+    if (data.type === 'u64')
+        return data.value;
+    if (data.type !== 'vec')
+        return null;
+    const v = data.value;
+    // SAC transfer event data shape (some clients): Vec<Address, I128>
+    for (const item of v) {
+        if (item.type === 'i128')
+            return item.value;
+        if (item.type === 'u64')
+            return item.value;
+    }
+    // Some flavours wrap in a Map. We expose Map entries as other; bail.
+    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;

package/dist-cjs/registry/identify.js

@@ -0,0 +1,87 @@
+"use strict";
+// src/registry/identify.ts - protocol identification (fail-closed).
+//
+// Given a (contract, method, args) triple, decide whether the call belongs
+// to a known protocol. Returns null when it does NOT - the caller MUST
+// preserve the fail-closed posture for null results.
+//
+// Recognition rules:
+//   1. SEP-41: recognised by INTERFACE - any contract calling one of the
+//      SEP-41 fns (transfer / mint / burn / approve) with a matching arg
+//      shape is a SEP-41 token. No address pin is needed.
+//   2. Blend: recognised by INTERFACE - real pool `submit` / `claim` calls
+//      hit per-pool instances, not the factory. The arg shape must match
+//      the Blend pool ABI (verified against the pool contract source).
+//      Address recognition still applies when the call is against the
+//      pinned factory address, with the same arg-shape check.
+//   3. SoroSwap: recognised by ADDRESS only - the router is a single pinned
+//      contract. FIX 4: the method must ALSO be present in the protocol's
+//      ABI; an unknown method on a pinned router -> null (fail-closed).
+//
+// Method lookup uses `Object.hasOwn` rather than `in` so prototype-chain
+// names like `constructor`, `toString`, `hasOwnProperty` do NOT register as
+// valid method calls. Arg-shape validation compares arg count + each arg's
+// ScVal subset type against the ABI signature; mismatch -> null.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identifyProtocol = identifyProtocol;
+const known_addresses_ts_1 = require("./known-addresses.js");
+const protocols_ts_1 = require("./protocols.js");
+/** 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. */
+function identifyProtocol(contract, method, args, network) {
+    // 1) SEP-41 by interface. Any contract whose (method, args) matches a
+    //    SEP-41 ABI signature is a SEP-41 token.
+    if (Object.hasOwn(protocols_ts_1.SEP41_ABI, method)) {
+        const sig = protocols_ts_1.SEP41_ABI[method];
+        if (sig && argsMatchAbi(sig.args, args)) {
+            return { protocol: 'sep41', fn: method };
+        }
+        return null;
+    }
+    // 2) Blend by interface. Real pool calls hit per-pool instances; pinned
+    //    factory calls also match here when the method is in the pool ABI.
+    if (Object.hasOwn(protocols_ts_1.BLEND_ABI, method)) {
+        const sig = protocols_ts_1.BLEND_ABI[method];
+        if (sig && argsMatchAbi(sig.args, args)) {
+            return { protocol: 'blend', fn: method };
+        }
+        return null;
+    }
+    // 3) Pinned-address recognition (Blend factory + SoroSwap router/factory).
+    //    FIX 4: the method must also be in the protocol's ABI; an unknown
+    //    method on a pinned address -> null.
+    if (network) {
+        const pinned = (0, known_addresses_ts_1.addressToProtocol)(contract, network);
+        if (pinned) {
+            const abi = pinned === 'blend' ? protocols_ts_1.BLEND_ABI : protocols_ts_1.SOROSWAP_ABI;
+            if (Object.hasOwn(abi, method)) {
+                const sig = abi[method];
+                if (sig && argsMatchAbi(sig.args, args)) {
+                    return { protocol: pinned, fn: method };
+                }
+            }
+        }
+    }
+    void contract;
+    return null;
+}
+/** Compare the decoded args against the ABI signature. Returns true only when
+ *  the arg count matches AND every arg's ScVal subset type matches the ABI's
+ *  declared type. `other` is intentionally NOT a valid ABI match - it means
+ *  the decoder couldn't classify the value, which is exactly the signal
+ *  fail-closed should refuse. */
+function argsMatchAbi(expected, actual) {
+    if (expected.length !== actual.length)
+        return false;
+    for (let i = 0; i < expected.length; i += 1) {
+        const want = expected[i];
+        const got = actual[i];
+        if (!want || !got)
+            return false;
+        if (want.type !== got.type)
+            return false;
+    }
+    return true;
+}

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

@@ -0,0 +1,3 @@
+export { type IdentifiedProtocol, identifyProtocol, } from './identify.ts';
+export { addressToProtocol, KNOWN_ADDRESSES, type KnownAddressesByNetwork, type KnownAddressesByProtocol, } from './known-addresses.ts';
+export { type AbiArg, type AbiEntry, BLEND_ABI, getAbi, PROTOCOL_ABIS, type ProtocolAbi, type ProtocolId, SEP41_ABI, SOROSWAP_ABI, } from './protocols.ts';

package/dist-cjs/registry/index.js

@@ -0,0 +1,15 @@
+"use strict";
+// src/registry/index.ts - re-export the protocol adjacency registry.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SOROSWAP_ABI = exports.SEP41_ABI = exports.PROTOCOL_ABIS = exports.getAbi = exports.BLEND_ABI = exports.KNOWN_ADDRESSES = exports.addressToProtocol = exports.identifyProtocol = void 0;
+var identify_ts_1 = require("./identify.js");
+Object.defineProperty(exports, "identifyProtocol", { enumerable: true, get: function () { return identify_ts_1.identifyProtocol; } });
+var known_addresses_ts_1 = require("./known-addresses.js");
+Object.defineProperty(exports, "addressToProtocol", { enumerable: true, get: function () { return known_addresses_ts_1.addressToProtocol; } });
+Object.defineProperty(exports, "KNOWN_ADDRESSES", { enumerable: true, get: function () { return known_addresses_ts_1.KNOWN_ADDRESSES; } });
+var protocols_ts_1 = require("./protocols.js");
+Object.defineProperty(exports, "BLEND_ABI", { enumerable: true, get: function () { return protocols_ts_1.BLEND_ABI; } });
+Object.defineProperty(exports, "getAbi", { enumerable: true, get: function () { return protocols_ts_1.getAbi; } });
+Object.defineProperty(exports, "PROTOCOL_ABIS", { enumerable: true, get: function () { return protocols_ts_1.PROTOCOL_ABIS; } });
+Object.defineProperty(exports, "SEP41_ABI", { enumerable: true, get: function () { return protocols_ts_1.SEP41_ABI; } });
+Object.defineProperty(exports, "SOROSWAP_ABI", { enumerable: true, get: function () { return protocols_ts_1.SOROSWAP_ABI; } });

package/dist-cjs/registry/known-addresses.d.ts

@@ -0,0 +1,16 @@
+import type { ProtocolId } from './protocols.ts';
+/** Pinned contract addresses per (network, protocol). Empty list = no
+ *  addresses pinned for that cell. */
+export interface KnownAddressesByProtocol {
+    blend: string[];
+    soroswap: string[];
+}
+export interface KnownAddressesByNetwork {
+    mainnet: KnownAddressesByProtocol;
+    testnet: KnownAddressesByProtocol;
+}
+export declare const KNOWN_ADDRESSES: KnownAddressesByNetwork;
+/** Map a (contract, network) pair to its pinned protocol id. Returns null
+ *  when the address is not pinned for that network - callers MUST preserve
+ *  the fail-closed posture for unpinned contracts. */
+export declare function addressToProtocol(contract: string, network: 'mainnet' | 'testnet'): ProtocolId | null;

package/dist-cjs/registry/known-addresses.js

@@ -0,0 +1,53 @@
+"use strict";
+// src/registry/known-addresses.ts - pinned real protocol contract addresses.
+//
+// Addresses here are fetched from authoritative public sources:
+//   - Blend mainnet: docs.blend.capital/mainnet-deployments
+//     https://docs.blend.capital/mainnet-deployments
+//   - SoroSwap mainnet: github.com/soroswap (organisation README)
+//     https://github.com/soroswap
+//
+// Testnet addresses are intentionally NOT pinned: the public docs do not
+// publish them, and per the task brief, unconfirmed addresses are marked
+// [VERIFY] and excluded from the active set rather than invented.
+//
+// SEP-41 is recognised by interface (any token), so no address list is needed
+// for it - see identify.ts.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWN_ADDRESSES = void 0;
+exports.addressToProtocol = addressToProtocol;
+// Source: https://docs.blend.capital/mainnet-deployments (Blend Pool Factory
+// mainnet deployment, fetched 2026-07-23).
+const BLEND_MAINNET_POOL_FACTORY = 'CDSYOAVXFY7SM5S64IZPPPYB4GVGGLMQVFREPSQQEZVIWXX5R23G4QSU';
+// Source: https://github.com/soroswap (organisation README, fetched 2026-07-23)
+// SoroswapRouter mainnet deployment.
+const SOROSWAP_MAINNET_ROUTER = 'CAG5LRYQ5JVEUI5TEID72EYOVX44TTUJT5BQR2J6J77FH65PCCFAJDDH';
+// Source: https://github.com/soroswap (organisation README, fetched 2026-07-23)
+// SoroswapFactory mainnet deployment.
+const SOROSWAP_MAINNET_FACTORY = 'CA4HEQTL2WPEUYKYKCDOHCDNIV4QHNJ7EL4J4NQ6VADP7SYHVRYZ7AW2';
+exports.KNOWN_ADDRESSES = {
+    mainnet: {
+        blend: [BLEND_MAINNET_POOL_FACTORY],
+        soroswap: [SOROSWAP_MAINNET_ROUTER, SOROSWAP_MAINNET_FACTORY],
+    },
+    testnet: {
+        // [VERIFY] Blend testnet pool factory address: not published in the
+        // public docs as of 2026-07-23. Excluded from the active set until an
+        // authoritative source is found.
+        blend: [],
+        // [VERIFY] SoroSwap testnet router / factory addresses: not published in
+        // the public docs as of 2026-07-23. Excluded from the active set.
+        soroswap: [],
+    },
+};
+/** Map a (contract, network) pair to its pinned protocol id. Returns null
+ *  when the address is not pinned for that network - callers MUST preserve
+ *  the fail-closed posture for unpinned contracts. */
+function addressToProtocol(contract, network) {
+    for (const protocol of ['blend', 'soroswap']) {
+        if (exports.KNOWN_ADDRESSES[network][protocol].includes(contract)) {
+            return protocol;
+        }
+    }
+    return null;
+}

package/dist-cjs/registry/protocols.d.ts

@@ -0,0 +1,38 @@
+import type { ScVal } from '../types.ts';
+export type ProtocolId = 'sep41' | 'blend' | 'soroswap';
+/** ScVal subset type vocabulary the ABI uses. Mirrors `ScVal['type']` minus
+ *  `other` (which by definition cannot be matched against an ABI arg). */
+export type AbiArgType = Exclude<ScVal['type'], 'other'>;
+export interface AbiArg {
+    name: string;
+    /** ScVal subset type the decoded arg must conform to. */
+    type: AbiArgType;
+    /** Human-readable meaning for the downstream reviewer. */
+    meaning: string;
+}
+export interface AbiEntry {
+    args: AbiArg[];
+}
+export type ProtocolAbi = Record<string, AbiEntry>;
+/** SEP-41 token interface - pinned from the SEP-41 spec (any token). */
+export declare const SEP41_ABI: ProtocolAbi;
+/** Blend pool interface (v2). Pinning the two fns the recorder surfaces.
+ *  Pool-level recognition is by INTERFACE (real pool calls hit per-pool
+ *  instances, not the factory). Arg shapes verified against the Blend v2
+ *  pool contract source (blend-capital/blend-contracts-v2 `pool/src/contract.rs`,
+ *  fetched 2026-07-23):
+ *    submit(env, from: Address, spender: Address, to: Address, requests: Vec<Request>)
+ *      -> Positions
+ *    claim(env, from: Address, reserve_token_ids: Vec<u32>, to: Address) -> i128
+ *  Other pool fns (add_reserves, withdraw, etc.) are intentionally omitted -
+ *  they are too version-sensitive to bind by interface. */
+export declare const BLEND_ABI: ProtocolAbi;
+/** SoroSwap router interface. Standard Uniswap-V2-style swap fn signatures
+ *  pinned from the SoroSwap router source. Recognised by address only (the
+ *  router is a single pinned contract); FIX 4 requires the method to also be
+ *  in this ABI for address recognition to succeed. The `path` arg is a
+ *  `vec<address>` - we record it as the outer `vec` subset and leave the
+ *  per-element shape to the downstream reviewer. */
+export declare const SOROSWAP_ABI: ProtocolAbi;
+export declare const PROTOCOL_ABIS: Record<ProtocolId, ProtocolAbi>;
+export declare function getAbi(protocol: ProtocolId): ProtocolAbi;