@floatonnear/float-adapter 0.0.0-stage → 0.1.1

package/dist/blocked-scan.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Recovering refused payments from the chain, continuously.
+ *
+ * A refusal is deliberately NOT stored in contract state — storing one would
+ * let an agent inflate the vault's storage bill by spamming rejects, which
+ * docs/KNOWN-TRADEOFFS.md §2 names as the real griefing vector. The contract
+ * emits a NEP-297 event and keeps nothing. That makes the single most
+ * important thing this product does invisible to anything that was not
+ * watching at the moment it happened.
+ *
+ * The events do survive, inside receipt outcomes, so they can be read back.
+ * No indexer is involved: NearBlocks returns nothing at all for this testnet
+ * account, so everything here is plain RPC and reproducible by anyone.
+ *
+ * Two things this module is careful about:
+ *
+ *   COST. A naive walk queries every chunk of every block. In practice one
+ *   chunk in ten carries any transaction, and an empty chunk's `tx_root` is
+ *   the all-ones hash, so empties are skipped without a second call. Work per
+ *   tick is also capped, so a long outage cannot turn the catch-up into a
+ *   thundering scan.
+ *
+ *   HONESTY ABOUT COVERAGE. A public RPC garbage-collects old blocks and
+ *   occasionally fails a request. Those blocks are HOLES, and a range that
+ *   contains holes is not covered. Reporting `from..to` while having silently
+ *   skipped blocks inside it would turn "we did not look there" into "nothing
+ *   happened" — the exact confusion this feature exists to remove.
+ */
+/** A chunk with no transactions carries this as its tx_root. */
+export declare const EMPTY_TX_ROOT = "11111111111111111111111111111111";
+export type RpcFn = (method: string, params: unknown) => Promise<any>;
+/**
+ * An RPC caller that paces itself and backs off when throttled.
+ *
+ * Added after watching the follower shred its own coverage map. Public
+ * endpoints rate-limit; without backoff every transient `429` turned into a
+ * PERMANENT gap, because a block that could not be read is recorded as
+ * unread. One load test left 33 fragmented gaps of three to twenty blocks
+ * each — each one technically honest and collectively useless, since nobody
+ * is ever going to backfill a five-block hole.
+ *
+ * Holes should mean "this span is genuinely unavailable", not "the endpoint
+ * was briefly busy". Retrying is what keeps that distinction meaningful.
+ */
+export declare function createRpc(url: string, opts?: {
+    paceMs?: number;
+    maxRetries?: number;
+    onThrottle?: (waitMs: number) => void;
+}): RpcFn;
+export interface BlockedRecord {
+    requestId: string;
+    nodeId: number;
+    reasonCode: string;
+    agent: string;
+    txHash: string;
+    blockHeight: number;
+    blockTimestampNs: string;
+}
+export interface ScanResult {
+    records: BlockedRecord[];
+    blocksSeen: number;
+    chunksFetched: number;
+    chunksSkipped: number;
+    /** Heights that could not be read. Coverage inside a hole is unknown. */
+    holes: number[];
+}
+/**
+ * Pull `request_blocked` events out of one transaction's receipt logs.
+ * Exported for testing: this parsing is the part that silently breaks if the
+ * event format ever changes.
+ */
+export declare function extractBlocked(logs: string[], ctx: {
+    agent: string;
+    txHash: string;
+    blockHeight: number;
+    blockTimestampNs: string;
+}): BlockedRecord[];
+/** Scan an inclusive block range for refusals by `vault`. */
+export declare function scanRange(rpc: RpcFn, vault: string, from: number, to: number): Promise<ScanResult>;
+/** An inclusive span of blocks that was NOT read. */
+export interface Hole {
+    from: number;
+    to: number;
+}
+export interface BlockedStore {
+    vault: string;
+    scannedFrom: number | null;
+    scannedTo: number | null;
+    /**
+     * Spans known to be unread, as RANGES rather than individual heights.
+     * An adapter restarted after a day is tens of thousands of blocks behind;
+     * listing each one would bloat the file to no purpose. Kept so that
+     * coverage is never overstated — `scannedFrom..scannedTo` minus these is
+     * what has actually been examined.
+     */
+    holes: Hole[];
+    blocked: Record<string, BlockedRecord>;
+}
+/** Merge overlapping/adjacent spans so the list stays short and readable. */
+export declare function coalesce(spans: Hole[]): Hole[];
+export declare function emptyStore(vault: string): BlockedStore;
+/** Fold a scan result into a store. Pure, so the merge rules are testable. */
+export declare function mergeScan(store: BlockedStore, from: number, to: number, res: ScanResult): {
+    store: BlockedStore;
+    added: number;
+};
+export interface FollowerOptions {
+    rpc: RpcFn;
+    vault: string;
+    load: () => BlockedStore;
+    save: (s: BlockedStore) => void;
+    /** Milliseconds between ticks. */
+    intervalMs?: number;
+    /** Hard cap on blocks examined per tick, so catch-up stays bounded. */
+    maxBlocksPerTick?: number;
+    /**
+     * If the cursor falls further behind the head than this, STOP trying to
+     * walk the gap: record it as a hole and resume at the head.
+     *
+     * Grinding through a day's backlog is tens of thousands of RPC calls and
+     * leaves the follower useless for hours. Jumping silently would be worse —
+     * it would report the skipped span as covered. Recording the hole keeps the
+     * adapter current AND keeps the coverage claim true; the gap can then be
+     * filled deliberately with scripts/scan-blocked.mjs.
+     */
+    maxCatchupBlocks?: number;
+    onTick?: (info: {
+        from: number;
+        to: number;
+        added: number;
+        holes: number;
+    }) => void;
+    /** Called when a backlog was too large to walk and became a hole. */
+    onSkip?: (span: Hole) => void;
+}
+/**
+ * Follows the chain head, recording refusals as they happen.
+ *
+ * Starts from the stored cursor when there is one, and otherwise from the
+ * CURRENT head — never from genesis. A fresh adapter should not spend its
+ * first hour replaying history nobody asked for; `scripts/scan-blocked.mjs`
+ * exists for deliberate backfill.
+ */
+export declare class BlockedFollower {
+    private readonly o;
+    private timer;
+    private running;
+    private stopped;
+    constructor(o: FollowerOptions);
+    tick(): Promise<void>;
+    start(): void;
+    stop(): void;
+}

