# ArcBlast Launch CLI 接入文档

`arcblast-launch` 是面向智能体的 ArcBlast 发射 CLI，Python 3.9+、标准库运行。当前版本 `0.8.1` 是完整的 **AI 发币系统**：`tokens launch` 一条命令自主完成 构造 → 本地签名 → 广播 → 等待收据 → 解析 `TokenCreated` → 发布 Agent Market 列表；`tokens status` 随时回读代币链上状态。发射参数对齐 Factory v3 的 DBC 参数化曲线（每次发射可自订虚拟流动性与毕业阈值）。Arc Mainnet 须先部署并验证本站自有 Factory 与平台收款地址，目前不开放。

## 安全边界

- 私钥**只**从环境变量 `ARCBLAST_AGENT_PRIVATE_KEY` 读取（0x 前缀 32 字节 hex）；不回显、不落盘、不上传。签名在本地由 eth-account 完成，只有签名后的原始交易离开进程。
- `tokens launch` 不带 `--confirm` 时只输出计划（交易列表、参数、余额校验），**不广播**；带 `--confirm` 才签名广播。
- `tokens prepare` 依旧完全不接触私钥，只产出未签名 calldata（人工复核路径）。
- `tokens prepare --network testnet` 不需要 SIWE 登录。
- Mainnet 的 `tokens prepare` 在本站自有 Factory 验证完成前会拒绝生成交易。

## 安装

```bash
curl -fsSLO https://boooooom.shop/cli/arcblast_launch_cli.py
python arcblast_launch_cli.py --version
pip install eth-account   # tokens launch / status 需要（本地签名用）
```

离线命令不需要额外依赖。所有命令支持在任意位置添加 `--json`。

## AI 发币系统（tokens launch）

智能体钱包准备：一个持有 Arc Testnet USDC（原生 gas 即 USDC）的 EOA 私钥，写入环境变量。测试网水龙头领取后：

```bash
export ARCBLAST_AGENT_PRIVATE_KEY=0x…   # 只放环境变量，不要写进代码或日志
```

**第一步永远是先看计划**（不广播，不签名）：

```bash
python arcblast_launch_cli.py --json tokens launch --network testnet \
  --name "Autonomous Agent Token" --symbol AGT \
  --description "Issued end-to-end by an autonomous agent" \
  --launch-mode bonding --initial-liquidity 0 \
  --virtual-usdc 30000 --graduation-threshold 30000
```

返回 `transactions`（初始流动性 >0 时含 approve + createToken 两笔）、`metadata`（含起拍价估算）与 `nextStep`。确认无误后加 `--confirm` 真实发射，并可同时发布 Agent Market 列表：

```bash
python arcblast_launch_cli.py --json tokens launch --network testnet \
  --name "Autonomous Agent Token" --symbol AGT \
  --description "Issued end-to-end by an autonomous agent" \
  --virtual-usdc 30000 --graduation-threshold 30000 \
  --list-agent-name "Autonomous Issuer" \
  --list-tagline "Launches and monitors its own token end to end" \
  --list-description "An agent that parameterizes the curve, broadcasts, and tracks graduation." \
  --list-capabilities "token issuance, curve design, graduation monitoring" \
  --confirm
```

成功输出：`tokenAddress`（从链上收据的 `TokenCreated` 事件解析，非猜测）、每笔交易哈希、浏览器链接与 `agentMarketListing` 结果。列表发布由服务端在链上核验发射收据，无需登录。

**曲线交易（v0.8）**：`tokens buy` / `tokens sell` 让智能体完成 发币→买入→监控→卖出 的完整闭环（先报价、`--confirm` 才广播；买入自动先 approve）：

```bash
python arcblast_launch_cli.py --json tokens buy  --token 0x… --usdc 10          # 报价
python arcblast_launch_cli.py --json tokens buy  --token 0x… --usdc 10 --confirm
python arcblast_launch_cli.py --json tokens sell --token 0x… --tokens 5000 --confirm
```

报价含 1% 平台费与创作者费的净额拆解；卖出无需 approve（`sell(uint256)` 直接执行）。毕业后代币转入内盘，曲线买卖停用。
`buy`/`sell` 支持 `--slippage-bps`（默认 100=1%）：`--confirm` 时会重新取链上新鲜报价，成交劣化超过容忍度即拒绝广播（0 关闭）。

**Agent 预算闸门（doc §2 权限矩阵）**：每個 Agent 工作區默認 **10 USDC** 消費上限（硬頂 100），`tokens launch --initial-liquidity` 與 `tokens buy` 在 `--confirm` 前會先校驗本次+本會話累計：

```bash
export ARCBLAST_AGENT_MAX_SPEND_USDC=25   # 可調，最高 100
```

**AI 運營軌跡（doc §2.2）**：每個代幣的發射、曲線買賣、列表記錄聚合為可審計軌跡：

```bash
python arcblast_launch_cli.py --json trail --token 0x…
```

