@floatonnear/mcp 0.3.0 → 0.5.0

package/dist/agent-key.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The node a creation-time agent is bound to.
+ *
+ * ONE, NOT ZERO, SINCE 2026-11-08. `new` used to bind at ROOT_NODE because it
+ * was the only node that existed — which left the FIRST agent holding the
+ * whole vault budget while every agent added later through `add_role` got a
+ * child of its own. The hierarchy only began constraining from agent #2.
+ *
+ * `new` now creates the agent its own child of root, carrying the same limits,
+ * exactly as `add_role` does. Root is 0 and that child is the first node
+ * inserted after it, so the agent is 1.
+ *
+ * PREDICTED, NOT READ, and that is unavoidable: the credential is generated
+ * before the vault exists, so there is nothing to ask. It is pinned by
+ * `binding_at_init_matches_binding_afterwards` in the contract, which asserts
+ * the node is 1 and not 0 — if `new` ever inserts another node first, that
+ * test fails rather than this constant drifting in silence.
+ */
+export declare const AGENT_NODE_ID = 1;
+export interface GeneratedAgentKey {
+    publicKey: string;
+    /** The role this credential was filed under, when one was given. */
+    role?: string;
+    /** Where the secret was written. The secret itself is deliberately absent. */
+    keyringPath: string;
+    envPath: string;
+    /** A prior keyring that was moved aside, if any. */
+    backedUpTo?: string;
+}
+/**
+ * Write the agent's credential where the adapter will actually find it.
+ *
+ * THE SHAPE MATTERS MORE THAN THE PATH. `loadKeyring` in
+ * packages/float-adapter/src/keyring.ts accepts an entry only when it has a
+ * string `agentId` and a string `secret`:
+ *
+ *     if (e && typeof e.agentId === "string" && typeof e.secret === "string")
+ *
+ * Anything else is skipped in silence — no warning, no error, the file simply
+ * contributes nothing. `float-agent.mjs` writes
+ * `{kind, vault, node, publicKey, privateKey}` into this same file, which that
+ * condition rejects on both counts. So the convenient-looking shape is the
+ * dead one, and this writes the shape that loads.
+ *
+ * `agentId` is the VAULT, not a separate account. A virtual agent has no
+ * account of its own: its key is a NEP-611 gas key installed ON the vault, so
+ * the account it signs as is the vault itself — which is also why
+ * `NEAR_VAULT_AGENT_ID` is set to a vault id in `.mcp.json`.
+ */
+export declare function generateAgentKey(opts: {
+    vault: string;
+    dir?: string;
+    /**
+     * The node this agent spends from.
+     *
+     * `null` means NOT YET KNOWN, and is written as an absent field rather
+     * than a guess. `add_role` creates the node inside the contract, so its id
+     * does not exist until the transaction lands — and a client cannot read
+     * one action's return value from the same transaction.
+     *
+     * A WRONG NODE ID IS WORSE THAN NONE. Defaulting to 0 filed the first
+     * `add_role` agent against the ROOT node while the contract had assigned
+     * it node 1: `byNode.get(1)` missed it entirely, and `byNode.get(0)`
+     * returned it under the root's name. Selection by role still worked, so
+     * nothing failed loudly. `loadKeyring` treats a missing `nodeId` as
+     * "selectable by role only", which is exactly the truth here.
+     *
+     * Omitted entirely still means ROOT, which is correct for the agent bound
+     * at vault creation — that one genuinely is node 0.
+     */
+    nodeId?: number | null;
+    /**
+     * A human name for this agent — "marketing", "news".
+     *
+     * THE ONLY UNIQUE IDENTIFIER once a vault has several agents. `agentId` is
+     * the account the key signs as, which for every virtual agent on one vault
+     * is the SAME vault, so a keyring indexed by it collapses them and the
+     * last one written silently wins.
+     */
+    role?: string;
+}): GeneratedAgentKey;
+/** Where the files would go, without creating anything. */
+export declare function agentKeyPaths(dir?: string): {
+    keyringPath: string;
+    envPath: string;
+    dir: string;
+};

package/dist/agent-key.js

