@floatonnear/float-adapter 0.0.0-stage → 0.1.1

package/dist/gate.js

@@ -0,0 +1,139 @@
+/**
+ * The HTTP gate: where to bind, who may POST, and which origin may ask.
+ *
+ * This layer had no tests, which is why it shipped open. Proven by PoC on
+ * 2026-10-29 against the running adapter (see docs/SELF-REVIEW-2026-10-29.md):
+ *
+ *   - `server.listen(port)` with no host bound `0.0.0.0` AND `[::]` — every
+ *     interface, v4 and v6 — while the startup log claimed `127.0.0.1`.
+ *   - An OPTIONS preflight carrying `Origin: https://evil.example` returned
+ *     `204` with `access-control-allow-origin: *`, so a browser proceeds to the
+ *     real request.
+ *   - `POST /v1/pay` returned `400`, not `401`: it reached body validation
+ *     because there was no auth gate to fail at. That route signs with the
+ *     agent key.
+ *
+ * Split out from server.ts so each decision is a pure function with a test,
+ * rather than three lines buried in a request handler where nothing could see
+ * them.
+ */
+import { timingSafeEqual } from "node:crypto";
+/**
+ * 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 function resolveHost(host) {
+    return host && host.trim() ? host.trim() : "127.0.0.1";
+}
+/**
+ * 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 function corsHeaders(allowedOrigin, requestOrigin) {
+    const base = {
+        "access-control-allow-headers": "content-type, authorization",
+        "access-control-allow-methods": "GET, POST, OPTIONS",
+        vary: "Origin",
+    };
+    if (requestOrigin && requestOrigin === allowedOrigin) {
+        base["access-control-allow-origin"] = requestOrigin;
+    }
+    return base;
+}
+/**
+ * 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 function authorize({ method, authHeader, token, }) {
+    if (method === "GET" || method === "OPTIONS" || method === "HEAD")
+        return { ok: true };
+    if (!token) {
+        return {
+            ok: false,
+            status: 503,
+            error: "this route signs with the agent key and is disabled until FLOAT_API_TOKEN is set. " +
+                "Set it in .float/adapter.env and send it as `Authorization: Bearer <token>`.",
+        };
+    }
+    const prefix = "Bearer ";
+    if (!authHeader || !authHeader.startsWith(prefix)) {
+        return { ok: false, status: 401, error: "missing bearer token" };
+    }
+    const provided = authHeader.slice(prefix.length);
+    // Length check first — timingSafeEqual throws on a length mismatch, and the
+    // length of a secret is not the part worth hiding.
+    if (provided.length !== token.length) {
+        return { ok: false, status: 401, error: "invalid token" };
+    }
+    const a = Buffer.from(provided);
+    const b = Buffer.from(token);
+    if (!timingSafeEqual(a, b)) {
+        return { ok: false, status: 401, error: "invalid token" };
+    }
+    return { ok: true };
+}
+/**
+ * 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 class BadRequest extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BadRequest";
+    }
+}
+/**
+ * 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 function classifyError(e) {
+    if (e instanceof BadRequest)
+        return { status: 400, body: { error: e.message } };
+    const message = e instanceof Error ? e.message : "internal error";
+    return { status: 500, body: { error: message } };
+}
+/**
+ * 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 function fromCaller(fn) {
+    try {
+        return fn();
+    }
+    catch (e) {
+        throw new BadRequest(e instanceof Error ? e.message : String(e));
+    }
+}

package/dist/handlers.d.ts

@@ -0,0 +1,210 @@
+/**
+ * The /v1 endpoints the existing Float dashboard already calls, served from
+ * NEAR vault views.
+ *
+ * `view` is injected so every handler is testable without a chain — the
+ * mapping and the shape of what the UI receives are exactly where a silent
+ * wrong-but-plausible number would come from.
+ */
+import { type ApiAgent, type Payment, type VaultOutcome } from "./map.js";
+export type ViewFn = <T>(method: string, args?: unknown) => Promise<T>;
+/** What the relayer recorded about a Base delivery. */
+export interface DeliveryRecord {
+    mode: "vault" | "operator";
+    baseTxHash: string;
+    payee: string;
+    amount: string;
+    at: string;
+}
+export interface AdapterConfig {
+    token: string;
+    decimals: number;
+    /**
+     * Base deliveries, keyed by request id, as the relayer recorded them.
+     *
+     * OFF-CHAIN ON PURPOSE. The NEAR budget already moved when the vault signed;
+     * delivery on Base is something an operator observed, not something the
+     * contract can attest. Keeping it in a separate map means a missing or lying
+     * ledger can only ever UNDERSTATE delivery — it can never invent budget or
+     * contradict the chain.
+     */
+    deliveries?: Record<string, DeliveryRecord>;
+    /** Bounded, in-memory. See `recordBlocked`. */
+    blockedRing: Payment[];
+    maxBlocked: number;
+    /**
+     * Refusals recovered FROM CHAIN by scripts/scan-blocked.mjs, keyed by
+     * request id.
+     *
+     * The in-memory ring above only held refusals this process personally
+     * witnessed, so the most important thing the vault does — refusing a payment
+     * because a SHARED pool is empty — vanished on restart and was invisible for
+     * any payment made by another client. A refused request is deliberately not
+     * stored in contract state (that is the storage griefing vector of §2), but
+     * the NEP-297 event survives in the receipt and can be read back. These rows
+     * carry a tx hash and are therefore independently checkable. The ring's are
+     * not.
+     */
+    chainBlocked?: Record<string, ChainBlocked>;
+    /**
+     * The block range the scanner has actually covered. Without it, "no
+     * refusals happened" and "we have not looked there" render identically —
+     * which is the confusion this feature exists to remove.
+     */
+    blockedScan?: {
+        from: number;
+        to: number;
+        /** Spans inside from..to that were never read. Unknown, not empty. */
+        holes?: Array<{
+            from: number;
+            to: number;
+        }>;
+    } | null;
+}
+/** One refusal, as recovered from a receipt outcome. */
+export interface ChainBlocked {
+    requestId: string;
+    nodeId: number;
+    reasonCode: string;
+    agent: string;
+    txHash: string;
+    blockHeight: number;
+    blockTimestampNs: string | number;
+}
+/**
+ * Blocked attempts are NOT stored on-chain — the hot path returns them as a
+ * value and emits an event, deliberately, so an agent cannot grow the vault's
+ * storage bill by spamming rejects.
+ *
+ * So the adapter remembers the ones it SEES, in a bounded in-memory ring. That
+ * covers blocks made through this product, which is what the dashboard is
+ * showing. Blocks made by another client, or before this process started, are
+ * not here and cannot be — the dashboard says so rather than implying none
+ * happened.
+ */
+/**
+ * Chain-recovered refusals as Payment rows.
+ *
+ * Deduped against the in-memory ring by request id, preferring the chain copy
+ * — it is the one that carries a tx hash a reader can check for themselves.
+ */
+export declare function chainBlockedPayments(cfg: AdapterConfig, nodeLabels: Record<number, string>): Payment[];
+export declare function recordBlocked(cfg: AdapterConfig, p: Payment): void;
+/** Where this vault lives, so the UI never has to hardcode a chain. */
+export interface VaultInfo {
+    vaultId: string;
+    tokenId: string;
+    tokenDecimals: number;
+    network: string;
+    /** NEAR Explorer base for the network the vault is actually on. */
+    explorerBase: string;
+    owner: string;
+    paused: boolean;
+    clockMode: string;
+    strictAllocation: boolean;
+    /**
+     * The vault's ACTUAL NEP-141 balance, base units.
+     *
+     * Deliberately separate from `treasury.amount` on /v1/dashboard, which is the
+     * root node's remaining DAILY BUDGET. They are different quantities and the
+     * funding page needs this one: fund 10,000 USDC against a 100/day root cap
+     * and the budget figure still reads 40, which would look like the deposit
+     * never arrived. Null when the token contract cannot be read.
+     */
+    vaultTokenBalance: string | null;
+}
+/**
+ * `near` / `testnet` / anything else. Derived from the network the contract
+ * reports rather than from an env var, so a UI pointed at testnet cannot link
+ * to a mainnet explorer and show "not found".
+ */
+export declare function explorerBaseFor(network: string): string;
+/** A view against an arbitrary contract — the token, not the vault. */
+export type ViewOnFn = (contractId: string, method: string, args?: unknown) => Promise<string | null>;
+export declare function getVaultInfo(view: ViewFn, cfg: AdapterConfig, viewOn: ViewOnFn): Promise<VaultInfo>;
+export interface AgentKeyView {
+    accountId: string;
+    nodeId: number;
+    label: string;
+    frozen: boolean;
+    keys: {
+        publicKey: string;
+        /** True only if the key really is a function-call key. */
+        restricted: boolean;
+        receiverId: string | null;
+        methodNames: string[];
+        allowanceYocto: string | null;
+    }[];
+    /** Set when the key list could not be read, so the UI can say so. */
+    error?: string;
+}
+export type KeyFn = (accountId: string) => Promise<{
+    public_key: string;
+    access_key: {
+        permission: "FullAccess" | {
+            FunctionCall: {
+                allowance: string | null;
+                receiver_id: string;
+                method_names: string[];
+            };
+        };
+    };
+}[]>;
+/**
+ * The bound agent accounts, with their access keys read FROM THE CHAIN.
+ *
+ * The restriction is the product's central security claim, so the page that
+ * states it must not state it from a constant. A hardcoded "restricted to
+ * request_payment" would keep rendering happily if someone added a full-access
+ * key to an agent account — exactly the regression a reader of that page is
+ * trying to rule out. `restricted` here is computed from the permission NEAR
+ * reports, and a FullAccess key makes it false.
+ */
+export declare function getAgentKeys(view: ViewFn, keys: KeyFn, _cfg: AdapterConfig): Promise<AgentKeyView[]>;
+export declare function getDashboard(view: ViewFn, cfg: AdapterConfig): Promise<{
+    owner: {
+        authMethod: string;
+        walletAddress: string;
+        displayName: string;
+    };
+    treasury: {
+        ownerId: string;
+        walletAddress: string;
+        createdAt: string;
+        amount: string;
+        currency: string;
+        decimals: number;
+    };
+    agents: ApiAgent[];
+    blockedCoverage: {
+        from: number;
+        to: number;
+        /** Spans inside from..to that were never read. Unknown, not empty. */
+        holes?: Array<{
+            from: number;
+            to: number;
+        }>;
+    } | null | undefined;
+    transactionStats: {
+        total: number;
+        approved: number;
+        blocked: number;
+        failed: number;
+        other: number;
+    };
+    recentActivity: {
+        id: string;
+        agent: string;
+        venue: string;
+        amount: string;
+        rail: string;
+        time: string;
+        status: string;
+    }[];
+    paused: boolean;
+}>;
+export declare function getSpendHistory(view: ViewFn, cfg: AdapterConfig, limit: number, offset: number): Promise<{
+    payments: Payment[];
+}>;
+/** Called by the pay endpoint so a block the product caused shows up as a row. */
+export declare function paymentFromOutcome(cfg: AdapterConfig, outcome: VaultOutcome, labels: Record<number, string>, amountHuman: string, recipient: string): Payment | null;

