enosys-contracts

name

enosys-contracts

description

Essential reference skill for Enosys Global DeFi protocol development on the Flare Network and its related chains. Use this skill whenever Darren asks about: interacting with Enosys smart contracts (DEX V2, DEX V3/CLMM, Loans/CDP, APYCloud, Governance), writing new Solidity contracts that integrate with Enosys products, building scripts or tools that call Enosys contract functions, understanding how Enosys products work internally, looking up contract addresses on Flare, Songbird, Coston1, or Coston2, understanding token addresses (HLN, APS, WFLR, FXRP, CDP, eUSDT, etc.), or building anything DeFi-related on the Flare Network. Trigger on any mention of Enosys, Flare DEX, DEX V3, CLMM, CDP token, Loans protocol, APYCloud, HLN, APS, FTSO oracle integration, or Flare DeFi development.

Enosys Global — Smart Contract Reference Skill

Enosys Global (formerly FLR Finance) is the leading DeFi suite on the Flare Network. This skill gives you authoritative contract addresses, product architecture, and integration patterns across all four networks.

Quick Reference: Network Configuration

Network	Chain ID	Role	RPC	Explorer
Flare	14	Production mainnet	https://flare-api.flare.network/ext/C/rpc	https://mainnet.flarescan.com
Songbird	19	Canary network (live, real $)	https://songbird-api.flare.network/ext/C/rpc	https://songbird-explorer.flare.network
Coston2	114	Flare testnet	https://coston2-api.flare.network/ext/C/rpc	https://coston2-explorer.flare.network
Coston1	16	Songbird testnet	https://coston-api.flare.network/ext/C/rpc	https://coston-explorer.flare.network

FlareContractRegistry (same address on ALL networks): 0xaD67FE66660Fb8dFE9d6b1b4240d8650e30F6019 Use this to resolve native Flare system contract addresses (WNat, FtsoRewardManager, etc.) on any network.

---

Product Overview

Enosys runs a suite of DeFi products, all fees flowing into the APYCloud (Central Yield Aggregator), which distributes rewards to governance stakers.

Product Hierarchy

APYCloud (ProfitDistribution contracts) ← collects fees from all products
├── DEX V2  — Uniswap V2 style CPAMM (constant product)
├── DEX V3  — Uniswap V3 style CLMM (concentrated liquidity)  ← main product on Flare
├── Loans   — Liquity V2 fork CDP protocol (mint CDP stablecoin)
├── Farms   — Yield farming / staking
├── Bridge  — Cross-chain asset bridge
└── Governance (APYCloud) — HLN + APS token staking, proposals

---

Contract Addresses by Network

Full address tables are in the reference files. Read them before writing any integration code.

• references/addresses_flare.md — Flare mainnet (production)
• references/addresses_songbird.md — Songbird canary network
• references/addresses_coston2.md — Coston2 testnet (Flare test)
• references/addresses_coston1.md — Coston1 testnet (Songbird test)

Most-Used Addresses: Flare Mainnet (Chain ID 14)

Core Tokens

WFLR (Wnat):  0x1D80c49BbBCd1C0911346656B529DF9E5c2F783d
sFLR:         0x12e605bc104e93B45e1aD99F9e555f659051c2BB
HLN:          0x140D8d3649Ec605CF69018C627fB44cCC76eC89f
APS:          0xfF56Eb5b1a7FAa972291117E5E9565dA29bc808d
FXRP:         0xAd552A648C74D49E10027AB8a618A3ad4901c5bE
CDP (stable): 0x6Cd3a5Ba46FA254D4d2E3C2B37350ae337E94a0F
eUSDT:        0x96B41289D90444B8adD57e6F265DB5aE8651DF29
USDT0:        0xe7cd86e13AC4309349F30B3435a9d337750fC82D

DEX V2 (Uniswap V2 style)

EnosysDexFactory: 0x28b70f6Ed97429E40FE9a9CD3EB8E86BCBA11dd4
EnosysDexRouter:  0x088EeCB467B3968Da36c71F05023A1d3133B2B83

DEX V3 (Concentrated Liquidity / CLMM)

EnosysDexV3Factory:         0x17AA157AC8C54034381b840Cb8f6bf7Fc355f0de
SwapRouter:                 0x5FD34090E9b195d8482Ad3CC63dB078534F1b113
NonfungiblePositionManager: 0xD9770b1C7A6ccd33C75b5bcB1c0078f46bE46657
Quoter (V1):                0x5Be6edd89feC3ab9889D49337B19C101712eBB77
QuoterV2:                   0x0A32EE3f66cC9E68ffb7cBeCf77bAef03e2d7C56
EpochManager:               0x389D610CBB52A2Da635a589013Ba542e807C74f7
RewardManagerUpgradableFactory: 0xbEEFA7FAb245B568183D5f67731487908630d801

