@odatano/nightgate-mcp 0.17.1 → 0.18.1

package/dist/tools.js

@@ -1,10 +1,13 @@
+import { createHash } from 'node:crypto';
 import { z } from 'zod';
 import { int64, raw, NightgateApiError } from './client.js';
-import { BUILDABLE_CALLS, BUILDABLE_ARTIFACTS, DEFAULT_ARTIFACT, buildSponsorable, attesterIdentity, seedIdentity } from './builder.js';
-import { buildOffer, postedOfferIds, readOffer, revertHalf, sameOffer, settleBoardRows, settleHalfJob, swapWalletInfo, takenHalves, takeOffer, trackHalfJob, trackPostedHalf, } from './swap.js';
-import { txExport } from './tx-module.js';
+import { isGatewayKey, vaultOf } from './config.js';
+import { BUILDABLE_CALLS, BUILDABLE_ARTIFACTS, DEFAULT_ARTIFACT, buildSponsorable, attesterIdentity } from './builder.js';
+import { buildOffer, halfJobIds, postedOfferIds, readOffer, revertHalf, sameOffer, settleBoardRows, settleHalfJob, swapWalletInfo, takenHalves, takeOffer, trackHalfJob, trackPostedHalf, } from './swap.js';
 import { buildMint } from './factory.js';
 import { resolveTxSource } from './built.js';
+import { awaitJob, forgetStart, jobSession, startOnce } from './jobs.js';
+import { seedCreated, seedNotice } from './seed.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; a number stays below 2^53 so String() renders it exactly. */
@@ -12,19 +15,6 @@ const scaledInt = (what) => z.union([
     z.string().regex(/^\d+$/, `${what} must be a non-negative integer (decimal string)`),
     z.number().int().nonnegative().safe(),
 ]);
-const merkleSiblings = z.array(hex64('sibling')).length(4)
-    .describe('Depth-4 Merkle inclusion path: exactly 4 sibling digests (64 hex each)');
-const merkleDirs = z.array(z.boolean()).length(4)
-    .describe('Exactly 4 booleans; true means the current node is the LEFT child');
-const setSiblings = z.array(hex64('setSibling')).length(6)
-    .describe('Depth-6 membership-set path: exactly 6 sibling digests (64 hex each)');
-const setDirs = z.array(z.boolean()).length(6)
-    .describe('Exactly 6 booleans; true means the current node is the LEFT child');
-const POLL_HINT = 'Async: returns { jobId, status } immediately; call get_job_status, which waits on the server until the job settles.';
-/** How long one get_job_status call lets the server wait for the job to settle, in ms. */
-const JOB_WAIT_MS = 20_000;
-// Off for this process once a server below NIGHTGATE 0.37 refuses getJobStatus' waitMs.
-let jobWait = true;
 /** 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'),
@@ -47,136 +37,74 @@ const OFFER_STATUS = z.enum(['open', 'filled', 'retired', 'expired', 'all']);
 const BOARD_ROW_HINT = 'Each row: offerId, the offer half (feed it to read_swap_offer or take_swap_offer), gives/wants ' +
     'type and amount, tags, expiresAt, postedAt, status, filledTxHash, closedAt, changedAt. Never the poster or the ' +
     "half's nullifiers.";
-/**
- * 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
- * (field `salt`; batch claims carry it as `salt` too). Witness material.
- */
-const fieldSalt = hex64('fieldSalt')
-    .describe('Per-slot salt of this field, from prepare_document_proof (fields[].salt). Witness material, never publish');
-/** The shared 16-slot schema descriptor list from prepare_document_proof. */
-/**
- * Content-tree slot widths NIGHTGATE ships: 16 (`attestation-vault`) and 32
- * (`attestation-vault-32`). A document uses exactly one of them, picked by
- * the `compiledArtifactRef` it is anchored under. These bounds only keep
- * obvious nonsense out; the SERVER knows the registered width of the actual
- * artifact and rejects a mismatch with a message naming it.
- */
-const SLOT_WIDTHS = [16, 32];
 const MAX_SLOT_WIDTH = 32;
+const RETRY_HINT = 'If the call was cut off or came back pending, run it again with the same arguments: ' +
+    'it picks up the job it started and submits nothing new.';
+const WAIT_HINT = 'The tool waits until the job settled (about 1 minute) and returns { status, txHash, transactionHash, result }. ' +
+    'failed: `next` says what to do. ' + RETRY_HINT;
 const MAX_MASK = 0xffffffff;
-const slotCount = (what) => (list) => SLOT_WIDTHS.includes(list.length)
-    || `${what} must have ${SLOT_WIDTHS.join(' or ')} entries, one per slot of the vault width`;
-/**
- * Mirrors the server's vacuity guard: a mask that frees every REAL
- * (non-padding) slot of the schema proves nothing at all. Checking it
- * against the SCHEMA rather than against a fixed all-ones constant is what
- * makes it width-independent, and it also catches the case a constant never
- * could, a mask that frees every real slot of a SHORT schema.
- */
-function maskFreesEveryRealSlot(allowedMask, schema) {
-    return schema.every((s, i) => s.kind === 2 || (allowedMask & (1 << i)) !== 0);
+/** Names one request, so a repeat of it is recognised; witness and bytes enter only as a hash. */
+function callKey(...parts) {
+    return createHash('sha256').update(JSON.stringify(parts, (_k, v) => (v && typeof v === 'object' && !Array.isArray(v)
+        ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b))) : v))).digest('hex');
 }