@@ -0,0 +1,130 @@
+/**
+ * Generating and storing the agent's key for one-signature onboarding.
+ *
+ * This is the ONE place `vault_create` stops being keyless, and the departure
+ * is deliberate but narrow: the key generated here is the AGENT's, never the
+ * owner's. An agent key can call exactly `request_payment` on one vault, is
+ * bounded by the budget tree, and cannot attach a deposit — so the worst a
+ * leaked copy does is spend inside limits the owner already set. The owner's
+ * full-access key still never comes near this server.
+ *
+ * THE SECRET NEVER GOES TO THE CALLER. It is written to disk and only the
+ * public half is returned. That is not a style preference: this session's own
+ * transcript acquired one private key from a screenshot and another from a
+ * config dump, and a tool response is a transcript entry forever. The agent
+ * calling `vault_create` has filesystem access to the same machine, so a path
+ * is strictly more useful to it than a string anyway.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, chmodSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { KeyPair } from "near-api-js";
+/**
+ * The node a creation-time agent is bound to.
+ *
+ * ONE, NOT ZERO, SINCE 2026-11-08. `new` used to bind at ROOT_NODE because it
+ * was the only node that existed — which left the FIRST agent holding the
+ * whole vault budget while every agent added later through `add_role` got a
+ * child of its own. The hierarchy only began constraining from agent #2.
+ *
+ * `new` now creates the agent its own child of root, carrying the same limits,
+ * exactly as `add_role` does. Root is 0 and that child is the first node
+ * inserted after it, so the agent is 1.
+ *
+ * PREDICTED, NOT READ, and that is unavoidable: the credential is generated
+ * before the vault exists, so there is nothing to ask. It is pinned by
+ * `binding_at_init_matches_binding_afterwards` in the contract, which asserts
+ * the node is 1 and not 0 — if `new` ever inserts another node first, that
+ * test fails rather than this constant drifting in silence.
+ */
+export const AGENT_NODE_ID = 1;
+/**
+ * Write the agent's credential where the adapter will actually find it.
+ *
+ * THE SHAPE MATTERS MORE THAN THE PATH. `loadKeyring` in
+ * packages/float-adapter/src/keyring.ts accepts an entry only when it has a
+ * string `agentId` and a string `secret`:
+ *
+ *     if (e && typeof e.agentId === "string" && typeof e.secret === "string")
+ *
+ * Anything else is skipped in silence — no warning, no error, the file simply
+ * contributes nothing. `float-agent.mjs` writes
+ * `{kind, vault, node, publicKey, privateKey}` into this same file, which that
+ * condition rejects on both counts. So the convenient-looking shape is the
+ * dead one, and this writes the shape that loads.
+ *
+ * `agentId` is the VAULT, not a separate account. A virtual agent has no
+ * account of its own: its key is a NEP-611 gas key installed ON the vault, so
+ * the account it signs as is the vault itself — which is also why
+ * `NEAR_VAULT_AGENT_ID` is set to a vault id in `.mcp.json`.
+ */
+export function generateAgentKey(opts) {
+    const dir = opts.dir ?? ".float";
+    // `undefined` -> root (the creation-time agent). `null` -> unknown, and the
+    // field is omitted rather than guessed.
+    const nodeId = opts.nodeId === null ? undefined : (opts.nodeId ?? AGENT_NODE_ID);
+    const keyringPath = join(dir, "agent-keys.json");
+    const envPath = join(dir, "agent.env");
+    const kp = KeyPair.fromRandom("ed25519");
+    const publicKey = kp.getPublicKey().toString();
+    const secret = kp.toString();
+    mkdirSync(dir, { recursive: true });
+    // APPEND, NEVER REPLACE. A vault may have several agents, and more to the
+    // point: overwriting would destroy the credential of an agent that is
+    // already bound on chain and working. An on-chain binding cannot be undone
+    // by deleting a file, so a lost secret is a permanently stranded agent.
+    let existing = [];
+    let backedUpTo;
+    if (existsSync(keyringPath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(keyringPath, "utf8"));
+            if (Array.isArray(parsed))
+                existing = parsed;
+            else
+                throw new Error("not an array");
+        }
+        catch {
+            // A malformed keyring must not be parsed into oblivion. Move it aside
+            // rather than overwrite it — whatever is in there may be the only copy
+            // of a working secret, and this is not the moment to decide it is junk.
+            backedUpTo = `${keyringPath}.unreadable-${publicKey.slice(8, 16)}`;
+            copyFileSync(keyringPath, backedUpTo);
+            existing = [];
+        }
+    }
+    existing.push({
+        agentId: opts.vault,
+        secret,
+        publicKey,
+        role: opts.role,
+        // Only when known. `JSON.stringify` drops an undefined value, so an
+        // unknown node leaves no field at all — which is what `loadKeyring`
+        // reads as "selectable by role, not by node".
+        ...(typeof nodeId === "number" ? { nodeId } : {}),
+    });
+    writeFileSync(keyringPath, JSON.stringify(existing, null, 2) + "\n");
+    // The env form the MCP server itself reads. Written second and separately
+    // because it holds ONE agent, while the keyring holds every agent — so the
+    // keyring is the durable record and this is a convenience.
+    writeFileSync(envPath, [
+        `# Written by vault_create. Contains a PRIVATE KEY — do not commit or paste.`,
+        `# The agent can only call request_payment on this vault, inside its budget.`,
+        `NEAR_VAULT_AGENT_ID=${opts.vault}`,
+        `NEAR_VAULT_AGENT_KEY=${secret}`,
+        ``,
+    ].join("\n"));
+    // Best effort. Windows ignores POSIX modes, so this must not be load-bearing
+    // — the real protection is that the key is restricted on chain.
+    for (const p of [keyringPath, envPath]) {
+        try {
+            chmodSync(p, 0o600);
+        }
+        catch {
+            /* not POSIX; the on-chain restriction is the actual boundary */
+        }
+    }
+    return { publicKey, role: opts.role, keyringPath, envPath, backedUpTo };
+}
+/** Where the files would go, without creating anything. */
+export function agentKeyPaths(dir = ".float") {
+    return { keyringPath: join(dir, "agent-keys.json"), envPath: join(dir, "agent.env"), dir: dirname(join(dir, "x")) };
+}