Loans (Liquity V2 Fork)

boldToken (CDP):      0x6Cd3a5Ba46FA254D4d2E3C2B37350ae337E94a0F
collateralRegistry:   0x9474206bc035D03d142264fd9913d1D51246d3AC
hintHelpers:          0x0f493519aFF37a4Ec95f31301b7c4F987915Acb0
multiTroveGetter:     0xb80C59BBCEB205bCA25Eea2e4221717f23b339d3
liquidationBot:       0xCB5e11E03c76396ae0e05A328707F85A725F0a9C
--- FXRP Branch ---
borrowerOperations:   0x18139E09Fb9a683Dd2c2df5D0edAD942c19CE912
troveManager:         0xc46e7d0538494FEb82b460b9723dAba0508C8Fb1
stabilityPool:        0x2c817F7159c08d94f09764086330c96Bb3265A2f
priceFeed (FXRP):     0xFc35d431Ce1445B9c79ff38594EF454618D2Ec49
--- WFLR Branch ---
borrowerOperations:   0x19b154D5d20126a77309ae01931645a135E4E252
troveManager:         0xB6cB0c5301D4E6e227Ba490cee7b92EB954ac06D
stabilityPool:        0x0Dd6daab4cB9A0ba6707Cf59DBfbc28cc33CA24A
priceFeed (WFLR):     0xBCB5420d7F6346DB739a7C49FC90AB37553B68dc

Governance & APYCloud

EnosysGovernanceStakeManagerHln: 0x988E94a0AEFB1fCdC0C4d44dDBa103C5d4c6c6b0
EnosysGovernanceStakeManagerAps: 0x7eB8CeB0F64D934a31835b98eB4cbAb3cA56dF28
EnosysGovernorSingle:            0x00074DdA3EE851a69475b453Ab95C20b7a867325
EnosysGovernorDual:              0xb03D96550Ab218161ECeccbd78A0EA136BA20B1c
ProfitDistribution_80-20_DexV2:  0xc66ff685376Cdb6D56410101757d27F13dd0bd0A
ProfitDistribution_80-20_DexV3:  0x36794833ae009368fdFb9736216F1160B9d1cBbE
ProfitDistribution_50-50_SimpleStaking: 0xd7C06B3dD6597A2958D14cd6478f444C095e5d25
ProfitDistribution_50-50_FtsoRewards:  0xf4bC63DAE1F7E424E28E67138b3Fb00B6c2820AE

Third-Party / Aggregator Contracts (Flare Mainnet)

BlazeSwap Router:   0xe3A1b355ca63abCBC9589334B5e609583C7BAa06
OpenOcean Exchange: 0x6352a56caadC4F1E25CD6c75970Fa768A3304e64
Multicall3:         0xcA11bde05977b3631167028862bE2a173976CA11

---

How Enosys Products Work

DEX V2 — Constant Product AMM

• Uniswap V2 fork. Pairs are proxy contracts (upgradeable), factory deploys new pairs.
• LP tokens are ERC-20, fungible within a pair. Fees auto-compound to pool.
• L1 rewards: wFLR held in pools is delegated → earns FTSO delegation rewards + FlareDrops → redistributed to LPs via FtsoRewardRedistributor and MonthlyAirdropRedistributor.
• Key router functions: swapExactTokensForTokens, addLiquidity, removeLiquidity

DEX V3 — Concentrated Liquidity Market Maker (CLMM)

• Uniswap V3 architecture. Each position = a unique NFT (ERC-721) from NonfungiblePositionManager.
• Liquidity is deployed in specific price tick ranges — capital only works when price is in range.
• Fee tiers: 100 (0.01%), 500 (0.05%), 3000 (0.3%), 10000 (1%) bps — each is a separate pool.
• Pool naming convention in addresses file: TOKEN_A/TOKEN_B/FEE_TIER e.g. Wnat/eUSDT/3000
• Epoch-based reward system: EpochManager tracks each reward epoch. RewardManager contracts distribute per-pool incentives. Rewards are weighted by time-in-range × liquidity.
• rFLR incentives: user's active liquidity proportion during an epoch determines share of rFLR rewards (vest 12 months, 50% penalty for early claim).
• L1 rewards flow through same redistribution contracts as V2.
• Key contracts: Factory (creates pools), SwapRouter (executes swaps), NonfungiblePositionManager (manage positions), Quoter/QuoterV2 (simulate swaps off-chain).
  • QuoterV1 (0x5Be6edd89feC3ab9889D49337B19C101712eBB77): ABI uses quoteExactInputSingle(tokenIn, tokenOut, fee, amountIn, sqrtPriceLimitX96) returns (uint256) — use for simple single-uint256 quote calls.
  • QuoterV2 (0x0A32EE3f66cC9E68ffb7cBeCf77bAef03e2d7C56): returns a tuple — use when you need gas estimates or additional output data.

