# Match Lifecycle

Every match in EcoRound goes through four distinct phases. Each phase transition is triggered by the Chainlink CRE oracle — automatically, without human intervention.

***

## Phase Flow

```mermaid
flowchart LR
    A([🟢 OPEN]) -->|Oracle: 2/3 sources started| B([🔒 LOCKED])
    B -->|Oracle: 2/3 sources ended + agree on winner| C([✅ RESOLVED])
    A -->|Admin: match cancelled| D([❌ CANCELLED])
    B -->|Admin: match cancelled| D

    style A fill:#1a3a2a,stroke:#00E6C3,color:#00E6C3
    style B fill:#3a2a00,stroke:#FFB800,color:#FFB800
    style C fill:#1a1a3a,stroke:#7B68EE,color:#7B68EE
    style D fill:#3a1a1a,stroke:#FF4655,color:#FF4655
```

***

## Deposit & Payout Flow

```mermaid
sequenceDiagram
    participant User
    participant USDC
    participant VaultMatch
    participant Morpho
    participant Oracle as Chainlink CRE

    User->>USDC: approve(vault, amount)
    User->>VaultMatch: deposit(TeamA, amount)
    VaultMatch-->>User: deposit recorded

    Note over VaultMatch: Status: OPEN — funds idle

    Oracle->>VaultMatch: lockMatch()
    VaultMatch->>USDC: transferFrom(vault → morpho)
    VaultMatch->>Morpho: deposit(totalUSDC)
    Morpho-->>VaultMatch: shares minted

    Note over Morpho: Yield accrues during match

    Oracle->>VaultMatch: resolveMatch(TeamA)
    VaultMatch->>Morpho: redeem(all shares)
    Morpho-->>VaultMatch: USDC + yield returned

    User->>VaultMatch: claim()
    VaultMatch-->>User: principal + yield share (if winner)
```

***

## Phase Details

### Phase 1 — Open

**What happens**: A new match is created on-chain via `FactoryMatch.createMatch()`. The VaultMatch contract starts in the `Open` state.

**User actions**:

* Browse the match on the frontend
* Choose Team A or Team B
* Deposit any amount of USDC

**Behind the scenes**:

* USDC sits idle in the VaultMatch contract
* No yield yet — funds are not deployed
* The oracle polls data sources every 30 seconds watching for the match to start

***

### Phase 2 — Locked

**Trigger**: The Chainlink CRE oracle detects that 2 of 3 data sources report the match has started. It calls `VaultMatch.lockMatch()`.

**What changes**:

* No new deposits accepted
* All collected USDC is deposited into the Morpho yield vault
* Yield begins accruing in real time

**User view**: Match card shows "LOCKED" status. The deposit form is disabled.

***

### Phase 3 — Resolved

**Trigger**: The oracle detects that 2 of 3 data sources report the match has ended and agree on the same winner. It calls `VaultMatch.resolveMatch(winner)`.

**What changes**:

* All Morpho shares are redeemed back to USDC
* Total yield is calculated: `redeemed USDC − original deposits`
* The winning team is recorded on-chain
* Claims become available

***

### Phase 4 — Claimed

**User action**: Any depositor calls `VaultMatch.claim()`.

**Payout**:

| Deposited on | Receives                                         |
| ------------ | ------------------------------------------------ |
| Winning team | Full deposit + proportional share of total yield |
| Losing team  | Full deposit (100% principal refund)             |

***

## Cancellation

If a match is cancelled before resolution, the admin pauses the vault and triggers `emergencyRefund()` for each depositor — returning 100% of their deposit regardless of state.

***

## Example Timeline

```mermaid
gantt
    title Match Lifecycle Timeline
    dateFormat HH:mm
    axisFormat %H:%M

    section Match
    Deposits Open       :done, open, 10:00, 4h
    Match in Progress   :active, locked, 14:00, 2h30m
    Claims Available    :crit, resolved, 16:30, 1h
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://eco-round.gitbook.io/eco-round-docs/how-ecoround-works/lifecycle.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.