@defdone/annon 0.0.0-stage → 0.1.0-alpha.1

package/dist/relay/admission.js

@@ -0,0 +1,58 @@
+import { rpcReply } from '../near/rpc.js';
+import { RelayError } from './relay.js';
+const paused = new WeakMap();
+/** Final liquid account funds, excluding required account storage stake. */
+export async function admissionBalance(nearRpc, accountId) {
+    const account = await rpcReply(nearRpc, 'query', {
+        request_type: 'view_account',
+        finality: 'final',
+        account_id: accountId,
+    });
+    const a = account.result;
+    const integer = (v) => {
+        if (!((typeof v === 'string' && /^\d+$/.test(v)) ||
+            (typeof v === 'number' && Number.isSafeInteger(v) && v >= 0)))
+            throw new RelayError('relayer_unavailable');
+        return BigInt(v);
+    };
+    if (account.error || !a?.block_hash)
+        throw new RelayError('relayer_unavailable');
+    const usage = integer(a.storage_usage), amount = integer(a.amount), locked = integer(a.locked);
+    const protocol = await rpcReply(nearRpc, 'EXPERIMENTAL_protocol_config', {
+        block_id: a.block_hash,
+    });
+    const price = protocol.result
+        ?.runtime_config?.storage_amount_per_byte;
+    if (protocol.error)
+        throw new RelayError('relayer_unavailable');
+    const stake = usage <= 770n ? 0n : usage * integer(price);
+    const held = stake > locked ? stake - locked : 0n;
+    return amount > held ? amount - held : 0n;
+}
+export async function checkAdmissionFloor(method, o) {
+    if (['unlock', 'claim_key', 'reopen'].includes(method) || o.admissionFloor === undefined)
+        return;
+    let balance;
+    try {
+        if (!o.admissionBalance)
+            throw new Error('balance unavailable');
+        balance = await o.admissionBalance();
+    }
+    catch {
+        const error = new RelayError('relayer_unavailable');
+        error.retryAt = Date.now() + 30000;
+        throw error;
+    }
+    const below = balance < o.admissionFloor;
+    if (o.alert && paused.get(o.alert) !== below) {
+        const previous = paused.get(o.alert);
+        paused.set(o.alert, below);
+        if (below || previous === true)
+            o.alert(below ? 'admissions_paused' : 'admissions_resumed');
+    }
+    if (below) {
+        const error = new RelayError('budget');
+        error.retryAt = Date.now() + 30000;
+        throw error;
+    }
+}

package/dist/relay/capabilities.d.ts

@@ -0,0 +1,36 @@
+import type { FileInfo } from '../near/rpc.js';
+import { type ProtocolFee } from './fees.js';
+export declare const BASE_ELIGIBILITY_MAX_AGE_SECONDS = 30;
+export interface BaseSponsorshipOptions {
+    deployment: {
+        network: string;
+        contractId: string;
+        nearUsdc: string;
+        baseUsdc: string;
+    };
+    file: FileInfo;
+    baseRpc: string;
+    relayer: string;
+    fetch?: typeof fetch;
+    now?: () => number;
+}
+export interface BaseSponsorship {
+    network: string;
+    contract: string;
+    fileId: string;
+    termsHash: string;
+    eligible: true;
+    tier: 'listed' | 'pool' | 'legacy' | 'external';
+    policyVersion: string;
+    minPrice: string;
+    fee: ProtocolFee;
+    decidedAt: number;
+    checkedAt: number;
+    splitCheckedAt: number;
+}
+/** Only records checked here, unchanged and still bound to the same deployment and final file, can be reused. */
+export declare function validBaseSponsorship(record: BaseSponsorship | undefined, o: BaseSponsorshipOptions): boolean;
+/** Verify the deployed immutable split even when the caller funds its own unlock. */
+export declare function checkBaseSplit(file: FileInfo, baseRpc: string): Promise<void>;
+/** Fail closed before signatures, payment submission or release of payment instructions. */
+export declare function checkBaseSponsorship(o: BaseSponsorshipOptions): Promise<BaseSponsorship>;

package/dist/relay/capabilities.js

