@lamarge/sdk 0.0.0-stage → 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,92 @@
+import { type operations } from "./generated/api.ts";
+/** An API refusal or an unusable answer. `code` and `reason` are stable; `message` is for people. */
+export declare class LaMargeError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly name = "LaMargeError";
+    readonly requestId: string | undefined;
+    readonly retryable: boolean | undefined;
+    readonly retryAfterMs: number | undefined;
+    readonly reason: string | undefined;
+    /** With `SETUP_REQUIRED`: the venue and the setup step to do first. */
+    readonly venue: string | undefined;
+    readonly step: string | undefined;
+    constructor(status: number, code: string, message: string, details?: {
+        requestId?: string | undefined;
+        retryable?: boolean | undefined;
+        retryAfterMs?: number | undefined;
+        reason?: string | undefined;
+        venue?: string | undefined;
+        step?: string | undefined;
+    });
+}
+export interface Request {
+    method: string;
+    /** Path template, such as `/v1/takes/{id}`. */
+    path: string;
+    params?: Record<string, string | number> | undefined;
+    query?: Record<string, string | number | boolean | undefined> | undefined;
+    body?: unknown;
+    token?: string | null | undefined;
+    signal?: AbortSignal | undefined;
+    /** Retry a 429, a 5xx or a network failure with the identical request, at most twice. Only for an
+     * operation that repeating cannot change: a read, or an exact replay of a client id or signed operation. */
+    retry?: boolean | undefined;
+    /** Statuses whose JSON body is the answer, as `/health`'s 503 while it is not ready. */
+    accept?: readonly number[] | undefined;
+}
+export interface Transport {
+    apiUrl: string;
+    fetch?: typeof fetch | undefined;
+    timeoutMs?: number | undefined;
+}
+/** Resolves after `ms`, or rejects as soon as `signal` aborts. */
+export declare function wait(ms: number, signal?: AbortSignal): Promise<void>;
+/** One HTTP exchange with the API: the answer's status and decoded JSON, or a `LaMargeError`. */
+export declare function exchange(transport: Transport, request: Request): Promise<{
+    status: number;
+    body: unknown;
+}>;
+/** An operation's path and query parameters, and its body, as a generated `operations` entry types them. */
+export type OperationInput<Op> = (Op extends {
+    parameters: infer P;
+} ? Pick<P, Extract<keyof P, "path" | "query">> : never) & (Op extends {
+    requestBody: {
+        content: {
+            "application/json": infer B;
+        };
+    };
+} ? {
+    body: B;
+} : {
+    body?: never;
+});
+type SuccessBody<R> = R extends {
+    content: {
+        "application/json": infer B;
+    };
+} ? B : null;
+/** An operation's success answer, as a generated `operations` entry types it. */
+export type OperationAnswer<Op> = Op extends {
+    responses: infer R;
+} ? SuccessBody<R[Extract<keyof R, 200 | 201 | 202 | 204>]> : never;
+export type Answer<O extends keyof operations> = OperationAnswer<operations[O]>;
+export type CallOptions<O extends keyof operations> = OperationInput<operations[O]> & {
+    signal?: AbortSignal | undefined;
+    retry?: boolean | undefined;
+};
+/** The options, required when the operation has a path parameter, a required query or a body. */
+export type CallArguments<O extends keyof operations> = object extends CallOptions<O> ? [options?: CallOptions<O>] : [options: CallOptions<O>];
+export interface ClientConfig extends Transport {
+    /** A session token or a maker credential (`mk_…`). */
+    token?: string | undefined;
+}
+export interface Client {
+    readonly apiUrl: string;
+    token: string | undefined;
+    /** Any public operation by its `operationId`, typed by the API reference. Answers are typed, not validated:
+     * what gets signed is checked by `@lamarge/sdk/protocol`. */
+    call<O extends keyof operations>(operation: O, ...options: CallArguments<O>): Promise<Answer<O>>;
+}
+export declare function createClient(config: ClientConfig): Client;
+export {};

package/dist/client.js

