@intent-engine/cli 0.1.11 → 0.1.15

package/dist/src/agent/wallet.js

@@ -1,17 +1,21 @@
-import { decodeEvent, findIntentPda, formatAmount, getIntentDecoder, IntentStatus, parseAmount } from "@intent-engine/core";
-import { chainTime, CLOCK_SYSVAR, mintOf } from "../accounts.js";
+import { createHash } from "node:crypto";
+import { AccountRole, getAddressDecoder } from "@solana/kit";
+import { attestedFillMessage, buildFillAttested, decodeEvent, decodeParams, feeBpsFor, findIntentPda, formatAmount, formatTime, getIntentDecoder, IntentStatus, Kind, LONG_LIVED_SECONDS, parseAmount, signEd25519Instruction, splitFees, WARN_ATTESTOR, WARN_LONG_LIVED, } from "@intent-engine/core";
+import { chainTime, CLOCK_SYSVAR, loadConfig, mintOf } from "../accounts.js";
 import { ENV_KEYPAIR, WALLET_NOT_MAINNET } from "../args.js";
 import { execute } from "../flows.js";
-import { TOKEN_NAMES, tokenNamed } from "../tokens.js";
-import { unmemoized } from "../transport.js";
+import { NATIVE_MINT, TOKEN_NAMES, tokenNamed } from "../tokens.js";
+import { MEMO_PROGRAM_ADDRESS, neverLanded, unmemoized } from "../transport.js";
 import { balances, defaultMints, FAUCET, PUBLIC_FAUCET, setup, withSettings } from "../wallet.js";
 import { define } from "./actions.js";
-import { MAX_EXPIRES_IN, MIN_EXPIRES_IN, prepareCreate } from "./create.js";
+import { MAX_EXPIRES_IN, MIN_EXPIRES_IN, prepareCreate, WRAPPED } from "./create.js";
 import { tool } from "./names.js";
-import { AgentRefusal } from "./problems.js";
+import { AgentRefusal, problemOf } from "./problems.js";
 import { listIntents } from "./read.js";
 import { InvalidInput, account, amount, choice, flag, integer, list, object, optional, text, time } from "./schema.js";
-import { orderSchema } from "./shapes.js";
+import { orderSchema, preparedView } from "./shapes.js";
+import { tokenAccountIfMissing, walletRecipient } from "./owner.js";
+import { prepare } from "./prepare.js";
 import { prepareCancel } from "./settle.js";
 import { STATUS } from "../accounts.js";
 export const walletGuard = (limits) => ({ limits, sales: [] });
@@ -19,7 +23,7 @@ export const SALE_WINDOW = 3600n;
 export const ESTIMATE_SCAN = 12;
 export const ESTIMATE_FILLS = 5;
 export const WAIT_DEFAULT = 30;
-export const WAIT_MAX = 55;
+export const WAIT_MAX = 40;
 export const WAIT_SCAN = 10;
 export const DEFAULT_EXPIRES_IN = 3_600;
 export const LANDING_SECONDS = 10;
@@ -28,7 +32,7 @@ export const WALLET_NOTICE = [
     "Test network only: this wallet works on Solana devnet, testnet or localnet and refuses mainnet. Its tokens have no value.",
     "Your key stays on this machine: setup makes one unless a keypair is already configured, and names its file. Only signed transactions leave it.",
     "This server talks to no one but the RPC endpoint it was started with.",
-    "Nothing moves until you approve: swaps, auctions and cancels only preview until you say yes.",
+    "Nothing moves until you approve: swaps, auctions, escrows, releases and cancels only preview until you say yes.",
     "Do not send real funds to this wallet or use its key anywhere else.",
 ];
 export const walletEmpty = (address) => `the wallet ${address} holds no SOL yet; request devnet SOL for it at ${FAUCET} or ${PUBLIC_FAUCET}, then try again`;
@@ -113,7 +117,14 @@ export function limitLines(limits) {
         "It sells no other token. Plan trades within these limits and tell the user when a request exceeds them.",
     ];
 }