@@ -0,0 +1,232 @@
+import { AnnonError, isTransient } from '../errors.js';
+import { parseRetryAfterMs } from '../net/retry.js';
+import { PayError } from '../pay/base.js';
+import { readSplitState } from '../pay/split.js';
+import { parseIdentity } from '../settle-near/identity.js';
+import { termsHash } from '../settle-near/terms.js';
+import { checkProtocolFee } from './fees.js';
+const MAX_JSON_BYTES = 65536;
+export const BASE_ELIGIBILITY_MAX_AGE_SECONDS = 30;
+const issued = new WeakMap();
+const binding = (o) => JSON.stringify([
+    o.deployment,
+    o.file.terms,
+    o.file.termsHash,
+    o.file.salesStoppedAt,
+    o.file.takenDown,
+    o.relayer,
+    o.baseRpc,
+]);
+const nowOf = (o) => (o.now ?? (() => Math.floor(Date.now() / 1000)))();
+const fresh = (at, now) => Number.isSafeInteger(at) && at >= 0 && Math.abs(now - at) <= BASE_ELIGIBILITY_MAX_AGE_SECONDS;
+const error = (code, retryAfterSeconds) => Object.assign(new AnnonError(code), {
+    code,
+    ...(retryAfterSeconds === undefined ? {} : { retryAfterSeconds }),
+});
+const uint = (v) => typeof v === 'string' && /^(0|[1-9][0-9]*)$/.test(v) && v.length <= 39 && BigInt(v) < 2n ** 128n;
+function origin(value) {
+    const u = new URL(value);
+    if (u.protocol !== 'https:' ||
+        u.username ||
+        u.password ||
+        u.search ||
+        u.hash ||
+        u.pathname !== '/')
+        throw error('relayer_unavailable');
+    return u.origin;
+}
+async function boundedJson(r) {
+    if (!r.body)
+        throw error('relayer_unavailable');
+    const reader = r.body.getReader();
+    const parts = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            size += next.value.length;
+            if (size > MAX_JSON_BYTES)
+                throw error('relayer_unavailable');
+            parts.push(next.value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    const all = new Uint8Array(size);
+    let at = 0;
+    for (const part of parts) {
+        all.set(part, at);
+        at += part.length;
+    }
+    const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(all));
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw error('relayer_unavailable');
+    return value;
+}
+/** Only records checked here, unchanged and still bound to the same deployment and final file, can be reused. */
+export function validBaseSponsorship(record, o) {
+    if (!record)
+        return false;
+    const saved = issued.get(record);
+    const now = nowOf(o);
+    return (!!saved &&
+        saved.binding === binding(o) &&
+        saved.value === JSON.stringify(record) &&
+        fresh(record.checkedAt, now) &&
+        record.splitCheckedAt <= now &&
+        fresh(record.splitCheckedAt, now));
+}
+/** Verify the deployed immutable split even when the caller funds its own unlock. */
+export async function checkBaseSplit(file, baseRpc) {
+    if (!baseRpc)
+        throw error('relayer_unavailable');
+    const terms = file.terms;
+    if (!terms.base ||
+        file.takenDown !== null ||
+        file.salesStoppedAt !== null ||
+        terms.near.recipients.some((r) => r.identity.kind !== 'evm'))
+        throw error('not_sponsored');
+    try {
+        await readSplitState(baseRpc, terms.base.pay_to, {
+            recipients: terms.near.recipients.map((r) => r.identity.id),
+            allocations: terms.near.recipients.map((r) => BigInt(r.bps)),
+            totalAllocation: 10000n,
+            distributionIncentive: 0,
+        });
+    }
+    catch (e) {
+        if (e instanceof PayError && e.code === 'network_mismatch')
+            throw e;
+        throw error(e instanceof PayError && !isTransient(e) ? 'not_sponsored' : 'relayer_unavailable');
+    }
+}
+/** Fail closed before signatures, payment submission or release of payment instructions. */
+export async function checkBaseSponsorship(o) {
+    if (!o.relayer)
+        throw error('transport_required');
+    let retryAfterSeconds;
+    try {
+        const url = origin(o.relayer);
+        const d = o.deployment;
+        const t = o.file.terms;
+        if (t.near.recipients.some((r) => r.identity.kind !== 'evm'))
+            throw error('not_sponsored');
+        if (t.network !== d.network ||
+            t.contract !== d.contractId ||
+            t.near.token !== d.nearUsdc ||
+            t.base?.usdc !== d.baseUsdc ||
+            termsHash(t, { nearUsdc: d.nearUsdc, baseUsdc: d.baseUsdc }) !== o.file.termsHash)
+            throw error('not_sponsored');
+        const fetcher = o.fetch ?? globalThis.fetch;
+        const request = async (path, body) => {
+            const r = await fetcher(new URL(path, url), {
+                redirect: 'error',
+                credentials: 'omit',
+                cache: 'no-store',
+                signal: AbortSignal.timeout(20000),
+                ...(body
+                    ? {
+                        method: 'POST',
+                        headers: { 'content-type': 'application/json' },
+                        body: JSON.stringify(body),
+                    }
+                    : {}),
+            });
+            const delay = parseRetryAfterMs(r.headers.get('Retry-After'), nowOf(o) * 1000);
+            if (delay !== undefined)
+                retryAfterSeconds = Math.max(1, Math.ceil(delay / 1000));
+            if (!r.ok) {
+                await r.body?.cancel();
+                throw error('relayer_unavailable', retryAfterSeconds);
+            }
+            return boundedJson(r);
+        };
+        const cap = await request('/v1/capabilities');
+        if (cap.network !== d.network ||
+            cap.contract !== d.contractId ||
+            cap.nearUsdc !== d.nearUsdc ||
+            cap.baseUsdc !== d.baseUsdc ||
+            !Array.isArray(cap.methods) ||
+            !cap.methods.includes('unlock') ||
+            typeof cap.disabled !== 'boolean' ||
+            typeof cap.baseSponsorship !== 'boolean' ||
+            typeof cap.acceptingNewBasePayments !== 'boolean')
+            throw error('relayer_unavailable');
+        if (cap.disabled || !cap.baseSponsorship || !cap.acceptingNewBasePayments)
+            throw error('relayer_unavailable', retryAfterSeconds ?? 5);
+        const v = await request('/v1/base-eligibility', {
+            fileId: t.file_id,
+            termsHash: o.file.termsHash,
+        });
+        if (v.network !== d.network ||
+            v.contract !== d.contractId ||
+            v.fileId !== t.file_id ||
+            v.termsHash !== o.file.termsHash ||
+            typeof v.eligible !== 'boolean')
+            throw error('relayer_unavailable');
+        if (!v.eligible)
+            throw error('not_sponsored');
+        if (!['listed', 'pool', 'legacy', 'external'].includes(String(v.tier)) ||
+            typeof v.policyVersion !== 'string' ||
+            !v.policyVersion ||
+            !uint(v.minPrice) ||
+            !v.fee ||
+            typeof v.fee !== 'object' ||
+            !fresh(v.checkedAt, nowOf(o)) ||
+            !Number.isSafeInteger(v.decidedAt) ||
+            v.decidedAt < 0 ||
+            v.decidedAt > v.checkedAt)
+            throw error('relayer_unavailable');
+        const fee = v.fee;
+        if (!uint(fee.fixed) ||
+            !Number.isSafeInteger(fee.bps) ||
+            fee.bps < 0 ||
+            fee.bps > 10000 ||
+            !Object.hasOwn(fee, 'treasuryNear') ||
+            !Object.hasOwn(fee, 'treasuryEvm'))
+            throw error('relayer_unavailable');
+        try {
+            if (!t.base || BigInt(t.base.price) < BigInt(v.minPrice))
+                throw new Error();
+            checkProtocolFee(t, fee);
+        }
+        catch {
+            throw error('not_sponsored');
+        }
+        await checkBaseSplit(o.file, o.baseRpc);
+        const checked = {
+            network: d.network,
+            contract: d.contractId,
+            fileId: t.file_id,
+            termsHash: o.file.termsHash,
+            eligible: true,
+            tier: v.tier,
+            policyVersion: v.policyVersion,
+            minPrice: v.minPrice,
+            fee: {
+                fixed: fee.fixed,
+                bps: fee.bps,
+                treasuryNear: fee.treasuryNear === null ? null : parseIdentity(fee.treasuryNear),
+                treasuryEvm: fee.treasuryEvm === null ? null : parseIdentity(fee.treasuryEvm),
+            },
+            decidedAt: v.decidedAt,
+            checkedAt: v.checkedAt,
+            splitCheckedAt: nowOf(o),
+        };
+        if (!fresh(checked.checkedAt, nowOf(o)))
+            throw error('relayer_unavailable');
+        issued.set(checked, { binding: binding(o), value: JSON.stringify(checked) });
+        return checked;
+    }
+    catch (e) {
+        if (e &&
+            typeof e === 'object' &&
+            'code' in e &&
+            ['not_sponsored', 'relayer_unavailable', 'network_mismatch'].includes(String(e.code)))
+            throw e;
+        throw error('relayer_unavailable', retryAfterSeconds);
+    }
+}

