13. 节点授权与链上治理

本章说明 OpenAgenet (OAN) 如何把链上治理事实转换为基础设施节点可以使用的授权状态。治理合约记录节点授权、授权域、能力范围和状态变化;链下信任索引器读取并保存这些事件,生成可查询的主体状态;根平台、注册服务节点和发现服务节点据此决定是否接受请求、传播资源或使用某个节点产生的治理材料。链上授权、节点授权凭证、资源登记和资源发布分别证明不同事实,不能相互替代。

本章中的“当前状态”均指某个组件基于其已同步读模型作出的判断。读模型可能暂时落后于链上事件,因此涉及新授权、暂停、恢复、撤销或高风险动作时,应同时关注事件序列、同步位置、状态有效期和证据来源。

13.1 治理目标与链上、链下边界

链上治理层和链下业务层通过“读取、验证、投影、执行”衔接,而不是共享同一个状态表。链上治理合约产生可复核的原始事件,索引器保存事件和主体状态,根平台或节点服务读取该投影并结合节点 DID、授权凭证和请求内容执行运行时判断。资源控制证明、资源包和发布状态属于资源业务链路,不能因其已存在而跳过节点治理状态检查。

13.1.1 链上治理事实

链上治理事实包括节点授权、暂停、恢复、撤销及其时间、序号和来源。链上事实是治理状态的权威来源,但链下服务可能在同步完成前保留旧读模型;响应中应区分链上位置、索引时间和服务当前采用的状态。

在当前治理合约中,治理事件由 GovernanceExecutionEvent 表达,包含动作类型、事件序号、目标节点 DID、节点类型、状态、授权域、生效时间、到期时间、策略哈希、元数据哈希以及前一事件和当前事件摘要等字段。事件的原始载荷和交易、事件序号、checkpoint 等链上位置应一并保存。这样,读侧既可以得到某节点的当前状态,也可以回溯该状态由哪一次治理执行产生。

链上事件与链下服务的关系可以概括为:链上记录证明“治理动作已经发生以及其顺序和参数”,索引器根据这些事件构造可查询状态,根平台和其他节点再按照自身策略使用该状态。索引器不能修改链上事件、重新签发治理权限或凭空补齐缺失事件;当原始事件和读模型不一致时,应以原始位置和事件摘要为核对入口。

字段 作用
节点 DID 标识被治理节点
事件类型 表示授权、暂停、恢复或撤销
授权域与能力 限定允许执行的操作
链上位置 支持顺序和复核
生效时间 区分链上发生时间和服务观察时间

13.1.2 根平台运行状态

根平台运行状态表示服务是否已读取并执行当前治理结果,包括是否接受节点提交、是否允许发布和是否允许向下游分发。它是链上治理事实的运行时投影,不得反向替代链上事实。

根平台运行时至少要区分“治理状态已知”和“本次请求已获准”两个判断。前者依赖链下信任索引器或其他治理读侧提供的状态、序列和新鲜度,后者还要结合请求节点 DID、请求动作、授权域和能力范围进行匹配。即使节点状态为 active,也只能说明它可能具备相应基础设施职责,资源控制权、资源内容、版本和发布材料仍需单独验证。

13.1.3 注册和发布状态

注册受理、根平台发布、内容分发和发现可见是不同状态。节点授权有效是执行资格条件,不等于某个资源已经通过控制权、内容和版本验证。

这些状态由不同组件产生:注册服务节点记录资源登记请求及其校验结果,根平台决定是否形成根平台可信发布事实,内容分发平台负责已批准材料的传播,发现服务节点把可见资源纳入本地索引。链上节点授权只决定基础设施节点是否有资格执行某类动作,不能替代资源提供方的签名、资源包完整性检查、发布流程或发现索引更新。

节点获授权 -> 可以提交请求
请求通过验证 -> 可以进入发布流程
根平台发布 -> 可以进入分发流程
发现节点索引 -> 资源可能对查询可见

13.1.4 发现节点读模型

