Token System Specifications

Overview

Token	Type	Purpose	Standard
fUSD	Stablecoin	Entry asset, 1:1 backed by approved stablecoins	ERC20 (Upgradeable)
sfUSD	Share Token	Yield-bearing staked position	ERC20 (Upgradeable)

Both tokens are upgradeable via the UUPS (Universal Upgradeable Proxy Standard) pattern, allowing the protocol to evolve while preserving user balances and state.

---

fUSD : Frgmnt Stable Asset

Token Details

Property	Value
Name	fUSD
Symbol	fUSD
Decimals	18
Standard	ERC20Upgradeable
Upgrade Pattern	UUPS

Minting Mechanism

fUSD is minted through deposits of approved stablecoins. The mint amount is calculated using oracle-sourced USD prices:

fUSD Minted = Deposit Amount × Oracle Price

Approved Assets: The protocol maintains a whitelist of accepted stablecoins (e.g., USDC, DAI, USDT). Each asset must be explicitly approved through governance before it can be used for minting.

Deposit Flow

1. User approves stablecoin spending for fUSD contract

2. User calls deposit with approved stablecoin

3. Contract validates asset is on the allowlist

4. Oracle provides current USD price for the asset

5. Deposit transfers to the sfUSD sink (staking pool)

6. fUSD minted to user at equivalent USD value

Access Control

Role	Permissions
DEFAULT_ADMIN_ROLE	Grant and revoke other roles
GOVERNANCE_ROLE	Manage oracle, sfUSD sink, allowed assets, authorize upgrades
EMERGENCY_ROLE	Pause/unpause deposits

Security Features

• Reentrancy Guard : Prevents recursive call exploits

• Pausable : Emergency pause capability for deposits

• Role-Based Access : Granular permission system

---

sfUSD : Staked FUSD

Token Details

Property	Value
Name	Staked fUSD (configurable)
Symbol	sfUSD (configurable)
Decimals	18
Standard	ERC20Upgradeable
Upgrade Pattern	UUPS

Share Pricing

sfUSD uses a share-based model where the token price represents the value of one sfUSD share in terms of underlying assets:

Token Price = Total Pool Value / Total sfUSD Supply

As the pool generates yield, the token price increases, meaning each sfUSD share is worth more over time.

Staking (fUSD → sfUSD)

When staking fUSD, shares are minted based on the current token price:

Shares Minted = fUSD Deposited / Token Price

Entry Fee: Applied as additional shares minted to the manager; not deducted from the user's deposit. This means users receive shares worth their full deposit amount.

User Shares = fUSD Deposited / Token Price
Fee Shares = User Shares × Entry Fee Rate
Manager Receives = Fee Shares

Unstaking (sfUSD → Assets)

Immediate Mode: Users burn sfUSD and receive proportional pool assets instantly.

Assets Received = (Shares Burned / Total Supply) × Pool Value

Exit Fee: Applied as shares burned from the user before calculating withdrawal amount.

Effective Shares = User Shares × (1 - Exit Fee Rate)
Assets = (Effective Shares / Total Supply) × Pool Value

Queued Mode: For pools with queued withdrawals enabled:

1. requestWithdraw(shares) Lock shares, receive request ID

2. Manager calls finalizeWithdraw(requestId) Burns shares, locks fUSD amount

3. claimWithdraw(requestId) User receives finalized fUSD

Yield Mechanics

sfUSD implements a dual yield system that separates principal appreciation from harvestable rewards:

1. Token Price Growth (Principal Appreciation)

The core share price increases as the pool generates value:

Token Price = Total Fund Value / Total sfUSD Supply

This happens automatically as:

• Strategy positions generate PnL

• The pool collects fees from other activities

• External yield sources accrue to the pool

2. Harvestable Yield Accumulator

A separate mechanism converts token price growth into claimable fUSD rewards using a global accumulator pattern:

Variable	Purpose
yieldPerShare	Cumulative fUSD yield per share (scaled 1e18)
lastTokenPriceForYield	Token price checkpoint for yield calculation
userYields[address].rewardDebt	User's last yieldPerShare checkpoint
userYields[address].claimable	Accumulated fUSD pending harvest

How it works:

On every user interaction (stake, unstake, harvest), the updateFeesAndYieldFor modifier:

1. Mints any pending manager fees

2. Calculates current token price

3. If price increased since lastTokenPriceForYield:

   gain = currentPrice - lastTokenPriceForYieldyieldPerShare += gainlastTokenPriceForYield = currentPrice

4. For the specific user:

   delta = yieldPerShare - user.rewardDebtearned = (userBalance × delta) / 1e18user.claimable += earneduser.rewardDebt = yieldPerShare

Harvesting:

Users call harvest() to claim accumulated fUSD without touching their sfUSD shares:

function harvest() external {
    uint256 amount = userYields[msg.sender].claimable;
    require(amount > 0, "nothing to harvest");
    userYields[msg.sender].claimable = 0;
    // Transfer FUSD to user
}