Pool address derivation: Use EnosysDexV3Factory.getPool(tokenA, tokenB, fee) to get pool address.

Loans — Liquity V2 Fork (CDP Protocol)

• Users lock collateral (FXRP or WFLR) in Troves to mint the CDP stablecoin (ticker: CDP).
• CDP maintains ~$1 peg via stability pool, user-set interest rates, and redemption mechanism.
• Branches: Each collateral type has its own set of contracts (BorrowerOperations, TroveManager, StabilityPool, PriceFeed). Currently 2 branches on Flare: FXRP and WFLR.
• FTSO oracle: PriceFeed contracts use Flare's FTSO (not Chainlink) for collateral pricing.
• wFLR delegation: Collateral deposited as WFLR is auto-delegated for FTSO rewards + FlareDrops.
• Fork changes vs Liquity V2 (see references/fork_changes.md):
  • Contracts are upgradeable (OZ proxy pattern) — owner is a 4/6 Safe multisig
  • FTSO replaces Chainlink oracle
  • CDP renamed from BOLD
  • Pauser functions added
  • Collateral-specific mint caps
  • Semi-diamond proxy for large contracts (BorrowerOperations/TroveManager facets)
• Key flow: BorrowerOperations.openTrove() → mint CDP → use CDP in ecosystem

APYCloud — Profit Distribution

• ProfitDistribution proxy contracts collect fee revenue from DEX V2 and DEX V3.
• 80/20 split: 80% to protocol, 20% to APYCloud treasury (or varies by product).
• Governance stakers (HLN/APS staked in EnosysGovernanceStakeManager) receive yield from APYCloud.
• Two governance paths: EnosysGovernorSingle (one token) and EnosysGovernorDual (both tokens).

Governance Tokens

Token	Symbol	Max Supply	Role
Helion	HLN	150,000,000	Secondary governance. Can vote on token listings/pairs. Replaces fees on DEX.
Apsis	APS	15,000	Primary governance. Higher voting weight. Primary reward token from farms.

• HLN staked in EnosysGovernanceStakeManagerHln → earns APYCloud yield
• APS staked in EnosysGovernanceStakeManagerAps → earns APYCloud yield
• Proposals require both to be staked; EnosysGovernorDual requires both token types

---

Integration Patterns

Fetch ABI from Flarescan API

const BASE_URL = {
  flare:    "https://mainnet.flarescan.com/api",
  songbird: "https://songbird-explorer.flare.network/api",
  coston2:  "https://coston2-explorer.flare.network/api",
  coston1:  "https://coston-explorer.flare.network/api",
};
const addr = "0x17AA157AC8C54034381b840Cb8f6bf7Fc355f0de"; // V3 Factory
const res = await fetch(`${BASE_URL.flare}?module=contract&action=getabi&address=${addr}`);
const abi = JSON.parse((await res.json()).result);

Connect to Flare with ethers.js

import { ethers } from "ethers";
const provider = new ethers.JsonRpcProvider("https://flare-api.flare.network/ext/C/rpc");
// Chain ID 14 for Flare, 19 for Songbird, 114 for Coston2, 16 for Coston1

Execute a V3 Swap (exactInputSingle)

// Always approve router first: token.approve(SWAP_ROUTER_ADDRESS, amountIn)
const router = new ethers.Contract(SWAP_ROUTER_ADDRESS, SWAP_ROUTER_ABI, signer);
const tx = await router.exactInputSingle({
  tokenIn: WFLR_ADDRESS,
  tokenOut: EUSDT_ADDRESS,
  fee: 3000,                         // 0.3% pool
  recipient: userAddress,
  deadline: Math.floor(Date.now() / 1000) + 300,
  amountIn: ethers.parseEther("100"),
  amountOutMinimum: 0n,              // set properly in production!
  sqrtPriceLimitX96: 0n,             // 0 = no price limit
});

Collect All Fees from a V3 Position

const npm = new ethers.Contract(NPM_ADDRESS, NPM_ABI, signer);
const MAX_UINT128 = (2n ** 128n) - 1n;
await npm.collect({
  tokenId: myTokenId,
  recipient: userAddress,
  amount0Max: MAX_UINT128,
  amount1Max: MAX_UINT128,
});

Claim DEX V3 Incentive Rewards