发现节点使用链下信任索引器或治理同步结果过滤资源。读模型必须记录来源和同步进度;治理事件尚未同步时,应采用保守状态,不能把旧缓存直接解释为当前授权结论。

发现节点实际消费的是治理读模型,而不是在每次查询时直接扫描链上历史。读模型至少需要能够关联节点 DID、节点类型、当前状态、授权域、最后治理序号、事件摘要和更新时间;查询结果中的资源来源状态还应与资源自身的生命周期和发布证明分开表示。索引器滞后时,发现节点可以保留只读快照改善访问连续性,但不能把快照标为当前治理事实。

13.2 基础设施节点授权模型

基础设施节点以节点 DID作为治理对象,并通过节点类型区分注册服务节点、发现服务节点和 VC 颁发者。当前索引器的 SubjectState 保存节点类型、节点 DID、状态、授权域、策略哈希、元数据哈希、生效时间、到期时间、状态版本、最后更新时间、最后治理序号和最后事件摘要。节点授权凭证可以作为链下证明材料使用,但它与链上状态是两条需要组合核验的证据链:凭证说明颁发者对节点资格的声明,链上读模型说明当前治理状态和授权范围。

一个最小的状态判断可表示为:

{
  "subjectType": "discovery",
  "subjectDid": "did:oan:INDS:example",
  "status": "active",
  "authorizedDomains": ["technology.software_engineering"],
  "effectiveFromMs": 0,
  "expiresAtMs": 0,
  "lastSequence": 12
}

上例中的 DID、序号和授权域是说明性值。运行时只有在节点类型匹配、状态为有效、当前时间已达到生效时间且尚未超过到期时间时,才可把该状态作为“治理层面允许”的输入;还必须继续检查请求动作是否落在授权域和能力范围内。

13.3 授权域与能力范围

授权域回答“节点可以处理哪些业务或资源范围”,能力范围回答“节点可以执行哪些基础设施动作”。例如,一个发现服务节点可以被授权服务某个能力域,但这不等于它可以代表资源控制者修改资源 DID文档,也不等于它能够颁发注册凭证。授权域应使用规范化、可比较的域值;合约当前还对授权域的非空、数量、长度、规范顺序、重复项和通配符混用进行输入限制。

多个授权域通常表示节点服务范围的并集,具体资源是否可被处理还要经过节点状态、资源授权域和治理状态的共同判断。授权域变更应产生新的治理事件和状态版本;缩减范围后,节点不得继续以旧范围接受新请求,已经形成的历史发布事实仍应保留其来源和时间,不能被简单删除。

13.4 治理事件模型

治理合约将提案创建、投票和最终执行分开处理;索引器关注已经发出的初始化事件和治理执行事件。事件解析后,索引器同时保存原始事件记录和结构化治理事件:原始记录保留交易摘要、事件序号、checkpoint、包标识、事件类型、时间和原始 JSON,结构化记录则便于按节点 DID、治理序号、状态和授权域查询。页面上的事件名称和说明是投影字段,不能替代原始事件载荷。

治理执行事件的关键字段可按下表理解:

字段类别 典型字段 作用
身份关系 subjectDidsubjectTypetargetAddress 关联被治理节点及其链上目标
动作状态 eventTypeeventLabelsubjectStatus 表示授权、暂停、恢复、撤销或域变更
范围时间 authorizedDomainseffectiveFromMsexpiresAtMs 约束节点适用范围和有效窗口
顺序证据 sequencepreviousEventDigesteventDigest 支持事件链和状态重放核对
变更依据 proposalIdpolicyHashmetadataHash 关联治理提案和策略材料
链上来源 交易摘要、事件序号、checkpoint 指向原始链上记录和读取位置

官网 Network 页面通过公开接口 /api/public/network/governance-events 展示当前读模型中的事件列表。本次核对时接口的 generatedAt2026-09-12T02:01:05.463553057+00:00。以下表格按接口当前返回顺序记录时间、节点和页面说明;它用于帮助读者直观理解已经公开观测到的治理动作,不替代治理合约中的原始事件载荷、交易和 checkpoint。该列表会随链上治理和索引器同步状态变化:

