Skip to main content
InternalMarkdown

ADR 0025. Provider Launch Sessions and PlayerPal Widget Distribution

Status​

Accepted.

Context​

ADR 0015 keeps PlayerPal out of game launch and settlement, while ADR 0017 defines operator-led linking. A realistic provider integration still needs to bootstrap a cross-origin game, optionally present PlayerPal inside the provider-owned experience, and support both operator-led and provider-led adoption without making browser payloads authoritative.

Copying the widget into a provider build makes its provenance and upgrade path provider-controlled. Passing launch credentials in an iframe URL leaks them through browser history, logs and referrers. Letting a provider call an operator to perform linking also reverses the intended ownership boundary.

Decision​

  1. The operator creates a short-lived Provider launch session through the provider's authenticated backend API. PlayerPal is not called in this path.
  2. Browser bootstrap uses a single-use, expiring POST body. Access tokens, signed assertions and player aliases never appear in the iframe URL. The provider backend consumes the bootstrap and supplies immutable, sanitized session context to its own game client. When the game client is on a different origin from the consume endpoint, the handoff uses same-tab window.name (never query/fragment secrets); the provider page then publishes verified context to the PlayerPal widget via a same-document event. Parent postMessage is not used for launch context.
  3. The operator remains authoritative for the seamless wallet. The provider owns game mathematics and Provider rounds; PlayerPal receives only asynchronous, post-settlement Activity batches from the provider backend.
  4. Providers load an exact immutable PlayerPal widget build from a PlayerPal-controlled asset origin with Subresource Integrity. They do not rebuild or redistribute the widget. Widget failure never blocks play.
  5. Integrations may use three Linking modes:
    • pre-linked — an existing provider alias is present at launch;
    • operator-led — the operator completes linking before launch and places only the provider alias in launch metadata;
    • provider-led — the provider's Link broker creates and exchanges a provider-scoped Link intent under authenticated integration scope.
  6. A provider never calls an operator to perform linking. If an operator-led launch has no alias, the provider continues without PlayerPal.
  7. The provider surface receives only its integration-scoped pp_plr_prv_… alias and coarse connection/outbox status. Global Points, ledger details, operator aliases and the private PlayerPal ID stay on PlayerPal-controlled surfaces.

Consequences​

  • Extends ADRs 0015 and 0017; it does not replace their asynchronous sidecar or PlayerPal-hosted consent requirements.
  • The local demonstration needs distinct operator, provider and PlayerPal backend boundaries and separately owned persistence, even when infrastructure is shared on one development machine.
  • A refreshed or replayed consumed bootstrap cannot resume a game. The operator requests a new Provider launch session; persisted wallet and round state make recovery idempotent.
  • The original PixiJS game remains play-money demonstration software and is not certified real-money gambling mathematics.