const rewardManager = new ethers.Contract(REWARD_MANAGER_ADDRESS, REWARD_MANAGER_ABI, signer);
// Check what's available first (free read)
const unclaimed = await rewardManager.getUnclaimed([tokenId], 100); // up to 100 epochs
// Then claim
await rewardManager.claim([tokenId], 100, userAddress);

// Use QuoterV2 (off-chain simulation, doesn't spend gas on actual swap)
const quoter = new ethers.Contract(
  "0x0A32EE3f66cC9E68ffb7cBeCf77bAef03e2d7C56", // QuoterV2 Flare
  quoterV2Abi,
  provider
);
const quote = await quoter.quoteExactInputSingle.staticCall({
  tokenIn: WFLR_ADDRESS,
  tokenOut: EUSDT_ADDRESS,
  fee: 3000,
  amountIn: ethers.parseEther("100"),
  sqrtPriceLimitX96: 0n,
});

Get Pool Address from V3 Factory

const factory = new ethers.Contract(
  "0x17AA157AC8C54034381b840Cb8f6bf7Fc355f0de",
  ["function getPool(address,address,uint24) view returns (address)"],
  provider
);
const poolAddress = await factory.getPool(tokenA, tokenB, feeTier);

Read a Trove (Loans)

const troveManager = new ethers.Contract(
  "0xc46e7d0538494FEb82b460b9723dAba0508C8Fb1", // FXRP branch
  ["function getTroveDebt(uint256) view returns (uint256)",
   "function getTroveColl(uint256) view returns (uint256)"],
  provider
);

---

Flare-Specific Development Notes

1. FTSO Oracle: Flare has a native decentralized oracle. Access via FlareContractRegistry to get FtsoRegistry/FtsoV2 address. No Chainlink on Flare.
2. wFLR delegation: Any contract holding wFLR should consider delegation to earn FTSO rewards. Use WNatRegistry to track delegations across product contracts.
3. FlareDrops: Monthly distributions to wFLR holders (including those in LPs). Handled by MonthlyAirdropRedistributor.
4. Block time: ~1.8 seconds, near-instant finality. Gas token is FLR/SGB/CFLR/C2FLR depending on network.
5. Proxy pattern: Most Enosys contracts are upgradeable proxies. Always interact with the proxy address, not the implementation. ProxyAdmin controls upgrades (owner = Enosys Safe 4/6 multisig).
6. EVM compatible: Flare is fully EVM-compatible. Standard Hardhat/Foundry/ethers.js workflows apply.
7. Testing track: Develop on Coston2 → stage on Songbird → production on Flare (mirrors Enosys' own 11-environment testing process).
8. Swap callback requirement: Any contract calling pool.swap() directly MUST implement enosysdexV3SwapCallback(int256 amount0Delta, int256 amount1Delta, bytes data). Use SwapRouter for standard swaps — it handles the callback internally.
9. Protocol fee collection: Protocol fees accumulate in each pool and must be swept to ProfitDistribution by calling factory.collectProtocolFeesAll() (callable by anyone). The ProfitDistribution then distributes to APYCloud stakers.
10. Governance voting power: In EnosysGovernorDual, 1 APS = 10,000 HLN in vote weight. Tokens must be staked in the StakeManager to vote — holding in wallet doesn't count.
11. Fee tier → tick spacing: 100 bps → spacing 1, 500 bps → spacing 10, 3000 bps → spacing 60, 10000 bps → spacing 200. Tick ranges in mint() must be multiples of the tick spacing.
12. Universal Router: Supports batched V2+V3 swaps and ETH wrapping in one tx. Command bytes from Commands.sol: 0x00=V3_EXACT_IN, 0x01=V3_EXACT_OUT, 0x08=V2_EXACT_IN, 0x0b=WRAP_ETH. Available on Songbird (0xfc737fa...) and Coston1 (0xc97ff9a...).
13. Solidity version: DEX V3 contracts use pragma solidity =0.7.6. Governance and APYCloud use ^0.8.13. Keep this in mind when writing integrating contracts or copying interfaces.

---

Reference Files

Load these when working on specific areas:

• references/abis_and_interfaces.md — Full ABI fragments for all major contracts (SwapRouter, NonfungiblePositionManager, Factory, Pool, EpochManager, RewardManager, Governance). Read this first when writing integration code.
• references/addresses_flare.md — All Flare mainnet addresses (tokens, pools, all products)
• references/addresses_songbird.md — All Songbird addresses
• references/addresses_coston2_coston1.md — Both testnet addresses (Coston2 + Coston1)
• references/loans_addresses.md — Full Loans protocol address breakdown (branches + implementations)
• references/dexv3_reward_managers.md — DEX V3 per-pool reward manager addresses + deadlines
• references/fork_changes.md — Enosys Loans fork changes vs Liquity V2