-const capOf = (text, decimals) => parseAmount(text, decimals);
+function capOf(text, decimals, mint) {
+    try {
+        return parseAmount(text, decimals);
+    }
+    catch {
+        throw new AgentRefusal("WalletTokenNotAllowed", `this server's limit of ${text} ${nameOf(mint)} does not fit a token with ${decimals} decimals, so it sells none; the user restarts it with a valid limit`);
+    }
+}
 function checkSale(guard, mint, decimals, amount, now) {
     if (!limited(guard)) {
         return;
@@ -125,16 +136,20 @@ function checkSale(guard, mint, decimals, amount, now) {
         throw new AgentRefusal("WalletTokenNotAllowed", `this server sells only ${allowed}, not ${name}; its limits were set when it started`);
     }
     const trade = perTrade.get(mint);
-    if (trade !== undefined && amount > capOf(trade, decimals)) {
+    if (trade !== undefined && amount > capOf(trade, decimals, mint)) {
         throw new AgentRefusal("WalletTradeLimit", `this server sells at most ${trade} ${name} per trade and this sells ${formatAmount(amount, decimals)}; sell less, or the user restarts the server with a higher --wallet-per-trade`);
     }
-    const hour = perHour.get(mint);
+    checkHour(guard, mint, decimals, amount, now);
+}
+function checkHour(guard, mint, decimals, amount, now) {
+    const hour = guard.limits.perHour.get(mint);
+    const name = nameOf(mint);
     if (hour === undefined) {
         return;
     }
     guard.sales = guard.sales.filter((s) => s.at > now - SALE_WINDOW);
     const used = guard.sales.filter((s) => s.mint === mint).reduce((sum, s) => sum + s.amount, 0n);
-    const cap = capOf(hour, decimals);
+    const cap = capOf(hour, decimals, mint);
     if (used + amount > cap) {
         throw new AgentRefusal("WalletHourLimit", `this server sells at most ${hour} ${name} per hour and has ${formatAmount(cap > used ? cap - used : 0n, decimals)} left; this sells ${formatAmount(amount, decimals)}`);
     }
@@ -192,7 +207,7 @@ export const walletBalance = define({
         return balances(ctx.transport, owner, mints);
     },
 });
-const offerOutput = object({
+const offerFields = {
     intent: account(),
     nonce: amount(),
     summary: list(text(), 24),
@@ -200,7 +215,8 @@ const offerOutput = object({
     sent: flag(),
     signature: optional(text()),
     next: optional(text()),
-});
+};
+const offerOutput = object(offerFields);
 async function offered(ctx, call, input, terms) {
     const wallet = access(ctx);
     const signer = await signerOf(ctx);
@@ -215,9 +231,9 @@ async function offered(ctx, call, input, terms) {
         mintOf(ctx.transport, outputMint),
         chainTime(ctx.transport),
     ]);
-    const made = terms(inputToken, outputToken, now);
+    const made = await terms(inputToken, outputToken, now, inputMint, outputMint);
     checkSale(wallet.limits, inputMint, inputToken.decimals, made.order.amount_in, now);
-    const view = (await prepareCreate.run(ctx, { owner: signer.address, input_mint: inputMint, output_mint: outputMint, ...made }, call));
+    const view = (await prepareCreate.run(ctx, { owner: signer.address, input_mint: inputMint, output_mint: outputMint, ...(input.pay_to === undefined ? {} : { pay_to: input.pay_to }), ...made }, call));
     const { intent, nonce, summary, warnings, prepared } = view;
     const sold = made.order.amount_in;
     const guard = wallet.limits;
@@ -231,14 +247,47 @@ async function offered(ctx, call, input, terms) {
         return await sent(ctx, signer, { intent, nonce, summary, warnings, prepared }, input.send, call);
     }
     catch (error) {
-        guard.sales = guard.sales.filter((s) => s !== sale);
+        if (neverLanded(error)) {
+            guard.sales = guard.sales.filter((s) => s !== sale);
+        }
         throw error;
     }
 }
+export const SWAP_FALLS_OVER = 120;
+export const PAY_TO = "the wallet that receives what is bought, such as someone this wallet pays; default this wallet. This wallet pays for its token account if it has none";
+export const SWAP_HEADROOM_BPS = 200n;
+export const SWAP_BLIND_BPS = 2500n;
+export const SWAP_CAP_BPS = 20000n;
+async function recentFills(transport, inputMint, outputMint) {
+    const { created, fills } = await engineHistory(transport, ESTIMATE_SCAN);
+    const unknown = [...new Set(fills.map((f) => f.intent).filter((intent) => !created.has(intent)))];
+    const views = unknown.length === 0 ? [] : await transport.getAccounts(unknown);
+    unknown.forEach((intent, i) => {
+        const view = views[i];
+        const pair = view === null || view === undefined ? null : pairOf(view.data);
+        if (pair !== null) {
+            created.set(intent, pair);
+        }
+    });
+    return fills
+        .filter((f) => f.amountIn > 0n && created.get(f.intent)?.inputMint === inputMint && created.get(f.intent)?.outputMint === outputMint)
+        .slice(0, ESTIMATE_FILLS);
+}
+const byRate = (fills) => [...fills].sort((a, b) => (a.delivered * b.amountIn < b.delivered * a.amountIn ? -1 : a.delivered * b.amountIn > b.delivered * a.amountIn ? 1 : 0));
+const bestOf = (fills) => byRate(fills).at(-1);
+const medianOf = (fills) => byRate(fills)[Math.floor((fills.length - 1) / 2)];
+function openingAsk(fills, amount, floor) {
+    const typical = medianOf(fills);
+    const blind = (floor * (10000n + SWAP_BLIND_BPS)) / 10000n;
+    const seen = typical === undefined ? 0n : (amount * typical.delivered * (10000n + SWAP_HEADROOM_BPS)) / (typical.amountIn * 10000n);
+    const cap = (floor * SWAP_CAP_BPS) / 10000n;
+    const ask = seen > blind ? seen : blind;
+    return ask < cap ? ask : cap;
+}
 const walletSwap = define({
     name: tool("wallet_swap"),
     title: "Swap from the wallet",
-    description: "Offer an exact amount of one token for at least an amount of another, from this server's wallet: the tokens are escrowed in an intent that a solver fills or that the wallet gets back. Amounts are whole tokens such as 0.05. Selling SOL wraps it first. Without send it only previews; show the user the summary and call again with send: true once they approve.",
+    description: `Sell an exact amount of one token for at least min_receive of another, from this server's wallet: the tokens are escrowed in an intent that a solver fills or that the wallet gets back. Solvers pay the least an intent asks, so by default the ask starts at start_receive, a little above the median of recent fills but at least a quarter above min_receive and at most twice it, and falls to min_receive over falls_over seconds (default ${SWAP_FALLS_OVER}): a solver takes it near the most it can pay. exact: true asks min_receive from the start instead. Amounts are whole tokens such as 0.05. Selling SOL wraps it first. Without send it only previews; show the user the summary, then call again with send: true and the start_receive the preview returned once they approve.`,
     effect: "submit",
     repeats: true,
     input: object({
@@ -246,18 +295,336 @@ const walletSwap = define({
         buy: text("SOL, TEST or a mint address"),
         amount: text("whole tokens to sell, such as 0.05"),
         min_receive: text("least whole tokens to receive for all of it"),
+        start_receive: optional(text("whole tokens asked when the offer lands; default a little above the median recent fill, between 1.25 and 2 times min_receive")),
+        falls_over: optional(integer(MIN_EXPIRES_IN, MAX_EXPIRES_IN, `seconds the ask takes to fall to min_receive; default ${SWAP_FALLS_OVER}`)),
+        exact: optional(flag("true asks min_receive from the start, with no falling ask")),
+        pay_to: optional(account(PAY_TO)),
         expires_in: optional(integer(MIN_EXPIRES_IN, MAX_EXPIRES_IN, `least seconds the offer stays open once sent; default ${DEFAULT_EXPIRES_IN}`)),
         send: optional(flag("true signs and sends; leave out to preview")),
     }),
+    output: object({ ...offerFields, start_receive: optional(text("whole tokens asked when the offer lands; pass it back when sending")) }),
+    run: async (ctx, input, call) => {
+        let opening;
+        const result = await offered(ctx, call, input, async (sold, bought, now, inputMint, outputMint) => {
+            const amountIn = raw(input.amount, sold.decimals, "amount");
+            const floor = raw(input.min_receive, bought.decimals, "min_receive");
+            const expiresIn = BigInt(input.expires_in ?? DEFAULT_EXPIRES_IN);
+            const ask = input.exact === true
+                ? floor
+                : input.start_receive === undefined
+                    ? openingAsk(await recentFills(ctx.transport, inputMint, outputMint), amountIn, floor)
+                    : raw(input.start_receive, bought.decimals, "start_receive");
+            if (ask <= floor) {
+                return { order: { kind: "swap", amount_in: amountIn, min_out: floor }, expires_at: now + expiresIn + BigInt(LANDING_SECONDS) };
+            }
+            opening = formatAmount(ask, bought.decimals);
+            const start = now + BigInt(LANDING_SECONDS);
+            const falls = BigInt(input.falls_over ?? SWAP_FALLS_OVER);
+            return {
+                order: { kind: "dutch", amount_in: amountIn, start_out: ask, end_out: floor, start_time: start, end_time: start + falls },
+                expires_at: start + (expiresIn > falls ? expiresIn : falls),
+            };
+        });
+        return opening === undefined ? result : { ...result, start_receive: opening };
+    },
+});
+export const ESCROW_EXPIRES_IN = 86_400;
+export const RECORD_MINT_NEEDED = "selling SOL on this RPC needs record_mint: any other token's mint, which only labels the escrow";
+function recordedMint(sell, url, chosen) {
+    if (chosen !== undefined) {
+        return mintNamed(chosen, url, "record_mint");
+    }
+    if (sell !== NATIVE_MINT) {
+        return NATIVE_MINT;
+    }
+    const test = tokenNamed("TEST", url);
+    if (test instanceof Error) {
+        throw new InvalidInput([{ path: "record_mint", message: RECORD_MINT_NEEDED }]);
+    }
+    return test;
+}
+const walletEscrow = define({
+    name: tool("wallet_escrow"),
+    title: "Escrow a payment for an attestor to release",
+    description: `Hold an exact amount of one token from this server's wallet in an attested intent: it goes, minus the engine fee, to whichever wallet the named attestor later signs for, once the attestor attests a result between min_result and max_result. Use it to pay another agent for work that a third agent or a person judges. The attestor alone decides who is paid; nothing else is checked on chain, so name an attestor the user trusts. Have the worker deliver to the attestor rather than to this wallet, since this wallet can cancel until the release; ${tool("wallet_receipt")} later shows what the release recorded. Until then the wallet can cancel it with ${tool("wallet_cancel")}, and after it expires anyone can return the escrow. Amounts are whole tokens such as 0.05. Without send it only previews; show the user the summary and call again with send: true once they approve.`,
+    effect: "submit",
+    repeats: true,
+    input: object({
+        sell: text("SOL, TEST or a mint address: the token to pay with"),
+        amount: text("whole tokens to escrow, such as 0.05"),
+        attestor: account("the wallet whose signature alone releases the escrow"),
+        min_result: optional(amount("least result the attestor may attest; default 1")),
+        max_result: optional(amount("greatest result the attestor may attest; default min_result")),
+        expires_in: optional(integer(MIN_EXPIRES_IN, MAX_EXPIRES_IN, `least seconds the escrow stays open once sent; default ${ESCROW_EXPIRES_IN}`)),
+        record_mint: optional(text("a token the escrow records as its output, other than sell; only a label. Default SOL, or TEST when selling SOL on devnet")),
+        send: optional(flag("true signs and sends; leave out to preview")),
+    }),
     output: offerOutput,
-    run: async (ctx, input, call) => offered(ctx, call, input, (sold, bought, now) => ({
-        order: {
-            kind: "swap",
-            amount_in: raw(input.amount, sold.decimals, "amount"),
-            min_out: raw(input.min_receive, bought.decimals, "min_receive"),
-        },
-        expires_at: now + BigInt((input.expires_in ?? DEFAULT_EXPIRES_IN) + LANDING_SECONDS),
-    })),
+    run: async (ctx, input, call) => {
+        const wallet = access(ctx);
+        const sold = mintNamed(input.sell, wallet.url, "sell");
+        const least = input.min_result ?? 1n;
+        const most = input.max_result ?? least;
+        if (most < least) {
+            throw new InvalidInput([{ path: "max_result", message: "must be at least min_result" }]);
+        }
+        return offered(ctx, call, { sell: sold, buy: recordedMint(sold, wallet.url, input.record_mint), send: input.send }, (token, _, now) => ({
+            order: { kind: "attested", amount_in: raw(input.amount, token.decimals, "amount"), min_result: least, max_result: most, attestor: input.attestor },
+            expires_at: now + BigInt((input.expires_in ?? ESCROW_EXPIRES_IN) + LANDING_SECONDS),
+        }));
+    },
+});
+export const PAYEE_MOVED = "this wallet's token account for the escrowed token now belongs to someone else, so a release would not reach it; ask the payee for another wallet";
+export const RELEASE_CHANGED = "this release differs from its preview: the payee, amount, result, fee or the escrow itself changed, or no approval was given; preview it again and show the user";
+export const approvalOf = (message, memo = "") => createHash("sha256").update(message).update(memo).digest("hex").slice(0, 16);
+export const DELIVERY_PREFIX = "delivery sha256:";
+const DELIVERY_MEMO = /^delivery sha256:([0-9a-f]{64})$/;
+function sha256Of(text, path) {
+    const hex = text.trim().toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(hex)) {
+        throw new InvalidInput([{ path, message: "give a sha256 as 64 hex digits" }]);
+    }
+    return hex;
+}
+export const notAttestor = (attestor) => `this intent names ${attestor} as its attestor, not this server's wallet; only that key can release it`;
+const walletAttest = define({
+    name: tool("wallet_attest"),
+    title: "Release an escrow as its attestor",
+    description: `As the attestor an escrow names, sign that it pays pay_to and settle it on chain from this server's wallet: the escrowed tokens, minus the engine fee and any partner fee, go to pay_to's token account, which this creates if needed. Use it when this server's wallet was named attestor of an intent made with ${tool("wallet_escrow")} and the work it pays for is done. A release cannot be undone. Without send it only previews and signs nothing; show the user the summary and, once they approve, call again with send: true and the approval the preview returned, which holds the send to exactly what was previewed.`,
+    effect: "submit",
+    input: object({
+        owner: account("the wallet that made the escrow"),
+        nonce: amount("the escrow intent's nonce"),
+        pay_to: account("the wallet to pay"),
+        result: optional(amount("the result to attest, between the intent's min_result and max_result; default min_result")),
+        delivered_sha256: optional(text(`the sha256, as 64 hex digits, of the work this release pays for; recorded in a memo this wallet signs with the release, so the payer can check what it receives with ${tool("wallet_receipt")}`)),
+        approval: optional(text("the approval the preview returned; needed with send")),
+        send: optional(flag("true signs the attestation and settles; leave out to preview")),
+    }),
+    output: object({
+        intent: account(),
+        pay_to: account(),
+        payee: account("pay_to's token account that receives the escrow"),
+        paid: text("whole tokens pay_to receives"),
+        fee: text("whole tokens kept as fees"),
+        result: amount(),
+        approval: text("pass it back with send: true; a send that would differ from this preview is refused"),
+        delivered_sha256: optional(text("the sha256 the release records")),
+        summary: list(text(), 8),
+        warnings: list(text(), 8),
+        sent: flag(),
+        signature: optional(text()),
+        next: optional(text()),
+    }),
+    run: async (ctx, input, call) => {
+        const signer = await signerOf(ctx);
+        const [intent] = await findIntentPda({ owner: input.owner, nonce: input.nonce });
+        const [view, { config }] = await Promise.all([ctx.transport.getAccount(intent), loadConfig(ctx.transport)]);
+        if (view === null) {
+            throw new AgentRefusal("NotFound", `no intent ${intent}; it was settled, cancelled and closed, or never made`);
+        }
+        const held = getIntentDecoder().decode(view.data);
+        const params = decodeParams(held.kind, Uint8Array.from(held.params));
+        if (params.kind !== Kind.AttestedResult) {
+            throw new AgentRefusal("KindMismatch", "this intent is not an attested escrow");
+        }
+        if (params.attestor !== signer.address) {
+            throw new AgentRefusal("Unauthorized", notAttestor(params.attestor));
+        }
+        if (held.status !== IntentStatus.Open) {
+            throw new AgentRefusal("InvalidTransition", `this escrow is ${STATUS[held.status] ?? "not open"}, so it can no longer be released`);
+        }
+        if (held.expiresAt <= (await chainTime(ctx.transport))) {
+            throw new AgentRefusal("IntentExpired", "this escrow has expired; its owner gets it back instead");
+        }
+        const result = input.result ?? params.minResult;
+        if (result < params.minResult || result > params.maxResult) {
+            throw new InvalidInput([{ path: "result", message: `must be between ${params.minResult} and ${params.maxResult}` }]);
+        }
+        await walletRecipient(ctx.transport, input.pay_to, "pay_to");
+        const token = await mintOf(ctx.transport, held.inputMint);
+        const payee = await tokenAccountIfMissing(ctx.transport, signer, input.pay_to, held.inputMint, token.tokenProgram);
+        if (payee.create.length === 0) {
+            const existing = await ctx.transport.getAccount(payee.address);
+            const holder = existing === null || existing.data.length < 64 ? null : getAddressDecoder().decode(existing.data.subarray(32, 64));
+            if (holder !== input.pay_to) {
+                throw new InvalidInput([{ path: "pay_to", message: PAYEE_MOVED }]);
+            }
+        }
+        const amountIn = held.escrowed - held.filled;
+        const maxFeeBps = feeBpsFor(config, held.kind) + held.partnerBps;
+        const shares = splitFees(amountIn, feeBpsFor(config, held.kind), held.partnerBps, held.partnerCutBps);
+        const treasury = shares.protocol > 0n
+            ? await tokenAccountIfMissing(ctx.transport, signer, config.feeRecipient, held.inputMint, token.tokenProgram)
+            : { create: [] };
+        const partnerPaid = shares.partner > 0n;
+        const partner = partnerPaid ? await tokenAccountIfMissing(ctx.transport, signer, held.partner, held.inputMint, token.tokenProgram) : { create: [] };
+        const message = await attestedFillMessage(signer.address, {
+            domain: Uint8Array.from(config.domain),
+            intent,
+            payee: payee.address,
+            amountIn,
+            result,
+            filled: held.filled,
+            revision: held.revision,
+            maxFeeBps,
+        });
+        const settle = await buildFillAttested({
+            solver: signer,
+            owner: input.owner,
+            nonce: input.nonce,
+            inputMint: held.inputMint,
+            inputTokenProgram: token.tokenProgram,
+            payee: payee.address,
+            ...(shares.protocol > 0n ? { feeRecipient: config.feeRecipient } : {}),
+            ...(partnerPaid ? { partner: held.partner } : {}),
+            amountIn,
+            result,
+            maxFeeBps,
+        });
+        const name = TOKEN_NAMES[held.inputMint] ?? held.inputMint;
+        const paid = formatAmount(shares.net, token.decimals);
+        const setup = [...payee.create, ...treasury.create, ...partner.create];
+        const delivered = input.delivered_sha256 === undefined ? undefined : sha256Of(input.delivered_sha256, "delivered_sha256");
+        const memoText = delivered === undefined ? "" : `${DELIVERY_PREFIX}${delivered}`;
+        const memo = delivered === undefined
+            ? []
+            : [{ programAddress: MEMO_PROGRAM_ADDRESS, accounts: [{ address: signer.address, role: AccountRole.READONLY_SIGNER, signer }], data: new TextEncoder().encode(memoText) }];
+        const approval = approvalOf(message, memoText);
+        if (input.send === true && input.approval !== approval) {
+            throw new AgentRefusal("ReleaseChanged", RELEASE_CHANGED);
+        }
+        const prepared = input.send === true
+            ? preparedView(await prepare(ctx.transport, [...setup, await signEd25519Instruction(signer, message), settle, ...memo], signer.address))
+            : undefined;
+        const view2 = {
+            intent,
+            pay_to: input.pay_to,
+            payee: payee.address,
+            paid,
+            fee: formatAmount(shares.protocol + shares.partner, token.decimals),
+            result,
+            approval,
+            ...(delivered === undefined ? {} : { delivered_sha256: delivered }),
+            summary: [
+                `Pays: ${paid} of ${name} to ${input.pay_to} from ${input.owner}'s escrow${held.inputMint === NATIVE_MINT ? WRAPPED : ""}`,
+                `Attests: result ${result}, signed by this server's wallet as the escrow's attestor`,
+                ...(delivered === undefined ? [] : [`Records: the delivered work's sha256 ${delivered}, in a memo this wallet signs with the release`]),
+                ...(payee.create.length === 0 ? [] : [`Setup: creates ${input.pay_to}'s ${name} account, paid by this wallet`]),
+                ...(treasury.create.length === 0 ? [] : [`Setup: creates the engine treasury's ${name} account for the fee, paid by this wallet`]),
+                ...(partner.create.length === 0 ? [] : [`Setup: creates the partner ${held.partner}'s ${name} account for its fee, paid by this wallet`]),
+            ],
+            warnings: [WARN_ATTESTOR],
+            prepared,
+        };
+        return sent(ctx, signer, view2, input.send, call);
+    },
+});
+export const MAX_RECURRING = 12;
+export const mayHaveLanded = (sent, times, problem) => `${sent} of ${times} orders were sent and the next may have landed too (${problem}); check ${tool("wallet_intents")} before sending any again, and do not repeat this call`;
+export const partlySent = (sent, times, problem) => `${sent} of ${times} orders were sent; the next failed with ${problem}. To finish, schedule only the ${times - sent} remaining orders; do not repeat this call`;
+export const WARN_EARLY = "an order fills before its turn if a solver can already pay its start_receive";
+export const NO_FALL = "must be more than 0, or the orders have no ask to fall";
+const refusedBeforeSending = (error) => neverLanded(error) || error instanceof AgentRefusal || error instanceof InvalidInput;
+export const MAX_EVERY = 30 * 24 * 60 * 60;
+const walletRecurring = define({
+    name: tool("wallet_recurring"),
+    title: "Repeat a swap on a schedule",
+    description: `Sell the same amount of one token for another several times, every so many seconds, from this server's wallet, with no bot left running: all orders are sent now and escrowed now. Each order holds its ask at start_receive until its turn, then lets it fall to min_receive over falls_over seconds; it expires when the next one opens, or falls_over seconds after its own opening if that is later, and anyone can then return its escrow. An order fills before its turn if a solver can already pay start_receive, so set it above what solvers pay now to hold the orders. Any order can be cancelled with ${tool("wallet_cancel")}. Each order pays the create fee and rent, and the rent returns when it closes. Amounts are whole tokens per order. Without send it only previews; show the user the summary, then call again with send: true and the start_receive the preview returned once they approve.`,
+    effect: "submit",
+    repeats: true,
+    input: object({
+        sell: text("SOL, TEST or a mint address"),
+        buy: text("SOL, TEST or a mint address"),
+        amount: text("whole tokens each order sells, such as 0.05"),
+        min_receive: text("least whole tokens each order receives"),
+        every: integer(MIN_EXPIRES_IN, MAX_EVERY, "seconds between one order opening and the next"),
+        times: integer(2, MAX_RECURRING, "how many orders"),
+        start_receive: optional(text("whole tokens each order asks until and when it opens; default a little above the median recent fill, between 1.25 and 2 times min_receive")),
+        falls_over: optional(integer(MIN_EXPIRES_IN, MAX_EVERY, `seconds each order's ask takes to fall to min_receive; default ${SWAP_FALLS_OVER}`)),
+        pay_to: optional(account(PAY_TO)),
+        send: optional(flag("true signs and sends every order; leave out to preview")),
+    }),
+    output: object({
+        orders: list(object({ opens_at: time("when the order's ask starts to fall"), intent: optional(account()), nonce: optional(amount()), signature: optional(text()) }), MAX_RECURRING),
+        summary: list(text(), 24, "the whole plan, then the first order"),
+        warnings: list(text(), 16),
+        start_receive: text("whole tokens each order asks when it opens; pass it back when sending"),
+        sent: flag(),
+        next: optional(text()),
+    }),
+    run: async (ctx, input, call) => {
+        const wallet = access(ctx);
+        const inputMint = mintNamed(input.sell, wallet.url, "sell");
+        const outputMint = mintNamed(input.buy, wallet.url, "buy");
+        const [inputToken, outputToken, now] = await Promise.all([
+            mintOf(ctx.transport, inputMint),
+            mintOf(ctx.transport, outputMint),
+            chainTime(ctx.transport),
+        ]);
+        const amountIn = raw(input.amount, inputToken.decimals, "amount");
+        const floor = raw(input.min_receive, outputToken.decimals, "min_receive");
+        const ask = input.start_receive === undefined
+            ? openingAsk(await recentFills(ctx.transport, inputMint, outputMint), amountIn, floor)
+            : raw(input.start_receive, outputToken.decimals, "start_receive");
+        if (ask <= floor) {
+            throw new InvalidInput([
+                input.start_receive === undefined ? { path: "min_receive", message: NO_FALL } : { path: "start_receive", message: "must be more than min_receive, or the order has no ask to fall" },
+            ]);
+        }
+        checkSale(wallet.limits, inputMint, inputToken.decimals, amountIn, now);
+        checkHour(wallet.limits, inputMint, inputToken.decimals, amountIn * BigInt(input.times), now);
+        const falls = BigInt(input.falls_over ?? SWAP_FALLS_OVER);
+        const every = BigInt(input.every);
+        const life = falls > every ? falls : every;
+        const opens = Array.from({ length: input.times }, (_, k) => now + BigInt(LANDING_SECONDS) + every * BigInt(k));
+        const terms = (open) => () => ({
+            order: { kind: "dutch", amount_in: amountIn, start_out: ask, end_out: floor, start_time: open, end_time: open + falls },
+            expires_at: open + life,
+        });
+        const shown = { start_receive: formatAmount(ask, outputToken.decimals) };
+        const last = opens[opens.length - 1];
+        const first = (await offered(ctx, call, { ...input, send: input.send }, terms(opens[0])));
+        const sold = TOKEN_NAMES[inputMint] ?? inputMint;
+        const plan = [
+            `Plan: ${input.times} orders of ${formatAmount(amountIn, inputToken.decimals)} of ${sold}, ${formatAmount(amountIn * BigInt(input.times), inputToken.decimals)} of ${sold} in all, escrowed now`,
+            `Schedule: the orders open from ${formatTime(opens[0])} to ${formatTime(last)}; the last expires ${formatTime(last + life)}`,
+            ...first["summary"],
+        ];
+        const warned = first["warnings"];
+        const warnings = [
+            ...warned,
+            WARN_EARLY,
+            ...(last + life - now > LONG_LIVED_SECONDS && !warned.includes(WARN_LONG_LIVED) ? [WARN_LONG_LIVED] : []),
+        ];
+        if (input.send !== true) {
+            return { orders: opens.map((opens_at) => ({ opens_at })), summary: plan, warnings, ...shown, sent: false, next: first["next"] };
+        }
+        const orders = [{ opens_at: opens[0], intent: first["intent"], nonce: first["nonce"], signature: first["signature"] }];
+        for (const open of opens.slice(1)) {
+            try {
+                const made = (await offered(ctx, call, { ...input, send: true }, terms(open)));
+                orders.push({ opens_at: open, intent: made["intent"], nonce: made["nonce"], signature: made["signature"] });
+            }
+            catch (error) {
+                for (const undo of call.undo.splice(0)) {
+                    undo();
+                }
+                const problem = problemOf(error);
+                return {
+                    orders: [...orders, ...opens.slice(orders.length).map((opens_at) => ({ opens_at }))],
+                    summary: plan,
+                    warnings,
+                    ...shown,
+                    sent: true,
+                    next: refusedBeforeSending(error)
+                        ? partlySent(orders.length, input.times, `${problem.code}: ${problem.hint}`)
+                        : mayHaveLanded(orders.length, input.times, `${problem.code}: ${problem.hint}`),
+                };
+            }
+        }
+        return { orders, summary: plan, warnings, ...shown, sent: true };
+    },
 });
 const walletAuction = define({
     name: tool("wallet_auction"),
@@ -273,6 +640,7 @@ const walletAuction = define({
         end_receive: text("least whole tokens accepted once the asked amount stops falling"),
         falls_over: integer(MIN_EXPIRES_IN, MAX_EXPIRES_IN, "seconds the asked amount takes to fall from start_receive to end_receive"),
         expires_in: optional(integer(MIN_EXPIRES_IN, MAX_EXPIRES_IN, `least seconds the offer stays open once sent, never less than falls_over; default ${DEFAULT_EXPIRES_IN}`)),
+        pay_to: optional(account(PAY_TO)),
         send: optional(flag("true signs and sends; leave out to preview")),
     }),
     output: offerOutput,
@@ -306,7 +674,7 @@ const walletIntents = define({
 const walletCancel = define({
     name: tool("wallet_cancel"),
     title: "Cancel a wallet intent",
-    description: "Cancel an open intent of this server's wallet by its nonce: the escrow returns to the wallet and the intent account closes, returning its rent. Without send it only previews; call again with send: true once the user approves.",
+    description: "Cancel an open intent of this server's wallet by its nonce: the escrow returns to the wallet's token account (wrapped SOL for SOL) and the intent account closes, returning its rent. Without send it only previews; call again with send: true once the user approves.",
     effect: "submit",
     input: object({ nonce: amount("the intent's nonce, from wallet_intents"), send: optional(flag("true signs and sends; leave out to preview")) }),
     output: object({
@@ -328,7 +696,11 @@ async function engineHistory(transport, limit, of) {
     const created = new Map();
     const fills = [];
     const ended = new Map();
+    let unread = 0;
     for (const tx of await transport.engineTransactions(limit, of)) {
+        if (tx.unread === true) {
+            unread += 1;
+        }
         if (tx.failed) {
             continue;
         }
@@ -354,7 +726,7 @@ async function engineHistory(transport, limit, of) {
             }
         }
     }
-    return { created, fills, ended };
+    return { created, fills, ended, unread };
 }
 function pairOf(data) {
     try {
@@ -365,7 +737,7 @@ function pairOf(data) {
         return null;
     }
 }
-export const ESTIMATE_NEXT = "solvers pay the least an intent asks, so these fills show what owners asked and got, not the most a solver would pay; ask a minimum near receive_at_best, or auction from a little above it down to the least the user accepts to find the price";
+export const ESTIMATE_NEXT = "solvers pay the least an intent asks, so these fills show what owners asked and got, not the most a solver would pay; ask a minimum near receive_at_median, since a single fill can be staged by one party on both sides, or auction from a little above it down to the least the user accepts to find the price";
 export const NO_FILLS = `no recent fill sold this token for that one; auction from a high ask down to the least the user accepts with ${tool("wallet_auction")} to find the price`;
 const walletEstimate = define({
     name: tool("wallet_estimate"),
@@ -384,7 +756,8 @@ const walletEstimate = define({
             at: optional(time("when the fill landed")),
             signature: text(),
         }), ESTIMATE_FILLS, "newest first"),
-        receive_at_best: optional(text("whole tokens amount would get at the best recent rate")),
+        receive_at_best: optional(text("whole tokens amount would get at the best recent rate; one fill can be staged by its own two sides")),
+        receive_at_median: optional(text("whole tokens amount would get at the median recent rate")),
         receive_at_latest: optional(text("whole tokens amount would get at the newest fill's rate")),
         next: text(),
     }),
@@ -394,19 +767,7 @@ const walletEstimate = define({
         const outputMint = mintNamed(input.buy, wallet.url, "buy");
         const [inputToken, outputToken] = await Promise.all([mintOf(ctx.transport, inputMint), mintOf(ctx.transport, outputMint)]);
         const amount = raw(input.amount, inputToken.decimals, "amount");
-        const { created, fills } = await engineHistory(ctx.transport, ESTIMATE_SCAN);
-        const unknown = [...new Set(fills.map((f) => f.intent).filter((intent) => !created.has(intent)))];
-        const views = unknown.length === 0 ? [] : await ctx.transport.getAccounts(unknown);
-        unknown.forEach((intent, i) => {
-            const view = views[i];
-            const pair = view === null || view === undefined ? null : pairOf(view.data);
-            if (pair !== null) {
-                created.set(intent, pair);
-            }
-        });
-        const matching = fills
-            .filter((f) => f.amountIn > 0n && created.get(f.intent)?.inputMint === inputMint && created.get(f.intent)?.outputMint === outputMint)
-            .slice(0, ESTIMATE_FILLS);
+        const matching = await recentFills(ctx.transport, inputMint, outputMint);
         const shown = matching.map((f) => ({
             sold: formatAmount(f.amountIn, inputToken.decimals),
             received: formatAmount(f.delivered, outputToken.decimals),
@@ -417,17 +778,18 @@ const walletEstimate = define({
         if (latest === undefined) {
             return { fills: shown, next: NO_FILLS };
         }
-        const best = matching.reduce((a, b) => (b.delivered * a.amountIn > a.delivered * b.amountIn ? b : a));
+        const best = bestOf(matching) ?? latest;
         const at = (f) => formatAmount((amount * f.delivered) / f.amountIn, outputToken.decimals);
-        return { fills: shown, receive_at_best: at(best), receive_at_latest: at(latest), next: ESTIMATE_NEXT };
+        return { fills: shown, receive_at_best: at(best), receive_at_median: at(medianOf(matching) ?? latest), receive_at_latest: at(latest), next: ESTIMATE_NEXT };
     },
 });
 export const WAIT_STATUS = ["open", "filling", "filled", "cancelled", "expired", "closed"];
+export const UNREAD = `the node could not yet return all of this intent's transactions, so whether it filled is unknown; call ${tool("wallet_wait")} again in a few seconds before acting on it`;
 export const stillWaiting = (status) => `still ${status}; call ${tool("wallet_wait")} again to keep waiting, or ${tool("wallet_cancel")} to take the escrow back`;
 const walletWait = define({
     name: tool("wallet_wait"),
     title: "Wait for a wallet intent",
-    description: `Wait until an intent of this server's wallet is filled, cancelled or expired, or until within seconds pass, then say which and, for a fill, how much the wallet received. Use it after sending instead of asking the user to check again; call it again while the status is still open.`,
+    description: `Wait until an intent of this server's wallet is filled, cancelled or expired, or until within seconds pass, then say which and, for a fill, how much it delivered to this wallet or to the pay_to it named. Use it after sending instead of asking the user to check again; call it again while the status is still open.`,
     effect: "read",
     input: object({
         nonce: amount("the intent's nonce, from the send or wallet_intents"),
@@ -437,7 +799,7 @@ const walletWait = define({
         intent: account(),
         status: choice(WAIT_STATUS, "closed means the account is gone and its recent transactions name no fill, cancel or expiry"),
         waited: integer(0, WAIT_MAX, "seconds waited"),
-        received: optional(text("whole tokens the wallet received from fills")),
+        received: optional(text("whole tokens the fills delivered, to this wallet or the pay_to it named")),
         token: optional(text("the token received")),
         signature: optional(text("the fill's transaction")),
         next: optional(text()),
@@ -448,6 +810,7 @@ const walletWait = define({
         const [intent] = await findIntentPda({ owner, nonce: input.nonce });
         const within = input.within ?? WAIT_DEFAULT;
         const fresh = unmemoized(ctx.transport);
+        const deadline = wallet.now() + BigInt(within);
         let waited = 0;
         let pair = null;
         let status = "closed";
@@ -460,7 +823,7 @@ const walletWait = define({
             const decoded = getIntentDecoder().decode(view.data);
             pair = { inputMint: decoded.inputMint, outputMint: decoded.outputMint };
             status = STATUS[decoded.status] ?? "open";
-            if ((status !== "open" && status !== "filling") || waited >= within || !(await wallet.sleep(1))) {
+            if ((status !== "open" && status !== "filling") || waited >= within || wallet.now() >= deadline || !(await wallet.sleep(1))) {
                 break;
             }
             waited += 1;
@@ -474,7 +837,8 @@ const walletWait = define({
         const history = await engineHistory(ctx.transport, WAIT_SCAN, intent);
         const fills = history.fills.filter((f) => f.intent === intent);
         if (fills.length === 0) {
-            return { intent, status: status === "closed" ? (history.ended.get(intent) ?? status) : status, waited };
+            const ended = status === "closed" ? (history.ended.get(intent) ?? status) : status;
+            return { intent, status: ended, waited, ...(ended === "closed" && history.unread > 0 ? { next: UNREAD } : {}) };
         }
         pair ??= history.created.get(intent) ?? null;
         const decimals = pair === null ? undefined : (await mintOf(ctx.transport, pair.outputMint)).decimals;
@@ -488,13 +852,85 @@ const walletWait = define({
         };
     },
 });
+export const NOT_RELEASED = `no release of this escrow is among its recent transactions; ${tool("wallet_wait")} or ${tool("wallet_intents")} shows whether it is still open`;
+const walletReceipt = define({
+    name: tool("wallet_receipt"),
+    title: "Check an escrow's release",
+    description: `Look up whether an escrow made with ${tool("wallet_escrow")} was released: to whom, for how much, by which attestor, and which delivered work the release recorded. Give sha256, the hash of the work you received, to check it is the work that was paid for. It reads the escrow's own transactions and sends nothing.`,
+    effect: "read",
+    input: object({
+        owner: optional(account("the wallet that made the escrow; default this server's wallet")),
+        nonce: amount("the escrow intent's nonce"),
+        sha256: optional(text("the sha256, as 64 hex digits, of the work you received, to compare with the one the release recorded")),
+    }),
+    output: object({
+        intent: account(),
+        released: flag(),
+        paid_to: optional(account("the wallet the release paid")),
+        payee: optional(account("the token account the release paid")),
+        paid: optional(text("whole tokens the payee received")),
+        attestor: optional(account()),
+        result: optional(amount()),
+        signature: optional(text("the release's transaction")),
+        delivered_sha256: optional(text("the sha256 the release recorded, if any")),
+        matches: optional(flag("whether sha256 equals the recorded one")),
+        next: optional(text()),
+    }),
+    run: async (ctx, input) => {
+        const owner = input.owner ?? (await signerOf(ctx)).address;
+        const wanted = input.sha256 === undefined ? undefined : sha256Of(input.sha256, "sha256");
+        const [intent] = await findIntentPda({ owner, nonce: input.nonce });
+        const transactions = await ctx.transport.engineTransactions(WAIT_SCAN, intent);
+        let mint;
+        for (const tx of transactions) {
+            for (const event of tx.emitted.map(decodeEvent)) {
+                const fields = (event?.fields ?? {});
+                if (event?.name === "IntentCreated" && fields["intent"] === intent) {
+                    mint = fields["inputMint"];
+                }
+            }
+        }
+        for (const tx of transactions) {
+            if (tx.failed) {
+                continue;
+            }
+            const release = tx.emitted.map(decodeEvent).find((event) => event?.name === "IntentAttested" && event.fields["intent"] === intent);
+            if (release === undefined || release === null) {
+                continue;
+            }
+            const fields = release.fields;
+            const payee = fields["payee"];
+            const held = await ctx.transport.getAccount(payee);
+            mint ??= held === null || held.data.length < 64 ? undefined : getAddressDecoder().decode(held.data.subarray(0, 32));
+            const decimals = mint === undefined ? undefined : (await mintOf(ctx.transport, mint)).decimals;
+            const recorded = (tx.memos ?? []).map((memo) => DELIVERY_MEMO.exec(memo)?.[1]).find((hash) => hash !== undefined);
+            return {
+                intent,
+                released: true,
+                ...(held === null || held.data.length < 64 ? {} : { paid_to: getAddressDecoder().decode(held.data.subarray(32, 64)) }),
+                payee,
+                paid: formatAmount(fields["net"], decimals),
+                attestor: fields["attestor"],
+                result: fields["result"],
+                signature: tx.signature,
+                ...(recorded === undefined ? {} : { delivered_sha256: recorded }),
+                ...(wanted === undefined ? {} : { matches: wanted === recorded }),
+            };
+        }
+        return { intent, released: false, next: NOT_RELEASED };
+    },
+});
 export const WALLET_ACTIONS = [
     walletSetup,
     walletBalance,
     walletEstimate,
     walletSwap,
     walletAuction,
+    walletRecurring,
+    walletEscrow,
+    walletAttest,
     walletWait,
+    walletReceipt,
     walletIntents,
     walletCancel,
 ];