> For the complete documentation index, see [llms.txt](https://docs.stoxa.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stoxa.app/how-it-works.md). # How it Works ### The rack model The machine is a physical metaphor made literal. Cards sit on **racks,** where one rack per (pack size, rarity tier). A spin draws a tier, then draws a card from that tier's rack, and that specific card transfers to you. This matters more than it sounds. The card you win **already existed** before you spun. It was bought, paid for, and put on a shelf. The machine cannot mint a prize on demand, so it can never owe you something it does not have. ### A spin, step by step #### 1. You pay You send BNB to the `ZapRouter`. It wraps to WBNB, swaps exactly the pack price into USDT on PancakeSwap V3, and refunds every leftover wei of BNB in the same transaction. The router then calls `spin()` on the Machine. #### 2. The vault reserves Before the spin is accepted, the Machine reserves the pack's **worst-case payout** against the bankroll vault: ``` reserved = pack price × maxFaceBps → 8.88 × 8.88 = $78.85 on the small pack ``` If the vault does not have that much unreserved, the spin **reverts here,** before you have a pending bet. This is what makes solvency physical rather than promised. #### 3. Randomness is requested The Machine asks Chainlink VRF v2.5 for one random word, paid in native BNB. This is a two-transaction process: your spin is recorded as `Pending`, and the outcome is decided later by the VRF callback. Nobody - not you, not the operator, not a validator knows the result at this point, because it does not exist yet. #### 4. Chainlink fulfils Typically a few seconds later, the coordinator calls back with the random word. The Machine: * takes `word % 10_000` and walks the cumulative probability table to pick a **tier** * takes `keccak256(word) % rack.length` to pick a **card** from that tier's rack * pops that card off the rack and transfers the NFT to you The two draws use different hash lanes, so the card pick is independent of the tier pick. #### 5. Fees split, the vault settles The pack price is divided (see Fees), the reservation is released, and the house's share flows into the vault. *** ### What happens if the rack is empty If a tier's rack ran dry between your request and its fulfilment, you are paid that tier's **face value in USDT** instead of a card. This is not a failure mode bolted on, it is why the reservation exists. The money was set aside in step 2, so the fallback can always pay. You get the same value, in cash rather than shares. ### What happens if Chainlink never answers Every spin is refundable in full after `rescueDelay` (**2 days**). Anyone can call `cancelSpin(spinId)` — it does not have to be you, and it does not require the operator. Fees are only taken at settlement, so a cancelled spin refunds the entire pack price. *** ### What a card actually is An ERC-721 certificate holding real tokenized shares in escrow. You can hold it, unwrap it for the raw stock, sell it back to the house, split it, or trade it anywhere. See **Cards** for the full detail. ### The safety properties, in order of importance **Two-transaction randomness.** The outcome binds to a VRF request that already exists. There is no single transaction in which someone could see and react to the result. **Solvency is physical.** A drawn card must already be on the rack. If it is not, the reserved USDT pays instead. **Settlement can never be bricked.** Card transfers use a raw transfer with no receiver hook, and USDT winnings are booked as claimable credit rather than pushed. Nothing a winner does, including being a contract that reverts can stop the VRF callback from completing. **The table freezes mid-flight.** Odds, fees and the randomness provider cannot be changed while any spin is pending. Changing the prize table additionally requires every rack to be empty, so a card can never be stranded under a tier that no longer exists. **Pause stops new spins only.** Settlement, cancellations and claims can never be paused. If the operator pauses the machine, in-flight spins still settle and your credits are still claimable. **Admin cannot reach the money.** There is no function that lets the owner withdraw from the bankroll vault, take player credits, or touch the jackpot or egg funds. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.stoxa.app/how-it-works.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.