package/dist/handlers.js

@@ -0,0 +1,246 @@
+/**
+ * The /v1 endpoints the existing Float dashboard already calls, served from
+ * NEAR vault views.
+ *
+ * `view` is injected so every handler is testable without a chain — the
+ * mapping and the shape of what the UI receives are exactly where a silent
+ * wrong-but-plausible number would come from.
+ */
+import { blockedToPayment, lifetimeByNode, requestToPayment, REASONS, treeToApiAgents, } from "./map.js";
+/**
+ * Blocked attempts are NOT stored on-chain — the hot path returns them as a
+ * value and emits an event, deliberately, so an agent cannot grow the vault's
+ * storage bill by spamming rejects.
+ *
+ * So the adapter remembers the ones it SEES, in a bounded in-memory ring. That
+ * covers blocks made through this product, which is what the dashboard is
+ * showing. Blocks made by another client, or before this process started, are
+ * not here and cannot be — the dashboard says so rather than implying none
+ * happened.
+ */
+/**
+ * Chain-recovered refusals as Payment rows.
+ *
+ * Deduped against the in-memory ring by request id, preferring the chain copy
+ * — it is the one that carries a tx hash a reader can check for themselves.
+ */
+export function chainBlockedPayments(cfg, nodeLabels) {
+    const seen = new Set(cfg.blockedRing.map((p) => p.id));
+    return Object.values(cfg.chainBlocked ?? {})
+        .filter((b) => !seen.has(b.requestId))
+        .map((b) => ({
+        id: b.requestId,
+        agentId: String(b.nodeId),
+        agentName: nodeLabels[b.nodeId] ?? `node-${b.nodeId}`,
+        // The amount is NOT in the event, and inventing one would be worse than
+        // showing none: a refused payment moved nothing, and a plausible figure
+        // would read as fact.
+        amount: "0",
+        currency: "USDC",
+        recipientAddress: "",
+        venue: "",
+        rail: "policy",
+        status: "blocked",
+        txSignature: b.txHash,
+        createdAt: new Date(Number(BigInt(b.blockTimestampNs) / 1000000n)).toISOString(),
+        blockReason: b.reasonCode,
+        blockMessage: REASONS[b.reasonCode] ?? b.reasonCode,
+        prompt: null,
+        resultUrl: null,
+    }));
+}
+export function recordBlocked(cfg, p) {
+    cfg.blockedRing.unshift(p);
+    if (cfg.blockedRing.length > cfg.maxBlocked)
+        cfg.blockedRing.length = cfg.maxBlocked;
+}
+async function loadTreeAndUsage(view, cfg) {
+    const tree = await view("get_tree", {});
+    const budgets = new Map();
+    const labels = {};
+    // CONCURRENT, not sequential. One view per node is bounded by MAX_NODES (64),
+    // but issuing them in series costs a full testnet round-trip EACH: measured
+    // at 30s for a five-node tree, which is not a dashboard, it is a progress
+    // bar. Only `get_tree` is a real dependency; the per-node budgets depend on
+    // nothing but it. Pinned by the concurrency test in handlers.test.ts.
+    for (const n of tree)
+        labels[n.id] = n.label;
+    const fetched = await Promise.all(tree.map((n) => view("get_node_budget", {
+        node_id: n.id,
+        token: cfg.token,
+        day: null,
+    })));
+    tree.forEach((n, i) => {
+        const b = fetched[i];
+        budgets.set(n.id, b ? { executed: b.executed, pending: b.pending } : { executed: "0", pending: "0" });
+    });
+    return { tree, budgets, labels };
+}
+/**
+ * `near` / `testnet` / anything else. Derived from the network the contract
+ * reports rather than from an env var, so a UI pointed at testnet cannot link
+ * to a mainnet explorer and show "not found".
+ */
+export function explorerBaseFor(network) {
+    return network === "mainnet" || network === "near"
+        ? "https://nearblocks.io"
+        : "https://testnet.nearblocks.io";
+}
+export async function getVaultInfo(view, cfg, viewOn) {
+    // `get_base_config` used to be read here alongside `get_config`. The
+    // MPC/Base rail and its config were removed from the contract on
+    // 2026-10-28, so there is no method left to call and no rail to report.
+    const c = await view("get_config", {});
+    // Read off the TOKEN contract, not the vault — so it is the real balance and
+    // not an echo of the vault's own bookkeeping. Null rather than "0" on
+    // failure: zero would read as "the deposit is not here", which is a
+    // different claim from "we could not look".
+    const vaultTokenBalance = await viewOn(cfg.token, "ft_balance_of", {
+        account_id: c.vault_id,
+    }).catch(() => null);
+    return {
+        vaultId: c.vault_id,
+        tokenId: cfg.token,
+        tokenDecimals: cfg.decimals,
+        network: c.network,
+        explorerBase: explorerBaseFor(c.network),
+        owner: c.owner,
+        paused: c.paused,
+        clockMode: c.clock_mode,
+        strictAllocation: c.strict_allocation,
+        vaultTokenBalance,
+    };
+}
+/**
+ * The bound agent accounts, with their access keys read FROM THE CHAIN.
+ *
+ * The restriction is the product's central security claim, so the page that
+ * states it must not state it from a constant. A hardcoded "restricted to
+ * request_payment" would keep rendering happily if someone added a full-access
+ * key to an agent account — exactly the regression a reader of that page is
+ * trying to rule out. `restricted` here is computed from the permission NEAR
+ * reports, and a FullAccess key makes it false.
+ */
+export async function getAgentKeys(view, keys, _cfg) {
+    const tree = await view("get_tree", {});
+    const bound = tree.filter((n) => n.account);
+    return Promise.all(bound.map(async (n) => {
+        const base = {
+            accountId: n.account,
+            nodeId: n.id,
+            label: n.label,
+            frozen: n.frozen,
+        };
+        try {
+            const list = await keys(n.account);
+            return {
+                ...base,
+                keys: list.map((k) => {
+                    const p = k.access_key.permission;
+                    const fc = typeof p === "object" && "FunctionCall" in p ? p.FunctionCall : null;
+                    return {
+                        publicKey: k.public_key,
+                        restricted: fc !== null,
+                        receiverId: fc?.receiver_id ?? null,
+                        methodNames: fc?.method_names ?? [],
+                        allowanceYocto: fc?.allowance ?? null,
+                    };
+                }),
+            };
+        }
+        catch (e) {
+            // An unreadable key list is reported, never silently rendered as "no
+            // keys" — that would read as "nothing is authorised here", the
+            // opposite of unknown.
+            return { ...base, keys: [], error: e instanceof Error ? e.message : String(e) };
+        }
+    }));
+}
+export async function getDashboard(view, cfg) {
+    const { tree, budgets, labels } = await loadTreeAndUsage(view, cfg);
+    // Also concurrent: neither depends on the other.
+    const [requests, cfgView] = await Promise.all([
+        view("list_requests", { from_index: 0, limit: 20 }),
+        view("get_config", {}),
+    ]);
+    const agents = treeToApiAgents(tree, budgets, cfg.decimals, lifetimeByNode(requests));
+    const onchain = requests.map((r) => requestToPayment(r, labels, cfg.decimals, cfg.deliveries?.[r.request_id]));
+    const recent = [...chainBlockedPayments(cfg, labels), ...cfg.blockedRing, ...onchain]
+        .sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1))
+        .slice(0, 20);
+    const root = tree.find((n) => n.parent === null);
+    const rootUsage = root ? budgets.get(root.id) : undefined;
+    return {
+        owner: { authMethod: "wallet", walletAddress: cfgView.owner, displayName: cfgView.owner },
+        treasury: {
+            ownerId: cfgView.owner,
+            walletAddress: cfgView.vault_id,
+            createdAt: new Date(0).toISOString(),
+            // The vault holds the tokens; the figure the dashboard cares about is
+            // how much of the ROOT budget is still available today.
+            amount: root?.limits[0]
+                ? (BigInt(root.limits[0].daily_cap) -
+                    BigInt(rootUsage?.executed ?? "0") -
+                    BigInt(rootUsage?.pending ?? "0")).toString()
+                : "0",
+            currency: "USDC",
+            decimals: cfg.decimals,
+        },
+        agents,
+        // What the refusal history actually covers. A UI that shows "0 blocked"
+        // without this cannot distinguish an honest zero from an unscanned range.
+        blockedCoverage: cfg.blockedScan,
+        transactionStats: {
+            total: onchain.length + cfg.blockedRing.length + Object.keys(cfg.chainBlocked ?? {}).length,
+            // The Base rail's terminal states count as approved. "success" alone was
+            // written when NEAR was the only rail; once Base payments report
+            // "signed"/"delivered" it rendered "4 transactions, 0 approved /
+            // 0 blocked" — every payment the vault had authorized vanished from the
+            // count. The UI's own list and this total disagreed on screen.
+            approved: onchain.filter((p) => ["success", "signed", "delivered"].includes(p.status)).length,
+            blocked: cfg.blockedRing.length + Object.keys(cfg.chainBlocked ?? {}).length,
+            failed: onchain.filter((p) => p.status === "failed").length,
+            other: onchain.filter((p) => p.status === "pending").length,
+        },
+        recentActivity: recent.map((p) => ({
+            id: p.id,
+            agent: p.agentName,
+            venue: p.venue,
+            amount: p.amount,
+            rail: p.rail,
+            time: p.createdAt,
+            status: p.status,
+        })),
+        paused: cfgView.paused,
+    };
+}
+export async function getSpendHistory(view, cfg, limit, offset) {
+    const tree = await view("get_tree", {});
+    const labels = {};
+    for (const n of tree)
+        labels[n.id] = n.label;
+    const requests = await view("list_requests", {
+        from_index: offset,
+        limit,
+    });
+    const onchain = requests.map((r) => requestToPayment(r, labels, cfg.decimals, cfg.deliveries?.[r.request_id]));
+    // Blocked rows only belong on the FIRST page: they are not part of the
+    // contract's paged list, so splicing them into later pages would duplicate
+    // them as the UI scrolls.
+    //
+    // Sorted by time rather than concatenated, because chain-recovered refusals
+    // can be older than the in-memory ones and a bare prepend would show them
+    // above newer activity.
+    const merged = offset === 0
+        ? [...chainBlockedPayments(cfg, labels), ...cfg.blockedRing, ...onchain].sort((a, b) => a.createdAt < b.createdAt ? 1 : -1)
+        : onchain;
+    return { payments: merged.slice(0, limit) };
+}
+/** Called by the pay endpoint so a block the product caused shows up as a row. */
+export function paymentFromOutcome(cfg, outcome, labels, amountHuman, recipient) {
+    if (outcome.status !== "BLOCKED")
+        return null;
+    const p = blockedToPayment(outcome, labels, amountHuman, recipient, new Date().toISOString());
+    recordBlocked(cfg, p);
+    return p;
+}