-const VACUOUS_MASK_MESSAGE = 'allowedMask frees every real (non-padding) schema slot; the claim would be vacuous and the server rejects it';
-const schemaSlots = z.array(z.object({
-    fieldKey: hex64('schema.fieldKey'),
-    kind: z.union([z.literal(0), z.literal(1), z.literal(2)])
-        .describe('0 = uint, 1 = bytes, 2 = padding'),
-    scale: z.union([z.string(), z.number()]).describe("Off-chain scaling of uint slots, '0' otherwise"),
-})).refine((l) => slotCount('schema')(l) === true, { message: 'schema must have 16 or 32 entries, one per slot of the vault width' })
-    .describe('The schema descriptor list returned by prepare_document_proof as `schema`, one entry per slot (16 on the default vault, 32 on attestation-vault-32). Both documents of a comparison MUST use the same one');
-/** One document's full opening (salt seed + one value per slot). */
-const documentOpening = z.object({
-    saltSeed: hex64('saltSeed'),
-    slots: z.array(z.object({
-        present: z.boolean(),
-        value: z.string().optional().describe('uint slots: the scaled integer'),
-        valueDigest: hex64('slot.valueDigest').optional().describe('bytes slots: the value digest'),
-    })).refine((l) => slotCount('slots')(l) === true, { message: 'slots must have 16 or 32 entries, one per slot of the vault width' }),
-}).describe('A document\'s complete opening from prepare_document_proof (`opening`): salt seed plus every slot value (16 or 32, matching the vault width). WITNESS material for the whole document, never publish');
-/** Batch claim shapes; claims may mix all kinds in one transaction. */
-const numericClaim = z.object({
-    predicate: z.enum(['lessOrEqual', 'greaterOrEqual']),
-    fieldKey: hex64('fieldKey'),
-    value: z.string().regex(/^\d+$/, 'value must be a non-negative integer (decimal string)'),
-    salt: fieldSalt,
-    siblings: merkleSiblings,
-    dirs: merkleDirs,
-    threshold: scaledInt('threshold'),
-    unit: z.string().optional(),
-});
-const equalityClaim = z.object({
-    predicate: z.literal('bytesEquality'),
-    fieldKey: hex64('fieldKey'),
-    expectedValue: z.string().min(1).optional()
-        .describe('Raw expected string; the server digests the EXACT string'),
-    expectedDigest: hex64('expectedDigest').optional()
-        .describe('blake2b-256 of the exact expected string (64 hex)'),
-    salt: fieldSalt,
-    siblings: merkleSiblings,
-    dirs: merkleDirs,
-}).superRefine((c, ctx) => {
-    if (!!c.expectedValue === !!c.expectedDigest) {
-        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'pass exactly one of expectedValue / expectedDigest' });
-    }
-});
-const membershipClaim = z.object({
-    predicate: z.literal('setMembership'),
-    fieldKey: hex64('fieldKey'),
-    value: z.string().min(1).optional().describe('Raw member string (witness only)'),
-    valueDigest: hex64('valueDigest').optional().describe('blake2b-256 of the exact member string (witness only)'),
-    allowedValues: z.array(z.string().min(1)).min(1).max(64).optional()
-        .describe('The public allow-list; the server builds the canonical set root + path'),
-    setRoot: hex64('setRoot').optional().describe('Precomputed canonical set root (64 hex)'),
-    setSiblings: setSiblings.optional(),
-    setDirs: setDirs.optional(),
-    salt: fieldSalt,
-    siblings: merkleSiblings,
-    dirs: merkleDirs,
-}).superRefine((c, ctx) => {
-    if (!!c.value === !!c.valueDigest) {
-        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'pass exactly one of value / valueDigest' });
-    }
-    const hasList = c.allowedValues !== undefined;
-    const hasPath = !!(c.setRoot || c.setSiblings || c.setDirs);
-    if (hasList && hasPath) {
-        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'pass either allowedValues or setRoot + setSiblings + setDirs, not both' });
-    }
-    if (!hasList && !(c.setRoot && c.setSiblings && c.setDirs)) {
-        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'allowedValues or setRoot + setSiblings + setDirs is required' });
-    }
-});
-/** Cross-root claim shapes: they relate the batch payload hash (document A) to a second document. */
-const documentIntegrityClaim = z.object({
-    predicate: z.literal('documentIntegrity'),
-    payloadHashB: hex64('payloadHashB').describe('The second document (A is the batch payloadHash)'),
-    attesterIdB: hex64('attesterIdB').optional().describe('Document B\'s attester; default the batch attester'),
-    allowedMask: z.number().int().min(0).max(MAX_MASK - 1)
-        .describe('Packed slot mask, one bit per slot of the vault width (16 bits by default, 32 on attestation-vault-32), bit i = slot i MAY differ. Must leave at least one real schema slot constrained, otherwise the claim is vacuous and rejected'),
-    schema: schemaSlots,
-    openingA: documentOpening,
-    openingB: documentOpening,
-}).superRefine((c, ctx) => {
-    if (maskFreesEveryRealSlot(c.allowedMask, c.schema)) {
-        ctx.addIssue({ code: z.ZodIssueCode.custom, message: VACUOUS_MASK_MESSAGE });
+/** The free verify call that shows a vault call's effect on-chain; none when the call names its record by key only. */
+function checkFor(input, ownAttesterId) {
+    const p = input.params;
+    const hex = (k) => (typeof p[k] === 'string' ? String(p[k]).toLowerCase() : undefined);
+    const base = { contractAddress: input.contractAddress, compiledArtifactRef: input.compiledArtifactRef ?? DEFAULT_ARTIFACT };
+    const record = (payloadHash, attesterId) => payloadHash ? { ...base, attesterId: attesterId ?? ownAttesterId, payloadHash } : undefined;
+    const claim = (args) => (args ? { tool: 'verify_predicate', args } : undefined);
+    switch (input.call) {
+        case 'attest':
+        case 'anchorContentRoot':
+        case 'grantDisclosure':
+        case 'revokeDisclosure':
+        case 'bindPassport': {
+            const r = record(hex('payloadHash'));
+            if (!r)
+                return undefined;
+            const root = input.call === 'anchorContentRoot' ? { contentRoot: hex('contentRoot'), schemaId: hex('schemaId') } : {};
+            return { tool: 'verify_attestation', args: { ...r, ...root } };
+        }
+        case 'proveFieldPredicate': {
+            const r = record(hex('payloadHash'), hex('attesterId'));
+            return claim(r && { ...r, predicate: Number(p.op) === 1 ? 'greaterOrEqual' : 'lessOrEqual', fieldKey: hex('fieldKey'), threshold: String(p.threshold) });
+        }
+        case 'proveFieldEquality': {
+            const r = record(hex('payloadHash'), hex('attesterId'));
+            return claim(r && { ...r, predicate: 'bytesEquality', fieldKey: hex('fieldKey'), expectedDigest: hex('expectedDigest') });
+        }
+        case 'proveFieldMembership': {
+            const r = record(hex('payloadHash'), hex('attesterId'));
+            return claim(r && { ...r, predicate: 'setMembership', fieldKey: hex('fieldKey'), setRoot: hex('setRoot') });
+        }
+        case 'proveFieldsUnchangedExcept':
+        case 'proveFieldsDiffer': {
+            const r = record(hex('payloadHashA'), hex('attesterIdA'));
+            if (!r || !hex('payloadHashB'))
+                return undefined;
+            const extraArgs = input.call === 'proveFieldsUnchangedExcept'
+                ? { predicate: 'documentIntegrity', allowedMask: Number(p.allowedMask) }
+                : { predicate: 'documentDiff', k: Number(p.k) };
+            return claim({ ...r, payloadHashB: hex('payloadHashB'), attesterIdB: hex('attesterIdB'), ...extraArgs });
+        }
+        default:
+            return undefined;
     }
-});
-const documentDiffClaim = z.object({
-    predicate: z.literal('documentDiff'),
-    payloadHashB: hex64('payloadHashB').describe('The second document (A is the batch payloadHash)'),
-    attesterIdB: hex64('attesterIdB').optional().describe('Document B\'s attester; default the batch attester'),
-    k: z.number().int().min(1).max(MAX_SLOT_WIDTH).describe('Minimum number of differing slots to prove, up to the vault width'),
-    schema: schemaSlots,
-    openingA: documentOpening,
-    openingB: documentOpening,
-});
-/**
- * Phase A tool set: crawler-free verification, job polling, and the
- * curated write path (anchoring, field predicates, disclosure).
- * Wallet lifecycle actions are deliberately never exposed over MCP.
- */
+}
+const CONTRACT = z.string().regex(HEX64, 'contractAddress must be 64 hex characters').optional()
+    .describe('AttestationVault address (64 hex); default the shared sandbox vault of the network (preprod, preview)');
+/** Every NIGHTGATE tool. Writes are built here with the caller seed and paid by a sponsor; no tool needs a server wallet. */
 export function registerTools(server, client, config) {
     const run = wrapHandler(client);
+    const vault = (contractAddress, compiledArtifactRef) => {
+        if (config)
+            return vaultOf(config, contractAddress, compiledArtifactRef);
+        if (!contractAddress)
+            throw new Error('contractAddress is required');
+        return contractAddress.toLowerCase();
+    };
     server.registerTool('verify_attestation', {
         description: 'Verify against LIVE Midnight contract state that an attester\'s record of a payload ' +
             'hash stands in an AttestationVault (crawler-free, no txHash needed). A record is ONE ' +
@@ -184,9 +112,12 @@ export function registerTools(server, client, config) {
             'name it by attesterId + payloadHash, or by a bound documentId, which resolves to exactly ' +
             'one record and reveals its attester. Optionally also checks that the anchored content ' +
             'root / schema id match. Returns verified:false (not an error) when absent; the result ' +
-            'carries attesterId, payloadHash, recordKey and documentId.',
+            'carries attesterId, payloadHash, recordKey and documentId. bindingRegistered is only ' +
+            'about documentId lookups: true when the vault registrar assigned that id to this ' +
+            'attester. A record anchored without a document id reports false, and that is fine. ' +
+            'Free: it reads the public verify service.',
         inputSchema: {
-            contractAddress: z.string().min(1).describe('AttestationVault contract address'),
+            contractAddress: CONTRACT,
             attesterId: hex64('attesterId').optional()
                 .describe('The attester whose record to check (64 hex; get_attester_identity for this server\'s own). Required unless documentId is given'),
             payloadHash: hex64('payloadHash').optional()
@@ -204,8 +135,8 @@ export function registerTools(server, client, config) {
         if (!args.documentId && !(args.attesterId && args.payloadHash)) {
             throw new Error('name the record: attesterId + payloadHash, or documentId');
         }
-        return client.callFunction('verifyAttestationState', {
-            contractAddress: args.contractAddress,
+        return client.callVerifyFunction('verifyAttestationState', {
+            contractAddress: vault(args.contractAddress, args.compiledArtifactRef),
             attesterId: args.attesterId,
             payloadHash: args.payloadHash,
             documentId: args.documentId,
@@ -222,9 +153,10 @@ export function registerTools(server, client, config) {
             'mismatch yields verified:false) and optionally fieldKey for field-bound proofs. ' +
             'bytesEquality needs fieldKey + expectedDigest; setMembership needs fieldKey + setRoot ' +
             '(recompute it from the published list via prepare_membership_set). Every claim is bound ' +
-            'to ONE attester\'s record of the document, so attesterId is part of the coordinates.',
+            'to ONE attester\'s record of the document, so attesterId is part of the coordinates. ' +
+            'Free: it reads the public verify service.',
         inputSchema: {
-            contractAddress: z.string().min(1).describe('AttestationVault contract address'),
+            contractAddress: CONTRACT,
             attesterId: hex64('attesterId').describe('The attester whose record of payloadHash carries the claim (64 hex)'),
             payloadHash: hex64('payloadHash').describe('The attestation payload hash (64 hex)'),
             predicate: z.enum(['lessOrEqual', 'greaterOrEqual', 'bytesEquality', 'setMembership',
@@ -265,8 +197,8 @@ export function registerTools(server, client, config) {
         if (args.predicate === 'documentDiff' && (!args.payloadHashB || args.k === undefined)) {
             throw new Error("predicate 'documentDiff' requires payloadHashB and k");
         }
-        return client.callFunction('verifyPredicateState', {
-            contractAddress: args.contractAddress,
+        return client.callVerifyFunction('verifyPredicateState', {
+            contractAddress: vault(args.contractAddress, args.compiledArtifactRef),
             attesterId: args.attesterId,
             payloadHash: args.payloadHash,
             attesterIdB: args.attesterIdB,
@@ -282,37 +214,11 @@ export function registerTools(server, client, config) {
             network: args.network,
         });
     }));
-    server.registerTool('verify_predicate_attestation', {
-        description: 'Verify a server-issued predicate attestation by its NIGHTGATE row id (UUID). ' +
-            'Confirms the proving transaction succeeded, with a crawler-free live-state fallback. ' +
-            'Use verify_predicate instead when you only have on-chain coordinates.',
-        inputSchema: {
-            predicateAttestationId: z.string().uuid().describe('PredicateAttestations row id'),
-        },
-    }, run(async (args) => client.callFunction('verifyPredicateAttestation', {
-        predicateAttestationId: args.predicateAttestationId,
-    })));
-    server.registerTool('verify_document', {
-        description: 'Verify an anchored document by its NIGHTGATE document id: compares the provided sha256 ' +
-            'against the anchored original and confirms the anchoring transaction, with a crawler-free ' +
-            'live-state fallback when contractAddress is supplied.',
-        inputSchema: {
-            documentId: z.string().uuid().describe('Documents row id'),
-            providedSha256: hex64('providedSha256').describe('sha256 of the document to check (64 hex)'),
-            contractAddress: z.string().optional().describe('Optional vault address, enables the crawler-free fallback'),
-            compiledArtifactRef: z.string().optional().describe("Contract artifact ref, defaults to 'attestation-vault-32'; 'attestation-vault' for a 16-slot vault"),
-        },
-    }, run(async (args) => client.callFunction('verifyDocument', {
-        documentId: args.documentId,
-        providedSha256: args.providedSha256,
-        contractAddress: args.contractAddress,
-        compiledArtifactRef: args.compiledArtifactRef ?? DEFAULT_ARTIFACT,
-    })));
     server.registerTool('prepare_document_proof', {
         description: 'Turn a structured document into everything the proof tools need: canonical JSON and its ' +
             'payloadHash (what anchor_document anchors), a Merkle contentRoot over an ORDERED list of ' +
-            'up to 16 proof fields, and per-field inclusion paths ready for prove_field_predicate / ' +
-            'prove_field_equality / prove_field_membership. kind "uint" (default) scales a numeric ' +
+            'up to 16 proof fields, and per-field inclusion paths ready for the proveField* calls of ' +
+            'submit_vault_call. kind "uint" (default) scales a numeric ' +
             'value; kind "bytes" (NIGHTGATE >= 0.16.0) enters a STRING field as the digest of the ' +
             'exact string, feeding the equality/membership proofs. Keep the field order stable across ' +
             'anchor and proof: it is part of the tree identity. Compute-only and synchronous, nothing ' +
@@ -345,117 +251,6 @@ export function registerTools(server, client, config) {
         saltSeed: args.saltSeed,
         compiledArtifactRef: args.compiledArtifactRef ?? DEFAULT_ARTIFACT,
     })));
-    server.registerTool('attest_agent_output', {
-        description: 'Anchor agent-output provenance on the Midnight chain: "agent X produced output O from ' +
-            'input I at time T". Builds the canonical v1 envelope server-side, hashes it and anchors ' +
-            'it; the response returns the envelopeJson any third party can re-hash and check via ' +
-            'verify_attestation, without trusting this server. ' + POLL_HINT,
-        inputSchema: {
-            agentId: z.string().min(1).max(200).describe('Agent identity, ideally a registered grantee id'),
-            inputHash: hex64('inputHash').describe('Commitment to the agent input (64 hex)'),
-            outputHash: hex64('outputHash').describe('Commitment to the produced output (64 hex)'),
-            sessionId: z.string().uuid().describe('Wallet session id that signs and submits'),
-            contractAddress: z.string().min(1).describe('AttestationVault deployment'),
-            modelId: z.string().max(200).optional().describe('Optional model identifier'),
-            policyHash: hex64('policyHash').optional().describe('Optional commitment to the governing policy (64 hex)'),
-            producedAt: z.string().datetime().optional().describe('Optional ISO-8601 production time, defaults to now'),
-            storageRef: z.string().optional().describe('Where output/envelope live, defaults to agent-output://<agentId>'),
-            compiledArtifactRef: z.string().optional().describe("Contract artifact ref, defaults to 'attestation-vault-32'; 'attestation-vault' for a 16-slot vault"),
-            idempotencyKey: z.string().optional().describe('Dedupes retries'),
-            sponsorSessionId: z.string().uuid().optional().describe('Optional second session that pays the dust fee'),
-        },
-    }, run(async (args) => client.callAction('attestAgentOutput', {
-        agentId: args.agentId,
-        inputHash: args.inputHash,
-        outputHash: args.outputHash,
-        modelId: args.modelId,
-        policyHash: args.policyHash,
-        producedAt: args.producedAt,
-        storageRef: args.storageRef,
-        sessionId: args.sessionId,
-        contractAddress: args.contractAddress,
-        compiledArtifactRef: args.compiledArtifactRef ?? DEFAULT_ARTIFACT,
-        idempotencyKey: args.idempotencyKey,
-        sponsorSessionId: args.sponsorSessionId,
-    })));
-    server.registerTool('anchor_document', {
-        description: 'Anchor a document content hash on the Midnight chain via the AttestationVault attest ' +
-            'circuit (one transaction). Commits only the sha256 + public metadata; you are responsible ' +
-            'for storing the actual bytes at storageRef. The on-chain record is keyed by the session\'s ' +
-            'attester id AND the hash, so nobody can pre-empt or take over it; the same hash anchored ' +
-            'by another identity is a separate record. ' + POLL_HINT +
-            ' Also returns documentId for verify_document and attesterId, which verifiers need next to the hash.',
-        inputSchema: {
-            sha256: hex64('sha256').describe('sha256 of the document content (64 hex), becomes the on-chain payload hash'),
-            storageRef: z.string().min(1).describe('Where the bytes live, e.g. file://, s3://, ipfs://'),
-            sessionId: z.string().uuid().describe('Wallet session id that signs and submits'),
-            contractAddress: z.string().min(1).describe('AttestationVault deployment to anchor into'),
-            contentType: z.string().optional().describe('MIME type, informational'),
-            size: z.number().int().nonnegative().optional().describe('Content size in bytes, informational'),
-            metadata: z.record(z.unknown()).optional().describe('Public metadata object; its hash is anchored alongside'),
-            compiledArtifactRef: z.string().optional().describe("Contract artifact ref, defaults to 'attestation-vault-32'; 'attestation-vault' for a 16-slot vault"),
-            idempotencyKey: z.string().optional().describe('Dedupes retries of the same anchor request'),
-            sponsorSessionId: z.string().uuid().optional().describe('Optional second session that pays the dust fee'),
-        },
-    }, run(async (args) => client.callAction('anchorDocument', {
-        sha256: args.sha256,
-        contentType: args.contentType,
-        size: args.size,
-        storageRef: args.storageRef,
-        metadata: args.metadata === undefined ? undefined : JSON.stringify(args.metadata),
-        sessionId: args.sessionId,
-        contractAddress: args.contractAddress,
-        compiledArtifactRef: args.compiledArtifactRef ?? DEFAULT_ARTIFACT,
-        idempotencyKey: args.idempotencyKey,
-        sponsorSessionId: args.sponsorSessionId,
-    })));
-    server.registerTool('prove_field_predicate', {
-        description: 'Issue a zero-knowledge field-bound predicate proof: prove that a hidden field of an ' +
-            'anchored document satisfies "value <= threshold" or "value >= threshold" WITHOUT revealing ' +
-            'the value. Needs the depth-4 Merkle inclusion path of the field in the anchored content ' +
-            'root. value/threshold are scaled integers (decimal strings); the value is a witness and ' +
-            'never persisted. If contentRoot is supplied it is anchored first. A false predicate fails ' +
-            'at local proving time, nothing is submitted. ' + POLL_HINT,
-        inputSchema: {
-            payloadHash: hex64('payloadHash').describe('Attestation payload hash (64 hex)'),
-            attesterId: hex64('attesterId').optional()
-                .describe('The attester whose record of payloadHash the claim is bound to (64 hex); default the session\'s own. A contentRoot can only be anchored under the session\'s own record'),
-            fieldKey: hex64('fieldKey').describe('Canonical field id (64 hex, public)'),
-            value: z.string().regex(/^\d+$/, 'value must be a non-negative integer (decimal string)')
-                .describe('Scaled integer field value (witness only, never persisted)'),
-            fieldSalt,
-            siblings: merkleSiblings,
-            dirs: merkleDirs,
-            predicate: z.enum(['lessOrEqual', 'greaterOrEqual']).describe('Predicate operator'),
-            threshold: scaledInt('threshold').describe('Scaled integer threshold (same scaling as value)'),
-            sessionId: z.string().uuid().describe('Wallet session id that signs and submits'),
-            contractAddress: z.string().min(1).describe('AttestationVault deployment'),
-            contentRoot: hex64('contentRoot').optional().describe('Optional Merkle root (64 hex) to anchor first'),
-            schemaId: hex64('schemaId').optional().describe('Schema id of the field list, required whenever contentRoot is supplied'),
-            unit: z.string().optional().describe('Informational unit, e.g. kWh'),
-            compiledArtifactRef: z.string().optional().describe("Contract artifact ref, defaults to 'attestation-vault-32'; 'attestation-vault' for a 16-slot vault"),
-            idempotencyKey: z.string().optional().describe('Dedupes retries'),
-            sponsorSessionId: z.string().uuid().optional().describe('Optional second session that pays the dust fee'),
-        },
-    }, run(async (args) => client.callAction('issueFieldPredicateAttestation', {
-        payloadHash: args.payloadHash,
-        attesterId: args.attesterId,
-        fieldKey: args.fieldKey,
-        value: args.value,
-        fieldSalt: args.fieldSalt,
-        contentRoot: args.contentRoot,
-        schemaId: args.schemaId,
-        siblings: args.siblings,
-        dirs: args.dirs,
-        predicate: args.predicate,
-        threshold: String(args.threshold),
-        unit: args.unit,
-        sessionId: args.sessionId,
-        contractAddress: args.contractAddress,
-        compiledArtifactRef: args.compiledArtifactRef ?? DEFAULT_ARTIFACT,
-        idempotencyKey: args.idempotencyKey,
-        sponsorSessionId: args.sponsorSessionId,
-    })));
     server.registerTool('prepare_membership_set', {
         description: 'Build the canonical depth-6 membership-set tree over a public allow-list (NIGHTGATE ' +
             '>= 0.16.0). Deterministic rule (digest each exact string, dedupe, sort ascending, pad by ' +
@@ -483,311 +278,111 @@ export function registerTools(server, client, config) {
             compiledArtifactRef: args.compiledArtifactRef ?? DEFAULT_ARTIFACT,
         });
     }));
-    server.registerTool('prove_field_equality', {
-        description: 'Issue a ZK bytes-equality proof (NIGHTGATE >= 0.16.0): the anchored document field ' +
-            'carries EXACTLY the value behind the public expectedDigest. The digest IS the statement, ' +
-            'so this is an authenticity/binding proof, not confidentiality (a low-entropy value\'s ' +
-            'digest is dictionary-guessable). The field must be a kind:"bytes" leaf from ' +
-            'prepare_document_proof; siblings/dirs are its depth-4 inclusion path. If contentRoot is ' +
-            'supplied it is anchored first. ' + POLL_HINT,
-        inputSchema: {
-            payloadHash: hex64('payloadHash').describe('Attestation payload hash (64 hex)'),
-            attesterId: hex64('attesterId').optional()
-                .describe('The attester whose record of payloadHash the claim is bound to (64 hex); default the session\'s own. A contentRoot can only be anchored under the session\'s own record'),
-            fieldKey: hex64('fieldKey').describe('Canonical field id (64 hex, public)'),
-            expectedValue: z.string().min(1).optional()
-                .describe('Raw expected string (the server digests the EXACT string; pass this OR expectedDigest)'),
-            expectedDigest: hex64('expectedDigest').optional()
-                .describe('blake2b-256 of the exact expected string (64 hex)'),
-            fieldSalt,
-            siblings: merkleSiblings,
-            dirs: merkleDirs,
-            sessionId: z.string().uuid().describe('Wallet session id that signs and submits'),
-            contractAddress: z.string().min(1).describe('AttestationVault deployment'),
-            contentRoot: hex64('contentRoot').optional().describe('Optional Merkle root (64 hex) to anchor first'),
-            schemaId: hex64('schemaId').optional().describe('Schema id of the field list, required whenever contentRoot is supplied'),
-            compiledArtifactRef: z.string().optional().describe("Contract artifact ref, defaults to 'attestation-vault-32'; 'attestation-vault' for a 16-slot vault"),
-            idempotencyKey: z.string().optional().describe('Dedupes retries'),
-            sponsorSessionId: z.string().uuid().optional().describe('Optional second session that pays the dust fee'),
-        },
-    }, run(async (args) => {
-        if (!!args.expectedValue === !!args.expectedDigest) {
-            throw new Error('pass exactly one of expectedValue / expectedDigest');
-        }
-        return client.callAction('issueFieldEqualityAttestation', {
-            payloadHash: args.payloadHash,
-            attesterId: args.attesterId,
-            fieldKey: args.fieldKey,
-            expectedValue: args.expectedValue,
-            expectedDigest: args.expectedDigest,
-            fieldSalt: args.fieldSalt,
-            contentRoot: args.contentRoot,
-            schemaId: args.schemaId,
-            siblings: args.siblings,
-            dirs: args.dirs,
-            sessionId: args.sessionId,
-            contractAddress: args.contractAddress,
-            compiledArtifactRef: args.compiledArtifactRef ?? DEFAULT_ARTIFACT,
-            idempotencyKey: args.idempotencyKey,
-            sponsorSessionId: args.sponsorSessionId,
-        });
-    }));
-    server.registerTool('prove_field_membership', {
-        description: 'Issue a ZK set-membership proof (NIGHTGATE >= 0.16.0): the anchored document field\'s ' +
-            'HIDDEN value is one of a public allow-list, without revealing which one. Supply the ' +
-            'allow-list directly (allowedValues: the server builds the canonical set root + path and ' +
-            'rejects a non-member with 400 BEFORE any proving) or a precomputed setRoot + setSiblings ' +
-            '+ setDirs from prepare_membership_set. The field must be a kind:"bytes" leaf from ' +
-            'prepare_document_proof; value/valueDigest stay witness material, never persisted. If ' +
-            'contentRoot is supplied it is anchored first. ' + POLL_HINT,
-        inputSchema: {
-            payloadHash: hex64('payloadHash').describe('Attestation payload hash (64 hex)'),
-            attesterId: hex64('attesterId').optional()
-                .describe('The attester whose record of payloadHash the claim is bound to (64 hex); default the session\'s own. A contentRoot can only be anchored under the session\'s own record'),
-            fieldKey: hex64('fieldKey').describe('Canonical field id (64 hex, public)'),
-            value: z.string().min(1).optional()
-                .describe('Raw member string (witness only; pass this OR valueDigest)'),
-            valueDigest: hex64('valueDigest').optional()
-                .describe('blake2b-256 of the exact member string (witness only)'),
-            allowedValues: z.array(z.string().min(1)).min(1).max(64).optional()
-                .describe('The public allow-list; pass this OR setRoot + setSiblings + setDirs'),
-            setRoot: hex64('setRoot').optional().describe('Precomputed canonical set root (64 hex)'),
-            setSiblings: setSiblings.optional(),
-            setDirs: setDirs.optional(),
-            fieldSalt,
-            siblings: merkleSiblings,
-            dirs: merkleDirs,
-            sessionId: z.string().uuid().describe('Wallet session id that signs and submits'),
-            contractAddress: z.string().min(1).describe('AttestationVault deployment'),
-            contentRoot: hex64('contentRoot').optional().describe('Optional Merkle root (64 hex) to anchor first'),
-            schemaId: hex64('schemaId').optional().describe('Schema id of the field list, required whenever contentRoot is supplied'),
-            compiledArtifactRef: z.string().optional().describe("Contract artifact ref, defaults to 'attestation-vault-32'; 'attestation-vault' for a 16-slot vault"),
-            idempotencyKey: z.string().optional().describe('Dedupes retries'),
-            sponsorSessionId: z.string().uuid().optional().describe('Optional second session that pays the dust fee'),
-        },
-    }, run(async (args) => {
-        if (!!args.value === !!args.valueDigest) {
-            throw new Error('pass exactly one of value / valueDigest');
-        }
-        const hasList = args.allowedValues !== undefined;
-        const hasPath = !!(args.setRoot || args.setSiblings || args.setDirs);
-        if (hasList && hasPath)
-            throw new Error('pass either allowedValues or setRoot + setSiblings + setDirs, not both');
-        if (!hasList && !(args.setRoot && args.setSiblings && args.setDirs)) {
-            throw new Error('allowedValues or setRoot + setSiblings + setDirs is required');
-        }
-        return client.callAction('issueFieldMembershipAttestation', {
-            payloadHash: args.payloadHash,
-            attesterId: args.attesterId,
-            fieldKey: args.fieldKey,
-            value: args.value,
-            valueDigest: args.valueDigest,
-            allowedValues: args.allowedValues,
-            setRoot: args.setRoot,
-            setSiblings: args.setSiblings,
-            setDirs: args.setDirs,
-            fieldSalt: args.fieldSalt,
-            contentRoot: args.contentRoot,
-            schemaId: args.schemaId,
-            siblings: args.siblings,
-            dirs: args.dirs,
-            sessionId: args.sessionId,
-            contractAddress: args.contractAddress,
-            compiledArtifactRef: args.compiledArtifactRef ?? DEFAULT_ARTIFACT,
-            idempotencyKey: args.idempotencyKey,
-            sponsorSessionId: args.sponsorSessionId,
+    /** Wait for a swap job; a landed swap frees its half here. */
+    const awaitSwap = async (started, offerId, extra) => {
+        const check = offerId ? { tool: 'get_swap_offer', args: { offerId } } : { tool: 'get_swap_wallet', args: {} };
+        const job = await awaitJob(client, config, started, extra, check);
+        if (typeof started.jobId === 'string')
+            settleHalfJob(started.jobId, job.status);
+        return job;
+    };
+    /** Hand bytes to a sponsor once and wait; the same bytes again pick up that job. */
+    const sponsorOnce = async (action, body, extra, check) => {
+        const key = callKey(action, body);
+        const started = await startOnce(key, async () => await client.callAction(action, body));
+        const job = await awaitJob(client, config, started, extra, check);
+        if (job.status === 'failed')
+            forgetStart(key);
+        return job;
+    };
+    /** Build one vault call here, hand it to the sponsor and wait until it settled. */
+    const submitVaultCall = async (input, idempotencyKey, extra) => {
+        if (!config)
+            throw new Error('local building is not configured for this server instance');
+        const key = callKey('vault', input.contractAddress, input.compiledArtifactRef ?? DEFAULT_ARTIFACT, input.call, input.params, input.merkleProof, input.docPair);
+        const started = await startOnce(key, async () => {
+            const built = await buildSponsorable(config, { ...input, bind: false });
+            const { b64 } = await resolveTxSource({ txId: built.txId }, 'unboundTxB64');
+            const job = await client.callAction('sponsorUnboundTransaction', { unboundTxB64: b64, idempotencyKey });
+            return { ...job, attesterId: built.attesterId, contractAddress: input.contractAddress, buildMs: built.buildMs };
         });
-    }));
-    server.registerTool('prove_field_predicates_batch', {
-        description: 'Batch variant of the field proof tools: prove up to 8 field-bound claims on ONE anchored ' +
-            'document in ONE transaction (7 if contentRoot is supplied, since the anchor occupies one ' +
-            'call slot). Claims may MIX the three kinds (NIGHTGATE >= 0.16.0), discriminated by ' +
-            'predicate: numeric (lessOrEqual/greaterOrEqual), bytesEquality, setMembership. Duplicate ' +
-            'claim tuples are dropped server-side. One false claim aborts the whole batch at local ' +
-            'proving time with zero on-chain effect. After submission the chain can finalize a ' +
-            'PARTIAL_SUCCESS subset; verify per claim via verify_predicate_attestation instead of ' +
-            'assuming all-or-nothing. ' + POLL_HINT,
-        inputSchema: {
-            payloadHash: hex64('payloadHash').describe('Shared attestation payload hash; also document A of any cross-root claim (64 hex)'),
-            attesterId: hex64('attesterId').optional()
-                .describe('The attester whose record of payloadHash the claim is bound to (64 hex); default the session\'s own. A contentRoot can only be anchored under the session\'s own record'),
-            claims: z.array(z.union([numericClaim, equalityClaim, membershipClaim, documentIntegrityClaim, documentDiffClaim]))
-                .min(1).max(8)
-                .describe('1-8 claims on the same payload hash; any mix of numeric, bytesEquality, setMembership, documentIntegrity and documentDiff'),
-            sessionId: z.string().uuid().describe('Wallet session id that signs and submits'),
-            contractAddress: z.string().min(1).describe('AttestationVault deployment'),
-            contentRoot: hex64('contentRoot').optional().describe('Optional Merkle root anchored as first call of the same batch'),
-            schemaId: hex64('schemaId').optional().describe('Schema id of the field list, required whenever contentRoot is supplied'),
-            compiledArtifactRef: z.string().optional().describe("Contract artifact ref, defaults to 'attestation-vault-32'; 'attestation-vault' for a 16-slot vault"),
-            idempotencyKey: z.string().optional().describe('Dedupes retries'),
-            sponsorSessionId: z.string().uuid().optional().describe('Optional second session that pays the dust fee'),
-        },
-    }, run(async (args) => {
-        if (args.contentRoot && args.claims.length > 7) {
-            throw new Error('with contentRoot the anchor occupies one slot: max 7 claims');
+        const job = await awaitJob(client, config, started, extra, checkFor(input, String(started.attesterId)));
+        if (job.status === 'failed')
+            forgetStart(key);
+        return job;
+    };
+    server.registerTool('anchor_document', {
+        description: 'Anchor a document hash on Midnight in one call: builds the attest transaction here with ' +
+            'the caller seed, a sponsor pays the fee, and the tool waits until it landed (about 1 to 2 ' +
+            'minutes; the first call also downloads the prover keys). The record belongs to this ' +
+            'seed (attesterId). Only the hash and the hash of the metadata go on-chain; keep the ' +
+            'document yourself. With contentRoot and schemaId from prepare_document_proof it also ' +
+            'anchors the content root, which the field claims of submit_vault_call need. Returns ' +
+            '{ status, attesterId, payloadHash, contractAddress, metadataJson, txHash, transactionHash, ' +
+            'check }; check is the verify_attestation call that shows the record on-chain. ' + RETRY_HINT,
+        inputSchema: {
+            sha256: hex64('sha256').describe('sha256 of the document (64 hex); it becomes the payloadHash'),
+            metadata: z.record(z.unknown()).optional()
+                .describe('Public metadata; its sha256 is anchored with the hash. Default none'),
+            contentRoot: hex64('contentRoot').optional().describe('Content root from prepare_document_proof (64 hex); needs schemaId'),
+            schemaId: hex64('schemaId').optional().describe('Schema id from prepare_document_proof (64 hex); needs contentRoot'),
+            contractAddress: CONTRACT,
+            compiledArtifactRef: z.enum(BUILDABLE_ARTIFACTS).optional()
+                .describe("Vault lineage, default 'attestation-vault-32' (the sandbox vaults); 'attestation-vault' for a 16-slot vault"),
+            idempotencyKey: z.string().optional().describe('Dedupes retries of the same anchor'),
+        },
+    }, run(async (args, extra) => {
+        if (!!args.contentRoot !== !!args.schemaId)
+            throw new Error('pass contentRoot and schemaId together');
+        const contractAddress = vault(args.contractAddress, args.compiledArtifactRef);
+        const payloadHash = args.sha256.toLowerCase();
+        const metadataJson = args.metadata === undefined ? '' : JSON.stringify(args.metadata);
+        const metadataHash = createHash('sha256').update(metadataJson, 'utf8').digest('hex');
+        const ref = args.compiledArtifactRef ?? DEFAULT_ARTIFACT;
+        const anchor = await submitVaultCall({ contractAddress, call: 'attest', params: { payloadHash, metadataHash }, compiledArtifactRef: ref }, args.idempotencyKey, extra);
+        if (!args.contentRoot || !args.schemaId)
+            return { ...anchor, payloadHash, metadataJson };
+        if (anchor.status !== 'succeeded') {
+            const rootNext = anchor.status === 'pending'
+                ? 'Run anchor_document again with the same arguments: it waits for this anchor and then anchors the content root.'
+                : 'The content root needs the anchor first.';
+            return { ...anchor, payloadHash, metadataJson, contentRoot: { status: 'not anchored', next: rootNext } };
         }
-        return client.callAction('issueFieldPredicateAttestationBatch', {
-            payloadHash: args.payloadHash,
-            attesterId: args.attesterId,
-            contentRoot: args.contentRoot,
-            schemaId: args.schemaId,
-            claims: args.claims.map((c) => 'threshold' in c ? { ...c, threshold: String(c.threshold) } : c),
-            sessionId: args.sessionId,
-            contractAddress: args.contractAddress,
-            compiledArtifactRef: args.compiledArtifactRef ?? DEFAULT_ARTIFACT,
-            idempotencyKey: args.idempotencyKey,
-            sponsorSessionId: args.sponsorSessionId,
-        });
+        const root = await submitVaultCall({ contractAddress, call: 'anchorContentRoot', params: { payloadHash, contentRoot: args.contentRoot, schemaId: args.schemaId }, compiledArtifactRef: ref }, args.idempotencyKey && `${args.idempotencyKey}:root`, extra);
+        return { ...root, payloadHash, metadataJson, anchorTxHash: anchor.txHash };
     }));
-    server.registerTool('prove_document_integrity', {
-        description: 'Prove that document B differs from anchored document A ONLY in the slots flagged by a ' +
-            'public slot mask, values hidden: the version-integrity claim ("v2 changed nothing ' +
-            'outside the allowed fields"). Both documents must be anchored, prepared with the SAME ' +
-            'ordered field list (identical schemaId) and you need BOTH full openings, which is why ' +
-            'this only works for a party that holds both documents. A mask that frees every real slot ' +
-            'is vacuous and rejected; a slot that changed, appeared or disappeared outside the mask ' +
-            'fails at local proving time with zero on-chain effect. ' + POLL_HINT,
-        inputSchema: {
-            payloadHashA: hex64('payloadHashA').describe('Anchored document A (64 hex)'),
-            payloadHashB: hex64('payloadHashB').describe('Anchored document B; must differ from A'),
-            attesterIdA: hex64('attesterIdA').optional()
-                .describe('Document A\'s attester (64 hex); default the session\'s own'),
-            attesterIdB: hex64('attesterIdB').optional()
-                .describe('Document B\'s attester (64 hex); default attesterIdA'),
-            allowedMask: z.number().int().min(0).max(MAX_MASK - 1)
-                .describe('Packed slot mask, one bit per slot of the vault width (16 bits by default, 32 on attestation-vault-32), bit i = slot i MAY differ. At least one real schema slot must stay constrained'),
-            schema: schemaSlots,
-            openingA: documentOpening,
-            openingB: documentOpening,
-            sessionId: z.string().uuid().describe('Wallet session id that signs and submits'),
-            contractAddress: z.string().min(1).describe('AttestationVault deployment'),
-            contentRootA: hex64('contentRootA').optional().describe('Optional: anchor A\'s root in the same flow'),
-            contentRootB: hex64('contentRootB').optional().describe('Optional: anchor B\'s root in the same flow'),
-            schemaId: hex64('schemaId').optional().describe('Shared schema id, required whenever a contentRoot is supplied'),
-            compiledArtifactRef: z.string().optional().describe("Contract artifact ref, defaults to 'attestation-vault-32'; 'attestation-vault' for a 16-slot vault"),
-            idempotencyKey: z.string().optional().describe('Dedupes retries'),
-            sponsorSessionId: z.string().uuid().optional().describe('Optional second session that pays the dust fee'),
-        },
-    }, run(async (args) => {
-        if (maskFreesEveryRealSlot(args.allowedMask, args.schema))
-            throw new Error(VACUOUS_MASK_MESSAGE);
-        return client.callAction('issueDocumentIntegrityAttestation', {
-            payloadHashA: args.payloadHashA,
-            payloadHashB: args.payloadHashB,
-            attesterIdA: args.attesterIdA,
-            attesterIdB: args.attesterIdB,
-            allowedMask: args.allowedMask,
-            schema: args.schema,
-            openingA: args.openingA,
-            openingB: args.openingB,
-            contentRootA: args.contentRootA,
-            contentRootB: args.contentRootB,
-            schemaId: args.schemaId,
-            sessionId: args.sessionId,
-            contractAddress: args.contractAddress,
-            compiledArtifactRef: args.compiledArtifactRef ?? DEFAULT_ARTIFACT,
-            idempotencyKey: args.idempotencyKey,
-            sponsorSessionId: args.sponsorSessionId,
-        });
-    }));
-    server.registerTool('prove_document_diff', {
-        description: 'Prove that at least k of the aligned slots differ between two anchored documents ' +
-            '(16 slots on the default vault, 32 on attestation-vault-32), ' +
-            'without revealing which slots or what values: the distinctness claim (k=1 is "provably ' +
-            'not the same document"). Same requirements as prove_document_integrity: identical field ' +
-            'list, both openings in hand. A difference is a value change or a field that appeared or ' +
-            'disappeared; both-empty slots compare equal and padding never counts. k above the real ' +
-            'count fails at local proving time with zero on-chain effect. ' + POLL_HINT,
-        inputSchema: {
-            payloadHashA: hex64('payloadHashA').describe('Anchored document A (64 hex)'),
-            payloadHashB: hex64('payloadHashB').describe('Anchored document B; must differ from A'),
-            attesterIdA: hex64('attesterIdA').optional()
-                .describe('Document A\'s attester (64 hex); default the session\'s own'),
-            attesterIdB: hex64('attesterIdB').optional()
-                .describe('Document B\'s attester (64 hex); default attesterIdA'),
-            k: z.number().int().min(1).max(MAX_SLOT_WIDTH).describe('Minimum number of differing slots to prove, up to the vault width'),
-            schema: schemaSlots,
-            openingA: documentOpening,
-            openingB: documentOpening,
-            sessionId: z.string().uuid().describe('Wallet session id that signs and submits'),
-            contractAddress: z.string().min(1).describe('AttestationVault deployment'),
-            contentRootA: hex64('contentRootA').optional().describe('Optional: anchor A\'s root in the same flow'),
-            contentRootB: hex64('contentRootB').optional().describe('Optional: anchor B\'s root in the same flow'),
-            schemaId: hex64('schemaId').optional().describe('Shared schema id, required whenever a contentRoot is supplied'),
-            compiledArtifactRef: z.string().optional().describe("Contract artifact ref, defaults to 'attestation-vault-32'; 'attestation-vault' for a 16-slot vault"),
-            idempotencyKey: z.string().optional().describe('Dedupes retries'),
-            sponsorSessionId: z.string().uuid().optional().describe('Optional second session that pays the dust fee'),
-        },
-    }, run(async (args) => client.callAction('issueDocumentDiffAttestation', {
-        payloadHashA: args.payloadHashA,
-        payloadHashB: args.payloadHashB,
-        attesterIdA: args.attesterIdA,
-        attesterIdB: args.attesterIdB,
-        k: args.k,
-        schema: args.schema,
-        openingA: args.openingA,
-        openingB: args.openingB,
-        contentRootA: args.contentRootA,
-        contentRootB: args.contentRootB,
-        schemaId: args.schemaId,
-        sessionId: args.sessionId,
-        contractAddress: args.contractAddress,
-        compiledArtifactRef: args.compiledArtifactRef ?? DEFAULT_ARTIFACT,
-        idempotencyKey: args.idempotencyKey,
-        sponsorSessionId: args.sponsorSessionId,
-    })));
-    server.registerTool('grant_disclosure', {
-        description: 'Grant a disclosure level for an attestation to a grantee identity, on-chain via the ' +
-            'AttestationVault. Attester-only: the transaction is rejected in-circuit unless the ' +
-            'session wallet is the original attester. level: 0=public, 1=legitimate-interest, ' +
-            '2=authority. ' + POLL_HINT,
-        inputSchema: {
-            payloadHash: hex64('payloadHash').describe('The attestation payload hash (64 hex)'),
-            grantee: hex64('grantee').describe('Grantee identity (64 hex Bytes<32>)'),
-            level: z.union([z.literal(0), z.literal(1), z.literal(2)])
-                .describe('0=public, 1=legitimate-interest, 2=authority'),
-            sessionId: z.string().uuid().describe('Wallet session id (must be the attester)'),
-            contractAddress: z.string().min(1).describe('AttestationVault deployment'),
-            compiledArtifactRef: z.string().optional().describe("Contract artifact ref, defaults to 'attestation-vault-32'; 'attestation-vault' for a 16-slot vault"),
-            idempotencyKey: z.string().optional().describe('Dedupes retries'),
-            sponsorSessionId: z.string().uuid().optional().describe('Optional second session that pays the dust fee'),
-        },
-    }, run(async (args) => client.callAction('grantDisclosure', {
-        payloadHash: args.payloadHash,
-        grantee: args.grantee,
-        level: args.level,
-        sessionId: args.sessionId,
-        contractAddress: args.contractAddress,
-        compiledArtifactRef: args.compiledArtifactRef ?? DEFAULT_ARTIFACT,
-        idempotencyKey: args.idempotencyKey,
-        sponsorSessionId: args.sponsorSessionId,
-    })));
-    server.registerTool('revoke_disclosure', {
-        description: 'Revoke a previously granted disclosure on-chain (removes the grantee entry). ' +
-            'Attester-only, enforced in-circuit. ' + POLL_HINT,
-        inputSchema: {
-            payloadHash: hex64('payloadHash').describe('The attestation payload hash (64 hex)'),
-            grantee: hex64('grantee').describe('Grantee identity (64 hex Bytes<32>)'),
-            sessionId: z.string().uuid().describe('Wallet session id (must be the attester)'),
-            contractAddress: z.string().min(1).describe('AttestationVault deployment'),
-            compiledArtifactRef: z.string().optional().describe("Contract artifact ref, defaults to 'attestation-vault-32'; 'attestation-vault' for a 16-slot vault"),
-            idempotencyKey: z.string().optional().describe('Dedupes retries'),
-            sponsorSessionId: z.string().uuid().optional().describe('Optional second session that pays the dust fee'),
+    server.registerTool('submit_vault_call', {
+        description: 'Run any AttestationVault call in one go: build, prove and sign it here with the caller ' +
+            'seed, a sponsor pays, and the tool waits until it landed. Same calls and params as ' +
+            'build_sponsorable_transaction: the ZK claims over a hidden field (proveFieldPredicate, ' +
+            'proveFieldEquality, proveFieldMembership), the claims across two documents ' +
+            '(proveFieldsUnchangedExcept, proveFieldsDiffer), disclosure (grantDisclosure, ' +
+            'revokeDisclosure), passports and anchoring. The witness from prepare_document_proof is ' +
+            'used here and never sent. Returns { status, attesterId, contractAddress, txHash, ' +
+            'transactionHash, check }; check is the free verify call that shows the effect on-chain. ' +
+            'A failed job says in `next` what to do. ' + RETRY_HINT,
+        inputSchema: {
+            contractAddress: CONTRACT,
+            call: z.enum(BUILDABLE_CALLS).describe('Which circuit to call'),
+            params: z.record(z.union([z.string(), z.number()]))
+                .describe('The call parameters, listed per call in build_sponsorable_transaction'),
+            merkleProof: z.record(z.any()).optional()
+                .describe('WITNESS for the proveField* calls, as prepare_document_proof returns it for that field'),
+            docPair: z.record(z.any()).optional()
+                .describe('WITNESS { schema, openingA, openingB } for proveFieldsUnchangedExcept and proveFieldsDiffer'),
+            compiledArtifactRef: z.enum(BUILDABLE_ARTIFACTS).optional()
+                .describe("Vault lineage, default 'attestation-vault-32' (the sandbox vaults); 'attestation-vault' for a 16-slot vault"),
+            idempotencyKey: z.string().optional().describe('Dedupes retries of the same call'),
         },
-    }, run(async (args) => client.callAction('revokeDisclosure', {
-        payloadHash: args.payloadHash,
-        grantee: args.grantee,
-        sessionId: args.sessionId,
-        contractAddress: args.contractAddress,
-        compiledArtifactRef: args.compiledArtifactRef ?? DEFAULT_ARTIFACT,
-        idempotencyKey: args.idempotencyKey,
-        sponsorSessionId: args.sponsorSessionId,
-    })));
+    }, run(async (args, extra) => submitVaultCall({
+        contractAddress: vault(args.contractAddress, args.compiledArtifactRef), call: args.call, params: args.params,
+        merkleProof: args.merkleProof, docPair: args.docPair, compiledArtifactRef: args.compiledArtifactRef ?? DEFAULT_ARTIFACT,
+    }, args.idempotencyKey, extra)));
     server.registerTool('build_sponsorable_transaction', {
-        description: 'Build, prove and sign an AttestationVault call LOCALLY (caller half of cross-server fee ' +
-            'sponsoring, @odatano/nightgate-tx txbuilder): the seed comes from the MCP server ' +
-            'environment (NIGHTGATE_SEED_HEX), the attestation secret is derived from it, nothing ' +
-            'secret leaves this machine. The fee-unpaid transaction stays in this process under the ' +
+        description: 'Build, prove and sign an AttestationVault call LOCALLY and hand back the bytes, for a ' +
+            'sponsor on another server or a later hand-over; submit_vault_call does build and submit ' +
+            'in one go. The caller seed (NIGHTGATE_SEED_HEX, else the seed file) stays here, the ' +
+            'attestation secret is derived from it, nothing secret leaves this machine. The fee-unpaid transaction stays in this process under the ' +
             'returned txId (its sha256; characters and bytes alongside), or is written to outFile: ' +
             'UNBOUND by default (hand the txId to sponsor_unbound_transaction, parallel channel) or ' +
             'bound with bind:true (sponsor_finalized_transaction). The on-chain effect carries the attester id ' +
@@ -814,7 +409,7 @@ export function registerTools(server, client, config) {
             'the transaction TTL (~30 min) and against the contract state at build time: if the ' +
             'sponsor job ends CHAIN_EXECUTION_FAILED, build again.',
         inputSchema: {
-            contractAddress: z.string().min(1).describe('AttestationVault contract address (64 hex)'),
+            contractAddress: CONTRACT,
             call: z.enum(BUILDABLE_CALLS).describe('Which circuit to call'),
             params: z.record(z.union([z.string(), z.number()]))
                 .describe('The call parameters (see the per-call list in the description)'),
@@ -833,13 +428,13 @@ export function registerTools(server, client, config) {
         if (!config)
             throw new Error('local building is not configured for this server instance');
         return buildSponsorable(config, {
-            contractAddress: args.contractAddress, call: args.call, params: args.params, bind: args.bind === true,
+            contractAddress: vault(args.contractAddress, args.compiledArtifactRef), call: args.call, params: args.params, bind: args.bind === true,
             compiledArtifactRef: args.compiledArtifactRef ?? DEFAULT_ARTIFACT,
             merkleProof: args.merkleProof, docPair: args.docPair, outFile: args.outFile,
         });
     }));
     server.registerTool('get_attester_identity', {
-        description: 'The attester id this MCP server builds under (derived from NIGHTGATE_SEED_HEX via the ' +
+        description: 'The attester id this MCP server builds under (derived from the caller seed via the ' +
             '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 ' +
@@ -859,8 +454,7 @@ export function registerTools(server, client, config) {
             'outside it. The transaction expires with its TTL (default 30 min), so hand it over ' +
             'promptly. This is the SERIAL channel (one tx per sponsor wallet at a time); for ' +
             'parallel submission build with bind:false and use sponsor_unbound_transaction. ' +
-            'The server picks the wallet that pays. Call get_job_status with the sessionId ' +
-            'RETURNED by this call. ' + POLL_HINT,
+            'The server picks the wallet that pays. ' + WAIT_HINT,
         inputSchema: {
             txId: TX_ID.describe('txId returned by build_sponsorable_transaction (bind:true) on this server; the bytes never pass through the conversation'),
             file: TX_FILE,
@@ -869,13 +463,9 @@ export function registerTools(server, client, config) {
             idempotencyKey: z.string().optional()
                 .describe('Dedupes retries; the request is also fingerprinted by the transaction bytes'),
         },
-    }, run(async (args) => {
+    }, run(async (args, extra) => {
         const { b64, sent } = await resolveTxSource({ txId: args.txId, file: args.file, b64: args.finalizedTxB64 }, 'finalizedTxB64');
-        const job = await client.callAction('sponsorFinalizedTransaction', {
-            finalizedTxB64: b64,
-            idempotencyKey: args.idempotencyKey,
-        });
-        return { ...job, sent };
+        return { ...await sponsorOnce('sponsorFinalizedTransaction', { finalizedTxB64: b64, idempotencyKey: args.idempotencyKey }, extra), sent };
     }));
     server.registerTool('sponsor_unbound_transaction', {
         description: 'Cross-server fee sponsoring, PARALLEL channel (NIGHTGATE 0.18.0): submit an UNBOUND ' +
@@ -889,8 +479,7 @@ export function registerTools(server, client, config) {
             'calls against the SAME contract in one block conflict, the loser lands on-chain but its ' +
             'call does not apply and the job ends failed with errorCode CHAIN_EXECUTION_FAILED (the ' +
             'transaction hash is in the error); then REBUILD the transaction against the current ' +
-            'contract state and sponsor again (never resubmit the same bytes). Call get_job_status ' +
-            'with the sessionId RETURNED by this call. ' + POLL_HINT,
+            'contract state and sponsor again (never resubmit the same bytes). ' + WAIT_HINT,
         inputSchema: {
             txId: TX_ID.describe('txId returned by build_sponsorable_transaction on this server; the bytes never pass through the conversation'),
             file: TX_FILE,
@@ -899,16 +488,12 @@ export function registerTools(server, client, config) {
             idempotencyKey: z.string().optional()
                 .describe('Dedupes retries of the SAME bytes; a rebuilt transaction is a new key'),
         },
-    }, run(async (args) => {
+    }, run(async (args, extra) => {
         const { b64, sent } = await resolveTxSource({ txId: args.txId, file: args.file, b64: args.unboundTxB64 }, 'unboundTxB64');
-        const job = await client.callAction('sponsorUnboundTransaction', {
-            unboundTxB64: b64,
-            idempotencyKey: args.idempotencyKey,
-        });
-        return { ...job, sent };
+        return { ...await sponsorOnce('sponsorUnboundTransaction', { unboundTxB64: b64, idempotencyKey: args.idempotencyKey }, extra), sent };
     }));
     server.registerTool('get_swap_wallet', {
-        description: 'The shielded wallet this MCP server swaps from (seed from NIGHTGATE_SEED_HEX): address, ' +
+        description: 'The shielded wallet this MCP server swaps from (the caller seed): 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; one posted with ' +
@@ -922,6 +507,15 @@ export function registerTools(server, client, config) {
         for (const offerId of postedOfferIds()) {
             settleBoardRows(await client.callFunction('getSwapOffer', { offerId: raw(offerId) }).catch(() => undefined));
         }
+        // a swap job that was still open when its tool returned may have landed since
+        for (const jobId of halfJobIds()) {
+            const sessionId = jobSession(jobId);
+            if (!sessionId)
+                continue;
+            const job = await client.callAction('getJobStatus', { jobId, sessionId }).catch(() => undefined);
+            if (job)
+                settleHalfJob(jobId, job.status);
+        }
         return swapWalletInfo(config);
     }));
     server.registerTool('read_swap_offer', {
@@ -959,9 +553,9 @@ export function registerTools(server, client, config) {
         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 submit: true the two halves go to the sponsor at once and the answer is the ' +
-            'job ({ jobId, status, sessionId, id, terms }): call get_job_status with the returned ' +
-            'sessionId. Without it the answer carries both halves for sponsor_swap. ALWAYS pass ' +
+            'With submit: true the two halves go to the sponsor at once and the tool waits until ' +
+            'the swap landed ({ status, txHash, transactionHash, result.swap, id, terms }). ' +
+            '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. With offerId ' +
             'the board entry is read first and the call refuses, before proving, when it is not open ' +
             'or carries another offer than `offer`. A sponsor that refuses the swap leaves the proven ' +
@@ -978,45 +572,55 @@ export function registerTools(server, client, config) {
             offerId: z.string().uuid().optional()
                 .describe('The board entry the offer came from (list_swap_offers), so the fill is recorded against it'),
         },
-    }, run(async (args) => {
+    }, run(async (args, extra) => {
         if (!config)
             throw new Error('swaps are not configured for this server instance');
-        if (args.offerId) {
-            const row = await client.callFunction('getSwapOffer', { offerId: raw(args.offerId) });
-            if (row.status !== 'open')
-                throw new Error(`board offer ${args.offerId} is ${String(row.status)}, not open`);
-            if (typeof row.offer !== 'string' || !(await sameOffer(args.offer, row.offer))) {
-                throw new Error(`board offer ${args.offerId} carries another offer than the one passed: take the board's text, or drop offerId`);
+        const take = async () => {
+            if (args.offerId) {
+                const row = await client.callFunction('getSwapOffer', { offerId: raw(args.offerId) });
+                if (row.status !== 'open')
+                    throw new Error(`board offer ${args.offerId} is ${String(row.status)}, not open`);
+                if (typeof row.offer !== 'string' || !(await sameOffer(args.offer, row.offer))) {
+                    throw new Error(`board offer ${args.offerId} carries another offer than the one passed: take the board's text, or drop offerId`);
+                }
             }
-        }
-        const taken = await takeOffer(config, {
-            offer: args.offer,
-            ...(args.expect ? { expect: { gives: legOut(args.expect.gives), wants: legOut(args.expect.wants) } } : {}),
-        });
-        if (args.submit !== true)
-            return taken;
-        let job;
-        try {
-            job = await client.callAction('sponsorSwap', {
-                ...(args.offerId ? { offerId: args.offerId } : { makerHalfB64: taken.makerHalfB64 }),
-                takerHalfB64: taken.takerHalfB64,
-                idempotencyKey: args.idempotencyKey,
+            return takeOffer(config, {
+                offer: args.offer,
+                ...(args.expect ? { expect: { gives: legOut(args.expect.gives), wants: legOut(args.expect.wants) } } : {}),
             });
-        }
-        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 };
+        };
+        if (args.submit !== true)
+            return take();
+        const key = callKey('takeSwapOffer', args.offer, args.expect, args.offerId);
+        const started = await startOnce(key, async () => {
+            const taken = await take();
+            let job;
+            try {
+                job = await client.callAction('sponsorSwap', {
+                    ...(args.offerId ? { offerId: args.offerId } : { makerHalfB64: taken.makerHalfB64 }),
+                    takerHalfB64: taken.takerHalfB64,
+                    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 };
+        });
+        const settled = await awaitSwap(started, args.offerId, extra);
+        if (settled.status === 'failed')
+            forgetStart(key);
+        return settled;
     }));
     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.',
+            'get_swap_wallet; a half whose swap landed leaves the list.',
         inputSchema: {
             id: z.string().regex(/^[0-9a-f]{32}$/, 'id must be the 32 hex characters a swap tool returned'),
         },
@@ -1036,7 +640,7 @@ export function registerTools(server, client, config) {
             '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); with `offerId` the maker half comes from the board, next to takerHalf or the ' +
-            'halfId of the taken offer. Call get_job_status with the sessionId RETURNED by this call. ' + POLL_HINT,
+            'halfId of the taken offer. ' + WAIT_HINT,
         inputSchema: {
             makerHalf: swapHalf("The maker's half (the offer)").optional(),
             takerHalf: swapHalf("The taker's half").optional(),
@@ -1047,7 +651,7 @@ export function registerTools(server, client, config) {
             offerId: z.string().uuid().optional()
                 .describe('An offer on the server\'s board (list_swap_offers): the server takes the maker half from there; pass takerHalf or the halfId of the taken offer with it'),
         },
-    }, run(async (args) => {
+    }, run(async (args, extra) => {
         let halves;
         if (args.offerId) {
             if (args.makerHalf)
@@ -1066,13 +670,17 @@ export function registerTools(server, client, config) {
                 ? { makerHalfB64: args.makerHalf, takerHalfB64: args.takerHalf }
                 : takenHalves(args.halfId);
         }
-        const job = await client.callAction('sponsorSwap', {
-            ...halves,
-            idempotencyKey: args.idempotencyKey,
+        const key = callKey('sponsorSwap', halves);
+        const started = await startOnce(key, async () => {
+            const job = await client.callAction('sponsorSwap', { ...halves, idempotencyKey: args.idempotencyKey });
+            if (args.halfId)
+                trackHalfJob(args.halfId, job?.jobId);
+            return job;
         });
-        if (args.halfId)
-            trackHalfJob(args.halfId, job?.jobId);
-        return job;
+        const settled = await awaitSwap(started, args.offerId, extra);
+        if (settled.status === 'failed')
+            forgetStart(key);
+        return settled;
     }));
     server.registerTool('post_swap_offer', {
         description: 'Post a maker half on the server\'s offer board, so takers find it with list_swap_offers ' +
@@ -1143,66 +751,6 @@ export function registerTools(server, client, config) {
             offerId: z.string().uuid().describe('The board entry'),
         },
     }, run(async (args) => client.callAction('retireSwapOffer', { offerId: args.offerId })));
-    server.registerTool('grant_disclosure_to_holders', {
-        description: 'Disclose a document to everyone who holds a token: whoever registered a claim key on ' +
-            'the holder-registry contract for tokenType by passing a coin through it can read the ' +
-            'text with claim_disclosure, and the server never learns who. content must hash to ' +
-            'payloadHash (blake2b-256 or sha256 of the UTF-8 text); it is stored encrypted. A repeat ' +
-            'call for the same payload, token type and registry updates the grant (content kept ' +
-            'when omitted). Returns { holderGrantId, hasContent, expiresAt, status }.',
-        inputSchema: {
-            payloadHash: hex64('payloadHash').describe('Hash of the document (64 hex)'),
-            tokenType: hex64('tokenType').describe('The raw shielded token type whose holders may read (64 hex)'),
-            registryAddress: hex64('registryAddress').describe('The holder-registry deployment holders registered on'),
-            content: z.string().max(1_048_576).optional().describe('The document text; must hash to payloadHash'),
-            contentType: z.string().max(100).optional().describe("Default 'text/plain'"),
-            expiresAt: z.string().datetime().optional().describe('ISO timestamp, at most one year ahead'),
-        },
-    }, run(async (args) => client.callAction('grantDisclosureToHolders', {
-        payloadHash: args.payloadHash.toLowerCase(),
-        tokenType: args.tokenType.toLowerCase(),
-        registryAddress: args.registryAddress.toLowerCase(),
-        content: args.content,
-        contentType: args.contentType,
-        expiresAt: args.expiresAt,
-    })));
-    server.registerTool('revoke_holder_disclosure', {
-        description: 'Revoke a disclosure to token holders. Only its grantor may. Returns { holderGrantId, status }.',
-        inputSchema: {
-            holderGrantId: z.string().uuid().describe('From grant_disclosure_to_holders'),
-        },
-    }, run(async (args) => client.callAction('revokeHolderDisclosure', { holderGrantId: args.holderGrantId })));
-    server.registerTool('claim_disclosure', {
-        description: 'Read a document disclosed to the holders of a token. claimSecret is the 32-byte secret ' +
-            'behind the claim key registered on the holder-registry contract (holder_claim_key); the ' +
-            'server reads the registry live and answers { entitled, content, contentType, ' +
-            'contentHashKind, expiresAt } or { entitled: false, reason }. Needs a live indexer on ' +
-            'the server.',
-        inputSchema: {
-            payloadHash: hex64('payloadHash').describe('Hash of the document (64 hex)'),
-            tokenType: hex64('tokenType').describe('The raw shielded token type (64 hex)'),
-            claimSecret: hex64('claimSecret').describe('The secret behind the registered claim key (64 hex)'),
-        },
-    }, run(async (args) => client.callAction('claimDisclosure', {
-        payloadHash: args.payloadHash.toLowerCase(),
-        tokenType: args.tokenType.toLowerCase(),
-        claimSecret: args.claimSecret.toLowerCase(),
-    })));
-    server.registerTool('holder_claim_key', {
-        description: 'The claim key a token holder registers on the holder-registry contract, derived from a ' +
-            '32-byte secret (compute-only). Without a secret a fresh random one is generated: keep ' +
-            'it, claim_disclosure needs it. Register the key with registerHolder(coin, claimKey) on ' +
-            'the registry (one coin of the token type passes through the contract and comes back), ' +
-            'e.g. through build_sponsorable_transaction on a builder that knows the registry.',
-        inputSchema: {
-            claimSecret: hex64('claimSecret').optional().describe('Existing secret (64 hex); omit to generate one'),
-        },
-    }, run(async (args) => {
-        const holderClaimKey = await txExport('holderClaimKey', 'holder_claim_key', '0.10.0');
-        const { randomBytes } = await import('node:crypto');
-        const claimSecret = (args.claimSecret ?? randomBytes(32).toString('hex')).toLowerCase();
-        return { claimSecret, claimKey: holderClaimKey(claimSecret) };
-    }));
     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, ' +
@@ -1219,18 +767,14 @@ export function registerTools(server, client, config) {
         domainSeparator: args.domainSeparator,
     })));
     server.registerTool('mint_token', {
-        description: 'Mint a shielded token with a name of your own on a token-factory deployment. Two ways. ' +
-            'LOCAL (default, no sessionId): this process is the issuer, its issuer secret derives from ' +
-            'NIGHTGATE_SEED_HEX, the mint is built, proven and signed here and the fee-unpaid ' +
-            'transaction goes to the sponsor like sponsor_unbound_transaction; the seed never ' +
-            'leaves this process. The factory has to be ' +
-            'on the sponsor\'s contract list and mint on its circuit list. SERVER (sessionId given): the ' +
-            'server session is the issuer and mints through mintFactoryToken; needs that action in ' +
-            'the grant. Either way the same name from another issuer is another token, and the ' +
-            'response names the token before the job runs ({ tokenType, domain, issuerKey }); a ' +
-            'landed mint makes the type known to the sponsor (swaps, offer board). The recipient ' +
-            'defaults to this wallet (get_attester_identity); another wallet takes both of its keys. ' +
-            'Job result { txHash, transactionHash, ... }. Call get_job_status with the sessionId RETURNED by this call. ' + POLL_HINT,
+        description: 'Mint a shielded token with a name of your own on a token-factory deployment. This ' +
+            'process is the issuer: its issuer secret derives from the caller seed, the mint is ' +
+            'built, proven and signed here, and a sponsor pays; the seed never leaves this process. ' +
+            'The factory has to be on the sponsor\'s contract list and mint on its circuit list. ' +
+            'The same name from another issuer is another token. The answer names the token ' +
+            '({ tokenType, domain, issuerKey }); a landed mint makes the type known to the sponsor ' +
+            '(swaps, offer board). The recipient defaults to this wallet (get_attester_identity); ' +
+            'another wallet takes both of its keys. ' + WAIT_HINT,
         inputSchema: {
             contractAddress: hex64('contractAddress').describe('A token-factory deployment'),
             name: z.string().min(1).refine((s) => Buffer.byteLength(s, 'utf8') <= 32, 'name must be at most 32 UTF-8 bytes')
@@ -1242,92 +786,46 @@ export function registerTools(server, client, config) {
             recipientCoinPublicKey: hex64('recipientCoinPublicKey').optional()
                 .describe('Zswap coin public key of the receiving wallet (64 hex); default this wallet\'s own'),
             recipientEncryptionPublicKey: hex64('recipientEncryptionPublicKey').optional()
-                .describe('The receiving wallet\'s encryption public key (64 hex); required with a recipient other than this wallet, local way'),
-            sessionId: z.string().uuid().optional()
-                .describe('Server way only: the wallet session that mints; it is the issuer'),
+                .describe('The receiving wallet\'s encryption public key (64 hex); required with a recipient other than this wallet'),
             idempotencyKey: z.string().optional().describe('Dedupes retries'),
         },
-    }, run(async (args) => {
-        if (args.sessionId) {
-            let recipient = args.recipientCoinPublicKey;
-            if (!recipient) {
-                if (!config?.seedHex)
-                    throw new Error('mint_token needs recipientCoinPublicKey: no NIGHTGATE_SEED_HEX for a default');
-                recipient = (await seedIdentity(config)).coinPublicKey;
-                if (!recipient)
-                    throw new Error('mint_token needs recipientCoinPublicKey: the seed exposes no shielded keys');
-            }
-            return client.callAction('mintFactoryToken', {
-                contractAddress: args.contractAddress.toLowerCase(),
-                name: args.name,
-                amount: String(args.amount),
-                recipientCoinPublicKey: recipient.toLowerCase(),
-                sessionId: args.sessionId,
-                idempotencyKey: args.idempotencyKey,
-            });
-        }
+    }, run(async (args, extra) => {
         if (!config)
             throw new Error('local minting is not configured for this server instance');
-        const built = await buildMint(config, {
+        const input = {
             contractAddress: args.contractAddress,
             name: args.name,
             amount: String(args.amount),
             recipientCoinPublicKey: args.recipientCoinPublicKey,
             recipientEncryptionPublicKey: args.recipientEncryptionPublicKey,
+        };
+        const key = callKey('mintToken', input);
+        const started = await startOnce(key, async () => {
+            const { unboundTxB64, ...built } = await buildMint(config, input);
+            const job = await client.callAction('sponsorUnboundTransaction', { unboundTxB64, idempotencyKey: args.idempotencyKey });
+            return { ...built, ...job };
         });
-        const job = await client.callAction('sponsorUnboundTransaction', {
-            unboundTxB64: built.unboundTxB64,
-            idempotencyKey: args.idempotencyKey,
-        });
-        const { unboundTxB64: _tx, ...rest } = built;
-        return { ...job, ...rest, channel: 'local' };
+        const job = await awaitJob(client, config, started, extra, { tool: 'get_swap_wallet', args: {} });
+        if (job.status === 'failed')
+            forgetStart(key);
+        return job;
     }));
-    server.registerTool('get_grant_usage', {
-        description: 'What this key did and what it may still do: jobs by kind and status, landed, failed, dustPaid, ' +
-            'and limits { jobsPerHour, jobsPerDay: { max, used, resetsAt }, classes: [{ name, windowSeconds, max, remaining }] }. ' +
-            'Read it before a burst and after a 429 (the error carries retryAfterSeconds). Default window: the last 30 days.',
+    server.registerTool('get_usage', {
+        description: 'What this key has left and what it spent. With a gateway key (oda_...): unitsLeft, ' +
+            'validUntil, status, usage today and over 30 days, and the last calls with the units each ' +
+            'one cost (ledger). Free. With an agent grant of a direct instance: jobs by kind and ' +
+            'status and the limits { jobsPerHour, jobsPerDay, classes }. Read it before a burst and ' +
+            'after a 429 (the error carries retryAfterSeconds).',
         inputSchema: {
-            since: z.string().datetime().optional().describe('ISO timestamp; start of the usage window'),
-            until: z.string().datetime().optional().describe('ISO timestamp; end of the usage window'),
-        },
-    }, run(async (args) => client.callFunction('getGrantUsage', { grantId: null, since: args.since ?? null, until: args.until ?? null })));
-    server.registerTool('get_job_status', {
-        description: 'Status of an async NIGHTGATE job (all submit actions return a jobId). ' +
-            'status: pending | running | external_execution | submitted | reconciliation_required | ' +
-            'succeeded | failed. The server holds the call up to waitMs (default 20 s) until the job ' +
-            'settles, so call it again only if the status is still open; result carries the job outcome ' +
-            'JSON, chainStatus tracks on-chain finalization independently. txHash and transactionId are ' +
-            'the ledger identifier (stable, tracks the job); transactionHash is the hash explorers show, ' +
-            'null until indexed. ' +
-            '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. ' +
-            '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. Mints: tokenType.',
-        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'),
-            waitMs: z.number().int().min(0).max(25_000).optional()
-                .describe('ms the server waits for the job to settle before it answers; default 20000, 0 answers at once'),
+            since: z.string().datetime().optional().describe('Agent grants only: ISO timestamp, start of the window; default 30 days back'),
+            until: z.string().datetime().optional().describe('Agent grants only: ISO timestamp, end of the window'),
         },
     }, run(async (args) => {
-        const ask = { jobId: args.jobId, sessionId: args.sessionId };
-        const waitMs = jobWait ? Math.min(args.waitMs ?? JOB_WAIT_MS, Math.max(0, (config?.timeoutMs ?? 30_000) - 5_000)) : 0;
-        let job;
-        try {
-            job = await client.callAction('getJobStatus', waitMs > 0 ? { ...ask, waitMs } : ask);
-        }
-        catch (err) {
-            if (!(waitMs > 0 && err instanceof NightgateApiError && err.status === 400 && /waitMs/.test(err.message)))
-                throw err;
-            jobWait = false;
-            job = await client.callAction('getJobStatus', ask);
-        }
-        settleHalfJob(args.jobId, job?.status);
-        return job;
+        if (!config?.token && !config?.username)
+            throw new Error('get_usage needs a key: set ODATANO_ACCESS_KEY (an oda_... key from https://api.odatano.dev)');
+        if (config && isGatewayKey(config))
+            return client.gatewayMe();
+        return client.callFunction('getGrantUsage', { grantId: null, since: args.since ?? null, until: args.until ?? null });
     }));
 }
 /** listSwapOffers wants all seven parameters, null for the unused ones. */
@@ -1354,20 +852,44 @@ function listOffers(client, args) {
  */
 export function wrapHandler(_client) {
     return function run(fn) {
-        return async (args) => {
+        return async (args, extra) => {
+            const notice = {};
+            const stopProgress = startProgress(extra);
             try {
-                const result = await fn(args);
-                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+                const result = await seedNotice.run(notice, () => fn(args, extra));
+                const seed = notice.createdFile ? seedCreated(notice.createdFile) : undefined;
+                const out = seed && result && typeof result === 'object' && !Array.isArray(result) ? { ...result, seed } : result;
+                return { content: [{ type: 'text', text: JSON.stringify(out, null, 2) }] };
             }
             catch (err) {
+                const seed = notice.createdFile ? seedCreated(notice.createdFile) : undefined;
                 if (err instanceof NightgateApiError) {
-                    const detail = { httpStatus: err.status, code: err.code ?? null, message: err.message, ...(err.detail ?? {}) };
+                    const detail = { httpStatus: err.status, code: err.code ?? null, message: err.message, ...(err.detail ?? {}), ...(seed ? { seed } : {}) };
                     return { content: [{ type: 'text', text: JSON.stringify(detail, null, 2) }], isError: true };
                 }
                 const message = err instanceof Error ? err.message : String(err);
-                return { content: [{ type: 'text', text: message }], isError: true };
+                return { content: [{ type: 'text', text: seed ? `${message}\n${JSON.stringify({ seed }, null, 2)}` : message }], isError: true };
+            }
+            finally {
+                stopProgress();
             }
         };
     };
 }
+/** Progress every 5 s while a call runs, when the client asked for it with a progress token. */
+function startProgress(extra) {
+    const token = extra?._meta?.progressToken;
+    if (token === undefined || !extra)
+        return () => { };
+    const t0 = Date.now();
+    let n = 0;
+    const timer = setInterval(() => {
+        extra.sendNotification({
+            method: 'notifications/progress',
+            params: { progressToken: token, progress: ++n, message: `working, ${Math.round((Date.now() - t0) / 1000)} s` },
+        }).catch(() => undefined);
+    }, 5_000);
+    timer.unref?.();
+    return () => clearInterval(timer);
+}
 //# sourceMappingURL=tools.js.map