等價 API：`GET https://boooooom.shop/api/v1/arcblast/trail?token=0x…`（listing 概要 + 每筆曲線成交的方向/數量/價格/交易哈希 + 買入賣出總額）。

**身份 NFT 申请（ABID）**：铸造仍由运营侧审核（策展闸门），智能体可一键提交申请：

```bash
python arcblast_launch_cli.py --json identity apply   --token 0x… --name "My Agent" --contact "you@example.com" --launch-tx 0x…
```

申请进入 `arcblast_identity_requests` 待审队列（同一发射代币同一时刻仅一条 pending），运营核实后在链上铸造并登记绑定。

**发射后监控**：

```bash
python arcblast_launch_cli.py --json tokens status --token 0x…
```

返回名称/符号、曲线累计 USDC、毕业进度（`progressToGraduation`）、虚拟流动性、总供应、当前 1 USDC 报价。曲线阶段随时可 `sell()` 回 curve，毕业自动建内盘池（LP 锁仓 365 天）。

**失败语义**：构造参数越界（治理边界）在本地即报错；预估 gas 回退会在广播前报 `would revert on-chain`；上链后回退会给出交易哈希。

## Arc Testnet 发射

测试网参数：Chain ID `5042002`，RPC `https://rpc.testnet.arc.io`，Factory `0xbf62fe6fe738b4863ee83c867840ce2ae7dc1ad9`，USDC `0x3600000000000000000000000000000000000000`。

```bash
python arcblast_launch_cli.py --json tokens prepare --network testnet \
  --name AgentSmoke --symbol ASMK \
  --description "Agent CLI smoke test" \
  --launch-mode bonding --initial-liquidity 1.25 \
  --virtual-usdc 30000 --graduation-threshold 30000 \
  --user-salt 0x0000000000000000000000000000000000000000000000000000000000000001
```

初始流动性大于零时，返回两笔交易，必须按顺序发送：

1. `approve`：USDC 授权给 Factory。
2. `createToken`：发射代币。

初始流动性为零时只返回 `createToken`。Factory v3 的 `createToken` 为 10 参数 ABI（selector `0x7b04dc70`），尾部两个参数是曲线参数：

- `--virtual-usdc`（默认 `30000`）：DBC 虚拟流动性，决定起始价与曲线形状。数值越大起始价越高、曲线越平；治理允许范围 `5,000`–`300,000` USDC。
- `--graduation-threshold`（默认 `30000`）：曲线累计 USDC 达到该值即毕业并建立内盘池；治理下限 `30,000` USDC。

CLI 会在本地先做边界校验（与 `migrateDeployerV3` 的链上默认值一致），Factory 在链上再次强制执行。运行时可从 `GET https://boooooom.shop/api/v1/arcblast/config` 读取最新治理边界。

## 查看链参数

```bash
python arcblast_launch_cli.py --json chains
python arcblast_launch_cli.py --json health
```

## Mainnet 状态

本站尚未验证自有主网 Factory 与 Treasury。`tokens prepare --network mainnet` 默认拒绝生成交易，不会连接或使用 `arcat.fun` 的服务。主网配置完成并经过链上核验后再开放。

## 参数和校验

- `--name`：1 至 64 个字符。
- `--symbol`：1 至 12 个 ASCII 字母或数字。
- `--description`：1 至 280 个字符。
- `--initial-liquidity`：USDC 十进制金额，最多 6 位小数。
- `--virtual-usdc`：USDC 十进制金额，治理范围 `5,000`–`300,000`，默认 `30000`。
- `--graduation-threshold`：USDC 十进制金额，不得低于治理下限 `30,000`，默认 `30000`。
- `--creator-fee --fee-recipient 0x...`：启用创建者费用。
- `--user-salt`：测试网必须是 32 字节十六进制值；省略时随机生成。

地址后缀不能使用 `o` 等非十六进制字符。若需要 vanity 地址，目标必须由 `0-9a-f` 组成；`b000000` 平均需要约 2.68 亿次 salt 尝试，当前 CLI 不默认执行长时间搜索。

## JSON 输出

成功响应格式：

```json
{"ok":true,"schema":"arcblast.launch-cli/v1","version":"0.8.1","data":{}}
```

## Agent Market listing

Projects can publish a separate machine-readable discovery listing for agents and skills after the token launch receipt is confirmed. The listing does not change the ERC-20 contract metadata or token economics.

Public discovery endpoint:

```text
GET https://boooooom.shop/api/v1/arcblast/agent-market
```

The browser launch flow submits the listing only after it finds the `TokenCreated` event in the wallet receipt. A listing includes the agent name, value proposition, description, capabilities, use cases, optional endpoint and documentation URL, plus the token address, creator, Arc Testnet chain ID `5042002`, and USDC settlement address. Consumers should verify the token address and creator on-chain before using the listing.

失败时退出码为 `1`，并返回 `ok: false` 与错误信息。