package/dist/keyring.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Which agent signs a payment.
+ *
+ * The adapter used to hold exactly one agent credential, in
+ * NEAR_VAULT_AGENT_ID / NEAR_VAULT_AGENT_KEY, and `POST /v1/pay` always signed
+ * as that agent. The dashboard meanwhile renders the whole tree. So a vault
+ * with sixteen agents showed sixteen rows and could act as one of them — and
+ * the sixteen-agent demo had to bypass the product entirely and drive the CLI
+ * instead.
+ *
+ * This matters more than it looks, because the contract resolves the spending
+ * node from the SIGNER (`account_to_node`), not from anything in the request
+ * body. Which key signs *is* which budget is charged. A single-key adapter
+ * cannot exercise a hierarchy at all; it can only ever spend one leaf.
+ *
+ * On holding several keys at once: each is the restricted key from
+ * `create_agent_account`, which can call only `request_payment` on its own
+ * vault, cannot call other contracts, and cannot attach a deposit. The vault
+ * enforces every cap regardless of who holds the key, so the blast radius of
+ * the whole keyring is bounded by the tree's own limits. That is the same
+ * bound as for one key, applied more times.
+ */
+export interface AgentCredential {
+    agentId: string;
+    secret: string;
+    /** Present when known; lets a caller select by node instead of account id. */
+    nodeId?: number;
+}
+export interface Keyring {
+    /** agent account id -> credential */
+    byAccount: Map<string, AgentCredential>;
+    /** node id -> credential */
+    byNode: Map<number, AgentCredential>;
+    /**
+     * Used when a request names no agent. Preserves the previous single-agent
+     * behaviour exactly, so existing deployments and the dashboard's own calls
+     * keep working untouched.
+     */
+    fallback?: AgentCredential;
+}
+export declare function emptyKeyring(): Keyring;
+/**
+ * Build a keyring from the singular env vars plus, optionally, the JSON file
+ * `create-float` writes at `.float/agent-keys.json`:
+ *
+ *   [{ "nodeId": 3, "agentId": "r1.float.me.testnet", "secret": "ed25519:..." }]
+ *
+ * The singular env pair stays authoritative for the fallback, so adding a file
+ * can never silently change which agent an un-targeted payment comes from.
+ */
+export declare function loadKeyring(env: {
+    agentId?: string;
+    agentKey?: string;
+    agentKeysPath?: string;
+}): Keyring;
+export declare class AgentSelectionError extends Error {
+}
+/**
+ * Pick the credential for a payment request.
+ *
+ * Errors name every agent that IS available. A selection failure is almost
+ * always a typo or a stale node id, and an error that says only "not found"
+ * costs the caller another round trip to discover what the valid options were.
+ */
+export declare function selectAgent(ring: Keyring, want?: {
+    agent?: string;
+    nodeId?: number;
+}): AgentCredential;