Skip to content

STE-66: hand over many race packs in one signature (spec v2.7.0) - #68

Merged
Lin1er merged 7 commits into
mainfrom
feat/66-claim-racepack-many
Sep 25, 2026
Merged

Lin1er merged 7 commits into
mainfrom
feat/66-claim-racepack-many

Conversation

@Lin1er

@Lin1er Lin1er commented Sep 24, 2026

Copy link
Copy Markdown
Collaborator

STE-66: hand over many race packs in one signature (spec v2.7.0)

Sibling of #60 for the race pack desk. Frozen-spec change, so it needs a PM ACC before merge under the 24 Sep decision on STE-46. Storage: no new key, no struct change. ABI: nothing renumbered — TooManyClaims = 109 is the next free C2 code. The live RaceRecord (now v2.6) is not upgraded until ACC.

Why

The scanner works offline and queues each hand-over. Sending that queue was one transaction and one wallet approval per runner, so a desk that handed over 300 packs asked its volunteer to approve 300 prompts.

The decision worth reviewing: this batch is NOT atomic

record_results (v2.6) claim_racepack_many (v2.7)
a row the chain refuses reverts the batch skipped and reported in Vec<SkippedClaim>
why a bad row means a bad file, and the preview fixes files a bad row means two desks met the same runner — the STE-25 case, ordinary at a busy desk
what still reverts — NotAuthorized(104) (a misconfigured desk) and TooManyClaims(109)

Skipping an unauthorised operator would hand a volunteer half a drained queue with no explanation; reverting on an already-claimed pack would let one runner block the other 299.

What

Layer Change
sc/ claim_racepack_many(token_ids, operator) -> Vec<SkippedClaim>; ClaimSkipped = NotFound | NotEntered; TooManyClaims = 109. Authority checked per event against the registry and remembered for the call. claim_racepack and every batch row share hand_over_racepack, so the paths cannot drift — its 85 existing tests pass unchanged.
docs/specs/ v2.7.0: INTERFACE.md plus a CHANGELOG entry covering the asymmetry and the measurement.
bindings, sdk/vendor race-record regenerated; event-registry byte-identical.
sdk/ claimRacepackMany, CLAIM_MAX_BATCH = 100, SkippedClaim mapped to { tokenId, reason: "not-entered" | "not-found" }, error 109.
be/ error 109 in the table; e2e:claim-many. The indexer needs no change: same RacepackClaimed event per pack.

The cap is 100, measured

A racepack_claimed carries the operator address, so a row costs 160 event bytes — against a result's 136 — and the 16,384-byte limit ceilings at 102. The cap keeps two rows of headroom: short costs one more transaction, over costs a volunteer's queue at the counter. a_full_queue_of_race_packs_fits_the_network_limits pins it and computes the headroom from the run.

Tests

  • sc: 12 new (RaceRecord 97, EventRegistry 107). Seven mutations each caught: unauthorised skipped instead of fatal, already-claimed fatal instead of skipped, no cap, authority checked once for any event, no operator signature, a missing record fatal, claimed_at not written.
  • sdk: 189. Gates: check-interface.mjs OK, verify.sh OK, fmt/clippy clean.

E2E on testnet (throwaway deployment, live pair untouched)

101 runners, two desks, evidence in docs/deployments.md:

  • 100 sent, 2 skipped, 98 claimed in one transaction (58010474…).
  • The pack desk A had already handed over came back not-entered, a token id with no record not-found, and every pack listed after them still landed.
  • A desk not allowlisted for a race reverted the batch with NotAuthorized, moving nothing.
  • The SDK refused an empty queue and 101 ids before signing.
  • The 98 events decode with be's own decoder, in row order, operator desk B.

