Structs Diplomacy

Structs Diplomacy

Important: Entity IDs containing dashes (like 3-1, 4-5) are misinterpreted as flags by the CLI parser. All transaction commands in this skill use -- before positional arguments to prevent this.

Safety

Permissions and address management are identity in Structs. See SAFETY.md for the trust contract; in this skill:

• permission-grant-on-object with PermAll (33554431) (Tier 2 — yields authority) — "Granting another machine PermAll is yielding full control of the object. The chain audits it. There is no undo if the recipient turns adversarial." Always escalate; prefer minimum-necessary permission bits.
• address-register (Tier 2 — identity hijack risk) — "You are attaching another signing key to your player. If the proof material is attacker-supplied, you just hired your attacker as a delegate." Verify the proof's provenance. See awareness/agent-security for the full attack pattern.
• address-revoke (Tier 2) — "Verify you are not orphaning your own access. If this is the address your --from key resolves to, the next command will fail."
• player-update-primary-address (Tier 2 — identity) — "Changes which key the chain considers your primary signer." Verify the new address is one you control.
• permission-set-on-object (Tier 1, Tier 2 if it widens authority) — "Clears existing grants and applies the new set. Confirm you are not revoking a permission you need."
• permission-guild-rank-set with broad bits (Tier 2) — see structs-guild for rank-permission breadth.

Permission System (25-bit)

Permissions use a 25-bit bitmask. Individual permissions can be combined (OR'd together). See knowledge/mechanics/permissions for the full permission system reference.

Procedure

1. Query permissions — structsd query structs permission [id], permission-by-object [object-id], permission-by-player [player-id].
2. Grant on object — structsd tx structs permission-grant-on-object TX_FLAGS -- [object-id] [player-id] [permissions]. Permissions are additive.
3. Revoke on object — structsd tx structs permission-revoke-on-object -- [object-id] [player-id] [permissions].
4. Set on object — structsd tx structs permission-set-on-object -- [object-id] [player-id] [permissions] — clears existing and applies new set.
5. Address-level permissions — structsd tx structs permission-grant-on-address -- [address] [permissions], permission-revoke-on-address -- [address] [permissions], permission-set-on-address -- [address] [permissions].
6. Guild rank permissions — structsd tx structs permission-guild-rank-set TX_FLAGS -- [object-id] [guild-id] [permission] [rank] — grant permission on object to guild members at or above specified rank. Revoke: structsd tx structs permission-guild-rank-revoke TX_FLAGS -- [object-id] [guild-id] [permission].
7. Address management — Register: structsd tx structs address-register TX_FLAGS -- [address] [proof-pubkey] [proof-signature] [permissions]. Revoke: structsd tx structs address-revoke -- [address]. Update primary: structsd tx structs player-update-primary-address -- [new-address].

Commands Reference

TX_FLAGS (interactive — the CLI prompts you to confirm): --from [key-name] --gas auto --gas-adjustment 1.5

TX_FLAGS_APPROVED (only after commander approval; suppresses the prompt): TX_FLAGS plus -y. See SAFETY.md "The -y Rule." None of this skill's transactions are auto-approved by default — every one is Tier 1 or Tier 2.

Requires: structsd on PATH and a configured signing key.

Verification

• Permission: structsd query structs permission-by-object [object-id] — list players with access.
• Guild rank permission: structsd query structs guild-rank-permission-by-object [object-id] — list guild rank-based permissions.
• Address: structsd query structs address [address] — verify registration, player link.
• Player addresses: structsd query structs address-all-by-player [player-id] — all linked addresses.

Error Handling

• Permission denied: Signer lacks permission on object. Check permission-by-object for current grants.
• Address already registered: Use address-revoke first, or link to different player.
• Invalid proof: Address registration requires valid proof pubkey and signature. Verify auth flow.
• Object not found: Object ID may be stale. Re-query to confirm entity exists.

See Also

• knowledge/mechanics/permissions — Full permission system reference (25-bit values, guild rank permissions, UGC moderation hook)
• knowledge/mechanics/ugc-moderation — Decentralized name/pfp moderation philosophy and validation rules
• knowledge/mechanics/transactions — Free vs paid messages, ante handler routing
• knowledge/entities/entity-relationships — Object types and IDs
• protocols/authentication — Auth for address registration