> ## 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.

# Overview

> Overview — Dark Matter Protocol on Robinhood Chain.

# Architecture Overview

Dark Matter is a set of **independent contracts** around a single core reactor. Each
component has its own admin, its own safety model, and its own payment role. Nothing
shares an upgradeable proxy — if one part fails, the others keep working.

```
                         ┌───────────────────────────────────────┐
        deposit (ETH)    │      UltimateSingularityProtocol      │
   ─────────────────────▶│         (the Reactor core)            │
                         └───┬────────┬────────┬────────┬───────┘
                             │        │        │        │
        1% stock dividend    │        │        │        │  500e18 DUST / ETH
                   ┌─────────▼──┐  ┌──▼────────┐  │  ┌─────▼──────┐
                   │StockDividend│ │FounderPass│  │  │StardustWheel│
                   │   Vault     │ │  (10% of  │  │  │   (DUST)    │
                   │ daily pool  │ │ fee stream│  │  └────────────┘
                   └─────────────┘ └───────────┘  │
                                       10% of fee │
                                              ┌───▼──────────────┐
                                              │ EventHorizonPool │
                                              │  weekly raffle   │
                                              └──────────────────┘

   Casino custody:  CrashVault (player balances, edge routing)
   Growth:          DarkMatterTreasury (gas relay top-ups, Supernova epochs, DAO)
   Earn:            EarnZapRouter → Morpho VaultV2 · NftLoanPool (pooled lending)
   NFTs:            DarkMatterNFT → injectMassFor (auto-invest) · LootBoxNFT
```

## Component map

| Contract | Role | Payment responsibility |
| - | - | - |
| `UltimateSingularityProtocol` | The Reactor — nodes, radiation, referral tree | Splits every deposit fee; forwards to all pools |
| `CrashVault` | Casino custody (ETH + USDG game balances) | Holds 100% of player assets; routes realized edge 50/50 |
| `StockDividendVault` | Daily stock dividend pool | Receives 1% of every reactor deposit, pools per UTC day |
| `FounderPass` | 215-pass fee-sharing NFT | Receives 10% of the reactor's fee stream; per-token accrual |
| `EventHorizonPool` | VIP layer gated by NFT mass | Receives 10% of the fee stream; weekly 70/30 raffle/dividend |
| `DarkMatterTreasury` | Protocol growth engine | Gas-relay top-ups, Supernova epochs, DUST-weighted DAO |
| `StardustWheel` | DUST token + prize wheel | Mints DUST on deposits; streak fees → treasury |
| `LootBoxNFT` | On-chain lootbox NFTs | Box revenue forwards 100% to treasury; signature-gated reveals |
| `EarnZapRouter` | One-signature Morpho zaps | 1% immutable exit fee → treasury |
| `NftLoanPool` | Pooled NFT lending | 10% of interest → treasury, 90% to lenders pro-rata |

## <a id="admin-safety" />Admin & safety model

Every contract follows the same four principles:

**1. Two-step ownership.** Transfers of admin/owner/treasury roles never take effect
immediately — the current role proposes, the new role accepts:

```solidity theme={null}
function transferOwnership(address newOwner) external onlyOwner;  // sets pendingOwner
function acceptOwnership() external;                              // pending must claim
```

**2. One-shot wiring for money destinations.** The vaults and pools on the reactor
(`setStockDividendVault`, `setRewardPools`, `setStardust`, `setGasSponsorSkim`) can only
be set once, ever. A compromised owner cannot redirect established payment flows.

**3. Fail-safe fee forwarding.** A rejected downstream transfer never reverts the user's
deposit. The reactor records failed pool credits as `pendingPoolCredits` which anyone can
retry permissionlessly (`retryPoolCredits()`):

```solidity theme={null}
// UltimateSingularityProtocol._deliverPoolCredit — abbreviated
(bool ok, ) = pool.call{value: amount}("creditDeposit(address,uint256)");
if (!ok) (ok, ) = pool.call{value: amount}("");     // plain fallback
if (!ok) pendingPoolCredits[pool] += amount;        // queued, never lost
```

**4. Allowance-capped automation.** The treasury's operator (the cron) can spend only
within a rolling 30-day allowance, and (when the allowlist is enforced) only to
pre-approved targets. A leaked operator key cannot drain the treasury.

## The custody split — one sentence per surface

* **Reactor deposits** land in the `UltimateSingularityProtocol` contract balance itself;
  yield is paid out of a shared balance curve (see [Reactor Yield](reactor/yield-economics.md)).
* **Casino balances** are held by `CrashVault`, which the server never controls — withdrawals
  require the player's own EIP-191 signature, enforced on-chain (see [Two Vaults](architecture/vaults-custody.md)).
* **Earn positions** are minted directly to the user's address — the zap router holds no
  custody and no approvals over user funds (see [Earn Zap](earn/earn-zap.md)).

## Trust boundaries (read this before integrating)

| Boundary | Trusts | Cannot do |
| - | - | - |
| Crash relayer | Relayer submits withdrawals | Move funds without the player's signature |
| Crash seed | Server pepper (secret) | Change outcomes after commit — seed hash is committed at betting-open |
| Lootbox signer | Signer commits tier rolls | Re-roll a box — outcome is fixed from `keccak(boxId ‖ pepper)` at buy time |
| VIP spend source | Lootbox relayer reports spend | Anyone else can `creditSpend` — only `spendSource` passes the guard |
| Treasury operator | Cron wallet | Spend beyond 30-day allowance or outside the allowlist |

Next: [The Two Vaults & Custody](architecture/vaults-custody.md).


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