@odatano/nightgate-mcp 0.8.0 → 0.9.0

package/dist/swap.d.ts

@@ -0,0 +1,76 @@
+import type { NightgateMcpConfig } from './config.js';
+export interface SwapLeg {
+    tokenType: string;
+    amount: string;
+}
+export interface SwapTermsOut {
+    gives: SwapLeg;
+    wants: SwapLeg;
+    inputs?: number;
+    outputs?: number;
+}
+interface TxSwapModule {
+    createSwapWallet: (opts: Record<string, unknown>) => Promise<any>;
+    readSwapTerms: (tx: unknown) => any;
+    decodeOffer: (input: string) => Promise<{
+        tx: unknown;
+        bound: boolean;
+        bytes: Uint8Array;
+    }>;
+}
+/** What an offer gives and wants, read from the transaction it carries. No wallet, no network. */
+export declare function readOffer(offer: string): Promise<SwapTermsOut & {
+    bound: boolean;
+    serializedBytes: number;
+}>;
+export declare function swapWalletInfo(config: NightgateMcpConfig): Promise<Record<string, unknown>>;
+export interface BuiltOffer {
+    id: string;
+    offer?: string;
+    halfB64: string;
+    bound: boolean;
+    serializedBytes: number;
+    terms: SwapTermsOut;
+    buildMs: number;
+}
+/** One half of a swap from this wallet; bound with its offer file unless `bind` is false. */
+export declare function buildOffer(config: NightgateMcpConfig, input: {
+    give: SwapLeg;
+    want: SwapLeg;
+    bind?: boolean;
+}): Promise<BuiltOffer>;
+export interface TakenOfferOut {
+    id: string;
+    makerHalfB64: string;
+    takerHalfB64: string;
+    bound: boolean;
+    terms: SwapTermsOut;
+    buildMs: number;
+}
+/** The mirror half of an offer from this wallet, after its terms were read and compared with `expect`. */
+export declare function takeOffer(config: NightgateMcpConfig, input: {
+    offer: string;
+    expect?: {
+        gives: SwapLeg;
+        wants: SwapLeg;
+    };
+}): Promise<TakenOfferOut>;
+/** Releases the coins of a half built here that is not going to be handed over. */
+export declare function revertHalf(config: NightgateMcpConfig, id: string): Promise<{
+    id: string;
+    reverted: true;
+}>;
+/** Both halves of an offer taken here, for a submission by id. */
+export declare function takenHalves(id: string): {
+    makerHalfB64: string;
+    takerHalfB64: string;
+};
+/** Remembers the sponsor job a half went into. An id this process does not hold is ignored. */
+export declare function trackHalfJob(id: string, jobId: unknown): void;
+/** A landed swap spent its coins: its half is no longer pending. A failed one stays, so it can be reverted. */
+export declare function settleHalfJob(jobId: string, status: unknown): void;
+/** Test seam / shutdown. */
+export declare function closeSwapWallet(): Promise<void>;
+/** Test seam: replace the module the swap functions load. */
+export declare function __setSwapModuleForTests(mod: TxSwapModule | undefined): void;
+export {};

package/dist/swap.js