After ACC

  1. Upgrade CCVW7WVC… v2.6 → v2.7, its own entry in docs/deployments.md with the tx hash.
  2. Re-run docs/rehearsal/run.sh (run 3's 49/0/6 is the baseline).
  3. Ancung: send-claims.ts sends the queue in chunks of 100 and puts what came back skipped on the flagged list.

@vercel

vercel Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
sterun-app Ready Ready Preview Sep 25, 2026 8:44am UTC
sterun-fe Ready Ready Preview Sep 25, 2026 8:44am UTC
sterun-landing-page Ready Ready Preview Sep 25, 2026 8:44am UTC

A race pack desk works offline and queues every hand-over. Sending that
queue was one transaction and one wallet approval per runner, because a
Soroban transaction carries one contract call and claim_racepack takes one
token. A desk that handed over 300 packs asked its volunteer to approve
300 times.

claim_racepack_many(token_ids, operator) -> Vec<SkippedClaim>, with the
asymmetry the ticket asks for and record_results deliberately does not
have:

- an already-claimed pack, or an unknown token, is SKIPPED and reported
  (ClaimSkipped::NotEntered / NotFound). That is the STE-25 two-desk case:
  the loser of a race must not block the other 299 hand-overs.
- an operator who may not claim for an event REVERTS the batch
  (NotAuthorized). A misconfigured desk is not a race, and half a queue
  with no explanation is worse than none.
- more than MAX_CLAIMS_PER_CALL reverts TooManyClaims = 109 before
  anything is read.

Authority is checked per event and remembered for the call, so a desk's
queue costs one pair of cross-contract reads rather than one per runner.
claim_racepack and every batch row share hand_over_racepack, so the single
and batch paths cannot drift; the 85 existing tests pass unchanged.

The cap is 100, measured: a racepack_claimed carries the operator address,
so a row costs 160 event bytes and the 16,384-byte limit ceilings at 102.
Two rows of headroom, because being short costs a transaction and being
over costs a volunteer's queue.

12 tests. Seven mutations (unauthorised skipped instead of fatal,
already-claimed fatal instead of skipped, no cap, authority checked once
for any event, no operator signature, a missing record fatal, claimed_at
not written) each fail a test.

check-interface.mjs fails on this commit by design until the spec change.
…signature (STE-66)

MINOR and additive: claim_racepack_many, SkippedClaim, ClaimSkipped and
TooManyClaims(109) at the next free C2 code.

The entry spends its length on the one decision a reader will not guess:
this batch is NOT atomic, unlike v2.6's record_results. A pack another
desk already handed over is skipped and reported, because that is the
ordinary outcome at a busy desk; an operator who may not claim still
reverts, because that is a misconfigured desk. The cap is 100 rather than
the 102 the event-size limit allows, measured, with the two spare rows
explained.
claim_racepack_many, SkippedClaim, ClaimSkipped and TooManyClaims(109)
reach the generated client, the vendored SDK copy and both hand-maintained
error tables, which their tests pin to the frozen table.
The scanner sends its offline queue with one signature instead of one per
runner. The method mirrors the contract's asymmetry rather than hiding
it: what the batch skipped comes back as the resolved value, mapped to
`{ tokenId, reason: "not-entered" | "not-found" }`, so the flagged screen
has the rows and the reason without decoding a tagged union; an operator
who may not claim still rejects with NotAuthorized(104).

An empty queue and more than 100 ids are refused before signing. 100, not
120 as for results: a racepack_claimed carries the operator address, so a
row costs 160 event bytes against a result's 136.
…ent (STE-66)

be/scripts/e2e-claim-many.ts, run through the shared throwaway-pair
wrapper: 101 runners, two desks, one pack handed over by the other desk
before the batch, and a token id no record exists for. It checks that the
full queue of CLAIM_MAX_BATCH lands in one transaction, that the two
strays come back as not-entered and not-found while every other pack still
lands, that an unallowlisted desk reverts the batch, and that the events
decode with be's own decoder in row order.
…oyment (STE-66)

100 sent, 2 skipped and reported, 98 claimed and announced, in one
transaction. The pack another desk had already handed over cost that row
alone and nothing after it, which is the difference between this batch and
record_results' atomic one.
…TE-66)

The harness feature-detects the SDK build through a structural type. It
declared claimRacepackMany as a function PROPERTY with options?: unknown,
and under strictFunctionTypes a property's parameters are contravariant —
so the real SterunClient.claimRacepackMany, whose options is the precise
CallOptions, was not assignable and the rehearsal typecheck failed the
moment STE-66's SDK method existed.

Method syntax, like claimRacepack beside it, is bivariant and accepts it.
The alternative was widening the SDK's own parameter to unknown, which
would cost every consumer its type for a detection shim.

This branch was successfully deployed

3 active deployments
Preview – sterun-landing-page — 34328fb5 Deployed Sep 25, 2026 by vercel[bot]
Preview – sterun-fe — 34328fb5 Deployed Sep 25, 2026 by vercel[bot]
Preview – sterun-app — 34328fb5 Deployed Sep 25, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant