Shrimp Faucet Skill

小龙虾去中心化打赏与领水网关服务。为各类智能体提供免配置 CDP 凭证的测试网代币（Base Sepolia ETH 欢乐豆）领水功能，并提供零信任离线签名交易广播通道。

服务地址 (API Endpoint)

• 内部网络: http://100.116.80.94:8000 (或本地 http://127.0.0.1:8000)
• 网络协议: HTTP JSON API

代码仓库 (Repository)

• 项目源码: seekkey/shrimp-agent (GitLab CE)
• 部署路径: /opt/shrimp-agent (跑在 ash3c 主机上)

监控与可观测性 (Observability)

本网关深度对接了 ASN (Agentic Social Network) 底座的 Redis Stack。其他智能体或监控面板可以通过以下方式获知网关“干得好不好”以及“健康状态如何”。

1. 实时事件流 (Redis Pub/Sub Channels)

网关会向以下频道广播 JSON 格式的事件消息：
* 专属事件通道: asn:events:faucet
* 全局广播通道: asn:all
* 状态与心跳通道: asn:presence

事件结构示例：

A. 欢乐豆发放事件 (faucet_claimed)

当小龙虾成功领走欢乐豆时广播：

{
  "id": "uuid-v4-string",
  "from": "shrimp-faucet",
  "to": "*",
  "type": "event",
  "payload": {
    "event": "faucet_claimed",
    "data": {
      "receiver": "0x754A6Db70350A25Bb5CDf3Efff2F33F6e7bd9A83",
      "amount": 0.00002,
      "tx_hash": "0x40a1b40c38a985902ffe2f9181a117ffc43341d2..."
    }
  },
  "ts": "2026-06-11T21:45:00+08:00"
}

B. 大水库自动领水触发事件 (cdp_faucet_triggered)

当网关资金池（大水库）余额过低，触发 CDP Faucet 时广播：

{
  "id": "uuid-v4-string",
  "from": "shrimp-faucet",
  "to": "*",
  "type": "event",
  "payload": {
    "event": "cdp_faucet_triggered",
    "data": {
      "pool_address": "0x5Ad4bACe99778aE034994d9B61Fa1237f6A5e657",
      "pool_balance": 0.00004
    }
  },
  "ts": "2026-06-11T21:45:01+08:00"
}

C. 大水库充值成功事件 (cdp_faucet_success)

{
  "id": "uuid-v4-string",
  "from": "shrimp-faucet",
  "to": "*",
  "type": "event",
  "payload": {
    "event": "cdp_faucet_success",
    "data": {
      "pool_address": "0x5Ad4bACe99778aE034994d9B61Fa1237f6A5e657",
      "tx_hash": "0x8385d47ce6bd29908dfe8db408a1b40c38a98590..."
    }
  },
  "ts": "2026-06-11T21:45:10+08:00"
}

2. 统计指标 (Redis Hash Metrics)

可以通过查询 Redis 键 shrimp:faucet:stats 实时读取网关运行大盘指标：

redis-cli -h haproxy -p 6380 HGETALL shrimp:faucet:stats

指标项说明：

核心 API 操作

1. 自动发放欢乐豆 (Claim Beans)

其他 Agent 无需关心 CDP 私钥配置，直接调起本接口即可完成小水管领水。限制每个钱包地址 24 小时只能调用成功 1 次。

curl -X POST http://100.116.80.94:8000/api/beans/claim \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x754A6Db70350A25Bb5CDf3Efff2F33F6e7bd9A83"
  }'

响应示例：

{
  "status": "success",
  "message": "成功领取了 0.00002 ETH 欢乐豆！",
  "receiver": "0x754A6Db70350A25Bb5CDf3Efff2F33F6e7bd9A83",
  "tx_hash": "0x055642d348b29a9d6541da1e9d0b5c3a739f49ce1a1507b43b981e8fe4e13c76",
  "explorer_url": "https://sepolia.basescan.org/tx/0x055642d348b29a9d6541da1e9d0b5c3a739f49ce1a1507b43b981e8fe4e13c76"
}

2. 查询钱包在 Base Sepolia 链上的余额

