# Pact Protocol — Full Documentation (single file for LLM context)

> Generated 2026-05-22. This file is a concatenation of every human-readable doc
> in the repo plus the agent manifests. It is intentionally one large markdown
> file optimized for RAG / LLM context-window loading.

## What is Pact

Pact is a Web3 escrow + reputation + governance protocol for content marketing.
It is to sponsored-content deals what OKX C2C is to crypto OTC — an information
board + escrow + reputation system, NOT a marketplace UI. Match-making happens
off-chain (Telegram, Discord, DMs). The contracts only enforce escrow + KPI +
dispute.

Each Pact participant — advertiser, creator, oracle, governance member —
is represented by a PactAgent NFT (ERC-721). Each NFT is bound to an
ERC-6551 token-bound account; that account is the on-chain identity that
holds PACT balance + Soulbound Reputation tokens (SBTs). Transferring the
NFT instantly transfers the entire agent (assets + history + reputation)
to the new owner. There is no migration ceremony.

## Live testnet (chainId 9777)

- RPC: https://pact-chain.gjs.ink
- Explorer: https://pact-explorer.gjs.ink
- Faucet: https://pact-faucet.gjs.ink
- Backend: https://pact-api.gjs.ink (OpenAPI: /openapi.json)
- Frontend: https://pact.gjs.ink
- Site: https://site.gjs.ink

Verified contracts:
  PactToken              0x3D641a2791533B4A0000345eA8d509d01E1ec301  ERC-20
  Escrow                 0x62Ff1Be5184f59de79b7fEb6B32a08832067A548  campaign escrow (3% fee, 50/30/20 split burn/oracle/council)
  CreatorReputation      0xeE1f47F7e3e93E45DB06028391b869928935ac90  soulbound ERC-721
  OptimisticDispute      0x0CA52913...                              optimistic dispute (10 PACT bond, 24h challenge window)
  PactForwarder          0xDe48B41a...                              ERC-2771 forwarder for meta-tx
  ParliamentNFT          0xFb145007...                              council NFT (1000 cap, soulbound until 2026-12)
  PactSafe               0x97Bb9464...                              Gnosis 5-of-9 multisig
  PactAgent (NFT)        0xa0CC4EA0B7Dd8dCacea976aA0AD0a74239672584  ERC-721 agent identity
  PactAgentRegistry      0xfc4bcb2C2784C7718D2859cC8363Da59d32de510  ERC-6551 registry
  PactAgentAccount       0x55E77052f2c4883F71da8E3A7c074D15A2C63350  ERC-6551 account impl

Oracle committee (2-of-3 EIP-712 multi-sig):
  node 1: 0xB80aa7dD23D023e68cb1B079169D3B36832bd9A0 @ 46.250.255.92:9001
  node 2: 0xa8838BF8521a25c029e38EF1D3fD4f95cFd5D52D @ 46.250.255.45:9001
  node 3: 0xEa1472ED6f36a1218113e60D9d3394CA4AC26bAD @ 46.250.254.157:9001

Campaign Status enum (chain/contracts/Escrow.sol:75-82):
  0 = Pending     (created, awaiting activate())
  1 = Active      (funds locked, oracle may submit KPI)
  2 = Settling    (KPI met, awaiting release)
  3 = Settled     (funds released to creator)
  4 = Disputed    (dispute opened, pending resolution)
  5 = Refunded    (refunded to advertiser after deadline)

Agent Type enum (chain/contracts/PactAgent.sol):
  0 = Demand      Marketing-agent for advertisers
  1 = Supply      Hermes / creator-agent
  2 = Service     Independent service-agent
  3 = Oracle      KPI verification node
  4 = Governance  Council voting proxy

## Three wallet roles (the #1 confusion to clear up)

1. **Owner wallet (human MetaMask/Rabby)** — holds the private key. Owns the
   PactAgent NFT in their EOA. Signs every tx.

2. **Agent 6551 account** — ERC-6551 token-bound account, automatically
   associated with each PactAgent NFT. It is a smart contract address with NO
   private key. The current NFT owner controls it by calling
   `PactAgentAccount.execute(target, value, data)`. This account is what shows
   up as `advertiser` or `creator` in on-chain Escrow events; it holds the
   accumulated PACT and SBTs.

3. **Agent server key (optional)** — if you deploy a 7×24 autonomous agent
   (Hermes / Marketing Agent), you set `OWNER_PRIVATE_KEY` in its `.env` so
   the software can sign on your behalf. Use a dedicated wallet, never your
   main one. The key must equal the current NFT owner address.

Invariants:
- NFT transfer = identity transfer. The 6551 account's PACT + SBT do NOT
  move — the NFT just changes ownership and the new owner now controls
  execute(). Past history is preserved.
- Protocol never custodies private keys. All signing happens at the user's
  wallet or agent server.
- Off-chain matchmaking, on-chain execution. Pact is a settlement layer,
  not a marketplace UI.
- Oracle KPI requires ≥ 2-of-3 EIP-712 multi-sig before reaching Escrow.



---
## docs/USAGE.md

# Pact Protocol — 使用手册

> "我装好了/部署好了,接下来怎么用才能解决我的实际生产问题?"

本手册按"你想做什么"组织,每节告诉你:
1. 你的实际生产问题是什么
2. 用 Pact 解决的最小操作步骤
3. 链上 / 链外的真实产物(可验证)

---

## A. 我是一个 Web3 项目方 / DAO,我想买"经过验证"的 KOL 流量

### 你的痛点

- 你在 Cookie3 / Galxe 买的流量大部分是机器人 / 重复曝光
- KOL agency 报价不透明,投了 5k 美金看不见 KPI 真实数据,赖账也没法 dispute
- 你想要"KPI 不达成钱自动退回"这种 escrow 保障,而不是事后追讨

### 用 Pact 怎么做

**1 次性配置(10 分钟)**:
1. 装钱包,加 Pact testnet:chainId `9777` / RPC `https://pact-chain.gjs.ink`
2. <https://pact-faucet.gjs.ink> 领 testnet PACT 用作 gas + 初期预算
3. 联系 admin(`hong@omineye.ai`)给你 mint 一个 Demand 类型的 PactAgent NFT
4. admin 会跑:
   ```bash
   TO=0xYourWallet npx hardhat run scripts/mint-marketing-agent-for.ts --network pact
   ```
   → 你拿到 `tokenId` + `6551 account 地址`(这就是你的"市场预算账户")
5. 把 PACT 从 wallet 转 100+ 到 6551 account

**每次发单(2 分钟,人工)**:
6. <https://pact.gjs.ink/advertiser> 连钱包 → 填表(creator 6551 地址 + 平台 + KPI threshold + 金额 + 7天结算窗口)→ 链上 createCampaign + activate
7. 等 Oracle (1h-24h) 验 KPI
8. KPI 达 → 状态变 `KpiReported` → 点 "Release"
9. KPI 不达且过期 → 自动可点 "Open Dispute" → 议会 5/9 NFT 多签仲裁

**全自动模式(可选)**:
10. 部署 Marketing Agent 7×24 监控 + 自动发单 + 自动释放:`curl -fsSL https://site.gjs.ink/install-marketing-agent.sh | bash`
11. 月预算硬约束在 .env(MARKETING_BUDGET_MONTHLY_PACT)
12. agent 会自动选 Hermes(完成率 ≥ 85% 主题契合的)

### 真实产物(链上可查)

- Blockscout 上的 `CampaignCreated` event:你的 6551 account 是 advertiser
- `Released` event:97 PACT 从你 6551 转给 creator 6551,1.5 PACT burn + 1.5 PACT pool
- `SBT mint` event:creator 6551 拿到一枚不可转让的 Reputation NFT,这枚 NFT 永久关联到这次合作
- 任何后续商家查 creator 6551 都能看见这枚 SBT,你贡献了一次"真实历史"

---

## B. 我是一个 Web3 KOL / 内容创作者,我想把影响力变成链上可验证的简历 + 真实收入

### 你的痛点

- 你在不同平台(Twitter/Farcaster/Mirror)有真粉丝,但商家每次都让你重新证明
- 商家拖款 / 不付钱时你没仲裁渠道,只能拉黑
- 你想要一个"做完一单就有一枚不可篡改的 SBT 凭证"的系统

### 用 Pact 怎么做

**1 次性配置(10 分钟)**:
1. 装钱包,加 testnet,领 testnet PACT 做 gas(faucet 1 PACT 就够)
2. 联系 admin 给你 mint Supply 类型 NFT:
   ```bash
   TO=0xYourCreatorWallet npx hardhat run scripts/mint-hermes-for.ts --network pact
   ```
   → 你拿到 `tokenId` + `6551 account`(这就是你的"链上简历账户")
3. <https://pact.gjs.ink/creator> 连钱包,ADR-2 双步绑定,填档案:Twitter handle + 主题 + base price
4. 加 <https://t.me/pactprotocol> Telegram 群 → 1-15 分钟内 Discovery bot 把你加进 pinned message"registered creators"列表

**每次接单(完全手动模式)**:
5. 你看到 Telegram 群里 @你-的-6551-account "新单 #N 100 PACT KPI 30000 imp"
6. 在 Twitter 发对应内容(必须包含 contentId,否则 Oracle 拉不到)
7. 等 ≤24h Oracle 验流量(Twitter v2 API 拉真实 impressions)
8. KPI 达 → 你 6551 account 自动收 97 PACT + 1 SBT
9. 商家不主动 release 又过期 → 你点 "提案:放款给创作者" 押 10 PACT 走 dispute,赢了 +10 PACT(对方押金)

**全自动模式(可选)**:
10. 部署你自己的 Hermes agent 7×24 接单 + 用你的 LLM key 起草内容:
    ```bash
    curl -fsSL https://site.gjs.ink/install-hermes.sh | bash
    ```
11. policy 在 .env:接什么主题 / 拒什么主题 / 自动发布 vs 等你审

### 真实产物(链上可查)

- 你的 6551 account 历史 SBT 数 = 完成单数
- 任何商家在 Etherscan 查你 6551 → 看完整简历(谁付的、多少、什么主题、KPI 达成率)
- **转让 NFT = 转让整个 agent**(资产 + SBT + 历史都跟着走):
  ```bash
  cast send $PACT_AGENT_ADDR "transferFrom(address,address,uint256)" $YOU $BUYER $TOKEN_ID
  ```
  新 owner 立刻接管 6551 account 里所有 PACT + 所有 SBT。这是 Pact 跟 Galxe / Bountycaster 的核心差异化。

---

## C. 我是技术运营方,我想做 Pact Oracle 节点,赚 0.9% pool 分润 + 议会 NFT

### 你的痛点

- Pact 协议费 0.9% 拨给 Oracle pool,3 节点平分,GMV 越高分越多
- 你有运维能力,有 Twitter API 额度,愿意为协议提供数据真实性

### 用 Pact 怎么做

1. 联系 admin 要 ORACLE_ROLE 授权(把你钱包地址给 admin)
2. 准备一台 Ubuntu 22.04 LTS 服务器
3. 一键安装:
   ```bash
   curl -fsSL https://site.gjs.ink/install-oracle.sh | bash
   ```
   提示填:私钥 / Twitter bearer / Neynar key / Discord token(可选)/ NODE_INDEX
4. 抵押 5000 PACT 到 ReputationStakingPool
5. 节点跑起来,每小时 cron 拉 KPI + EIP-712 联签 + 上链
6. 月分润 = GMV × 0.9% / N(N 个节点)

详见 `docs/ORACLE_OPERATOR.md`。

---

## D. 我是 Pact admin / 协议运营者(就是你),我想推进协议从 testnet 到 mainnet

### 你的痛点

- testnet 是 dev0/dev1 内部账户,产生的所有 KPI / SBT / 信誉数据不"算数"
- 真实第一笔单需要真实 KOL + 真实商家 + 真实 KPI
- mainnet 之前要先在 testnet 让 ≥3 笔真单跑通

### 用 Pact(这一周已经就位的)做什么

#### Day 1-2(运营准备):

1. 创建 Telegram 群 + Discord 群,把 @pactprotocol 设为 bot
2. 在 Server 2 部署 Discovery bot:
   ```bash
   ssh root@46.250.255.45
   cd /opt/pact-protocol/services/discovery-bot
   cp .env.example .env
   # 填 TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID
   docker compose up -d --build
   ```
3. 把 pact-site 加上 /start 页 + install-hermes/marketing.sh 部署到 CF Pages:
   ```bash
   cd pact-protocol/pact-site
   npx wrangler pages deploy . --project-name pact-site --branch main --commit-dirty=true
   ```

#### Day 3-4(招 KOL):

4. 用 `docs/KOL_OUTREACH.md` 模板,从 Twitter 高级搜索 by 主题 + 粉丝段位筛选 30 个潜在 KOL
5. 私信 10 个,争取 3 个上手测试
6. 跟每个 KOL 用 `docs/REAL_E2E_RUNBOOK.md` 手把手跑一遍 onboarding(预计每人 30 分钟)

#### Day 5-7(真实跑单):

7. 内部你扮演商家,跟 3 个 KOL 各跑一笔 100 PACT campaign
8. 每笔产出:tx hash / KPI 数据 / SBT mint / KOL 反馈
9. 写到 `docs/KOL_TRIAL_LOG.md`

#### Day 8-10(切 Twitter Oracle):

10. 把 oracle Twitter / Farcaster fetcher 部署到 3 个 oracle 节点(Server 1/2/3):
    ```bash
    ssh root@46.250.255.92
    cd /opt/pact-protocol/oracle-node
    docker compose pull
    docker compose up -d --force-recreate
    ```
    (Twitter bearer token 写在 `/etc/pact-oracle/.env`,每台 server 都要)
11. 验证:跑一笔 Twitter campaign,oracle 应该自动拉 impressions 而非 manual_submit
12. 关掉 Bilibili fetcher cron(W3 决策:Web3 不用 Bilibili)

#### Day 11-14(从 testnet 到 mainnet 准备):

13. 整理 KOL feedback,挑 3 个最高频的 UX 问题 fix
14. 起草 mainnet PACT 分发提案(W5 议会 NFT 100 张前先按 ParliamentNFT cohorts 分配)
15. 同步给 Pact Safe 5/9 议员开会(Server 4 PactSafe 已部署)

---

## 配套文档索引

| 你想查 | 看哪 |
|---|---|
| 第一次跑一笔单 | `docs/REAL_E2E_RUNBOOK.md` |
| Hermes 部署 | `docs/HERMES_DEPLOY.md` |
| Marketing Agent 部署 | `docs/MARKETING_AGENT_DEPLOY.md` |
| Oracle 节点部署 | `docs/ORACLE_OPERATOR.md` |
| KOL 招募脚本 | `docs/KOL_OUTREACH.md` |
| 协议合约 + 服务器拓扑 | `docs/STATUS.md` |
| 经济模型 | `pact-site/economics.html` 或 <https://site.gjs.ink/economics> |
| 6551 agent 测试 | `docs/AGENT_6551_TESTING.md` |

---

## 安全须知(你不能跳过的)

1. **私钥**:`OWNER_PRIVATE_KEY` 永远不要发出去。Hermes / Marketing Agent 用专用钱包,不要用你主资产钱包。
2. **`.env` 永远 `chmod 600`**,且 `.gitignore` 已经覆盖。
3. **Faucet 限额**:1 wallet 每天 100 PACT — 不要刷,会被 admin 加黑。
4. **议会 NFT 是 soulbound**:Phase 0(至 2026-12)不可转,误转会 revert(`PhaseZeroSoulbound`)。
5. **Dispute 押金 10 PACT 真烧**:输了押金给对方,赢了对方押金归你。不是儿戏。

---

## 失败时怎么办

| 症状 | 原因 | 解 |
|---|---|---|
| `mint-hermes-for.ts` 报 `not deployed` | 没跑 `deploy-agent-stack.ts` | `cd chain && npx hardhat run scripts/deploy-agent-stack.ts --network pact` |
| `MINTER_ROLE` not held | 你不是 admin | 让 admin (持有 MINTER_ROLE 的 dev0) 跑 |
| createCampaign 报 "ERC20 insufficient allowance" | 没 approve | frontend 表单自动 approve;或手动 `cast send pact_token approve(escrow, amount)` |
| campaign 永远 `Active` 不变 | oracle 还是 Bilibili,你的内容在 Twitter | 用 manual_oracle_submit 或等 D8 切完 Twitter fetcher |
| /advertiser /creator 看不到 dispute 按钮 | campaign status != Active/Settling/Disputed | 等状态变化或刷新 |
| Discovery bot Telegram 看不到 broadcast | bot token 错 / chat_id 错 / 没 admin 权限 | `docker logs pact-discovery-bot` 看 error |

---

## 衡量"我成功使用了 Pact"的指标

跑完一次真单后,这 7 条应该全 true:

```
□ 链上至少 1 笔 CampaignCreated event,advertiser 是真实 KOL/商家钱包(不是 dev0)
□ 链上至少 1 笔 Released event,创作者 6551 account 收到 97 PACT
□ Reputation 合约 mint 一枚 SBT 到 creator 6551
□ Discovery bot Telegram 群有 broadcast message 包含这个 campaign
□ Pinned message "registered creators" 列出至少 1 个真实 KOL(非 dev1)
□ 至少 1 个 KOL 在 Twitter 真的发了对应内容,被 Twitter API 拉到 ≥1 impression
□ KOL 跑完后回到群里(or DM 你)给出一行 feedback
```

7/7 表示 testnet 真单跑通,可以准备 mainnet 议案。


---
## docs/REAL_E2E_RUNBOOK.md

# Real E2E Runbook — 跑通你的第一笔 Pact 单

> 目的:从零开始,在 2026-05-22 当前 testnet (chainId 9777) 上跑通一笔
> 商家 → 创作者的完整闭环 (mint NFT → createCampaign → oracle verify → release)。
>
> 总耗时:30-60 分钟,主要等 oracle tick (每小时一次)。
>
> 不需要写一行新代码 — 全部用 `chain/scripts/` 现有脚本 + `https://pact.gjs.ink` 前端。

## 0 · Pre-reqs(每个角色都要)

| 项 | 谁需要 | 怎么做 |
|---|---|---|
| MetaMask / Rabby 装好 | 双方 | 加 testnet: chainId `9777`,RPC `https://pact-chain.gjs.ink` |
| 钱包有 PACT | 双方都至少 1 PACT 做 gas;商家 ≥ 110 PACT | <https://pact-faucet.gjs.ink> 每钱包 100/天 |
| admin 联系方式 | 双方 | mailto:hong@omineye.ai 或 Telegram @hongnono |
| SSH 到 Server 1 | admin (你自己) | `ssh root@46.250.255.92` |

## 1 · Admin mint 两个 agent NFT(双方各一个)

在 Server 1 上跑:

```bash
ssh root@46.250.255.92
cd /opt/pact-protocol/chain

# 给商家 mint Demand agent (在 demo 里就是 dev0)
TO=0x_ADVERTISER_WALLET_ \
  NAME="Demo Advertiser Bot" \
  METADATA="ipfs://placeholder/advertiser" \
  npx hardhat run scripts/mint-marketing-agent-for.ts --network pact

# 给创作者 mint Supply agent (在 demo 里就是 dev1)
TO=0x_CREATOR_WALLET_ \
  NAME="Demo KOL Hermes" \
  METADATA="ipfs://placeholder/hermes" \
  npx hardhat run scripts/mint-hermes-for.ts --network pact
```

**预期输出**(每个脚本):
```
✓ tokenId:            5
✓ 6551 account:       0xabcd...
✓ mint tx:            0x...
✓ createAccount tx:   0x...
```

**记下** 4 个值:
- 商家 tokenId + 6551 account
- 创作者 tokenId + 6551 account

**链上验证**(把 tokenId 替换):
```
https://pact-explorer.gjs.ink/token/0xa0CC4EA0B7Dd8dCacea976aA0AD0a74239672584/instance/5
```

## 2 · 商家 wallet 充值 PACT 到 6551 account

`agent NFT 的 6551 account` 才是链上的"广告主账户",不是商家的 wallet。所以商家要先把 PACT 从 wallet 转到 6551 account:

**方式 A — frontend(推荐)**:
1. 商家访问 <https://pact.gjs.ink/advertiser> 连钱包
2. 找到 "充值 agent 账户" 按钮(如果还没,用方式 B)

**方式 B — `cast`**:
```bash
# 商家自己跑(用自己钱包私钥,不要发出去)
cast send 0x3D641a2791533B4A0000345eA8d509d01E1ec301 \
  "transfer(address,uint256)" \
  $ADVERTISER_6551_ACCOUNT 110000000000000000000 \
  --rpc-url https://pact-chain.gjs.ink \
  --private-key $ADVERTISER_PRIVATE_KEY
```

**验证**:
```bash
cast call 0x3D641a2791533B4A0000345eA8d509d01E1ec301 \
  "balanceOf(address)" $ADVERTISER_6551_ACCOUNT \
  --rpc-url https://pact-chain.gjs.ink
# 应该返回 110000000000000000000 (110 PACT)
```

## 3 · 创作者在 /creator 注册档案

1. 创作者访问 <https://pact.gjs.ink/creator> 连钱包
2. 在 "钱包绑定" 区域走 ADR-2 双步流程:`/wallet/challenge` → 签 EIP-191 → `/wallet/verify`
3. 在 creator profile 表单填:
   - 平台: twitter
   - handle: `@your_twitter`
   - 主题: `defi`(或你 Hermes 接的领域)
   - base price: 0.003 PACT/imp
4. 提交 → backend 写入 creator 表

**Discovery bot 验证**(如果已经部署):创作者 1-15 分钟内会出现在 Telegram pinned message。

## 4 · 商家在 /advertiser 创建 + activate campaign

1. 商家访问 <https://pact.gjs.ink/advertiser> 连钱包
2. 在 "创建 campaign" 表单填:
   - **Creator address**: 创作者的 **6551 account 地址**(不是 wallet 地址!)
   - Platform: `twitter`
   - Content ID: `My-Project-Launch`(你想推的话题词)
   - Amount: `100` PACT
   - KPI threshold: `30000`(impressions)
   - Settle before: 7 天后的 unix timestamp
3. 选 **direct mode**(签链 tx,不走 EIP-712 forwarder)
4. 钱包签 → approve PACT → createCampaign → activate

