InvarCoin

Git Source

Inherits: ERC20, ERC20Permit, Ownable2Step, Pausable, ReentrancyGuard

Title: InvarCoin (INVAR)

Global purchasing power token backed 50/50 by USDC + plDXY-BEAR via Curve LP.

INVAR is a vault token whose backing is held as Curve USDC/plDXY-BEAR LP tokens. Users deposit USDC, which is single-sided deployed to Curve. The vault earns Curve trading fee yield (virtual price growth), which is harvested and donated to sINVAR stakers. LP tokens are valued with dual pricing to prevent manipulation:

• totalAssets() and harvest use pessimistic pricing (min of EMA, oracle) for conservative NAV.
• totalAssetsValidated() provides strict oracle-validated NAV (reverts on stale/invalid oracle).
• deposit() uses optimistic NAV (max of EMA, oracle) so new depositors cannot dilute existing holders.
• lpDeposit() values minted LP pessimistically so depositors cannot extract value from stale-high EMA.
• withdraw() and lpWithdraw() use pro-rata asset distribution (no NAV pricing needed). The oracle-derived LP price mirrors the twocrypto-ng formula: 2 * virtualPrice * sqrt(bearPrice). A 2% USDC buffer (BUFFER_TARGET_BPS) is maintained locally for gas-efficient withdrawals. Permissionless solvers can rebalance USDC/Curve LP inventory against conservative reserve prices. Virtual shares (1e18 INVAR / 1e6 USDC) protect against inflation attacks on the first deposit.

Note: security-contact: contact@plether.com

Constants

USDC

USDC collateral token (6 decimals).

IERC20 public immutable USDC;

BEAR

plDXY-BEAR synthetic token (18 decimals).

IERC20 public immutable BEAR;

CURVE_LP_TOKEN

Curve USDC/plDXY-BEAR LP token.

IERC20 public immutable CURVE_LP_TOKEN;

CURVE_POOL

Curve twocrypto-ng pool for USDC/plDXY-BEAR.

ICurveTwocrypto public immutable CURVE_POOL;

BASKET_ORACLE

Chainlink BasketOracle — weighted basket of 6 FX feeds, returns foreign currencies priced in USD (8 decimals).

AggregatorV3Interface public immutable BASKET_ORACLE;

SEQUENCER_UPTIME_FEED

L2 sequencer uptime feed for staleness protection (address(0) on L1).

AggregatorV3Interface public immutable SEQUENCER_UPTIME_FEED;

CRV_MINTER

Curve Minter for CRV emissions on L1 (address(0) on L2 where claim_rewards handles CRV).

ICurveMinter public immutable CRV_MINTER;

BUFFER_TARGET_BPS

uint256 public constant BUFFER_TARGET_BPS = 200;

DEPLOY_THRESHOLD

uint256 public constant DEPLOY_THRESHOLD = 1000e6;

MAX_SPOT_DEVIATION_BPS

uint256 public constant MAX_SPOT_DEVIATION_BPS = 50;

SOLVER_PRICE_SPREAD_BPS

uint256 private constant SOLVER_PRICE_SPREAD_BPS = 10;

ORACLE_TIMEOUT

uint256 public constant ORACLE_TIMEOUT = 24 hours;

SEQUENCER_GRACE_PERIOD

uint256 public constant SEQUENCER_GRACE_PERIOD = 1 hours;

VIRTUAL_SHARES

uint256 public constant VIRTUAL_SHARES = 1e18;

VIRTUAL_ASSETS

uint256 public constant VIRTUAL_ASSETS = 1e6;

USDC_INDEX

uint256 private constant USDC_INDEX = 0;

BPS

uint256 private constant BPS = 10_000;

STAKED_INVAR_TIMELOCK

uint256 public constant STAKED_INVAR_TIMELOCK = 7 days;

GAUGE_TIMELOCK

uint256 public constant GAUGE_TIMELOCK = 7 days;

GAUGE_REWARDS_TIMELOCK

uint256 public constant GAUGE_REWARDS_TIMELOCK = 7 days;

State Variables