@@ -0,0 +1,100 @@
+import { routes } from "./generated/api.js";
+import { isRecord, required } from "./protocol/validation.js";
+import { retryAfterMs } from "./retry-after.js";
+/** An API refusal or an unusable answer. `code` and `reason` are stable; `message` is for people. */
+export class LaMargeError extends Error {
+    status;
+    code;
+    name = "LaMargeError";
+    requestId;
+    retryable;
+    retryAfterMs;
+    reason;
+    /** With `SETUP_REQUIRED`: the venue and the setup step to do first. */
+    venue;
+    step;
+    constructor(status, code, message, details = {}) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.requestId = details.requestId;
+        this.retryable = details.retryable;
+        this.retryAfterMs = details.retryAfterMs;
+        this.reason = details.reason;
+        this.venue = details.venue;
+        this.step = details.step;
+    }
+}
+const text = (value) => typeof value === "string" ? value : undefined;
+function refusal(status, raw, headers) {
+    const error = isRecord(raw) && isRecord(raw.error) ? raw.error : undefined;
+    const code = text(error?.code);
+    const message = text(error?.message);
+    return new LaMargeError(status, code && message !== undefined ? code : "UNKNOWN", code && message !== undefined ? message : `HTTP ${status}`, {
+        requestId: text(error?.request_id) ?? headers.get("x-request-id") ?? undefined,
+        retryable: typeof error?.retryable === "boolean" ? error.retryable : undefined,
+        retryAfterMs: retryAfterMs(headers.get("retry-after")),
+        reason: text(error?.reason),
+        venue: text(error?.venue),
+        step: text(error?.step),
+    });
+}
+/** Resolves after `ms`, or rejects as soon as `signal` aborts. */
+export function wait(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const abort = () => { clearTimeout(timer); reject(signal?.reason); };
+        const timer = setTimeout(() => { signal?.removeEventListener("abort", abort); resolve(); }, ms);
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+/** One HTTP exchange with the API: the answer's status and decoded JSON, or a `LaMargeError`. */
+export async function exchange(transport, request) {
+    const path = request.path.replace(/\{([^}]+)\}/g, (_match, key) => encodeURIComponent(required(request.params?.[key], `Missing path parameter ${key}`)));
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(request.query ?? {}))
+        if (value !== undefined)
+            query.set(key, String(value));
+    const headers = { accept: "application/json" };
+    if (request.body !== undefined)
+        headers["content-type"] = "application/json";
+    if (request.token)
+        headers.authorization = `Bearer ${request.token}`;
+    const url = `${transport.apiUrl.replace(/\/+$/, "")}${path}${query.size ? `?${query}` : ""}`;
+    const body = request.body === undefined ? undefined : JSON.stringify(request.body);
+    const timeoutMs = transport.timeoutMs ?? 30_000;
+    for (let attempt = 0;; attempt++) {
+        request.signal?.throwIfAborted();
+        try {
+            const signal = request.signal ? AbortSignal.any([request.signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs);
+            const response = await (transport.fetch ?? globalThis.fetch)(url, { method: request.method, headers, signal, ...(body === undefined ? {} : { body }) });
+            const raw = response.status === 204 ? null : await response.json().catch(() => null);
+            if (!response.ok && !request.accept?.includes(response.status))
+                throw refusal(response.status, raw, response.headers);
+            return { status: response.status, body: raw };
+        }
+        catch (error) {
+            request.signal?.throwIfAborted();
+            // The server says what may be retried; an answer without its envelope, from a proxy, only for a 429 or 5xx.
+            const transient = !(error instanceof LaMargeError) || (error.retryable ?? (error.status === 429 || error.status >= 500));
+            if (!request.retry || attempt >= 2 || !transient)
+                throw error;
+            const delay = error instanceof LaMargeError && error.retryAfterMs !== undefined ? error.retryAfterMs : 250 * 2 ** attempt;
+            await wait(delay, request.signal);
+        }
+    }
+}
+export function createClient(config) {
+    const url = new URL(config.apiUrl);
+    if (url.protocol !== "https:" && !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))
+        throw new Error("Use HTTPS outside localhost");
+    async function call(operation, options = {}) {
+        const route = routes[operation];
+        const answer = await exchange(config, {
+            method: route.method, path: route.path, params: options.path, query: options.query, body: options.body, token: client.token,
+            signal: options.signal, retry: options.retry ?? route.method === "GET", accept: route.accept,
+        });
+        return answer.body;
+    }
+    const client = { apiUrl: config.apiUrl, token: config.token, call };
+    return client;
+}

