INTEGRATIONS

Integrating with Flywheel

Flywheel Protocol is designed to be integrated — not just used. Any project can plug into the five-layer architecture, either adopting the full stack or integrating individual layers. This page covers the interfaces, patterns, and best practices for building on Flywheel.

Integration Patterns

Full Stack

Deploy all five layers with your own token parameters. Best for new projects launching a reward system from scratch.

Revenue Source Only

Plug your existing protocol's revenue into Flywheel's Collection Layer. Keep your existing infrastructure.

Conversion Router Only

Use Flywheel's oracle-verified conversion pipeline for your own reward system. Bring your own accounting and vault.

Settlement Vault Only

Use Flywheel's proven vault with penalties, cooldowns, and LP staking. Bring your own revenue and conversion.

Required Interfaces

Revenue Source Interface

interface IRevenueSource {
function collectRevenue(address token, uint256 amount) external;
function getAccumulatedRevenue(address token) external view returns (uint256);
}

Conversion Router Interface

interface IConversionRouter {
function convertRewards(
address revenueToken,
uint256 amount,
bytes calldata swapData
) external returns (uint256 rewardTokensOut);
function getOraclePrice(address token) external view returns (uint256);
}

Settlement Vault Interface

interface ISettlementVault {
function deposit(address token, uint256 amount) external;
function requestWithdrawal(uint256 amount) external;
function claimRewards() external returns (uint256);
function pendingRewards(address user) external view returns (uint256);
function stakeLP(uint256 tokenId) external;
function unstakeLP(uint256 tokenId) external;
}

Configuration Parameters

Parameter	Default	Description
Deposit Token	Configurable	The ERC-20 token users deposit to earn rewards
Reward Token	Configurable	The ERC-20 token distributed as rewards
Activation Period	1 hour	Time before new deposits start earning
Penalty Rate	5%	Burn percentage for early withdrawal
Penalty Window	24 hours	Duration during which penalty applies
Cooldown Period	48 hours	Time between withdrawal request and completion
Max Slippage	100 BPS (1%)	Maximum deviation from oracle price
Max Price Age	3600s (1 hr)	Maximum oracle data staleness
LP Bonus Share	10%	Portion of rewards allocated to LP stakers
Depositor Share	90%	Portion of rewards allocated to depositors

Integration Checklist

01Choose your integration pattern (full stack or partial)

02Define your revenue sources and how they flow into Layer 1

03Configure token parameters: deposit token, reward token, and splits

04Set up Chainlink price feeds for your revenue and reward tokens

05Configure security parameters: slippage, staleness, penalties, cooldowns

06Deploy contracts and verify on your chain's block explorer

07Set up keeper infrastructure for automated conversion triggers

08Integrate the Settlement Vault interface into your frontend

09Configure monitoring and alerting for protocol events

10Publish documentation and audit reports for your users

Reference Implementation

Bullion is the first and reference implementation of the Flywheel Protocol. It demonstrates the full five-layer architecture in production: creator fees as Revenue Sources, ETH aggregation in the Collection Layer, conversion to SLV through the Conversion Router, per-second reward tracking in Reward Accounting, and claims through the Settlement Vault. Study the Bullion case study for a complete worked example, or inspect the open-source contracts on GitHub.