stakedInvarCoin

sINVAR staking contract that receives harvested yield.

StakedToken public stakedInvarCoin;

pendingStakedInvarCoin

address public pendingStakedInvarCoin;

stakedInvarCoinActivationTime

uint256 public stakedInvarCoinActivationTime;

curveLpCostVp

Cumulative virtual-price cost basis of tracked LP tokens (18 decimals).

Used to isolate fee yield (VP growth) from price appreciation. Only LP tokens deployed by the vault are tracked — donated LP is excluded to prevent yield manipulation.

uint256 public curveLpCostVp;

trackedLpBalance

LP token balance deployed by the vault (excludes donated LP).

uint256 public trackedLpBalance;

emergencyActive

True when emergency mode is active — blocks deposits and single-sided withdrawals.

bool public emergencyActive;

curveGauge

ICurveGauge public curveGauge;

gaugeStakedLp

Internally-tracked LP balance staked in the gauge (avoids external balanceOf dependency).

uint256 public gaugeStakedLp;

pendingGauge

address public pendingGauge;

gaugeActivationTime

uint256 public gaugeActivationTime;

approvedGauges

mapping(address => bool) public approvedGauges;

gaugeRewardsReceiver

address public gaugeRewardsReceiver;

pendingGaugeRewardsReceiver

address public pendingGaugeRewardsReceiver;

gaugeRewardsReceiverActivationTime

uint256 public gaugeRewardsReceiverActivationTime;

protectedRewardTokens

mapping(address => bool) public protectedRewardTokens;

Functions

constructor

constructor(
    address _usdc,
    address _bear,
    address _curveLpToken,
    address _curvePool,
    address _oracle,
    address _sequencerUptimeFeed,
    address _crvMinter
) ERC20("InvarCoin", "INVAR") ERC20Permit("InvarCoin") Ownable(msg.sender);

Parameters

_validateStakingVault

function _validateStakingVault(
    address stakingVault
) private view;

proposeStakedInvarCoin

Propose the sINVAR staking contract. Finalized after STAKED_INVAR_TIMELOCK.

function proposeStakedInvarCoin(
    address _stakedInvarCoin
) external onlyOwner;

Parameters

finalizeStakedInvarCoin

Finalize the proposed sINVAR staking contract after the timelock.

function finalizeStakedInvarCoin() external onlyOwner;

proposeGaugeRewardsReceiver

Propose the receiver for protected gauge reward tokens.

function proposeGaugeRewardsReceiver(
    address receiver
) external onlyOwner;

finalizeGaugeRewardsReceiver

Finalize the protected reward receiver after the timelock.

function finalizeGaugeRewardsReceiver() external onlyOwner;

_isCoreRewardProtectedAsset

function _isCoreRewardProtectedAsset(
    address token
) private view returns (bool);

protectRewardToken

Irreversibly marks a token as a protected gauge reward token.

function protectRewardToken(
    address token
) external onlyOwner;

sweepGaugeRewards

Sweeps a protected gauge reward token to the configured receiver.

function sweepGaugeRewards(
    address token
) external onlyOwner;

totalAssets

Total assets backing INVAR (USDC, 6 decimals).

Uses pessimistic LP pricing: min(Curve EMA, oracle-derived) to prevent stale-EMA exploitation.

function totalAssets() public view returns (uint256);

totalAssetsValidated

Total assets backing INVAR with strict oracle validation (USDC, 6 decimals).

Reverts if sequencer/oracle checks fail (stale, invalid, or within sequencer grace period).

function totalAssetsValidated() external view returns (uint256);

_totalAssetsWithPrice

Total assets using pre-fetched LP balance and validated oracle price.

function _totalAssetsWithPrice(
    uint256 lpBal,
    uint256 oraclePrice
) private view returns (uint256);

getBufferMetrics

Buffer health metrics for keeper bots and frontends.

Uses permissive totalAssets() (best-effort oracle read). For strict oracle-validated NAV, use totalAssetsValidated().

function getBufferMetrics()
    external
    view
    returns (uint256 currentBuffer, uint256 targetBuffer, uint256 deployable, uint256 replenishable);

