18 KiB
18 KiB
灵隙去中心化身份与寻址协议 v2(草案)
版本:0.2(草案) 状态:草案 层级:基础设施层 依赖:灵隙原始协议 v1 关联会议:2026-06-29 v1草案讨论会
摘要
本草案定义了灵隙协议栈中去中心化场景下的 Agent 身份认证与发现机制。v2 版本在 v1 草案基础上,根据 2026-06-29 会议决议 进行了以下核心调整:
- 签名机制:统一为非对称签名(Ed25519 默认)
- 区块链定位:从可选方案提升为身份协议的核心组成部分
- 分层规范:严格区分协议层(v1 本文件)与实现层(v1.1 的组件规范)
- 版本规划:DHT 实现按 Phase 分阶段推进
1. 协议层定义范围
本文件仅定义以下协议层内容:
- AgentID 的生成规则与格式
- 签名算法选择与验证流程
- 身份生命周期状态机
- 消息类型与载荷格式
- 发现协议的行为约束
不包含(移入实现层文档):
- Solidity / 智能合约实现代码 → 移入
v1.1 链上注册表实现规范 - DHT 协议栈实现细节 → 移入
v1.1 DHT 实现规范 - 缓存策略与具体数据结构 → 移入
v1.1 灵脉 Meridian 组件规范
2. AgentID 生成规则
2.1 ID 结构
AgentID = {namespace}:{key_hash}[:{alias}]
示例:
synapse:7hJ4x9K2mNpQ (无别名,官方命名空间)
synapse:7hJ4x9K2mNpQ:llm-agent-01 (带别名)
com.mycompany.agent:aB3dEfGhIjK (企业自定义命名空间)
did:synapse:ethereum:0x1234... (DID 格式)
| 部分 | 格式 | 必填 | 说明 |
|---|---|---|---|
| namespace | string | ✓ | 命名空间标识 |
| key_hash | base58 | ✓ | 公钥哈希的前 16 字节 |
| alias | string | - | 人类可读别名(可选,不要求全局唯一) |
2.2 命名空间治理
| 命名空间 | 所有者 | 说明 |
|---|---|---|
synapse: |
灵隙协议官方 | 官方保留前缀,推荐所有 Agent 使用 |
did:synapse: |
灵隙协议官方 | W3C DID 兼容格式,使用独立体系 |
{反向域名}: |
企业/组织 | 如 com.mycompany.agent:,无需注册 |
test: |
本地测试 | 仅用于开发测试环境 |
2.3 生成算法
func GenerateAgentID(privateKey []byte, namespace string, alias string) string {
// 1. 从私钥派生公钥(Ed25519)
publicKey := ed25519.PrivateKey(privateKey).Public()
// 2. 计算公钥哈希
hash := sha3.Sum256(publicKey)
// 3. 取前 16 字节,Base58 编码
keyHash := base58.Encode(hash[:16])
// 4. 组装完整 ID
if alias != "" {
return fmt.Sprintf("%s:%s:%s", namespace, keyHash, alias)
}
return fmt.Sprintf("%s:%s", namespace, keyHash)
}
2.4 ID 特性
| 特性 | 说明 |
|---|---|
| 唯一性 | 相同公钥 → 相同 key_hash → 相同 AgentID |
| 不可伪造 | 无法在没有私钥的情况下生成有效 AgentID |
| 可验证 | 任何人都可以用公钥验证 AgentID 真实性 |
| 不可预测 | 私钥随机生成,key_hash 不可预测 |
3. 签名机制
3.1 签名算法栈
| 层级 | 算法 | 定位 | 说明 |
|---|---|---|---|
| 协议层(默认) | Ed25519 | 标准签名 | 所有消息的默认签名算法,64 字节签名值 |
| 协议层(兼容) | ECDSA-P256 | 跨链互操作 | 与支持 P256 的链(如 Solana)互操作 |
| 协议层(兼容) | ECDSA-secp256k1 | 以太坊系兼容 | 兼容以太坊、Polygon 等链 |
| 传输层(可选) | HMAC-SHA256 | 内网优化 | 仅在可信内网链路中使用,不作为消息签名的替代 |
3.2 签名内容
签名覆盖的字段(UTF-8 编码后签名):
signature_content = sender.agent_id | receiver.agent_id | timestamp | payload
其中:
sender.agent_id:发送方完整 AgentID(字符串)receiver.agent_id:接收方完整 AgentID(字符串,广播消息可省略)timestamp:RFC3339 时间戳字符串payload:消息载荷的 JSON 序列化字符串- 分隔符
|为竖线字符(0x7C)
3.3 签名验证流程
发送方:
1. 用私钥对 signature_content 签名
2. 将签名值写入消息的 signature 字段
3. 将公钥 / 算法标识随消息一起发送
接收方:
1. 从消息中提取 sender.agent_id 和 sender.public_key
2. 用 public_key 重新计算 agent_id 的 key_hash
3. 与消息中 sender.agent_id 的 key_hash 部分比对
4. 如匹配,用公钥验证签名
5. 如验证通过,确认消息来源可信
3.4 消息签名格式
消息信封中与签名相关的字段定义:
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
signature |
string | ✓ | - | Ed25519 签名值(Base64 编码) |
signature_algorithm |
string | ✓ | Ed25519 |
签名算法标识 |
public_key |
string | ✓ | - | 发送方公钥(Base64 编码) |
3.5 算法标识枚举
| 标识值 | 算法 | 签名长度 |
|---|---|---|
Ed25519 |
Ed25519 | 64 字节 |
ECDSA-P256 |
ECDSA P-256 | 64-72 字节(DER 编码) |
ECDSA-secp256k1 |
ECDSA secp256k1 | 64-72 字节(DER 编码) |
HMAC-SHA256 |
HMAC SHA-256 | 32 字节(仅内网) |
3.6 公钥派生 AgentID 校验
接收方必须执行以下检查以验证消息来源的真实性:
1. 从 signature_algorithm 字段获取算法标识
2. 对 public_key 字段中的公钥进行哈希(算法依赖公钥类型)
3. 取哈希值前 16 字节,Base58 编码
4. 与 sender.agent_id 中的 key_hash 部分比对
5. 不一致 → 丢弃消息,返回 identity:validation_failed 错误
6. 一致 → 用 public_key 验证 signature
7. 签名无效 → 丢弃消息,返回 identity:signature_mismatch 错误
4. 发现协议
4.1 三层发现架构
查询优先级:本地缓存(快) → DHT(中) → 区块链(慢,最终源)
┌──────────────┐
│ Agent A │
│ (查询方) │
└──────┬───────┘
│
┌─────────────┼─────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────────┐
│ L1: │ │ L2: │ │ L3: │
│ 本地缓存 │ │ DHT │ │ 区块链 │
│ (内存) │ │ (网络) │ │ (链上合约) │
│ 微秒级 │ │ 毫秒级 │ │ 秒~分钟级 │
│ TTL 1min │ │ 弱一致 │ │ 最终一致性源 │
└──────────┘ └──────────┘ └──────────────┘
| 层级 | 组件 | 延迟 | 一致性 | v1.0 支持 | v1.1 支持 | v1.2 支持 |
|---|---|---|---|---|---|---|
| L1 | 本地缓存 | 微秒 | 最终(TTL) | ✓ | ✓ | ✓ |
| L2 | 广播查询 | 毫秒 | 弱 | ✓ | - | - |
| L2 | 分层 DHT | 毫秒~秒 | 最终 | - | ✓ | - |
| L2 | 完整 Kademlia | 毫秒 | 强 | - | - | ✓ |
| L3 | 区块链注册表 | 秒~分钟 | 最终一致性源 | ✓ | ✓ | ✓ |
4.2 L2 发现 — 广播查询(v1.0)
适用于小型网络,无需复杂路由:
请求(广播):
type: "identity:lookup"
target_id: "目标 AgentID"
requester_id: "查询方 AgentID"
timestamp: "2026-06-29T12:00:00Z"
响应(单播给查询方):
type: "identity:lookup_response"
target_id: "目标 AgentID"
endpoint: "http://target:8080"
public_key: "Base64 编码的公钥"
signature: "目标 Agent 对该端点的签名"
4.3 L3 发现 — 区块链注册表(v1.0+,核心层)
区块链作为最终一致性源,所有 Agent 身份以链上记录为权威来源。
4.3.1 链上记录结构(协议层定义,实现见 v1.1)
type OnChainAgentRecord struct {
AgentID string // Agent 唯一标识
Endpoint string // 当前网络地址
PublicKey []byte // 公钥
Status string // 状态:registered/active/suspended/revoked
RegisteredAt int64 // 注册时间戳
LastHeartbeat int64 // 最后心跳时间戳
}
4.3.2 查询行为
1. 查询方构造 lookup 请求(可先查本地缓存,再查 DHT)
2. 本地和 DHT 均未命中 → 查询链上注册表
3. 收到链上记录后:
a. 验证链上记录的签名(已在合约级别验证过)
b. 更新本地缓存(设置 TTL)
c. 可选:广播到 DHT 加速后续查询
4. 链上记录缺失 → 返回 Agent 不存在
4.4 发现消息类型
| 消息类型 | 方向 | 说明 | v1.0 |
|---|---|---|---|
identity:lookup |
广播 | 查询 Agent 信息 | ✓ |
identity:lookup_response |
单播 | 查询响应 | ✓ |
identity:register |
→ 链 | 注册 Agent 身份 | ✓ |
identity:heartbeat |
→ 链 | 心跳保活 | ✓ |
identity:revoke |
→ 链 | 注销身份 | ✓ |
identity:challenge |
双向 | Endpoint 验证挑战 | ✓ |
identity:challenge_response |
双向 | 挑战响应 | ✓ |
dht:ping |
DHT | 节点探测 | v1.1 |
dht:store |
DHT | 存储记录 | v1.1 |
dht:find_value |
DHT | 查找 Agent 记录 | v1.1 |
dht:find_node |
DHT | 查找附近节点 | v1.2 |
dht:notify |
DHT | 通知记录更新 | v1.2 |
5. 身份生命周期
5.1 状态机
┌──────────────┐
│ 离线 │
│ (offline) │
└──────┬───────┘
│ 链上注册成功
▼
┌──────────────┐
┌─────────│ 活跃 │─────────┐
│ │ (active) │ │
│ └──────┬───────┘ │
│ │ 心跳刷新 │ 心跳超时
│ ▼ │
│ ┌──────────────┐ │
│ │ 待验证 │ │
│ │ (pending) │ │
│ └──────┬───────┘ │
│ │ │
│ ┌─────────┴─────────┐ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ 正常 │ │ 挂起 │ │
│ │ (active) │ │(suspended)│ │
│ └────┬─────┘ └────┬─────┘ │
└──────┴──────────────────┴───────┘
│
▼
┌──────────────┐
│ 已注销 │
│ (revoked) │
└──────────────┘
5.2 状态说明
| 状态 | 说明 | 链上状态 | DHT 可发现 |
|---|---|---|---|
| offline | 初始状态,未注册 | 无 | 否 |
| active | 已注册,心跳正常 | Registered | 是 |
| pending | 已注册,Endpoint 待验证 | Registered | 否 |
| suspended | 心跳超时(3 倍间隔) | Registered | 否 |
| revoked | 主动注销 | Revoked | 否 |
5.3 关键约束
| 行为 | 约束 |
|---|---|
| 注册 | 必须同时完成链上交易和本地签名验证 |
| 心跳 | 默认间隔 1 小时,可配置 |
| 挂起 | 超过 3 次心跳间隔未更新 → 自动挂起 |
| 注销 | 链上 revoke 交易 → 状态切换为 revoked |
| Endpoint 变更 | 必须通过心跳或更新交易声明新地址 |
6. Endpoint 验证
6.1 挑战-响应协议
为防止 Endpoint 欺骗,引入双向认证:
1. Agent A 声称自己是 "synapse:abc123:agent-A"
并声称其 Endpoint 是 "http://A:8080"
2. Agent B 收到声明后:
a. 用 A 的公钥验证 AgentID 合法
b. 向 Endpoint 发送挑战(包含随机 Nonce)
c. A 必须用私钥对 Nonce 签名响应
d. 响应通过 → Endpoint 绑定确认
6.2 消息载荷
// 挑战消息(type: "identity:challenge")
type ChallengePayload struct {
ChallengeID string // 挑战唯一标识
Nonce []byte // 随机数(32 字节)
Timestamp string // 发送时间(RFC3339)
}
// 响应消息(type: "identity:challenge_response")
type ChallengeResponsePayload struct {
ChallengeID string // 对应挑战 ID
Nonce []byte // 原样返回的 Nonce
Signature []byte // 对 Nonce 的 Ed25519 签名
}
7. 安全考虑
7.1 威胁模型
| 威胁 | 防护措施 |
|---|---|
| 身份伪造 | 公钥派生 ID + 签名验证(公钥不匹配 → 丢弃) |
| Endpoint 欺骗 | 挑战-响应协议(需私钥签名响应) |
| 重放攻击 | 时间戳窗口(±5min)+ Nonce 去重 |
| 中间人攻击 | TLS + 消息级签名验证 |
| 女巫攻击 | 链上质押(可选,由实现层控制) |
| 日食攻击 | 多路径查询(L1 → L2 → L3 多条路径) |
7.2 反重放机制
type AntiReplayConfig struct {
Window time.Duration // 时间窗口(默认 5 分钟)
}
// 接收消息时必须执行:
// 1. 检查 timestamp 是否在 [now - Window, now + Window] 范围内
// 2. 检查 Nonce/CorrelationID 是否已处理过(内存去重集合)
// 3. 以上任一不通过 → 丢弃并返回 identity:replay_detected 错误
8. 版本规划
| 版本 | 身份相关功能 | 签名方案 | 发现机制 | 组件实现 |
|---|---|---|---|---|
| v1.0 | AgentID 生成、签名验证、生命周期定义 | Ed25519(默认)+ ECDSA(兼容) | 广播 + 区块链注册表(协议层定义) | 仅协议层定义 |
| v1.1 | 分层 DHT、缓存策略、链上合约实现 | 同上 + HMAC 内网优化 | 分层 DHT + 完整合约实现 | 七大组件落地 |
| v1.2 | 密钥轮换、隐私保护、跨链互操作 | 同上 + 零知识证明(可选) | 完整 Kademlia | DID 方法注册 |
9. 与现有协议的关系
9.1 与 Raw 协议的关系
本草案扩展 Raw 协议 的签名机制和 AgentEndpoint 定义:
| Raw 协议字段 | 变更 |
|---|---|
signature |
从 HMAC 变更为 Ed25519 签名 |
signature_algorithm |
默认值从 HMAC-SHA256 变更为 Ed25519 |
sender |
新增 public_key 字段(可选携带) |
9.2 与灵脉(Meridian)的关系
| 模式 | 行为 |
|---|---|
| 中心化可用(v1.0) | 灵脉作为可选中心目录,本草案的身份验证机制仍然生效 |
| 去中心化(v1.1) | 灵脉作为 DHT 引导节点(Bootstrap Node),不存储全量路由 |
| 纯 Web3(v1.2) | 完全去中心化,灵脉退化为本地路由缓存 |
9.3 与灵玺(Sigil)的关系
| 组件 | 职责边界 |
|---|---|
| 本草案(协议层) | 定义签名算法、验证流程、ID 生成规则 |
| 灵玺 Sigil(v1.1 实现层) | 密钥管理、签名/验证的 API 封装、密钥轮换逻辑 |
10. 待解决问题(Open Issues)
| 问题 | 说明 | 优先级 | 目标版本 |
|---|---|---|---|
| 密钥轮换 | 更换私钥后 AgentID 会改变,如何保持身份连续性 | 高 | v1.2 |
| 隐私保护 | 公钥哈希是否能追踪 Agent 行为 | 高 | v1.2 |
| 名称冲突 | 人类可读别名可能重复 | 中 | v1.1 |
| 链上 Gas 成本 | 频繁心跳会导致高额交易费用 | 中 | v1.1 |
| DID 方法注册 | W3C 标准 DID 方法注册流程 | 低 | v1.2 |
| 跨链互操作 | 不同链上的 Agent 如何互相发现 | 低 | v1.2 |
11. 参考资料
- RFC 8032: Ed25519 Edwards-Curve Digital Signature Algorithm
- Decentralized Identifiers (DIDs) v1.0
- Kademlia: A Peer-to-peer Information System Based on the XOR Metric
附录:本次版本变更记录
| 章节 | 变更内容 | 变更理由 |
|---|---|---|
| 整体 | 剥离 Solidity 合约实现、DHT 实现细节 | 遵循"协议层不包含实现细节"原则 |
| 第3章 | 签名机制重写:Ed25519 默认,HMAC 降级 | 会议决议一 |
| 第4章 | 区块链从"可选方案"提升为"核心组成部分" | 会议决议二 |
| 第4章 | DHT 分阶段定义(v1.0 / v1.1 / v1.2) | 会议决议三 |
| 第8章 | 新增版本规划表 | 会议决议四 |
| 全文 | solidity 合约代码、完整 DHT 实现移至 v1.1 规范 | 协议层/实现层分离 |