aether

Project Aether — M2M 推理清算所（MVP）

AI Agent 在连续双向竞价现货市场中买卖推理单位（指定模型的令牌，例如 llama-3.1-70b-instruct）。**凭据绝不会易手。**买方持有托管的配额，清算所通过一次性、绑定请求正文的交付 JWT，将每个请求代理到卖方自己的无状态端点。卖方按代理流式传输的确切令牌数获得纳美元报酬。

**准备投入生产：**请参阅 docs/PRODUCTION.md，了解线上平台的运作方式、资金流向、上线检查清单和路线图。

Agent 可通过任何兼容 OpenAI 的客户端连接：

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<client_id>.<client_secret>")  # api_key from POST /v1/agents
client.chat.completions.create(
    model="llama-3.1-70b-instruct",
    messages=[{"role": "user", "content": "hi"}],
    max_tokens=64,
    extra_body={"max_price_usd_per_mtok": "0.50"},
)

每次调用都会按价格上限在市场上买入所缺的容量、将其托管、流式传输答案，并按交付的令牌数结算。

范围说明。 将密钥隐藏在代理后面，并不意味着可以转售专有 API（OpenAI、Anthropic、Google 等）。如果卖方的端点只是转发到其自己的供应商密钥，这仍属于转售访问权限，而这些提供商的条款通常会禁止此类行为。此 MVP 面向的模式是：卖方运行自己有权提供服务的模型（在自有或租用的 GPU 上运行开放权重模型），或明确允许转售的提供商。

架构

            OAuth2 client_credentials                    ┌──────────────────────────────┐
 Buyer ──── POST /oauth/token ──► JWT (buy_inference) ──►│  FastAPI clearinghouse       │
 agent      POST /v1/orders  (bid, escrowed first) ─────►│  auth.py      RS256 JWT/JWKS │
            POST /v1/inference (SSE) ◄──── stream ──────│  exchange.py  clearing+escrow│
                                                         │  proxy_router.py (asyncio)   │
 Seller ─── POST /v1/orders (ask) ──────────────────────►│                              │
 agent  ◄── POST /v1/generate + delivery JWT ───────────│                              │
   (verifies via /.well-known/jwks.json)                 └──────┬──────────────┬────────┘
                                                                │              │
                          Redis: Lua matching engine (ZSET book),│              │ PostgreSQL: agents, orders,
                          match Stream (durable fill log),        │              │ trades/allocations, double-entry
                          Pub/Sub market data, job checkpoints   ▼              ▼ ledger (source of truth)

订单 → 配额 → 交付 → 结算

1. **撮合前托管。**买入报价在进入订单簿前，会从 available 锁定 price_cap × qty 到 escrow。
2. **撮合。**一个 Lua 脚本按价格优先、再按时间（FIFO）原子撮合，并将结果追加到 Redis Stream。成交按做市方价格执行，价格优惠会立即退还。
3. **恰好应用一次。**每个 Stream 事件只应用到 PostgreSQL 一次，并由 applied_match_events 保证。请求会内联应用自身事件；消费者组工作线程会应用崩溃后遗留的事件。PostgreSQL 是权威数据源，启动时会据此重建 Redis 订单簿。
4. 路由。/v1/inference 会在价格最低的托管配额上预留 max_tokens（行锁可防止并发请求超额使用），否则返回 402。随后签发有效期为 60 秒的交付 JWT（aud=aether-seller:<id>、jti 一次性使用、绑定 body_sha256），并将卖方的 SSE 响应流式传回。
5. **检查点／重试。**交付的令牌会批量写入 Redis Stream。如果卖方断开连接、超时、返回 5xx，或未带 done 标记就结束（现货抢占），代理会通过 resume_from 和 prefix 在同一配额上恢复。达到 max_attempts_per_allocation 后，会切换到另一个托管配额。买方看到的是一条连续、无间断的数据流。
6. **结算。**买方托管资金会按确切交付的令牌数转入卖方的 available 账户和 house:fees 账户。预留金额的剩余部分会被释放。即使买方断开连接，结算仍会执行。如果代理进程终止，清理任务会在心跳超时后，根据检查点结算孤立任务。

**代理选型：Python asyncio。**路由器受 I/O 限制：它会中继数据块，并在每个请求中执行少量短事务。单个事件循环配合池化的 httpx.AsyncClient，即可多路复用数千条数据流，并共享账本代码，无需 RPC 跳转。当基于 tokenizer 的计量等逐数据块 CPU 工作成为主要开销时，采用 Go 数据平面才更有价值。

数据模型（app/models.py）

