Bad Debt When a position’s loss exceeds its locked margin at the time of liquidation or settlement. The excess loss that cannot be covered by the trader’s margin is absorbed by pool equity, reducing share price for all LPs. Basis Points (bps) One hundredth of a percentage point. 100 bps = 1%. All percentage-based parameters in the protocol (margin factors, fee rates, spreads, exposure caps) are expressed in basis points using an integer denominator of 10,000. BPS_DENOMINATOR The constant
10,000 used as the denominator for all basis-point calculations onchain. For example,
a 2% initial margin factor is stored as 200 and applied as notional * 200 / 10,000.
CloseReason
An enum indicating why a position was closed. Possible values: NONE (position is still open),
MATURED (settled at the fixing price on the maturity date), LIQUIDATED (force-closed because
equity fell below maintenance margin), or EARLY_TERMINATION (closed by the trader before maturity).
Collateral
USDC deposited into a trader’s margin account via MarginAccounts.deposit(). Collateral backs
positions and pays fees. It exists as either free balance (available for new positions or withdrawal)
or locked margin (committed to an open position).
Config
The onchain contract that stores all configurable protocol parameters — margin factors, fee rates,
tenor durations, risk caps, oracle thresholds, and more. Parameters are modified by the admin via
role-gated setter functions.
Early Termination
Closing a position before its maturity date at the current forward price. Only the position owner
can trigger early termination. A trading fee and oracle fee are charged. PnL is calculated against
the entry strike using the current forward price rather than the fixing price.
Entry Strike
The forward price locked at the moment a position is opened. This is the reference price used for
all PnL calculations throughout the position’s lifetime. The entry strike is immutable — it never
changes regardless of market movements, margin adjustments, or partial reductions.
ERC-4626
An Ethereum standard for tokenized vaults. The PoolVault implements ERC-4626, allowing LPs to deposit
USDC and receive fungible share tokens. The standard defines a common interface for deposits,
withdrawals, share price calculation, and accounting.
Fixing Price
The EUR/USD spot price recorded at 4 PM UTC on the maturity business day. This is the canonical
settlement price for positions that reach maturity. The publisher records the fixing price onchain
via the OracleModule when the fixing timestamp is reached.
Fixing Timestamp
The exact UTC timestamp at which a position matures. Calculated from the open timestamp plus the
tenor duration, adjusted to 4 PM UTC on a business day. If the raw maturity falls on a weekend, the
fixing timestamp rolls forward to the next Monday at 4 PM UTC.
Forward Price
The predicted EUR/USD exchange rate for a specific future date, computed from the current spot price
using interest rate parity: F = S * (1 + r * t / (365 days * 10,000)). Forward prices are published
onchain by the publisher service and used for opening positions, early termination, liquidation, and
partial reduction.
Forward Rate
The annualized interest rate differential between EUR and USD, expressed in basis points. Used in the
forward price formula to adjust the spot price for the time value of money. Configurable per tenor
via the Config contract.
Gross Notional
The sum of all open position notionals, regardless of direction. A pool with 5,000 USDC in LONG
notional and 3,000 USDC in SHORT notional has a gross notional of 8,000 USDC. Used for utilization
calculations and risk cap checks.
Initial Margin (IM)
The minimum collateral required to open a position, expressed as a percentage of notional. Default:
200 bps (2%). A 10,000 USDC notional position requires at least 200 USDC as initial margin. Traders
can lock more than the minimum to reduce leverage and liquidation risk.
Isolated Margin
The margin model used by the protocol where each position has its own independent locked margin. A
liquidation on one position does not affect the margin, equity, or liquidation threshold of any other
position held by the same trader. Contrast with cross margin, where all positions share a common
margin pool.
Keeper
An off-chain service that monitors matured and liquidatable positions and triggers their settlement
or liquidation onchain. The keeper calls SettlementEngine.batchSettle() for matured positions and
SettlementEngine.liquidate() for underwater positions. These functions are permissionless — anyone
can call them.
Liquidation
Forced closure of a position when its equity drops below the maintenance margin threshold. Anyone
can trigger liquidation by calling SettlementEngine.liquidate(). The position is closed at the
current forward price, and a liquidation penalty (default 30 bps / 0.3% of notional) is deducted
from the trader’s remaining margin and accrues to the pool.
Liquidation Penalty
A fee charged when a position is liquidated, expressed in basis points of the position’s notional.
Default: 30 bps (0.3%). The penalty compensates the pool for the risk of bad debt and incentivizes
traders to manage their margin proactively.
Maintenance Margin (MM)
The minimum equity threshold below which a position becomes liquidatable. Default: 100 bps (1%) of
notional. A 10,000 USDC notional position has a maintenance margin of 100 USDC. If position equity
(locked margin + unrealized PnL) falls below this level, the position can be liquidated.
MarginAccounts
The onchain contract that manages trader collateral. Handles deposits, withdrawals, per-position
margin locking/unlocking, and PnL settlement flows between traders and the pool.
Mode
The protocol’s operating state, managed by the ModeController contract. Four modes form a severity
ladder: NORMAL (all operations permitted), DEGRADED (all operations permitted but with wider
spreads), REDUCE_ONLY (no new exposure — only closes, settlements, and liquidations), and
PAUSED (all operations halted).
ModeController
The onchain contract implementing the four-state operating mode machine. Mode transitions are
sequential: NORMAL to DEGRADED to REDUCE_ONLY to PAUSED (and back). Each escalation restricts
progressively more operations.
MockUSDC
The test USDC token deployed on Sepolia for development and testing. Has a public mint(address, uint256)
function that anyone can call to get test tokens. Uses 6 decimals, matching production USDC.
Net Exposure
The directional exposure of the pool, calculated as SHORT notional minus LONG notional. A positive
net exposure means the pool is net long (more SHORT positions open). A negative net exposure means
the pool is net short (more LONG positions open).
Notional
The face value of a forward position, denominated in USDC (6 decimals). A 10,000 USDC notional
position is stored onchain as 10,000,000,000 raw units. Notional determines PnL magnitude, fee
amounts, and margin requirements.
OracleModule
The onchain contract that manages price data. It stores Pyth spot prices (updated via pull oracle)
and publisher-pushed forward prices for each active fixing timestamp. Includes safeguard checks on
price movement, staleness, and deviation.
Oracle Fee
A flat fee charged for each forward price lookup during position open, close, or early termination.
Default: 0.10 USDC (100,000 raw units). Covers the cost of oracle infrastructure.
PnL (Profit and Loss)
The gain or loss on a position, calculated from the price difference scaled by notional. For LONG:
PnL = notional * (currentPrice - entryStrike) / 1e18. For SHORT:
PnL = notional * (entryStrike - currentPrice) / 1e18. PnL is unrealized while the position is
open and realized at close or settlement.
Pool Equity
The total value backing the liquidity pool, calculated as total pool assets plus the pool’s
unrealized PnL (which is the negative of aggregate trader PnL). Pool equity determines the share
price and the pool’s capacity to take on new positions.
PoolVault
The ERC-4626 vault contract where LPs deposit USDC and receive share tokens. The vault serves as
the counterparty to all trader positions. Its total assets fluctuate based on fee accrual, trader
PnL settlement, and LP deposits/withdrawals.
PositionManager
The onchain contract that manages the position lifecycle: opening new positions, increasing notional,
reducing notional, closing positions, and adjusting margin. It coordinates with OracleModule (for
prices), RiskManager (for cap checks), MarginAccounts (for collateral), and PoolVault (for exposure
tracking).
PRICE_PRECISION
The constant 1e18 used for all onchain price representation. EUR/USD 1.08 is stored as
1,080,000,000,000,000,000. This 18-decimal fixed-point format matches the standard EVM wei
convention and provides sufficient precision for FX pip-level accuracy.
Publisher
An authorized off-chain service that computes forward prices using interest rate parity from the
Pyth spot feed and submits them onchain via OracleModule.publishForwardRound(). Runs continuously
to keep forward curves fresh for all active tenors and fixing timestamps.
Pyth Network
A decentralized oracle network that provides the protocol’s EUR/USD spot price feed. The publisher
service fetches prices from Pyth’s Hermes API, and the OracleModule verifies Pyth price updates
onchain.
RiskManager
The onchain contract that enforces exposure limits at multiple levels: per-position notional caps,
per-account notional caps, pool-level gross notional caps, and rate-of-change throttling. Prevents
excessive concentration of risk.
SettlementEngine
The onchain contract that processes position closures at maturity, handles liquidations, and
executes early terminations. Calculates final PnL, applies fees and penalties, and orchestrates
fund flows between MarginAccounts and PoolVault.
Share Price
The value of one pool share token in USDC terms, calculated as pool equity divided by total shares
outstanding. Increases when the pool earns fees or traders lose money. Decreases when traders profit
or bad debt is absorbed.
Side
The direction of a forward position. LONG (enum value 0) profits when EUR/USD rises above the
entry strike. SHORT (enum value 1) profits when EUR/USD falls below the entry strike.
Snapshot
The set of parameters captured at position open time and stored immutably with the position. Includes
initial margin factor, maintenance margin factor, trading fee rate, liquidation penalty rate, and
oracle fee. Using snapshot parameters ensures that parameter changes by the admin do not
retroactively affect existing positions.
Spot Price
The current EUR/USD exchange rate as reported by Pyth Network. Used as the base input for forward
price computation, as the fixing price at maturity, and for oracle health monitoring. Stored onchain
with 18-decimal precision after conversion from Pyth’s native format.
Tenor
The maturity duration of a forward contract. Three tenors are available: ONE_DAY (24 hours /
86,400 seconds), ONE_WEEK (7 days / 604,800 seconds), and ONE_MONTH (30 days / 2,592,000
seconds). A TEST_60S tenor (60 seconds) is available in local development environments only.
Trading Fee
A fee charged on the position’s notional at open, close, and settlement events. Default: 5 bps
(0.05%) of notional. Fees are split between the pool (default 70%) and the protocol treasury
(default 30%).
USDC_PRECISION
The constant 1e6 matching the USDC token’s 6 decimal places. All monetary values (notional,
margin, PnL, fees) are denominated in raw USDC units. 1 USDC = 1,000,000 raw units.
Utilization
Gross notional as a percentage of pool total assets: utilization = grossNotional / totalAssets.
High utilization means the pool’s capital is heavily committed to backing open positions. Withdrawals
are restricted when utilization exceeds the maximum utilization cap (default 80%) to ensure the pool
can honor its obligations to open positions.
Zero-Sum
The fundamental economic property of the protocol: every unit of USDC gained by a trader is lost by
the pool, and every unit lost by a trader is gained by the pool. Expressed as TraderPnL + PoolPnL = 0
(excluding fees). Fees are the only value extracted from the system.