Permission System

Purpose: AI-readable reference for the Structs permission system. Covers address permissions, object permissions, guild rank permissions, and the message handler permission reference.

Overview

The permission system controls what actions players and their addresses can perform on game objects. It operates at three layers:

1. Address Permissions – What permission flags an address is allowed to exercise on behalf of its player
2. Object Permissions – What permission flags a specific player holds on a specific object
3. Guild Rank Permissions – What permission flags are granted to guild members based on their rank

All three layers are checked during PermissionCheck, the central authorization gate for every state-changing transaction.

Permission Flags

Permissions are bitwise flags stored as uint64 values. There are 25 individual permission bits (bits 0–24):

Composite Permission Masks

Multiple flags can be combined with bitwise OR. The system defines several useful composites:

Permission Storage

Permission IDs

Each permission entry is keyed by a permission ID string stored under the Permission/value/ KV prefix.

Object permissions use the format:

{objectId}@{playerId}

For example, 4-1@1-2 means “player 1-2’s permissions on guild 4-1”.

Address permissions use the format:

{objectTypeNumber}-{address}@0

For example, 8-cosmos1abc...@0 represents the permissions for address cosmos1abc.... The @0 suffix distinguishes address permission keys from object permission keys.

Permission Values

The stored value is a single uint64 representing the bitwise OR of all granted permission flags. For example, if a player has PermUpdate | PermDelete on an object, the stored value is 12.

Bitwise Operations

• Grant (PermissionAdd): current | newFlags – adds flags without removing existing ones
• Revoke (PermissionRemove): current &^ revokedFlags – removes only the specified flags
• Set (SetPermissions): Replaces the entire value – overwrites all flags to exactly the provided value
• Clear (ClearPermissions): Deletes the permission entry entirely (equivalent to setting to 0)

Permission Check Flow

PermissionCheck(object, activePlayer, requiredPermission) evaluates access in the following order, returning success on the first match:

1. Null check – If the object or player is nil, deny immediately.
2. Permissionless check – A check for Permissionless (0) always denies.
3. Player account check – The active player must have a valid player account on chain.
4. Address permissions – The calling address must have the required permission flags set on its address permission record. Even if a player owns an object, the specific address being used must be authorized to exercise those permissions.
5. Ownership – If the player is the owner of the object, access is granted (all permissions are implicitly held by the owner).
6. Explicit object permissions – Check if the player has the required flags in their {objectId}@{playerId} permission record. Uses HasAll semantics: all requested bits must be present.
7. Guild rank permissions – If the player belongs to a guild, check the guild rank register for the (objectId, guildId) pair. All requested permission bits must have a rank record, and the player’s guild rank must be numerically <= the most restrictive (lowest) rank across those bits.

If none of the above grant access, the request is denied with a permission error.

Administration is the exception to step 7. PermissionAdministrationCheck — used by rank assignment, entry-rank changes, permission grants/sets/revokes and ownership transfer — accepts ownership or a direct PermAdmin grant, but a PermAdmin bit held only through a rank register confers nothing. Stored rank entries containing bit 2 may remain but are inert; owners grant direct PermAdmin to officers who should administer. Operational rank bits (membership, endpoint, mint, …) remain effective, subject to the signing key’s own ceiling at step 4.

Vaults inherit the key’s token bits. Spending an owner’s vault (vault-send, player-send from a vault address, reactor-infuse, struct-generator-infuse, agreement-open, rank purchase, guild-bank-*) runs PermissionCheck on the vault owner for the relevant PermToken* bit, so a secondary address scoped without PermTokenTransfer cannot drain it. See energy.md — vaults.

UGC Permission Check (UGCPermissionCheck)

Name and profile-picture updates on player, planet, and substation objects use a dedicated permission helper that allows EITHER self-service or guild moderation:

1. Try PermUpdate (4) on the target object via the standard PermissionCheck flow above. Owners pass automatically (ownership grants every permission), and explicit object-level grants of PermUpdate also pass. This is the self-service path.
2. If that fails, look up the target object’s owner. If the owner has no guild, deny.
3. Otherwise check PermGuildUGCUpdate (16777216) on the owner’s guild object via PermissionCheck. This is the guild moderation path – it lets a guild member with that permission bit (granted directly or via a guild rank register entry on the guild) rewrite the name/pfp of any object owned by a guild-mate.

MsgGuildUpdateName and MsgGuildUpdatePfp do NOT use UGCPermissionCheck. They fall back to the standard PermissionCheck(guild, player, PermUpdate) – so renaming a guild itself requires PermUpdate (4) on that guild, granted to the owner by ownership and reachable by other members only via an explicit grant or a rank-register entry that includes bit 2.

When the actor of a UGC update is not the target object’s owner, the chain emits a ugc_moderated event so guilds can audit moderator activity. See knowledge/mechanics/ugc-moderation.md for the full philosophy and validation rules.

Object Types

Objects are identified by a string in the format {typeNumber}-{sequenceId}. The type number determines what kind of entity the object is:

Guild Rank Permission System

The guild rank permission system allows guild administrators to grant permissions on objects based on a player’s rank within the guild, rather than granting permissions to individual players. This enables scalable access control: instead of explicitly permissioning every guild member, an admin sets a rank threshold for a permission on an object, and any guild member at or above that rank automatically receives the permission.

Rank Concepts

Rank is a numeric value stored on each player’s profile (Player.GuildRank). Lower numbers represent higher privilege:

• Rank 1 is the most powerful (guild creator default)
• Rank 101 is the default assigned on join
• Rank 0 means “no rank assigned”

Guild administrators set player ranks via player-update-guild-rank.

Packed Rank Register

Guild rank permissions are stored as a packed rank register per (objectId, guildId) pair. Each register is a fixed-size array of 24 uint64 slots (192 bytes total), where slot i holds the worst-allowed rank (highest numeric rank that still grants access) for permission bit i. A slot value of 0 means no guild rank permission is set for that bit.

KV Store key: Permission/guildRank/{objectId}/{guildId} -> 192-byte register

Example register state (after setting PermUpdate | PermGuildEndpointUpdate at rank 3):

Each bit stores its rank independently. A subsequent call to set PermUpdate at rank 5 only changes slot 2 – slot 14 remains at 3.

Bitmask Decomposition

When a combined bitmask is passed to Set or Revoke, the system decomposes it into individual bits and operates on each slot independently:

• Set permission=16388, rank=3: Writes rank 3 into slot 2 (PermUpdate) and slot 14 (PermGuildEndpointUpdate). All other slots untouched.
• Revoke permission=16384: Zeros slot 14 only. Slot 2 untouched.
• Revoke permission=16388: Zeros both slot 2 and slot 14 atomically.

Guild Rank Permission Check

When a player attempts an action requiring a permission, and the check reaches the guild rank layer:

1. Load the register for (objectId, playerGuildId)
2. For each bit in the requested permission mask, check the corresponding slot
3. If any requested bit has no record (slot = 0), the guild rank check fails
4. If all requested bits have records, take the minimum (most restrictive) rank across those slots
5. If the player’s guild rank is numerically <= that minimum rank, access is granted

Example: If PermUpdate is set at rank 5 and PermDelete is set at rank 3, a check for PermUpdate | PermDelete requires the player’s rank to be <= 3 (the more restrictive threshold).

Transactions

Object Permission Transactions

These manage per-player permission flags on specific objects. The caller must already have the permission flags they are granting/revoking/setting.

permission-grant-on-object

Adds permission flags to a player’s existing permissions on an object (bitwise OR).

structsd tx structs permission-grant-on-object {objectId} {playerId} {permissions} --from {signer} --gas auto -y

Behavior: stored = stored | permissions. Existing flags are preserved; new flags are added.

permission-revoke-on-object

Removes permission flags from a player’s permissions on an object (bitwise AND NOT).

structsd tx structs permission-revoke-on-object {objectId} {playerId} {permissions} --from {signer} --gas auto -y

Behavior: stored = stored &^ permissions. Only the specified flags are removed.

permission-set-on-object

Replaces a player’s permission value on an object entirely.

structsd tx structs permission-set-on-object {objectId} {playerId} {permissions} --from {signer} --gas auto -y

Behavior: stored = permissions. This overwrites the entire value. Use with care – any flags not included in the new value will be lost.

Address Permission Transactions

These manage what permissions an address is allowed to exercise. A player may have multiple addresses; each can be independently restricted — except the primary: any set or revoke that would leave the player’s primary address below PermAll is rejected with primary_full_access_required. The primary is the full-authority recovery key; scope delegates on secondary addresses.

permission-grant-on-address

structsd tx structs permission-grant-on-address {address} {permissions} --from {signer} --gas auto -y

permission-revoke-on-address

structsd tx structs permission-revoke-on-address {address} {permissions} --from {signer} --gas auto -y

permission-set-on-address

structsd tx structs permission-set-on-address {address} {permissions} --from {signer} --gas auto -y

Guild Rank Permission Transactions

permission-guild-rank-set