package/dist/relay/fees.d.ts

@@ -0,0 +1,17 @@
+import { type Identity } from '../settle-near/identity.js';
+import type { NearTerms, Terms } from '../settle-near/terms.js';
+export interface ProtocolFee {
+    fixed: string;
+    bps: number;
+    treasuryNear: Identity | null;
+    treasuryEvm: Identity | null;
+}
+export declare function requiredFeeBps(price: string, fee: Pick<ProtocolFee, 'fixed' | 'bps'>): number;
+/** Base terms use one EVM treasury share satisfying the larger route requirement. */
+export declare function applySponsoredFee(near: NearTerms, fee: ProtocolFee, basePrice?: string): NearTerms;
+export declare const DEFAULT_MAX_PROTOCOL_FEE: Readonly<{
+    fixed: "30000";
+    bps: 100;
+}>;
+export declare function protocolFeeAboveMax(price: string, fee: Pick<ProtocolFee, 'fixed' | 'bps'>, max?: Pick<ProtocolFee, 'fixed' | 'bps'>): boolean;
+export declare function checkProtocolFee(terms: Terms, fee: ProtocolFee): void;

package/dist/relay/fees.js

@@ -0,0 +1,105 @@
+/** Public sponsorship policy. Amounts use USDC base units, arithmetic stays integer-only. */
+import { compare } from '../settle-near/codec.js';
+import { encodeIdentity, identityJson, parseIdentity, } from '../settle-near/identity.js';
+export function requiredFeeBps(price, fee) {
+    if (!/^(0|[1-9][0-9]*)$/.test(fee.fixed) ||
+        !Number.isSafeInteger(fee.bps) ||
+        fee.bps < 0 ||
+        fee.bps > 10000)
+        throw new TypeError('invalid protocol fee');
+    const p = BigInt(price);
+    if (p <= 0n)
+        throw new TypeError('positive price required');
+    const n = (BigInt(fee.fixed) * 10000n + p * BigInt(fee.bps) + p - 1n) / p;
+    if (n >= 10000n)
+        throw new TypeError('protocol fee leaves no seller share');
+    return Number(n);
+}
+function allocate(near, requests) {
+    const required = new Map();
+    for (const request of requests) {
+        if (!request.bps)
+            continue;
+        if (!request.identity)
+            throw new TypeError('sponsorship treasury unavailable');
+        const identity = parseIdentity(request.identity);
+        const key = identityJson(identity);
+        const existing = near.recipients.find((r) => identityJson(r.identity) === key)?.bps ?? 0;
+        required.set(key, {
+            identity,
+            bps: Math.max(existing, request.bps, required.get(key)?.bps ?? 0),
+        });
+    }
+    if (!required.size ||
+        [...required].every(([key, r]) => near.recipients.some((old) => identityJson(old.identity) === key && old.bps >= r.bps))) {
+        const unchanged = structuredClone(near);
+        const remainder = near.recipients[near.remainder];
+        if (remainder && required.has(identityJson(remainder.identity))) {
+            const seller = near.recipients.findIndex((r) => !required.has(identityJson(r.identity)));
+            if (seller >= 0)
+                unchanged.remainder = seller;
+        }
+        return unchanged;
+    }
+    const originalRemainder = near.recipients[near.remainder]?.identity;
+    const others = near.recipients.filter((r) => !required.has(identityJson(r.identity)));
+    const fixed = [...required.values()];
+    const available = 10000 - fixed.reduce((n, r) => n + r.bps, 0);
+    const total = others.reduce((n, r) => n + r.bps, 0);
+    if (!others.length || available <= 0 || others.length + fixed.length > 8)
+        throw new TypeError('fee requires seller share and one of eight recipient slots');
+    const recipients = others.map((r) => ({ ...r, bps: Math.floor((r.bps * available) / total) }));
+    recipients.push(...fixed);
+    const rounding = recipients.find((r) => originalRemainder &&
+        !required.has(identityJson(r.identity)) &&
+        identityJson(r.identity) === identityJson(originalRemainder)) ?? recipients[0];
+    if (!rounding)
+        throw new TypeError('seller recipient required');
+    rounding.bps += 10000 - recipients.reduce((n, r) => n + r.bps, 0);
+    if (recipients.some((r) => r.bps <= 0))
+        throw new TypeError('fee rounds a recipient to zero');
+    recipients.sort((a, b) => compare(encodeIdentity(a.identity), encodeIdentity(b.identity)));
+    return { ...near, recipients, remainder: recipients.indexOf(rounding) };
+}
+/** Base terms use one EVM treasury share satisfying the larger route requirement. */
+export function applySponsoredFee(near, fee, basePrice) {
+    if (basePrice && fee.treasuryEvm?.kind !== 'evm')
+        throw new TypeError('EVM treasury required');
+    return allocate(near, [
+        {
+            identity: basePrice ? fee.treasuryEvm : (fee.treasuryNear ?? fee.treasuryEvm),
+            bps: Math.max(requiredFeeBps(near.price, fee), basePrice ? requiredFeeBps(basePrice, fee) : 0),
+        },
+    ]);
+}
+export const DEFAULT_MAX_PROTOCOL_FEE = Object.freeze({ fixed: '30000', bps: 100 });
+export function protocolFeeAboveMax(price, fee, max = DEFAULT_MAX_PROTOCOL_FEE) {
+    for (const value of [fee, max]) {
+        if (!/^(0|[1-9][0-9]*)$/.test(value.fixed) ||
+            !Number.isSafeInteger(value.bps) ||
+            value.bps < 0 ||
+            value.bps > 10000)
+            throw new TypeError('invalid protocol fee');
+    }
+    const p = BigInt(price);
+    if (p <= 0n)
+        throw new TypeError('positive price required');
+    return (BigInt(fee.fixed) * 10000n + p * BigInt(fee.bps) >
+        BigInt(max.fixed) * 10000n + p * BigInt(max.bps));
+}
+export function checkProtocolFee(terms, fee) {
+    const check = (price, treasury) => {
+        const required = requiredFeeBps(price, fee);
+        if (!required)
+            return;
+        if (!treasury ||
+            !terms.near.recipients.some((r) => identityJson(r.identity) === identityJson(treasury) && r.bps >= required))
+            throw new TypeError('required treasury share missing');
+    };
+    check(terms.near.price, terms.base ? fee.treasuryEvm : (fee.treasuryNear ?? fee.treasuryEvm));
+    if (terms.base) {
+        if (fee.treasuryEvm?.kind !== 'evm' && requiredFeeBps(terms.base.price, fee))
+            throw new TypeError('EVM treasury required');
+        check(terms.base.price, fee.treasuryEvm);
+    }
+}