package/dist/delivery.d.ts

@@ -0,0 +1,68 @@
+import type { DeliveryFill } from "./maker.ts";
+/** The deliveries a deliverer persisted, by fill: read whole, saved whole; nothing is sent before a save resolves, and a failed save sends nothing. */
+export type DeliveryJournal<T> = {
+    load: () => Record<string, T> | Promise<Record<string, T>>;
+    save: (deliveries: Record<string, T>) => void | Promise<void>;
+};
+/** Where the deliverer reads the identity's fills and reports deliveries: a `Quoter` or its `fillFeed`. */
+export interface FillSource {
+    fills(): Promise<DeliveryFill[]>;
+    deliver(id: string, hash: string): Promise<{
+        fill: {
+            delivery_hash: string | null;
+            state: string;
+        };
+    }>;
+}
+export type Log = (line: string) => void;
+export declare const errorText: (error: unknown) => string;
+/** The venue answered the send and refused it: these bytes never execute. */
+export declare class Refused extends Error {
+}
+export declare abstract class VenueDeliverer<D extends {
+    fill_id: string;
+    outcome?: string | undefined;
+}> {
+    private venue;
+    protected sendMargin: number;
+    protected store: DeliveryJournal<D>;
+    protected now: () => number;
+    private running;
+    private stuckSince;
+    /** When each fill's report may be retried. */
+    private reportAt;
+    /** `sendMargin`: no transfer is first sent closer than this to `deliver_by`. */
+    constructor(venue: string, sendMargin: number, store: DeliveryJournal<D>, now: () => number);
+    /** Moves one persisted delivery forward; false while its outcome on the venue is unknown. */
+    protected abstract settle(quoter: FillSource, delivery: D, fill: DeliveryFill | undefined, deliveries: Record<string, D>, log: Log): Promise<boolean>;
+    /** Delivers fills of `due`, the earliest deadline first; false while one's outcome on the venue is unknown. */
+    protected abstract deliver(quoter: FillSource, due: DeliveryFill[], deliveries: Record<string, D>, log: Log): Promise<boolean>;
+    /** One pass at a time: overlapping calls share the pass in progress. */
+    run(quoter: FillSource, log?: Log): Promise<void>;
+    /** True while deliveries have been stuck for a while: the pool must stop taking fills. */
+    get blocked(): boolean;
+    /**
+     * Settles persisted deliveries first, then, only if no outcome is unknown, delivers paid fills
+     * whose payment the server has re-read. Returns true when the pass left no outcome unknown.
+     */
+    private pass;
+    /**
+     * Whether the server still accepts a delivery for `fill`: until `report_by`, while the payment
+     * is locked, even after the maker leg was abandoned for lack of a report.
+     */
+    protected awaits(fill: DeliveryFill | undefined): fill is DeliveryFill;
+    /** False while `id` waits for its next try; otherwise schedules the next one with a growing backoff. */
+    protected turn(map: Map<string, {
+        at: number;
+        wait: number;
+    }>, id: string): boolean;
+    /** False while the fill's report waits for its retry. */
+    protected reportDue(id: string): boolean;
+    /**
+     * Reports `hash` as the fill's delivery. Returns `failed` when the server will never take it,
+     * or undefined to retry, less often while the server says the venue does not show it final yet.
+     */
+    protected report(quoter: FillSource, id: string, hash: string, log: Log): Promise<"reported" | "failed" | undefined>;
+    /** Unsettled deliveries plus fills this bot can still send; a shutdown waits for zero. */
+    outstanding(quoter: FillSource): Promise<number>;
+}

package/dist/delivery.js