Returns

getHarvestableYield

Estimated harvestable Curve fee yield (USDC, 6 decimals).

Read-only estimator mirroring _harvest math. Uses permissive oracle reads and returns 0 if no staking contract, no sINVAR stakers, or no VP growth.

function getHarvestableYield() external view returns (uint256 yieldUsdc);

getSpotDeviation

Spot-vs-EMA deviation for a 1 USDC deposit (basis points).

Returns 0 if spot >= EMA (no discount). Used by keepers to check if deploy/replenish is safe.

function getSpotDeviation() external view returns (uint256 deviationBps);

_totalAssetsOptimistic

Total assets using optimistic LP pricing — max(EMA, oracle) to prevent deposit dilution.

function _totalAssetsOptimistic(
    uint256 oraclePrice
) private view returns (uint256);

_oracleLpPrice

Oracle-derived LP price: mirrors twocrypto-ng formula 2 * vp * sqrt(bearPrice_18dec).

function _oracleLpPrice(
    uint256 oraclePrice
) private view returns (uint256);

_pessimisticLpPrice

function _pessimisticLpPrice(
    uint256 oraclePrice
) private view returns (uint256);

_optimisticLpPrice

function _optimisticLpPrice(
    uint256 oraclePrice
) private view returns (uint256);

_validatedOraclePrice

function _validatedOraclePrice() private view returns (uint256);

_hasStakedInvarSupply

function _hasStakedInvarSupply() private view returns (bool);

_checkpointIfNoStakers

function _checkpointIfNoStakers(
    uint256 currentVpValue
) private returns (bool checkpointed);

_lpBalance

Total LP held: local + gauge-staked (internally tracked to avoid external call dependency).

function _lpBalance() private view returns (uint256);

_ensureUnstakedLp

Unstakes LP from gauge if local balance is insufficient for the requested amount.

function _ensureUnstakedLp(
    uint256 amount
) private;

_outsideSpotDeviationBounds

function _outsideSpotDeviationBounds(
    uint256 spotValue,
    uint256 emaValue
) private pure returns (bool);

_reduceLpAccounting

function _reduceLpAccounting(
    uint256 lpReduced,
    uint256 totalLp
) private;

_recordLpDeployment

function _recordLpDeployment(
    uint256 lpMinted
) private;

_depositToCurve

function _depositToCurve(
    uint256 usdcAmount,
    uint256 bearAmount,
    uint256 oraclePrice
) private returns (uint256 lpMinted);

_stakeLpToGauge

function _stakeLpToGauge(
    uint256 amount
) private;

_validateGaugeAddress

function _validateGaugeAddress(
    address gauge
) private view;

_validateGauge

function _validateGauge(
    address gauge
) private view;

deposit

Deposit USDC to mint INVAR shares. USDC stays in the local buffer until deployed to Curve.

Uses optimistic LP pricing for NAV to prevent deposit dilution. Harvests yield before minting. Reverts while emergencyActive is true.

function deposit(
    uint256 usdcAmount,
    address receiver,
    uint256 minSharesOut
) public nonReentrant whenNotPaused returns (uint256 glUsdMinted);

Parameters

Returns

depositWithPermit

Gasless deposit using ERC-2612 permit. Falls back to existing allowance if permit fails (e.g., front-run griefing) and the allowance is sufficient.

function depositWithPermit(
    uint256 usdcAmount,
    address receiver,
    uint256 minSharesOut,
    uint256 deadline,
    uint8 v,
    bytes32 r,
    bytes32 s
) external returns (uint256);

Parameters

Returns

withdraw

USDC-only withdrawal via pro-rata buffer + JIT Curve LP burn.

Burns the user’s pro-rata share of local USDC and Curve LP (single-sided to USDC). Does not distribute raw BEAR balances — if the contract holds material BEAR, use lpWithdraw() or set minUsdcOut to enforce fair value. Blocked during emergencyActive since single-sided LP exit may be unavailable.

