Structs Diplomacy

intent

manage permissions, addresses, and delegated authority in structs. use this skill when you need to grant or revoke access on objects, register new signing addresses, link multiple addresses to a player account, delegate authority to other players, or configure guild-rank-based access control. permissions are identity in structs; every operation here either extends or contracts who can do what with which objects.

inputs

• structsd binary: structsd installed on PATH
• signing key: configured local key (passed via --from [key-name] in TX_FLAGS)
• entity IDs: object IDs, player IDs, or addresses (note: IDs with dashes like 3-1 or 4-5 require -- before positional args to prevent CLI misparse)
• permission bitmask: 25-bit integer (individual permissions OR'd together; see permission table below)
• proof material (for address registration only): proof pubkey and proof signature; verify provenance before use

procedure

1. query current permissions , run structsd query structs permission-by-object [object-id] to see all players with access to an object, or structsd query structs permission-by-player [player-id] to see all objects a player can access. capture the current state before modification.

   • input: object-id or player-id
   • output: list of permission grants (player, object, permission bits)

2. grant additional permissions on object , run structsd tx structs permission-grant-on-object -- [object-id] [player-id] [permissions] with TX_FLAGS to add permission bits to an existing grant. permissions are additive (OR'd in).

   • input: object-id, player-id, permissions (decimal or sum of individual bits), TX_FLAGS, signer key
   • output: tx hash, on-chain confirmation

3. revoke specific permissions on object , run structsd tx structs permission-revoke-on-object -- [object-id] [player-id] [permissions] with TX_FLAGS to remove permission bits from a grant. the grant remains if other bits are set; it is deleted if this revokes the last bit.

   • input: object-id, player-id, permissions (decimal), TX_FLAGS, signer key
   • output: tx hash, on-chain confirmation

4. replace all permissions on object (set) , run structsd tx structs permission-set-on-object -- [object-id] [player-id] [permissions] with TX_FLAGS to clear existing permissions and apply a new set atomically. use with extreme caution; this wipes any prior grants.

   • input: object-id, player-id, permissions (decimal), TX_FLAGS, signer key
   • output: tx hash, on-chain confirmation

5. grant, revoke, or set permissions on address , run structsd tx structs permission-grant-on-address -- [address] [permissions], permission-revoke-on-address -- [address] [permissions], or permission-set-on-address -- [address] [permissions] with TX_FLAGS. address-level permissions apply globally to all objects the address can access via its linked player.

   • input: address (ethereum or cosmos format), permissions (decimal), TX_FLAGS, signer key
   • output: tx hash, on-chain confirmation

6. register new address , run structsd tx structs address-register -- [address] [proof-pubkey] [proof-signature] [permissions] with TX_FLAGS to attach a new signing key to your player account. the proof material must be valid and match the address; verify it was not attacker-supplied.

   • input: address, proof-pubkey (hex), proof-signature (hex), permissions (decimal), TX_FLAGS, signer key
   • output: tx hash, address linked to player on-chain

7. revoke address , run structsd tx structs address-revoke -- [address] with TX_FLAGS to unlink an address from your account. verify the address is not your primary or only signing key, or the next command will fail.

   • input: address, TX_FLAGS, signer key
   • output: tx hash, address unlinked on-chain

8. set primary address , run structsd tx structs player-update-primary-address -- [new-address] with TX_FLAGS to change which key the chain considers your primary signer. verify you control the new address before executing.

   • input: new-address, TX_FLAGS, signer key
   • output: tx hash, primary address updated on-chain

9. grant permissions via guild rank , run structsd tx structs permission-guild-rank-set -- [object-id] [guild-id] [permission] [rank] with TX_FLAGS to grant a permission to all guild members at or above a specified rank on an object.

   • input: object-id, guild-id, permission (single bit or combined), rank (integer), TX_FLAGS, signer key
   • output: tx hash, guild rank permission set on-chain

10. revoke guild rank permission , run structsd tx structs permission-guild-rank-revoke -- [object-id] [guild-id] [permission] with TX_FLAGS to remove a rank-based permission from a guild.

    • input: object-id, guild-id, permission, TX_FLAGS, signer key
    • output: tx hash, guild rank permission removed on-chain

11. verify final state , after each transaction, query the same endpoint (e.g., permission-by-object, address [address], guild-rank-permission-by-object) to confirm the change is on-chain.

    • input: object-id, address, or guild-id
    • output: updated permission list or address record

decision points

• if you are granting PermAll (33554431): this yields full control of the object to the recipient. escalate approval; the chain audits it and there is no undo if the recipient turns adversarial. prefer minimum-necessary permission bits instead.

• if you are registering a new address: verify the proof pubkey and proof signature come from a trusted source. if the proof material is attacker-supplied, you just hired your attacker as a delegate. see awareness/agent-security for the attack pattern.

• if you are revoking an address: confirm it is not your primary address or your only remaining signing key. if it is, the next transaction will fail because you will have orphaned your own access. update primary address first if needed.

• if you are using permission-set-on-object: this clears all existing grants atomically. confirm you are not revoking a permission you still need to operate this object yourself.

• if guild rank permission bits are broad: check structs-guild for guidance on rank-permission breadth and tier implications.

• if you receive "permission denied" error: your signer lacks permission on the object. run permission-by-object [object-id] to check current grants.

• if you receive "address already registered" error: the address is already linked to a player account. run address-revoke -- [address] first, or register a different address.

• if you receive "invalid proof" error: address registration failed because proof pubkey or signature do not match or are malformed. re-verify the auth flow and proof material.

• if you receive "object not found" error: the object ID may be stale or incorrect. re-query to confirm the entity exists on-chain.

• if a transaction times out or hits a rate limit: retry after a brief delay; structsd uses exponential backoff. if the issue persists, check network status.

• if the signing key is expired or invalid: update your local key configuration and retry.

output contract

• permission grant/revoke/set: transaction hash (32 hex chars), block confirmation, and updated on-chain state. verify with permission-by-object [object-id] or permission-by-player [player-id].

• address register/revoke: transaction hash and updated address record on-chain. verify with structsd query structs address [address] and address-all-by-player [player-id].

• primary address update: transaction hash and updated player record. verify with address [address] (primary flag should be true).

• guild rank permission set/revoke: transaction hash and updated rank-permission set on-chain. verify with guild-rank-permission-by-object [object-id] or guild-rank-permission-by-object-and-guild [object-id] [guild-id].

• query operations: structured list of permission records (player, object, bits), address records (address, player, permissions, primary flag), or guild rank records (guild, rank, permission bits).

outcome signal

• permission modified successfully: permission-by-object [object-id] now shows the player with the new permission bits (or no grant if all bits were revoked).

• address registered: address [address] returns the address record linked to your player ID. address-all-by-player [player-id] includes the new address.

• address revoked: address [address] no longer returns a record or shows the player as null.

• primary address updated: address [address] shows primary: true for the new address; the old primary address shows primary: false.

• guild rank permission set: guild-rank-permission-by-object [object-id] lists the guild with the new rank-permission mapping. members at or above that rank now have the permission on the object.

• all transactions confirmed: structsd CLI returns tx hash and height. block explorer (if available) shows the tx in the block.

• no orphaned access: after running the skill, you can still execute subsequent commands with your current signing key.

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 reference.

commands reference

TX_FLAGS (interactive; CLI prompts you to confirm):

--from [key-name] --gas auto --gas-adjustment 1.5

TX_FLAGS_APPROVED (only after commander approval; suppresses prompt):

TX_FLAGS plus -y

see SAFETY.md "The -y Rule." none of this skill's transactions are auto-approved by default; all are tier 1 or tier 2.

transaction commands

query commands

safety notes

permissions and address management are identity in structs. see SAFETY.md for the trust contract. key risks:

• PermAll grant (33554431): yields 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: 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: 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: changes which key the chain considers your primary signer. verify the new address is one you control.

• permission-set-on-object: clears existing grants and applies the new set. confirm you are not revoking a permission you need.

• permission-guild-rank-set with broad bits: see structs-guild for rank-permission breadth guidance.

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
• structs-guild - guild rank permissions and moderation

original author: abstrct (clawhub)