@bolloon/bolloon-agent 0.4.31 → 0.4.32

package/dist/agents/chain/chain-wallet.js

@@ -0,0 +1,198 @@
+/**
+ * chain-wallet.ts — 链上交易的**签名放行闸** (P3, ③)
+ *
+ * 硬规则:
+ *   「链上交易签名走 `authorizeWalletSignature` 这个唯一放行闸 (fail-closed)
+ *     + 写 `~/.bolloon/wallet-signatures.jsonl` 审计 (不记私钥、不记任务正文);
+ *     未授权一律拒。」
+ *
+ * 所以这个文件里**没有第二条**"要不要签"的判断: 任何链上写操作都必须先过
+ * `authorizeChainTransaction()`, 它内部只有 `task-contract.authorizeWalletSignature` 一个权威。
+ * 未授权 → 不造 signer、不发交易、不写审计, 直接拒绝并说明哪一条没过。
+ *
+ * 三层授权来源 (与 CLI `bolloon wallet sign` 完全一致, 只是入口不同):
+ *   ① `~/.bolloon/signing-policy.json` 的 `agentAuthorized: true`
+ *   ② 环境变量 `BOLLOON_AGENT_AUTHORIZED=1`
+ *   ③ (钱包本身) `BOLLOON_WALLET_PRIVATE_KEY` / `~/.bolloon/wallet.json`
+ * 程序参数**只能收紧** (更小额度 / 白名单交集), 不能凭空授予。
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { authorizeWalletSignature, recordSignatureAudit, readSignatureAudit, isPaymentMode, } from '../task-contract.js';
+import { fingerprintOf, payloadDigest } from '../local-signer.js';
+import { bolloonHome, walletAvailable, assertNotForeignWalletPath } from './chain-config.js';
+/** 链上签名的能力名 (授权白名单里用这个) */
+export const CHAIN_SIGN_CAPABILITY = 'chain.escrow';
+export function chainSigningPolicyPath(home) {
+    return path.join(bolloonHome(home), 'signing-policy.json');
+}
+/**
+ * 读本机签名授权策略 (语义与 `src/cli/commands/wallet.ts:readSigningPolicy` 一致;
+ * 两处都必须只有这 ①② 两个授予源)。
+ */
+export function readChainSigningPolicy(opts = {}) {
+    const env = opts.env || process.env;
+    const envOn = String(env.BOLLOON_AGENT_AUTHORIZED || '') === '1';
+    const out = {
+        agentAuthorized: envOn,
+        source: envOn ? 'env BOLLOON_AGENT_AUTHORIZED=1' : 'default (未授权)',
+    };
+    const f = chainSigningPolicyPath(opts.home);
+    assertNotForeignWalletPath(f);
+    try {
+        if (fs.existsSync(f)) {
+            const j = JSON.parse(fs.readFileSync(f, 'utf8'));
+            if (j?.agentAuthorized === true) {
+                out.agentAuthorized = true;
+                out.source = `${f} (agentAuthorized=true)`;
+            }
+            if (Array.isArray(j?.allowedNetworks))
+                out.allowedNetworks = j.allowedNetworks.map(String);
+            if (Array.isArray(j?.allowedCapabilities))
+                out.allowedCapabilities = j.allowedCapabilities.map(String);
+            if (typeof j?.maxPerTxAtomic === 'string')
+                out.maxPerTxAtomic = j.maxPerTxAtomic;
+            if (typeof j?.dailyLimitAtomic === 'string')
+                out.dailyLimitAtomic = j.dailyLimitAtomic;
+        }
+    }
+    catch (e) {
+        out.fileError = String(e?.message || e).slice(0, 160);
+    }
+    return out;
+}
+const ATOMIC = /^[0-9]+$/;
+const minAtomic = (a, b) => {
+    const okv = (v) => !!v && ATOMIC.test(v);
+    if (!okv(a))
+        return okv(b) ? b : undefined;
+    if (!okv(b))
+        return a;
+    return BigInt(a) <= BigInt(b) ? a : b;
+};
+/** 意图 → 幂等 requestId (同一 method+taskKey+金额+链 = 同一个请求, 只签一次) */
+export function chainRequestIdOf(intent, chainId) {
+    const basis = [intent.method, intent.taskKey.toLowerCase(), intent.amountAtomic || '0', chainId ?? '?', intent.intentNonce || ''].join('|');
+    return `chaintx-${intent.method}-${crypto.createHash('sha256').update(basis).digest('hex').slice(0, 16)}`;
+}
+/**
+ * ★ 链上签名的唯一放行判断 (fail-closed)。
+ * 任何一条不满足 → `allowed: false` 且给出原因; 调用方**必须**原样停下。
+ */
+export async function authorizeChainTransaction(intent, opts = {}) {
+    const policy = readChainSigningPolicy({ home: opts.home, env: opts.env });
+    const mode = isPaymentMode(intent.mode) ? intent.mode : 'agent-authorized';
+    const amountAtomic = String(intent.amountAtomic ?? '0');
+    const network = String(intent.network || 'unknown');
+    const capability = String(intent.capability || CHAIN_SIGN_CAPABILITY);
+    const readAudit = opts.auditReader || readSignatureAudit;
+    let audit = [];
+    try {
+        audit = await readAudit(opts.home, 1000);
+    }
+    catch {
+        audit = [];
+    }
+    const dayStart = new Date();
+    dayStart.setHours(0, 0, 0, 0);
+    const spentTodayAtomic = audit
+        .filter((a) => a.at >= dayStart.getTime())
+        .reduce((acc, a) => acc + (ATOMIC.test(String(a.amountAtomic || '')) ? BigInt(String(a.amountAtomic)) : 0n), 0n)
+        .toString();
+    const signedRequestIds = audit.map((a) => a.requestId);
+    const w = walletAvailable({ home: opts.home, env: opts.env });
+    const requestId = chainRequestIdOf(intent, opts.chainId);
+    const decision = authorizeWalletSignature({
+        mode,
+        agentAuthorized: policy.agentAuthorized,
+        amountAtomic,
+        network,
+        capability,
+        requestId,
+        signedRequestIds,
+        allowedNetworks: policy.allowedNetworks,
+        allowedCapabilities: policy.allowedCapabilities,
+        maxPerTxAtomic: minAtomic(policy.maxPerTxAtomic, intent.maxPerTxAtomic),
+        dailyLimitAtomic: minAtomic(policy.dailyLimitAtomic, intent.dailyLimitAtomic),
+        spentTodayAtomic,
+        walletAvailable: w.available,
+    });
+    return {
+        allowed: decision.allowed,
+        requestId,
+        reason: decision.reason,
+        checks: decision.checks,
+        policy,
+        walletAvailable: w.available,
+        walletSource: w.source,
+        amountAtomic, network, capability, spentTodayAtomic,
+        privateKeyTouched: false,
+    };
+}
+/** 审计 kind 映射 (schema 只有 4 种, 这里如实映射, 不新增字段) */
+function auditKindOf(method) {
+    if (method === 'submitProofV2')
+        return 'task_result';
+    if (method === 'disputeV2')
+        return 'task_request';
+    return 'task_payment'; // createEscrowV2 / releaseV2 / claimAfterTimeoutV2 都是钱的移动
+}
+/**
+ * ★ 受控发交易: 放行闸 → (只在这里) 取私钥造 signer → 执行 → 写审计。
+ * 放行闸拒绝时: 不取私钥、不发交易、不写审计。
+ *
+ * `execute` 拿到的 signer 是唯一能用私钥的对象, 调用方不许把它带出作用域。
+ */
+export async function sendChainTxGuarded(params) {
+    const auth = await authorizeChainTransaction(params.intent, {
+        home: params.home, env: params.env, chainId: params.client.chainId, auditReader: params.auditReader,
+    });
+    if (!auth.allowed) {
+        return { allowed: false, reason: auth.reason, auth, auditWritten: false };
+    }
+    // ★ 只有走到这里才碰私钥 (局部变量, 不外泄)
+    let signer;
+    try {
+        signer = params.signer
+            || (params.signerFactory ? params.signerFactory(params.client) : params.client.localSigner({ home: params.home }));
+    }
+    catch (e) {
+        return {
+            allowed: false,
+            reason: `放行闸过了但取不到本机钱包: ${String(e?.message || e).slice(0, 200)}`,
+            auth, auditWritten: false,
+        };
+    }
+    const outcome = await params.execute(signer);
+    // 审计: 只记摘要 (意图摘要, 不含私钥 / 不含任务正文)
+    const digest = payloadDigest(JSON.stringify({
+        method: params.intent.method, taskKey: params.intent.taskKey, amountAtomic: auth.amountAtomic,
+    }));
+    const entry = {
+        kind: auditKindOf(params.intent.method),
+        mode: (isPaymentMode(params.intent.mode) ? params.intent.mode : 'agent-authorized'),
+        requestId: auth.requestId,
+        taskId: params.intent.taskId,
+        amountAtomic: auth.amountAtomic,
+        currency: 'USDC',
+        network: auth.network,
+        capability: auth.capability,
+        signerFingerprint: fingerprintOf(String(params.client.escrowAddress)),
+        payloadDigest: digest,
+    };
+    let auditWritten = false;
+    try {
+        const rec = params.recordAudit || recordSignatureAudit;
+        await rec(entry, params.home);
+        auditWritten = true;
+    }
+    catch {
+        auditWritten = false;
+    }
+    return { allowed: true, auth, outcome, auditWritten, auditEntry: entry };
+}
+/** 便捷包装: 让 4 个 v2 写方法都只能从放行闸过 */
+export async function gatedEscrowWrite(client, intent, run, opts = {}) {
+    return sendChainTxGuarded({ client, intent, execute: run, ...opts });
+}