function withdraw(
    uint256 glUsdAmount,
    address receiver,
    uint256 minUsdcOut
) external nonReentrant whenNotPaused returns (uint256 usdcOut);

Parameters

Returns

lpWithdraw

Balanced withdrawal: returns pro-rata USDC + BEAR from Curve LP (remove_liquidity).

Intentionally lacks whenNotPaused — serves as the emergency exit when the contract is paused. Emergency mode still honors pro-rata LP claims by redeeming any remaining LP before paying out.

function lpWithdraw(
    uint256 glUsdAmount,
    uint256 minUsdcOut,
    uint256 minBearOut,
    address receiver
) external nonReentrant returns (uint256 usdcReturned, uint256 bearReturned);

Parameters

Returns

_lpWithdraw

function _lpWithdraw(
    uint256 glUsdAmount,
    uint256 minUsdcOut,
    uint256 minBearOut,
    address receiver
) internal returns (uint256 usdcReturned, uint256 bearReturned);

lpDeposit

Direct LP deposit: provide USDC and/or plDXY-BEAR, deploy to Curve, mint INVAR.

Inverse of lpWithdraw. Curve slippage is borne by the depositor, not existing holders. Shares are priced using pessimistic LP valuation so the depositor cannot extract value from a stale-high EMA. Spot deviation is checked against EMA to block sandwich attacks. Reverts while emergencyActive is true.

function lpDeposit(
    uint256 usdcAmount,
    uint256 bearAmount,
    address receiver,
    uint256 minSharesOut
) external nonReentrant whenNotPaused returns (uint256 glUsdMinted);

Parameters

Returns

harvest

Permissionless keeper harvest for Curve LP fee yield.

Measures fee yield as virtual price growth above the cost basis (curveLpCostVp). Mints INVAR proportional to the USDC value of yield and donates it to sINVAR stakers. Only tracks VP growth on vault-deployed LP (trackedLpBalance), not donated LP. Reverts if no yield is available to donate or checkpoint — use as a heartbeat signal for keepers.

function harvest() external nonReentrant whenNotPaused returns (uint256 donated);

Returns

_harvestSafe

Harvest yield before withdrawals. Best-effort: skips when no yield is pending, Curve is down, or oracle is unavailable. If no sINVAR recipients exist, checkpoints VP growth as INVAR NAV. Withdrawals must never be blocked.

function _harvestSafe() internal;

_harvest

Uses trackedLpBalance (not _lpBalance()) so donated LP cannot inflate harvestable yield. Divergence from actual LP is prevented by internal gaugeStakedLp tracking and forceRemoveGauge() which writes off stuck LP from both trackedLpBalance and curveLpCostVp.

function _harvest() internal returns (uint256 donated, bool accounted);

_mintAndDonate

function _mintAndDonate(
    uint256 amount
) private;

_harvestWithPrice

function _harvestWithPrice(
    uint256 lpBal,
    uint256 currentVpValue,
    uint256 oraclePrice
) private returns (uint256 donated, bool accounted);

donateUsdc

Accepts USDC donations from RewardDistributor, mints proportional INVAR, and donates to sINVAR.

function donateUsdc(
    uint256 usdcAmount
) external nonReentrant whenNotPaused;

Parameters

previewSellLpToVault

Preview USDC paid when a solver sells Curve LP to the vault.

Uses the pessimistic fair LP price less SOLVER_PRICE_SPREAD_BPS as the vault bid.

function previewSellLpToVault(
    uint256 lpAmount
) external view returns (uint256 usdcOut);

previewBuyLpFromVault

Preview USDC required when a solver buys Curve LP from the vault.

Uses the optimistic fair LP price plus SOLVER_PRICE_SPREAD_BPS as the vault ask.

function previewBuyLpFromVault(
    uint256 lpAmount
) external view returns (uint256 usdcIn);

sellLpToVault

Permissionless solver fill: solver sells Curve LP to the vault for excess USDC buffer.

The vault never trades on Curve; the solver owns sourcing/slippage risk.

function sellLpToVault(
    uint256 lpAmount,
    uint256 minUsdcOut
) external nonReentrant whenNotPaused returns (uint256 usdcOut);