package/dist/create.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Onboarding: what a user with NO vault yet needs in order to get one.
+ *
+ * This is the only part of the server that talks to someone who is not yet a
+ * customer, and it holds no key and signs nothing — same trust model as the
+ * plan tools. It answers three questions and hands back a URL:
+ *
+ *   where does my vault go     the FACTORY's own `vault_id_for` view
+ *   what must I attach          the factory's `required_deposit` + code storage
+ *   how do I sign it            the web page, which the user's wallet approves
+ *
+ * THE DERIVATION IS NOT REIMPLEMENTED HERE. `vault_id_for` exists on the
+ * factory precisely so there is one implementation of it; a local copy is a
+ * thing that drifts. The factory's prefix rule has already changed once (labels
+ * are now rooted in the caller's prefix after a squatting hole), and a client
+ * that had copied the old rule would have gone on confidently printing wrong
+ * addresses.
+ */
+/**
+ * Bytes of the vault contract the factory deploys.
+ *
+ * 301,033 until `create_agent_account` was removed, which took 7,305 bytes
+ * with it — about 0.073 NEAR off every vault's storage deposit. The pin
+ * caught the drift the moment the contract shrank, which is the entire
+ * reason it exists.
+ *
+ * 298,819 -> 298,920 on 2026-11-08, when `new` began giving a creation-time
+ * agent its OWN child node instead of binding it to root. +101 bytes, about
+ * 0.00101 NEAR more per vault. The pin caught this one too, on the first gate
+ * run after the rebuild.
+ *
+ * Mirrors `packages/create-float/res/vault.wasm`, and `create.pins.test.ts`
+ * reads that file and fails if the two disagree — so a contract rebuild cannot
+ * silently leave this quoting a deposit that is too small. Too small is not a
+ * clean failure: CreateAccount succeeds and the vault sits below its own
+ * storage requirement, bricking on the first write.
+ */
+export declare const CONTRACT_BYTES = 298920;
+/** NEAR charges 1e19 yoctoNEAR per byte of storage. */
+export declare const STORAGE_COST_PER_BYTE: bigint;
+/**
+ * What `web/index.html` adds on top of the code's storage stake.
+ *
+ * THE FACTORY'S FLOOR IS NOT WHAT THE USER IS ASKED FOR, and conflating the
+ * two quoted a deposit 0.26 NEAR too low. `begin()` in
+ * contracts/factory/src/lib.rs rejects below `required_deposit + bytes * 1e19`
+ * — a real floor, 3.037280 on testnet today. But the page attaches
+ * `stake + 0.36` instead, as headroom for the root node's state, and a wallet
+ * checks the balance against what the PAGE attaches.
+ *
+ * Measured 2026-11-03: a vault created through the page,
+ * tinyrice9138-testnet.fac.floatv4.testnet, holds exactly 3.297280 — the
+ * page's figure to the yoctoNEAR. A user funded to the old 3.237280 quote is
+ * rejected by their wallet needing 3.497280, which is precisely the failure
+ * GAS_RESERVATION_YOCTO below was written to prevent, arriving through the
+ * other term.
+ *
+ * This is a COPY of a value in a file that cannot import from here — the page
+ * is standalone HTML served to a browser with no build step. `create.pins.
+ * test.ts` reads that file and fails if the two disagree, the same way
+ * CONTRACT_BYTES and CREATE_GAS_TGAS are pinned. A copy nothing checks is a
+ * copy that drifts.
+ */
+export declare const PAGE_HEADROOM_YOCTO: bigint;
+/**
+ * Funding for an agent's gas key, when one is bound at creation.
+ *
+ * A NEP-611 gas key's BALANCE is its spending cap — `allowance` is null by
+ * design — so this is the only thing bounding how much gas the agent burns.
+ * 0.12 NEAR ≈ 50 payments at the vault's 50-TGas `MIN_GAS_FOR_DISPATCH`
+ * floor, matching `gasKeyFunding({tgas:60, payments:50})` in create-float.
+ *
+ * Charged ONLY when an agent is bound. The factory raises its own on-chain
+ * deposit floor by exactly this amount in that case, so a quote that omits it
+ * is refused with DEPOSIT_TOO_SMALL — and a quote that always includes it
+ * overcharges everyone who creates a bare vault.
+ *
+ * A COPY of `AGENT_GAS_KEY_FUNDING` in contracts/factory/src/lib.rs and
+ * `AGENT_GAS` in web/index.html. Three files, one number, which is exactly
+ * the shape that already shipped a 0.26 NEAR underquote here — so
+ * `create.pins.test.ts` reads both of the others and fails if any disagree.
+ */
+export declare const AGENT_GAS_KEY_FUNDING_YOCTO: bigint;
+/**
+ * Gas the create page attaches. MEASURED commitment is 124.88 TGas:
+ * 42.79 to deliver and decode the 401 KB base64 argument (measured on chain),
+ * plus CreateAccount 7.70, Transfer 0.23, DeployContract 34.16, and the
+ * factory's forwarded 30 + 10. 200 keeps ~60% headroom.
+ *
+ * Must match `web/index.html`. It is not a free choice — see
+ * `GAS_RESERVATION_YOCTO`.
+ */
+export declare const CREATE_GAS_TGAS = 200n;
+/**
+ * What the user must HOLD on top of the deposit, at signing time.
+ *
+ * A transaction reserves `prepaid_gas * 1e9` — the MAXIMUM gas price — for the
+ * duration of the call, and refunds the unused part a receipt later. Almost
+ * none of it is burned (~0.004 in practice), but the wallet checks the balance
+ * against the reservation and refuses below it. Quoting only the deposit is
+ * what produced:
+ *
+ *   Sender work12.testnet does not have enough balance 3.5234
+ *   for operation costing 3.674061500357969
+ *
+ * so the quoted total includes it.
+ */
+export declare const GAS_RESERVATION_YOCTO: bigint;
+/**
+ * Known factories.
+ *
+ * MAINNET IS DELIBERATELY ABSENT until one is deployed and verified. A wrong
+ * default here does not fail safely: it sends a real user with real NEAR to
+ * sign a 3.4 NEAR deposit into an account we do not control. Absent means the
+ * tool asks, which is the correct behaviour for a value nobody has measured.
+ */
+export declare const FACTORY_BY_NETWORK: Record<string, string | undefined>;
+export interface CreatePlanInput {
+    owner: string;
+    /**
+     * False when the caller does not know the user's NEAR account.
+     *
+     * An agent onboarding a stranger has no account id to pass, and demanding
+     * one assumes the user knows it, types it correctly, and has one at all.
+     * The page derives everything from the CONNECTED wallet anyway, so an
+     * owner-less link is not degraded — it asks the wallet instead of the human.
+     */
+    ownerKnown?: boolean;
+    /** From the factory's `vault_id_for`. `null` means no legal derived id. */
+    vaultId: string | null;
+    factory: string;
+    network: string;
+    /** From the factory's `get_config`. */
+    requiredDepositYocto: string;
+    paused: boolean;
+    appUrl: string;
+    /** Whether the derived account is already on chain. */
+    exists?: boolean;
+    /**
+     * The EXISTING account's own `get_config.owner`, when it could be read.
+     *
+     * WHY THIS IS NOT OPTIONAL REASONING. "The account at your derived id exists,
+     * therefore it is yours" is an inference from the derivation, not a fact
+     * about the account — and `derive_prefix` IS NOT INJECTIVE. The factory says
+     * so in capitals, and `derive_prefix_collides_between_a_dot_and_a_hyphen`
+     * asserts it: `a.b.testnet` and `a-b.testnet` both land on `a-b-testnet`,
+     * because replacing the dot merges it into an alphabet that already contains
+     * the hyphen. Whoever creates first takes the id.
+     *
+     * Without reading the vault back, this tool would tell the LOSER of that
+     * collision to point their agent at the WINNER's vault. Narrow, but the
+     * failure is "you are now configured against someone else's money".
+     *
+     * `null` means the read failed, or the account is not a Float vault at all.
+     * That is a THIRD outcome and must not be flattened into either of the
+     * others — "I could not check" is not "it is yours".
+     */
+    existingOwner?: string | null;
+    /**
+     * The agent public key to bind at creation, if any.
+     *
+     * Only affects the QUOTE here — the server neither generates nor holds the
+     * secret half, and the page still asks the user to confirm the key before
+     * anything is signed.
+     */
+    agentPk?: string | null;
+}
+export interface CreatePlan {
+    owner: string | null;
+    /** Null when the owner is unknown — the wallet decides it at signing time. */
+    vault: string | null;
+    factory: string;
+    network: string;
+    depositYocto: string;
+    depositNear: string;
+    gasTgas: number;
+    gasReservationNear: string;
+    totalRequiredYocto: string;
+    totalRequiredNear: string;
+    url: string;
+    warnings: string[];
+    note: string;
+}
+/** yoctoNEAR -> a NEAR string, without floating point. */
+export declare function yoctoToNear(y: bigint, dp?: number): string;
+export declare function buildCreatePlan(i: CreatePlanInput): CreatePlan;

