Repository navigation
v0.23.0: substation connection caps, planet sectors, and the group/authz execution fix
Summary
The v0.23.0 upgrade bundles three changes:
- Substation connection capacity maximum. Substation owners can cap how much power each connected player draws.
- Planet sectors. Every planet now carries a sector (127, 999 or 44). New planets get one at creation, and the upgrade backfills existing ones.
- Group/authz execution fix (security). Closes a reproduced route that executed Structs messages inside x/group proposals, skipping the Structs ante checks (quotas, throttles, charge).
This is a coordinated, state-breaking upgrade. It adds a message, protobuf fields and a grid attribute, and it changes which transactions are valid. It cannot be rolled out as a rolling binary swap. Dependencies are unchanged from v0.22.0.
Upgrade handler
The plan name is v0.23.0 (app/upgrades/v0_23_0, registered in app/app.go). The handler runs RunMigrations, then BackfillPlanetSectors. No store keys are added, and it does not replay the v0.22.0 economy conversion.
Substation connection capacity maximum
- New message:
MsgSubstationUpdateConnectionCapacityMaximum(creator,substationId,connectionCapacityMaximum). CLI:structsd tx structs substation-update-connection-capacity-maximum <substation-id> <maximum>. A maximum of0removes the cap. - The share calculation is unchanged:
max(floor(raw * 9/10) - load, 0) / max(connections, 1). The result is then capped when a maximum is set. Zero, including a missing row on existing substations, means unlimited. The cap is a ceiling, not a guaranteed minimum. - Storage: grid attribute
connectionCapacityMaximum, enum id 15, stored as15-<substationId>. Queries expose it asGridAttributesprotobuf field 16. Genesis preserves it, and substation deletion clears it. - Authorization:
PermUpdateon both the signing key and the substation, through the existing resolver (owner, delegates, guild ranks). UGC moderation permission does not grant it. Missing, deleted and closing substations are rejected. - Efficiency: a share is written, and
EventGridemitted, only when its value changes. Resubmitting the same maximum writes nothing. Nothing iterates over connected players. - Ante: the message is registered in
KnownStructsMessagesandPermissionMap(PermUpdate). It is admitted as an ordinary free Structs message, with no proof, charge or throttle requirement.
Planet sectors
Planet.sectoris a new uint64 protobuf field (19), carried in queries, exports andEventPlanet.- The sector is drawn from the block-AppHash
math/randseed plus an FNV-1a hash of the planet id. Both the seed calculation and the order of the list[127, 999, 44]are consensus rules. Player combat nonces are not consumed. - The upgrade assigns a sector to every planet that lacks one, including completed and ownerless planets. It emits one
EventPlanetper backfilled planet and is safe to re-run. - Genesis import fills in legacy zero-sector records. Validation rejects any nonzero sector outside the list.
- Sector has no gameplay effect yet, and no transaction can choose or change it.
Group/authz execution fix (security)
Before: A group proposal could wrap an authz.MsgExec holding a registered player's grant to the group policy account. Submitting with EXEC_TRY, calling MsgExec on a stored proposal, voting with EXEC_TRY, or wrapping any of these in authz all ran the Structs handler. The handler still enforced the granter's permissions, but the Structs ante checks never saw the inner message.
After:
NestedStructsMsgDecoratorfollows both authz and group containers. It checks every group submission and resolves stored proposals forMsgExecandMsgVote(EXEC_TRY), including proposals stored before the upgrade.- Shared limits: nesting depth 8, and 256 visited messages per transaction. Cycles, malformed or nil payloads, and proposals that can't be read are rejected with
structs-ante/2004. - Stored proposals are read under the transaction gas meter, after fee deduction and signature verification. An unsigned or unfunded transaction cannot make a node read state.
- Each distinct proposal is read once per transaction. A repeated reference replays the depth and visit count recorded for that proposal, so the transaction is accepted or rejected exactly as a full rescan would decide. Without this, a single transaction could force up to 255 reads.
Client and indexer impact
- Group users: a
MsgExecmust point at a proposal that is already stored when the ante runs. To create and execute a proposal in one transaction, submit it withEXEC_TRY; don't follow it with a separateMsgExec. Stored proposals that wrap Structs messages can no longer be executed. They can still be voted on (without execution) or withdrawn. - Indexers (GRASS, structs-pg): new grid attribute 15 records,
sectoron planet records and events, and a burst ofEventPlanetevents at the upgrade height. - Game rules: players can now see the connection cap and planet sectors, and Structs messages wrapped in group proposals are refused. The player docs in
structs-aineed updating for all three.
Testing
go test ./...: all 14 packages pass.- Upgrade:
app/v023_upgrade_test.goruns the registered handler through x/upgrade. It checks the module version map and diffs the exported state before and after; the only change allowed is the sector assignments. - Group/authz:
app/group_authz_signed_test.gouses signed transactions. It reproduces the bypass (it fails against the old ante, with the inner message executing), then shows rejection with state unchanged. It covers pre-upgrade proposals and includes a native group action that must still succeed.app/ante/nested_group_test.gocovers the traversal limits, plus a check that repeated references cost one read at both the visit and depth limits.
- Connection cap:
- Cache tests cover the arithmetic, uint64 boundaries and write suppression.
- A handler test covers owner, delegate, missing substation, closing substation, unregistered signer, no grant, and a key without
PermUpdate. - A signed real-app test covers guild and rank authority and multi-message rollback.
- A genesis round-trip test covers export and import.
- Sectors: deterministic assignment within a block, persistence, migration idempotence, and genesis round trips.
- Live chain (Nov 11):
tests/test_chain.sh --skip-mining --extended-battlepassed 1343 checks with 0 failures, on a binary built from this branch.- The connection-cap scenario ran in Phase 4. It set, raised, lowered and cleared the cap, checked that an unpermitted player is refused, and checked the expected store-write counts.
- Phase 6 checks new planets for valid sectors, and the naming phase checks that a rename keeps the sector.
- No group/authz transactions were sent live; that path is covered only by the Go tests above.