@@ -0,0 +1,118 @@
+// Shared by deliveries inside a venue: one pass at a time, persisted deliveries settled before new
+// fills are signed, stuck pools stop quoting, delivery reports and shutdown draining. The journal's
+// storage is the caller's: a file synced on each save, a database.
+import { LaMargeError } from "./client.js";
+import { insist } from "./protocol/protocol.js";
+/** Deliveries stuck this long stop the pool's quotes: a new fill could not be delivered. */
+const STUCK_MS = 15_000;
+export const errorText = (error) => error instanceof Error ? error.message : String(error);
+/** The venue answered the send and refused it: these bytes never execute. */
+export class Refused extends Error {
+}
+export class VenueDeliverer {
+    venue;
+    sendMargin;
+    store;
+    now;
+    running = null;
+    stuckSince = null;
+    /** When each fill's report may be retried. */
+    reportAt = new Map();
+    /** `sendMargin`: no transfer is first sent closer than this to `deliver_by`. */
+    constructor(venue, sendMargin, store, now) {
+        this.venue = venue;
+        this.sendMargin = sendMargin;
+        this.store = store;
+        this.now = now;
+    }
+    /** One pass at a time: overlapping calls share the pass in progress. */
+    run(quoter, log = console.log) {
+        this.running ??= this.pass(quoter, log).then(progressed => { this.stuckSince = progressed ? null : this.stuckSince ?? this.now(); }, error => { this.stuckSince ??= this.now(); throw error; }).finally(() => { this.running = null; });
+        return this.running;
+    }
+    /** True while deliveries have been stuck for a while: the pool must stop taking fills. */
+    get blocked() {
+        return this.stuckSince !== null && this.now() - this.stuckSince >= STUCK_MS;
+    }
+    /**
+     * Settles persisted deliveries first, then, only if no outcome is unknown, delivers paid fills
+     * whose payment the server has re-read. Returns true when the pass left no outcome unknown.
+     */
+    async pass(quoter, log) {
+        const deliveries = await this.store.load();
+        const fills = (await quoter.fills()).filter(fill => fill.role === "maker" && fill.to_venue === this.venue && fill.delivery_to !== null);
+        const byId = new Map(fills.map(fill => [fill.id, fill]));
+        let unknown = false;
+        for (const delivery of Object.values(deliveries).filter(delivery => !delivery.outcome)) {
+            try {
+                unknown = !(await this.settle(quoter, delivery, byId.get(delivery.fill_id), deliveries, log)) || unknown;
+            }
+            catch (error) {
+                unknown = true;
+                log(`${delivery.fill_id}: ${errorText(error)}`);
+            }
+        }
+        if (unknown)
+            return false;
+        const due = fills
+            .filter(fill => !deliveries[fill.id] && fill.state === "PAID" && fill.maker_leg === "NONE" && !fill.delivery_hash && fill.payment_verified_at && fill.deliver_by && Date.parse(fill.deliver_by) - this.now() > this.sendMargin)
+            .sort((a, b) => Date.parse(a.deliver_by ?? "") - Date.parse(b.deliver_by ?? ""));
+        return this.deliver(quoter, due, deliveries, log);
+    }
+    /**
+     * Whether the server still accepts a delivery for `fill`: until `report_by`, while the payment
+     * is locked, even after the maker leg was abandoned for lack of a report.
+     */
+    awaits(fill) {
+        return fill !== undefined && fill.payment_leg === "LOCKED" && ["NONE", "ABANDONED"].includes(fill.maker_leg)
+            && (!fill.report_by || Date.parse(fill.report_by) > this.now());
+    }
+    /** False while `id` waits for its next try; otherwise schedules the next one with a growing backoff. */
+    turn(map, id) {
+        const last = map.get(id);
+        if (last && last.at > this.now())
+            return false;
+        const wait = Math.min((last?.wait ?? 250) * 2, 5_000);
+        map.set(id, { at: this.now() + wait, wait });
+        return true;
+    }
+    /** False while the fill's report waits for its retry. */
+    reportDue(id) {
+        const retry = this.reportAt.get(id);
+        return !retry || retry.at <= this.now();
+    }
+    /**
+     * Reports `hash` as the fill's delivery. Returns `failed` when the server will never take it,
+     * or undefined to retry, less often while the server says the venue does not show it final yet.
+     */
+    async report(quoter, id, hash, log) {
+        try {
+            const { fill } = await quoter.deliver(id, hash);
+            insist(fill.delivery_hash === hash, "The server recorded another delivery");
+            this.reportAt.delete(id);
+            log(`${id}: delivered, ${fill.state}`);
+            return "reported";
+        }
+        catch (error) {
+            const code = error instanceof LaMargeError ? error.code : undefined;
+            const reason = error instanceof LaMargeError ? error.reason : undefined;
+            if (code === "VALIDATION_ERROR" || code === "STATE_CONFLICT") {
+                // The server will never take this transfer as the delivery: `reason` says why.
+                log(`${id}: delivery refused (${String(reason ?? code)}): ${errorText(error)}`);
+                return "failed";
+            }
+            const retry = this.reportAt.get(id);
+            const wait = code === "DELIVERY_PENDING" ? Math.min((retry?.wait ?? 500) * 2, 30_000) : 1_000;
+            this.reportAt.set(id, { at: this.now() + wait, wait });
+            log(`${id}: report pending: ${errorText(error)}`);
+            return undefined;
+        }
+    }
+    /** Unsettled deliveries plus fills this bot can still send; a shutdown waits for zero. */
+    async outstanding(quoter) {
+        const open = Object.values(await this.store.load()).filter(delivery => !delivery.outcome).length;
+        const fills = (await quoter.fills()).filter(fill => fill.role === "maker" && fill.to_venue === this.venue && fill.maker_leg === "NONE"
+            && ["RESERVED", "PAID"].includes(fill.state) && fill.deliver_by && Date.parse(fill.deliver_by) - this.sendMargin > this.now());
+        return open + fills.length;
+    }
+}