package/dist/agents/chain/escrow-client.js

@@ -0,0 +1,433 @@
+/**
+ * escrow-client.ts — AgentEscrow v2 的链桥客户端 (P3: Bolloon 链桥)
+ *
+ * 职责 (只有这些, 不做判断):
+ *   · 用 ethers v6 调 AgentEscrow v2 的 4 个写方法:
+ *       createEscrowV2 / submitProofV2 / releaseV2 / claimAfterTimeoutV2
+ *   · 读 escrow 结构 (19 字段) 与链上 hash 复算入口
+ *   · 听 5 个 v2 事件
+ *   · 读 receipt / 数确认数 (把"链上到底成没成"的**原始事实**拿出来)
+ *
+ * 它**不判断**"算不算已结算" —— 那是 chain-settlement.ts 的事。
+ * 这样客户端能随便换 provider 做测试, 而判定逻辑只有一份。
+ *
+ * 两个必须照做的本机坑:
+ *   ① `new JsonRpcProvider(url, null, { cacheTimeout: -1 })`:
+ *      ethers v6 默认缓存 eth_getTransactionCount/eth_blockNumber 250ms。
+ *      本地链瞬时出块 → 第二笔交易会拿旧 nonce → "nonce has already been used"。
+ *      构造入口统一走 `createJsonRpcProvider()`, 不散落在调用方。
+ *   ② signer / provider **可注入**: 测试要能用假 provider 造重组 / 掉 RPC,
+ *      而不能真的去连网。
+ */
+import { JsonRpcProvider, Contract, Interface, Wallet, AbiCoder, encodeBytes32String, keccak256, } from 'ethers';
+import { loadChainConfig, readWalletPrivateKey, DEFAULT_CONFIRMATIONS, LOCAL_DEV_CHAIN_ID, } from './chain-config.js';
+// ── 冻结 hash 口径 (与 AgentEscrow.sol / MODEL_FREEZE.md §4 逐字一致) ─────────
+export const TAG_TASK = encodeBytes32String('bolloon.task.v1'); // "bolloon.task.v1" → bytes32
+const ABICODER = AbiCoder.defaultAbiCoder();
+/** taskKey = keccak256(abi.encode(bytes32("bolloon.task.v1"), taskId)) */
+export function computeTaskKeyOffChain(taskId) {
+    return keccak256(ABICODER.encode(['bytes32', 'string'], [TAG_TASK, taskId]));
+}
+/** v1 过渡兼容键 = keccak256(utf8(taskId)) */
+export function computeLegacyTaskKeyOffChain(taskId) {
+    return keccak256(new TextEncoder().encode(taskId));
+}
+/** resultHash/inputHash/manifestHash = keccak256(utf8("sha256:<hex>")) */
+export function computeResultHashOffChain(sha256Digest) {
+    return keccak256(new TextEncoder().encode(String(sha256Digest)));
+}
+/** proofHash = keccak256(abi.encode(bytes32("bolloon.proof.v1"), resultHash, proofVersion)) */
+export function computeProofHashOffChain(resultHash, proofVersion) {
+    return keccak256(ABICODER.encode(['bytes32', 'bytes32', 'uint16'], [encodeBytes32String('bolloon.proof.v1'), resultHash, proofVersion]));
+}
+/** EscrowState 枚举名 (与合约顺序一致) */
+export const ESCROW_STATES = ['ACTIVE', 'RELEASED', 'DISPUTED', 'REFUNDED'];
+// ── ABI (只嵌 v2 面 + 复算入口 + 5 个 v2 事件; 不改合约, 只是本地 ABI 视图) ────
+export const AGENT_ESCROW_V2_ABI = [
+    // ── 写 ──
+    'function createEscrowV2(bytes32 taskKey, address agent, uint256 amount, address paymentAsset, bytes32 termsHash, bytes32 quoteHash, bytes32 inputHash, bytes32 manifestHash, uint64 deadline, uint32 confirmationWindow, uint16 proofVersion) returns (bytes32)',
+    'function submitProofV2(bytes32 taskKey, bytes32 resultHash, bytes32 manifestHash, uint16 proofVersion) returns (bytes32 proofHash)',
+    'function releaseV2(bytes32 taskKey)',
+    'function claimAfterTimeoutV2(bytes32 taskKey)',
+    'function disputeV2(bytes32 taskKey, bytes32 reasonHash)',
+    'function refundV2(bytes32 taskKey, bytes32 reasonHash)',
+    'function releaseAfterArbitrationV2(bytes32 taskKey)',
+    // ── 读 ──
+    'function escrows(bytes32 taskKey) view returns (tuple(address buyer, address agent, uint256 amount, uint8 state, uint256 createdAt, bytes32 proofHash, bytes32 taskKey, bytes32 termsHash, bytes32 quoteHash, bytes32 inputHash, bytes32 resultHash, bytes32 manifestHash, uint256 chainId, uint32 contractVersion, uint64 createdBlock, uint64 deadline, uint32 confirmationWindow, address paymentAsset, uint16 proofVersion))',
+    'function claimableAt(bytes32 taskKey) view returns (uint256)',
+    'function balance() view returns (uint256)',
+    'function token() view returns (address)',
+    'function releaseTimeout() view returns (uint256)',
+    'function CONTRACT_VERSION() view returns (uint32)',
+    // P4 追加的只读视图 (与 contracts/deployments/abis/AgentEscrow.json 逐字一致; 只加读, 不改写面)
+    'function expireGrace() view returns (uint256)',
+    'function DEFAULT_EXPIRE_GRACE() view returns (uint256)',
+    'function expireAt(bytes32 taskKey) view returns (uint256)',
+    'function owner() view returns (address)',
+    'function taskIds(uint256 index) view returns (bytes32)',
+    // ── 链上复算入口 ──
+    'function computeTaskKey(string taskId) pure returns (bytes32)',
+    'function computeLegacyTaskKey(string taskId) pure returns (bytes32)',
+    'function computeResultHash(string sha256Digest) pure returns (bytes32)',
+    'function computeProofHash(bytes32 resultHash, uint16 proofVersion) pure returns (bytes32)',
+    // ── 5 个 v2 事件 ──
+    'event EscrowCreatedV2(bytes32 indexed taskKey, bytes32 indexed quoteHash, address indexed buyer, address agent, address paymentAsset, uint256 amount, uint256 deadline, uint32 confirmationWindow, uint16 proofVersion, uint32 contractVersion)',
+    'event ProofSubmittedV2(bytes32 indexed taskKey, bytes32 resultHash, bytes32 manifestHash, bytes32 proofHash, uint16 proofVersion)',
+    'event ReleasedV2(bytes32 indexed taskKey, address to, uint256 amount, uint8 by)',
+    'event RefundedV2(bytes32 indexed taskKey, address to, uint256 amount, bytes32 reasonHash)',
+    'event DisputedV2(bytes32 indexed taskKey, address by, bytes32 reasonHash)',
+];
+export const V2_EVENT_NAMES = ['EscrowCreatedV2', 'ProofSubmittedV2', 'ReleasedV2', 'RefundedV2', 'DisputedV2'];
+/** ★ 唯一的 provider 构造入口 (cacheTimeout: -1 是本机链的硬要求)
+ *  注: ethers v6 的 TS 签名把 network 标成 `Networkish | undefined`, 但运行时支持 `null`
+ *  (部署脚本 scripts/deploy.js 一直这么用)。这里保留 `null` 的运行时语义并显式转型,
+ *  不改成本地默认值 —— 本地瞬时出块不缓存 nonce 才是要点。 */
+export function createJsonRpcProvider(rpcUrl) {
+    return new JsonRpcProvider(rpcUrl, null, { cacheTimeout: -1 });
+}
+export class EscrowClient {
+    provider;
+    escrowAddress;
+    confirmations;
+    iface;
+    chainId;
+    injectedSigner;
+    constructor(opts = {}) {
+        let cfg = opts.config;
+        if (!cfg && (opts.rpcUrl || opts.escrowAddress)) {
+            // 允许只给部分字段的轻量构造 (测试): 缺的用默认值填, 但地址必须有
+            cfg = {
+                chainId: LOCAL_DEV_CHAIN_ID, networkName: 'unknown', rpcUrl: opts.rpcUrl || '',
+                escrowAddress: opts.escrowAddress || '', tokenAddress: null, tokenDecimals: 6,
+                confirmations: opts.confirmations || DEFAULT_CONFIRMATIONS, sources: {},
+            };
+        }
+        if (!cfg)
+            cfg = loadChainConfig();
+        if (!cfg.escrowAddress)
+            throw new Error('EscrowClient: 缺 escrowAddress (给 config 或 escrowAddress)');
+        this.escrowAddress = cfg.escrowAddress;
+        this.confirmations = opts.confirmations || cfg.confirmations || DEFAULT_CONFIRMATIONS;
+        this.chainId = cfg.chainId || undefined;
+        this.iface = new Interface(AGENT_ESCROW_V2_ABI);
+        this.injectedSigner = opts.signer;
+        if (opts.provider)
+            this.provider = opts.provider;
+        else if (cfg.rpcUrl)
+            this.provider = createJsonRpcProvider(cfg.rpcUrl);
+        else
+            throw new Error('EscrowClient: 既没注入 provider, 也没给 rpcUrl');
+    }
+    /** 只读合约 (事件过滤 / 读结构都走它) */
+    get readContract() {
+        return new Contract(this.escrowAddress, AGENT_ESCROW_V2_ABI, this.provider);
+    }
+    /** 造一个连着 signer 的合约 (写路径) */
+    contractWith(signer) {
+        return new Contract(this.escrowAddress, AGENT_ESCROW_V2_ABI, signer);
+    }
+    /**
+     * 本机钱包 signer。私钥只在这里的局部变量里存在一瞬, 不返回给外部。
+     * 注: 真正的"允不允许签"由 chain-wallet.ts 的放行闸决定 —— 本方法只负责造对象。
+     */
+    localSigner(opts = {}) {
+        if (this.injectedSigner)
+            return this.injectedSigner;
+        const { privateKey } = readWalletPrivateKey({ home: opts.home });
+        return new Wallet(privateKey, this.provider);
+    }
+    // ── 读: escrow 结构 ────────────────────────────────────────────────────────
+    normalizeEscrow(raw) {
+        const state = Number(raw.state);
+        return {
+            buyer: raw.buyer,
+            agent: raw.agent,
+            amount: BigInt(raw.amount),
+            state,
+            stateName: ESCROW_STATES[state] || 'UNKNOWN',
+            createdAt: BigInt(raw.createdAt),
+            proofHash: raw.proofHash,
+            taskKey: raw.taskKey,
+            termsHash: raw.termsHash,
+            quoteHash: raw.quoteHash,
+            inputHash: raw.inputHash,
+            resultHash: raw.resultHash,
+            manifestHash: raw.manifestHash,
+            chainId: BigInt(raw.chainId),
+            contractVersion: Number(raw.contractVersion),
+            createdBlock: Number(raw.createdBlock),
+            deadline: BigInt(raw.deadline),
+            confirmationWindow: Number(raw.confirmationWindow),
+            paymentAsset: raw.paymentAsset,
+            proofVersion: Number(raw.proofVersion),
+        };
+    }
+    /** 读 escrow; 不存在 (buyer == 0) → null (不假装读到了一条空 escrow) */
+    async getEscrow(taskKey) {
+        const raw = await this.readContract.escrows(taskKey);
+        const e = this.normalizeEscrow(raw);
+        if (/^0x0{40}$/i.test(String(e.buyer)))
+            return null;
+        return e;
+    }
+    async balance() {
+        return BigInt(await this.readContract.balance());
+    }
+    async tokenAddress() {
+        return await this.readContract.token();
+    }
+    async contractVersion() {
+        return Number(await this.readContract.CONTRACT_VERSION());
+    }
+    async claimableAt(taskKey) {
+        return BigInt(await this.readContract.claimableAt(taskKey));
+    }
+    /** P4: 托管过期宽限期 (秒) 与单条 taskKey 的过期时间 (只读) */
+    async expireGrace() {
+        return BigInt(await this.readContract.expireGrace());
+    }
+    async defaultExpireGrace() {
+        return BigInt(await this.readContract.DEFAULT_EXPIRE_GRACE());
+    }
+    async expireAt(taskKey) {
+        return BigInt(await this.readContract.expireAt(taskKey));
+    }
+    async owner() {
+        return await this.readContract.owner();
+    }
+    /** 链上任务数组的第 index 个 taskKey (越界会 revert; 调用方自己 try/catch) */
+    async taskIdAt(index) {
+        return await this.readContract.taskIds(index);
+    }
+    async releaseTimeout() {
+        return BigInt(await this.readContract.releaseTimeout());
+    }
+    /** 链上复算入口 (交叉核对口径用; 与本地复算不一致 = 口径漂了) */
+    async computeTaskKey(taskId) { return await this.readContract.computeTaskKey(taskId); }
+    async computeLegacyTaskKey(taskId) { return await this.readContract.computeLegacyTaskKey(taskId); }
+    async computeResultHash(sha256Digest) { return await this.readContract.computeResultHash(sha256Digest); }
+    async computeProofHash(resultHash, proofVersion) {
+        return await this.readContract.computeProofHash(resultHash, proofVersion);
+    }
+    // ── 读: receipt / 确认数 ──────────────────────────────────────────────────
+    /** 读 receipt; 读不到 (未打包 / RPC 报错) → null。异常原样抛出由调用方区分"没有"和"读不到"。 */
+    async getReceipt(txHash) {
+        return await this.provider.getTransactionReceipt(txHash);
+    }
+    async getLatestBlockNumber() {
+        return await this.provider.getBlockNumber();
+    }
+    /**
+     * 确认数 = latestBlock - receipt.blockNumber + 1。
+     * 读不到 receipt 或 latestBlock → 抛错 (调用方必须如实报"不知道")。
+     */
+    async confirmationsOf(txHash) {
+        const rc = await this.getReceipt(txHash);
+        if (!rc)
+            throw new Error(`tx 还没上链 (拿不到 receipt): ${txHash}`);
+        const latestBlock = await this.getLatestBlockNumber();
+        return { confirmations: latestBlock - rc.blockNumber + 1, blockNumber: rc.blockNumber, latestBlock };
+    }
+    /** 交易被哪个块打包 (重组检测用: 同一个 tx 换块 = 提示) */
+    async transactionBlockNumber(txHash) {
+        const tx = await this.provider.getTransaction(txHash);
+        return tx ? Number(tx.blockNumber) : null;
+    }
+    // ── 写 (全部返回 TxOutcome; 失败如实报, 不抛成"成功") ──────────────────────
+    async send(fn, signer) {
+        const c = this.contractWith(signer);
+        let tx = null;
+        try {
+            tx = await fn(c);
+        }
+        catch (e) {
+            // 广播前就失败 (estimateGas / 非白名单) → 没有 txHash, 如实报"没发出去"
+            const hash = e?.transaction?.hash || e?.receipt?.hash || '';
+            if (!hash) {
+                return { txHash: '', blockNumber: null, gasUsed: null, status: null, reverted: false, logs: [], broadcast: false, error: String(e?.shortMessage || e?.reason || e?.message || e).slice(0, 300) };
+            }
+            // 有 hash: 交易确实发出去了
+            const rc = e?.receipt;
+            return {
+                txHash: hash, blockNumber: rc?.blockNumber ?? null, gasUsed: rc ? rc.gasUsed.toString() : null,
+                status: rc ? Number(rc.status) : null, reverted: rc ? Number(rc.status) === 0 : false,
+                logs: rc?.logs ?? [], broadcast: true,
+                error: String(e?.shortMessage || e?.reason || e?.message || e).slice(0, 300),
+            };
+        }
+        const txHash = tx.hash;
+        try {
+            const rc = await tx.wait();
+            if (!rc) {
+                return { txHash, blockNumber: null, gasUsed: null, status: null, reverted: false, logs: [], broadcast: true, error: 'receipt 为空 (还没打包?)' };
+            }
+            return {
+                txHash, blockNumber: rc.blockNumber, gasUsed: rc.gasUsed.toString(),
+                status: Number(rc.status), reverted: Number(rc.status) === 0,
+                logs: rc.logs ?? [], broadcast: true,
+            };
+        }
+        catch (e) {
+            // ethers v6: status 0 时 tx.wait() 会抛, 但 e.receipt 带着真 receipt
+            const rc = e?.receipt;
+            return {
+                txHash, blockNumber: rc?.blockNumber ?? null, gasUsed: rc ? rc.gasUsed.toString() : null,
+                status: rc ? Number(rc.status) : null, reverted: rc ? Number(rc.status) === 0 : false,
+                logs: rc?.logs ?? [], broadcast: true,
+                error: String(e?.shortMessage || e?.reason || e?.message || e).slice(0, 300),
+            };
+        }
+    }
+    async createEscrowV2(p, signer) {
+        return this.send((c) => c.createEscrowV2(p.taskKey, p.agent, p.amount, p.paymentAsset, p.termsHash, p.quoteHash, p.inputHash, p.manifestHash, p.deadline, p.confirmationWindow, p.proofVersion), signer);
+    }
+    async submitProofV2(taskKey, resultHash, manifestHash, proofVersion, signer) {
+        return this.send((c) => c.submitProofV2(taskKey, resultHash, manifestHash, proofVersion), signer);
+    }
+    async releaseV2(taskKey, signer) {
+        return this.send((c) => c.releaseV2(taskKey), signer);
+    }
+    async claimAfterTimeoutV2(taskKey, signer) {
+        return this.send((c) => c.claimAfterTimeoutV2(taskKey), signer);
+    }
+    async disputeV2(taskKey, reasonHash, signer) {
+        return this.send((c) => c.disputeV2(taskKey, reasonHash), signer);
+    }
+    /** 静态调用 (不花 gas 地读 revert reason; F2 门槛类断言用) */
+    async staticCallClaimAfterTimeout(taskKey, from) {
+        try {
+            const data = this.iface.encodeFunctionData('claimAfterTimeoutV2', [taskKey]);
+            await this.provider.call({ to: this.escrowAddress, from, data });
+            return { ok: true };
+        }
+        catch (e) {
+            return { ok: false, reason: e?.reason || e?.shortMessage || String(e?.message || e).slice(0, 200) };
+        }
+    }
+    // ── 5 个 v2 事件监听 ──────────────────────────────────────────────────────
+    /** 只认本合约发出的、topic 匹配的日志 (别的合约发出的一律不算) */
+    escrowLogsOf(outcome) {
+        return (outcome.logs || []).filter((l) => String(l.address).toLowerCase() === this.escrowAddress.toLowerCase());
+    }
+    /** 把一笔 receipt 的日志里属于本合约的、指定 v2 事件的解码出来 */
+    decodeV2Events(outcome, eventName) {
+        const out = [];
+        for (const log of this.escrowLogsOf(outcome)) {
+            let parsed;
+            try {
+                parsed = this.iface.parseLog({ topics: [...log.topics], data: log.data });
+            }
+            catch {
+                continue;
+            }
+            if (!parsed)
+                continue;
+            if (eventName && parsed.name !== eventName)
+                continue;
+            const args = {};
+            parsed.fragment.inputs.forEach((inp, i) => { args[inp.name] = parsed.args[i]; });
+            out.push({ name: parsed.name, args, log });
+        }
+        return out;
+    }
+    /** 用**我们自己的 Interface** 从原始日志解码 (不依赖 ethers 传参形状) */
+    decodeLogArgs(eventName, log) {
+        const frag = this.iface.getEvent(eventName);
+        if (!frag || !log?.topics)
+            return null;
+        try {
+            const decoded = this.iface.decodeEventLog(frag, log.data, [...log.topics]);
+            const args = {};
+            frag.inputs.forEach((inp, i) => { args[inp.name] = decoded[i]; });
+            return args;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 监听某个 v2 事件。可给 taskKey 过滤 (链上 indexed 字段, 在回调里核对)。
+     * 返回取消订阅函数 —— 调用方必须能干净地摘掉监听 (否则重启会叠加)。
+     *
+     * 实现说明 (踩过的坑): 把 `contract.filters.X(...)` 这种 Filter 对象交给
+     * `contract.on()` 时, ethers v6 会把 fragment 解析成 null, 于是回调只收到一个
+     * ContractEventPayload (位置参数全空)。所以这里用**事件名字符串**注册, 自己按
+     * topic0/taskKey 过滤, 并从原始 log 用本地 Interface 解码 —— 参数形状永远一致。
+     */
+    onV2Event(eventName, handler, filter) {
+        const contract = this.readContract;
+        const frag = this.iface.getEvent(eventName);
+        if (!frag)
+            throw new Error(`AgentEscrow ABI 里没有事件 ${eventName}`);
+        const topic0 = String(frag.topicHash).toLowerCase();
+        const wantKey = filter?.taskKey ? String(filter.taskKey).toLowerCase() : null;
+        const selfAddr = this.escrowAddress.toLowerCase();
+        const listener = (...a) => {
+            const payload = a[a.length - 1];
+            const log = payload?.log ?? (payload?.topics ? payload : undefined);
+            // 只认本合约 + 本事件 topic0 (别的合约/别的事件一律不算)
+            if (log?.address && String(log.address).toLowerCase() !== selfAddr)
+                return;
+            if (log?.topics?.[0] && String(log.topics[0]).toLowerCase() !== topic0)
+                return;
+            // taskKey 过滤 (indexed topic1)
+            if (wantKey && log?.topics?.[1] && String(log.topics[1]).toLowerCase() !== wantKey)
+                return;
+            let args = log ? this.decodeLogArgs(eventName, log) : null;
+            if (!args) {
+                args = {};
+                frag.inputs.forEach((inp, i) => { args[inp.name] = a[i]; });
+                if (wantKey && String(args.taskKey || '').toLowerCase() !== wantKey)
+                    return;
+            }
+            try {
+                handler(args, log);
+            }
+            catch { /* 监听回调不许炸主流程 */ }
+        };
+        contract.on(eventName, listener); // ethers v6: 返回 Promise, 订阅失败不抛同步异常
+        const swallow = (r) => { if (r && typeof r.catch === 'function')
+            r.catch(() => { }); };
+        return () => { try {
+            swallow(contract.off(eventName, listener));
+        }
+        catch { /* 已摘 */ } };
+    }
+    onEscrowCreatedV2(h, f) { return this.onV2Event('EscrowCreatedV2', h, f); }
+    onProofSubmittedV2(h, f) { return this.onV2Event('ProofSubmittedV2', h, f); }
+    onReleasedV2(h, f) { return this.onV2Event('ReleasedV2', h, f); }
+    onRefundedV2(h, f) { return this.onV2Event('RefundedV2', h, f); }
+    onDisputedV2(h, f) { return this.onV2Event('DisputedV2', h, f); }
+    /** 等某个 v2 事件出现 (真等链上, 不猜); 超时 → 明确报超时, 不假装收到 */
+    waitForV2Event(eventName, opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? 60_000;
+        return new Promise((resolve) => {
+            let done = false;
+            const off = this.onV2Event(eventName, (args, raw) => {
+                if (done)
+                    return;
+                if (opts.predicate && !opts.predicate(args))
+                    return;
+                done = true;
+                off();
+                clearTimeout(timer);
+                resolve({ args, raw });
+            }, { taskKey: opts.taskKey });
+            const timer = setTimeout(() => { if (done)
+                return; done = true; off(); resolve(null); }, timeoutMs);
+        });
+    }
+    /** 摘掉所有监听 (重启/收尾用) */
+    removeAllListeners() {
+        const swallow = (r) => { if (r && typeof r.catch === 'function')
+            r.catch(() => { }); };
+        try {
+            swallow(this.readContract.removeAllListeners());
+        }
+        catch { /* noop */ }
+        try {
+            swallow(this.provider.removeAllListeners?.());
+        }
+        catch { /* noop */ }
+    }
+}

package/dist/agents/chain/index.js

@@ -0,0 +1,20 @@
+/**
+ * src/agents/chain/index.ts — 链桥模块出口 (P3: Bolloon 链桥 / P5: 链上索引器)
+ *
+ * 七件事的入口:
+ *   · chain-config        — 链配置 / 确认数门槛 / 钱包路径 (env → 本地安全配置 → 报错)
+ *   · escrow-client       — AgentEscrow v2 真链读写 + 5 个 v2 事件监听 (ethers v6)
+ *   · chain-settlement    — 「到底结算了没有」的唯一判定 (修 F5)
+ *   · chain-wallet        — 链上签名的唯一放行闸 + 签名审计
+ *   · chain-state-store   — 落盘 / 重启恢复 / 重组对账
+ *   · chain-indexer       — P5: v2 事件索引器 (分页扫 / 增量 / 去重 / 重组回退 / 全量重建)
+ *   · chain-index-query   — P5: 只读查询 (时间线 / cursor 增量 / 统计 / 索引高度)
+ */
+export * from './chain-config.js';
+export * from './escrow-client.js';
+export * from './chain-settlement.js';
+export * from './chain-wallet.js';
+export * from './chain-state-store.js';
+export * from './onchain-trade.js';
+export * from './chain-indexer.js';
+export * from './chain-index-query.js';