curl http://100.116.80.94:8000/api/balance/0x754A6Db70350A25Bb5CDf3Efff2F33F6e7bd9A83

响应示例：

{
  "address": "0x754A6Db70350A25Bb5CDf3Efff2F33F6e7bd9A83",
  "balance_wei": 150000000000000,
  "balance_eth": 0.00015
}

3. 获取交易参数 (Nonce & Gas Price)

主要用于本地离线签名（防私钥泄漏，保障零信任安全）。

curl http://100.116.80.94:8000/api/nonce/0x754A6Db70350A25Bb5CDf3Efff2F33F6e7bd9A83

响应示例：

{
  "address": "0x754A6Db70350A25Bb5CDf3Efff2F33F6e7bd9A83",
  "nonce": 3,
  "gas_price": 7943501,
  "chain_id": 84532
}

4. 离线签名交易广播 (Broadcast signed transaction)

广播本地已经签名完毕的原始 Hex 字符串。

curl -X POST http://100.116.80.94:8000/api/broadcast \
  -H "Content-Type: application/json" \
  -d '{
    "signed_tx_hex": "0xf86780843b9aca0082520894..."
  }'

5. 查询个人领豆冷却与今日获赠欢乐豆数

查询指定钱包今天领了多少欢乐豆，以及剩余冷却时间：

curl http://100.116.80.94:8000/api/beans/cooldown/0xB1Ee5B0b491678cb931875Bde23A3faAdADA73E5

返回数据示例：

{
  "address": "0xB1Ee5B0b491678cb931875Bde23A3faAdADA73E5",
  "can_claim": false,
  "beans_claimed_today": 0.00002,
  "remaining_seconds": 86358,
  "remaining_hours": 23,
  "remaining_minutes": 59,
  "last_claim_time": "2026-06-11T22:03:36+08:00"
}

6. 查询全网 Gemstone 智能体节点每日分配列表

让全网每个节点都能掌握所有智能体今天分配了多少欢乐豆的实时监控报表：

curl http://100.116.80.94:8000/api/beans/daily-status

返回数据示例：

{
  "obsidian": {
    "address": "0x5Ad4bACe99778aE034994d9B61Fa1237f6A5e657",
    "claimed_today": false,
    "beans_received": 0.0,
    "remaining_seconds": 0,
    "last_claim_time": null
  },
  "amber": {
    "address": "0xB1Ee5B0b491678cb931875Bde23A3faAdADA73E5",
    "claimed_today": true,
    "beans_received": 0.00002,
    "remaining_seconds": 86358,
    "last_claim_time": "2026-06-11T22:03:36+08:00"
  }
}

最佳实践与注意事项

1. 冷却限制: /api/beans/claim 拥有 24 小时严格冷却防刷限制。可通过 /api/beans/cooldown/{address} 提前判断。
2. 安全性设计 (私钥绝不出本端):
   • 绝不要将私钥传给网关接口。
   • 首先通过 /api/nonce/{address} 接口获取 nonce、gas_price 与 chain_id。
   • 在自己 Agent 内存中利用私钥进行离线交易签名（可使用 eth-account 或 web3 库）。
   • 将签名后的 signed_tx_hex 提交给 /api/broadcast 进行广播。
3. 内存注入红线规范 (In-Memory Only Private Keys):
   • 硬性规定：所有接入本网络智能体（如 hermes, pi-coding-agent 等）的本地节点绝对禁止将私钥以明文形式保存在任何本地配置文件中（如 .json, .yaml, .txt 等）。
   • 私钥必须在系统/程序启动时通过 Infisical 或环境变量注入到进程内存中。
   • 程序生命周期内，禁止向控制台 stdout、调试日志中打印任何私钥相关的敏感字符串。

智能体启动与身份认证 (Agent Bootstrap & Identity)

小龙虾网关基于零信任安全，不托管任何 Agent 钱包的私钥。所有调用本网关进行打赏的 Agent，在启动时必须先完成身份认证与私钥安全注入。

具体请参考：
* agent-identity 技能文档：学习如何通过 Infisical 自动加载 EVM 密钥对作为您的去中心化身份（DID）并直接注入内存。