Sets guild rank permissions on an object. Combined bitmasks are decomposed into individual bits before storage.

structsd tx structs permission-guild-rank-set {objectId} {guildId} {permission} {rank} --from {signer} --gas auto -y

The caller must already have the specified permission on the object.

permission-guild-rank-revoke

Revokes guild rank permissions from an object. Only the specified bits are zeroed.

structsd tx structs permission-guild-rank-revoke {objectId} {guildId} {permission} --from {signer} --gas auto -y

Player Rank Management

player-update-guild-rank

Sets a player’s guild rank. Authorized by PermissionAdministrationCheck on the guild: the caller’s signing address must carry PermAdmin (2), and the calling player must be the guild owner or hold a direct PermAdmin grant on the guild. A rank register never qualifies — holding a good rank (bought or assigned) confers configured access, not the authority to hand out free ranks. The target must already be a member of the named guild (not_member otherwise); --guild-id may be omitted by a member caller, and is required for an owner who is not a member.

structsd tx structs player-update-guild-rank --from {signer} --gas auto -y -- {playerId} {guildRank}

Queries

permission

Returns the permission record for a specific permission ID.

structsd query structs permission {permissionId}

Response:

{
  "permissionRecord": {
    "permissionId": "4-1@1-2",
    "value": "12"
  }
}

The value field is the uint64 bitmask. Decompose with bitwise AND (e.g., value & 4 != 0 means PermUpdate is granted).

permission-by-object

Returns all permission records for a given object. Paginated over a scoped index: default 100 rows, --limit clamped to 1000, pagination.total always 0 — walk next_key.

structsd query structs permission-by-object {objectId}

permission-by-player

Returns all permission records for a given player. Paginated over a scoped index (same limits as above).

structsd query structs permission-by-player {playerId}

permission-all

Returns all permission records. Paginated (default 100, max 1000, total always 0).

structsd query structs permission-all

guild-rank-permission-by-object

Returns all guild rank permission records for a given object across all guilds. Paginated over a scoped index (default 100, max 1000, total always 0).

structsd query structs guild-rank-permission-by-object {objectId}

guild-rank-permission-by-object-and-guild

Returns guild rank permission records for a specific (objectId, guildId) pair. Returns at most 24 records. No pagination needed.

structsd query structs guild-rank-permission-by-object-and-guild {objectId} {guildId}

Response format (both guild rank queries):

{
  "guild_rank_permission_records": [
    {
      "objectId": "6-1",
      "guildId": "0-1",
      "permissions": "4",
      "rank": "3"
    },
    {
      "objectId": "6-1",
      "guildId": "0-1",
      "permissions": "16384",
      "rank": "3"
    }
  ]
}

Each record represents a single permission bit. Combined bitmasks are always decomposed in query responses.

Events

EventPermission

Emitted every time a permission value changes:

{
  "permissionRecord": {
    "permissionId": "4-1@1-2",
    "value": 12
  }
}

Events are emitted for every write, even if the value didn’t change.

EventGuildRankPermission

Emitted for each guild rank permission bit that changes:

{
  "guildRankPermissionRecord": {
    "objectId": "6-1",
    "guildId": "0-1",
    "permissions": 4,
    "rank": 3
  }
}

• On set: one event per changed bit, with the new rank value
• On revoke: one event per zeroed bit, with rank = 0
• Events are only emitted for bits that actually changed

Permission Lifecycle

Player Creation

When a player is created (via a native staking delegate from a fresh funded key, or guild join-proxy), their primary address is automatically granted PermPlayerAll (all 25 bits, value 33554431) on the address permission record, and that address can never be set below PermAll afterwards (primary_full_access_required). The primary address can exercise any permission the player holds. Rotating primary (player-update-primary-address) also requires PermAll on the signing address — a limited delegate cannot point the purse at a new key.

Object Creation

When an object is created, the creating player is typically set as the owner. Owners implicitly pass all permission checks on their objects without needing explicit permission records.

Delegation Pattern

Object owners can delegate specific capabilities to other players:

# Guild owner grants Player 2 membership management and token minting
structsd tx structs permission-grant-on-object --from owner --gas auto -y -- $GUILD_ID $PLAYER_2_ID 8704
# 8704 = PermGuildMembership (512) | PermGuildTokenMint (8192)

Address Restriction Pattern

A player can register secondary addresses and restrict each one:

# Grant a secondary address only play and hash permissions
structsd tx structs permission-set-on-address cosmos1secondary... 15728641 --from primary --gas auto -y
# 15728641 = PermPlay (1) | PermHashAll (15728640)