@@ -0,0 +1,244 @@
+/**
+ * Shielded swaps, the local side: one wallet that holds the shielded coins of
+ * `NIGHTGATE_SEED_HEX` builds swap halves and takes offers. It wraps the swap
+ * wallet of `@odatano/nightgate-tx` (0.8.0 or later); the fee is the sponsor's,
+ * so the wallet needs neither NIGHT nor dust.
+ */
+import { createHash } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+let modulePromise;
+async function loadSwapModule() {
+    modulePromise ??= (async () => {
+        let tx;
+        try {
+            tx = await import('@odatano/nightgate-tx/txbuilder');
+        }
+        catch (err) {
+            modulePromise = undefined;
+            throw new Error('swaps need @odatano/nightgate-tx >= 0.8.0 next to the MCP server (npm install @odatano/nightgate-tx): ' +
+                (err instanceof Error ? err.message : String(err)));
+        }
+        if (typeof tx.createSwapWallet !== 'function' || typeof tx.decodeOffer !== 'function') {
+            modulePromise = undefined;
+            throw new Error('swaps need @odatano/nightgate-tx >= 0.8.0; the installed version has no swap wallet (npm install @odatano/nightgate-tx@latest)');
+        }
+        return { createSwapWallet: tx.createSwapWallet, readSwapTerms: tx.readSwapTerms, decodeOffer: tx.decodeOffer };
+    })();
+    return modulePromise;
+}
+function defaults(network) {
+    return {
+        indexerHttpUrl: `https://indexer.${network}.midnight.network/api/v4/graphql`,
+        indexerWsUrl: `wss://indexer.${network}.midnight.network/api/v4/graphql/ws`,
+    };
+}
+const termsOut = (terms) => ({
+    gives: { tokenType: String(terms.gives.tokenType), amount: String(terms.gives.amount) },
+    wants: { tokenType: String(terms.wants.tokenType), amount: String(terms.wants.amount) },
+    ...(Number.isInteger(terms.inputs) ? { inputs: terms.inputs } : {}),
+    ...(Number.isInteger(terms.outputs) ? { outputs: terms.outputs } : {}),
+});
+/** What an offer gives and wants, read from the transaction it carries. No wallet, no network. */
+export async function readOffer(offer) {
+    const { decodeOffer, readSwapTerms } = await loadSwapModule();
+    const decoded = await decodeOffer(offer);
+    return { ...termsOut(readSwapTerms(decoded.tx)), bound: decoded.bound, serializedBytes: decoded.bytes.length };
+}
+let open;
+/** Halves built here whose swap has not landed, by id. */
+const pending = new Map();
+const halfId = (halfB64) => createHash('sha256').update(Buffer.from(halfB64, 'base64')).digest('hex').slice(0, 32);
+async function readState(path) {
+    if (!path)
+        return undefined;
+    try {
+        const text = (await readFile(path, 'utf8')).trim();
+        return text.length > 0 ? text : undefined;
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return undefined;
+        throw new Error(`swap wallet state ${path} is not readable: ${err.message}`);
+    }
+}
+/** The state holds the wallet's coins: written next to itself, then renamed, readable by the owner only. */
+async function writeState(path, wallet) {
+    if (!path)
+        return;
+    const state = String(await wallet.serializeState());
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.part`;
+    await writeFile(tmp, state, { mode: 0o600 });
+    await rename(tmp, path);
+    await chmod(path, 0o600).catch(() => { });
+}
+async function openWallet(config) {
+    if (!config.seedHex) {
+        throw new Error('swaps need NIGHTGATE_SEED_HEX in the MCP server environment; it is never a tool argument');
+    }
+    open ??= (async () => {
+        try {
+            const { createSwapWallet } = await loadSwapModule();
+            const d = defaults(config.network);
+            const walletState = await readState(config.swapStateFile);
+            const wallet = await createSwapWallet({
+                seedHex: config.seedHex,
+                networkId: config.network,
+                indexerHttpUrl: config.indexerHttpUrl ?? d.indexerHttpUrl,
+                indexerWsUrl: config.indexerWsUrl ?? d.indexerWsUrl,
+                ...(config.nodeUrl ? { nodeUrl: config.nodeUrl } : {}),
+                ...(config.proofServerUrl ? { provingMode: 'server', proofServerUrl: config.proofServerUrl } : {}),
+                ...(config.swapMaxInputs ? { maxInputs: config.swapMaxInputs } : {}),
+                ...(walletState ? { walletState } : {}),
+            });
+            const entry = { wallet, synced: Promise.resolve(), isSynced: false, syncError: null, startedAt: Date.now(), resumed: !!walletState };
+            entry.synced = (async () => {
+                try {
+                    await wallet.sync();
+                    await writeState(config.swapStateFile, wallet).catch((err) => console.error(`nightgate-mcp: swap wallet state not saved: ${err.message}`));
+                    entry.isSynced = true;
+                }
+                catch (err) {
+                    entry.syncError = err instanceof Error ? err : new Error(String(err));
+                }
+            })();
+            return entry;
+        }
+        catch (err) {
+            open = undefined;
+            throw err;
+        }
+    })();
+    return open;
+}
+/** The wallet once it has caught up; a wallet that needs longer than `waitMs` says so instead of blocking the call. */
+async function syncedWallet(config, waitMs) {
+    const entry = await openWallet(config);
+    if (!entry.isSynced && !entry.syncError) {
+        await Promise.race([entry.synced, new Promise((resolve) => setTimeout(resolve, waitMs))]);
+    }
+    if (entry.syncError) {
+        open = undefined;
+        throw new Error(`the swap wallet could not sync: ${entry.syncError.message}`);
+    }
+    if (!entry.isSynced) {
+        const seconds = Math.round((Date.now() - entry.startedAt) / 1000);
+        throw new Error(`the swap wallet is still syncing its shielded coins (${seconds} s so far; a first sync from genesis takes about 5 minutes` +
+            `${config.swapStateFile ? '' : ', set NIGHTGATE_SWAP_STATE_FILE to resume after a restart'}); call again shortly`);
+    }
+    return entry.wallet;
+}
+/** How long a tool call waits for a wallet that is still syncing. */
+const SYNC_WAIT_MS = 20_000;
+export async function swapWalletInfo(config) {
+    const entry = await openWallet(config);
+    const { wallet } = entry;
+    const base = {
+        address: String(wallet.address),
+        coinPublicKey: String(wallet.coinPublicKey),
+        encryptionPublicKey: String(wallet.encryptionPublicKey),
+        network: config.network,
+        maxInputs: Number(wallet.maxInputs),
+        provingMode: String(wallet.provingMode),
+        synced: entry.isSynced,
+        resumedFromState: entry.resumed,
+    };
+    if (entry.syncError)
+        throw new Error(`the swap wallet could not sync: ${entry.syncError.message}`);
+    if (!entry.isSynced) {
+        await Promise.race([entry.synced, new Promise((resolve) => setTimeout(resolve, SYNC_WAIT_MS))]);
+        if (!entry.isSynced)
+            return { ...base, syncingSeconds: Math.round((Date.now() - entry.startedAt) / 1000) };
+    }
+    const coins = await wallet.coins();
+    const byType = new Map();
+    for (const c of coins) {
+        const t = byType.get(c.tokenType) ?? { balance: 0n, coins: 0 };
+        byType.set(c.tokenType, { balance: t.balance + c.amount, coins: t.coins + 1 });
+    }
+    const tokens = [];
+    for (const [tokenType, t] of byType) {
+        tokens.push({ tokenType, balance: t.balance.toString(), coins: t.coins, spendable: String(await wallet.spendable(tokenType)) });
+    }
+    const pendingHalves = [...pending.entries()].map(([id, p]) => ({ id, role: p.role, ...(p.jobId ? { jobId: p.jobId } : {}), ...p.terms }));
+    return { ...base, synced: true, tokens, pendingHalves };
+}
+/** One half of a swap from this wallet; bound with its offer file unless `bind` is false. */
+export async function buildOffer(config, input) {
+    const t0 = Date.now();
+    const wallet = await syncedWallet(config, SYNC_WAIT_MS);
+    const half = await wallet.buildHalf({ give: input.give, want: input.want, bind: input.bind !== false });
+    const terms = termsOut(half.terms);
+    const id = halfId(half.halfB64);
+    pending.set(id, { revert: half.revert, terms, role: 'maker' });
+    await writeState(config.swapStateFile, wallet).catch(() => { });
+    return {
+        id, ...(half.offer ? { offer: half.offer } : {}), halfB64: half.halfB64, bound: half.bound === true,
+        serializedBytes: Number(half.serializedBytes), terms, buildMs: Date.now() - t0,
+    };
+}
+/** The mirror half of an offer from this wallet, after its terms were read and compared with `expect`. */
+export async function takeOffer(config, input) {
+    const t0 = Date.now();
+    const wallet = await syncedWallet(config, SYNC_WAIT_MS);
+    const taken = await wallet.takeOffer({ offer: input.offer, ...(input.expect ? { expect: input.expect } : {}) });
+    const terms = termsOut(taken.terms);
+    const id = halfId(taken.takerHalfB64);
+    pending.set(id, { revert: taken.revert, terms, role: 'taker', halves: { makerHalfB64: taken.makerHalfB64, takerHalfB64: taken.takerHalfB64 } });
+    await writeState(config.swapStateFile, wallet).catch(() => { });
+    return { id, makerHalfB64: taken.makerHalfB64, takerHalfB64: taken.takerHalfB64, bound: taken.bound === true, terms, buildMs: Date.now() - t0 };
+}
+/** Releases the coins of a half built here that is not going to be handed over. */
+export async function revertHalf(config, id) {
+    const half = pending.get(id);
+    if (!half)
+        throw new Error(`no half with id ${id} was built by this server process (ids are listed by get_swap_wallet)`);
+    await half.revert();
+    pending.delete(id);
+    const entry = await openWallet(config);
+    await writeState(config.swapStateFile, entry.wallet).catch(() => { });
+    return { id, reverted: true };
+}
+/** Both halves of an offer taken here, for a submission by id. */
+export function takenHalves(id) {
+    const half = pending.get(id);
+    if (!half)
+        throw new Error(`no half with id ${id} is held by this server process (ids are listed by get_swap_wallet)`);
+    if (!half.halves)
+        throw new Error(`half ${id} is an offer built here, not a taken one: pass both halves`);
+    return half.halves;
+}
+/** Remembers the sponsor job a half went into. An id this process does not hold is ignored. */
+export function trackHalfJob(id, jobId) {
+    const half = pending.get(id);
+    if (half && typeof jobId === 'string')
+        half.jobId = jobId;
+}
+/** A landed swap spent its coins: its half is no longer pending. A failed one stays, so it can be reverted. */
+export function settleHalfJob(jobId, status) {
+    if (status !== 'succeeded')
+        return;
+    for (const [id, half] of pending)
+        if (half.jobId === jobId)
+            pending.delete(id);
+}
+/** Test seam / shutdown. */
+export async function closeSwapWallet() {
+    const current = open;
+    open = undefined;
+    pending.clear();
+    if (!current)
+        return;
+    try {
+        await (await current).wallet.close?.();
+    }
+    catch { /* best effort */ }
+}
+/** Test seam: replace the module the swap functions load. */
+export function __setSwapModuleForTests(mod) {
+    modulePromise = mod ? Promise.resolve(mod) : undefined;
+    open = undefined;
+    pending.clear();
+}
+//# sourceMappingURL=swap.js.map

package/dist/swap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"swap.js","sourceRoot":"","sources":["../src/swap.ts"],"names":[],"mappings":"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"}

package/dist/tools.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { int64, NightgateApiError } from './client.js';
 import { BUILDABLE_CALLS, BUILDABLE_ARTIFACTS, buildSponsorable, attesterIdentity } from './builder.js';
+import { buildOffer, readOffer, revertHalf, settleHalfJob, swapWalletInfo, takenHalves, takeOffer, trackHalfJob } from './swap.js';
 const HEX64 = /^[0-9a-fA-F]{64}$/;
 const hex64 = (what) => z.string().regex(HEX64, `${what} must be 64 hex characters`);
 /** Scaled non-negative integer, as string (preferred, exact) or JS number. */
@@ -19,6 +20,21 @@ const setDirs = z.array(z.boolean()).length(6)
 const POLL_HINT = 'Async: returns { jobId, status } immediately; poll get_job_status until succeeded or failed.';
 /** NIGHTGATE's platform sponsor pool id (0.17.2+): the server picks a free pool sponsor. */
 const PLATFORM_POOL_SENTINEL = '00000000-0000-0000-0000-706f6f6c0000';
+/** One side of a swap: a raw token type and an amount in atoms. */
+const swapLeg = (what) => z.object({
+    tokenType: hex64(`${what}.tokenType`).describe('Raw token type (64 hex), what derive_token_type returns'),
+    amount: z.union([
+        z.string().regex(/^[1-9]\d*$/, `${what}.amount must be a positive integer (decimal string)`),
+        z.number().int().positive(),
+    ]).describe('Amount in atoms; a decimal string is exact'),
+});
+const legOut = (leg) => ({ tokenType: leg.tokenType.toLowerCase(), amount: String(leg.amount) });
+/** A swap half as it is handed over: offer file text or base64 of the serialized transaction. */
+const swapHalf = (what) => z.string().min(16)
+    .describe(`${what}: offer file text (swapoffer1...) or base64 of the serialized, proven transaction`);
+const SWAP_HINT = 'A swap settles two shielded tokens between two wallets without a contract: each side builds one half ' +
+    '(it spends the coin it gives and creates the coin it wants), the two mirrored halves merge into one transaction, ' +
+    'and a sponsor pays the fee.';
 /**
  * Per-slot salt of a proof field. Content-tree leaves are SALTED, so every
  * single-field proof needs the slot's salt from prepare_document_proof
@@ -809,8 +825,10 @@ export function registerTools(server, client, config) {
     }));
     server.registerTool('get_attester_identity', {
         description: 'The attester id this MCP server builds under (derived from NIGHTGATE_SEED_HEX via the ' +
-            'txbuilder), plus the network. Use it to check verify_attestation results against the ' +
-            'identity that will appear on-chain; builds nothing and submits nothing.',
+            'txbuilder), plus the network, the shielded address and the two public shielded keys ' +
+            '(what a sender needs to create a coin for this wallet). Use it to check ' +
+            'verify_attestation results against the identity that will appear on-chain; builds ' +
+            'nothing and submits nothing.',
         inputSchema: {},
     }, run(async () => {
         if (!config)
@@ -870,6 +888,148 @@ export function registerTools(server, client, config) {
         sponsorSessionId: args.sponsorSessionId,
         idempotencyKey: args.idempotencyKey,
     })));
+    server.registerTool('get_swap_wallet', {
+        description: 'The shielded wallet this MCP server swaps from (seed from NIGHTGATE_SEED_HEX): address, ' +
+            'public keys, and per token type the balance, the number of free coins and `spendable`, ' +
+            'the most ONE swap half can give (what its largest coins hold, up to maxInputs coins). ' +
+            'Also lists the halves built here that are not handed over yet. The wallet syncs its ' +
+            'shielded coins only; a first sync from genesis takes about 5 minutes, during which the ' +
+            'answer is { synced: false, syncingSeconds }: call again. Spends nothing.',
+        inputSchema: {},
+    }, run(async () => {
+        if (!config)
+            throw new Error('swaps are not configured for this server instance');
+        return swapWalletInfo(config);
+    }));
+    server.registerTool('read_swap_offer', {
+        description: SWAP_HINT + ' This reads what an offer gives and wants FROM THE TRANSACTION it carries, ' +
+            'never from what its maker says: gives / wants (token type and amount, from the ' +
+            "maker's side), the coins it carries, and whether it is bound. Refuses anything that is " +
+            'not a plain swap half (a contract call, unshielded value, more than one token type ' +
+            'given or wanted). Needs no wallet and no network. Check the terms here before take_swap_offer.',
+        inputSchema: {
+            offer: swapHalf('The offer'),
+        },
+    }, run(async (args) => readOffer(args.offer)));
+    server.registerTool('build_swap_offer', {
+        description: SWAP_HINT + ' This builds and proves ONE half from this server\'s wallet: it spends `give` ' +
+            'and creates `want` (and the change) for this wallet. Returns the offer file ' +
+            '(`offer`, text starting with swapoffer1, about 25 000 characters) to publish, its `id`, ' +
+            'and the terms read back from the built transaction. Anyone holding the wanted token can ' +
+            'take the offer; the first swap that lands consumes it. The coins stay reserved until ' +
+            'the swap lands: withdraw an offer that is not going to be used with revert_swap_offer. ' +
+            'An offer refers to a recent chain state and expires with it, so publish it promptly. ' +
+            '`give.amount` may not exceed `spendable` of get_swap_wallet. Proving takes about 200 s ' +
+            'in-process, 11 to 17 s on a proof server (NIGHTGATE_PROOF_SERVER_URL). Spends no fee.',
+        inputSchema: {
+            give: swapLeg('give'),
+            want: swapLeg('want'),
+            bind: z.boolean().optional()
+                .describe('true (default): bound, with its offer file. false: unbound, base64 only (halfB64), for a taker that builds unbound too'),
+        },
+    }, run(async (args) => {
+        if (!config)
+            throw new Error('swaps are not configured for this server instance');
+        return buildOffer(config, { give: legOut(args.give), want: legOut(args.want), bind: args.bind });
+    }));
+    server.registerTool('take_swap_offer', {
+        description: SWAP_HINT + ' This takes an offer: it reads the offer\'s terms from the transaction, ' +
+            'refuses when they differ from `expect`, builds and proves the mirror half from this ' +
+            'server\'s wallet (it spends what the offer wants and creates what the offer gives). ' +
+            'With sponsorSessionId the two halves go to the sponsor at once and the answer is the ' +
+            'job ({ jobId, status, sessionId, id, terms }): poll get_job_status with the returned ' +
+            'sessionId. Without it the answer carries both halves for sponsor_swap. ALWAYS pass ' +
+            '`expect` with the terms you agreed to: an offer is text from someone else. A sponsor ' +
+            'that refuses the swap leaves the proven half held under `halfId`: send it again with ' +
+            'sponsor_swap({ halfId, sponsorSessionId }) or release its coins with revert_swap_offer. ' +
+            'If the offer was taken by somebody else first, the job fails: revert_swap_offer.',
+        inputSchema: {
+            offer: swapHalf('The offer to take'),
+            expect: z.object({ gives: swapLeg('expect.gives'), wants: swapLeg('expect.wants') }).optional()
+                .describe("The terms you agreed to, from the MAKER's side: what the offer gives and what it wants"),
+            sponsorSessionId: z.string().uuid().optional()
+                .describe('Sponsor session or the platform sponsor POOL id ' + `${PLATFORM_POOL_SENTINEL}` + '; when given the swap is submitted at once'),
+            idempotencyKey: z.string().optional().describe('Dedupes retries of the same submission'),
+        },
+    }, run(async (args) => {
+        if (!config)
+            throw new Error('swaps are not configured for this server instance');
+        const taken = await takeOffer(config, {
+            offer: args.offer,
+            ...(args.expect ? { expect: { gives: legOut(args.expect.gives), wants: legOut(args.expect.wants) } } : {}),
+        });
+        if (!args.sponsorSessionId)
+            return taken;
+        let job;
+        try {
+            job = await client.callAction('sponsorSwap', {
+                makerHalfB64: taken.makerHalfB64,
+                takerHalfB64: taken.takerHalfB64,
+                sponsorSessionId: args.sponsorSessionId,
+                idempotencyKey: args.idempotencyKey,
+            });
+        }
+        catch (err) {
+            if (!(err instanceof NightgateApiError))
+                throw err;
+            throw new NightgateApiError(err.status, err.code, err.message, { ...(err.detail ?? {}), halfId: taken.id });
+        }
+        trackHalfJob(taken.id, job.jobId);
+        return { ...job, id: taken.id, terms: taken.terms, bound: taken.bound, buildMs: taken.buildMs };
+    }));
+    server.registerTool('revert_swap_offer', {
+        description: 'Release the coins of a swap half this server built (build_swap_offer or take_swap_offer) ' +
+            'that is not going to be used. Until then, or until the swap lands, the coins count as ' +
+            'spent in this wallet. It does not recall an offer somebody already holds: to make a ' +
+            'published offer worthless, spend its coins in another swap. Ids are listed by ' +
+            'get_swap_wallet; a half whose swap landed leaves the list when get_job_status reports it.',
+        inputSchema: {
+            id: z.string().regex(/^[0-9a-f]{32}$/, 'id must be the 32 hex characters a swap tool returned'),
+        },
+    }, run(async (args) => {
+        if (!config)
+            throw new Error('swaps are not configured for this server instance');
+        return revertHalf(config, args.id);
+    }));
+    server.registerTool('sponsor_swap', {
+        description: SWAP_HINT + ' This hands the two halves to the sponsor, which checks them, merges them, ' +
+            'pays the dust and submits: each half carries an offer and nothing else, gives exactly ' +
+            'one token type and wants exactly one other, both on the sponsor\'s token allow-list and ' +
+            'never NIGHT, at most 4 inputs and 2 outputs per half, and the halves mirror each other ' +
+            'in types and amounts. A half may be bound or unbound and is passed as offer file text ' +
+            'or base64. Off on a server by default (NIGHTGATE_SPONSOR_ALLOW_SWAPS); an agent grant ' +
+            'needs sponsorSwap in its allowedActions. Job result { txHash, swap: { gives, wants } }. ' +
+            'An offer fills once: if it was taken first by somebody else the job fails. Pass both ' +
+            'halves, or `halfId` alone for an offer this server took (take_swap_offer keeps both ' +
+            'halves). Poll get_job_status with the sessionId RETURNED by this call. ' + POLL_HINT,
+        inputSchema: {
+            makerHalf: swapHalf("The maker's half (the offer)").optional(),
+            takerHalf: swapHalf("The taker's half").optional(),
+            sponsorSessionId: z.string().uuid()
+                .describe('Wallet session that pays the dust and submits, or the platform sponsor POOL id ' +
+                `${PLATFORM_POOL_SENTINEL}`),
+            idempotencyKey: z.string().optional()
+                .describe('Dedupes retries of the SAME two halves'),
+            halfId: z.string().regex(/^[0-9a-f]{32}$/, 'halfId must be the 32 hex characters a swap tool returned').optional()
+                .describe('Id of the half this server built for the swap: alone it names a taken offer, next to both halves it ties the job to the half'),
+        },
+    }, run(async (args) => {
+        if (!!args.makerHalf !== !!args.takerHalf)
+            throw new Error('sponsor_swap needs makerHalf AND takerHalf, or halfId alone');
+        if (!args.makerHalf && !args.halfId)
+            throw new Error('sponsor_swap needs makerHalf and takerHalf, or the halfId of an offer this server took');
+        const halves = args.makerHalf && args.takerHalf
+            ? { makerHalfB64: args.makerHalf, takerHalfB64: args.takerHalf }
+            : takenHalves(args.halfId);
+        const job = await client.callAction('sponsorSwap', {
+            ...halves,
+            sponsorSessionId: args.sponsorSessionId,
+            idempotencyKey: args.idempotencyKey,
+        });
+        if (args.halfId)
+            trackHalfJob(args.halfId, job?.jobId);
+        return job;
+    }));
     server.registerTool('derive_token_type', {
         description: 'Derive the raw token type a minting contract produces (compute-only, no wallet, no ' +
             'chain access). A custom token is addressed by rawTokenType(domainSeparator, ' +
@@ -893,16 +1053,23 @@ export function registerTools(server, client, config) {
             'Sponsor jobs: failed + errorCode CHAIN_EXECUTION_FAILED = the transaction IS on-chain but ' +
             'the contract call did not apply (same-contract conflict) -> rebuild and sponsor again; ' +
             'reconciliation_required = broadcast outcome unknown to the server yet, the transaction ' +
-            'identifier is in the error message, the server keeps resolving it via the indexer.',
+            'identifier is in the error message, the server keeps resolving it via the indexer. ' +
+            'Batches: once confirmed, chainSegments ([{ segment, calls, applied }]) says which calls ' +
+            'applied; resend only the ones with applied false. Swaps: the result carries swap ' +
+            '{ gives, wants }, what was exchanged from the maker\'s side.',
         inputSchema: {
             jobId: z.string().uuid().describe('Job id returned by a submit action'),
             sessionId: z.string().uuid()
                 .describe('Wallet session id the job belongs to; for sponsor jobs the sessionId RETURNED by the sponsor call'),
         },
-    }, run(async (args) => client.callAction('getJobStatus', {
-        jobId: args.jobId,
-        sessionId: args.sessionId,
-    })));
+    }, run(async (args) => {
+        const job = await client.callAction('getJobStatus', {
+            jobId: args.jobId,
+            sessionId: args.sessionId,
+        });
+        settleHalfJob(args.jobId, job?.status);
+        return job;
+    }));
 }
 /**
  * Uniform handler wrapper: JSON success payloads, API errors reported as