Benevolence explainer

⭐ Benevolence Dapp Explainer

The Benevolence Dapp is a decentralized blasting engine that converts matched USDC into route‑specific tokens and distributes them between a vault and the caller. It is fully non‑custodial, transparent, and permissionless.

Your PEWPEW balance is used only as a read‑only eligibility signal — it is never transferred, locked, or approved.

Each route defines:

– tokenOut — the asset being blasted
– vault — where most blasted tokens are sent
– primary USDC pool
– secondary USDC pool
– matched USDC — determines how many steps can be blasted

When a user blasts a route, matched USDC is swapped for tokenOut.
Most of the output goes to the route’s vault, and a small portion goes to the caller as a tier‑based reward determined by their PEWPEW balance.

—

🟦 PEWPEW Gating System (Read‑Only)

PEWPEW is never moved or approved.
Your balance is only read to determine:

– Blasting eligibility
– Cooldown tier
– Reward tier
– Primary start permissions
– Cancel permissions
– Reassign permissions
– Sweep permissions

Eligibility Thresholds

| PEWPEW Held | Permission / Benefit |
|————-|———————-|
| ≥ 1,000,000 | Eligible to blast |
| ≥ 10,000,000 | Reduced cooldown (180s), and full administrative functions |
| ≥ 20,000,000 | Same as 10M (no extra privileges) |
| ≥ 40,000,000 | Fastest cooldown (60s), Tier 5 rewards |

—

🟩 Tiered Reward System

Rewards are paid in tokenOut, but calculated using a USDC value per tier.
These values are owner‑adjustable and expressed in 6‑decimal USDC units.

Reward Tiers

The contract:

1. Converts the USDC reward value into tokenOut using the route’s pathIn
2. Ensures the reward does not exceed the tier cap
3. Sends the reward to the caller

The remainder of tokenOut goes to the route’s vault.

—

🟧 Cooldown System (Final)

Cooldowns apply globally across all routes and depend on the caller’s PEWPEW balance.

Cooldown Tiers

| PEWPEW Held | Cooldown |
|————-|———-|
| < 10M | 300 seconds | | ≥ 10M | 180 seconds | | ≥ 20M | 120 seconds | | ≥ 40M | 60 seconds (fastest) | Cooldown is tracked per caller using lastBlastTime. --- ⭐ Administrative Privileges (Final) Anyone with ≥ 10,000,000 PEWPEW can: ✔ Start Primary Pools - First primary deposit requires ≥ 10M PEWPEW - After that, anyone may add primary ✔ Cancel Primary - Can cancel unspent primary USDC - Works whether blasting has begun or not - Canceled USDC becomes unassigned ✔ Reassign Unassigned - Can move unassigned → primary - Must respect half‑cap limits ✔ Sweep Stray USDC - Can sweep mismatched or leftover USDC into unassigned - Helps keep routes clean and balanced ✔ Full Blasting Access - Tier‑3+ rewards - Shorter cooldowns - No restrictions on blasting routes > 20M–39.99M PEWPEW holders do not gain extra privileges beyond cooldown and reward tier.

—

🔥 Blasting Workflow

1. Caller must hold ≥ 1M PEWPEW
2. Caller must not be in cooldown
3. Route must be enabled and not paused
4. Matched USDC determines how many steps can be blasted
5. Each step consumes:
– halfStep from primary
– halfStep from secondary
6. USDC is swapped for tokenOut using the route’s pathIn
7. Caller receives a tier‑based reward in tokenOut
8. Remainder goes to the route’s vault
9. Event Blasted is emitted

—

🟫 Deposits & Matching

Primary Deposits
– Anyone can deposit primary
– The first primary deposit for a route requires ≥ 10M PEWPEW
– First deposit must be ≥ 5 USDC
– Primary pool cannot exceed half of the route cap
– Only unspent primary can be canceled

Secondary Deposits
– Anyone can deposit secondary
– No PEWPEW requirement
– Same half‑cap limit

Matching Logic
Matched USDC = min(primaryAvailable, secondaryAvailable)

Steps available = matchedUSDC ÷ halfStep

—

🟪 Canceling & Reassigning

Cancel Primary (≥ 10M PEWPEW)
– Cancels unspent primary
– Moves canceled USDC → unassigned
– Works before or after blasting begins

Reassign Unassigned (≥ 10M PEWPEW)
– Moves unassigned → primary
– Must respect half‑cap limits

Sweep Stray USDC (≥ 10M PEWPEW)
– Sweeps mismatched or leftover USDC into unassigned
– Keeps route accounting clean

—

🟦 Route Configuration (Owner‑Only)

Routes can only be configured or removed if:

– They contain no funds, and
– They have no blasting history

Each route defines:

– tokenOut — the asset being blasted
– vault — where most tokenOut is sent
– pathIn — USDC → tokenOut swap path
– pathValue — tokenOut → USDC valuation path

Default Paths
When configuring a route, the contract automatically sets:

`
pathIn: USDC → WPLS → tokenOut
pathValue: tokenOut → WPLS → USDC
`

Owner may override with custom multi‑hop paths (2–4 tokens).

Route Signature Protection
Routes cannot duplicate (tokenOut, vault) pairs.

—

🟧 Slippage Controls

– Global slippage: 50–4900 bps
– Per‑route override: 0 (use global) or 50–4900 bps
– Enforced on every swap

—

🟩 Frontend‑Ready Views

The contract exposes rich read functions:

Route Status
– Enabled / paused
– tokenOut
– vault
– primaryAvailable
– secondaryAvailable
– matchedAvailable
– stepsAvailable
– slippageUsed

Global Status
– Total committed
– Total spent
– Total unspent
– Global slippage
– Step size
– Half‑step
– Minimum PEWPEW to blast
– Unassigned USDC

Caller Eligibility
– Can blast
– Cooldown active
– Seconds remaining
– Caller PEWPEW balance
– Cooldown tier

Reward Preview
– Reward USDC target
– Reward USDC cap
– Reward tokenOut amount
– Reward value in USDC
– Caller PEWPEW
– Capped PEWPEW used

—

🟦 PEWPEW Safety Guarantee

Your PEWPEW Is Always Safe

BenevolenceVault v1.8.x:

– Never transfers PEWPEW
– Never locks PEWPEW
– Never spends PEWPEW
– Never requests approval for PEWPEW
– Never burns PEWPEW
– Never escrows PEWPEW

PEWPEW is read‑only and used exclusively for:

– Eligibility
– Cooldown tier
– Reward tier
– Primary start permissions
– Cancel permissions
– Reassign permissions
– Sweep permissions

Non‑Custodial
The contract only holds:

– USDC (for blasting)
– tokenOut (from swaps)

It never holds PEWPEW.

Your PEWPEW stays in your wallet — always.