This design means users can choose to:

• Hold sfUSD and let both principal and harvestable yield compound

• Harvest regularly to realize fUSD gains while maintaining their staked position

• Unstake to exit entirely with their proportional share of pool assets

Fee Minting

Performance and management fees are minted as new sfUSD shares to the manager and DAO:

Fee Type	Mechanism
Performance Fee	Percentage of token price growth since tokenPriceAtLastFeeMint
Management Fee	Time-weighted streaming fee based on lastFeeMintTime

// Performance fee calculation
if (currentTokenPrice > tokenPriceAtLastFeeMint) {
    feeUsdAmount = (priceGain × performanceFeeNumerator × totalSupply) / denominator
    performanceFee = (feeUsdAmount × totalSupply) / (fundValue - feeUsdAmount)
}

// Streaming (management) fee calculation  
timeChange = block.timestamp - lastFeeMintTime
streamingFee = (totalSupply × timeChange × managerFeeNumerator) / denominator / 365 days

The DAO receives a percentage of total fees (configured in factory), remainder goes to the manager. This dilutes all holders proportionally rather than transferring from individual accounts.

Withdrawal Modes

Mode	Behavior
Immediate	Direct burn-for-assets, subject to liquidity and cooldown
Queued	Lido-style: lock shares → manager finalizes → user claims

Pool managers can toggle between modes based on pool strategy requirements.

Queued Withdrawal Flow:

1. Request (requestWithdraw): User locks sfUSD shares, exit fee taken upfront in shares

2. Finalize (finalizeWithdraw): Manager burns the locked shares, calculates fUSD amount at current price

3. Claim (claimWithdraw): User receives the finalized fUSD amount

This pattern allows managers to handle illiquid positions gracefully without forcing immediate liquidation.

---

Pool Manager Logic Integration

Both tokens integrate with PoolManagerLogic for:

Asset Management

// Supported assets for the pool
function getSupportedAssets() → Asset[]
function getDepositAssets() → address[]
function isSupportedAsset(address) → bool
function validateAsset(address) → bool

Valuation

// Price and composition queries
function assetValue(address asset) → uint256          // Total USD value
function assetValue(address asset, uint256 amount) → uint256
function totalFundValue() → uint256                   // Pool TVL in USD
function getFundComposition() → (assets[], balances[], rates[])

Fee Configuration

// Fee parameters (all in basis points relative to denominator)
function getFee() → (
  performanceFeeNumerator,
  managerFeeNumerator,
  entryFeeNumerator,
  exitFeeNumerator,
  denominator
)

Fee Changes: Fee increases require an announcement period before they can be committed, protecting users from sudden changes:

1. announceFeeIncrease() Propose new fees

2. Wait for timelock period

3. commitFeeIncrease() Apply new fees

4. Or renounceFeeIncrease() Cancel proposal

Access Control

// Membership verification
function isMemberAllowed(address) → bool
function isNftMemberAllowed(address) → bool

Pools can be configured as private (whitelist only) or public, with optional NFT-gated access.

---

Guard System

All external protocol interactions are validated through a two-layer guard system managed by the Governance contract:

Contract Guards

Assigned per external contract address (e.g., Aave, Uniswap routers). When sfUSD calls execTransaction():

1. The guard's txGuard() function parses the calldata

2. Returns a txType (transaction classification) and isPublic flag

3. If txType > 0, the transaction is allowed

4. If not public, only manager or trader can execute

Governance.contractGuards(externalContract) → guardAddress

Available contract guards include:

• AaveLendingPoolGuardV2/V3 Deposit, withdraw, borrow, repay

• UniswapV2RouterGuard Swaps and liquidity operations

• UniswapV3RouterGuard V3 swaps with path validation

• MorphoContractGuard Morpho lending operations

• CompoundV3CometContractGuard Compound V3 supply/withdraw

Asset Guards

Assigned per asset type ID. Handle balance calculation and withdrawal processing for different asset classes:

Governance.assetGuards(assetType) → guardAddress

Transaction Execution Flow

function _execTransaction(address to, bytes data) private {
    // 1. Check contract guard first
    address contractGuard = factory.getContractGuard(to);
    (txType, isPublic) = IGuard(contractGuard).txGuard(poolManagerLogic, to, data);
    
    // 2. Fall back to asset guard if no contract guard match
    if (txType == 0) {
        address assetGuard = factory.getAssetGuard(to);
        (txType, isPublic) = IGuard(assetGuard).txGuard(poolManagerLogic, to, data);
    }
    
    // 3. Validate authorization
    require(txType > 0, "invalid transaction");
    require(isPublic || msg.sender == manager || msg.sender == trader);
    
    // 4. Execute and run post-hooks if guard implements ITxTrackingGuard
    success = to.tryAssemblyCall(data);
    if (guard.isTxTrackingGuard()) {
        ITxTrackingGuard(guard).afterTxGuard(poolManagerLogic, to, data);
    }
}

