Repository navigation
STE-66: hand over many race packs in one signature (spec v2.7.0) - #68
Merged
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
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.
Lin1er
force-pushed
the
feat/66-claim-racepack-many
branch
from
September 25, 2026 08:37
2c7c485 to
912109e
Compare
…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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 = 109is 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)Vec<SkippedClaim>NotAuthorized(104)(a misconfigured desk) andTooManyClaims(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
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_racepackand every batch row sharehand_over_racepack, so the paths cannot drift — its 85 existing tests pass unchanged.docs/specs/sdk/vendorsdk/claimRacepackMany,CLAIM_MAX_BATCH = 100,SkippedClaimmapped to{ tokenId, reason: "not-entered" | "not-found" }, error 109.be/e2e:claim-many. The indexer needs no change: sameRacepackClaimedevent per pack.The cap is 100, measured
A
racepack_claimedcarries 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_limitspins 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_atnot written.sdk: 189. Gates:check-interface.mjsOK,verify.shOK, fmt/clippy clean.E2E on testnet (throwaway deployment, live pair untouched)
101 runners, two desks, evidence in
docs/deployments.md:58010474…).not-entered, a token id with no recordnot-found, and every pack listed after them still landed.NotAuthorized, moving nothing.After ACC
CCVW7WVC…v2.6 → v2.7, its own entry indocs/deployments.mdwith the tx hash.docs/rehearsal/run.sh(run 3's 49/0/6 is the baseline).send-claims.tssends the queue in chunks of 100 and puts what came back skipped on the flagged list.