GRASS Event Schemas

Version: 1.1.0 Category: streaming

Complete catalog of GRASS event payload schemas for AI agents.

Base Event

All GRASS events share a common base structure.

Field Type Required Description
subject string Yes NATS subject for this event. Pattern: ^structs\..+$
category string Yes Event category (see event-types.yaml)
id string Yes Entity identifier
updated_at string (date-time) Yes ISO 8601 timestamp of update

Event Definitions

PlayerConsensusEvent

Extends BaseEvent. Category: player_consensus

Data Fields:

Field Type Description
id string Player ID
guildId string Guild ID
primaryAddress string Player primary address
username string Player display name (on structs.player; from chain UGC)
pfp string Profile picture URI (on structs.player; from chain UGC)

Fires when sync-state commits an insert or update to structs.player, including UGC changes from MsgPlayerUpdateName / MsgPlayerUpdatePfp or signup proxy.

PlayerMetaEvent (legacy)

Extends BaseEvent. Category: player_meta (legacy enum value — no longer emitted)

The player_meta GRASS category was retired when UGC moved to structs.player. Subscribe to player_consensus instead.

GuildConsensusEvent

Extends BaseEvent. Category: guild_consensus

Data Fields: Guild consensus data object.

GuildMetaEvent

Extends BaseEvent. Category: guild_meta

Data Fields:

Field Type Description
id string Guild ID
description string Guild description (off-chain config on structs.guild_meta)
tag string Short guild tag
logo string Logo URI
services object Guild API / GRASS / webapp endpoint map

Chain UGC name and pfp live on structs.guild and surface via guild_consensus / chain events — not through guild_meta.

UGCModeratedEvent (Cosmos chain event)

Not delivered through GRASS. This is a typed Cosmos sdk.Event of type ugc_moderated emitted by the chain keeper. Subscribe via Tendermint event subscriptions (tx.events/block_events).

Fires only when the actor of a UGC update is not the target object’s owner (i.e. moderation overrides only — self-service updates are silent).

Attributes:

Attribute Description
actor_player_id Player ID of the moderator
actor_address Signing address that authored the tx
target_object_id Player / planet / substation / guild ID being moderated
target_owner_player_id Owner player ID at the time of the update
field name or pfp
old_value Field value before the update
new_value Field value after the update

See knowledge/mechanics/ugc-moderation.md for the full philosophy and validation rules.

GuildMembershipEvent

Extends BaseEvent. Category: guild_membership

Data Fields: Guild membership change data object.

EventGuildRankPermission

Extends BaseEvent. Category: guild_rank_permission

Fires when guild rank permissions are set or revoked on an object.

Data Fields:

Field Type Description
guildRankPermissionRecord object Guild rank permission record
guildRankPermissionRecord.objectId string Object the permission applies to
guildRankPermissionRecord.guildId string Guild ID
guildRankPermissionRecord.permissions integer Permission bitmask (single bit, decomposed)
guildRankPermissionRecord.rank integer Worst-allowed rank for this permission bit (0 = revoked) 
{
  "guildRankPermissionRecord": {
    "objectId": "6-1",
    "guildId": "0-1",
    "permissions": 4,
    "rank": 3
  }
}

PlanetRaidStatusEvent

Extends BaseEvent. Category: raid_status

Data Fields:

Field Type Description
status string Raid outcome. One of: victory (attacker won), defeat (attacker lost), attackerRetreated (attacker retreated from raid)
attackerId string Attacker player ID
planetId string Target planet ID

PlanetActivityEvent

Extends BaseEvent. Category: planet_activity

Data Fields:

Field Type Description
planetId string Planet ID associated with this activity
details object Activity details (JSONB from planet_activity table)
details.struct_health object Struct health information (additional properties allowed)

FleetArriveEvent

Extends BaseEvent. Category: fleet_arrive

Data Fields: Fleet arrival data object.

StructStatusEvent

Extends BaseEvent. Category: struct_status

Data Fields: Struct status change data object.

BlockEvent

Extends BaseEvent. Category: block

Data Fields:

Field Type Description
height integer Block height
hash string Block hash

Event Categories

Category Group Event Types
consensus block
guild guild_consensus, guild_meta, guild_membership, guild_rank_permission
planet raid_status, fleet_arrive, fleet_advance, fleet_depart, planet_activity
struct struct_attack, struct_defense_remove, struct_defense_add, struct_defender_clear, struct_status, struct_move, struct_block_build_start, struct_block_ore_mine_start, struct_block_ore_refine_start
player player_consensus, player_meta

Breaking Changes