Parameters

Returns

buyLpFromVault

Permissionless solver fill: solver buys Curve LP from the vault and restores USDC buffer.

The vault never trades on Curve; the solver owns exit/slippage risk.

function buyLpFromVault(
    uint256 lpAmount,
    uint256 maxUsdcIn
) external nonReentrant whenNotPaused returns (uint256 usdcIn);

Parameters

Returns

redeployToCurve

Re-deploys recovered BEAR + excess USDC to Curve after emergency recovery.

Clears emergencyActive flag. Should only be called after emergencyWithdrawFromCurve() has recovered the BEAR tokens from the pool.

function redeployToCurve(
    uint256 minLpOut
) external onlyOwner nonReentrant;

Parameters

setEmergencyMode

Activates emergency mode without touching Curve.

Pauses the contract and blocks deposits plus single-sided withdrawals. LP accounting is left intact so users retain their pro-rata claim once balanced exits recover.

function setEmergencyMode() external onlyOwner;

forceRemoveGauge

Write off a bricked gauge and its stuck LP from accounting.

Only callable during emergencyActive. Clears curveGauge, proportionally reduces trackedLpBalance and curveLpCostVp for the lost LP, and zeros gaugeStakedLp. After this, emergencyWithdrawFromCurve() or lpWithdraw() can proceed with remaining local LP.

function forceRemoveGauge() external onlyOwner;

emergencyWithdrawFromCurve

Attempts to recover LP tokens from Curve via balanced remove_liquidity.

Also callable as a standalone emergency — sets emergencyActive, pauses, and only zeroes tracked LP accounting after the LP has actually been recovered. If Curve is bricked, the remove_liquidity call reverts and the entire tx rolls back, leaving state unchanged. Use setEmergencyMode() first in that case.

function emergencyWithdrawFromCurve() external onlyOwner nonReentrant;

setGaugeApproval

function setGaugeApproval(
    address gauge,
    bool approved
) external onlyOwner;

pause

function pause() external onlyOwner;

unpause

function unpause() external onlyOwner;

rescueToken

Rescue accidentally sent ERC20 tokens. Cannot rescue USDC, BEAR, or Curve LP.

function rescueToken(
    address token,
    address to
) external onlyOwner;

Parameters

proposeGauge

Propose a new Curve gauge for LP staking. Subject to GAUGE_TIMELOCK delay.

function proposeGauge(
    address _gauge
) external onlyOwner;

Parameters

finalizeGauge

Finalize a pending gauge change after the timelock expires.

This MUST revert if oldGauge.withdraw() fails. Do NOT wrap in try/catch: silent failure would update curveGauge to newGauge while LP stays locked in oldGauge, causing _lpBalance() to forget the stuck LP and collapsing totalAssets(). If the old gauge is permanently bricked, use setEmergencyMode() instead.

function finalizeGauge() external onlyOwner;

stakeToGauge

Stake LP tokens to the active Curve gauge.

function stakeToGauge(
    uint256 amount
) external onlyOwner;

Parameters

unstakeFromGauge

Unstake LP tokens from the active Curve gauge.

function unstakeFromGauge(
    uint256 amount
) external onlyOwner;

Parameters

claimGaugeRewards

Claim CRV + extra rewards from the gauge. Use rescueToken() to sweep reward tokens.

On L1, CRV is minted via the Curve Minter (not claim_rewards). On L2, claim_rewards handles CRV.

function claimGaugeRewards() external onlyOwner;

Events

Deposited

event Deposited(address indexed user, address indexed receiver, uint256 usdcIn, uint256 glUsdOut);

Withdrawn

event Withdrawn(address indexed user, address indexed receiver, uint256 glUsdIn, uint256 usdcOut);

LpWithdrawn

event LpWithdrawn(
    address indexed user, address indexed receiver, uint256 sharesBurned, uint256 usdcReturned, uint256 bearReturned
);

LpDeposited

event LpDeposited(address indexed user, address indexed receiver, uint256 usdcIn, uint256 bearIn, uint256 glUsdOut);