时间(UTC) 节点 事件说明
2026-08-25 03:11:30 Test Discovery 更新测试发现节点授权域为全域。
2026-06-29 02:16:44 Test Discovery 更新测试发现节点授权域为 28 个行业/领域集合。
2026-06-29 02:15:47 Registrar 1 更新注册节点授权域为 28 个行业/领域集合。
2026-06-29 01:26:06 Test Discovery 更新测试发现节点授权域为 16 个行业/领域集合。
2026-06-29 01:25:10 Registrar 1 更新注册节点授权域为 16 个行业/领域集合。
2026-06-29 01:12:12 Test Discovery 更新测试发现节点授权域为 technology.software_engineering
2026-06-29 01:11:05 Registrar 1 更新注册节点授权域为 technology.software_engineering
2026-06-28 22:48:58 Official Discovery 更新官方发现节点授权域为全域。
2026-06-28 22:47:41 Test Discovery 更新测试发现节点授权域为全域。
2026-06-28 22:46:14 Test Registrar 更新测试注册节点授权域为全域。
2026-06-28 22:45:59 Official Registrar 更新官方注册节点授权域为全域。
2026-06-28 22:45:35 Registrar 1 更新注册节点授权域为全域。
2026-06-04 09:16:16 Official Discovery 恢复官方发现节点为 active
2026-06-04 09:15:47 Official Discovery 暂停官方发现节点授权。
2026-06-04 09:15:17 Test Discovery 恢复测试发现节点为 active
2026-06-04 09:14:48 Test Discovery 暂停测试发现节点授权。
2026-06-04 09:12:10 Test Registrar 恢复测试注册节点为 active
2026-06-04 09:11:41 Test Registrar 暂停测试注册节点授权。
2026-06-04 09:11:12 Official Registrar 恢复官方注册节点为 active
2026-06-04 09:10:42 Official Registrar 暂停官方注册节点授权。
2026-06-04 09:10:14 Registrar 1 恢复注册节点为 active
2026-06-04 09:09:46 Registrar 1 暂停注册节点授权。
2026-06-04 07:21:26 Legacy Discovery 2 撤销发现节点授权。
2026-06-04 07:19:09 Legacy Discovery 1 撤销发现节点授权。
2026-06-04 07:13:42 Legacy Registrar 3 撤销注册节点授权。
2026-06-04 07:12:51 Legacy Registrar 2 撤销注册节点授权。
2026-06-04 07:11:21 Legacy Registrar 1 撤销注册节点授权。
2026-06-04 07:06:52 Official Discovery 授权官方发现节点为 active;授权域为 genesis.openagenet.localopenagenet.local
2026-06-04 07:05:45 Test Discovery 授权测试发现节点为 active;授权域为 genesis.openagenet.localopenagenet.local
2026-06-04 07:04:36 Test Registrar 授权测试注册节点为 active;未设置显式授权域。
2026-06-04 07:03:36 Official Registrar 授权官方注册节点为 active;未设置显式授权域。
2026-06-04 07:02:43 Registrar 1 授权注册节点为 active;未设置显式授权域。
2026-06-04 06:24:16 Legacy Discovery 2 授权发现节点为 active;授权域为 genesis.openagenet.localopenagenet.local
2026-06-04 06:23:35 Legacy Discovery 1 授权发现节点为 active;授权域为 genesis.openagenet.localopenagenet.local
2026-06-04 06:21:59 Legacy Registrar 3 授权注册节点为 active;未设置显式授权域。
2026-06-04 06:21:40 Legacy Registrar 2 授权注册节点为 active;未设置显式授权域。
2026-06-04 06:19:58 Legacy Registrar 1 授权注册节点为 active;未设置显式授权域。

13.4.1 节点授权事件

授权事件使节点进入可用状态的候选集合。接收方仍需检查事件最终性、授权期限、能力范围和节点 DID 绑定,不能只依据事件名称放行。

当前动作编码中,注册服务节点授权为 21,发现服务节点授权为 31,VC 颁发者授权为 41。这些编码来自治理合约和索引器的动作映射,事件的实际生效仍由状态、时间窗口、授权域以及读模型是否已经同步共同决定。授权事件中的目标 DID 与目标地址、节点 DID 文档和运行时连接身份不一致时,应停止自动放行并进入核验流程。

13.4.2 节点暂停与恢复事件

暂停事件优先于普通业务请求,恢复事件只能在满足治理条件并被索引器按正确顺序观察后生效。服务应保留暂停和恢复的原始事件,避免只覆盖当前布尔状态。

暂停和恢复不是对历史事件的删除或覆盖。索引器应把它们作为连续治理序列保存,并根据最后一个有效序列投影当前状态。恢复后,系统只重新允许后续符合条件的新动作;暂停期间失败的请求是否重新提交,由调用方依据请求标识和业务结果决定,不能由状态恢复自动补发。

13.4.3 节点撤销事件

撤销事件表示节点不应继续执行授权范围内的新操作。已完成的资源发布和历史查询不应被无条件改写,但下游服务必须停止采用撤销节点产生的新治理结论。

撤销影响的是节点后续的治理资格,不是把该节点曾经产生的所有数据从历史中抹去。下游在处理撤销事件后,应停止接受该节点的新登记、发布、分发或治理状态更新,并对来自该节点且尚未完成验证的材料重新检查来源。已经由其他事实独立确认的历史资源记录可以保留,但必须保留其来源节点、事件位置和当时的状态。

13.4.4 事件时间、序列与来源

事件排序应优先使用链上 checkpoint、交易序号、事件序号或实现明确的复合键;事件发生时间、索引时间和页面展示时间必须分开记录。

当前事件源在分页读取后按 checkpoint、交易摘要和事件序号排序,并将读取游标与最后处理位置保存到索引器状态。emittedAtMs 表示事件载荷中的链上时间,索引器写入时间表示读侧观察和提交时间,网页生成时间只表示展示时刻。三者不能互相替换;如果事件没有可用时间,应依靠链上位置和索引时间进行排序和诊断。

13.5 节点授权、暂停、恢复与撤销

节点状态是治理序列对主体状态的当前投影。授权、暂停、恢复和撤销都通过治理事件改变主体的可用性,但具体生效还受授权域、节点能力、有效时间、到期时间、事件顺序和索引新鲜度影响。服务节点在执行动作前,应把状态判断与请求来源、请求类型和资源事实结合起来;不能把一次成功的历史请求当作当前授权仍然有效的证明。

13.5.1 授权

授权完成后,节点获得明确的授权域和能力范围。根平台在接收节点请求时应校验当前状态和范围,不能把授权事件解释为资源内容已经通过验证。

13.5.2 暂停

暂停状态下,服务可以保留只读状态查询和审计能力,但不得继续接受需要该节点授权的新提交或传播动作,除非治理策略明确允许。

13.5.3 恢复

恢复应重新确认节点身份、授权范围和治理事件顺序。恢复不自动补发暂停期间被拒绝的请求,客户端需要根据请求 ID 和状态重新确认。

13.5.4 撤销

撤销后应停止新授权范围内的动作,保留撤销原因、时间、操作者和链上位置。发现节点和分发服务需要刷新治理读模型并逐步收敛。

13.5.5 状态对注册、分发和发现的影响

节点状态 注册提交 内容分发 发现索引
active 按授权域处理 处理已批准材料 提供符合过滤条件的结果
suspended 拒绝或暂停新提交 暂停相关传播 不采用其新增治理结论
revoked 拒绝新提交 停止其授权传播 撤销或隔离其来源记录
unknown 保守拒绝高风险动作 不推进不确定状态 只读结果需带不确定性标记

状态转换的判定不应只依赖一个布尔字段。索引器在投影时还要检查事件序列是否连续、前一事件摘要是否匹配、事件是否重复以及生效和到期时间是否有效。运行时授权判断还需把当前时间与 effectiveFromMsexpiresAtMs 比较:生效时间到达前不能放行,非零到期时间到达时不再视为有效。状态未知、序列存在缺口或摘要链不一致时,应优先阻止高风险新动作,而不是猜测下一状态。

