# Lifecycle and deadlines

> The three timestamps every bounty carries, who may act in each window, and what happens when nothing settles.

A bounty carries exactly three timestamps, all fixed at creation and never
movable afterwards.

| Timestamp               | How it is derived                                       | What it opens or closes                                        |
| ----------------------- | ------------------------------------------------------- | -------------------------------------------------------------- |
| `submission_deadline`   | The Poster's frontmatter value                          | Submissions close. Submission keys become time-lock-releasable |
| `judging_deadline_at`   | `submission_deadline` + half the Guardian review window | Verdict *revisions* close. Settlement opens                    |
| `settlement_timeout_at` | `submission_deadline` + the full Guardian review window | Settlement closes. The full-refund timeout path opens          |

The review window is protocol configuration, read from the Hub at creation and
then frozen onto the bounty. Changing it later does not move an existing
bounty's deadlines.

## The judging schedule

Who may act, and when. Solid arrows are on-chain calls; dashed arrows are work
an actor does off-chain, on its own machine.

### Before the deadline

Solvers compete; nothing can be read yet.

```mermaid
sequenceDiagram
    participant P as Poster
    participant S as Solver
    participant H as ElgoraHub

    rect rgb(240, 238, 232)
    Note over P,H: Open · until submission_deadline
    P->>H: createBounty() · escrows the reward, pins the roster
    S-->>S: builds the package, encrypts to the pinned roster
    S->>H: submit() · records the commitment
    Note over S,H: A Solver may replace its own Submission<br/>any number of times, until the deadline
    Note over P,H: Keys are time-locked. Nobody — Solver, Poster,<br/>Guardian or Elgora — can open a Submission yet
    end

    Note over P,H: ▼ submission_deadline · Submissions close, the time-lock releases
```

### After the deadline

Guardians judge, and the bounty reaches one of its final states.

```mermaid
sequenceDiagram
    participant G as Guardian roster
    participant C as Coordinator / anyone
    participant H as ElgoraHub

    rect rgb(240, 238, 232)
    Note over G,H: Judging · until judging_deadline_at
    G-->>G: fetches and decrypts every eligible Submission
    G-->>G: publishes its written Verdict
    G->>H: commitVerdict() · revisable in this window only
    Note over G,H: Settlement is impossible here even if the roster<br/>already agrees: no result may become final while<br/>a Guardian could still change its mind
    end

    Note over G,H: ▼ judging_deadline_at · revisions close, settlement opens

    rect rgb(240, 238, 232)
    Note over G,H: Settlement · until settlement_timeout_at
    G->>H: commitVerdict() · a silent Guardian may still cast a first Verdict
    alt a coordinator is configured
        C->>H: settle() · coordinator only, for its grace period
    else no coordinator, or the grace period has passed
        C->>H: settle() · anyone may call
    end
    H-->>H: re-tallies the pinned roster, settles at two-thirds
    end

    Note over G,H: ▼ settlement_timeout_at · nothing can be awarded any more

    rect rgb(240, 238, 232)
    Note over G,H: Timed out · only if nothing settled above
    C->>H: timeoutSettlement() · queues the Poster's full refund, no fees
    end

    Note over G,H: After finality, on no schedule at all: the winner claims<br/>the reward and the Poster claims any refund, whenever<br/>each chooses. A queued balance never expires.
```

A bounty either settles inside the settlement window or times out after it —
never both.

## The windows

<Steps>
  <Step>
    ### Open — up to `submission_deadline`

    * **Solvers** may submit and replace Submissions. One active Submission per
      Solver; a replacement overwrites, it does not append.
    * **Nobody** can decrypt anything. The keys are locked to a randomness beacon
      round that has not been published yet.
    * **Guardians** have nothing to do.
    * The bounty's status is `open`.
  </Step>

  <Step>
    ### Judging — `submission_deadline` to `judging_deadline_at`

    * Submissions are refused by the contract.
    * The time-lock releases, so each pinned Guardian can decrypt eligible
      Submissions.
    * Guardians publish written Verdicts and record on-chain Verdicts, and may
      **revise** a recorded Verdict freely inside this window.
    * Settlement is not yet possible, even if everyone already agrees. This is
      deliberate: no result can become final while a Guardian could still change
      their mind.
  </Step>

  <Step>
    ### Settlement — `judging_deadline_at` to `settlement_timeout_at`

    * Revisions stop. A Guardian who has recorded a Verdict can no longer change
      it.
    * A Guardian who never recorded one may still cast a **first** Verdict, as long
      as the bounty is still open. A late first voice can complete a quorum; it
      cannot retract an existing one.
    * `settle` becomes callable. It re-tallies live and settles whatever the pinned
      roster currently agrees on.
  </Step>

  <Step>
    ### Timed out — after `settlement_timeout_at`

    * `settle` reverts. Nothing can be awarded any more.
    * `timeoutSettlement` becomes callable by **anyone**, and queues the Poster's
      full escrow refund, with no fees taken at all.
  </Step>
</Steps>

## Who calls settlement

Settlement is a transaction someone has to pay gas for. Two arrangements exist:

* **Permissionless.** If no coordinator is configured, any address may call
  `settle` as soon as the settlement window opens.
* **Coordinator-first.** If a coordinator is configured, it gets an exclusive
  window: from the later of *first agreement* and `judging_deadline_at`, plus a
  configured grace period. After that, anyone may call.

The coordinator improves liveness and nothing else. It supplies no result, and
cannot change the tally — `settle` re-derives the outcome from the Guardians'
recorded Verdicts every time, so whoever calls it gets the same answer.

Elgora runs a coordinator for its own deployment on a short heartbeat, so in
practice a bounty settles on its own shortly after it becomes settleable.

<Callout title="First agreement is recorded, but never trusted">
  The contract stamps the moment the tally first crossed the threshold, and that
  stamp never moves even if Guardians later disagree and re-agree. It is used to
  start the coordinator's window — not as the result. Settlement always re-tallies
  from scratch.
</Callout>

## What each state means for you

| Status                | Poster                                                                                       | Solver                       |
| --------------------- | -------------------------------------------------------------------------------------------- | ---------------------------- |
| `open`                | Wait                                                                                         | Submit, or replace           |
| `awarded`             | Retrieve the winning work                                                                    | If you are the winner, claim |
| `no_valid_submission` | Claim the full refund if nobody submitted; otherwise minus the Guardian fee. No treasury fee | Nothing                      |
| `timed_out`           | Claim the full escrow, no fees                                                               | Nothing                      |

These are the only four. There is no cancelled, disputed, appealed, or
under-review state, because none of those actions exists.