Influence contests API

Influence is a Guild Stack scoring projection of chain raid and membership facts. It does not alter consensus combat, mining, or travel. Routes under /api/influence require authentication and use the webapp success, errors, data, optional meta and total envelope. Responses use Cache-Control: private, no-store.

Routes

All routes use GET. Below, {c} is a positive contest ID; guild, player, and planet IDs have prefixes 0-, 1-, and 2- respectively.

Path after /api/influence Query parameters Result
/contests or /contests/page/{page} limit, after_id, include_total, chain_id Contest descriptors
/contests/{c} None Descriptor and readiness
/contests/{c}/standings sector Guild standings, ranks, ties, winners
/contests/{c}/guilds/{guild_id} sector Guild totals and sector rows
/contests/{c}/players or /contests/{c}/players/page/{page} limit, after_id, include_total, guild_id, sector Personal score rows
/contests/{c}/players/{player_id} sector Personal totals and sectors
/contests/{c}/planets/{planet_id} None One contest planet snapshot
/contests/{c}/planets Required planet_ids Batch of contest planet snapshots
/contests/{c}/history start_height, end_height, bucket_blocks, sector, group_by Guild score history
/contests/{c}/guilds/{guild_id}/history Same history parameters One guild’s history
/contests/{c}/players/{player_id}/history Same history parameters Personal history

Unknown or non-scalar query parameters are rejected. Pagination defaults to 100, with a maximum of 10,000; include_total=1 requests totals. Use meta.has_more and next_after_id; after_id cannot accompany a page other than 1.

planet_ids accepts 1–100 comma-separated IDs, deduplicated in first-occurrence order. It is not the general 200-ID object resolver. Planet snapshots include exists, scoring sector, nullable holder and holder_guild_id, latest_raid with event-time guilds and source_sector, and complete guild_coverage with exact supporter-count strings. exists:false means no contest claim record, not proof that the chain planet does not exist. The batch rejects coverage over 10,000 guild entries rather than truncating it.

Rules and exact values

Read weights from the contest descriptor. Rule 1 assigns 100 points per distinct defending planet covered by a guild’s current members and 200 points per planet held by the latest eligible successful raider. Eligibility uses different players with nonempty, different guilds at the raid event. Failed raids leave scores alone; an ineligible successful raid clears the current claim. Ore amounts and defensive losses award no points. Completed planets retain scores.

Guild coverage is a union: multiple members winning the same planet do not stack its coverage points. Membership transfers move the player’s contribution; another supporting member can preserve the departing guild’s coverage. Guildless players retain personal achievements but credit no guild. Personal scores are not additive guild shares; personal history is a separate ledger.

planet_sectors scores by captured sector 44, 127, or 999; unresolved sector 0 prevents finalization. single_sector uses sector 0, “All planets”, and rejects other sector filters. This is a scoring area, not a chain planet assignment. Bounds and mode are immutable. The ending block is inclusive; final scores ignore later raids and membership changes. Sector ranks use points, then guild-wide overall_points. Positive tied final leaders are co-winners; an all-zero area has no winner.

Snapshot and history contract

Each multi-query response reads one published build. Contest-scoped meta carries api_contract: structs-influence-v1, build_id, projected_height, source_height, coverage_start, contest bounds, weights, scoring mode, sectors, and readiness. Keep IDs, heights, counts and points as exact decimal strings; sector is a small JSON integer. Do not combine standings and history from different builds.

History ranges are inclusive block heights, not timestamps. Required start_height/end_height must lie within the contest and at or below its projected height. Limits: 1,000,000 blocks, 1,000 samples per series, and 10,000 rows including opening balances. bucket_blocks defaults to 1,000. Contest group_by accepts total, sector, guild, or guild_sector; guild/player history accepts total or sector.

data.opening is the balance at start_height - 1; data.samples contains bucket-ending balances and signed component/point deltas. Carry balances across quiet periods. The reader combines verified 1,000-height rollups and checkpoints with raw edges, using raw history where verified coverage is unavailable.

HTTP 400 identifies malformed input; 404 identifies an unknown contest or absent requested guild/player; 422 identifies an out-of-coverage range or oversized result. HTTP 503 means no complete published snapshot, missing schema, or a read exceeding the five-second query budget. Treat unavailable data as unavailable, not zero scores.

GRASS loading and recovery

Subscribe to an exact scope under structs.influence.<chain>.<contest>: .contest, .scores, .guild.<id>, .player.<id>, or .planet.<id>. The contract is structs-influence-grass-v1. Frames contain state, not merely invalidation hints. Healthy complete updates require no HTTP fetch.

The reference InfluenceStream subscribes and flushes before loading an API snapshot, then discards buffered updates covered by that snapshot’s build/height. Use API snapshots again after reconnect, predecessor gaps, invalid/incomplete multipart frames, or explicit resynchronization. Multipart assembly checks the SHA-256 digest. Frame IDs are monotonic globally; use previous_frame_id for scope continuity, not global consecutiveness. A different build requires a replacement; ignore duplicate and older frames. Replacement history is not ready until history.complete is true.

Clients need subscription-only NATS access. There are no replay request subjects, reply inboxes, or JetStream requirement. The database outbox protects relay delivery, not offline-client replay. See streaming schemas.

Verified scope: webapp 4fb40a54, InfluenceController, InfluenceManager, InfluenceQuery, InfluenceParameters, and InfluenceStream; structs-pg 4d04c29 influence schema/projector, single-sector, GRASS and personal-history migrations.