package/dist/create.js

@@ -0,0 +1,240 @@
+/**
+ * Onboarding: what a user with NO vault yet needs in order to get one.
+ *
+ * This is the only part of the server that talks to someone who is not yet a
+ * customer, and it holds no key and signs nothing — same trust model as the
+ * plan tools. It answers three questions and hands back a URL:
+ *
+ *   where does my vault go     the FACTORY's own `vault_id_for` view
+ *   what must I attach          the factory's `required_deposit` + code storage
+ *   how do I sign it            the web page, which the user's wallet approves
+ *
+ * THE DERIVATION IS NOT REIMPLEMENTED HERE. `vault_id_for` exists on the
+ * factory precisely so there is one implementation of it; a local copy is a
+ * thing that drifts. The factory's prefix rule has already changed once (labels
+ * are now rooted in the caller's prefix after a squatting hole), and a client
+ * that had copied the old rule would have gone on confidently printing wrong
+ * addresses.
+ */
+/**
+ * Bytes of the vault contract the factory deploys.
+ *
+ * 301,033 until `create_agent_account` was removed, which took 7,305 bytes
+ * with it — about 0.073 NEAR off every vault's storage deposit. The pin
+ * caught the drift the moment the contract shrank, which is the entire
+ * reason it exists.
+ *
+ * 298,819 -> 298,920 on 2026-11-08, when `new` began giving a creation-time
+ * agent its OWN child node instead of binding it to root. +101 bytes, about
+ * 0.00101 NEAR more per vault. The pin caught this one too, on the first gate
+ * run after the rebuild.
+ *
+ * Mirrors `packages/create-float/res/vault.wasm`, and `create.pins.test.ts`
+ * reads that file and fails if the two disagree — so a contract rebuild cannot
+ * silently leave this quoting a deposit that is too small. Too small is not a
+ * clean failure: CreateAccount succeeds and the vault sits below its own
+ * storage requirement, bricking on the first write.
+ */
+export const CONTRACT_BYTES = 298920;
+/** NEAR charges 1e19 yoctoNEAR per byte of storage. */
+export const STORAGE_COST_PER_BYTE = 10n ** 19n;
+/**
+ * What `web/index.html` adds on top of the code's storage stake.
+ *
+ * THE FACTORY'S FLOOR IS NOT WHAT THE USER IS ASKED FOR, and conflating the
+ * two quoted a deposit 0.26 NEAR too low. `begin()` in
+ * contracts/factory/src/lib.rs rejects below `required_deposit + bytes * 1e19`
+ * — a real floor, 3.037280 on testnet today. But the page attaches
+ * `stake + 0.36` instead, as headroom for the root node's state, and a wallet
+ * checks the balance against what the PAGE attaches.
+ *
+ * Measured 2026-11-03: a vault created through the page,
+ * tinyrice9138-testnet.fac.floatv4.testnet, holds exactly 3.297280 — the
+ * page's figure to the yoctoNEAR. A user funded to the old 3.237280 quote is
+ * rejected by their wallet needing 3.497280, which is precisely the failure
+ * GAS_RESERVATION_YOCTO below was written to prevent, arriving through the
+ * other term.
+ *
+ * This is a COPY of a value in a file that cannot import from here — the page
+ * is standalone HTML served to a browser with no build step. `create.pins.
+ * test.ts` reads that file and fails if the two disagree, the same way
+ * CONTRACT_BYTES and CREATE_GAS_TGAS are pinned. A copy nothing checks is a
+ * copy that drifts.
+ */
+export const PAGE_HEADROOM_YOCTO = 36n * 10n ** 22n;
+/**
+ * Funding for an agent's gas key, when one is bound at creation.
+ *
+ * A NEP-611 gas key's BALANCE is its spending cap — `allowance` is null by
+ * design — so this is the only thing bounding how much gas the agent burns.
+ * 0.12 NEAR ≈ 50 payments at the vault's 50-TGas `MIN_GAS_FOR_DISPATCH`
+ * floor, matching `gasKeyFunding({tgas:60, payments:50})` in create-float.
+ *
+ * Charged ONLY when an agent is bound. The factory raises its own on-chain
+ * deposit floor by exactly this amount in that case, so a quote that omits it
+ * is refused with DEPOSIT_TOO_SMALL — and a quote that always includes it
+ * overcharges everyone who creates a bare vault.
+ *
+ * A COPY of `AGENT_GAS_KEY_FUNDING` in contracts/factory/src/lib.rs and
+ * `AGENT_GAS` in web/index.html. Three files, one number, which is exactly
+ * the shape that already shipped a 0.26 NEAR underquote here — so
+ * `create.pins.test.ts` reads both of the others and fails if any disagree.
+ */
+export const AGENT_GAS_KEY_FUNDING_YOCTO = 12n * 10n ** 22n;
+/**
+ * Gas the create page attaches. MEASURED commitment is 124.88 TGas:
+ * 42.79 to deliver and decode the 401 KB base64 argument (measured on chain),
+ * plus CreateAccount 7.70, Transfer 0.23, DeployContract 34.16, and the
+ * factory's forwarded 30 + 10. 200 keeps ~60% headroom.
+ *
+ * Must match `web/index.html`. It is not a free choice — see
+ * `GAS_RESERVATION_YOCTO`.
+ */
+export const CREATE_GAS_TGAS = 200n;
+/**
+ * What the user must HOLD on top of the deposit, at signing time.
+ *
+ * A transaction reserves `prepaid_gas * 1e9` — the MAXIMUM gas price — for the
+ * duration of the call, and refunds the unused part a receipt later. Almost
+ * none of it is burned (~0.004 in practice), but the wallet checks the balance
+ * against the reservation and refuses below it. Quoting only the deposit is
+ * what produced:
+ *
+ *   Sender work12.testnet does not have enough balance 3.5234
+ *   for operation costing 3.674061500357969
+ *
+ * so the quoted total includes it.
+ */
+export const GAS_RESERVATION_YOCTO = CREATE_GAS_TGAS * 10n ** 12n * 10n ** 9n;
+/**
+ * Known factories.
+ *
+ * MAINNET IS DELIBERATELY ABSENT until one is deployed and verified. A wrong
+ * default here does not fail safely: it sends a real user with real NEAR to
+ * sign a 3.4 NEAR deposit into an account we do not control. Absent means the
+ * tool asks, which is the correct behaviour for a value nobody has measured.
+ */
+export const FACTORY_BY_NETWORK = {
+    testnet: "fac.floatv4.testnet",
+    mainnet: undefined,
+};
+/** yoctoNEAR -> a NEAR string, without floating point. */
+export function yoctoToNear(y, dp = 5) {
+    const neg = y < 0n;
+    const v = neg ? -y : y;
+    const whole = v / 10n ** 24n;
+    const frac = (v % 10n ** 24n).toString().padStart(24, "0").slice(0, dp);
+    return `${neg ? "-" : ""}${whole}.${frac}`;
+}
+export function buildCreatePlan(i) {
+    if (i.paused) {
+        throw new Error(`The factory ${i.factory} is paused — vault creation is disabled. ` +
+            `This is the operator's kill switch; try again later.`);
+    }
+    // UNKNOWN OWNER IS A VALID CASE, not a missing argument. Everything below
+    // that depends on the owner is skipped rather than guessed: no derived
+    // address, no existence check, and no `owner` on the url — the page refuses
+    // when that parameter disagrees with the connected wallet, so a blank or
+    // invented one would turn every link into a refusal.
+    const known = i.ownerKnown !== false && !!i.owner;
+    if (known && !i.vaultId) {
+        throw new Error(`${i.owner} has no legal vault id under ${i.factory}. ` +
+            `An implicit account (a 64-character hex id) cannot have one: the derived ` +
+            `prefix is already 64 characters, so "<prefix>.${i.factory}" exceeds NEAR's ` +
+            `64-character limit. Use a named account.`);
+    }
+    if (known && i.exists) {
+        // Three outcomes, deliberately not two. The old message asserted the
+        // first one for all three.
+        if (i.existingOwner && i.existingOwner === i.owner) {
+            throw new Error(`${i.vaultId} already exists and ${i.owner} owns it — confirmed by reading ` +
+                `its get_config. Connect to it with NEAR_VAULT_CONTRACT=${i.vaultId} ` +
+                `rather than creating another.`);
+        }
+        if (i.existingOwner) {
+            throw new Error(`${i.vaultId} already exists and is owned by ${i.existingOwner}, NOT by ` +
+                `${i.owner}. Do NOT point an agent at it.\n\n` +
+                `The factory derives a vault id by replacing dots with hyphens, and that ` +
+                `is not injective: "a.b.near" and "a-b.near" both derive "a-b-near", and ` +
+                `whoever created first holds the id. Create yours under a label instead, ` +
+                `which puts it at a different address.`);
+        }
+        throw new Error(`${i.vaultId} already exists, but its owner could NOT be read, so whether it ` +
+            `is yours is unknown — not assumed. It may not be a Float vault at all. ` +
+            `Check it before pointing anything at it:\n` +
+            `  near view ${i.vaultId} get_config`);
+    }
+    // Two different floors, and the quote must clear BOTH.
+    //
+    //   pageAttaches   what the wallet is actually asked to approve
+    //   factoryFloor   what `begin()` rejects below, on chain
+    //
+    // They are independent: the page's headroom is a fixed constant while the
+    // factory's floor moves with `set_required_deposit`. Quoting either one
+    // alone is what broke — the old code quoted the floor, and the page then
+    // asked for 0.26 more.
+    const stake = BigInt(CONTRACT_BYTES) * STORAGE_COST_PER_BYTE;
+    // Both floors move by the gas-key funding when an agent is bound: the page
+    // attaches it, and the factory requires it.
+    const agentFunding = i.agentPk ? AGENT_GAS_KEY_FUNDING_YOCTO : 0n;
+    const pageAttaches = stake + PAGE_HEADROOM_YOCTO + agentFunding;
+    const factoryFloor = BigInt(i.requiredDepositYocto) + stake + agentFunding;
+    const deposit = pageAttaches > factoryFloor ? pageAttaches : factoryFloor;
+    const total = deposit + GAS_RESERVATION_YOCTO;
+    // If the operator raises `required_deposit` past the page's headroom, the
+    // page under-attaches and the create is rejected ON CHAIN with
+    // DEPOSIT_TOO_SMALL. Quoting the higher figure does not rescue that — the
+    // user would hold enough and still fail, because the page attaches the
+    // lesser amount regardless of what they hold. Say so rather than quoting a
+    // number that cannot help.
+    const underAttachWarning = factoryFloor > pageAttaches
+        ? [
+            `WARNING: ${i.factory} now requires ${yoctoToNear(factoryFloor)} NEAR, but the ` +
+                `create page attaches only ${yoctoToNear(pageAttaches)}. The transaction will be ` +
+                `rejected on chain with DEPOSIT_TOO_SMALL no matter how much you hold. The page's ` +
+                `headroom constant needs raising — this is an operator bug, not a funding problem.`,
+        ]
+        : [];
+    const url = new URL(i.appUrl);
+    if (known)
+        url.searchParams.set("owner", i.owner);
+    if (i.agentPk)
+        url.searchParams.set("agent_pk", i.agentPk);
+    url.searchParams.set("factory", i.factory);
+    url.searchParams.set("network", i.network);
+    const unknownOwnerWarnings = known
+        ? []
+        : [
+            `The vault address is not known yet — it is derived from whichever wallet ` +
+                `you connect, and the page will show it before you approve anything.`,
+            `Nothing has checked whether you already have a vault. If you do, the page ` +
+                `will say so rather than creating a second one.`,
+        ];
+    return {
+        owner: known ? i.owner : null,
+        vault: known ? i.vaultId : null,
+        factory: i.factory,
+        network: i.network,
+        depositYocto: deposit.toString(),
+        depositNear: yoctoToNear(deposit),
+        gasTgas: Number(CREATE_GAS_TGAS),
+        gasReservationNear: yoctoToNear(GAS_RESERVATION_YOCTO),
+        totalRequiredYocto: total.toString(),
+        totalRequiredNear: yoctoToNear(total),
+        url: url.toString(),
+        warnings: [
+            ...underAttachWarning,
+            ...unknownOwnerWarnings,
+            `Almost all of the ${yoctoToNear(deposit)} NEAR is a refundable storage ` +
+                `deposit held by your vault, not a fee.`,
+            `You must HOLD ${yoctoToNear(total)} NEAR at signing time: the deposit plus a ` +
+                `${yoctoToNear(GAS_RESERVATION_YOCTO)} gas reservation. The reservation is ` +
+                `refunded moments later — only about 0.004 is actually spent — but a wallet ` +
+                `refuses the transaction if the balance is below it.`,
+            `Nothing can spend from this vault until you add an agent and give it a budget.`,
+        ],
+        note: `This server never sees or holds a key. Open the URL and approve the ` +
+            `transaction in your own wallet; the contract travels as an argument to ` +
+            `one ordinary function call, and the factory deploys it for you.`,
+    };
+}