@bolloon/bolloon-agent 0.4.32 → 0.5.0

package/dist/agents/chain/explorer.js

@@ -0,0 +1,52 @@
+/**
+ * explorer.ts — 区块浏览器映射 (chainId → 公网浏览器) + **交易**链接构造
+ *
+ * 只回答一件事: **这条链有没有已知的公网浏览器**。
+ *   · 有 → `https://<explorer>/tx/0x…` (公开可核验的链上事实)
+ *   · 认不出 / 本机隔离开发链 (31337) → **null** —— 没有公网浏览器就**不给链接**,
+ *     绝不编造 `href="#"`、死链或猜一个域名 (宁缺勿错)。
+ *
+ * 隐私红线 (2026-09-23 leo 拍板; 同日收窄):
+ *   · 允许出现在公开快照里的 0x 字符串**只有两种**: 交易哈希 (0x+64 hex) 与 escrow **合约**地址
+ *     (0x+40 hex) —— 它们本来就是公开链上事实。
+ *   · 但**页面只可点交易**: escrow 合约地址保留在行数据里供索引/诊断, **不渲染、不生成合约链接**
+ *     (所以本文件**没有** address 链接构造器 —— 少一个能凭空造出合约链接的入口)。
+ *   · EOA / 钱包地址 (买方·卖方·payTo 之类)、taskKey 原文、taskId、args 里的地址、DID、
+ *     peer IP / multiaddr、私钥 —— **一个都不许**经这里或别处进快照。
+ *   · 本文件只构造 URL, 不读盘不发 RPC, 也从不接受「调用方说它是合约地址」的自我声明。
+ */
+/** chainId → 公网浏览器 base URL (白名单; 认不出的一律没有) */
+export const EXPLORER_BY_CHAIN = Object.freeze({
+    8453: 'https://basescan.org', // Base 主网
+    84532: 'https://sepolia.basescan.org', // Base Sepolia 测试网
+    1: 'https://etherscan.io', // Ethereum 主网
+    11155111: 'https://sepolia.etherscan.io', // Sepolia 测试网
+});
+/** 交易哈希: 小写 0x + 64 位十六进制 (词法唯一形状) */
+export const TX_HASH_RE = /^0x[0-9a-f]{64}$/;
+/** 地址: 小写 0x + 40 位十六进制 (合约地址同样长这样 —— 是**谁**由调用方的白名单决定) */
+export const ADDRESS_RE = /^0x[0-9a-f]{40}$/;
+/**
+ * 浏览器**交易**链接形状 (反向校验用): https + 已知浏览器域名 + `/tx/0x64hex`。
+ * 给守卫 / 单测一把「这不是我们造的链接」的尺子 —— 端口 / 凭据 / 别的路径 (含 `/address/`) 一律不认。
+ */
+export const EXPLORER_URL_RE = /^https:\/\/(?:[a-z0-9-]+\.)*(?:basescan\.org|etherscan\.io)\/tx\/0x[0-9a-f]{64}$/;
+/** chainId 有没有已知公网浏览器 → base URL; 认不出 (含本机 31337) → null */
+export function explorerBaseUrl(chainId) {
+    const id = Number(chainId);
+    if (!Number.isInteger(id) || id < 0)
+        return null;
+    return EXPLORER_BY_CHAIN[id] ?? null;
+}
+/** 交易链接; 链没浏览器 / 哈希非法 → null (调用方**不要**填 null 之外的占位) */
+export function explorerTxUrl(chainId, txHash) {
+    const base = explorerBaseUrl(chainId);
+    const h = String(txHash ?? '').toLowerCase();
+    if (!base || !TX_HASH_RE.test(h))
+        return null;
+    return `${base}/tx/${h}`;
+}
+/** 这个字符串是不是我们亲手造的那种**交易**浏览器链接 (守卫 / 单测用) */
+export function isExplorerUrl(url) {
+    return typeof url === 'string' && EXPLORER_URL_RE.test(url);
+}

package/dist/agents/chain/index.js

@@ -9,6 +9,7 @@
  *   · chain-state-store   — 落盘 / 重启恢复 / 重组对账
  *   · chain-indexer       — P5: v2 事件索引器 (分页扫 / 增量 / 去重 / 重组回退 / 全量重建)
  *   · chain-index-query   — P5: 只读查询 (时间线 / cursor 增量 / 统计 / 索引高度)
+ *   · explorer            — chainId → 公网区块浏览器 (**只造交易链接**: 合约地址不页面化; 认不出的链不给链接)
  */
 export * from './chain-config.js';
 export * from './escrow-client.js';
@@ -18,3 +19,4 @@ export * from './chain-state-store.js';
 export * from './onchain-trade.js';
 export * from './chain-indexer.js';
 export * from './chain-index-query.js';
+export * from './explorer.js';

package/dist/agents/chain/onchain-trade.js

