| 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 | 所有权限（完全访问权限） |
操作流程
- 查询权限：
structsd query structs permission [id]、permission-by-object [object-id]、permission-by-player [player-id]。
- 授予对象权限：
structsd tx structs permission-grant-on-object TX_FLAGS -- [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]、permission-revoke-on-address -- [address] [permissions]、permission-set-on-address -- [address] [permissions]。
- 公会等级权限：
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]。
- 地址管理：注册地址：
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 可能已失效。请重新查询以确认对象是否存在。
相关文档
