Protocol Overview
Architecture
JamFi’s architecture combines a strictly defined on-chain core with a flexible off-chain service layer. All logic that affects user funds and protocol rules—pool and asset management, interest accrual and indexing, debt accounting, liquidation thresholds, and revenue distribution—is enforced by smart contracts. What does not need to live on-chain—multi-source price aggregation, real‑time risk computation, KYC/AML for high‑limit and institutional modes, integrations with payment networks, notifications, and analytics—runs off-chain and interacts with contracts through hardened interfaces. The result is a system that preserves transparency and immutability of financial rules while enabling rapid iteration, integrations, and scale.
The on-chain layer is centered around market contracts (pools, assets, positions, indexes), a utilization‑aware rate model, and a liquidation engine. Treasury and reward mechanics are part of the same layer and feed the protocol’s economics. The off-chain layer acts as the data and policy orchestrator: it aggregates oracle prices with deviation filters, computes risk in real time, manages compliance policies where required, and publishes metrics and events to users and partners. A simple rule of thumb governs the split: smart contracts define what is allowed, off-chain services optimize how it is executed—safely, quickly, and in compliance.
On-chain Components
The on-chain core includes the market manager, asset registry, rate model, liquidation engine, treasury/rewards, and governance. The market manager creates/configures markets, stores risk parameters and caps, accrues interest, accepts liquidity, and opens/repays debt. The asset registry whitelists tokens, links each market to a price oracle, and enforces per‑asset limits (supply/borrow caps, debt ceilings) to prevent concentration and orphan risks. The rate model derives borrower APR and supplier APY from market utilization (and may incorporate external volatility premia): when utilization is high, rates rise to attract liquidity; when utilization is low, rates fall to stimulate borrowing. The liquidation engine continuously evaluates position health and, if thresholds are breached, initiates controlled collateral seizure aimed at maximizing recovery while minimizing slippage. DAO contracts with timelock execution control parameter changes (thresholds, caps, rate curves), while the treasury module accrues and routes fee flows into rewards and other economic programs.
Below is a minimal interface for a market manager and its configuration, showing where the main control levers live. In practice, access control is role‑based (RBAC/ACL), upgrades use proxies (UUPS/Transparent), pausable guards exist for incidents, and events are designed for auditability
interface IPoolManager {
struct MarketConfig {
address asset; // ERC20
address oracle; // Price feed (USD 1e8/1e18)
uint16 collateralFactorBps; // 7500 = 75.00%
uint16 liqThresholdBps; // 8000 = 80.00%
uint16 liqBonusBps; // 500 = 5.00%
uint16 reserveFactorBps; // share of interest to treasury
uint256 supplyCap; // max supplied
uint256 borrowCap; // max borrowed
uint256 debtCeiling; // per-market debt ceiling
}
event Deposit(address indexed user, address indexed asset, uint256 amount, address onBehalfOf);
event Withdraw(address indexed user, address indexed asset, uint256 amount, address to);
event Borrow(address indexed user, address indexed asset, uint256 amount, address onBehalfOf);
event Repay(address indexed user, address indexed asset, uint256 amount, address onBehalfOf);
event Liquidate(address indexed liquidator, address indexed user, address debtAsset, uint256 repaid, address collateralAsset, uint256 seized);
function setMarketConfig(MarketConfig calldata cfg) external; // onlyGovernance
function getMarketConfig(address asset) external view returns (MarketConfig memory);
function deposit(address asset, uint256 amount, address onBehalfOf) external;
function withdraw(address asset, uint256 amount, address to) external;
function borrow(address asset, uint256 amount, address onBehalfOf) external;
function repay(address asset, uint256 amount, address onBehalfOf) external;
function accrueInterest(address asset) external; // index update
function updateRates(address asset) external; // utilization → APR/APY
function liquidate(
address user,
address debtAsset,
uint256 maxRepay,
address collateralAsset,
address receiver
) external returns (uint256 repaid, uint256 seized);
}The rate model and oracle layer are separated so implementations can be swapped without migrating market state. Interfaces are intentionally narrow: callers pass an asset and utilization to get normalized rates; oracles return a price with a freshness timestamp for validation.
interface IRateModel {
function borrowAPR(address asset, uint256 utilizationWad) external view returns (uint256 aprWad);
function supplyAPY(address asset, uint256 utilizationWad) external view returns (uint256 apyWad);
}
interface IOracle {
/// @return price (USD 1e8/1e18), lastUpdate (unix)
function getPrice(address asset) external view returns (uint256 price, uint256 lastUpdate);
}Liquidations use a safe collateral seizure and an optional Dutch style descending price auction. Below is a simplified quoting and auction step. Production code adds anti MEV techniques, batch repayments for large positions, and strict slippage limits.
contract LiquidationEngine {
uint256 public constant WAD = 1e18;
function quoteSeize(
uint256 debtValue, // in base currency (USD)
uint16 liqBonusBps // liquidator bonus
) public pure returns (uint256 seizeValue) {
// seize >= debt * (1 + bonus)
seizeValue = (debtValue * (10_000 + liqBonusBps)) / 10_000;
}
// Linear auction price decay
function auctionPrice(
uint256 startValue,
uint256 minValue,
uint256 startTime,
uint256 duration
) public view returns (uint256) {
if (block.timestamp <= startTime) return startValue;
if (block.timestamp >= startTime + duration) return minValue;
uint256 elapsed = block.timestamp - startTime;
return startValue - ((startValue - minValue) * elapsed) / duration;
}
}Health checks are computed deterministically on-chain so liquidation triggers are transparent. The helper below shows the HF formula with WAD scaling; real aggregation sums multiple collaterals and debts with oracle‑normalized prices.
library HealthLib {
/// HF = (CollateralValue * liqThresholdBps / 10_000) / DebtValue
function healthFactor(
uint256 collateralValue,
uint256 debtValue,
uint16 liqThresholdBps
) internal pure returns (uint256 hfWad) {
if (debtValue == 0) return type(uint256).max;
uint256 adj = (collateralValue * liqThresholdBps) / 10_000;
return (adj * 1e18) / debtValue; // WAD
}
}Off-chain Services
The off-chain layer provides the protocol’s “senses” and “service harness.” A price aggregator collects quotes from multiple sources, normalizes decimals, applies deviation/sanity checks, and only then exposes the result on-chain—mitigating single‑feed anomalies and volatility spikes. On top of the price stream, a risk engine maintains continuous portfolio valuations: it computes total collateral and debt in a base currency, simulates shocks and volatility, forms margin alerts, and when necessary initiates liquidation via on-chain interfaces.
Compliance policies are activated for high‑limit and institutional flows. The module manages KYC/AML profiles, sanctions screening, and regional restrictions; it does not undermine decentralization—advanced limits are policy‑gated, while baseline on-chain operations remain permissionless within global protocol limits.
Analytics & notifications publish metric feeds (TVL, utilization, liquidation incidents, revenue by source) to dashboards and deliver user/integrator events: rate changes, approaching margin triggers, market parameter updates, and new DAO votes. Stable APIs/webhooks and event subscriptions allow partners to build products on top of JamFi.
Markets and Pools
JamFi organizes liquidity into independent markets, each bound to a single underlying asset and a dedicated set of risk parameters. Markets are isolated by design: collateral enablement, borrowability, and debt ceilings can be configured per‑asset so that risk does not cascade across unrelated assets. Supply and borrow caps act as hard safety rails, while utilization is monitored continuously to keep markets within healthy operating ranges without manual intervention. Where required, specialized markets can be flagged as isolated so that borrowing in those markets is only permitted against approved collaterals with stricter thresholds.
Every market is defined by a compact configuration that the protocol enforces on‑chain. The snippet below illustrates the per‑asset risk profile and liquidity controls. Governance sets these parameters via timelocked proposals; run‑time checks in the market manager prevent configuration drift and concentration beyond allowed caps.
struct AssetRiskParams {
address asset; // ERC20
address oracle; // price feed
uint16 ltvBps; // max borrow vs collateral (e.g., 6500)
uint16 liqThresholdBps; // liquidation threshold (e.g., 8000)
uint16 liqBonusBps; // bonus to liquidator (e.g., 600)
uint16 reserveFactorBps; // interest share to treasury
uint256 supplyCap; // max supplied amount
uint256 borrowCap; // max outstanding borrows
uint256 debtCeiling; // total market debt limit
bool collateralEnabled; // asset can be pledged as collateral
bool borrowable; // asset can be borrowed
bool isolated; // restricts cross‑market exposure
}From a state perspective, a market tracks cash, borrows, reserves, and interest indexes. Accrual and index updates are deterministic and triggered on interaction, ensuring predictable accounting. The exact rate curves are covered in the Rates page; here we show where utilization and index math plug into the market state.
struct MarketState {
uint256 cash; // idle liquidity
uint256 borrows; // total principal (in units of asset)
uint256 reserves; // protocol reserves
uint256 borrowIndex; // index-scaled accumulator
uint256 supplyIndex; // index-scaled accumulator
uint40 lastAccrual; // timestamp of last accrual
}
library MarketMath {
uint256 constant WAD = 1e18;
/// U = borrows / (cash + borrows - reserves)
function utilization(uint256 cash, uint256 borrows, uint256 reserves) internal pure returns (uint256 uWad) {
uint256 denom = cash + borrows - reserves;
if (denom == 0) return 0; // empty market
return (borrows * WAD) / denom;
}
}Price integrity is enforced through the oracle abstraction. The protocol normalizes decimals, rejects stale or deviating feeds, and falls back to secondary sources when necessary. Prices are always returned alongside a freshness marker so that on‑chain logic can short‑circuit sensitive operations if data quality is insufficient.
interface IOracleAggregator {
/// Returns normalized USD price (WAD) and freshness flag
function priceWad(address asset) external view returns (uint256 priceWad, bool fresh);
}
contract OracleGuard {
uint256 public maxAge = 60; // seconds
uint256 public maxDeviationBps = 50; // 0.50%
function validate(uint256 pRef, uint256 pAlt, uint256 updatedAt) public view returns (bool ok) {
if (block.timestamp - updatedAt > maxAge) return false;
uint256 hi = pRef > pAlt ? pRef : pAlt;
uint256 lo = pRef > pAlt ? pAlt : pRef;
return (hi - lo) * 10_000 / hi <= maxDeviationBps;
}
}Operationally, a pool’s lifecycle is straightforward. Liquidity providers deposit the underlying token and receive index‑accruing claims; borrowers post enabled collateral and draw the borrowable asset within LTV and cap constraints. Each user’s position aggregates across markets into a portfolio whose health is evaluated in a single base currency using oracle prices. If health deteriorates due to price moves or utilization shifts, the liquidation engine can seize collateral per the configured liquidation threshold and bonus, with execution paths chosen to minimize slippage and maximize recovery.
Markets can be reconfigured by governance as liquidity and risk evolve. Typical adjustments include tightening or loosening supply/borrow caps, changing reserve factors, enabling or disabling collateralization for a given asset, and updating oracle sources. Changes are timelocked, announced via events, and picked up by off‑chain services so integrators and users can react ahead of enforcement. This governance cadence—coupled with deterministic accounting and clear isolation boundaries—keeps individual pools robust while preserving composability across the wider protocol.
Risks and Liquidations
JamFi’s risk management framework is embedded at the smart contract level and reinforced by off-chain monitoring, ensuring that lenders remain protected while borrowers have predictable conditions. Every market is governed by parameters such as collateral factor, liquidation threshold, and close factor, codified directly in immutable risk contracts. Collateral factors determine the maximum borrowing power of each asset, while liquidation thresholds define the point at which collateral becomes unsafe and eligible for liquidation.
The protocol continuously evaluates borrower health using the health factor (HF) metric:
function healthFactor(address user) external view returns (uint256) {
uint256 collateralValue = Oracle.getCollateralValue(user);
uint256 borrowedValue = Oracle.getBorrowedValue(user);
if (borrowedValue == 0) return type(uint256).max;
return collateralValue * 1e18 / borrowedValue;
}An HF below 1.0 signals insolvency risk, automatically making the position eligible for liquidation. Liquidators interact with the LiquidationEngine contract, repaying part of the borrower’s debt in exchange for a discounted portion of collateral. Discounts (liquidation bonuses) are asset-specific and are parameterized to encourage timely intervention without over-penalizing borrowers.
Liquidations follow a Dutch auction mechanism for larger volumes, starting at a small premium and gradually reducing until matched by liquidators, minimizing slippage and protecting overall pool solvency. For retail-sized liquidations, JamFi employs fixed-discount instant liquidations to ensure speed. The system distributes recovered collateral with priority to lenders, while a small portion (typically 5-10%) is redirected to the insurance fund.
Borrowers receive automated margin calls before liquidation triggers. The monitoring service pushes alerts via the app, email, and optional SMS, giving a grace period to add collateral or repay part of the loan. Additionally, refinancing is integrated into the liquidation flow: rather than immediate seizure, the borrower can roll over debt under revised parameters (e.g., higher collateral ratio, adjusted rate).
To reduce oracle manipulation risk, JamFi aggregates multi-source feeds (Chainlink, Pyth, internal signed feeds from CEX partners) and applies medianization. In stress scenarios like flash loan attacks, the liquidation engine can be temporarily paused by a DAO-controlled timelock guardian, buying time for governance or emergency modules to intervene.
The insurance fund, seeded with treasury reserves and replenished by protocol fees, provides partial coverage for lender losses in the unlikely event of cascade failures. This creates a final safety net that, together with the overcollateralization design, ensures that systemic insolvency remains statistically improbable.
Protocol Economics and Revenue
JamFi’s economics are built around diversified revenue streams and transparent allocation to ensure both sustainability of the protocol and value accrual for $JAMI holders. Core revenue is generated from loan interest spreads, fees on payments and cross‑border transfers, card transaction fees, and flash loan charges. Loan activity is the largest contributor, with borrowers paying variable rates tied to utilization and risk. Payment and transfer flows add steady volume‑based revenue at 0.1–0.5%, while card operations capture 1–2% in merchant fees. Flash loans, although niche, provide consistent incremental yield.
All revenues accrue into the protocol treasury and are distributed programmatically. Forty percent is directed toward $JAMI buybacks and rewards for stakers, directly linking platform growth to tokenholder value. Thirty percent is returned as ecosystem incentives—APY boosts for liquidity providers, participation rewards for DAO voters, and growth campaigns. Twenty percent is reserved for operational expenses such as audits, infrastructure, and integrations. The remaining ten percent builds a strategic reserve under DAO governance, ensuring resilience against shocks and funding for long‑term expansion.
Scaling projections demonstrate the compounding effect of adoption. At $50M TVL, JamFi generates around $3.2M annually; at $200M, $12.8M; at $500M, $32M; and at $1B, approximately $80M. Profit margins improve as fixed costs dilute, rising from ~60% at lower scales to ~75% at higher TVLs. This growth translates directly into stronger buybacks and higher staker rewards, creating a self‑reinforcing loop where liquidity and participation increase as protocol revenues expand.
By enforcing deterministic allocation and maintaining full on‑chain transparency, JamFi ensures that participants can trust the revenue model and predict the flows of value. The outcome is an economic engine that rewards users, sustains operations, and continuously strengthens the $JAMI token’s role at the center of the ecosystem.
Integrations and Infrastructure
JamFi is designed as a composable protocol that integrates seamlessly with both on-chain and off-chain infrastructure. At the data layer, the protocol relies on multi-source oracles such as Chainlink, Pyth, and proprietary signed feeds, with medianization and deviation checks ensuring data integrity. Fallback logic is in place to reject stale or inconsistent prices, which prevents manipulation during periods of high volatility. Bridges connect JamFi across networks—Ethereum, BNB Chain, Solana, and selected L2/L3 ecosystems—providing liquidity routing and enabling users to interact with JamFi markets regardless of the chain they primarily operate on.
At the financial infrastructure level, JamFi is integrated with payment rails through partners such as Visa, Mastercard, and regulated local providers. These integrations allow credit and staking flows to directly connect to real-world transactions, including card payments and cross-border transfers. Settlement layers are modular, so new partners or networks can be added without disrupting existing services.
From an operational standpoint, JamFi’s backend is architected for high availability and resilience. The protocol targets SLA >99.9%, with auto-scaling infrastructure that can adjust dynamically to spikes in transaction volume. Observability is built into the stack, with real-time monitoring of key indicators such as TVL, utilization, liquidation events, and system latency. Automated incident detection and recovery processes ensure rapid mitigation, keeping downtime and user impact minimal.
Security is central to JamFi’s infrastructure strategy. The protocol undergoes regular third-party audits and runs continuous internal testing on stress scenarios, flash-loan resistance, and oracle manipulation attempts. Bug bounty programs incentivize external researchers to probe the system, while insurance pools add a financial safety net. Multi-sig safeguards and DAO-controlled timelocks govern critical upgrades, ensuring decentralization and protection against operator misuse.
This layered approach to integrations and infrastructure ensures that JamFi remains composable with the broader DeFi ecosystem, interoperable across chains, connected to real-world financial rails, and robust enough to scale globally without compromising on security or reliability.
User Journeys
JamFi is structured to support distinct user journeys that cover the core interactions within the protocol while maintaining a unified architecture underneath. Each journey is optimized for simplicity at the interface layer and determinism at the contract layer, ensuring that end-users—whether individuals or businesses—can participate without navigating unnecessary complexity
Liquidity providers
For liquidity providers, the journey begins with depositing assets into a chosen market. Upon deposit, they receive interest-bearing claims that automatically accrue yield based on utilization and rate models. Their position is visible in the dashboard as a growing balance, boosted further when holding or staking $JAMI. Providers can withdraw at any time, with accrued interest calculated deterministically via on-chain indexes. Risk is minimized through clear visibility into utilization, collateral composition, and reserve factors.
Borrowers
For borrowers, the flow starts with posting collateral. Eligible assets are locked into the protocol, and the user can then draw loans up to their allowed loan-to-value ratio. Borrowers see real-time health factor calculations, receive automated alerts if their positions approach liquidation thresholds, and can respond by adding collateral, partially repaying, or initiating refinancing to adjust terms without closing the position. Integration with off-chain services ensures borrowers are notified across channels before their positions deteriorate.
Card users
For card users, the journey extends beyond the protocol’s on-chain core into real-world spending. Borrowed or supplied liquidity can be transferred seamlessly onto JamFi’s virtual or physical cards, enabling direct purchases in fiat while still linking back to on-chain accounting. Transactions generate cashback in $JAMI, and a share of card fees is recycled into protocol buybacks, tying individual user actions to the broader token economy.
Businesses
For businesses, JamFi supports enterprise-oriented flows such as batch payouts and invoice financing. APIs allow firms to integrate directly with the protocol, automating mass disbursements to employees or suppliers in stablecoins or local fiat. Risk modules apply the same real-time monitoring and margin rules to business positions, ensuring institutional usage adheres to the same security guarantees as retail.
Metrics and Monitoring
JamFi maintains a comprehensive monitoring framework that provides transparency to users, governance, and integrators, while ensuring that the protocol remains robust under varying market conditions. Core metrics include TVL, utilization rates of each market, interest rate levels, and aggregate default or liquidation events. These metrics are derived directly from smart contract state and are exposed in real time through both on-chain views and off-chain analytics dashboards.
From a revenue perspective, JamFi tracks income streams segmented by source: loan interest, payment and transfer fees, card fees, and flash loan revenue. These figures feed into the Treasury reporting cycle, allowing participants to verify buybacks, reward distributions, and reserve growth against transparent data. Revenue analytics also include efficiency ratios—such as revenue per dollar of TVL and protocol profit margins—that indicate the health and scalability of the business model.
User activity is another essential dimension. Metrics cover the number of active depositors and borrowers, growth in card issuance and spending volume, and retention statistics over time. These data points allow governance to understand adoption patterns and to fine-tune incentive programs. On the institutional side, JamFi monitors enterprise API usage, batch payouts volume, and liquidity concentration to ensure balanced exposure across counterparties.
Governance metrics ensure accountability of the DAO. Quorum attainment, voter participation rates, proposal throughput, and execution latency under timelock conditions are all published to the community. These metrics make governance performance visible and inform whether additional incentive structures or reforms are required.
From a systems reliability perspective, Site Reliability Engineering standards apply. Metrics such as uptime, request latency, error rates, and mean time to recovery are tracked continuously. Automated alerts are triggered for anomalies, and incident reports are published post-mortem to maintain transparency.
Last updated