@@ -116,7 +116,7 @@ function emptyStep(stage, partial) {
 async function judge(req, taskKey, txHash, expect, recorded) {
     const gate = req.gate || 'confirmed';
     const verify = req.verifyOnChain || (await defaultVerifyPaymentOnChain());
-    return verify({
+    const run = () => verify({
         txHash,
         chainSettlement: {
             verifier: createChainSettlementVerifier(req.client, { gate }),
@@ -125,6 +125,20 @@ async function judge(req, taskKey, txHash, expect, recorded) {
             recorded,
         },
     });
+    let v = await run();
+    // ★ 未定/读偏的有界重读: 交易已经发出去了 (钱/证明在链上), 一次读偏不该定案 —— 只重读, 不重发。
+    //   两种读偏形态都要覆盖:
+    //     · 'pending'        —— eth_blockNumber 还停在前一个块 → 确认数数成 0
+    //     · 'event_mismatch' —— 事件读到了 (receipt 按 txHash 取, 一定新), 但合约状态 eth_call 读回旧值
+    //   真 mismatch (event/taskKey 真对不上) 重读 3 次后结论不变 → 不会把错的判成对的。
+    const attempts = req.settleRetryAttempts ?? 3;
+    const delayMs = req.settleRetryDelayMs ?? 1500;
+    for (let i = 1; i <= attempts && !v.chainSettled && v.rpcAvailable !== false
+        && (v.status === 'pending' || v.status === 'event_mismatch'); i++) {
+        await new Promise((r) => setTimeout(r, delayMs));
+        v = await run();
+    }
+    return v;
 }
 /** 判定落盘 (P3 chain-state-store) */
 async function persist(req, method, taskKey, txHash, amountAtomic, verdict) {

package/dist/agents/contacts/chain.js

@@ -18,7 +18,9 @@
  *   - 联系人撤销后不允许重试 (revoke 时清等待 + 记 unresolved)
  *   - 同一 requestId 不重复发送 (policy 的 duplicate_request + sent.json)
  */
-import { addEvidence, readGoal, setContinuation, setUnresolved, updateGoal } from '../goal-store.js';
+import { addEvidence, readGoal, setUnresolved } from '../goal-store.js';
+// 2026-09-25 (M0 接线冻结, 规则 ②): Goal 状态变更只有一个漏斗
+import { reduceGoalState } from '../goal-state-reducer.js';
 import { addRunEvidence } from '../run-store.js';
 import { bindExternalWait, clearExternalWait, deliverExternalEvent, expireExternalWaits, newContinuationId } from '../external-events.js';
 import { ContactsStore } from './store.js';
@@ -321,7 +323,14 @@ export class ContactChain {
                 note: `等 ${contact.displayValue} 回复 (通道 ${contact.provider})`,
             };
             await bindExternalWait(opts.goalId, wait);
-            await updateGoal(opts.goalId, { status: 'awaiting_external' });
+            // 规则 ②: 进入"等外部"也是一种 Goal 状态变更 → 走 Goal reducer
+            await reduceGoalState({
+                goalId: opts.goalId,
+                intent: 'external_wait_enter',
+                now: new Date(this.now()).toISOString(),
+                by: 'contacts',
+                externalWait: `等 ${contact.displayValue} 回复 (通道 ${contact.provider})`,
+            });
             const g = await readGoal(opts.goalId);
             await this.ledger({
                 activity: 'contact.authorization_requested', contactId: contact.contactId, goalId: opts.goalId, runId: opts.runId,
@@ -453,9 +462,14 @@ export class ContactChain {
             await clearExternalWait(s.goalId);
             const g = await readGoal(s.goalId);
             await setUnresolved(s.goalId, Array.from(new Set([...(g?.unresolvedItems || []), `联系方式授权 ${grantId} 已撤销, 该联系不可自动重试 (转人工)`])));
-            // 撤等待 + 转人工: 不再自动唤醒, 由人接手 (Supervisor 下一轮看到 needs_human)
-            await setContinuation(s.goalId, { wakeReason: 'needs_human', needsExternal: undefined, autoContinue: false }).catch(() => null);
-            await updateGoal(s.goalId, { status: 'needs_human' }).catch(() => null);
+            // 撤等待 + 转人工: 不再自动唤醒, 由人接手 (规则 ②: 状态经 Goal reducer 写, 单一漏斗)
+            await reduceGoalState({
+                goalId: s.goalId,
+                intent: 'contact_revoked_human',
+                now: new Date().toISOString(),
+                by: 'contacts',
+                revokeNote: `联系方式授权 ${grantId} 已撤销, 该联系不可自动重试`,
+            }).catch(() => null);
             affected.push(s.goalId);
         }
         return { ok: true, affectedGoals: affected };
@@ -555,8 +569,14 @@ export class ContactChain {
             await clearExternalWait(s.goalId);
             const g = await readGoal(s.goalId);
             await setUnresolved(s.goalId, Array.from(new Set([...(g?.unresolvedItems || []), `联系人 ${c.displayValue} 已撤销授权, 该联系不可重试`])));
-            await setContinuation(s.goalId, { wakeReason: 'needs_human', needsExternal: undefined, autoContinue: false }).catch(() => null);
-            await updateGoal(s.goalId, { status: 'needs_human' }).catch(() => null);
+            // 规则 ②: 经 Goal reducer 写 (单一漏斗)
+            await reduceGoalState({
+                goalId: s.goalId,
+                intent: 'contact_revoked_human',
+                now: new Date().toISOString(),
+                by: 'contacts',
+                revokeNote: `联系人 ${c.displayValue} 已撤销授权, 该联系不可重试`,
+            }).catch(() => null);
             affected.push(s.goalId);
         }
         return { ok: true, evidenceRef: ev.evidenceRef, affectedGoals: affected };