package/dist/blocked-scan.js

@@ -0,0 +1,274 @@
+/**
+ * Recovering refused payments from the chain, continuously.
+ *
+ * A refusal is deliberately NOT stored in contract state — storing one would
+ * let an agent inflate the vault's storage bill by spamming rejects, which
+ * docs/KNOWN-TRADEOFFS.md §2 names as the real griefing vector. The contract
+ * emits a NEP-297 event and keeps nothing. That makes the single most
+ * important thing this product does invisible to anything that was not
+ * watching at the moment it happened.
+ *
+ * The events do survive, inside receipt outcomes, so they can be read back.
+ * No indexer is involved: NearBlocks returns nothing at all for this testnet
+ * account, so everything here is plain RPC and reproducible by anyone.
+ *
+ * Two things this module is careful about:
+ *
+ *   COST. A naive walk queries every chunk of every block. In practice one
+ *   chunk in ten carries any transaction, and an empty chunk's `tx_root` is
+ *   the all-ones hash, so empties are skipped without a second call. Work per
+ *   tick is also capped, so a long outage cannot turn the catch-up into a
+ *   thundering scan.
+ *
+ *   HONESTY ABOUT COVERAGE. A public RPC garbage-collects old blocks and
+ *   occasionally fails a request. Those blocks are HOLES, and a range that
+ *   contains holes is not covered. Reporting `from..to` while having silently
+ *   skipped blocks inside it would turn "we did not look there" into "nothing
+ *   happened" — the exact confusion this feature exists to remove.
+ */
+/** A chunk with no transactions carries this as its tx_root. */
+export const EMPTY_TX_ROOT = "11111111111111111111111111111111";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * An RPC caller that paces itself and backs off when throttled.
+ *
+ * Added after watching the follower shred its own coverage map. Public
+ * endpoints rate-limit; without backoff every transient `429` turned into a
+ * PERMANENT gap, because a block that could not be read is recorded as
+ * unread. One load test left 33 fragmented gaps of three to twenty blocks
+ * each — each one technically honest and collectively useless, since nobody
+ * is ever going to backfill a five-block hole.
+ *
+ * Holes should mean "this span is genuinely unavailable", not "the endpoint
+ * was briefly busy". Retrying is what keeps that distinction meaningful.
+ */
+export function createRpc(url, opts = {}) {
+    const paceMs = opts.paceMs ?? 25;
+    const maxRetries = opts.maxRetries ?? 5;
+    return async function rpc(method, params, attempt = 0) {
+        if (paceMs)
+            await sleep(paceMs);
+        let r;
+        try {
+            r = await fetch(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+            });
+        }
+        catch (e) {
+            // A dropped connection mid-scan is routine, not exceptional.
+            if (attempt >= maxRetries)
+                throw e;
+            await sleep(Math.min(30_000, 500 * 2 ** attempt));
+            return rpc(method, params, attempt + 1);
+        }
+        if (r.status === 429 || r.status >= 500) {
+            if (attempt >= maxRetries)
+                throw new Error(`RPC HTTP ${r.status} after ${attempt} retries`);
+            const wait = Math.min(30_000, 500 * 2 ** attempt);
+            opts.onThrottle?.(wait);
+            await sleep(wait);
+            return rpc(method, params, attempt + 1);
+        }
+        if (!r.ok)
+            throw new Error(`RPC HTTP ${r.status}`);
+        const j = await r.json();
+        if (j.error)
+            throw new Error(`${method}: ${JSON.stringify(j.error).slice(0, 140)}`);
+        return j.result;
+    };
+}
+/**
+ * Pull `request_blocked` events out of one transaction's receipt logs.
+ * Exported for testing: this parsing is the part that silently breaks if the
+ * event format ever changes.
+ */
+export function extractBlocked(logs, ctx) {
+    const out = [];
+    for (const line of logs) {
+        if (!line.startsWith("EVENT_JSON:") || !line.includes("request_blocked"))
+            continue;
+        let ev;
+        try {
+            ev = JSON.parse(line.slice("EVENT_JSON:".length));
+        }
+        catch {
+            // A malformed log line is not a reason to abandon the rest of the
+            // transaction, nor to pretend the others do not exist.
+            continue;
+        }
+        if (ev?.event !== "request_blocked")
+            continue;
+        for (const d of ev.data ?? []) {
+            if (typeof d?.request_id !== "string")
+                continue;
+            out.push({
+                requestId: d.request_id,
+                nodeId: Number(d.node_id),
+                reasonCode: String(d.reason_code ?? "UNKNOWN"),
+                ...ctx,
+            });
+        }
+    }
+    return out;
+}
+/** Scan an inclusive block range for refusals by `vault`. */
+export async function scanRange(rpc, vault, from, to) {
+    const res = {
+        records: [],
+        blocksSeen: 0,
+        chunksFetched: 0,
+        chunksSkipped: 0,
+        holes: [],
+    };
+    for (let h = from; h <= to; h++) {
+        let blk;
+        try {
+            blk = await rpc("block", { block_id: h });
+        }
+        catch {
+            res.holes.push(h);
+            continue;
+        }
+        res.blocksSeen++;
+        for (const ch of blk.chunks ?? []) {
+            if (ch.tx_root === EMPTY_TX_ROOT) {
+                res.chunksSkipped++;
+                continue;
+            }
+            let chunk;
+            try {
+                chunk = await rpc("chunk", { chunk_id: ch.chunk_hash });
+                res.chunksFetched++;
+            }
+            catch {
+                // A chunk we could not read means this block is not fully covered.
+                res.holes.push(h);
+                continue;
+            }
+            for (const tx of chunk.transactions ?? []) {
+                if (tx.receiver_id !== vault)
+                    continue;
+                let st;
+                try {
+                    st = await rpc("EXPERIMENTAL_tx_status", [tx.hash, tx.signer_id]);
+                }
+                catch {
+                    res.holes.push(h);
+                    continue;
+                }
+                const logs = (st.receipts_outcome ?? []).flatMap((o) => o.outcome?.logs ?? []);
+                res.records.push(...extractBlocked(logs, {
+                    agent: tx.signer_id,
+                    txHash: tx.hash,
+                    blockHeight: h,
+                    blockTimestampNs: String(blk.header?.timestamp ?? "0"),
+                }));
+            }
+        }
+    }
+    return res;
+}
+/** Merge overlapping/adjacent spans so the list stays short and readable. */
+export function coalesce(spans) {
+    if (spans.length < 2)
+        return [...spans];
+    const sorted = [...spans].sort((a, b) => a.from - b.from);
+    const out = [{ ...sorted[0] }];
+    for (const s of sorted.slice(1)) {
+        const last = out[out.length - 1];
+        if (s.from <= last.to + 1)
+            last.to = Math.max(last.to, s.to);
+        else
+            out.push({ ...s });
+    }
+    return out;
+}
+export function emptyStore(vault) {
+    return { vault, scannedFrom: null, scannedTo: null, holes: [], blocked: {} };
+}
+/** Fold a scan result into a store. Pure, so the merge rules are testable. */
+export function mergeScan(store, from, to, res) {
+    let added = 0;
+    for (const r of res.records) {
+        if (store.blocked[r.requestId])
+            continue; // same refusal seen twice
+        store.blocked[r.requestId] = r;
+        added++;
+    }
+    store.scannedFrom = store.scannedFrom === null ? from : Math.min(store.scannedFrom, from);
+    store.scannedTo = Math.max(store.scannedTo ?? 0, to);
+    if (res.holes.length) {
+        store.holes = coalesce([...store.holes, ...res.holes.map((h) => ({ from: h, to: h }))]);
+    }
+    return { store, added };
+}
+/**
+ * Follows the chain head, recording refusals as they happen.
+ *
+ * Starts from the stored cursor when there is one, and otherwise from the
+ * CURRENT head — never from genesis. A fresh adapter should not spend its
+ * first hour replaying history nobody asked for; `scripts/scan-blocked.mjs`
+ * exists for deliberate backfill.
+ */
+export class BlockedFollower {
+    o;
+    timer = null;
+    running = false;
+    stopped = false;
+    constructor(o) {
+        this.o = o;
+    }
+    async tick() {
+        // Ticks must never overlap. A slow catch-up on a quiet RPC would
+        // otherwise stack, and two scans sharing a cursor double the work and
+        // race on the store.
+        if (this.running || this.stopped)
+            return;
+        this.running = true;
+        try {
+            const head = (await this.o.rpc("block", { finality: "final" })).header.height;
+            const store = this.o.load();
+            const cap = this.o.maxBlocksPerTick ?? 50;
+            const maxCatchup = this.o.maxCatchupBlocks ?? 5_000;
+            let from = store.scannedTo === null ? head : store.scannedTo + 1;
+            if (from > head)
+                return;
+            if (head - from > maxCatchup) {
+                const skipFrom = from;
+                const skipTo = head - 1;
+                store.holes = coalesce([...store.holes, { from: skipFrom, to: skipTo }]);
+                this.o.onSkip?.({ from: skipFrom, to: skipTo });
+                from = head;
+            }
+            const to = Math.min(head, from + cap - 1);
+            const res = await scanRange(this.o.rpc, this.o.vault, from, to);
+            const { store: next, added } = mergeScan(store, from, to, res);
+            next.vault = this.o.vault;
+            this.o.save(next);
+            this.o.onTick?.({ from, to, added, holes: res.holes.length });
+        }
+        catch {
+            // A failed tick is normal on a public endpoint. Swallow it: the cursor
+            // did not advance, so the next tick retries the same range.
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    start() {
+        this.stopped = false;
+        const ms = this.o.intervalMs ?? 10_000;
+        void this.tick();
+        this.timer = setInterval(() => void this.tick(), ms);
+        // Do not hold the process open on this timer alone.
+        this.timer.unref?.();
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+}

package/dist/env-file.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Read an env file without involving a shell.
+ *
+ * Every doc in this repo tells the operator to run:
+ *
+ *   set -a && . .float/adapter.env && set +a && npx @floatonnear/float-adapter
+ *
+ * That idiom has already failed on a real box. From this project's memory
+ * (prod-env-file-cannot-be-sourced-by-bash): one unquoted value containing a
+ * space made `set -a; . .env; set +a` die with `Scan: command not found`, and
+ * every script opening with that line failed before it ran.
+ *
+ * Two reasons that is the wrong mechanism HERE specifically, rather than merely
+ * fragile:
+ *
+ *   1. The file is written by create-float and carries NEAR_VAULT_AGENT_KEY,
+ *      FLOAT_QUOTE_SIGNER_KEY and FLOAT_API_TOKEN. Sourcing it means the shell
+ *      EXECUTES its contents: `$(...)` and backticks in a value run as
+ *      commands. A secrets file should be data.
+ *   2. It has to work the same way on Windows and on a VPS. `set -a` is not
+ *      available in PowerShell at all, which is why this repo's memory carries
+ *      a bespoke `Get-Content | ForEach-Object { Set-Item Env: }` incantation
+ *      just to start the adapter locally.
+ *
+ * One parser, tested, used by both.
+ */
+/**
+ * Parse `KEY=value` lines into a plain object.
+ *
+ * Deliberately NOT a dotenv clone: no variable interpolation, no escape
+ * sequences, no multi-line values. Each of those is a way for the contents of a
+ * secrets file to change meaning, and none is needed by the file create-float
+ * writes.
+ */
+export declare function parseEnvFile(text: string): Record<string, string>;
+/**
+ * Apply a parsed env file WITHOUT overriding anything already set.
+ *
+ * A real environment variable must outrank the file, so a deploy can point one
+ * service at a different port or contract without editing shared secrets. That
+ * precedence is the same one the pythscan sandbox relied on to keep a verify run
+ * aimed at a database COPY while every credential still came from the
+ * production file.
+ */
+export declare function applyEnvFile(parsed: Record<string, string>, env?: Record<string, string | undefined>): string[];

package/dist/env-file.js

@@ -0,0 +1,82 @@
+/**
+ * Read an env file without involving a shell.
+ *
+ * Every doc in this repo tells the operator to run:
+ *
+ *   set -a && . .float/adapter.env && set +a && npx @floatonnear/float-adapter
+ *
+ * That idiom has already failed on a real box. From this project's memory
+ * (prod-env-file-cannot-be-sourced-by-bash): one unquoted value containing a
+ * space made `set -a; . .env; set +a` die with `Scan: command not found`, and
+ * every script opening with that line failed before it ran.
+ *
+ * Two reasons that is the wrong mechanism HERE specifically, rather than merely
+ * fragile:
+ *
+ *   1. The file is written by create-float and carries NEAR_VAULT_AGENT_KEY,
+ *      FLOAT_QUOTE_SIGNER_KEY and FLOAT_API_TOKEN. Sourcing it means the shell
+ *      EXECUTES its contents: `$(...)` and backticks in a value run as
+ *      commands. A secrets file should be data.
+ *   2. It has to work the same way on Windows and on a VPS. `set -a` is not
+ *      available in PowerShell at all, which is why this repo's memory carries
+ *      a bespoke `Get-Content | ForEach-Object { Set-Item Env: }` incantation
+ *      just to start the adapter locally.
+ *
+ * One parser, tested, used by both.
+ */
+/**
+ * Parse `KEY=value` lines into a plain object.
+ *
+ * Deliberately NOT a dotenv clone: no variable interpolation, no escape
+ * sequences, no multi-line values. Each of those is a way for the contents of a
+ * secrets file to change meaning, and none is needed by the file create-float
+ * writes.
+ */
+export function parseEnvFile(text) {
+    const out = {};
+    // Strip a BOM. PowerShell's Out-File and Set-Content write one by default, so
+    // any file the operator has touched from a one-liner has it, and it would
+    // otherwise become part of the FIRST key's name — producing a missing-variable
+    // failure whose cause is invisible.
+    for (const raw of text.replace(/^/, "").split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        // Split on the FIRST '=' only. Base64url tokens and ed25519 keys contain
+        // '=' as padding, and splitting on each one silently truncates a secret —
+        // which surfaces as a 401 that nobody can account for.
+        const eq = line.indexOf("=");
+        if (eq < 0)
+            continue; // not an assignment; not our business
+        const key = line.slice(0, eq).trim().replace(/^export\s+/, "");
+        if (!key)
+            continue;
+        let value = line.slice(eq + 1).trim();
+        // Strip ONE layer of matching surrounding quotes, so both `A="x y"` and the
+        // bare `A=x y` that broke the shell mean the same thing here.
+        if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * Apply a parsed env file WITHOUT overriding anything already set.
+ *
+ * A real environment variable must outrank the file, so a deploy can point one
+ * service at a different port or contract without editing shared secrets. That
+ * precedence is the same one the pythscan sandbox relied on to keep a verify run
+ * aimed at a database COPY while every credential still came from the
+ * production file.
+ */
+export function applyEnvFile(parsed, env = process.env) {
+    const applied = [];
+    for (const [k, v] of Object.entries(parsed)) {
+        if (env[k] !== undefined)
+            continue;
+        env[k] = v;
+        applied.push(k);
+    }
+    return applied;
+}

package/dist/gate.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Loopback by default. Exposure is opted into, never inherited.
+ *
+ * `listen(port)` with no host is the dangerous default — it binds every
+ * interface. Passing a host explicitly is the whole fix, and defaulting it to
+ * loopback means a deployment has to SAY it wants to be reachable.
+ */
+export declare function resolveHost(host: string | undefined): string;
+/**
+ * CORS headers, echoing only an exact-match origin.
+ *
+ * A wildcard plus an approving preflight is what made this drive-by reachable:
+ * any page the operator had open could POST JSON here. Returning no
+ * `allow-origin` for an unknown origin makes the browser block the response and
+ * — for a preflighted `application/json` POST — never send the request at all.
+ *
+ * The header is omitted entirely when no `Origin` was sent, which is the
+ * curl/server-to-server case and needs no CORS at all.
+ */
+export declare function corsHeaders(allowedOrigin: string, requestOrigin: string | undefined): Record<string, string>;
+export type AuthVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+/**
+ * Only mutating requests need the token.
+ *
+ * GETs are read-only and the bind is loopback, so they are reachable only from
+ * the machine itself. OPTIONS must pass or the browser never reaches the real
+ * request and the dashboard breaks for a reason nobody can see.
+ *
+ * A MISSING token is 503, not 401. They are different problems: 401 tells a
+ * caller to go and find a credential, and here there is none to find — the
+ * operator has not configured one. Conflating them sends people hunting for a
+ * secret that does not exist.
+ */
+export declare function authorize({ method, authHeader, token, }: {
+    method: string;
+    authHeader: string | undefined;
+    token: string | undefined;
+}): AuthVerdict;
+/**
+ * An error caused by the CALLER, not by this server.
+ *
+ * The catch-all returned 500 for everything, so `{"amount":"abc"}` came back as
+ * `500 invalid amount "abc"` — verified live against the running adapter.
+ *
+ * That is not a cosmetic status-code quibble on an agent-facing API. 500 means
+ * "the server broke, retrying may help"; 400 means "your request is wrong, fix
+ * it". An agent reading 500 on a malformed amount retries the same malformed
+ * amount forever. SKILL.md teaches agents exactly this distinction for the
+ * contract's reason codes, and the HTTP layer was contradicting it.
+ */
+export declare class BadRequest extends Error {
+    constructor(message: string);
+}
+/**
+ * Map a thrown value to a response.
+ *
+ * Takes `unknown` rather than `Error` on purpose: `throw "string"` is legal,
+ * and a catch-all that assumes `.message` exists turns a small bug into an
+ * unhandled one. Only the message is returned — never a stack, which would
+ * hand a caller the server's file paths.
+ */
+export declare function classifyError(e: unknown): {
+    status: number;
+    body: {
+        error: string;
+    };
+};
+/**
+ * Run caller-supplied parsing, re-labelling any failure as the caller's.
+ *
+ * Wraps the validation helpers that throw plain `Error` — `toBaseUnits` and
+ * friends — so their failures reach the catch-all already classified, instead
+ * of being indistinguishable from an RPC outage.
+ */
+export declare function fromCaller<T>(fn: () => T): T;