@intent-engine/cli 0.1.10 → 0.1.14

package/dist/src/agent/wallet.js

@@ -1,18 +1,28 @@
-import { parseAmount } from "@intent-engine/core";
-import { chainTime, CLOCK_SYSVAR, mintOf } from "../accounts.js";
+import { attestedFillMessage, buildFillAttested, decodeEvent, decodeParams, feeBpsFor, findIntentPda, formatAmount, getIntentDecoder, IntentStatus, Kind, parseAmount, signEd25519Instruction, splitFees, WARN_ATTESTOR, } 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 { tokenNamed } from "../tokens.js";
+import { NATIVE_MINT, TOKEN_NAMES, tokenNamed } from "../tokens.js";
+import { 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 } from "./schema.js";
-import { orderSchema } from "./shapes.js";
+import { InvalidInput, account, amount, choice, flag, integer, list, object, optional, text, time } from "./schema.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: [] });
+export const SALE_WINDOW = 3600n;
+export const ESTIMATE_SCAN = 12;
+export const ESTIMATE_FILLS = 5;
+export const WAIT_DEFAULT = 30;
+export const WAIT_MAX = 40;
+export const WAIT_SCAN = 10;
 export const DEFAULT_EXPIRES_IN = 3_600;
 export const LANDING_SECONDS = 10;
 export const MAINNET_GENESIS = "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d";