Post-Transaction Hooks

Guards implementing ITxTrackingGuard can run logic after transaction execution:

• Uniswap V3 NFT Guard: Tracks minted/burned NFT position IDs

• Aave V3 L2 Guard: Validates health factor stays above 1.01

---

Events

fUSD Events

Event	Description
Deposit(user, asset, amount, fusdMinted)	User deposited stablecoins for fUSD

sfUSD Events

Event	Description
Stake(user, fusdAmount, mintedShares, entryFeeShares)	User staked fUSD
Harvest(user, fusdAmount)	User claimed yield
WithdrawRequested(id, user, sharesLocked, exitFeeShares)	Queued withdrawal initiated
WithdrawFinalized(id, fusdAmount)	Manager finalized withdrawal
WithdrawClaimed(id, user, fusdAmount)	User claimed withdrawal
ManagerFeeMinted(pool, manager, available, daoFee, managerFee, tokenPrice)	Fees minted
TransactionExecuted(pool, manager, txType, time)	Guarded transaction completed

---

Security Considerations

Reentrancy Protection

Both tokens implement ReentrancyGuardUpgradeable on all state-changing external functions.

Cooldown Mechanisms

sfUSD implements a weighted cooldown system to prevent flash-loan exploits:

Storage Variable	Purpose
lastDeposit[address]	Timestamp of user's last stake
lastExitCooldown[address]	Calculated cooldown duration for user

Cooldown Calculation:

When staking, the cooldown is weighted based on new vs existing position size:

function _calculateCooldown(
    currentBalance,
    liquidityMinted,
    newCooldown,        // from factory.getExitCooldown()
    lastCooldown,
    lastDepositTime,
    blockTimestamp
) {
    remainingCooldown = max(0, lastDepositTime + lastCooldown - blockTimestamp);
    
    if (currentBalance == 0) return newCooldown;
    if (liquidityMinted == 0) return remainingCooldown;
    
    // Weight new cooldown by deposit ratio
    aggregated = (newCooldown × liquidityMinted / currentBalance) + remainingCooldown;
    return min(aggregated, newCooldown);
}

Transfer Restriction:

The _update() hook blocks transfers if cooldown is active, unless the recipient is whitelisted:

if (!factory.receiverWhitelist(to)) {
    require(getExitRemainingCooldown(from) == 0, "cooldown active");
}

Upgrade Safety

Storage layout must be preserved across upgrades:

• Never remove or rename existing state variables

• Append new variables before __gap

• Maintain __gap array for future expansion

Decimal Handling

All calculations account for varying decimals across stablecoins. Oracle prices normalize to 18 decimals for consistent math.

---

Contract Addresses

Addresses will be published here after mainnet deployment.

Contract	Network	Address
fUSD Proxy	BASE - 8453	TBD
sfUSD Proxy	BASE - 8453	TBD
PoolManagerLogic	BASE - 8453	TBD
Governance	BASE - 8453BASE - 8453	TBD

---

Integration Guide

Reading Token Price

const sfusd = new ethers.Contract(SFUSD_ADDRESS, SFUSD_ABI, provider);

// Price including pending manager fees (what you'd get if fees were minted now)
const tokenPrice = await sfusd.tokenPrice();

// Raw price without pending fees
const rawPrice = await sfusd.tokenPriceWithoutManagerFee();

// tokenPrice is in 18 decimals
// e.g., 1.05e18 means 1 SFUSD = 1.05 FUSD worth of assets

Calculating Share Value

const userShares = await sfusd.balanceOf(userAddress);
const tokenPrice = await sfusd.tokenPrice();
const valueInFusd = userShares * tokenPrice / 10n**18n;

Checking Claimable Yield

// Read the user's yield state directly
const userYield = await sfusd.userYields(userAddress);
const claimable = userYield.claimable;

// Note: Additional yield may have accrued since last interaction
// Call harvest() to update and claim

Staking fUSD

const fusd = new ethers.Contract(FUSD_ADDRESS, FUSD_ABI, signer);
const sfusd = new ethers.Contract(SFUSD_ADDRESS, SFUSD_ABI, signer);

// 1. Approve SFUSD to spend FUSD
await fusd.approve(SFUSD_ADDRESS, amount);

// 2. Stake
await sfusd.stake(amount);

Harvesting Yield

// Claim accumulated FUSD yield without unstaking
await sfusd.harvest();

Unstaking (Immediate Mode)

const sharesToBurn = await sfusd.balanceOf(userAddress);

// Check cooldown first
const cooldownRemaining = await sfusd.getExitRemainingCooldown(userAddress);
if (cooldownRemaining > 0) {
    console.log(`Must wait ${cooldownRemaining} seconds`);
    return;
}

// Unstake - receives proportional share of all pool assets
await sfusd.unstake(sharesToBurn);