package/dist/relay/index.d.ts

@@ -0,0 +1,10 @@
+/** Service entrypoint for relayer admission, durable sponsorship and settlement. */
+export { clientKey } from '../net/ip.js';
+export { NEAR_USDC } from '../settle-near/terms.js';
+export { checkProtocolFee, type ProtocolFee } from './fees.js';
+export { keeperBalance } from './keeper-balance.js';
+export type { KeeperRecord, KeepOptions, KeepResult, RefundSource } from './keeper-runner.js';
+export { type Admission, type Cutover, RelayLedger, type RelayLimits, type RelayOperation, type RelayState, requestHash, type SponsorshipDecision, } from './ledger.js';
+export { type CheckOptions, deferPaidUnlock, keep, RelayError, type RelayErrorCode, type RelayPolicy, type RelayRequest, type RelayResult, reconcileRelayStorage, relay, relayStatus, retryPaidUnlocks, type Sender, } from './relay.js';
+export type { HostingReservation } from './reservation.js';
+export { baseEligibility, relayLimits, ZERO_FEE } from './sponsorship.js';

package/dist/relay/index.js

@@ -0,0 +1,8 @@
+/** Service entrypoint for relayer admission, durable sponsorship and settlement. */
+export { clientKey } from '../net/ip.js';
+export { NEAR_USDC } from '../settle-near/terms.js';
+export { checkProtocolFee } from './fees.js';
+export { keeperBalance } from './keeper-balance.js';
+export { RelayLedger, requestHash, } from './ledger.js';
+export { deferPaidUnlock, keep, RelayError, reconcileRelayStorage, relay, relayStatus, retryPaidUnlocks, } from './relay.js';
+export { baseEligibility, relayLimits, ZERO_FEE } from './sponsorship.js';

