Chain events (Cosmos / Tendermint)

Category: api Verified against: structsd 48686a9 (v0.21.0, 2026-08-19) Source: proto/structs/structs/events.proto and keeper EmitTypedEvent sites

These are the events structsd writes onto the Tendermint ABCI log. They are not GRASS NATS messages and they are not Guild API planet-activity rows. Sync-state reads this log and then writes PostgreSQL; GRASS and the REST activity feed are that projection, not the original events.

Canonical proto: playstructs/structsd events.proto. Combat shot fields: integration-notes and combat.md. UGC attributes: ugc-moderation.md.

How to subscribe

Tendermint WebSocket: wss://public.testnet.structs.network:26657/websocket

Typed gameplay events from message handlers land on tm.event='Tx'. EventTime is emitted from begin-blocker (EmitEventTime) and lands on block events (tm.event='NewBlock'), not on a tx.

After the fact, the same array is on GET https://public.testnet.structs.network/cosmos/tx/v1beta1/txs/{hash}.

Typed-event type is the proto message name. Verified in keeper tests: structs.structs.EventAttack. Subscribe to all txs and filter that type, or query the container attribute:

{
  "jsonrpc": "2.0",
  "method": "subscribe",
  "id": 1,
  "params": {
    "query": "tm.event='Tx' AND structs.structs.EventAttack.eventAttackDetail EXISTS"
  }
}

EventTime uses tm.event='NewBlock' and structs.structs.EventTime.eventTimeDetail EXISTS. Parse with Cosmos ParseTypedEvent (or equivalent). Do not treat these as GRASS category strings.

Guild Stack sync_state.raw_events / raw_attributes only fill when SYNC_STATE_MIRROR_RAW=true (Compose default is false).

Two emission styles

Typed proto (EmitTypedEvent)

Almost every Structs gameplay event is a protobuf message. The proto wraps the payload in a container so the indexer stores one JSON blob rather than one ABCI attribute per field:

EventAttack { eventAttackDetail: { ... } }
EventDelete { objectId: "6-1" }   // single-field messages skip the wrapper

ABCI attributes are proto JSON: camelCase keys, uint64 as strings. Nested objects (the attack shot array, a full Player record) sit under the container field name.

Untyped (sdk.NewEvent)

ugc_moderated is an untyped Cosmos event (x/structs/types/events_ugc.go). Type string is exactly ugc_moderated. Attributes are snake_case strings.

Reactor infusion / defusion / migration / cancel-defusion also emit Cosmos staking events (delegate, unbond, redelegate, cancel_unbonding_delegation) on the same tx. IBC packet code emits timeout. Those are not Structs gameplay types; they ride along when those messages run.

Catalog

type below is the Tendermint event.Type string (structs.structs. + message name), except ugc_moderated.

Objects

Emitted when the keeper writes or deletes that entity. EventDelete is the generic tombstone (objectId).

On block height 1 the keeper also replays genesis (EventAllGenesis) as the same typed events so an indexer can bootstrap without scanning history.

Attributes, grid, permissions

Combat and raids

GRASS struct_attack can be a stub (~8 KB NATS cap). The chain EventAttack is the full proto.

Production and hashing

Guild bank

Provider extras

Addresses and membership

Block

Untyped

Self-service UGC updates are silent. pfpClientRenderAttributes is owner-only and does not take this path. Full rules: ugc-moderation.md.

In proto, not emitted

These messages exist in events.proto and are not currently passed to EmitTypedEvent / EmitEvent:

Do not subscribe to these as a live signal.

GRASS is not a 1:1 mirror

structs-sync-state consumes this log and writes tables. Some planet_activity categories (shield_change, block_raid_start) are derived from attribute writes and have no chain event of their own. A GRASS struct_attack stub has no shot detail; structs.structs.EventAttack on the tx does.

See event-types.md for GRASS categories and database-schema.md for unknown_event_log when a new chain type has no indexer handler yet.