Bullion|Protocol Docs

SETTLEMENT

Oracle-Verified Settlement

Settlement is the final stage of the Flywheel reward pipeline. It ensures that every conversion from revenue tokens to reward tokens is fair, verifiable, and resistant to manipulation. Chainlink oracles validate every purchase — bad prices revert on-chain.

Settlement Pipeline

1

Revenue Accumulation

Revenue tokens accumulate in the Collection Layer. When a trigger fires (time, volume, or manual), the accumulated balance is forwarded to the Conversion Router.

2

Oracle Price Check

The Conversion Router queries Chainlink Data Feeds for the current fair market price of the revenue token relative to the reward token. This price becomes the benchmark for settlement validation.

3

DEX Aggregation

The router sends the swap through a DEX aggregator (e.g., 0x, 1inch, or custom router). The aggregator finds the best execution path across multiple liquidity sources.

4

Post-Swap Validation

After the swap executes, the effective exchange rate is compared against the oracle benchmark. If deviation exceeds maxSlippageBPS, the entire transaction reverts.

5

Reward Delivery

Validated reward tokens are transferred to the Settlement Vault. The Reward Accounting layer updates the rewardPerToken accumulator, instantly crediting all active depositors.

6

User Claims

Depositors call claimRewards() to withdraw their accrued reward tokens. Claims are unbounded — claim as frequently or infrequently as you want with no penalty.

Oracle Integration

Chainlink Data Feeds are the canonical price source for Flywheel settlement. The protocol queries the latest round data before and after each swap to ensure fair execution.

Oracle Query

(, int256 price, , uint256 updatedAt, ) = priceFeed.latestRoundData();

Only round data updated within a configurable staleness threshold is accepted. Stale prices cause the transaction to revert, preventing settlement against outdated market data.

Slippage Validation

uint256 effectivePrice = (outputAmount × PRECISION) / inputAmount;
uint256 deviation = abs(effectivePrice - oraclePrice) / oraclePrice;
require(deviation <= maxSlippage, "Slippage exceeded");

Configurable Parameters

  • • maxSlippageBPS — maximum allowed deviation (default: 100 = 1%)
  • • maxPriceAge — maximum oracle data age in seconds (default: 3600)
  • • priceFeed — the specific Chainlink aggregator address

DEX Aggregation

The Conversion Router delegates execution to a DEX aggregator for best-price routing. This ensures the protocol always receives the optimal exchange rate across all available liquidity sources.

Routing Strategy

1.Revenue token is approved for the aggregator contract
2.Aggregator computes the optimal route across all DEXes
3.Minimum output amount is set based on oracle price - slippage
4.Swap executes atomically — all or nothing

MEV Protection

The combination of oracle-verified minimum output amounts and atomic execution prevents sandwich attacks. An attacker cannot manipulate the DEX price to their advantage because the post-swap validation will detect the deviation and revert the transaction.

Claim Process

Claims are the user-facing side of settlement. Depositors can claim accrued rewards at any time with zero fees. The claim process is simple, gas-efficient, and non-custodial.

Claim Lifecycle

1.User calls claimRewards() on the Settlement Vault
2.Contract computes pending rewards using the checkpoint formula
3.Reward tokens are transferred from vault to user wallet
4.Checkpoint is updated — user starts fresh from zero pending

No Claim Fees

Flywheel does not charge fees on claims. The protocol earns revenue from the configured revenue sources — not from taxing user withdrawals. Claims are unbounded in frequency and size.