package/dist/relay/keeper-balance.d.ts

@@ -0,0 +1,17 @@
+/** Price a single zero-deposit function call, before signing, at one finalized block.
+ * NEP-642: send fees burn at block price; receipt gas is bought at the protocol minimum.
+ * https://near.github.io/nearcore/architecture/how/gas.html
+ */
+export declare function keeperBalance(o: {
+    nearRpc: string;
+    accountId: string;
+    contractId: string;
+    block: string;
+    gasPrice: bigint;
+    method: string;
+    args: object;
+    gas: bigint;
+}): Promise<{
+    balance: bigint;
+    cost: bigint;
+}>;

package/dist/relay/keeper-balance.js

@@ -0,0 +1,46 @@
+import { rpcReply } from '../near/rpc.js';
+const object = (v) => {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        throw new Error('keeper balance/protocol data unavailable');
+    return v;
+};
+const integer = (v) => {
+    if (!((typeof v === 'string' && /^(0|[1-9][0-9]*)$/.test(v)) ||
+        (typeof v === 'number' && Number.isSafeInteger(v) && v >= 0)))
+        throw new Error('invalid keeper balance/protocol integer');
+    return BigInt(v);
+};
+/** Price a single zero-deposit function call, before signing, at one finalized block.
+ * NEP-642: send fees burn at block price; receipt gas is bought at the protocol minimum.
+ * https://near.github.io/nearcore/architecture/how/gas.html
+ */
+export async function keeperBalance(o) {
+    const [account, protocol] = await Promise.all([
+        rpcReply(o.nearRpc, 'query', {
+            request_type: 'view_account',
+            block_id: o.block,
+            account_id: o.accountId,
+        }),
+        rpcReply(o.nearRpc, 'EXPERIMENTAL_protocol_config', { block_id: o.block }),
+    ]);
+    if (account.error || protocol.error)
+        throw new Error('final keeper balance/protocol unavailable');
+    const a = object(account.result);
+    const runtime = object(object(protocol.result).runtime_config);
+    const fees = object(runtime.transaction_costs);
+    const actions = object(fees.action_creation_config);
+    const receipt = object(fees.action_receipt_creation_config);
+    const call = object(actions.function_call_cost);
+    const byte = object(actions.function_call_cost_per_byte);
+    const size = BigInt(new TextEncoder().encode(o.method + JSON.stringify(o.args)).length);
+    const send = o.accountId === o.contractId ? 'send_sir' : 'send_not_sir';
+    const sendGas = integer(receipt[send]) + integer(call[send]) + size * integer(byte[send]);
+    const receiptGas = o.gas + integer(receipt.execution) + integer(call.execution) + size * integer(byte.execution);
+    const minPrice = integer(runtime.min_gas_purchase_price);
+    const cost = sendGas * o.gasPrice + receiptGas * (minPrice > o.gasPrice ? minPrice : o.gasPrice);
+    const amount = integer(a.amount), locked = integer(a.locked), usage = integer(a.storage_usage);
+    // NEP-448 permits accounts using at most 770 bytes to have zero storage stake.
+    const stake = usage <= 770n ? 0n : usage * integer(runtime.storage_amount_per_byte);
+    const held = stake > locked ? stake - locked : 0n;
+    return { cost, balance: amount > held ? amount - held : 0n };
+}