@@ -20,7 +30,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`;
@@ -86,6 +96,62 @@ function raw(tokens, decimals, path) {
         throw new InvalidInput([{ path, message: error instanceof Error ? error.message : String(error) }]);
     }
 }
+const nameOf = (mint) => TOKEN_NAMES[mint] ?? mint;
+const limited = (guard) => guard.limits.perTrade.size + guard.limits.perHour.size > 0;
+export function limitLines(limits) {
+    const mints = [...new Set([...limits.perTrade.keys(), ...limits.perHour.keys()])];
+    if (mints.length === 0) {
+        return [];
+    }
+    return [
+        "Whoever started this server set sell limits that no tool call can change:",
+        ...mints.map((mint) => {
+            const caps = [
+                ...(limits.perTrade.has(mint) ? [`${limits.perTrade.get(mint)} per trade`] : []),
+                ...(limits.perHour.has(mint) ? [`${limits.perHour.get(mint)} per hour`] : []),
+            ];
+            return `- ${nameOf(mint)}: at most ${caps.join(" and ")}`;
+        }),
+        "It sells no other token. Plan trades within these limits and tell the user when a request exceeds them.",
+    ];
+}
+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;
+    }
+    const { perTrade, perHour } = guard.limits;
+    const name = nameOf(mint);
+    if (!perTrade.has(mint) && !perHour.has(mint)) {
+        const allowed = [...new Set([...perTrade.keys(), ...perHour.keys()])].map(nameOf).join(", ");
+        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, 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`);
+    }
+    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, 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)}`);
+    }
+}
 async function sent(ctx, signer, view, send, call) {
     for (const undo of call.undo.splice(0)) {
         undo();
@@ -139,7 +205,7 @@ export const walletBalance = define({
         return balances(ctx.transport, owner, mints);
     },
 });
-const offerOutput = object({
+const offerFields = {
     intent: account(),
     nonce: amount(),
     summary: list(text(), 24),
@@ -147,7 +213,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);
@@ -162,14 +229,57 @@ async function offered(ctx, call, input, terms) {
         mintOf(ctx.transport, outputMint),
         chainTime(ctx.transport),
     ]);
-    const view = (await prepareCreate.run(ctx, { owner: signer.address, input_mint: inputMint, output_mint: outputMint, ...terms(inputToken, outputToken, now) }, call));
+    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, ...(input.pay_to === undefined ? {} : { pay_to: input.pay_to }), ...made }, call));
     const { intent, nonce, summary, warnings, prepared } = view;
-    return sent(ctx, signer, { intent, nonce, summary, warnings, prepared }, input.send, call);
+    const sold = made.order.amount_in;
+    const guard = wallet.limits;
+    checkSale(guard, inputMint, inputToken.decimals, sold, now);
+    if (input.send !== true || !limited(guard)) {
+        return sent(ctx, signer, { intent, nonce, summary, warnings, prepared }, input.send, call);
+    }
+    const sale = { mint: inputMint, at: now, amount: sold };
+    guard.sales.push(sale);
+    try {
+        return await sent(ctx, signer, { intent, nonce, summary, warnings, prepared }, input.send, call);
+    }
+    catch (error) {
+        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;
+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 bestOf = (fills) => fills.reduce((a, b) => (a === undefined || b.delivered * a.amountIn > a.delivered * b.amountIn ? b : a), undefined);
+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 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 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.`,
     effect: "submit",
     repeats: true,
     input: object({
@@ -177,18 +287,282 @@ 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")),
+        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: `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.`,
+    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 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.`,
+    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")),
+        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(),
+        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);
+        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 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 } : {}),
+            ...(held.partnerBps === 0 ? {} : { 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 prepared = input.send === true
+            ? preparedView(await prepare(ctx.transport, [...setup, await signEd25519Instruction(signer, message), settle], signer.address))
+            : undefined;
+        const view2 = {
+            intent,
+            pay_to: input.pay_to,
+            payee: payee.address,
+            paid,
+            fee: formatAmount(shares.protocol + shares.partner, token.decimals),
+            result,
+            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`,
+                ...(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`;
+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.`,
+    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 when it opens; default a little above the best recent fill")),
+        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"),
+        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([{ 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 first = (await offered(ctx, call, { ...input, send: input.send }, terms(opens[0])));
+        if (input.send !== true) {
+            const { summary, warnings, next } = first;
+            return { orders: opens.map((opens_at) => ({ opens_at })), summary, warnings, ...shown, sent: false, 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: first["summary"],
+                    warnings: first["warnings"],
+                    ...shown,
+                    sent: true,
+                    next: neverLanded(error)
+                        ? `${orders.length} of ${input.times} orders were sent; the next failed with ${problem.code}: ${problem.hint}`
+                        : mayHaveLanded(orders.length, input.times, `${problem.code}: ${problem.hint}`),
+                };
+            }
+        }
+        return { orders, summary: first["summary"], warnings: first["warnings"], ...shown, sent: true };
+    },
 });
 const walletAuction = define({
     name: tool("wallet_auction"),
@@ -204,6 +578,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,
@@ -255,5 +630,170 @@ const walletCancel = define({
         return sent(ctx, signer, view, input.send, call);
     },
 });
-export const WALLET_ACTIONS = [walletSetup, walletBalance, walletSwap, walletAuction, walletIntents, walletCancel];
+async function engineHistory(transport, limit, of) {
+    const created = new Map();
+    const fills = [];
+    const ended = new Map();
+    for (const tx of await transport.engineTransactions(limit, of)) {
+        if (tx.failed) {
+            continue;
+        }
+        const begun = new Map();
+        for (const event of tx.emitted.map(decodeEvent)) {
+            if (event === null) {
+                continue;
+            }
+            const fields = event.fields;
+            const intent = fields["intent"];
+            if (event.name === "IntentCreated") {
+                created.set(intent, { inputMint: fields["inputMint"], outputMint: fields["outputMint"] });
+            }
+            if (event.name === "FillBegun") {
+                begun.set(intent, fields["amountIn"]);
+            }
+            const amountIn = event.name === "IntentFilled" ? fields["amountIn"] : event.name === "FillEnded" ? begun.get(intent) : undefined;
+            if (amountIn !== undefined) {
+                fills.push({ intent, amountIn, delivered: fields["delivered"], signature: tx.signature, blockTime: tx.blockTime });
+            }
+            if (event.name === "IntentCancelled" || event.name === "IntentExpired") {
+                ended.set(intent, event.name === "IntentCancelled" ? "cancelled" : "expired");
+            }
+        }
+    }
+    return { created, fills, ended };
+}
+function pairOf(data) {
+    try {
+        const { inputMint, outputMint } = getIntentDecoder().decode(data);
+        return { inputMint, outputMint };
+    }
+    catch {
+        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 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"),
+    title: "Estimate a swap from recent fills",
+    description: `Estimate what selling an amount of one token for another gets now, from the rates of recent fills of the same pair on this cluster. It reads the engine's last ${ESTIMATE_SCAN} transactions and sends nothing. Use it before ${tool("wallet_swap")} or ${tool("wallet_auction")} to pick min_receive or the auction's start and end.`,
+    effect: "read",
+    input: object({
+        sell: text("SOL, TEST or a mint address"),
+        buy: text("SOL, TEST or a mint address"),
+        amount: text("whole tokens to sell, such as 0.05"),
+    }),
+    output: object({
+        fills: list(object({
+            sold: text("whole tokens of the sold token"),
+            received: text("whole tokens the owner received"),
+            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_latest: optional(text("whole tokens amount would get at the newest fill's rate")),
+        next: text(),
+    }),
+    run: async (ctx, input) => {
+        const wallet = await testCluster(ctx);
+        const inputMint = mintNamed(input.sell, wallet.url, "sell");
+        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 matching = await recentFills(ctx.transport, inputMint, outputMint);
+        const shown = matching.map((f) => ({
+            sold: formatAmount(f.amountIn, inputToken.decimals),
+            received: formatAmount(f.delivered, outputToken.decimals),
+            ...(f.blockTime === null ? {} : { at: f.blockTime }),
+            signature: f.signature,
+        }));
+        const [latest] = matching;
+        if (latest === undefined) {
+            return { fills: shown, next: NO_FILLS };
+        }
+        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 };
+    },
+});
+export const WAIT_STATUS = ["open", "filling", "filled", "cancelled", "expired", "closed"];
+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.`,
+    effect: "read",
+    input: object({
+        nonce: amount("the intent's nonce, from the send or wallet_intents"),
+        within: optional(integer(1, WAIT_MAX, `most seconds to wait; default ${WAIT_DEFAULT}`)),
+    }),
+    output: object({
+        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 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()),
+    }),
+    run: async (ctx, input) => {
+        const wallet = access(ctx);
+        const owner = (await signerOf(ctx)).address;
+        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";
+        for (;;) {
+            const view = await fresh.getAccount(intent);
+            if (view === null) {
+                status = "closed";
+                break;
+            }
+            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 || wallet.now() >= deadline || !(await wallet.sleep(1))) {
+                break;
+            }
+            waited += 1;
+        }
+        if (status === "open" || status === "filling") {
+            return { intent, status, waited, next: stillWaiting(status) };
+        }
+        if (status === "cancelled" || status === "expired") {
+            return { intent, status, waited };
+        }
+        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 };
+        }
+        pair ??= history.created.get(intent) ?? null;
+        const decimals = pair === null ? undefined : (await mintOf(ctx.transport, pair.outputMint)).decimals;
+        return {
+            intent,
+            status: "filled",
+            waited,
+            received: formatAmount(fills.reduce((sum, f) => sum + f.delivered, 0n), decimals),
+            ...(pair === null ? {} : { token: nameOf(pair.outputMint) }),
+            signature: fills[0]?.signature,
+        };
+    },
+});
+export const WALLET_ACTIONS = [
+    walletSetup,
+    walletBalance,
+    walletEstimate,
+    walletSwap,
+    walletAuction,
+    walletRecurring,
+    walletEscrow,
+    walletAttest,
+    walletWait,
+    walletIntents,
+    walletCancel,
+];
 //# sourceMappingURL=wallet.js.map