DeployedToCurve

event DeployedToCurve(address indexed caller, uint256 usdcDeployed, uint256 bearDeployed, uint256 lpMinted);

SolverLpPurchased

event SolverLpPurchased(address indexed solver, uint256 lpIn, uint256 usdcOut);

SolverLpSold

event SolverLpSold(address indexed solver, uint256 lpOut, uint256 usdcIn);

YieldHarvested

event YieldHarvested(uint256 glUsdMinted, uint256 callerReward, uint256 donated);

TokenRescued

event TokenRescued(address indexed token, address indexed to, uint256 amount);

EmergencyWithdrawCurve

event EmergencyWithdrawCurve(uint256 lpBurned, uint256 usdcReceived, uint256 bearReceived);

StakedInvarCoinProposed

event StakedInvarCoinProposed(address indexed stakedInvarCoin, uint256 activationTime);

StakedInvarCoinSet

event StakedInvarCoinSet(address indexed stakedInvarCoin);

GaugeProposed

event GaugeProposed(address indexed gauge, uint256 activationTime);

GaugeUpdated

event GaugeUpdated(address indexed oldGauge, address indexed newGauge);

GaugeRewardsReceiverProposed

event GaugeRewardsReceiverProposed(address indexed receiver, uint256 activationTime);

GaugeRewardsReceiverSet

event GaugeRewardsReceiverSet(address indexed receiver);

RewardTokenProtected

event RewardTokenProtected(address indexed token);

GaugeStaked

event GaugeStaked(uint256 amount);

GaugeUnstaked

event GaugeUnstaked(uint256 amount);

GaugeRewardsClaimed

event GaugeRewardsClaimed();

GaugeRewardsSwept

event GaugeRewardsSwept(address indexed token, address indexed receiver, uint256 amount);

UsdcDonated

event UsdcDonated(address indexed donor, uint256 usdcAmount, uint256 invarMinted);

GaugeForceRemoved

event GaugeForceRemoved(address indexed gauge, uint256 lpLost);

Errors

InvarCoin__ZeroAmount

error InvarCoin__ZeroAmount();

InvarCoin__StakingNotSet

error InvarCoin__StakingNotSet();

InvarCoin__ZeroAddress

error InvarCoin__ZeroAddress();

InvarCoin__SlippageExceeded

error InvarCoin__SlippageExceeded();

InvarCoin__NothingToDeploy

error InvarCoin__NothingToDeploy();

InvarCoin__NoYield

error InvarCoin__NoYield();

InvarCoin__CannotRescueCoreAsset

error InvarCoin__CannotRescueCoreAsset();

InvarCoin__PermitFailed

error InvarCoin__PermitFailed();

InvarCoin__AlreadySet

error InvarCoin__AlreadySet();

InvarCoin__SpotDeviationTooHigh

error InvarCoin__SpotDeviationTooHigh();

InvarCoin__UseLpWithdraw

error InvarCoin__UseLpWithdraw();

InvarCoin__Unauthorized

error InvarCoin__Unauthorized();

InvarCoin__NoStakers

error InvarCoin__NoStakers();

InvarCoin__GaugeTimelockActive

error InvarCoin__GaugeTimelockActive();

InvarCoin__StakingTimelockActive

error InvarCoin__StakingTimelockActive();

InvarCoin__GaugeRewardsTimelockActive

error InvarCoin__GaugeRewardsTimelockActive();

InvarCoin__InvalidProposal

error InvarCoin__InvalidProposal();

InvarCoin__NoGauge

error InvarCoin__NoGauge();

InvarCoin__EmergencyActive

error InvarCoin__EmergencyActive();

InvarCoin__InvalidGauge

error InvarCoin__InvalidGauge();

InvarCoin__InvalidStakingVault

error InvarCoin__InvalidStakingVault();

InvarCoin__GaugeRewardsReceiverNotSet

error InvarCoin__GaugeRewardsReceiverNotSet();

InvarCoin__NotEmergency

error InvarCoin__NotEmergency();