package/dist/relay/keeper-runner.d.ts

@@ -0,0 +1,114 @@
+import { type BudgetRecord, type SpendReservation } from '../node/budget.js';
+import type { Store, Versioned } from '../pay/store.js';
+import { type MaterializeRefundArgs } from './keeper.js';
+import type { RelayResult, Sender } from './relay.js';
+export interface KeeperRecord extends Versioned {
+    handled?: string;
+    tries?: number;
+    nextAt?: number;
+    observed?: {
+        funded: string;
+        paid: number[];
+    };
+    stage?: 'ready' | 'preparing' | 'finalizing' | 'submitted' | 'retired';
+    active?: {
+        id: string;
+        deliveryId: number;
+    }[];
+    tx?: {
+        hash: string;
+        signer: string;
+        signed: string;
+        method: 'settle' | 'materialize_refund';
+        args: object;
+        phases: string[];
+        /** Persist before broadcast, so expiry remains provable after RPC block garbage collection. */
+        reference?: {
+            hash: string;
+            height: number;
+        };
+        reservation?: SpendReservation;
+        storageReserved?: string;
+    } | null;
+    sweep?: {
+        block: string;
+        count: number;
+        from: number;
+    };
+    balanceLow?: boolean;
+    reserveCheckedAt?: number;
+    inFlightAlerted?: boolean;
+    uncertainAlerted?: boolean;
+    belowMinimum?: boolean;
+    firstSeenAt?: number;
+    oldDeliveryAlerted?: boolean;
+}
+export interface RefundSource {
+    /** Supply current proofs from durable event history. No indexer is bundled. Retry stale proofs. */
+    leaves(context: {
+        nearRpc: string;
+        contractId: string;
+        limit: number;
+    }): Promise<MaterializeRefundArgs[]>;
+}
+export interface KeepOptions {
+    nearRpc: string;
+    /** Stable chain identity, independent of the RPC provider. */
+    network: string;
+    contractId: string;
+    sender: Sender;
+    store: Store<KeeperRecord>;
+    budgetStore: Store<BudgetRecord>;
+    hourlyBudget: bigint;
+    dailyBudget: bigint;
+    /** Maximum yoctoNEAR per gas unit. Refuse if current finalized gas price exceeds this. */
+    gasPrice: bigint;
+    /** USDC base units; refunds bypass this minimum. */
+    minPayout?: bigint;
+    oldestDeliverySeconds?: number;
+    maxPages?: number;
+    maxTransactions?: number;
+    maxUnresolved?: number;
+    storagePerRefund?: bigint;
+    reserveLowWater?: bigint;
+    /** Minimum liquid yoctoNEAR before signing; requires max(this, submission cost). */
+    balanceLowWater?: bigint;
+    alert?: (alert: {
+        type: 'reserve_low' | 'in_flight' | 'uncertain' | 'breaker' | 'low_balance' | 'old_delivery';
+        balance?: string;
+        needed?: string;
+        reserve?: string;
+        deliveryId?: number;
+        seconds?: number;
+    }) => void;
+    refunds?: RefundSource;
+    now?: () => number;
+    jitter?: () => number;
+}
+export interface KeepResult {
+    sent: {
+        method: 'settle' | 'materialize_refund';
+        args: object;
+        result: RelayResult;
+    }[];
+    errors: {
+        from?: number;
+        deliveryId?: number;
+        error: unknown;
+    }[];
+    incidents: {
+        classification: 'budget' | 'transport' | 'finalized_failure' | 'in_flight' | 'uncertain' | 'rejected';
+        deliveryId?: number;
+        reason?: string;
+    }[];
+}
+export declare function retryDelay(tries: number, jitter?: number): number;
+interface Transport {
+    sign(method: string, args: object, gas: bigint): Promise<{
+        txHash: string;
+        signed: string;
+    }>;
+    send(hash: string, signed: string): Promise<RelayResult>;
+}
+export declare function runKeeper(o: KeepOptions, transport: Transport): Promise<KeepResult>;
+export {};