@intent-engine/cli 0.1.14 → 0.1.16

package/dist/src/agent/wallet.js

@@ -1,9 +1,11 @@
-import { attestedFillMessage, buildFillAttested, decodeEvent, decodeParams, feeBpsFor, findIntentPda, formatAmount, getIntentDecoder, IntentStatus, Kind, parseAmount, signEd25519Instruction, splitFees, WARN_ATTESTOR, } from "@intent-engine/core";
+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 { NATIVE_MINT, TOKEN_NAMES, tokenNamed } from "../tokens.js";
-import { neverLanded, unmemoized } from "../transport.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, WRAPPED } from "./create.js";
@@ -255,6 +257,7 @@ 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)))];
@@ -270,16 +273,21 @@ async function recentFills(transport, inputMint, outputMint) {
         .filter((f) => f.amountIn > 0n && created.get(f.intent)?.inputMint === inputMint && created.get(f.intent)?.outputMint === outputMint)
         .slice(0, ESTIMATE_FILLS);
 }
-const bestOf = (fills) => fills.reduce((a, b) => (a === undefined || b.delivered * a.amountIn > a.delivered * b.amountIn ? b : a), undefined);
+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 best = bestOf(fills);
-    const ask = best === undefined ? (floor * (10000n + SWAP_BLIND_BPS)) / 10000n : (amount * best.delivered * (10000n + SWAP_HEADROOM_BPS)) / (best.amountIn * 10000n);
-    return ask > floor ? ask : 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: `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 best recent fill, 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.`,
+    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({
@@ -287,7 +295,7 @@ 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 best recent fill")),
+        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)),
@@ -338,7 +346,7 @@ function recordedMint(sell, url, chosen) {
 const walletEscrow = define({
     name: tool("wallet_escrow"),
     title: "Escrow a payment for an attestor to release",
-    description: `Lock 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. 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.`,
+    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({
@@ -366,17 +374,118 @@ const walletEscrow = define({
         }));
     },
 });
+export const MAX_PIECES = 12;
+export const piecesPartlySent = (sent, total, problem) => `${sent} of ${total} pieces were escrowed; the next failed with ${problem}. To finish, escrow only the ${total - sent} remaining pieces; do not repeat this call`;
+export const piecesMayHaveLanded = (sent, total, problem) => `${sent} of ${total} pieces were escrowed and the next may have landed too (${problem}); check ${tool("wallet_intents")} before escrowing any again, and do not repeat this call`;
+const walletEscrowPlan = define({
+    name: tool("wallet_escrow_plan"),
+    title: "Escrow a task's pieces in one plan",
+    description: `Split a task into pieces and escrow each piece's payment from this server's wallet in one call, each as ${tool("wallet_escrow")} would: every piece is its own escrow that its attestor releases on its own, to whichever wallet it signs for, so workers are paid as each piece passes. One preview shows every piece and the total; one send escrows them all. A piece not yet released can be cancelled on its own with ${tool("wallet_cancel")}. Have workers deliver to the attestor rather than to this wallet. Amounts are whole tokens. 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"),
+        attestor: account("the wallet that releases every piece that names no attestor of its own"),
+        pieces: list(object({
+            name: text("a label for the piece, shown in the plan only"),
+            amount: text("whole tokens this piece pays, such as 0.01"),
+            attestor: optional(account("this piece's attestor, instead of the plan's")),
+        }), MAX_PIECES, "the pieces, in order", 2),
+        expires_in: optional(integer(MIN_EXPIRES_IN, MAX_EXPIRES_IN, `least seconds each escrow stays open once sent; default ${ESCROW_EXPIRES_IN}`)),
+        record_mint: optional(text("a token the escrows record as their output, other than sell; only a label. Default SOL, or TEST when selling SOL on devnet")),
+        send: optional(flag("true signs and sends every piece; leave out to preview")),
+    }),
+    output: object({
+        pieces: list(object({ name: text(), amount: text(), attestor: account(), intent: optional(account()), nonce: optional(amount()), signature: optional(text()) }), MAX_PIECES),
+        total: text("whole tokens escrowed across all pieces"),
+        summary: list(text(), 24, "the plan, then the first piece"),
+        warnings: list(text(), 16),
+        sent: flag(),
+        next: optional(text()),
+    }),
+    run: async (ctx, input, call) => {
+        const wallet = access(ctx);
+        const sold = mintNamed(input.sell, wallet.url, "sell");
+        const buy = recordedMint(sold, wallet.url, input.record_mint);
+        const [token, now] = await Promise.all([mintOf(ctx.transport, sold), chainTime(ctx.transport)]);
+        const planned = input.pieces.map((piece, i) => ({
+            name: piece.name,
+            amountIn: raw(piece.amount, token.decimals, `pieces.${i}.amount`),
+            attestor: piece.attestor ?? input.attestor,
+        }));
+        const total = planned.reduce((sum, piece) => sum + piece.amountIn, 0n);
+        for (const piece of planned) {
+            checkSale(wallet.limits, sold, token.decimals, piece.amountIn, now);
+        }
+        checkHour(wallet.limits, sold, token.decimals, total, now);
+        const terms = (piece) => (_sold, _bought, at) => ({
+            order: { kind: "attested", amount_in: piece.amountIn, min_result: 1n, max_result: 1n, attestor: piece.attestor },
+            expires_at: at + BigInt((input.expires_in ?? ESCROW_EXPIRES_IN) + LANDING_SECONDS),
+        });
+        const name = TOKEN_NAMES[sold] ?? sold;
+        const listed = (piece) => ({ name: piece.name, amount: formatAmount(piece.amountIn, token.decimals), attestor: piece.attestor });
+        const [head, ...rest] = planned;
+        const first = (await offered(ctx, call, { sell: sold, buy, send: input.send }, terms(head)));
+        const shown = {
+            total: formatAmount(total, token.decimals),
+            summary: [
+                `Plan: ${planned.length} pieces, ${formatAmount(total, token.decimals)} of ${name} in all, each escrowed now and released on its own`,
+                ...planned.map((piece, i) => `Piece ${i + 1}: ${piece.name}, ${formatAmount(piece.amountIn, token.decimals)} of ${name}, released by ${piece.attestor}`),
+                ...first["summary"],
+            ],
+            warnings: first["warnings"],
+        };
+        if (input.send !== true) {
+            return { pieces: planned.map(listed), ...shown, sent: false, next: first["next"] };
+        }
+        const pieces = [{ ...listed(head), intent: first["intent"], nonce: first["nonce"], signature: first["signature"] }];
+        for (const piece of rest) {
+            try {
+                const made = (await offered(ctx, call, { sell: sold, buy, send: true }, terms(piece)));
+                pieces.push({ ...listed(piece), intent: made["intent"], nonce: made["nonce"], signature: made["signature"] });
+            }
+            catch (error) {
+                for (const undo of call.undo.splice(0)) {
+                    undo();
+                }
+                const problem = problemOf(error);
+                const reason = `${problem.code}: ${problem.hint}`;
+                return {
+                    pieces: [...pieces, ...planned.slice(pieces.length).map(listed)],
+                    ...shown,
+                    sent: true,
+                    next: refusedBeforeSending(error) ? piecesPartlySent(pieces.length, planned.length, reason) : piecesMayHaveLanded(pieces.length, planned.length, reason),
+                };
+            }
+        }
+        return { pieces, ...shown, sent: true };
+    },
+});
+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, 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. Without send it only previews and signs nothing; show the user the summary and call again with send: true once they approve.`,
+    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({
@@ -386,6 +495,8 @@ const walletAttest = define({
         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(),
@@ -420,13 +531,21 @@ const walletAttest = define({
         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 partner = shares.partner > 0n ? await tokenAccountIfMissing(ctx.transport, signer, held.partner, 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,
@@ -445,7 +564,7 @@ const walletAttest = define({
             inputTokenProgram: token.tokenProgram,
             payee: payee.address,
             ...(shares.protocol > 0n ? { feeRecipient: config.feeRecipient } : {}),
-            ...(held.partnerBps === 0 ? {} : { partner: held.partner }),
+            ...(partnerPaid ? { partner: held.partner } : {}),
             amountIn,
             result,
             maxFeeBps,
@@ -453,8 +572,17 @@ const walletAttest = define({
         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], signer.address))
+            ? preparedView(await prepare(ctx.transport, [...setup, await signEd25519Instruction(signer, message), settle, ...memo], signer.address))
             : undefined;
         const view2 = {
             intent,
@@ -463,9 +591,12 @@ const walletAttest = define({
             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`]),
@@ -477,12 +608,16 @@ const walletAttest = define({
     },
 });
 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`;
+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, a little above the best recent fill, 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. 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.`,
+    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({
@@ -492,14 +627,14 @@ const walletRecurring = define({
         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 when it opens; default a little above the best recent fill")),
+        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 first order"),
+        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(),
@@ -520,7 +655,9 @@ const walletRecurring = define({
             ? openingAsk(await recentFills(ctx.transport, inputMint, outputMint), amountIn, floor)
             : raw(input.start_receive, outputToken.decimals, "start_receive");
         if (ask <= floor) {
-            throw new InvalidInput([{ path: "start_receive", message: "must be more than min_receive, or the order has no ask to fall" }]);
+            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);
@@ -533,10 +670,22 @@ const walletRecurring = define({
             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) {
-            const { summary, warnings, next } = first;
-            return { orders: opens.map((opens_at) => ({ opens_at })), summary, warnings, ...shown, sent: false, next };
+            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)) {
@@ -551,17 +700,17 @@ const walletRecurring = define({
                 const problem = problemOf(error);
                 return {
                     orders: [...orders, ...opens.slice(orders.length).map((opens_at) => ({ opens_at }))],
-                    summary: first["summary"],
-                    warnings: first["warnings"],
+                    summary: plan,
+                    warnings,
                     ...shown,
                     sent: true,
-                    next: neverLanded(error)
-                        ? `${orders.length} of ${input.times} orders were sent; the next failed with ${problem.code}: ${problem.hint}`
+                    next: refusedBeforeSending(error)
+                        ? partlySent(orders.length, input.times, `${problem.code}: ${problem.hint}`)
                         : mayHaveLanded(orders.length, input.times, `${problem.code}: ${problem.hint}`),
                 };
             }
         }
-        return { orders, summary: first["summary"], warnings: first["warnings"], ...shown, sent: true };
+        return { orders, summary: plan, warnings, ...shown, sent: true };
     },
 });
 const walletAuction = define({
@@ -612,7 +761,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({
@@ -634,7 +783,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;
         }
@@ -660,7 +813,7 @@ async function engineHistory(transport, limit, of) {
             }
         }
     }
-    return { created, fills, ended };
+    return { created, fills, ended, unread };
 }
 function pairOf(data) {
     try {
@@ -671,7 +824,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"),
@@ -690,7 +843,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(),
     }),
@@ -713,15 +867,16 @@ const walletEstimate = define({
         }
         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"),
@@ -769,7 +924,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;
@@ -783,6 +939,74 @@ 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,
@@ -791,8 +1015,10 @@ export const WALLET_ACTIONS = [
     walletAuction,
     walletRecurring,
     walletEscrow,
+    walletEscrowPlan,
     walletAttest,
     walletWait,
+    walletReceipt,
     walletIntents,
     walletCancel,
 ];