That limited key cannot call player-update-primary-address. Infusion playerId follows the current owner of the infusion’s address. Strict address moves (address-register, primary rotation) refuse while a redelegation is in flight. address-revoke leaves Cosmos stake in place and drops the game capacity credited to that address.

Accumulative Grants vs Absolute Sets

• Grant is additive – only adds flags, never removes them
• Set is absolute – replaces the entire value (dangerous if you forget to include existing flags)
• Revoke is subtractive – only removes specified flags

Object Deletion Cleanup

When an object is deleted, all permission records for that object (both direct {objectId}@{playerId} records and guild rank registers) are cleared, as bounded work: at most PermissionCleanupBudget (256) records per block, with the remainder queued (permissionCleanupQueue in genesis) and finished in following blocks. Revocation events are emitted for each cleared entry. A permission record that drops to zero is removed rather than stored as zero bytes, and grants/sets/revokes on objects reject a target player that does not exist.

Guild Rank Permission Examples

Guild officer rank grants management access

# Admin sets: guild members rank 3 or better can update endpoint and manage membership
structsd tx structs permission-guild-rank-set --from admin --gas auto -y -- $GUILD_ID $GUILD_ID 16896 3
# 16896 = PermGuildMembership (512) | PermGuildEndpointUpdate (16384)

# Promote player to rank 2 (officer)
structsd tx structs player-update-guild-rank --from admin --gas auto -y -- $PLAYER_ID 2

# Player can now update the guild endpoint (rank 2 <= 3)
structsd tx structs guild-update-endpoint --from officer --gas auto -y -- $GUILD_ID "new.endpoint"

# Demote player to rank 5 (grunt)
structsd tx structs player-update-guild-rank --from admin --gas auto -y -- $PLAYER_ID 5
# Player can no longer update the endpoint (rank 5 > 3) -- transaction fails

Different ranks for different permissions

# Rank 3+ can connect allocations
structsd tx structs permission-guild-rank-set --from admin --gas auto -y -- $SUB_ID $GUILD_ID 2048 3

# Rank 5+ can connect to the substation
structsd tx structs permission-guild-rank-set --from admin --gas auto -y -- $SUB_ID $GUILD_ID 1024 5

# Query shows 2 records with independent ranks
structsd query structs guild-rank-permission-by-object-and-guild $SUB_ID $GUILD_ID

Partial revoke

# Set combined PermUpdate | PermDelete at rank 3
structsd tx structs permission-guild-rank-set --from admin --gas auto -y -- $GUILD_ID $GUILD_ID 12 3

# Revoke only PermUpdate (4), PermDelete (8) stays
structsd tx structs permission-guild-rank-revoke --from admin --gas auto -y -- $GUILD_ID $GUILD_ID 4

Provider access via guild rank

# Grant guild members rank 5+ the ability to open agreements on a provider
structsd tx structs permission-guild-rank-set --from admin --gas auto -y -- $PROVIDER_ID $GUILD_ID 262144 5
# 262144 = PermProviderOpen

Message Handler Permission Reference

Every msg_server_* handler that performs a permission check is listed below.

Permission Transactions

For all permission transactions, the caller must already possess the permission flags they are granting, revoking, or setting.

Player Transactions

UGC Transactions

Address Transactions

Reactor Transactions

Guild Transactions

Guild Membership Transactions

Permission checks are conditional based on guild join settings (GuildJoinBypassLevel).

Struct Transactions

CanBePlayedBy checks PermPlay on the struct’s owner (player object), not the struct itself. Each proof-of-work completion checks its own single hash bit on the owner (player): CanBuildHashedBy → PermHashBuild, CanMineHashedBy → PermHashMine, CanRefineHashedBy → PermHashRefine, CanRaidHashedBy → PermHashRaid. None of them requires all four bits. The ante handler independently requires the same single bit on the signing address. See hashing.md for the full proof-of-work mechanism.

Fleet / Planet Transactions

Substation Transactions

Allocation Transactions

Provider Transactions

Agreement Transactions

Handlers With Multiple Permission Checks

Some handlers check permissions on multiple objects. All checks must pass unless noted as fallback.

Permission Flag Usage Summary

See Also

• combat.md – Combat mechanics and attack resolution
• power.md – Power requirements
• resources.md – Resource types
• transactions.md – Free vs paid transactions, ante handler routing
• ugc-moderation.md – Decentralized name/pfp moderation philosophy and validation rules
• schemas/entities.md – Entity permission properties
• schemas/actions.md – Transaction definitions
• api/queries/permission.md – Permission query API