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