System Architecture

Technical Deep Dive

This document explains the technical architecture of the 5xFaction protocol.

---

High-Level Architecture

---

Contract Architecture

FiveFaction Contract

---

Epoch Timing Architecture

7-Day Epoch Structure

Duration Constants

// In the smart contract
uint256 public constant DEPOSIT_PHASE_DURATION = 2 days;  // 172800 seconds
uint256 public epochDuration = 7 days;                     // 604800 seconds
// Lock Phase = epochDuration - DEPOSIT_PHASE_DURATION = 5 days

---

State Management

On-Chain State

Frontend State

State	Source	Update Frequency
User Balance	useUSDCBalance	On transaction
User Stake	useWarriorInfo	On transaction
Allowance	useUSDCAllowance	On approval
All TVLs	useAllClanTVLs	Polling (5s)
All Scores	useAllScores	Polling (5s)
Epoch Time	useEpochStartTime	Polling (30s)
Deposit Phase Duration	useDepositPhaseDuration	Once
Epoch Duration	useEpochDuration	Once

---

Transaction Flows

Stake Flow

Epoch Resolution Flow

---

Scoring Algorithm

Pentagon Relationship Matrix

         SHADOW  BLADE  SPIRIT  PILLAR  WIND
SHADOW      0      -1      +1      -1    +1
BLADE      +1       0      -1      +1    -1
SPIRIT     -1      +1       0      -1    +1
PILLAR     +1      -1      +1       0    -1
WIND       -1      +1      -1      +1     0

Where:

• +1 = Defeats (target)

• -1 = Defeated by (predator)

• 0 = Self (neutral)

Score Calculation

function calculateScore(Clan clan) view returns (int256) {
    (Clan target1, Clan target2) = getClanTargets(clan);
    (Clan pred1, Clan pred2) = getClanPredators(clan);

    int256 targetTVL = int256(clanTVL[target1]) + int256(clanTVL[target2]);
    int256 predatorTVL = int256(clanTVL[pred1]) + int256(clanTVL[pred2]);

    return targetTVL - predatorTVL;
}

---

Security Model

Access Control

Function	Access	Restriction
joinClan	Public	Deposit phase only (Days 1-2)
stakeInk	Public	Deposit phase only (Days 1-2)
withdrawInk	Public	Anytime
clearCanvas	Public	After 7 days elapsed
mint (USDC)	Public	Testnet only

Phase Enforcement

modifier onlyDepositPhase() {
    require(
        block.timestamp < epochStartTime + DEPOSIT_PHASE_DURATION,
        "DepositPhaseClosed"
    );
    _;
}

// joinClan and stakeInk use this modifier
// Enforces 2-day deposit window

Safety Mechanisms

---

Gas Optimization

Function	Estimated Gas
joinClan	~50,000
stakeInk	~120,000
withdrawInk	~100,000
clearCanvas	~150,000
approve	~45,000

---

Future Architecture (Mainnet)

Changes for mainnet:

• Integration with Aave V3 for real yield

• Price oracle for accurate valuations

• Multi-sig admin functions

• Timelock for upgrades

• Emergency pause capability

• Configurable epoch durations