How It Works

Contract Architecture

Spree is a modular system of upgradeable smart contracts deployed on EVM chains. Each contract has a specific responsibility, and contracts communicate through well-defined interfaces.

                        ┌─────────────────────┐
                        │    SpreeFactory      │
                        │  (Mint / Redeem SP)  │
                        └──────┬──────┬────────┘
                               │      │
                    ┌──────────┘      └──────────┐
                    ▼                             ▼
          ┌──────────────────┐          ┌──────────────────┐
          │   SpreePoints    │          │  CollateralVault  │
          │   (SP ERC-20)    │          │  (ERC-4626)       │
          └────────┬─────────┘          └──────────────────┘
                   │
       ┌───────────┼───────────────┐
       ▼           ▼               ▼
┌────────────┐ ┌──────────────┐ ┌──────────────────┐
│PointsFactory│ │PendingSPVault│ │  SpreeVault4626   │
│(Branded SP) │ │  (pSP)       │ │ (Rewards Vault)   │
└────────────┘ └──────┬───────┘ └────────┬──────────┘
                      │                  │
                      │         ┌────────┘
                      ▼         ▼
               ┌──────────────────────┐
               │  BonusRewardsVault   │
               │ (Bonus Rewards)      │
               └──────────────────────┘
                      │
            ┌─────────┼──────────┐
            ▼                    ▼
  ┌───────────────────┐ ┌───────────────┐
  │SpreeStatusRegistry│ │  BoostEngine  │
  │  (Tiers / TWAB)   │ │ (Multipliers) │
  └───────────────────┘ └───────────────┘

Deployed Chains

Network	Chain ID	Environment
Ethereum Mainnet	1	Mainnet
Base	8453	Mainnet
Berachain	80094	Mainnet
Base Sepolia	84532	Testnet
Berachain Testnet	80084	Testnet
MOCA Devnet	5151	Devnet
MOCA Testnet	222888	Testnet

Security Model

Role-Based Access Control (RBAC)

Every contract uses OpenZeppelin's AccessControl (or AccessControlUpgradeable). Roles are granular:

• DEFAULT_ADMIN_ROLE controls role assignment and critical configuration

• MANAGER_ROLE handles day-to-day operations (rates, whitelists, campaigns)

• OPERATOR_ROLE triggers automated processes (tier updates, rebalancing)

• PAUSER_ROLE can halt operations in emergencies

No contract uses a single-owner pattern. All privileged operations require a specific role.

UUPS Upgrades

Core contracts (SpreePoints, SpreeFactory, SpreeVault4626, BonusRewardsVault, PendingSPVault, SpreeStatusRegistry, BoostEngine) use the UUPS proxy pattern. An UPGRADER_ROLE authorizes upgrades. The implementation contract's constructor calls _disableInitializers() to prevent initialization of the implementation directly.

Whitelists

SP transfers require both sender and receiver to be on the transfer whitelist. Minting SP requires the caller to be on the mint whitelist. Redemption requires the redeem whitelist. pSP settlements require the destination to be on the campaign's settlement whitelist.

Oracle Safety

The SpreeFactory checks price oracle data before every mint. If a collateral asset's price deviates from $1.00 beyond the configured tolerance, or if the price data is stale, the mint reverts.

The SpreeVault4626 uses an OracleManager with hysteresis-based circuit breaking: the vault pauses deposits when deviation exceeds pauseDeviation, and requires N consecutive safe price updates below unpauseDeviation before resuming.

Collateral Invariants

• SP: totalSupply() of SP <= sum of all CollateralVault assets

• Branded SP: SP.balanceOf(PointsFactory) >= sum of all brands' collateralSP

• pSP: totalSupply() of pSP <= SP.balanceOf(PendingSPVault)

• BonusRewardsVault: totalDistributed <= totalHarvested

The contracts check these invariants after state-changing operations.