structs-diplomacy

name	structs-diplomacy
description	在 **Structs** 中，该模块负责处理权限管理、地址分配以及玩家之间的协调工作。适用于以下场景：授予或撤销对象的权限、注册新地址、管理多地址账户、将权限委托给其他玩家，以及设置基于地址的访问控制规则。

Diplomacy 模块的结构

重要提示：包含连字符的实体 ID（例如 3-1、4-5）会被 CLI 解析器误认为是标志（flags）。因此，在使用该模块的所有交易命令中，必须在位置参数前加上 -- 以避免这种误解。

权限系统（24 位）

权限使用 24 位的位掩码（bitmask）来表示。各个权限可以相互组合（使用逻辑 OR 运算）。有关完整的权限系统说明，请参阅 knowledge/mechanics/permissions。

权限	值	描述
PermPlay	1	基本操作权限
PermAdmin	2	管理权限（包括权限管理）
PermUpdate	4	更新对象设置
PermDelete	8	删除对象
PermTokenTransfer	16	转移令牌
PermTokenInfuse	32	将令牌注入反应堆/生成器
PermTokenMigrate	64	在对象之间迁移令牌
PermTokenDefuse	128	提取（撤销）令牌
PermGuildMembership	512	管理公会成员资格
PermSubstationConnection	1024	连接变电站
PermAllocationConnection	2048	连接分配资源
PermReactorGuildCreate	524288	在反应堆上创建公会
PermHashBuild	1048576	提交哈希工作量证明（proof-of-work）
PermHashMine	2097152	提交采矿工作量证明
PermHashRefine	4194304	提交精炼工作量证明
PermHashRaid	8388608	提交团队协作工作量证明
PermAll	16777215	所有权限（完全访问权限）

操作流程

1. 查询权限：structsd query structs permission [id]、permission-by-object [object-id]、permission-by-player [player-id]。
2. 授予对象权限：structsd tx structs permission-grant-on-object TX_FLAGS -- [object-id] [player-id] [permissions]。权限是可叠加的。
3. 撤销对象权限：structsd tx structs permission-revoke-on-object -- [object-id] [player-id] [permissions]。
4. 设置对象权限：structsd tx structs permission-set-on-object -- [object-id] [player-id] [permissions] — 会清除现有权限并应用新的权限设置。
5. 地址级别的权限：structsd tx structs permission-grant-on-address -- [address] [permissions]、permission-revoke-on-address -- [address] [permissions]、permission-set-on-address -- [address] [permissions]。
6. 公会等级权限：structsd tx structs permission-guild-rank-set TX_FLAGS -- [object-id] [guild-id] [permission] [rank] — 授予指定等级及以上的公会成员对象权限。撤销权限：structsd tx structs permission-guild-rank-revoke TX_FLAGS -- [object-id] [guild-id] [permission]。
7. 地址管理：注册地址：structsd tx structs address-register TX_FLAGS -- [address] [proof-pubkey] [proof-signature] [permissions]。撤销地址：structsd tx structs address-revoke -- [address]。更新主地址：structsd tx structs player-update-primary-address -- [new-address]。

命令参考

功能	命令
授予对象权限	structsd tx structs permission-grant-on-object -- [object-id] [player-id] [permissions]
撤销对象权限	structsd tx structs permission-revoke-on-object -- [object-id] [player-id] [permissions]
设置对象权限	structsd tx structs permission-set-on-object -- [object-id] [player-id] [permissions]
授予地址权限	structsd tx structs permission-grant-on-address -- [address] [permissions]
撤销地址权限	structsd tx structs permission-revoke-on-address -- [address] [permissions]
设置地址权限	structsd tx structs permission-set-on-address -- [address] [permissions]
设置公会等级权限	structsd tx structs permission-guild-rank-set -- [object-id] [guild-id] [permission] [rank]
撤销公会等级权限	structsd tx structs permission-guild-rank-revoke -- [object-id] [guild-id] [permission]
注册地址	structsd tx structs address-register -- [address] [proof-pubkey] [proof-signature] [permissions]
撤销地址	structsd tx structs address-revoke -- [address]
更新主地址	structsd tx structs player-update-primary-address -- [new-address]

TX_FLAGS：--from [key-name] --gas auto --gas-adjustment 1.5 -y

查询命令	命令
按 ID 查询权限	structsd query structs permission [id]
按对象查询权限	structsd query structs permission-by-object [object-id]
按玩家查询权限	structsd query structs permission-by-player [player-id]
按对象和公会查询公会等级权限	structsd query structs guild-rank-permission-by-object [object-id]
按对象和公会查询公会等级权限	structsd query structs guild-rank-permission-by-object-and-guild [object-id] [guild-id]
查询地址信息	structsd query structs address [address]
查询玩家的所有地址	structsd query structs address-all-by-player [player-id]

验证机制

• 权限验证：structsd query structs permission-by-object [object-id] — 列出具有该权限的玩家。
• 公会等级权限验证：structsd query structs guild-rank-permission-by-object [object-id] — 列出基于公会等级的权限。
• 地址验证：structsd query structs address [address] — 验证地址的注册状态和玩家关联信息。
• 玩家地址查询：structsd query structs address-all-by-player [player-id] — 获取玩家关联的所有地址。

错误处理

• 权限拒绝：签名者没有操作对象的权限。请使用 permission-by-object 命令检查当前拥有的权限。
• 地址已注册：请先使用 address-revoke 命令撤销地址关联，或将其关联到其他玩家。
• 验证失败：地址注册需要有效的公钥（proof pubkey）和签名。请检查认证流程。
• 对象未找到：对象 ID 可能已失效。请重新查询以确认对象是否存在。

相关文档

• knowledge/mechanics/permissions — 完整的权限系统说明（24 位权限值、公会等级权限）
• knowledge/entities/entity-relationships — 对象类型和 ID
• protocols/authentication — 地址注册的认证机制