package/dist/events.d.ts

@@ -0,0 +1,30 @@
+import { type Answer, type Client } from "./client.ts";
+import type { components } from "./generated/api.ts";
+export type EventPage = components["schemas"]["EventPage"];
+/** `private` snapshots add the signed-in user's or credential's orders, fills and leases. */
+export type Snapshot = Answer<"getV1Snapshot"> | Answer<"getV1MeSnapshot">;
+export type Change = EventPage | {
+    resync: Snapshot;
+};
+/** What the feed needs of a WebSocket: the browser's, Bun's and Node 22's global, or `ws`. */
+export type SocketConstructor = new (url: string) => {
+    onopen: (() => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: (() => void) | null;
+    send(data: string): void;
+    close(): void;
+};
+export interface ChangeOptions {
+    /** `private`: the signed-in user's or credential's orders, fills, leases, balances and withdrawals. */
+    scope: "public" | "private";
+    signal: AbortSignal;
+    WebSocket?: SocketConstructor | undefined;
+}
+/**
+ * What changed, durably: a snapshot first, then each page of events after it, pushed over the
+ * stream; between connections, HTTP replay catches up from the last page yielded. `{ resync }`
+ * replaces all local state. Events say what to read again; they are no settlement ledger.
+ */
+export declare function changes(client: Client, options: ChangeOptions): AsyncGenerator<Change>;

package/dist/events.js

@@ -0,0 +1,93 @@
+import { LaMargeError, wait } from "./client.js";
+import { insist } from "./protocol/protocol.js";
+function decode(frame) {
+    const value = JSON.parse(frame);
+    return value;
+}
+/**
+ * The journal after `after` over the WebSocket stream: each page as the server publishes it, at
+ * least every half second, or a control frame. Ends with the connection, or after five seconds
+ * without a frame.
+ */
+async function* stream(client, after, scope, signal, Socket) {
+    const socket = new Socket(`${client.apiUrl.replace(/\/+$/, "").replace(/^http/, "ws")}/v1/stream`);
+    const frames = [];
+    let wake = () => { };
+    const push = (frame) => { frames.push(frame); wake(); };
+    // The token travels in the first frame, never in the URL.
+    socket.onopen = () => socket.send(JSON.stringify(scope === "private" ? { token: client.token, after } : { after }));
+    socket.onmessage = (event) => push(typeof event.data === "string" ? event.data : null);
+    socket.onclose = () => push(null);
+    const close = () => socket.close();
+    signal.addEventListener("abort", close, { once: true });
+    try {
+        for (;;) {
+            if (!frames.length) {
+                let timer;
+                await new Promise(resolve => { wake = resolve; timer = setTimeout(resolve, 5_000); });
+                clearTimeout(timer);
+            }
+            const frame = frames.shift();
+            if (frame === undefined || frame === null)
+                return;
+            yield decode(frame);
+        }
+    }
+    finally {
+        signal.removeEventListener("abort", close);
+        socket.close();
+    }
+}
+/**
+ * What changed, durably: a snapshot first, then each page of events after it, pushed over the
+ * stream; between connections, HTTP replay catches up from the last page yielded. `{ resync }`
+ * replaces all local state. Events say what to read again; they are no settlement ledger.
+ */
+export async function* changes(client, options) {
+    const { scope, signal } = options;
+    const Socket = options.WebSocket ?? globalThis.WebSocket;
+    const snapshot = () => scope === "private" ? client.call("getV1MeSnapshot", { signal }) : client.call("getV1Snapshot", { signal });
+    const replay = (after) => scope === "private"
+        ? client.call("getV1MeEvents", { query: { after, limit: 500 }, signal })
+        : client.call("getV1Events", { query: { after, limit: 500 }, signal });
+    const initial = await snapshot();
+    let cursor = initial.cursor;
+    yield { resync: initial };
+    const page = (next) => {
+        insist(BigInt(next.next_cursor) >= BigInt(cursor), "Event cursor moved backwards");
+        cursor = next.next_cursor;
+        return next;
+    };
+    while (!signal.aborted) {
+        let resync = false;
+        for await (const frame of stream(client, cursor, scope, signal, Socket)) {
+            if ("type" in frame) {
+                if (frame.type === "authentication_required")
+                    throw new LaMargeError(401, "UNAUTHENTICATED", frame.reason);
+                resync = frame.type === "resync_required";
+                break;
+            }
+            yield page(frame);
+        }
+        if (signal.aborted)
+            break;
+        try {
+            if (resync)
+                throw new LaMargeError(410, "RESYNC_REQUIRED", "The stream asked for a snapshot");
+            for (;;) {
+                const next = page(await replay(cursor));
+                yield next;
+                if (!next.has_more)
+                    break;
+            }
+        }
+        catch (error) {
+            if (!(error instanceof LaMargeError && error.code === "RESYNC_REQUIRED"))
+                throw error;
+            const fresh = await snapshot();
+            cursor = fresh.cursor;
+            yield { resync: fresh };
+        }
+        await wait(500, signal).catch(() => undefined);
+    }
+}

package/dist/funds.d.ts

@@ -0,0 +1,19 @@
+/** A balance read under two minutes old; a missing or unparsable time is stale. */
+export declare const FRESH_MS = 120000;
+export declare const fresh: (at: string | null | undefined, now?: number) => boolean;
+type Held = {
+    venue: string;
+    chain_balance: string | null;
+    chain_error?: string | null | undefined;
+    chain_read_at: string | null;
+    escrow_balance: string | null;
+    deposit_balance?: string | null | undefined;
+};
+/** What the deposit address holds that the relayer sweeps without a withdrawal to it. */
+export declare function sweepable(balance: Held | undefined): bigint;
+/**
+ * What a take pays without moving margin, from a recent, successful escrow-chain read: the
+ * available balance, and the linked address, whose funds the take deposits. Null when unknown.
+ */
+export declare function prefunded(balance: Held | undefined, now?: number): bigint | null;
+export {};

package/dist/funds.js

@@ -0,0 +1,17 @@
+import { sweepMinimum } from "./protocol/protocol.js";
+/** A balance read under two minutes old; a missing or unparsable time is stale. */
+export const FRESH_MS = 120_000;
+export const fresh = (at, now = Date.now()) => Boolean(at) && now - Date.parse(at ?? "") < FRESH_MS;
+/** What the deposit address holds that the relayer sweeps without a withdrawal to it. */
+export function sweepable(balance) {
+    const held = BigInt(balance?.deposit_balance ?? 0);
+    return balance && held >= sweepMinimum(balance.venue) ? held : 0n;
+}
+/**
+ * What a take pays without moving margin, from a recent, successful escrow-chain read: the
+ * available balance, and the linked address, whose funds the take deposits. Null when unknown.
+ */
+export function prefunded(balance, now = Date.now()) {
+    return balance?.chain_balance !== null && balance?.chain_balance !== undefined && !balance.chain_error && fresh(balance.chain_read_at, now)
+        ? BigInt(balance.chain_balance) + BigInt(balance.escrow_balance ?? 0) : null;
+}