aipou-mcp-server 0.2.0

package/README.md

@@ -0,0 +1,70 @@
+# AIPOU MCP Server
+
+`aipou-mcp-server` records private, signed receipts for authorized AI tasks. It supports local receipt collection and optional claims for validated work on Base.
+
+It does not detect hidden AI use, prove task quality, replace payment rails, or require raw prompts and outputs to leave the user's machine.
+
+## Fast Local Adoption Test
+
+If you are evaluating AIPOU for an agent framework, start with the lifecycle adapter example:
+
+```bash
+npm install
+npm run build -w mcp-server
+cd examples/lifecycle-adapter
+npm install
+npm run demo
+```
+
+The demo launches this MCP server over stdio, creates a local signed receipt with an ephemeral wallet, and prints the `receiptId` reference a framework can attach to metadata. It does not claim rewards or move funds.
+
+## Run locally from this repository
+
+The npm package metadata is prepared, but the first public npm publish must be performed by the repository owner. Until `aipou-mcp-server` is published, run the MCP server from a local checkout:
+
+```bash
+npm install
+npm run build -w mcp-server
+node mcp-server/dist/index.js
+```
+
+For development:
+
+```bash
+npm run dev -w mcp-server
+```
+
+## Run after npm publication
+
+After the package is published to npm, MCP clients can launch it with:
+
+```bash
+npx -y aipou-mcp-server
+```
+
+Required configuration:
+
+```text
+AIPOU_AGENT_PRIVATE_KEY=<dedicated farming wallet key>
+AIPOU_CONTRACT_ADDRESS=0x55f0Cc5e51A1284D20337d6cbb18938C8A1ABCbB
+AIPOU_CLAIMS_ADDRESS=0x4ca4C98fB784D20EdC8E2A7F531dAab4c6e53058
+```
+
+Use a new dedicated farming wallet, never a primary wallet. Do not commit the private key. Optional claims and settlement occur only after an explicit user request.
+
+Do not configure `AIPOU_VALIDATOR_PRIVATE_KEY` on a user installation. That key is only for the separate protocol validator service. The local Ed25519 collector key and receipt metadata are stored unencrypted under `AIPOU_DATA_DIR`; restrict that directory with operating-system permissions and use encrypted backups.
+
+The default network is Base mainnet. `AIPOU_RPC_URL` and `AIPOU_DATA_DIR` can be set when a custom RPC endpoint or receipt directory is needed.
+
+Publication checklist: [docs/npm-publication.md](https://github.com/0xddneto/AI-Proof-of-Us/blob/main/docs/npm-publication.md).
+
+## Documentation
+
+- [Local Receipt Mode](https://github.com/0xddneto/AI-Proof-of-Us/tree/main/examples/local-receipt-mode)
+- [Lifecycle Adapter Example](https://github.com/0xddneto/AI-Proof-of-Us/tree/main/examples/lifecycle-adapter)
+- [Evidence Boundaries](https://github.com/0xddneto/AI-Proof-of-Us/blob/main/docs/evidence-boundaries.md)
+- [Claim Validation Policy](https://github.com/0xddneto/AI-Proof-of-Us/blob/main/docs/claim-validation-policy.md)
+- [Tokenomics](https://github.com/0xddneto/AI-Proof-of-Us/blob/main/docs/tokenomics.md)
+- [Security Policy](https://github.com/0xddneto/AI-Proof-of-Us/blob/main/SECURITY.md)
+
+License: MIT

package/dist/canonical.d.ts

@@ -0,0 +1,2 @@
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256Hex(value: string): string;

package/dist/canonical.js

@@ -0,0 +1,18 @@
+import { createHash } from "node:crypto";
+export function canonicalJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+    }
+    const record = value;
+    return `{${Object.keys(record)
+        .filter((key) => record[key] !== undefined)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+        .join(",")}}`;
+}
+export function sha256Hex(value) {
+    return `0x${createHash("sha256").update(value).digest("hex")}`;
+}

package/dist/claims.d.ts

@@ -0,0 +1,2 @@
+import type { SettlementResult } from "./types.js";
+export declare function settleRewards(maxReceipts?: number): Promise<SettlementResult>;

package/dist/claims.js

@@ -0,0 +1,150 @@
+import { MerkleTree } from "merkletreejs";
+import { AbiCoder, Contract, JsonRpcProvider, Wallet, concat, getAddress, getBytes, keccak256, parseUnits } from "ethers";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { collectorFingerprint, verifyCollectorPayload } from "./collector.js";
+import { verifyTaskAuthorization } from "./identity.js";
+import { DAY_MS, filterEligibleReceipts, settlementPolicyFromEnv } from "./policy.js";
+import { deriveTrustTier } from "./providers.js";
+import { markBatchSettled, settledReceiptsSince, unsettledReceipts } from "./store.js";
+const claimsAbi = [
+    "function token() view returns (address)",
+    "function validator() view returns (address)",
+    "function approvedRoots(bytes32 root) view returns (bool)",
+    "function publishRoot(bytes32 root)",
+    "function claimBatch(bytes32 root, address[] accounts, uint256[] amounts, bytes32[] receiptIds, bytes32[][] proofs)"
+];
+const tokenAbi = ["function emissionController() view returns (address)"];
+function claimsAddress() {
+    const value = process.env.AIPOU_CLAIMS_ADDRESS;
+    if (!value)
+        throw new Error("AIPOU_CLAIMS_ADDRESS is required to settle rewards");
+    return getAddress(value);
+}
+async function validatorPrivateKey() {
+    const keyFile = process.env.AIPOU_VALIDATOR_KEY_FILE;
+    if (keyFile) {
+        const key = (await readFile(path.resolve(keyFile), "utf8")).trim();
+        if (!key)
+            throw new Error(`AIPOU_VALIDATOR_KEY_FILE ${keyFile} is empty`);
+        return key;
+    }
+    const envKey = process.env.AIPOU_VALIDATOR_PRIVATE_KEY;
+    if (envKey) {
+        console.error("aipou-mcp: AIPOU_VALIDATOR_PRIVATE_KEY in the shared environment is deprecated; " +
+            "move it to a separate file and set AIPOU_VALIDATOR_KEY_FILE so farming agents never load the validator key");
+        return envKey;
+    }
+    throw new Error("AIPOU_VALIDATOR_KEY_FILE (or legacy AIPOU_VALIDATOR_PRIVATE_KEY) is required only on the protocol validator server");
+}
+async function validatorWallet() {
+    const provider = new JsonRpcProvider(process.env.AIPOU_RPC_URL || "https://mainnet.base.org");
+    return new Wallet(await validatorPrivateKey(), provider);
+}
+async function trustedCollectorFingerprints() {
+    const file = process.env.AIPOU_TRUSTED_COLLECTORS_FILE;
+    if (!file)
+        throw new Error("AIPOU_TRUSTED_COLLECTORS_FILE is required on the protocol validator server");
+    const content = JSON.parse(await readFile(path.resolve(file), "utf8"));
+    if (!Array.isArray(content.fingerprints))
+        throw new Error("Trusted collectors file must contain a fingerprints array");
+    return new Set(content.fingerprints);
+}
+async function verifyReceipt(receipt, trustedCollectors) {
+    const fingerprint = collectorFingerprint(receipt.collectorPublicKey);
+    if (!trustedCollectors.has(fingerprint)) {
+        throw new Error(`Untrusted collector ${fingerprint} for ${receipt.receiptId}`);
+    }
+    const { collectorSignature, batchRoot, claimTransaction, ...signedPayload } = receipt;
+    if (!verifyCollectorPayload(signedPayload, collectorSignature, receipt.collectorPublicKey)) {
+        throw new Error(`Invalid collector signature for ${receipt.receiptId}`);
+    }
+    const session = {
+        nonce: receipt.nonce,
+        wallet: receipt.wallet,
+        provider: receipt.provider,
+        model: receipt.model,
+        taskHash: receipt.taskHash,
+        client: receipt.client,
+        issuedAt: receipt.authorizationIssuedAt,
+        chainId: receipt.authorizationChainId,
+        verifyingContract: receipt.authorizationContract,
+        walletAuthorization: receipt.walletAuthorization,
+        completedAt: receipt.recordedAt
+    };
+    if (!verifyTaskAuthorization(session))
+        throw new Error(`Invalid wallet authorization for ${receipt.receiptId}`);
+    const derivedTier = await deriveTrustTier(session, {
+        nonce: receipt.nonce,
+        inputTokens: receipt.inputTokens,
+        outputTokens: receipt.outputTokens,
+        durationSeconds: receipt.durationSeconds,
+        outputHash: receipt.outputHash,
+        providerEvidence: receipt.providerEvidence
+    }, receipt.providerEvidence);
+    if (derivedTier !== receipt.trustTier)
+        throw new Error(`Invalid trust tier for ${receipt.receiptId}`);
+}
+export async function settleRewards(maxReceipts = 25) {
+    const candidates = await unsettledReceipts(maxReceipts);
+    if (candidates.length === 0)
+        throw new Error("There are no unsettled receipts");
+    const policy = settlementPolicyFromEnv();
+    const recentlySettled = await settledReceiptsSince(Date.now() - DAY_MS);
+    const { eligible: receipts, skipped } = filterEligibleReceipts(candidates, recentlySettled, policy);
+    if (receipts.length === 0) {
+        const reasons = skipped.map((item) => `${item.receiptId.slice(0, 10)}…: ${item.reason}`).join("; ");
+        throw new Error(`No receipts pass the settlement policy. Skipped: ${reasons}`);
+    }
+    const trustedCollectors = await trustedCollectorFingerprints();
+    for (const receipt of receipts)
+        await verifyReceipt(receipt, trustedCollectors);
+    const accounts = receipts.map((receipt) => receipt.wallet);
+    const amounts = receipts.map((receipt) => parseUnits(receipt.estimatedReward, 18));
+    const receiptIds = receipts.map((receipt) => receipt.receiptId);
+    const coder = AbiCoder.defaultAbiCoder();
+    // Leaves are double-hashed (inner keccak, then keccak again) so an interior
+    // Merkle node can never be replayed as a valid leaf (second-preimage guard).
+    const leaves = receipts.map((receipt, index) => {
+        const inner = keccak256(coder.encode(["address", "uint256", "bytes32"], [receipt.wallet, amounts[index], receipt.receiptId]));
+        return Buffer.from(getBytes(keccak256(concat([inner]))));
+    });
+    const tree = new MerkleTree(leaves, (value) => Buffer.from(getBytes(keccak256(value))), { sortLeaves: true, sortPairs: true });
+    const root = tree.getHexRoot();
+    const proofs = leaves.map((leaf) => tree.getHexProof(leaf));
+    const signer = await validatorWallet();
+    const address = claimsAddress();
+    const claims = new Contract(address, claimsAbi, signer);
+    const configuredValidator = getAddress(await claims.validator());
+    if (configuredValidator !== signer.address) {
+        throw new Error(`Validator mismatch: contract expects ${configuredValidator}, server uses ${signer.address}`);
+    }
+    const tokenAddress = await claims.token();
+    const token = new Contract(tokenAddress, tokenAbi, signer.provider);
+    if (getAddress(await token.emissionController()) !== address) {
+        throw new Error("AIPOUClaims is not the token emission controller");
+    }
+    const publish = await claims.publishRoot(root);
+    const publishReceipt = await publish.wait();
+    let rootApproved = false;
+    for (let attempt = 0; attempt < 10 && !rootApproved; attempt += 1) {
+        rootApproved = await claims.approvedRoots(root);
+        if (!rootApproved)
+            await new Promise((resolve) => setTimeout(resolve, 3_000));
+    }
+    if (!rootApproved)
+        throw new Error("Published Merkle root was not visible through the RPC after 30 seconds");
+    const claim = await claims.claimBatch(root, accounts, amounts, receiptIds, proofs);
+    const claimReceipt = await claim.wait();
+    if (!publishReceipt || !claimReceipt)
+        throw new Error("Settlement transaction receipt is unavailable");
+    const batch = {
+        root,
+        receiptIds,
+        publishTransaction: publishReceipt.hash,
+        claimTransaction: claimReceipt.hash,
+        settledAt: new Date().toISOString()
+    };
+    await markBatchSettled(batch);
+    return { ...batch, skippedReceipts: skipped };
+}

package/dist/collector.d.ts

@@ -0,0 +1,4 @@
+export declare function getCollectorPublicKey(): Promise<string>;
+export declare function collectorFingerprint(publicKey: string): string;
+export declare function signCollectorPayload(payload: unknown): Promise<string>;
+export declare function verifyCollectorPayload(payload: unknown, signature: string, publicKey: string): boolean;

package/dist/collector.js

@@ -0,0 +1,68 @@
+import { execFile } from "node:child_process";
+import { createHash, createPublicKey, generateKeyPairSync, sign, verify } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { canonicalJson } from "./canonical.js";
+const execFileAsync = promisify(execFile);
+// mode 0o600 is a no-op on NTFS, so on Windows the private key would keep the
+// permissive inherited ACL. Strip inheritance and grant only the current user.
+// Best-effort: an ACL failure must not block receipt collection.
+async function restrictToCurrentUser(filePath) {
+    if (process.platform !== "win32")
+        return;
+    const user = process.env.USERNAME;
+    if (!user)
+        return;
+    const principal = process.env.USERDOMAIN ? `${process.env.USERDOMAIN}\\${user}` : user;
+    try {
+        await execFileAsync("icacls", [filePath, "/inheritance:r", "/grant:r", `${principal}:F`]);
+    }
+    catch {
+        // keep the inherited ACL rather than failing key creation
+    }
+}
+function dataDir() {
+    return path.resolve(process.env.AIPOU_DATA_DIR || ".aipou");
+}
+function privateKeyPath() {
+    return path.join(dataDir(), "collector-ed25519-private.pem");
+}
+function publicKeyPath() {
+    return path.join(dataDir(), "collector-ed25519-public.pem");
+}
+async function ensureCollectorKeys() {
+    await mkdir(dataDir(), { recursive: true });
+    try {
+        const [privateKey, publicKey] = await Promise.all([
+            readFile(privateKeyPath(), "utf8"),
+            readFile(publicKeyPath(), "utf8")
+        ]);
+        return { privateKey, publicKey };
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const pair = generateKeyPairSync("ed25519");
+    const privateKey = pair.privateKey.export({ format: "pem", type: "pkcs8" }).toString();
+    const publicKey = pair.publicKey.export({ format: "pem", type: "spki" }).toString();
+    await writeFile(privateKeyPath(), privateKey, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await restrictToCurrentUser(privateKeyPath());
+    await writeFile(publicKeyPath(), publicKey, { encoding: "utf8", flag: "wx" });
+    return { privateKey, publicKey };
+}
+export async function getCollectorPublicKey() {
+    return (await ensureCollectorKeys()).publicKey;
+}
+export function collectorFingerprint(publicKey) {
+    const der = createPublicKey(publicKey).export({ format: "der", type: "spki" });
+    return `sha256:${createHash("sha256").update(der).digest("hex")}`;
+}
+export async function signCollectorPayload(payload) {
+    const { privateKey } = await ensureCollectorKeys();
+    return sign(null, Buffer.from(canonicalJson(payload)), privateKey).toString("base64");
+}
+export function verifyCollectorPayload(payload, signature, publicKey) {
+    return verify(null, Buffer.from(canonicalJson(payload)), publicKey, Buffer.from(signature, "base64"));
+}

package/dist/contract.d.ts

@@ -0,0 +1,17 @@
+export interface TokenContractConfig {
+    name: string;
+    symbol: string;
+    address: string | null;
+    decimals: number;
+    chainId: number;
+    chainName: string;
+    rpcUrl: string;
+    blockExplorer: string;
+    explorerUrl: string | null;
+    claimsAddress?: string | null;
+    claimsExplorerUrl?: string | null;
+    source: "env" | "deployment_file" | "unconfigured";
+}
+export declare const aipouTokenAbi: string[];
+export declare const aipouClaimsAbi: string[];
+export declare function getTokenContractConfig(): Promise<TokenContractConfig>;

package/dist/contract.js

@@ -0,0 +1,107 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+export const aipouTokenAbi = [
+    "function name() view returns (string)",
+    "function symbol() view returns (string)",
+    "function decimals() view returns (uint8)",
+    "function totalSupply() view returns (uint256)",
+    "function balanceOf(address account) view returns (uint256)",
+    "function emissionController() view returns (address)",
+    "function mintUsageReward(address to, uint256 amount)"
+];
+export const aipouClaimsAbi = [
+    "function validator() view returns (address)",
+    "function approvedRoots(bytes32 root) view returns (bool)",
+    "function claimedReceipts(bytes32 receiptId) view returns (bool)",
+    "function claim(bytes32 root, address account, uint256 amount, bytes32 receiptId, bytes32[] proof)"
+];
+async function configuredClaimsAddress() {
+    if (process.env.AIPOU_CLAIMS_ADDRESS)
+        return process.env.AIPOU_CLAIMS_ADDRESS;
+    const claimsPath = path.resolve(process.env.AIPOU_CLAIMS_DEPLOYMENT_FILE || "deployments/base-claims.json");
+    try {
+        const deployment = JSON.parse(await readFile(claimsPath, "utf8"));
+        return deployment.address || null;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function envConfig() {
+    const address = process.env.AIPOU_CONTRACT_ADDRESS;
+    if (!address) {
+        return null;
+    }
+    const blockExplorer = process.env.AIPOU_BLOCK_EXPLORER || "https://basescan.org";
+    return {
+        name: "AI Proof of Use",
+        symbol: "AIPOU",
+        address,
+        decimals: 18,
+        chainId: Number(process.env.AIPOU_CHAIN_ID || 8453),
+        chainName: process.env.AIPOU_CHAIN_NAME || "Base Mainnet",
+        rpcUrl: process.env.AIPOU_RPC_URL || "https://mainnet.base.org",
+        blockExplorer,
+        explorerUrl: `${blockExplorer}/token/${address}`,
+        source: "env"
+    };
+}
+async function deploymentFileConfig() {
+    const deploymentPath = path.resolve(process.env.AIPOU_DEPLOYMENT_FILE || "deployments/base.json");
+    try {
+        const deployment = JSON.parse(await readFile(deploymentPath, "utf8"));
+        const address = deployment.token?.address;
+        if (!address) {
+            return null;
+        }
+        const blockExplorer = deployment.chain?.explorer || "https://basescan.org";
+        return {
+            name: deployment.token?.name || "AI Proof of Use",
+            symbol: deployment.token?.symbol || "AIPOU",
+            address,
+            decimals: deployment.token?.decimals || 18,
+            chainId: deployment.chain?.id || 8453,
+            chainName: deployment.chain?.name || "Base Mainnet",
+            rpcUrl: process.env.AIPOU_RPC_URL || "https://mainnet.base.org",
+            blockExplorer,
+            explorerUrl: `${blockExplorer}/token/${address}`,
+            source: "deployment_file"
+        };
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function getTokenContractConfig() {
+    let config;
+    const fromEnv = envConfig();
+    if (fromEnv) {
+        config = fromEnv;
+    }
+    else {
+        const fromFile = await deploymentFileConfig();
+        config = fromFile || {
+            name: "AI Proof of Use",
+            symbol: "AIPOU",
+            address: null,
+            decimals: 18,
+            chainId: 8453,
+            chainName: "Base Mainnet",
+            rpcUrl: "https://mainnet.base.org",
+            blockExplorer: "https://basescan.org",
+            explorerUrl: null,
+            source: "unconfigured"
+        };
+    }
+    const claimsAddress = await configuredClaimsAddress();
+    return {
+        ...config,
+        claimsAddress,
+        claimsExplorerUrl: claimsAddress ? `${config.blockExplorer}/address/${claimsAddress}` : null
+    };
+}

package/dist/identity.d.ts

@@ -0,0 +1,18 @@
+import { Wallet } from "ethers";
+import type { TaskSession } from "./types.js";
+export declare const authorizationTypes: {
+    TaskAuthorization: {
+        name: string;
+        type: string;
+    }[];
+};
+export declare function agentWallet(): Wallet;
+export declare function createTaskSession(input: {
+    provider: string;
+    model: string;
+    taskHash: string;
+    client: string;
+    chainId: number;
+    verifyingContract: string;
+}): Promise<TaskSession>;
+export declare function verifyTaskAuthorization(session: TaskSession): boolean;

package/dist/identity.js

@@ -0,0 +1,59 @@
+import { randomBytes } from "node:crypto";
+import { Wallet, getAddress, hexlify, isAddress, verifyTypedData } from "ethers";
+export const authorizationTypes = {
+    TaskAuthorization: [
+        { name: "wallet", type: "address" },
+        { name: "nonce", type: "bytes32" },
+        { name: "taskHash", type: "bytes32" },
+        { name: "provider", type: "string" },
+        { name: "model", type: "string" },
+        { name: "issuedAt", type: "uint256" }
+    ]
+};
+export function agentWallet() {
+    const privateKey = process.env.AIPOU_AGENT_PRIVATE_KEY;
+    if (!privateKey) {
+        throw new Error("AIPOU_AGENT_PRIVATE_KEY is required; use a dedicated farming wallet, never a primary wallet");
+    }
+    return new Wallet(privateKey);
+}
+export async function createTaskSession(input) {
+    if (!isAddress(input.verifyingContract))
+        throw new Error("AIPOU_CLAIMS_ADDRESS must be a valid contract address");
+    const wallet = agentWallet();
+    const nonce = hexlify(randomBytes(32));
+    const issuedAt = Math.floor(Date.now() / 1000);
+    const domain = {
+        name: "AI Proof of Us",
+        version: "1",
+        chainId: input.chainId,
+        verifyingContract: getAddress(input.verifyingContract)
+    };
+    const value = {
+        wallet: wallet.address,
+        nonce,
+        taskHash: input.taskHash,
+        provider: input.provider,
+        model: input.model,
+        issuedAt
+    };
+    const walletAuthorization = await wallet.signTypedData(domain, authorizationTypes, value);
+    return { ...input, wallet: wallet.address, nonce, issuedAt, walletAuthorization };
+}
+export function verifyTaskAuthorization(session) {
+    const domain = {
+        name: "AI Proof of Us",
+        version: "1",
+        chainId: session.chainId,
+        verifyingContract: session.verifyingContract
+    };
+    const value = {
+        wallet: session.wallet,
+        nonce: session.nonce,
+        taskHash: session.taskHash,
+        provider: session.provider,
+        model: session.model,
+        issuedAt: session.issuedAt
+    };
+    return verifyTypedData(domain, authorizationTypes, value, session.walletAuthorization) === session.wallet;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "dotenv/config";

package/dist/index.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { settleRewards } from "./claims.js";
+import { collectorFingerprint, getCollectorPublicKey } from "./collector.js";
+import { aipouClaimsAbi, aipouTokenAbi, getTokenContractConfig } from "./contract.js";
+import { agentWallet } from "./identity.js";
+import { beginTask, completeTask, exportReceipts } from "./receipts.js";
+import { estimateReward } from "./rewards.js";
+const bytes32 = z.string().regex(/^0x[a-fA-F0-9]{64}$/);
+const usageCounts = {
+    inputTokens: z.number().int().min(0).max(10_000_000),
+    outputTokens: z.number().int().min(0).max(10_000_000),
+    durationSeconds: z.number().int().min(0).max(86_400)
+};
+const server = new McpServer({ name: "aipou-mcp", version: "0.2.0" }, {
+    instructions: "For meaningful AI tasks, call begin_ai_task before work and complete_ai_task after work using hashes, never raw prompts or outputs. " +
+        "Use the dedicated farming identity only. Never reveal private keys or local collector state. " +
+        "Call settle_ai_rewards only after the user explicitly asks to claim or settle their AIPOU; it submits two on-chain transactions. " +
+        "The host client and its user always keep the final say on transaction confirmation policy."
+});
+server.tool("get_aipou_contract", "Return the configured AIPOU token contract address, Base network details, explorer URL, and minimal ABI.", {}, async () => {
+    const contract = await getTokenContractConfig();
+    return {
+        content: [{ type: "text", text: JSON.stringify({ ...contract, tokenAbi: aipouTokenAbi, claimsAbi: aipouClaimsAbi }, null, 2) }]
+    };
+});
+server.tool("get_aipou_identity", "Return the dedicated farming wallet address and public Ed25519 collector key. Private keys are never returned.", {}, async () => {
+    const wallet = agentWallet();
+    const collectorPublicKey = await getCollectorPublicKey();
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({ wallet: wallet.address, collectorPublicKey, collectorFingerprint: collectorFingerprint(collectorPublicKey) }, null, 2)
+            }]
+    };
+});
+server.tool("estimate_ai_reward", "Estimate the client-signed AIPOU reward before a task is completed. The final tier is derived by the validator.", usageCounts, async (input) => ({
+    content: [{
+            type: "text",
+            text: JSON.stringify({ estimatedReward: estimateReward({ ...input, trustTier: "client_signed" }), unit: "AIPOU" }, null, 2)
+        }]
+}));
+server.tool("begin_ai_task", "Create a unique task nonce and EIP-712 authorization signed by the dedicated farming wallet.", {
+    provider: z.string().min(1).max(64),
+    model: z.string().min(1).max(128),
+    taskHash: bytes32,
+    client: z.string().min(1).max(64)
+}, async (input) => {
+    const contract = await getTokenContractConfig();
+    const verifyingContract = process.env.AIPOU_CLAIMS_ADDRESS;
+    if (!verifyingContract)
+        throw new Error("AIPOU_CLAIMS_ADDRESS is required before tasks can begin");
+    const session = await beginTask({
+        ...input,
+        chainId: contract.chainId,
+        verifyingContract
+    });
+    return { content: [{ type: "text", text: JSON.stringify(session, null, 2) }] };
+});
+server.tool("complete_ai_task", "Complete a unique task, derive its trust tier, reject duplicate evidence, and create an Ed25519-signed receipt.", {
+    nonce: bytes32,
+    ...usageCounts,
+    outputHash: bytes32,
+    providerEvidence: z.object({
+        keyId: z.string().min(1).max(128),
+        signature: z.string().min(32)
+    }).optional()
+}, async (input) => {
+    const receipt = await completeTask(input);
+    return { content: [{ type: "text", text: JSON.stringify(receipt, null, 2) }] };
+});
+server.tool("export_ai_receipts", "Export stored signed AI task receipts, optionally filtered by wallet.", { wallet: z.string().regex(/^0x[a-fA-F0-9]{40}$/).optional() }, async ({ wallet }) => {
+    const receipts = await exportReceipts(wallet);
+    return { content: [{ type: "text", text: JSON.stringify({ count: receipts.length, receipts }, null, 2) }] };
+});
+server.tool("settle_ai_rewards", "After an explicit user claim request, validate eligible receipts against the settlement policy, publish a Merkle root, and mint the included rewards. Submits two on-chain transactions; the host's own confirmation policy applies.", { maxReceipts: z.number().int().min(1).max(100).default(25) }, async ({ maxReceipts }) => {
+    const batch = await settleRewards(maxReceipts);
+    return { content: [{ type: "text", text: JSON.stringify(batch, null, 2) }] };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/lock.d.ts

@@ -0,0 +1 @@
+export declare function withFileLock<T>(lockPath: string, operation: () => Promise<T>): Promise<T>;

package/dist/lock.js

@@ -0,0 +1,42 @@
+import { rm, stat, writeFile } from "node:fs/promises";
+// State mutations finish in well under a second, so a lock older than this
+// belongs to a crashed process and can be reclaimed safely.
+const STALE_LOCK_MS = 15_000;
+const ACQUIRE_TIMEOUT_MS = 10_000;
+async function acquire(lockPath) {
+    const deadline = Date.now() + ACQUIRE_TIMEOUT_MS;
+    for (;;) {
+        try {
+            await writeFile(lockPath, `${process.pid}\n`, { encoding: "utf8", flag: "wx" });
+            return;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        try {
+            const info = await stat(lockPath);
+            if (Date.now() - info.mtimeMs > STALE_LOCK_MS) {
+                await rm(lockPath, { force: true });
+                continue;
+            }
+        }
+        catch {
+            // The holder released the lock between attempts; retry immediately.
+            continue;
+        }
+        if (Date.now() > deadline) {
+            throw new Error(`Timed out waiting for lock ${lockPath}; remove it manually if no other AIPOU process is running`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 25 + Math.floor(Math.random() * 75)));
+    }
+}
+export async function withFileLock(lockPath, operation) {
+    await acquire(lockPath);
+    try {
+        return await operation();
+    }
+    finally {
+        await rm(lockPath, { force: true });
+    }
+}