System Architecture

...& State Machine Overview

The 3 Protocol is implemented as three core, interoperable smart contract systems: The Guild, The Grove, and The Reserve, governed by a unified economic model and a user-sentiment-driven security framework. A dedicated Settlement Contract, under the remit of The Reserve, adjudicates the system's foundational stability pledge. This section provides a high-level specification of each protocol's purpose, its key interfaces, and the finite state machine governing the system's economic phase transitions.

2.1. Protocol Specifications & Interfaces

2.1.1. The Guild

• Purpose: The protocol for issuing the decentralised currency (GUILD) and managing its associated bond-based liquidity system.

• Core State Variables:

  • totalGUILDIssued: The outstanding supply of the currency.

  • totalAgedBonds: The quantity of Aged 3Bond NFTs outstanding.

• Key Interfaces:

  • mint(derivativeAsset, amount) → (GUILD, 3Fi): The primary issuance function. Accepts approved yield-bearing derivative tokens and mints GUILD & 3Fi based on the oracle price of the underlying asset.

  • createBond(crvUSD, type) → (adolescentBondTokenId): Accepts crvUSD to issue an Adolescent 3Bond (ERC-721 NFT).

  • ageBond(adolescentBondTokenId) → (agedBondTokenId): Converts a fully-vested Adolescent Bond to an Aged 3Bond NFT, representing a future claim on the Single-Sided Lending Pool (SSLP).

2.1.2. The Settlement Contract

• Purpose: Adjudicates the hard-coded settlement pledge (1 GUILD = 1 crvUSD). Users permanently stake GUILD, which is eventually burned 1:1 against allocated crvUSD.

• Core State Variables:

  • totalGUILDStaked: Total GUILD permanently committed by users awaiting crvUSD allocation.

  • userUnallocated[address]: Per-user balance of staked GUILD not yet matched with crvUSD.

  • userClaimable[address]: Per-user balance of crvUSD allocated and available for claim.

• Key Interfaces:

  • stakeForSettlement(amountGUILD): User permanently locks GUILD in the contract. Increases userUnallocated.

  • pushCrvUSD(amountCrvUSD): Any caller can forward crvUSD from The Grove's Holding Contract. Triggers the allocation algorithm:

    1. Calculate looseGUILD = totalGUILDIssued - totalGUILDBurned - (totalAgedBonds * 10_000).

    2. Calculate RV = looseGUILD / (totalGUILDIssued - totalGUILDBurned).

    3. Allocate incomingCrvUSD * RV to staked users pro-rata based on userUnallocated balances, moving value from userUnallocated to userClaimable. The remaining crvUSD is sent to The Reserve's Distribution Engine.

  • claimCrvUSD(): User transfers their userClaimable balance, burning a corresponding amount of their staked GUILD.

2.1.3. The Grove

• Purpose: The protocol for managing the protocol's and users' yield-bearing asset deposits through programmable yield directives (Signals).

• Core State Variables:

  • ProtocolHeldAssets (PHA): The total value of derivative assets (e.g., sdCRV, cvxCRV) owned and managed by the protocol.

  • totalRevenueGenerated: Accumulated yield (in crvUSD) harvested from PHA.

• Key Interfaces:

  • deposit(asset, amount, signal) → (3Receipt): Deposits an asset into a specific pool under a user-defined Signal (Self Compound or Boost).

  • setSignal(3Receipt, newSignal): Updates the yield directive for a deposit.

  • create3NFT(3Receipts[]) → (3NFTTokenId): Composes multiple 3Receipts into an NFT (ERC-721), which locks their Signal to a Liquidation Path for automated yield conversion to crvUSD.

  • harvest(3NFTTokenId): Triggers the liquidation of accrued yield for the specified 3.NFT, sending crvUSD to the Holding Contract.

2.1.4. The Reserve

• Purpose: The protocol governing the strategic treasury (The Vault), value distribution, ecosystem funding, and overarching governance.

• Core State Variables:

  • ActualReserves (AR): The total value of ETH held in The Vault.

  • ReserveRequirement (RR): The dynamic target for AR, defined by the active Reserve Requirement Curve (RRC).

  • totalVW3Minted: Always 4 * total3FiMinted.

  • totalVW3Claimed: VW3 weight actively staked by users or allocated to PODs.

• Key Interfaces:

  • distributeRevenue(crvUSD_amount): Called by the Settlement Contract with surplus crvUSD. Executes the revenue fork logic (see Section 4.2).

  • stake(3Fi_amount, lockupTime) → (VW3_weight): Locks 3Fi to generate and claim governance weight over time (max 4 VW3 per 3Fi over 4 years).

  • vote(POD_address, VW3_weight): Allocates claimed VW3 weight to a Purpose-Oriented Distributor (POD).

• Governance Nuance: The Distribution Engine calculates POD weights using claimed VW3. All unclaimed VW3 (totalVW3Minted - totalVW3Claimed) is automatically added to the weight of the Creditors POD, granting creditors (3Bond holders) a default, strategic governance advantage.

2.2. System State Machine & Phase Transitions

The protocol progresses through defined economic phases, governed by the relationship between ActualReserves (AR) and ReserveRequirement (RR). Transitions are automatic and based on on-chain metrics.

• State S0: Bootstrap

  • Condition: Initial deployment. AR ≈ 0.

  • Characteristics: Reliance on the Settlement Pledge is maximal. The system focuses on acquiring assets via GuildSwap FARM/ARBITRAGE. The RR is defined by RRC_Phase1, targeting a minimal ETH/GUILD backing ratio.

• State S1: Fortify

  • Condition: AR < RR. The system is below its strategic reserve target.

  • Action: The Distribution Engine allocates 67% of surplus revenue to PODs / 33% to The Vault to accelerate reserve growth.

• State S2: Thrive

  • Condition: AR >= RR. The system has met or exceeded its strategic reserve target.

  • Action: The Distribution Engine allocates 100% of surplus revenue to PODs. The system is considered self-sustaining, and the strategic reserve is sufficient to back the currency's stability.

• State Transition Trigger:

  • The check if (AR >= RR) is performed within every distributeRevenue() call. The transition between Fortify (S1) and Thrive (S2) is therefore continuous and automated.

  • A phase change from Bootstrap (S0) to Fortify (S1) is triggered by a governance-oracle update to the ReserveRequirementCurve, moving from RRC_Phase1 to RRC_Phase2, reflecting a higher target backing ratio.

This architecture creates a system that is self-correcting: shortfalls in reserves trigger a higher savings rate (Fortify), while adequate reserves enable maximum distribution to stakeholders (Thrive), incentivising further ecosystem growth.