13.6 治理通知与授权状态

治理通知适合向服务节点和运维界面传达“状态发生变化”及其核验入口,但通知本身不是新的授权凭证。通知或快照至少应带节点 DID、节点类型、当前状态、授权域、最后治理序号、事件摘要、链上位置和索引器观察时间。接收方收到通知后,应根据自身的安全要求读取状态接口或原始链上证据复核,而不能仅凭通知文本执行高风险操作。

当通知传递失败、读模型落后或状态快照与原始事件不一致时,服务可以暂时保留已知状态用于低风险只读展示,但应停止推进新的高风险授权动作,并记录待恢复的同步位置。通知恢复后,应按照治理序列重新核对,而不是只处理最后一条通知。

13.7 信任索引器作为治理读侧投影

链下信任索引器是治理信息的读取和投影组件。它从配置的链端点读取目标治理事件,将原始事件、结构化事件和主体当前状态保存到本地存储,并通过 HTTP 接口为根平台和节点服务提供查询入口。索引器通过链适配和统一状态投影将区块链实现与 OAN 的节点和业务逻辑解耦,使同一套节点授权、治理读取和状态判断机制可以适配星火链网等联盟链以及以太坊等公链;具体链的事件模型、最终性、查询接口和部署适配仍需分别实现和验证,当前参考实现主要覆盖 Sui。索引器的价值在于把链上事件转化为可操作的读模型,边界在于它不拥有治理密钥、不提交治理交易,也不凭自身判断创建或撤销节点授权。

13.7.1 链上事件读取

事件读取应支持初次同步、按游标增量读取和断点恢复。读取失败时保存最后一个已确认位置,不得用空结果覆盖已有有效读模型。

索引器的事件源支持按事件类型分页查询,并把事件类型对应的 GraphQL 游标、交易摘要和事件序号组合成可恢复游标。配置中的事件类型包、可接受的发出包和同步模式需要与实际链上升级历史保持一致;否则可能出现“接口可访问但读不到目标事件”的假健康状态。首次同步用于建立完整历史,增量同步从已保存游标继续,断点恢复必须从安全位置重读并依靠幂等写入消除重复。

13.7.2 状态投影

状态投影按照事件顺序更新节点状态、授权域和能力范围,并保留必要的事件历史。重复事件应幂等处理,旧事件不得覆盖已确认的新状态。

当前存储层以治理序列作为治理事件主键,并以“节点类型 + 节点 DID”作为主体状态主键。相同序列和相同事件摘要重复到达时可以视为幂等重放;相同序列却出现不同摘要时,应报告治理事件冲突并停止静默覆盖。只有新事件序列大于主体状态最后序列时,才允许更新该主体的当前投影。

13.7.3 同步游标与延迟

游标用于恢复和观测,不等同于链上最终性。接口应区分当前已读取位置、已确认位置和服务对外采用的位置,并可计算同步延迟。

/v1/status 可提供包标识、治理对象标识、最后处理 checkpoint、事件游标、事件源、最新治理序列、最新事件摘要、序列缺口标志、摘要缺口标志和最后同步时间等运维信息。latestSequence 只能说明索引器已写入的最高治理序列,不能单独证明已经追平链上最新 checkpoint;判断延迟时还要结合事件源返回的最新位置和同步结果。

13.7.4 查询接口

查询接口应返回状态来源、链上位置、索引时间和状态原因。调用方可以用其做筛选,但高风险授权仍应根据原始事实或可验证证明复核。

索引器公开的主体查询、授权状态查询和治理事件查询分别服务于不同用途:主体查询适合列出节点状态,授权状态查询适合运行时判断,事件查询适合审计和故障追踪。查询接口返回的是索引器读模型,调用方应结合最后治理序列、事件摘要和同步状态判断其新鲜度;“authorized”类结果不能被理解为索引器替调用方验证了节点全部密钥、端点或资源行为。