所有金额均为整数纳美元（1e-9）。价格为每个 token 的整数纳美元：每 1M 个 token 收费 $0.35 = 350。因此最小价格刻度为每 1M 个 token $0.001，且每笔费用都是精确的整数乘积，无需四舍五入。费用按每笔分配累计计算（floor(gross_total × bps / 10⁴)），因此在多次微额结算中不会产生偏差。

表	用途 / 关键列
agents	client_id、client_secret_hash（scrypt）、allowed_scopes、endpoint_url、balance_available_nanos、balance_escrow_nanos、token_version（递增以撤销所有 JWT）
orders	side 为 bid/ask，order_type 为 limit/market，time_in_force 为 gtc/ioc，price_npt、quantity/filled/cancelled_tokens、escrow_nanos（买单：price × open）、seq（时间优先级）、expires_at
trades	一笔成交；对买方而言，也是一笔分配：tokens_total/used/reserved、escrow_nanos（= price × unused）、gross_settled_nanos、fee_nanos、status 为 active/exhausted/released/expired
trade_ledger	只追加的复式记账日志：每个 tx_id 的总和为 0；账户包括 agent:<id>:available、agent:<id>:escrow、house:fees、house:sandbox_mint
applied_match_events	用于匹配流事件的恰好一次处理保护机制
inference_jobs	每个请求的状态、token 数、费用、尝试次数、故障转移次数、每个卖家的分段信息

GET /v1/audit（sandbox）会检查以下不变量：账本总和为零、每笔交易均平衡、缓存余额与账本一致，且每个 Agent 的托管金额等于其未成交买单的托管金额加上分配的托管金额。

JWT 载荷（RS256，kid = RFC 7638 指纹，公钥位于 /.well-known/jwks.json）

访问令牌（来自 POST /oauth/token，grant_type=client_credentials，使用 HTTP Basic 或表单进行身份验证）：

{
  "iss": "http://clearinghouse:8000", "sub": "agt_7bf7…", "aud": "aether-clearinghouse",
  "iat": 1790508813, "nbf": 1790508813, "exp": 1790509713, "jti": "0dbd3f97…",
  "client_id": "agt_cli_f17d…", "scope": "buy_inference", "tv": 0, "typ": "access"
}

作用域：buy_inference（出价、使用、释放分配）和 sell_compute（挂出卖单、注册端点）。可通过 jti 撤销令牌（POST /oauth/revoke），也可通过 tv 一次性撤销某个 Agent 的所有令牌。

交付令牌（代理 → 卖家，每次卖家调用使用一个）：

{
  "iss": "…", "sub": "job_0d41…", "aud": "aether-seller:agt_2edb…", "exp": "iat + 60",
  "jti": "…", "typ": "delivery", "trade_id": "trd_…", "instrument": "llama-3.1-70b-instruct",
  "max_tokens": 150, "resume_from": 25, "body_sha256": "<sha256 of the exact request body>"
}

文件

路径	内容
app/main.py	FastAPI 应用、CORS、Redis 连接池、httpx 连接池、启动恢复（排空流 → 对账订单簿）、后台工作进程
app/auth.py	OAuth2 客户端凭据授权、scrypt 密钥、JWT 签发/验证、作用域依赖项、撤销、JWKS、交付令牌
app/matching_engine.py	Redis Lua 连续双向拍卖（价格/时间 FIFO、防止自成交、过期处理、持久化撮合流）
app/exchange.py	订单录入、恰好一次的成交应用、托管资金划转、分配预留、作业结算、流工作进程、对账
app/proxy_router.py	托管门控、交付令牌铸造、异步 SSE 中继、检查点/恢复/故障转移、结算、孤立任务恢复
app/ledger.py	带行锁余额检查的复式记账
app/api.py	Agent 注册表、水龙头、订单、订单簿、市场数据 SSE、分配、账本、审计
app/openai_compat.py	兼容 OpenAI 的 /v1/chat/completions（流式传输 + 用量）、/v1/models、/v1/quote、自动购买
app/services.py	Agent 服务市场：列表、发现、按调用托管执行、退款、评分
app/crypto_payments.py	USDC 支付通道：签名关联钱包、链上存款监控、已验证付款、偿付能力
app/payments.py	Stripe Checkout 存款（已签名、幂等 Webhook）、Stripe Connect 入驻和付款
app/seller_gateway.py	生产级卖家：为你的 vLLM/SGLang/TGI 服务提供前置代理、保持卖单挂单、验证交付 JWT、从前缀恢复
app/keygen.py	为 AETHER_JWT_PRIVATE_KEY_PEM 生成 RS256 密钥
render.yaml, .github/workflows/ci.yml	一键部署到 Render（应用、Postgres、Key Value）；CI 运行 lint、测试和 Docker 端到端测试
app/seller_agent_sim.py	模拟卖家：自行注册、列出容量、验证交付 JWT、提供 SSE、模拟现货抢占
app/buyer_agent_sim.py	模拟买家：完整的 M2M 端到端协商
Dockerfile, docker-compose.yml	应用镜像，以及 Postgres 16、Redis 7（AOF）、清算所、seller-a（便宜、不稳定）、seller-b（可靠）、buyer
tests/	50 个异步测试：撮合、托管、身份验证、API 密钥、速率限制、恢复、故障转移、展期、超额扣款竞态、孤立任务恢复、OpenAI 格式、Stripe 和加密货币存款与付款、卖家网关

运行

docker compose up -d --build --wait      # postgres, redis, clearinghouse, seller-a, seller-b
docker compose run --rm --no-deps buyer  # the buyer agent's end-to-end simulation
docker compose logs -f clearinghouse seller-a
open http://localhost:8000/docs          # OpenAPI UI
docker compose down -v                   # tear down, wiping volumes

本地开发和测试（需要将 redis-server 添加到 PATH；测试使用 SQLite 和临时 Redis）：

python -m venv .venv && . .venv/bin/activate && pip install -r requirements-dev.txt
pytest -q

每次克隆后安装一次密钥扫描 pre-commit 钩子（需要将 gitleaks 添加到 PATH，例如 sudo apt-get install gitleaks）：

git config core.hooksPath scripts/git-hooks

CI 还会在每次推送和 PR 时运行 gitleaks（.github/workflows/gitleaks.yml），作为第二层防护。在此仓库中，切勿运行 git add -A / git add .——请明确暂存具体路径，以免运行时状态（.env、data/）随提交一并提交。

预期输出（来自实际运行的 docker compose run --rm --no-deps buyer，内容已删节）

== 2. The M2M boundary holds =============================================
sell attempt with a buy_inference token   -> HTTP 403 insufficient_scope (Bearer realm="aether", error="insufficient_scope", scope="sell_compute")
inference before escrowing any funds      -> HTTP 402 no_escrowed_allocation
tampered JWT signature                    -> HTTP 401 invalid_token

== 4. Order book for llama-3.1-70b-instruct ==============================
side   $/1M tokens     tokens  orders
ASK            0.4       5000       1
ASK           0.35        400       1

== 5. Market BID 1000 tokens, protection cap $0.50/1M (escrow before matching)
order ord_6645… status=filled filled=1000/1000 cancelled_remainder=0
  FILL    400 tokens @ $0.35/1M from seller agt_9b4c3e5d7982… -> allocation trd_1790507830419_0_0… escrow=$0.000140000
  FILL    600 tokens @ $0.4/1M from seller agt_b242131598ab… -> allocation trd_1790507830419_0_1… escrow=$0.000240000
wallet: available=$0.999620000 escrow=$0.000380000 (price improvement vs cap already refunded)

== 6. 3 concurrent inference streams through the proxy router ============
[job1] routed job=job_83cb… -> seller=agt_9b4c3e5d7982… trade=trd_1790507830419_0_0… @ $0.35/1M reserved=150
[job3] routed job=job_1d8c… -> seller=agt_b242131598ab… trade=trd_1790507830419_0_1… @ $0.4/1M reserved=150
[job1] interrupted: stream ended without completion marker (instance preempted)
[job1] RESUME on seller=agt_9b4c3e5d7982… from checkpoint token #25
[job1] interrupted: stream ended without completion marker (instance preempted)
[job1] FAILOVER to seller=agt_b242131598ab… from checkpoint token #50
[job1] done: 150 tokens, cost $0.000057500, attempts=3, failovers=1, finish=length
[job1]   segment seller=agt_9b4c3e5d7982… trade=trd_1790507830419_0_0… tokens=50
[job1]   segment seller=agt_b242131598ab… trade=trd_1790507830419_0_1… tokens=100

== 8. Micro-transaction ledger (buyer, newest first) =====================
  escrow_release  available    $0.000105000  allocation released by buyer
  settlement      escrow      $-0.000040000  job_798b…: 100 tokens
  settlement      escrow      $-0.000017500  job_798b…: 50 tokens
  escrow_release  available    $0.000060000  price improvement
final wallet: available=$0.999825000 escrow=$0.000000000

== 9. Clearinghouse audit (double-entry invariants) ======================
{ "ledger_sum_nanos": 0, "unbalanced_transactions": [], "cached_balance_mismatches": [],
  "escrow_backing_mismatches": [], "house_fees_usd": "$0.000001750", "ok": true }

SIMULATION PASSED

同一次运行的清算所日志：

aether.exchange: FILL llama-3.1-70b-instruct 400 tokens @ $0.35/1M buyer=agt_7bf7… seller=agt_2edb… (taker=bid)
aether.proxy: ROUTE job=job_0d41… buyer=agt_7bf7… -> seller=agt_2edb… trade=trd_…_0_0 reserved=150
aether.proxy: job=job_0d41… seller=agt_2edb… interrupted at token 25 (attempt 1): stream ended without completion marker (instance preempted)
aether.proxy: job=job_0d41… seller=agt_2edb… interrupted at token 50 (attempt 2): stream ended without completion marker (instance preempted)
aether.proxy: SETTLED job=job_0d41… tokens=150 cost=$0.000057500 segments=[('trd_…_0_0', 50), ('trd_…_0_1', 100)] status=completed

API 摘要

方法和路径	作用域	说明
POST /v1/agents	—（沙箱）/ X-Admin-Token	返回 client_id 和 client_secret（密钥仅显示一次）
POST /oauth/token、POST /oauth/revoke	客户端凭据 / bearer	RFC 6749 §4.4、RFC 7009 子集
PUT /v1/agents/me/endpoint	sell_compute	卖家的 webhook。AETHER_ALLOW_PRIVATE_SELLER_URLS=false 会强制使用 https 和公共 IP
POST /v1/orders、GET/DELETE /v1/orders/{id}	bid→buy_inference，ask→sell_compute	price_usd_per_mtok、quantity_tokens、order_type、time_in_force、ttl_seconds
GET /v1/book/{instrument}、GET /v1/market/{instrument}/stream	公开	深度；通过 SSE（Redis Pub/Sub）推送成交记录
POST /v1/inference	buy_inference	SSE 事件：meta、令牌 data、resume、done / error
GET /v1/jobs/{id}	buy_inference	状态及已保存检查点的文本（如果买家的连接中断，可恢复输出）
GET /v1/trades、POST /v1/trades/{id}/release	任意 / buy_inference	资金分配；释放会退还未使用的托管资金
POST /v1/chat/completions、GET /v1/models、GET /v1/quote/{model}	buy_inference / 公开	兼容 OpenAI；扩展支持 max_price_usd_per_mtok 和 auto_buy
POST /v1/agents/me/rotate-secret	任意	新密钥；旧密钥、API 密钥和 JWT 将失效
GET /v1/billing/crypto、GET …/crypto/link-challenge、POST …/crypto/wallets、GET …/crypto/deposits、POST/GET …/crypto/withdrawals	任意	从通过签名关联的钱包存入 USDC；提现至本人关联的钱包
GET /v1/admin/crypto/payouts、POST …/payouts/{id}/paid / cancel、GET /v1/admin/crypto/solvency	X-Admin-Token	提现队列（已通过链上验证）、资金库偿付能力
GET /v1/services、POST /v1/services、PATCH /v1/services/{id}、POST /v1/services/{id}/invoke、POST /v1/services/calls/{id}/rating	公开 / sell_compute / buy_inference	Agent 服务市场：Agent 按次出售已完成的任务；使用托管资金，失败时退款，收取 10% 费用
POST /v1/feedback、GET /v1/admin/feedback、GET /.well-known/agent.json	开放 / X-Admin-Token / 公开	来自 Agent 的反馈；机器可读的 Agent 卡片
POST /v1/billing/deposits、POST /v1/billing/stripe/webhook	任意 / Stripe 签名	通过 Stripe Checkout 使用银行卡充值
POST /v1/billing/connect/onboard、POST/GET /v1/billing/withdrawals	sell_compute	Stripe Connect KYC 和提现
GET /v1/ledger	任意	Agent 的账本条目
GET /v1/audit、GET /v1/admin/stats	沙箱或 X-Admin-Token	不变量；收入、交易量和活动情况
POST /v1/sandbox/faucet	仅限沙箱	测试资金

实际资金交易前的已知缺口

完整列表及优先级见 docs/PRODUCTION.md。 最重要的事项：

• 计量信任。 代理会统计 SSE 令牌事件，因此不诚实的卖家可以将输出拆分成更多“令牌”。 计费应使用对应工具的分词器。
• 提示词令牌目前尚未计费，也没有任何机制验证卖家实际运行的是哪个模型。
• 运维。 架构通过 create_all 创建（首次架构变更前需要使用 Alembic 迁移）， 且 Lua 脚本假设只有一个 Redis 主节点。
• 监管。 实际资金通过平台的 Stripe Connect 流转，但持有余额并向卖家付款 仍需根据你所在司法辖区进行法律审查。