> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canvas-protocol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verification flow

> State machine, timing, and edge case handling for a single verification.

## State machine

```
PENDING
  │
  ├─ no active campaign ──► PASS_NO_BUDGET
  │                         (user admitted, no payout)
  ▼
ACTIVE
  │
  ├─ no response within 5 min ──► TIMED_OUT (user denied)
  │
  ▼
AWAITING_SCORE
  │
  ├─ Kimi unavailable (4 retries exhausted) ──► SCORING_UNAVAILABLE
  │                                             (user admitted, no payout, no cooldown)
  ├─ score < threshold ──► REPROMPT
  │     │
  │     ├─ second failure ──► COOLDOWN_REJECTED
  │     │                     (user denied, 24h cooldown)
  │     └─ second pass ──► PASSED
  │
  └─ score ≥ threshold ──► PASSED
          │
          ▼
       PAID_OUT
```

## Conversation sub-states

Within `ACTIVE`, the conversation moves through:

1. `GREETING` — agent sends opening message from brief
2. `AWAITING_RESPONSE` — waiting for user reply
3. `PROBING` (conditional) — agent sends follow-up if response was thin; returns to `AWAITING_RESPONSE`
4. `CLOSING` — agent sends final turn; transcript queued for Kimi

Maximum 3 agent turns. The conversational LLM decides whether to probe based on response length and whether the brief's target signal was collected.

## Timing

| Stage                         | Target                       |
| ----------------------------- | ---------------------------- |
| Join detected → DM sent       | \< 2s                        |
| Each LLM turn                 | \< 1s                        |
| Kimi scoring                  | \< 3s                        |
| `logCompletion` contract call | \< 5s                        |
| `releasePayout` contract call | \< 5s                        |
| User admitted                 | \< 1s after payout confirmed |

Typical total: under 30 seconds for an engaged user.

## Timeouts

**Verification timeout:** User does not respond to the initial DM within 5 minutes → `TIMED_OUT` → user denied. They can rejoin and start a new verification.

**Rejection cooldown:** Two consecutive failures (including re-prompt) → `COOLDOWN_REJECTED` → 24-hour cooldown on that user/group combination. The cooldown key is `tg_user_id + group_id`.

**Kimi outage:** Scoring request queued with up to 4 retries and exponential backoff. If all 4 fail → `SCORING_UNAVAILABLE` → user admitted, no payout released, no cooldown applied. Kimi infrastructure failures do not penalize users.

## Rate limits

| Scope              | Limit                                                         |
| ------------------ | ------------------------------------------------------------- |
| Per user per group | 3 verification attempts per 24 hours                          |
| Per group globally | Sequential processing (no concurrent verifications per group) |

Sequential processing per group prevents simultaneous join floods from exhausting campaign budgets faster than intended.

## Re-prompt

On first failure, the agent sends a single re-prompt using a different angle from the same brief:

> "Let's give it another shot — \[rephrased question or different question from the brief]."

If the second attempt also fails, the user is denied and the 24-hour cooldown begins. Failed verifications are not billed to the advertiser.