> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darkmatter.rdytobash.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Lootbox

> Lootbox — Dark Matter Protocol on Robinhood Chain.

# Lootboxes

Two lootbox systems exist, deliberately separate:

1. **The DUST/stock lootbox** (serverless `/api/lootbox`) — pays DUST points and real
   tokenized-stock drops.
2. **The LootBox NFT** (`LootBoxNFT.sol`, `/api/lootbox-nft`) — boxes are themselves
   tradable NFTs; reveals are signature-committed on-chain.

***

## 1. The stock-drop lootbox

**Price: 0.001 ETH** (`LOOTBOX_PRICE_ETH`) sent as a plain ETH transfer to the pool
address. Payment is verified on-chain (`to == pool, value == price, not seen before`),
so there are no orphan payments and no double-claims.

### Prize table (verbatim from `serverless/lootbox.js`)

| bps | Chance | Prize | Label multiplier |
| - | - | - | - |
| 2800 | 28.0% | 20 DUST | 0.1× |
| 2150 | 21.5% | 50 DUST | 0.25× |
| 1745 | 17.45% | 100 DUST | 0.5× |
| 1745 | 17.45% | 200 DUST | 1× |
| 1000 | 10.0% | 400 DUST | 2× |
| 260 | 2.6% | **STOCK DROP** — random slice 0.003–0.005 ETH in xStock | 3× |
| 240 | 2.4% | 0.005 ETH in xStock | 5× |
| 55 | 0.55% | 0.01 ETH in xStock | 10× |
| 5 | 0.05% | 0.025 ETH in xStock | 25× |

Weights sum to exactly **10000**. The STOCK DROP tier **always delivers a real listed
share slice** — pool ETH is swapped into one of the listed xStocks (AAPL, NVDA, TSLA,
SPACEX…) and **sent to the winner, never plain ETH**, so win feeds can show
"📈 AAPL drop" and the prize is a visible, ownable asset.

### The stock sprinkle

On top of the table: every **DUST winner** holds a 1-in-50 chance
(`LOOTBOX_SPRINKLE_CHANCE`) of an extra sprinkle — \~1% of the box price
(`SPRINKLE_BPS = 100`) into a listed xStock, sent automatically. The winner needs
zero extra prompts.

### Why the pool can't go bankrupt

Prize ETH is paid **from the pool's actual balance**, funded by box sales — the pool
can never be bankrupted and every prize is always fully paid. If a stock tier hits
and the swap fails, the row carries a DUST fallback (`dustFallback`) so the winner is
never empty-handed.

### Money flow per 0.001 ETH box

```
box sale 0.001 ETH ──▶ lootbox pool
   ├── DUST prizes: zero treasury cost (DUST is minted points)
   ├── stock prizes: pool ETH swapped → sent to winner (~4.4% of boxes)
   └── sprinkle: ~1% of box price per lucky DUST winner (2% of boxes)
Long-run stock payout ≈ 0.0006 ETH/box → house keeps ≈ 0.0003–0.0004 ETH/box
```

The measured Monte Carlo ETH-RTP of this box is **\~33%** — but that's by design:
94.4% of boxes pay DUST (reactor fuel, zero cost), and the dust economy absorbs the
rest. The real treasury cost is the stock tiers, and the box is strongly
profit-positive in ETH terms.

### Share-to-spin — free daily open

One **free** DUST-prize open per UTC day: share the day's code publicly (X / Reddit /
TikTok), paste the post link, and the server verifies the post actually contains the
code via the provider's public **oEmbed API** — no API keys, deleted/private posts
fail closed. The code is deterministic per UTC day (`keccak(pepper : date)`), can't
be pre-farmed, and is the same for everyone (one claim per wallet per day).

***

## 2. The LootBox NFT (`LootBoxNFT.sol`)

Boxes themselves are **NFTs that stay tradable until opened**; opening is one-shot
and reveals the tier permanently on the same token (no separate prize NFT).

### Box kinds & prices

| Kind | Launch price | Common | Rare | Epic | Legendary | Mythic |
| - | - | - | - | - | - | - |
| Standard | 0.001 ETH | 50% | 30% | 15% | 4.5% | 0.5% |
| Premium | 0.005 ETH | 25% | 35% | 27% | 11% | 2% |
| Apex | 0.02 ETH | 8% | 27% | 40% | 20% | 5% |

The tier table lives **on-chain** (`tierForRoll`) — anyone can verify the odds
exactly as published; the server derives tiers from the chain, not a copied table.

### Flow — three wallet prompts, never more

```
1. buy(kind)      — payable; the exact box price forwards 100% to the treasury
                    (fail-closed: if the treasury rejects, the mint reverts)
2. reveal (free)  — server rolls the tier deterministically from keccak(boxId ‖ pepper)
                    the moment the box is bought — the outcome is fixed before any
                    reveal, ungrindable, and signature-committed on-chain
3. open(boxId, tier, nonce, deadline, sig) — the relayer-signed commitment is bound
                    to (contract, boxId, tier, nonce, deadline) so it cannot be
                    replayed onto another contract, box, or after expiry
```

Opening burns nothing: the token **stays**, its tier is revealed, and metadata flips
from crate to revealed art. Winner DUST prizes are credited separately via
`StardustWheel.claimAward` with the **same nonce** — one nonce, two effects, both
verifiable on-chain.

### Revenue destination

```solidity theme={null}
address public immutable treasury;   // box revenue forwards here — 100%
```

### Rarity names are cosmetic status

In-app flex + DUST prize sizes. DUST confers no monetary rights — this keeps the
lootbox free of real-money gambling mechanics (the stock-drop box above is the one
with monetary prizes, and it is fully pool-backed as shown).

Next: [Stardust & the Wheel](stardust.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.