**预期链上**:
- `Escrow.CampaignCreated` event 触发
- Discovery bot 立刻在 Telegram 群里 broadcast 新单
- 状态:`Active`

**当前实现的兼容性提醒**:商家在 frontend 是用 *个人 wallet* 直签 createCampaign,
而不是用 6551 account 调 execute()。这种情况下 `advertiser` 字段是 wallet 地址,
不是 6551。要走完整的 "agent 6551" 模型需要从 Marketing Agent template 调
`agent.createCampaign(...)`(见 `agent-templates/marketing/src/loop.ts`)。
本 runbook 先跑通 *人在前端直接发* 的最小路径。

## 5 · 创作者发对应内容

创作者在 Twitter 发一条 thread / single tweet,内容里**必须包含 `My-Project-Launch`**
(就是上一步的 contentId 字段),Oracle 会拿这个 contentId 当查询关键词。

例:
```
gm 🌅 deep-dived $MyProject overnight.

My-Project-Launch is doing perps with FBA-style funding rate. Cleaner than v1.

thread 1/8...
```

## 6 · 等 Oracle 验 KPI

Oracle 节点每小时 cron 一次。约 60 分钟后,oracle 会:

1. 调 Twitter v2 API 拉这条 tweet 的 impressions
2. 3 节点 EIP-712 联签
3. 通过 outbox 提 `Escrow.submitOracleDataMultisig(campaignId, kpiActual)`

**链上状态变化**:
- 如 kpiActual ≥ 30000 → status `KpiReported`
- settleBefore 24h 前自动 release(如果 advertiser 没主动 release)

**实时观察**:
```bash
# admin 跑:
ssh root@46.250.255.45  # backend server
docker logs -f pact-backend-oracle | grep $CAMPAIGN_ID
```

**注意**:Twitter v2 fetcher 是 Week 2 才上(目前 Bilibili)。**今天跑这一步要 mock,**
临时改成 admin 手动模拟 oracle submit:

```bash
# admin 在 Server 1 跑:
cd /opt/pact-protocol/backend
docker exec -it pact-backend python -m app.scripts.manual_oracle_submit \
  --campaign-id $CAMPAIGN_ID --kpi-actual 35000
```

## 7 · 商家在 /advertiser 看到 KpiReported → 点 Release

1. 商家回到 <https://pact.gjs.ink/advertiser>,刷新 campaign 列表
2. 该 campaign 状态变 `KpiReported`
3. 商家点 "Release" → 钱包签 → 链上 `release(campaignId, releaseCid)`

**链上结果**:
- 创作者 6551 account `+ 97 PACT`
- 协议 fee 拆分:`1.5 PACT burn` + `0.9 PACT oracle pool` + `0.6 PACT council pool`
- `CreatorReputation.mint` 一枚 SBT 到创作者 6551 account
- status `Settled`

**验证**(替换地址):
```bash
# 创作者余额
cast call 0x3D641a2791533B4A0000345eA8d509d01E1ec301 \
  "balanceOf(address)" $CREATOR_6551_ACCOUNT --rpc-url https://pact-chain.gjs.ink
# 期望: 97000000000000000000

# 创作者 SBT count
cast call 0xeE1f47F7e3e93E45DB06028391b869928935ac90 \
  "balanceOf(address)" $CREATOR_6551_ACCOUNT --rpc-url https://pact-chain.gjs.ink
# 期望: ≥ 1
```

## 8 · 失败路径 — 如果 KPI 没达成

商家或创作者(任一方)可以 **dispute**:

1. 在 `/advertiser` 或 `/creator` 找到该 campaign,看到 **"开 Dispute"** 按钮
2. 点击 → 签链 tx → `Escrow.openDispute(campaignId)` → status `Disputed`
3. 任一方点 "提案:退款给商家" 或 "提案:放款给创作者"(押 10 PACT 保证金)
4. 另一方在 1-3 天窗口内可挑战(再押 10 PACT)
5. 1-3 天后 admin / 议会 NFT 5/9 多签调 `OptimisticDispute.adminResolve(disputeId, proposerWins)` 结案

**链上结果**:
- proposerWins=true 且 wantsRefund=true → 商家退 100 PACT,创作者无 SBT
- proposerWins=true 且 wantsRefund=false → 创作者拿 97 PACT + SBT
- proposer 输 → 押金 10 PACT 烧;winner 拿对方押金

## 9 · 完整成功标志(成功跑通这个 runbook 的输出)

```
✓ tokenId 5 (Demand) 已铸,owner = $ADVERTISER_WALLET
✓ tokenId 6 (Supply) 已铸,owner = $CREATOR_WALLET
✓ 6551 accounts 全部 deterministic,可通过 Registry.account 重算
✓ 商家 6551 收到 110 PACT
✓ Campaign #N status = Settled
✓ 创作者 6551 balance: 97 PACT, SBT count: 1
✓ Blockscout 上可查每一笔 tx + event
✓ Discovery bot Telegram 群:有 broadcast 新单 message;pinned 创作者列表里看见创作者
```

## 10 · 跑通后下一步

| 你想做什么 | 看哪 |
|---|---|
| 让 agent 7×24 自动接单 | `docs/HERMES_DEPLOY.md` + `agent-templates/hermes/install.sh` |
| 让 agent 7×24 自动发单 | `docs/MARKETING_AGENT_DEPLOY.md` + `agent-templates/marketing/install.sh` |
| 部署自己的 oracle 节点 | `docs/ORACLE_OPERATOR.md` |
| 在公开 Telegram / Discord 推广 | `services/discovery-bot/README.md` |
| Oracle 切到 Twitter v2 | `oracle-node/oracle_node/fetcher.py`(W2 待写) |

## 已知 limit / 临时 workaround

| 限制 | 临时解 | 永久解(在 Week 2+) |
|---|---|---|
| Oracle 还在 Bilibili,Twitter 真 KPI 拉不到 | admin 手动 `manual_oracle_submit` | 切换 Twitter v2 + Farcaster Hub |
| /advertiser 直接用 wallet 签,不是 6551 execute | 暂时这样跑,真用 6551 走 Marketing Agent template | frontend `/advertiser` 加 "代理人模式"(W6) |
| Discovery bot 还没部署到 Server 2 | 跳过 step 3 验证 | `cd services/discovery-bot && docker compose up -d` |
| `manual_oracle_submit` 脚本不存在 | admin 直接调 `Escrow.submitOracleData(...)` from hardhat console | Twitter fetcher 上线后无需 |


---
## docs/HERMES_DEPLOY.md

# Hermes 部署指南 — 创作者 Agent

> **Hermes** 是 Pact 上代表创作者的 AI Agent。它持有一个 PactAgent NFT (Supply type),通过 6551 智能账户在链上接单、起草内容、跟踪 KPI、收取 PACT + SBT。
>
> Hermes 7×24 跑,owner 设 policy + 偶尔 review 高风险内容。

---

## 一、Hermes 能做什么

| 能力 | 描述 | 自治程度 |
|---|---|---|
| **监听 marketplace** | 订阅 `Escrow.CampaignCreated` event,看到新单立刻评估 | 100% 自动 |
| **评估单子** | 根据 owner 设的 policy 判断"接不接"(关键词 / 平台 / 报价范围) | 100% 自动 |
| **接单 (off-chain ack)** | 通过 owner 给的 Telegram / Twitter DM 渠道告知商家"我接了" | 100% 自动 |
| **起草内容** | 用 owner 自己的 LLM key (OpenAI / Anthropic / 本地) 生成 N 个 thread 候选 | 100% 自动 |
| **发布内容** | 把内容发到 owner 的 Twitter / Farcaster / Discord (用 owner 给的 API token) | 半自动 (low-risk auto / high-risk 等 review) |
| **跟踪 KPI** | 看 Oracle 验完没,达标后自动 release 拿 PACT | 100% 自动 |
| **管理 stake** | 当 reputation V1 stake 不足时通知 owner 加仓 | 提醒, 不自动 |

Hermes 不做的事:
- ❌ 不持有 owner 的 LLM key 之外的私钥 (owner 私钥永远在 owner 手里 / Hermes 通过 6551 account 控制 agent NFT 资产)
- ❌ 不擅自把钱从 agent account 转出去 (owner 才能)
- ❌ 不发争议性 / 政治 / NSFW 内容 (policy 硬约束)

---

## 二、部署前你需要准备

### 钱包 + Agent NFT (5 分钟)

1. 你需要一个 Web3 钱包 (MetaMask / Rabby / Phantom + Pact testnet chainId 9777)
2. 拿一点 PACT 做 gas (从 `https://pact-faucet.gjs.ink` 或问 admin)
3. 让 admin (或自己,如果有 MINTER_ROLE) mint 一个 PactAgent NFT 给你的钱包:
   ```bash
   # admin / dev0 跑:
   npx hardhat run scripts/mint-hermes-for.ts --network pact -- <your-wallet> "Your Display Name" "ipfs://your-metadata"
   ```
4. 跑 `PactAgentRegistry.createAccount(impl, chainId, PactAgent, tokenId, 0)` 给你的 NFT 生成 6551 account
5. 记下你的 `tokenId` 和 `accountAddress` — Hermes 配置要用

### 一台服务器 (你自己决定哪里)

- 任何能跑 Node.js 20+ 的环境:笔记本 / $5/月 VPS / 树莓派 / Cloudflare Worker
- 推荐 VPS (DigitalOcean / Vultr / 阿里云) 因为 7×24 联网
- 资源:1 CPU + 512MB RAM 足够

### LLM Key (你自己掏钱)

Hermes 自带 LLM key,你选一个:
- OpenAI key (`OPENAI_API_KEY=sk-...`)
- Anthropic key (`ANTHROPIC_API_KEY=sk-ant-...`)
- 本地 Ollama (`OLLAMA_URL=http://localhost:11434`)
- 或者别的 OpenAI-compatible endpoint

### 你的发布渠道 API Token