当前链下信任索引器提供 GET /v1/statusGET /v1/summaryGET /v1/subjectsGET /v1/registrarsGET /v1/discoveriesGET /v1/vc-issuersGET /v1/events 等读接口。主体类接口通常返回 subjects 数组,治理事件接口返回 events 数组,状态接口返回索引状态结构;这些响应使用动态 JSON,因为索引状态和链上事件字段由索引器读模型序列化产生。POST /v1/admin/sync-once 是同步管理操作,不应与公开查询接口混用。

索引器的链访问实现使用 Sui 官方 gRPC/protobuf 类型,例如 checkpoint 和服务信息请求;这些类型属于外部 Sui RPC 协议,不是 OAN 自有的节点协作 .proto。因此,OAN 节点之间仍以共享 Rust 类型序列化的 JSON/HTTP 协议作为业务接口,区块链端点和 protobuf 只位于治理事实读取边界。

13.7.5 同步失败与恢复

同步失败时应记录错误、重试次数和最后成功游标;恢复后从安全位置重放并执行一致性检查。不能因为索引器暂时不可用就把所有节点标记为撤销。

恢复过程应至少包括读取失败原因、保留最后成功游标、重新读取受影响页、检查事件序列和摘要链、确认主体状态没有被旧事件覆盖,并记录恢复后的新游标和处理数量。索引器不可用时,依赖方应把状态标为未知或暂不可用,而不是批量写入 revoked;撤销必须来源于实际治理事件或可验证的治理状态。

13.8 根平台运行时治理状态强制执行

根平台处理请求时应按以下顺序执行:

  1. 识别请求节点 DID 并验证通信签名。
  2. 查询当前治理状态及其同步新鲜度。
  3. 检查请求动作是否属于授权域和能力范围。
  4. 再执行资源控制权、版本、哈希和内容验证。
  5. 将接受、拒绝或延迟原因写入可追踪日志。

授权有效只是进入资源验证流程的前置条件,不是资源发布结论。

其中第一步确认的是通信请求来自哪个节点,第二步确认的是该节点在治理读侧的状态和新鲜度,第三步确认的是动作、节点类型、授权域和能力范围是否匹配,第四步才进入资源 DID文档、控制签名、资源包、版本和内容校验。任一步骤的证据不足,都不能仅靠后续步骤的成功来弥补。例如资源包签名正确,只能说明资源控制证明可能有效,不能证明提交它的注册服务节点仍有当前授权资格。

13.9 发现侧治理过滤

发现节点过滤至少区分来源节点状态、资源生命周期、根平台发布状态和索引新鲜度。语义相关性或标签命中只能在这些硬条件通过后参与排序。

发现节点可以把节点授权状态用于过滤来源,但不应将授权状态直接写入资源的生命周期字段。来源节点处于暂停、撤销或未知状态时,新同步材料应被拒绝、隔离或标记为受限;已经存在且由其他证据确认的资源记录可以保留历史,但不能在缺少当前治理确认时继续作为正常新鲜候选。授权域不匹配时,资源对该发现节点不可见;这不等于资源 DID 在整个网络中不存在。

13.10 治理事件历史与公开可观测性

公开事件查询应使用稳定分页和明确排序,并同时展示链上位置与索引时间:

字段 说明
事件类型 授权、暂停、恢复或撤销
节点 DID 受影响节点
授权域/能力 事件涉及的范围
链上位置 checkpoint、交易或事件序号
observedAt 索引器观察时间
状态原因 面向运维和审计的解释

公开展示可以把 eventLabel 作为便于阅读的动作名称,但应保留原始 eventType、治理序列和来源位置。事件列表中的“最近”应按治理序列或链上位置解释,而不是按网页接口返回时间解释;分页边界也应绑定稳定排序,避免新事件到达时客户端把同一事件重复展示或漏掉。

13.11 链端点、包、对象与部署配置

索引器配置至少要同时记录网络、当前操作包、事件类型定义包、允许的事件发出包、治理公告对象、事件源模式和同步参数。OAN 当前使用 Sui Mainnet:治理公告对象为 0xb900fb0dc1ebd58fbc4d0c697d644c861578ed948e26638836e338de0d1a3b46,初始包 0x1b602d575ddf1ced075f9d2986bfe53cd7d4e59967ec26a0d949009c7b2c9d6c 定义治理事件类型,当前操作包为 0x232f984a25ceb8358290a8bae594078deca2d670a80c8d57d291d64a491d7fd5。升级过程中,0x2fd18248c0cd42f371409eb1003176dc0d5744cccfdf2e49e5224b4249a5ffb4 也曾发出治理事件,因此索引器需要接受三个包产生的事件,才能连续重建升级前后的治理序列。

[chain]
network = "sui-mainnet"
grpc_endpoint = "https://fullnode.mainnet.sui.io"
event_query_endpoint = "https://graphql.mainnet.sui.io/graphql"
package_id = "0x232f984a25ceb8358290a8bae594078deca2d670a80c8d57d291d64a491d7fd5"
event_type_package_id = "0x1b602d575ddf1ced075f9d2986bfe53cd7d4e59967ec26a0d949009c7b2c9d6c"
emitting_package_ids = [
  "0x1b602d575ddf1ced075f9d2986bfe53cd7d4e59967ec26a0d949009c7b2c9d6c",
  "0x2fd18248c0cd42f371409eb1003176dc0d5744cccfdf2e49e5224b4249a5ffb4",
  "0x232f984a25ceb8358290a8bae594078deca2d670a80c8d57d291d64a491d7fd5",
]
bulletin_object_id = "0xb900fb0dc1ebd58fbc4d0c697d644c861578ed948e26638836e338de0d1a3b46"

[sync]
event_source = "event_query"
poll_enabled = true
sync_on_start = true
poll_interval_ms = 10000
event_page_size = 50
max_pages_per_sync = 2

上述值对应当前主网事件同步配置。package_id 指向执行当前治理操作的包,event_type_package_id 保持指向最初定义事件结构的包,emitting_package_ids 覆盖升级历史中实际发出治理事件的包,bulletin_object_id 指向持续演进的治理公告对象。四者承担不同作用:只把 package_id 更新为最新包而遗漏旧事件类型包或中间发出包,会造成事件查询缺口;只配置公告对象而不核对事件源,也可能出现服务正常启动但治理序列停止增长的情况。

13.12 治理升级与迁移规则

升级应先声明合约包、事件结构、索引器和节点服务的兼容关系,再执行迁移和回放。旧事件必须可解析或有明确转换规则,转换失败时保留原始数据并阻止不确定状态覆盖有效状态。

升级还应区分“包地址变化”和“事件类型定义变化”。Sui 可升级包的当前操作包可能与事件类型定义包不同,因此事件查询配置、checkpoint 审计配置和索引器接受的发出包集合不能凭包名猜测。迁移完成后,应用一组已知治理事件核对原始事件数量、结构化事件数量、最新序列、摘要链和主体状态,确认升级没有造成重复投影或跳过事件。

13.13 治理事件顺序与最终性

事件处理可按以下状态理解:

observed -> ordered -> confirmed -> projected -> exposed

较晚到达但链上位置更早的事件应插入历史并重新计算受影响投影;已确认的更高版本状态不得被旧事件直接覆盖。

其中 observed 是事件被事件源读取,ordered 是索引器按链上位置或治理序列建立顺序,confirmed 表示已通过实现定义的完整性和位置检查,projected 表示已写入主体状态,exposed 表示查询接口可以读取该投影。某一事件已经进入公开读模型,不代表链上发生时间等于接口观察时间;当序列缺口或摘要缺口存在时,公开状态应携带不确定性,避免把不完整历史当成连续治理链。

13.14 链上事实、链下发布状态与读模型一致性

一致性不是要求链上事件、索引器、根平台和发现节点在同一时刻完成更新,而是要求每一层都能说明自己采用的事实位置和延迟。链上事件是治理事实来源,索引器提供带游标和时间的读模型,根平台据此执行发布决策,发现节点据此过滤来源和资源可见性。任何一层落后或发生冲突,都应保留已确认事实、标明差异,并在高风险动作上采取收紧策略。

13.14.1 链上最终事实

链上最终事实以可复核的事件位置和合约状态为依据,至少保留对象、动作、操作者、时间和原始事件引用。索引器接口返回只能作为读取入口,不能改变原始事实。

治理合约中的 SubjectState 保存节点当前状态、授权域、策略和元数据哈希、生效及到期时间、状态版本和更新时间;GovernanceExecutionEvent 则保存导致状态变化的事件上下文。二者结合可以回答“现在是什么状态”和“由哪次治理执行形成”,但仍应通过交易、事件和治理对象的原始链上位置进行复核。

13.14.2 根平台发布状态

根平台发布状态表示链下验证和发布流程的结果。它可以滞后于链上授权,也可能因资源验证失败而未产生;因此不能从节点已获授权推导资源已发布。

根平台可以读取节点治理状态后接收注册服务节点提交,但资源发布还要经过资源 DID文档、控制签名、资源包完整性、版本关系、内容策略和发布流程检查。发布状态应保留其资源 DID、资源版本、发布证明引用、处理时间和来源节点;它与链上节点授权状态分开保存,便于在节点治理状态变化后重新判断后续传播资格。

13.14.3 发现节点索引状态

发现索引状态表示发现节点是否已接收并索引可传播资源。它应关联资源 DID、版本、发布证明引用、索引时间和治理过滤结果。

发现节点索引状态是本地读模型的状态,不是链上资源状态。索引记录应能指出资源来自哪个发布或分发来源、使用了哪个资源版本、何时写入本地索引、采用了哪个节点治理状态以及是否因授权域或生命周期被过滤。语义索引命中、能力标签命中和治理授权命中应分别解释,不能用检索分数掩盖来源节点已经撤销或治理状态未知。

13.14.4 状态不一致与收敛

状态不一致时采用保守处理:暂停高风险动作,保留已确认事实,标记差异来源和同步延迟,并在治理读模型、根平台和发现索引完成收敛后更新对外状态。

常见不一致包括链上已有新治理序列而索引器尚未读取、索引器已读取事件但节点服务尚未刷新、根平台已完成发布而发现节点尚未索引,以及资源来源节点状态发生变化而旧资源记录仍在本地。每类不一致都应记录比较的序列、时间、来源和处理动作;恢复时按事实源重新计算,而不是用网页访问时刻或最后一次成功请求覆盖差异。

13.15 治理权威密钥管理与应急流程

应将治理密钥操作与资源提供方的本地控制私钥严格分离。应急流程至少包含:暂停高风险治理操作、轮换或隔离疑似泄露密钥、确认链上事件、重新同步索引器、通知节点并验证状态收敛。未经链上或授权流程确认的运维标记不得直接作为最终治理事实。

治理密钥用于发起或批准治理动作,资源控制私钥用于证明具体资源 DID或资源版本的控制关系,索引器和普通运维进程不应持有前者。应急处置完成后,应分别核对治理账户或对象权限、链上事件序列、索引器状态、节点运行时决策和下游发现结果;任何一个环节仍处于未知或滞后状态,都应在对外状态中保留限制性标记,而不能仅因服务进程恢复就宣布治理恢复完成。

参考来源

来源 类型 链接
oan-trust-indexer 代码仓:链上治理事件同步和链下信任状态投影 https://github.com/OpenAgenet/oan-trust-indexer
oan-root-services 代码仓:节点授权、治理状态和根平台决策 https://github.com/OpenAgenet/oan-root-services
oan-protocol-common 代码仓:授权、治理和状态共享类型 https://github.com/wolfbrother/oan-protocol-common
OAN Yellow Paper arXiv 黄皮书:治理、授权和信任边界 https://arxiv.org/abs/2606.03163
Agentic Overlay Network Architecture IETF 草案:网络节点和治理协作架构 https://datatracker.ietf.org/doc/draft-xu-agentic-overlay-network-architecture/
On this page