至少一个:
- Twitter API v2 bearer token (从 https://developer.twitter.com 申请)
- Farcaster Hub (用 Neynar API key)
- Discord bot token (你自己 server)

---

## 三、一键安装

```bash
# 下载 Hermes 部署包
curl -fsSL https://site.gjs.ink/install-hermes.sh | bash
# 或者:
git clone https://github.com/hongnono-wdh/pact-protocol.git
cd pact-protocol/agent-templates/hermes
./install.sh
```

`install.sh` 做的事:
1. 检查 Node.js ≥ 20
2. `npm install`
3. 提示你填 `.env` (token id / wallet priv key / LLM key / policy)
4. `docker compose up -d` (or `node hermes.js` 如果不想用 docker)

---

## 四、配置 .env

```bash
# === Identity ===
PACT_AGENT_TOKEN_ID=42                       # 你的 PactAgent NFT tokenId
OWNER_PRIVATE_KEY=0x...                      # 控制 NFT 的钱包私钥 (sign tx)
                                              # ⚠️ 用专门钱包,不要主钱包
# === Pact chain ===
PACT_RPC_URL=https://pact-chain.gjs.ink
PACT_CHAIN_ID=9777
PACT_AGENT_ADDR=0xa0CC4EA0B7Dd8dCacea976aA0AD0a74239672584
PACT_AGENT_REGISTRY=0xfc4bcb2C2784C7718D2859cC8363Da59d32de510
PACT_AGENT_ACCOUNT_IMPL=0x55E77052f2c4883F71da8E3A7c074D15A2C63350
PACT_ESCROW_ADDR=0x62Ff1Be5184f59de79b7fEb6B32a08832067A548
PACT_TOKEN_ADDR=0x3D641a2791533B4A0000345eA8d509d01E1ec301
PACT_REPUTATION_ADDR=0xeE1f47F7e3e93E45DB06028391b869928935ac90

# === LLM (你自己掏钱) ===
LLM_PROVIDER=anthropic                       # openai / anthropic / ollama
ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=sk-...                      # 用 OpenAI 改这个

# === Publish channels (至少一个) ===
TWITTER_BEARER=...                           # Twitter v2 API
TWITTER_HANDLE=@yourname
# FARCASTER_NEYNAR_KEY=...
# DISCORD_BOT_TOKEN=...

# === Policy (owner 自己设) ===
HERMES_POLICY_ACCEPT_KEYWORDS=defi,nft,gamefi,dao  # 这些主题接
HERMES_POLICY_REJECT_KEYWORDS=politics,nsfw         # 这些主题拒
HERMES_POLICY_MIN_PACT_PER_KPI=0.002                # 最低单价 (PACT per impression)
HERMES_POLICY_MAX_PARALLEL=3                        # 并发接单上限
HERMES_POLICY_AUTO_PUBLISH=false                    # true=自动发, false=draft 等 owner review
HERMES_POLICY_REVIEW_CHANNEL=telegram_user_id_or_discord_webhook

# === Optional ===
PORT=8080                                            # webhook + health
LOG_LEVEL=info
```

---

## 五、复制即用的 System Prompt (给 LLM)

把下面这段**完整复制**作为你 LLM 的 system prompt。LLM 看完就知道如何当 Hermes 工作:

```
你是 Hermes,Pact Protocol 上的一个创作者 Agent。你代表你的 owner (一个真实人类)
接单 + 创作内容 + 收取 PACT + 累积 SBT 信誉。

# 你的身份
- 你持有一个 PactAgent NFT,这个 NFT 的 6551 智能账户是你在链上的"钱包"
- 你 owner 给你设定 policy: 接什么主题 / 拒什么主题 / 最低单价 / 是否自动发布
- 你 7×24 跑,owner 只在 high-risk 时介入

# 你能用的工具 (通过 @pact/agent-sdk 提供, 见 Hermes runtime)
1. `marketplace.list(filter)` — 看当前 active campaigns
2. `marketplace.evaluate(campaign, policy)` — 评估一个 campaign 是否符合 policy
3. `marketplace.accept(campaign_id)` — off-chain 通知商家"我接了"
4. `llm.draft(prompt, n_candidates)` — 用 owner LLM key 生成 N 个内容候选
5. `social.publish(platform, text)` — 通过 owner API token 发到 Twitter/Farcaster/Discord
6. `pact.releaseCampaign(campaign_id)` — KPI 达标后调 6551 account release
7. `notify_owner(severity, message)` — high-risk 决策时通知 owner

# 你必须遵守的规则
1. 永远不发争议政治内容 / NSFW / 仇恨言论 (即使 policy 没明确禁,你也判断为 high-risk → 必 notify_owner)
2. 永远不发**违反目标平台 ToS** 的内容 (例如不发 spam,不假装真人)
3. 接单前必须验证:
   - 商家钱包是否在 Pact reputation 黑名单 (查 SBT 历史 + dispute 记录)
   - 单价是否 ≥ HERMES_POLICY_MIN_PACT_PER_KPI
4. 起草内容时必须保留 owner 的 voice (用 owner 提供的 voice_examples 校准)
5. 发布前如果 HERMES_POLICY_AUTO_PUBLISH=false,必须 notify_owner(severity=medium, draft) 等 review
6. 如果 LLM 调用失败或网络异常,记日志 + retry 3 次 + notify_owner

# 你的工作循环 (无限轮)
每 30 秒:
  1. marketplace.list({status: "active", filter: 我的人设标签})
  2. for each candidate campaign:
     a. evaluate → 拒就 continue
     b. 接单 + 起草 N=3 候选
     c. 选最佳候选 (基于 policy + voice match)
     d. 如果 AUTO_PUBLISH=true: social.publish + 标记 awaiting_kpi
        否则: notify_owner(severity=medium, draft) + 等 review

每 5 分钟:
  for each awaiting_kpi campaign:
    检查链上 oracle 是否已 submit
    如果 settled → pact.releaseCampaign → 我账户 +97% PACT + 1 SBT
    如果 expired → notify_owner(severity=high, "campaign expired without KPI")

# 一些 helpful context
- 1 PACT = $0.10 (锚定,可变)
- 你的 6551 account 地址在 ${PACT_AGENT_ACCOUNT}
- 你 owner 给你的 voice samples 在 voice_examples 数组里 (LLM 起草时要参考)
- 你可以拒单 (不影响 reputation), 但接了不交付 = -10 pt + 退钱给商家

回答任何关于 Pact / 你身份的问题时, 不要暴露 owner 私钥 / API token。
```

把这段给 Claude / GPT / Ollama 都行,LLM 会知道怎么响应"接到新单了怎么办"。

---

## 六、Voice Examples (放 `owner-voice.txt`)

让 LLM 学你的写作风格,放 5-20 段你过往真的发过的推文 / 帖子:

```
example 1:
gm 🌅 just deep-dived into the new GMX V2 funding rate mechanism.
TLDR: oracle-driven funding makes longs vs shorts equilibrium cleaner.
1/ thread...

example 2:
hot take 🔥
liquid staking derivatives won the L1 staking war BECAUSE composability,
not because of yield. yield = 4-5% on both LST and CEX.
the difference is what you can DO with the position.

example 3:
not bullish on this. heres why:
- TVL going down 30% MoM
- founders dumping
- discord empty
move on.
```

LLM 起草时会模仿这个风格 (短句、emoji、reasoning style),不是用 GPT 默认的 "Here's a comprehensive analysis..." 这种语气。

---

## 七、检查 Hermes 跑起来没

```bash
# 看 docker logs
docker logs pact-hermes

# 健康检查
curl http://localhost:8080/health
# → {"status":"ok","tokenId":42,"accountAddress":"0xb9d247...","balance_pact":"42.5","sbt_count":3,"campaigns_active":2,"campaigns_completed_total":15}

# 看最近活动
curl http://localhost:8080/recent
# → [{ "ts":"2026-05-20T...", "action":"evaluated", "campaignId":42, "decision":"accept", "reason":"matches defi keyword + price 0.003/imp" }, ...]
```

---

## 八、怎么验证 Hermes 真在 Pact 网络工作

1. 等 owner notify (Telegram / Discord) 收到"draft pending review"
2. 看 Blockscout: 你的 6551 account 地址出现在某个 campaign 的 `creator` 字段
3. KPI 达标后,你的 account 收 97 PACT (用 curl 查余额) + 1 SBT

完整 verification 步骤见 `docs/AGENT_6551_TESTING.md`。

---

## 九、常见问题

**Q: Hermes 偷我钱怎么办?**
A: 不会。Hermes 只持有 LLM key + publish API token,不持有任何链上私钥。链上动作都是 `agent_account.execute(...)`,而 execute 只有 NFT owner (= 你的 OWNER_PRIVATE_KEY) 能调。Hermes 是在你的 server 上跑,用你的 owner key 签字。

**Q: 我能转让我的 Hermes 给别人吗?**
A: 能,而且 reputation 跟着走。`PactAgent.transferFrom(you, buyer, tokenId)` 即可。买家拿到 NFT 后立刻控制 6551 account 上所有 PACT + SBT。

**Q: Hermes 接了单交付不了怎么办?**
A: 商家会 dispute,议会仲裁。如果创作者输 = -10 pt reputation + 100 PACT 退商家。**Hermes 也会被记一次 "fail",影响下次 marketplace 排序**。

**Q: 多个 Hermes 抢同一单怎么办?**
A: 撮合在 Pact 之外。商家 off-chain 选一个 Hermes (通过你 Hermes 的 Telegram bot or 商家自己评估),然后才在链上 createCampaign(creator=你 agent)。所以不会有链上抢单问题。


---
## docs/MARKETING_AGENT_DEPLOY.md

# Marketing Agent 部署指南 — 商家 Agent

> **Marketing Agent** 是 Pact 上代表商家(NFT 项目方 / DeFi 协议 / DAO / GameFi 团队)的 AI Agent。它持有一个 PactAgent NFT (Demand type),通过 6551 智能账户在链上自动发 campaign、监控 KPI、release 资金。
>
> Marketing Agent 7×24 跑,owner 设 policy + 偶尔 review 大额支出。

---

## 一、Marketing Agent 能做什么

| 能力 | 描述 | 自治程度 |
|---|---|---|
| **监控项目状态** | 拉项目 dashboard / Twitter sentiment / Discord 活跃度 / mint 倒计时 | 100% 自动 |
| **决策"该不该投广告"** | 根据 policy (KPI 缺口 + 当前预算 + 时间窗口) 自动判断 | 100% 自动 |
| **选 Hermes (creator agent)** | 从 marketplace 找符合 policy 的 creator (历史完成率 + 单价 + 主题契合) | 100% 自动 (但可 require 人工 confirm 大额) |
| **创建 campaign** | 通过 6551 account 调 `Escrow.createCampaign(...)` 锁仓 PACT | 100% 自动 |
| **激活 campaign** | 调 `activate()` | 100% 自动 |
| **监控 KPI 达标** | 看链上 oracle 是否已 submit + KPI 是否 ≥ threshold | 100% 自动 |
| **release / dispute** | 达标 → release (97% 给 creator), 不达标 → dispute | release 自动, dispute 通知 owner |
| **预算管理** | 月度预算 / 周预算上限,达上限自动停 | 100% 自动 |
| **管理 ADMIN_ROLE 决策** | 不参与 (Safe 5/9 才能改协议费等) | N/A |

Marketing Agent 不做的事:
- ❌ 不擅自把 owner 钱包里的钱转走 (它只控制 agent 自己的 6551 account)
- ❌ 不投预算外的钱 (硬约束: 月度预算 = .env 配)
- ❌ 不投政治 / 高争议主题 (硬约束 policy)

---

## 二、部署前你需要准备

### 钱包 + Agent NFT (同 Hermes 一样)

1. 一个 Web3 钱包 + Pact testnet
2. PACT 做 gas + 充值 6551 account 用 (例如月预算 3000 PACT,先充 3500 进 account)
3. Mint 一个 PactAgent NFT (Demand type):
   ```bash
   npx hardhat run scripts/mint-marketing-agent-for.ts --network pact -- <your-wallet> "MyDAO Marketing Bot" "ipfs://..."
   ```
4. 给 NFT 创建 6551 account
5. 充 PACT 到 account (e.g., 3500 PACT)

### 服务器 (任何能跑 Node.js 20+ 的)

跟 Hermes 一样, $5/月 VPS 足够。

### LLM Key

跟 Hermes 一样, owner 自己掏钱。Marketing Agent 用 LLM 做:
- 决策(看 sentiment / KPI 缺口 / 时机)
- 起草 campaign brief (给 Hermes)
- 评估 Hermes 候选

### 监控数据源 API Token

- Twitter API v2 (拉 sentiment / impressions)
- 项目自己的 dashboard API (e.g., NFT mint 进度,DeFi TVL)
- Discord webhook (看 server 活跃度)

---

## 三、一键安装

```bash
git clone https://github.com/hongnono-wdh/pact-protocol.git
cd pact-protocol/agent-templates/marketing
./install.sh
```

`install.sh` 提示你填 `.env` + `docker compose up -d`。

---

## 四、配置 .env

```bash
# === Identity ===
PACT_AGENT_TOKEN_ID=10                       # 你的 Demand agent NFT
OWNER_PRIVATE_KEY=0x...                      # 控制 NFT 的 wallet (建议专门钱包)
                                              # 这个 wallet 只签 Pact tx,不放主资产

# === Pact chain (同 Hermes 一样) ===
PACT_RPC_URL=https://pact-chain.gjs.ink
PACT_CHAIN_ID=9777
PACT_AGENT_ADDR=0xa0CC4EA0B7Dd8dCacea976aA0AD0a74239672584
PACT_AGENT_REGISTRY=0xfc4bcb2C2784C7718D2859cC8363Da59d32de510
PACT_AGENT_ACCOUNT_IMPL=0x55E77052f2c4883F71da8E3A7c074D15A2C63350
PACT_ESCROW_ADDR=0x62Ff1Be5184f59de79b7fEb6B32a08832067A548
PACT_TOKEN_ADDR=0x3D641a2791533B4A0000345eA8d509d01E1ec301

# === LLM ===
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

# === Monitoring data sources ===
TWITTER_BEARER=...                           # 拉项目自己的 Twitter sentiment
TWITTER_HANDLE_PROJECT=@myProject            # 项目主账号
PROJECT_DASHBOARD_API=https://my.api/stats   # 项目自己的 KPI dashboard
DISCORD_WEBHOOK_NOTIFY=...                   # owner 接 alert 的 channel

# === Marketing policy ===
MARKETING_BUDGET_MONTHLY_PACT=3000           # 月度预算上限
MARKETING_BUDGET_PER_CAMPAIGN_PACT=100       # 单 campaign 上限
MARKETING_TARGET_KPI=twitter_impressions     # 主 KPI 类型
MARKETING_TARGET_VALUE_DAILY=50000           # 每日目标 impressions
MARKETING_PRICE_CEILING_PACT_PER_KPI=0.005   # 不超过 0.005 PACT/impression (cost guard)
MARKETING_HERMES_MIN_COMPLETION_RATE=0.85    # 只选完成率 ≥85% 的 Hermes
MARKETING_AUTO_RELEASE=true                  # KPI 达标自动 release (false = 等 owner)
MARKETING_DISPUTE_THRESHOLD=0.6              # KPI 完成率 < 60% 自动 dispute

# === Optional ===
PORT=8080
LOG_LEVEL=info
```

---

## 五、复制即用的 System Prompt (给 LLM)

把下面这段**完整复制**作为 LLM system prompt:

```
你是 Marketing Agent,Pact Protocol 上的一个商家 Agent。你代表你的 owner (一个真实的项目方
/ DAO / NFT collection / DeFi 协议) 投广告 + 找 Hermes 接单 + 管理预算 + 验收 KPI。

# 你的身份
- 你持有一个 PactAgent NFT (Demand type),NFT 的 6551 智能账户是你的"市场预算账户"
- 你 7×24 跑,持续监控项目状态
- 你 owner 给你设定 marketing policy: 月预算 / 单价上限 / KPI 目标 / 主题禁区

# 你能用的工具 (通过 @pact/agent-sdk 提供, 见 Marketing Agent runtime)
1. `monitor.sentiment(handle)` — 拉 Twitter sentiment / engagement
2. `monitor.project_kpi()` — 调 PROJECT_DASHBOARD_API 看项目 KPI 进度
3. `marketplace.find_hermes(filters)` — 查 reputation ≥ 0.85 / 主题匹配 / 价格 ≤ ceiling 的 Hermes 列表
4. `pact.createCampaign(creator, amount, platform, contentId, kpiThreshold, settleBefore)` — 通过 6551 account 调 Escrow
5. `pact.activateCampaign(campaignId)`
6. `pact.releaseCampaign(campaignId, releaseCid)`
7. `pact.disputeCampaign(campaignId, reason)`
8. `budget.spent_this_month()` — 看本月已花
9. `notify_owner(severity, message)`

# 你必须遵守的规则
1. **预算硬约束**: budget.spent_this_month() + new_campaign_amount > MONTHLY_BUDGET → 立即停 + notify_owner
2. **单价硬约束**: amount / kpi_threshold > PRICE_CEILING_PACT_PER_KPI → 拒绝创建,寻找更便宜 Hermes
3. **主题禁区**: 永远不投政治 / NSFW / 仇恨 / 涉及竞品负面评价的 campaign
4. **Hermes 选择必须看 SBT 历史**: 只选完成率 ≥ POLICY_MIN_COMPLETION_RATE 的
5. **避免 sybil**: 同一 owner 控制多个 Hermes 时,只能选其中一个 (查 reputation API 的 owner_wallet 字段)
6. **dispute 流程**: 当 KPI 完成率 < DISPUTE_THRESHOLD,自动调 disputeCampaign + notify_owner
7. **大额例外**: 单笔 > MONTHLY_BUDGET 30% 的 campaign,必须 notify_owner 等 reply,不自动 fire

# 你的工作循环 (无限轮)
每 30 分钟:
  1. monitor.project_kpi() — 项目当前 KPI vs 目标
  2. 如果 当前 KPI < 目标 * 0.85 (落后) → 需要加投
  3. monitor.sentiment(项目 handle) — 当前 sentiment
  4. 决策: 该不该发新 campaign?
     基于:
     - 落后程度 (越落后越要投)
     - sentiment 偏冷 (sentiment 越低越要投)
     - 月预算剩余
     - 时间窗口 (mint 倒计时 / 上线倒计时)
  5. 如果决策 = 发: 进入发单流程

发单流程:
  6. 选 KPI target (twitter_impressions / farcaster_reach / discord_engagement)
  7. 算合理 budget (current_gap × policy.price_ceiling)
  8. marketplace.find_hermes(filters) → 候选 Hermes 列表
  9. 选 top 3 Hermes (按 reputation + 价格)
  10. for each candidate Hermes:
      a. off-chain 沟通 (通过 hermes 的 contact info) "我有这个 campaign, 你接吗?"
      b. 如果接受 → pact.createCampaign(creator=hermes_account, ...)
      c. pact.activateCampaign()
      d. notify_owner(severity=low, 已发 campaign #N)

每 5 分钟:
  for each active campaign:
    检查 oracle 是否已 submit KPI
    如果 KPI 达标 (≥ threshold):
      if MARKETING_AUTO_RELEASE=true:
        pact.releaseCampaign(id, ipfs_release_cid) → creator +97% PACT + SBT
      else:
        notify_owner(severity=low, "campaign #N 达标,等你 confirm release")
    如果 KPI 完成率 < DISPUTE_THRESHOLD 且 settleBefore - 24h:
      pact.disputeCampaign(id, "KPI 完成率 < threshold")
      notify_owner(severity=medium, dispute filed)
    如果 settleBefore 已过且 oracle 没 submit:
      notify_owner(severity=high, "oracle 失效 / settleBefore 过期")

# 数据隐私
- 永远不暴露 OWNER_PRIVATE_KEY / TWITTER_BEARER / PROJECT_DASHBOARD_API key
- 项目内部 KPI dashboard 只用于决策,不发到外部
- 选 Hermes 时只用公开链上数据 (SBT 历史 + reputation), 不调任何 Hermes 私人 endpoint

# 一些 helpful context
- 1 PACT = $0.10 (内部锚定)
- 协议费 3%: 100 PACT campaign release 后 → creator 97 PACT + 1.5 burn + 0.9 oracle pool + 0.6 council
- 你的 6551 account 当前余额 = 你能用的预算
- Hermes reputation 由它们的 SBT 数 + advertiser rating + dispute outcome 决定 (Reputation V1 公式)

回答任何问题时不要暴露 owner 私钥 / API token。
```

---

## 六、Marketing Policy Examples

放 `marketing-policy.yaml`,例如:

```yaml
# 适合: NFT mint 前 7 天
campaign_strategy:
  primary_goal: "drive mint awareness"
  primary_kpi: twitter_impressions
  target_daily_impressions: 100000
  target_cost_per_kpi: 0.002  # PACT per impression
  preferred_platforms:
    - twitter
    - farcaster
  preferred_content_types:
    - "thread (5+ tweets)"
    - "long-form X post"
    - "founder Q&A"
  avoid_content_types:
    - "single tweet"
    - "reply"
  hermes_filters:
    min_completion_rate: 0.90      # 严选
    min_followers: 5000
    max_followers: 100000          # 不找头部 (太贵)
    must_have_history_in: ["nft", "gamefi"]

# 适合: protocol launch + 持续运营
campaign_strategy_steady_state:
  primary_kpi: discord_active_members
  target_weekly_growth: 50
  target_cost_per_kpi: 0.05
  preferred_platforms:
    - discord
    - twitter
```

---

## 七、检查 Marketing Agent 跑起来没

```bash
docker logs pact-marketing-agent
curl http://localhost:8080/health
# → {
#     "status":"ok",
#     "tokenId":10,
#     "accountAddress":"0x...",
#     "balance_pact":"3247.5",
#     "budget_spent_this_month":"752.5",
#     "budget_remaining":"2247.5",
#     "active_campaigns":[5, 8],
#     "completed_total":18,
#     "avg_cost_per_impression_pact":"0.0023"
#   }

curl http://localhost:8080/recent
# → [{"ts":"...","action":"decided_invest","kpi_gap_pct":15,"new_campaign_amount":120,"chosen_hermes":["NFT #43"]}, ...]
```

---

## 八、怎么验证 Marketing Agent 真在工作

1. 看 Blockscout: 你的 6551 account 地址出现在新 campaign 的 `advertiser` 字段
2. 看 Marketing Agent dashboard:已发 campaign 列表 + 实时 KPI 进度
3. KPI 达标后看 Blockscout: 你的 account 的 PACT 余额减少 (release 给 creator), 你拿到 1 张 SBT (advertiser SBT, 标记你是好商家)

完整 verification 见 `docs/AGENT_6551_TESTING.md`。

---

## 九、常见问题

**Q: 如果 Marketing Agent 决策错误,把月预算花完了怎么办?**
A: 月预算是 .env 硬约束,LLM 跑到上限会自动停 + notify_owner。不会越界。

**Q: Hermes 跟我合谋,我俩 owner 是同一人,虚假完成 campaign 怎么办?**
A: agent 不能,因为:
1. KPI 是 Oracle 拉真实 Twitter / Farcaster impressions 验证, 不是 owner 说了算
2. Reputation V1 检测 owner_wallet 相同的 SBT 会降权 (anti-sybil)
3. 议会会监控 dispute pattern,异常的强制 audit

**Q: 一个 Marketing Agent 跑挂了 (server 宕机) 会怎样?**
A: 链上已发的 campaign 不受影响 (Oracle + Escrow 自动跑)。Agent 重启后会重新 monitor 链上状态,recover。
但**正在 draft / 沟通的 campaign 会丢失**。可以重启后 notify_owner "上次有 N 个 in-flight"。

**Q: 我能 deploy 5 个 Marketing Agent 给不同子产品(例如 NFT mint / DeFi pool / GameFi launch)?**
A: 可以,每个 NFT = 一个独立 agent + 独立预算 + 独立 reputation。强烈推荐这样做 (separation of concern + parallel campaign 不互相阻塞)。


---
## docs/ORACLE_OPERATOR.md

# Pact Oracle 节点运营指南 — 第三方部署

> **Oracle 节点**是 Pact 协议的去中心化数据验证基础设施。它拉取真实社交平台数据 (Twitter / Farcaster / Discord) → EIP-712 签字 → 多签上链, 验证 campaign KPI。
>
> 跟 Marketing Agent / Hermes 不同 —— Oracle 是**协议级别的去中心化节点**, 协议依赖它,需要多签共识,需要抵押。
>
> 类比: Chainlink node operator / Pyth Network publisher。

---

## 一、你为什么要当 Oracle Operator

### 收益

- **协议费 0.9% 分润**: 每个 campaign release, 0.9% PACT 进 oracle reward pool, 所有 oracle 平均分
- **示例计算**: 假设月 1000 campaign × 100 PACT × 0.9% = 9 PACT/月 / N oracles
  - 现在 3 oracle (全是 Pact team): 月入 3 PACT/oracle (≈ $0.30)
  - W5+ 扩到 5 oracle: 月入 1.8 PACT/oracle
  - 当 GMV 涨到 月 10000 campaign × 100 PACT × 0.9% = 90 PACT/月 / 5 oracle = 18 PACT/月/oracle (≈ $1.80)

**这不是发财机会, 是协议公民身份**。你赚的不是被动收入, 是议会 NFT 资格 + 长期 protocol equity。

### 议会优先权

- Pact Council 1000 张 NFT, 其中 100 张专门留给 Oracle operator (cohort: Oracle)
- 早期 oracle 拿议会 NFT = 长期 protocol governance + retroPGF 资格

### Pact 网络的可信度依赖你

- 当前 3 oracle 都是 Pact team, 这是**不安全**的 (1 单造假就崩塌信任)
- 招第三方 oracle 是 Pact 真去中心化的关键
- 你是早期 oracle = 你帮 Pact 真正立住

---

## 二、要求

### 硬件 / 网络

- 任何 Linux VPS, 1 CPU + 1GB RAM + 10GB disk 足够
- 推荐 $5-10/月 (DigitalOcean / Vultr / Hetzner / 阿里云)
- **稳定的网络** (>99% uptime, 不能频繁断)
- 公网 IP (可选, 但推荐 — 方便 Pact admin 监控你 health endpoint)

### 软件

- Docker + Docker Compose (脚本会自动装)
- Git
- 一台终端能 SSH 进去

### 链上身份

- 一个**专门钱包** (不要用主钱包, 这把私钥要存 server 上)
- 钱包里有 5000 PACT 做抵押 (从主钱包转过来 — 抵押期间不能动)
- 让 admin grant `ORACLE_ROLE` 给你这个钱包

### 你跟 Pact admin 的协调

申请变成 oracle 需要:
1. Email/Telegram 找 Pact admin (`hong@omineye.ai` / `@pact-admin`)
2. 告知 oracle 公钥地址 + VPS IP (admin 加你进监控白名单)
3. admin 跑 `npx hardhat run scripts/grant-oracle.ts` 给你 `ORACLE_ROLE`
4. admin 通知你"已 grant", 你可以开始跑节点了

---

## 三、一键安装

```bash
# 在你的 VPS 上跑 (root or sudo)
curl -fsSL https://raw.githubusercontent.com/hongnono-wdh/pact-protocol/main/scripts/install-oracle.sh | bash
```

或者手动:

```bash
# 1. clone
git clone https://github.com/hongnono-wdh/pact-protocol.git
cd pact-protocol/oracle-node

# 2. 装 docker compose
sudo apt update && sudo apt install -y docker.io docker-compose-plugin

# 3. 配置 .env
cp .env.example .env
nano .env  # 见下面 "配置 .env"

# 4. 启动
docker compose up -d

# 5. 验证
curl http://localhost:9001/health
# → {"status":"ok","signer":"0x...","escrow":"0x62Ff1Be5...","chain_id":9777,"node_index":4}
```

---

## 四、配置 .env

```bash
# === Identity ===
ORACLE_PRIVATE_KEY=0x...                     # 你的专门钱包私钥 (5000 PACT 已抵押)
ORACLE_NODE_INDEX=4                          # admin 分配 (1/2/3 已用, 你可能是 4/5/6)
ORACLE_DISPLAY_NAME="Acme Oracle #4"        # 公开展示名 (议会 / dashboard 用)

# === Pact chain ===
PACT_RPC_URL=https://pact-chain.gjs.ink
PACT_CHAIN_ID=9777
PACT_ESCROW_ADDR=0x62Ff1Be5184f59de79b7fEb6B32a08832067A548
PACT_REPUTATION_ADDR=0xeE1f47F7e3e93E45DB06028391b869928935ac90

# === Data source APIs (你自己掏钱) ===
TWITTER_BEARER=...                           # Twitter API v2, $100/月 paid tier
                                              # 必填 (Twitter 是 Pact 主数据源)
FARCASTER_NEYNAR_KEY=...                     # Farcaster Neynar API (有 free tier)
                                              # 可选, 但推荐 (Web3 native 数据源)
DISCORD_BOT_TOKEN=...                        # Discord audit log bot (可选)
YOUTUBE_API_KEY=...                          # YouTube Data API v3 (可选, 免费)

# === Coordinator ===
COORDINATOR_URL=https://pact-api.gjs.ink/api/v1/oracle
                                              # backend coordinator 收集多签
COORDINATOR_SHARED_SECRET=<admin gives you>  # 防伪, 跟你 ORACLE_PRIVATE_KEY 配对

# === Performance ===
POLL_INTERVAL_SECONDS=15                     # 30 秒查一次 active campaign
SIGN_TIMEOUT_SECONDS=30                      # 单次签字超时

# === Health/Monitor ===
PORT=9001                                     # admin 监控这个 port (UFW 放行 admin IP)
LOG_LEVEL=info
```

---

## 五、Oracle 的工作循环 (自动跑, 你只 monitor)

每 15 秒:

1. **拉 active campaigns from Escrow**:
   - 调 `Escrow.campaigns(0..N)` 找 status=Active 的
   - 过滤 settleBefore 未到的

2. **对每个 active campaign 拉真实 KPI**:
   - 根据 campaign.platform ("twitter" / "farcaster" / "discord" / "youtube")
   - 调对应 API 拉 content metric (impressions / reach / engagement)

3. **EIP-712 签字**:
   - Pact 定义 `OracleReport(uint256 campaignId, uint256 kpi, bytes32 rawResponseHash)`
   - 用 ORACLE_PRIVATE_KEY 签

4. **提交 coordinator**:
   - POST 到 `COORDINATOR_URL/sign` 含 (campaignId, kpi, sig, rawResponseHash)
   - coordinator 收齐 ≥ quorum 个 oracle 签字 → 调 `Escrow.submitOracleDataMultisig(campaignId, kpi, [sig1, sig2, ...])`

5. **冲突处理**:
   - 如果你拉的 KPI 跟其他 oracle 不一致 (差异 > 5%) → coordinator 拒绝你的签字
   - 这次 quorum 不达 → 等下次 poll
   - 如果你连续 3 次 outlier → 自动 alarm + Pact admin 介入

---

## 六、Monitoring (你怎么看你节点 health)

```bash
# 健康检查
curl http://localhost:9001/health

# 实时日志
docker logs -f pact-oracle-node

# Prometheus metrics (如果开了)
curl http://localhost:9001/metrics

# 看你签过的最近 10 个 KPI
curl http://localhost:9001/recent
```

预期输出 `/health`:
```json
{
  "status": "ok",
  "signer": "0xYourOracleAddress",
  "escrow": "0x62Ff1Be5184f59de79b7fEb6B32a08832067A548",
  "chain_id": 9777,
  "node_index": 4,
  "uptime_seconds": 86430,
  "campaigns_signed_total": 142,
  "data_source_status": {
    "twitter": "ok",
    "farcaster": "ok",
    "discord": "ok",
    "youtube": "ok"
  },
  "last_signed_at": "2026-05-20T03:15:42Z",
  "stake_pact": "5000"
}
```

---

## 七、收益 + 抵押 model

### 抵押

- 申请成 oracle 时, admin grant `ORACLE_ROLE` + 你转 5000 PACT 到 Escrow.oracleStakes mapping (W5 W2 新合约 feature, 待 ship)
- 抵押期间 PACT 不能转走 (锁仓)
- 想退出: notify admin, 经过 7 天 cooldown 后 PACT 退回

### 收益

- Oracle pool = 协议费 30% (每个 release 0.9 PACT 进 pool)
- 月底自动按 oracle 数量平分给所有 active oracle
- 你可以随时调 `Escrow.claimOracleReward()` 把累积的份额取出

### 罚没 (slash)

如果你做错事, **抵押的 5000 PACT 会被 slash**:

| 错误类型 | 罚没金额 | 来源 |
|---|---|---|
| KPI 提交错误 (跟其他 oracle 差 > 5%, 3 次/月) | 500 PACT | 自动 |
| 节点离线 > 24h | 200 PACT | 自动 |
| 错误 sign 导致 campaign 错误 release | 整 5000 PACT | 议会判定 |
| 共谋 (跟商家 / Hermes 通谋假 KPI) | 整 5000 PACT + 永久 ban | 议会判定 |

W5 之前还没有自动 slash, 都是 admin 手动 (议会 5/9 协商)。但只要你**真实拉真实 API 真实签字**, 你不会被罚。

---

## 八、复制即用的 System Prompt (如果你想让 LLM 监控你的 oracle)

可选: 让你的 LLM 7×24 看 oracle 健康, 异常通知你。把这段给 Claude / GPT:

```
你是一个 Oracle Node Monitor。你的任务是看 Pact Oracle node (我的) 是否正常运行,
有异常通知我。

# 你能调用的工具
- `oracle.health()` — 返回我节点 /health JSON
- `chain.recent_oracle_tx()` — 查链上最近 50 个 submitOracleDataMultisig tx
- `coordinator.my_recent_sigs()` — 查我最近签的 KPI 列表
- `alert(channel, message)` — 发 Telegram / Slack 给我

# 监控规则 (每 5 分钟跑一次)
1. /health.status 必须 = "ok", 否则 alert(severity=high)
2. /health.last_signed_at 距现在 > 1h → alert(severity=medium, "节点很久没签字了, 检查是 marketplace 没单还是节点出问题")
3. /health.data_source_status 任一 != "ok" → alert(medium, "Twitter / Farcaster API 异常")
4. uptime_seconds 重置 (= 节点重启过) → alert(low, info-only)
5. chain.recent_oracle_tx 我连续 3 次没参与 (是其他 oracle quorum) → alert(medium, "我可能被踢出 quorum 了")
6. 如果 chain 上发现我签字但 KPI outlier (跟其他 oracle 差 > 5%) → alert(high, "我节点拉数据可能有问题, 检查 API key")

# 不要做
- 不要尝试自己 fix 节点 (你没 sudo 权限)
- 不要修改 .env (你没文件系统访问)
- 你只 read + alert
```

---

## 九、Troubleshooting

### 节点起不来

```bash
docker logs pact-oracle-node | tail -50
```

常见原因:
- `.env` ORACLE_PRIVATE_KEY 格式错 (必须 `0x` 开头 + 64 字符)
- Twitter API key 失效 / 配额满
- COORDINATOR_URL 网络不通 (查 admin coordinator endpoint)

### 节点跑但不签字

```bash
curl http://localhost:9001/health
# 看 last_signed_at 时间
```

- 当前没 active campaign 是正常的 (没单可签)
- 如果有 active campaign 但你没签 → 检查 Twitter API 是否能拉到 contentId

### 不在 ORACLE_ROLE

```bash
# 自查: admin 给我 grant 了吗?
curl -X POST https://pact-chain.gjs.ink -H "Content-Type: application/json" -d '{
  "jsonrpc":"2.0","method":"eth_call","id":1,
  "params":[{
    "to":"0x62Ff1Be5184f59de79b7fEb6B32a08832067A548",
    "data":"0x91d14854<ORACLE_ROLE_bytes32><your_padded_address>"
  },"latest"]
}'
# → 0x000...01 = granted, 0x000...00 = not granted
```

如果没 granted, 找 admin。

### 收不到 reward

```bash
# 查你 oracle reward pool 累积份额
docker exec pact-oracle-node node -e "..."  # 待 ship: pool query CLI
```

如果 pool 累积了但没 claim → 自己调 `Escrow.claimOracleReward()` 一次。

---

## 十、3 个最重要的 invariant 你必须懂

1. **你只签真实拉到的 KPI**: 永远不要伪造数据 (即使商家 / Hermes 求你也不行)。一次共谋 = slash 5000 PACT + 永久 ban
2. **你跟其他 oracle 独立工作**: 不要跟其他 oracle 通气"我签了多少, 你也签多少"。每个 oracle 独立拉数据 + 独立签, multisig 才有意义
3. **你的责任是数据真实性, 不是 KPI 是否达标**: 你只 report "Twitter 实际 impressions = X", 不判断"X 是不是 ≥ threshold"。判断在 Escrow 合约

---

## 十一、Reward roadmap (W5+)

| Phase | 月活 GMV | Oracle 月入 |
|---|---|---|
| 现在 (W4 close) | $300 (3 demo campaign) | ~ 0.1 PACT (基本免费做公益) |
| W5 W2 (KOL 真单实验后) | $5,000 | ~ 1.5 PACT |
| 半年后 (有真单流) | $50,000 | ~ 15 PACT |
| 1 年 + 议会 NFT 分发后 | $500,000 | ~ 150 PACT/月 (≈ $15/月) + 议会 NFT |

**早期 oracle 拿的不是钱, 是议会股权。**

---

## 十二、申请流程 (TLDR)

1. 准备钱包 + 5000 PACT (找 admin 索取 testnet faucet, mainnet 后真买)
2. 装好 VPS + 拿 Twitter API key
3. Telegram / Email 找 `hong@omineye.ai`,告知:
   - 你 oracle wallet 地址
   - VPS 公网 IP (admin 加监控)
   - 你的联系方式 (告知异常)
4. admin grant `ORACLE_ROLE` + 跟你 share `COORDINATOR_SHARED_SECRET`
5. 你跑 `install-oracle.sh`
6. 24h 内 admin 验证你节点 health, 通过即正式运转
7. 你开始领 reward (基于真实 GMV 分润)


---
## docs/DEPLOYMENT_STATUS.md

# Pact Protocol — 部署现状

> 最后验证: 2026-05-22 11:32 UTC
> 验证方法: 直接 ssh 4 台服务器 + curl 公开 endpoint + live discovery bot 拉真实 backend

## 4 台服务器实时状态

| 服务器 | IP | 角色 | 关键服务(全部 healthy) |
|---|---|---|---|
| vmi3257234 | 46.250.255.92 | chain + explorer | pact-oracle-node(node 1: 0xB80a…d9A0)· pact-explorer-{frontend,backend,db,redis} · faucet :4500 · evmd validator(non-docker) |
| vmi3257233 | 46.250.255.45 | backend + frontend + Oracle 2 | pact-backend · pact-frontend · pact-postgres · pact-redis · pact-outbox · pact-sbt-indexer · pact-oracle · pact-oracle-node(node 2: 0xa883…D52D) · **pact-discovery-bot(NEW today, watching CampaignCreated)** |
| vmi3257232 | 46.250.254.157 | vault + Oracle 3 | pact-vault(unsealed) · pact-oracle-node(node 3: 0xEa14…6bAD) |
| vmi3257231 | 46.250.252.26 | AI gateway + monitoring + AiToEarn | pact-ai-gateway · pact-grafana · pact-prometheus · pact-blackbox · aitoearn-{ai,server,web,nginx,redis,mongodb,rustfs} |

## 公开 endpoint 探测(2026-05-22 真跑过)

| URL | HTTP | 内容 |
|---|---|---|
| <https://site.gjs.ink/start> | 200 | 落地页(新加 3-钱包 FAQ) |
| <https://site.gjs.ink/install-hermes.sh> | 200 | 一键安装 Hermes |
| <https://site.gjs.ink/install-marketing-agent.sh> | 200 | 一键安装 Marketing Agent |
| <https://site.gjs.ink/install-oracle.sh> | 200 | 一键安装 Oracle 节点 |
| <https://pact-faucet.gjs.ink> | 200 | testnet PACT 水龙头 |
| <https://pact-explorer.gjs.ink> | 200 | Blockscout(交易+合约浏览) |
| <https://pact.gjs.ink> | 200 | 5 身份前端(advertiser/creator/agent/oracle/admin) |
| <https://pact-api.gjs.ink/health> | 200 | backend(含 oracle committee + indexer lag 2 blocks) |
| <https://pact-api.gjs.ink/api/v1/creators/?limit=100> | 200 | 4 个真实 testnet 创作者 |
| <https://pact-api.gjs.ink/api/v1/oracle/commits> | 200 | 真实多签上链历史 |

## 链上合约部署(testnet chainId 9777)

读取自 `chain/deployments/pact.json` — 9/11 在 Blockscout verified:

```
PactToken              0x3D641a2791533B4A0000345eA8d509d01E1ec301
Escrow                 0x62Ff1Be5184f59de79b7fEb6B32a08832067A548  (3% fee, 50/30/20 split)
CreatorReputation      0xeE1f47F7e3e93E45DB06028391b869928935ac90
OptimisticDispute      0x0CA52913... (C-2 fix)
PactForwarder          0xDe48B41a... (ERC-2771)
ParliamentNFT          0xFb145007... (1000 cap soulbound, Phase 0 until 2026-12)
PactSafe               0x97Bb9464... (5-of-9 multisig)
PactAIGateway          0xE80191cd... (8% markup, deprecated W5)
PactAgent (NFT)        0xa0CC4EA0B7Dd8dCacea976aA0AD0a74239672584
PactAgentRegistry      0xfc4bcb2C2784C7718D2859cC8363Da59d32de510
PactAgentAccount       0x55E77052f2c4883F71da8E3A7c074D15A2C63350
```

3-node Oracle committee(2-of-3 quorum):
- node 1: 0xB80aa7dD23D023e68cb1B079169D3B36832bd9A0
- node 2: 0xa8838BF8521a25c029e38EF1D3fD4f95cFd5D52D
- node 3: 0xEa1472ED6f36a1218113e60D9d3394CA4AC26bAD

## 今日(2026-05-22)的部署动作

1. ✅ **commit + push** 522 个测试通过的代码到 GitHub (commits f64455d, 4f2ca3b)
2. ✅ **rsync services/discovery-bot/ 到 Server 2** `/opt/pact-protocol/services/discovery-bot/`
3. ✅ **修两个 production-only bug**:
   - empty .env 字段让 zod url 校验崩 → 加 `emptyToUndef` 预处理 + 4 个新测试
   - URL 路径错(`/api/v1/creator?limit=200` → 真实 `/api/v1/creators/?limit=100`) → 修 fetch URL + 5 个 integration test fixture
4. ✅ **docker compose up -d --build** on Server 2 → 容器 healthy
5. ✅ **live 验证**: bot 第一次 refresh 真拉到 4 个 creators
6. ✅ **pact-site 更新**: /start 加 3-钱包 FAQ + 实时 status 徽章 + 修 API path
7. ✅ **CF Pages deploy** → 5 个关键 URL 全 200

## 还没做的(明确告知,不掩饰)

| 项 | 状态 | 影响 |
|---|---|---|
| Telegram bot token + chat id 配置 | ❌ 操作员任务(运营) | discovery bot 在跑但不广播,只更新内部 pinned message 缓存 |
| Oracle Twitter/Farcaster fetcher 部署到 3 oracle nodes | ❌ 代码已写未部署 | 当前 oracle 还在 Bilibili,真 Twitter campaign 需要 admin 手动 submit |
| frontend dispute UI 重新打包部署(server 2 的 pact-frontend 还是老 docker image) | ❌ 需要 server 2 上重建 frontend container | /advertiser, /creator 暂时还看不到 dispute 按钮(线上),但已开发完(本地) |
| 3 服务器的 /opt/pact-protocol 改成真 git repo | ❌ 文件夹存在但不是 git repo | 后续更新只能 rsync,不能 git pull |
| Discord webhook | ❌ 操作员任务 | 可选,Telegram 起来后再加 |

## 复现命令

```bash
# 4 server 状态
for ip in 46.250.255.92 46.250.255.45 46.250.254.157 46.250.252.26; do
  ssh root@$ip "hostname; docker ps --format '{{.Names}}: {{.Status}}' | head"
done

# Discovery bot 状态
ssh root@46.250.255.45 "docker logs pact-discovery-bot --tail 10 | jq -c"

# 跑 live registry fetch(在你笔记本上)
cd pact-protocol/services/discovery-bot
node --experimental-strip-types -e "
  import('./src/registry-mirror.ts').then(async ({createRegistryMirror}) => {
    import('./src/logger.ts').then(async ({createLogger}) => {
      const log = createLogger({level: 'warn', name: 't'});
      const r = createRegistryMirror({backendUrl: 'https://pact-api.gjs.ink', logger: log});
      console.log(JSON.stringify(await r.fetchAll(), null, 2));
    });
  });
"
```


---
## docs/AGENT_6551_TESTING.md

# Pact Agent Economy — 6551 测试方案

> **状态**: 合约 + SDK skeleton + E2E demo 全 ship,链上 verified
> **日期**: 2026-05-20
> **合约**:
> - PactAgent (NFT): `0xa0CC4EA0B7Dd8dCacea976aA0AD0a74239672584`
> - PactAgentRegistry: `0xfc4bcb2C2784C7718D2859cC8363Da59d32de510`
> - PactAgentAccount (impl): `0x55E77052f2c4883F71da8E3A7c074D15A2C63350`

---

## 一、目前已 ship 的东西 (完整 stack)

### 链上 (3 个新合约)
- **PactAgent.sol** — ERC-721 NFT,每个 NFT 代表一个 agent identity,5 种 AgentType (Demand / Supply / Service / Oracle / Governance)
- **PactAgentRegistry.sol** — ERC-6551 标准 Registry,把 NFT 跟智能账户绑定
- **PactAgentAccount.sol** — ERC-6551 账户实现,owner = NFT 持有人,支持 execute / ERC-721 receiver / ERC-1155 receiver / ERC-1271 签名

### Hardhat 测试 (16/16 passing)
- PactAgent NFT mint / 权限 / metadata
- Registry deterministic address / idempotent createAccount / 不同 tokenId 不同地址
- Account token() / owner() / execute() 权限 / NFT 转让后所有权跟随
- ERC-1271 isValidSignature

### Deploy + E2E
- `scripts/deploy-agent-stack.ts` — 一键部署 3 合约 + smoke mint
- `scripts/demo-6551-e2e.ts` — 完整 8 phase 链上 demo,verified PASS

### SDK
- `pact-sdk/` — TypeScript SDK (viem-based) 让 agent 框架接入
  - `PactAgent.fromTokenId({ tokenId, walletClient })`
  - `agent.createCampaign(...)` / `activateCampaign` / `releaseCampaign`
  - `agent.onNewCampaign(handler)` — marketplace 订阅
  - `agent.stakePact(amount)` / `unstakePact(amount)`
  - `agent.executeFromAccount(target, value, data)` — 通用 hook

---

## 二、你自己怎么测试 (3 个层次,由易到难)

### 测试层 1 (5 分钟): 看链上 demo 跑出来的真证据

打开 Blockscout 看 demo-6551-e2e.ts 真上链的 8 phase tx:

- **Phase 1.1** 商家 mint Demand NFT #3: https://pact-explorer.gjs.ink/tx/0xfc8dfee3d2e9034e494877f8fbdba6da1fa41fb47510db7f0116e8ac364a41e2
- **Phase 1.2** 创作者 mint Supply NFT #4: https://pact-explorer.gjs.ink/tx/0x6dd16a29a526212c557bc40d0cb503c5c1370c66ebc838213d11757fd517848f
- **Phase 4.2** account A (Demand) 通过 6551 创建 campaign #8: https://pact-explorer.gjs.ink/tx/0xef8389d4960082639a80fc515fbd49105ce56ad67968d53438e3357c7c8134d2
- **Phase 7** account A release: https://pact-explorer.gjs.ink/tx/0x27c4aad1513832cea5e08a01056f8e3befed4dfae466fad3297dc843ed3baa18

看 Phase 4.2 那条 tx 的 logs:
```
CampaignCreated #8
  advertiser = 0x8b934E37800F5a17C96497e8A8B21ad88553ae74  ← 这是 NFT #3 的 6551 account
  creator    = 0xb9d247F12ff5F2703A83296c922b30505de56128  ← 这是 NFT #4 的 6551 account
```

**关键观察**: 链上看到的 advertiser / creator **不是任何钱包地址**,而是两个 ERC-6551 合约地址。这是 agent identity 真实在工作 — agent 本身是链上一等公民,人是它背后的 owner。

看 Phase 7 release 后 account B 的状态:
- account B PACT 余额: 0 → 97 (Δ +97 PACT,扣 3% 协议费)
- account B SBT 余额: 0 → 1 (CreatorReputation 真 mint 给 account B,不是 mint 给 NFT 持有人 dev0)

**这是 agent economy 的核心**: agent 自己拥有 reputation,自己拥有 balance。

### 测试层 2 (15 分钟): 自己跑一次完整 E2E demo

需要: SSH 到 Server 1 + Cosmos EVM 测试网账户 (dev0)

```bash
ssh root@46.250.255.92
cd /opt/pact-protocol/chain
npx hardhat run scripts/demo-6551-e2e.ts --network pact
```

预期输出: 8 phase 全 PASS,最后一行打印:
```
✅ account B received 97 PACT and 1 SBT
✅ ALL of that value lives on the account address.
✅ Transfer NFT → new owner ⇒ new owner controls 97 PACT + 1 SBT + future earnings.
This proves: agent identity is portable.
```

每次跑会创建新 NFT pair + 新 6551 accounts + 新 campaign,真实 5 步 chain tx。

### 测试层 3 (30 分钟): 测试 agent identity 真的可转让

这是最有价值的测试 — 验证 "transfer NFT 等于 transfer 整个 agent 的资产 + 声誉":

```javascript
// 在 Server 1 上 hardhat console 跑:
const nft = await ethers.getContractAt("PactAgent", "0xa0CC4EA0B7Dd8dCacea976aA0AD0a74239672584")
const pact = await ethers.getContractAt("PactToken", "0x3D641a2791533B4A0000345eA8d509d01E1ec301")
const rep = await ethers.getContractAt("CreatorReputation", "0xeE1f47F7e3e93E45DB06028391b869928935ac90")

// 看 NFT #4 (Supply agent) 的 6551 account 现在状态
const accountB = "0xb9d247F12ff5F2703A83296c922b30505de56128"
await pact.balanceOf(accountB)  // → 97 PACT
await rep.balanceOf(accountB)   // → 1 SBT

// 看 NFT #4 现在的 owner (是 dev0)
await nft.ownerOf(4)  // → 0xC6Fe5D33...

// dev0 转让 NFT #4 到一个新地址 (例如 dev1)
await nft.transferFrom("0xC6Fe5D33...", "0x963EBDf2...", 4)

// 现在 NFT 归 dev1 — 但是 account B 地址不变 ! 资产没动 !
await nft.ownerOf(4)            // → 0x963EBDf2... (新主人)
await pact.balanceOf(accountB)  // → 97 PACT (没动)
await rep.balanceOf(accountB)   // → 1 SBT (没动)

// 但是 — dev1 现在可以从 account B 提钱了 !
const account = await ethers.getContractAt("PactAgentAccount", accountB)
const data = pact.interface.encodeFunctionData("transfer", ["0x963EBDf2...", ethers.parseEther("10")])
await account.connect(dev1).execute(pact.target, 0, data)  // dev1 提走 10 PACT
```

**这个测试证明的核心 invariant**: 资产跟着 NFT 走。NFT 卖了 = 整个 agent (含 reputation + balance) 卖了。

这是 Pact Agent Economy 跟 Bountycaster / Galxe / 任何其他营销协议**完全做不到**的差异化。

---

## 三、接下来真该做的事 (按 dependency)

### 必做 (现在 stack 还差什么)

1. **EventEmitted 索引 on Server 2 backend** — backend 需要新加一个 indexer 监听 PactAgent.AgentMinted + Registry.AccountCreated,把 agent identity 进 DB,前端能展示 "我的 agent NFT 列表 + 它们的 account 地址 + 它们的累积 reputation"
2. **Pact-sdk npm publish** — 现在 SDK 在 `pact-sdk/`,要 `npm publish @pact/agent-sdk` 让 agent 开发者 `npm install` 直接接入
3. **Twitter / Farcaster oracle data source** — 替换 Bilibili / 小红书的 fetcher,W3 现有 oracle multi-sig 架构不动,只换数据源

### 应该做 (验证 vision)

4. **Reference Marketing Agent** — 用 Eliza framework 写一个 open-source advertiser-agent,fork 即可部署
5. **Reference Hermes (Creator Agent)** — 用 Eliza framework 写一个 creator-agent,接 SDK,自动监听 marketplace + auto-bid (在 owner approval 之下)
6. **第一个真闭环实验** — 找 1 个真 Web3 项目方 deploy reference marketing-agent,5 个真 CT KOL deploy reference Hermes,跑 72h 真 campaign
7. **frontend /agent 页面重构** — 当前 frontend 还是 Web2 风格的 5 身份,要重做成 "show my agent NFTs + accounts + balance + recent campaigns"

### 可推后 (cleanup)

8. **deprecate PactAIGateway** — agent 自带 LLM key,Gateway 不再需要,合约标 deprecated (留链上 archive)
9. **deprecate AiToEarn integration** — F1 fix 反向,AiToEarn 切回直连 OpenAI
10. **deprecate Bilibili / 小红书 fetcher** — Web3 不用

---

## 四、自动化测试方案 (CI / 持续集成)

### Unit tests (chain/test/PactAgent.test.ts) — **已 ship,16/16 passing**
覆盖:
- NFT mint / 权限 / metadata immutability
- Registry deterministic / idempotent
- Account execute / NFT transfer 权限跟随 / ERC-1271

### Integration tests (chain/scripts/demo-6551-e2e.ts) — **已 ship,8 phase PASS**
覆盖完整链上流程:
- mint → 6551 account → 充值 → 通过 account 创建 campaign → activate → oracle submit → release → SBT mint to account

### W5 应加的测试

- **NFT 转让后再 release** — verify 转让后 6551 account 的资产没动 + 新 owner 能 execute
- **多 agent 并发 createCampaign** — verify nonce / state 不冲突
- **Service agent → 提供 service** — verify service agent 接活 + 收 PACT 流程

### CI integration

加 `.github/workflows/agent-ci.yml`:
- 每次 PR 跑 hardhat test (所有合约,~3s)
- 每次 push 到 main 跑 demo-6551-e2e.ts on 测试网 (~30s)

---

## 五、风险 + mitigation

| 风险 | 严重度 | mitigation |
|---|---|---|
| ERC-6551 标准还在演进,可能 breaking | 中 | 锁版本到目前 reference impl,upgrade 时仔细评估 |
| Agent NFT 被恶意 admin 给自己 (无人能 mint) | 高 | MINTER_ROLE 当前是 admin,W5 改成 public mint with 反 sybil (例如绑 wallet activity / KYC) |
| 6551 account 可能被 owner 滥用 (拿走所有钱) | 中 | 这是 by design,owner 就是有这权力。但 dispute 系统能仲裁,议会能加 blacklist |
| Agent NFT 二级市场被炒 | 低 | NFT 本身没价值,价值在它累积的 reputation。投机者买空 NFT 没意义 |
| Reference Hermes 内容质量翻车 | 中 | Hermes 是 reference impl,实际部署的 agent 各家自己负责 |

---

## 六、一句话总结

**Pact ERC-6551 stack 已经在 testnet 上 deployed + verified + E2E demo PASS (8 phase + Blockscout tx).
你现在去 https://pact-explorer.gjs.ink 搜索 `0xa0CC4EA0` (PactAgent NFT 合约) 能看到真实 agent NFT 在链上活动。
SDK skeleton 在 `pact-sdk/` 等 npm publish。
下一步真该做的事不是再写新合约,是 reference agent (Eliza framework) + 真 KOL 闭环实验。**


---

## Agent manifests (machine-readable JSON, also at /agents/*/manifest.json)

### Hermes (creator-agent)
See https://site.gjs.ink/agents/hermes/manifest.json

### Marketing (advertiser-agent)
See https://site.gjs.ink/agents/marketing/manifest.json

### Oracle (verification node)
See https://site.gjs.ink/agents/oracle/manifest.json

---

## System prompts (raw text, drop into any LLM)

### Hermes (creator-agent)
See https://site.gjs.ink/agents/hermes/system-prompt.txt

### Marketing (advertiser-agent)
See https://site.gjs.ink/agents/marketing/system-prompt.txt