> ## 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.

# How it works

> Setup and per-verification flow.

## Setup

Two parties register before any verification can run: the group owner and the advertiser. Both use `@CanvasVerificationBot` directly.

<Steps>
  <Step title="Group owner registers">
    The group owner DMs `@CanvasVerificationBot` with their group link, topic, Base wallet address, and price per verification (default: \$0.10 USDC). Canvas writes the group to Postgres.
  </Step>

  <Step title="Bot is added as admin">
    The group owner adds `@CanvasVerificationBot` as admin with two permissions: restrict members and send messages. No other permissions are required.
  </Step>

  <Step title="Advertiser funds a campaign">
    The advertiser selects groups by topic and member count, sets a bid per verification, and locks USDC into the Canvas escrow contract on Base. Budget draws down as completions pass Kimi scoring.
  </Step>
</Steps>

## Per-verification flow

Runs automatically on every new join attempt to a registered group.

<Steps>
  <Step title="Join detected">
    Telegram fires a webhook to the Canvas agent server on Railway. The server checks Postgres: group registered, active campaign budget present.
  </Step>

  <Step title="User restricted and DMed">
    The bot restricts the new member from posting and opens a DM. The Canvas agent sends an opening message generated from the advertiser brief and group topic.
  </Step>

  <Step title="Conversation runs">
    The user exchanges 2–4 messages with the agent. If a response is thin or evasive, the agent sends a follow-up. Maximum 3 agent turns. Each conversation is generated dynamically from the brief — no two users see the same opener.
  </Step>

  <Step title="Completion logged onchain">
    On the user's final turn, the agent server calls `logCompletion` on the Canvas escrow contract. The attempt is recorded on Base regardless of what Kimi scores.
  </Step>

  <Step title="Kimi scores the transcript">
    The full conversation transcript goes to Kimi. Kimi returns a score between 0 and 1 based on response entropy, contextual coherence, engagement trajectory, and timing.
  </Step>

  <Step title="Pass: payout released">
    Score ≥ threshold → agent server calls `releasePayout` on the escrow contract → USDC sent to group owner wallet → user unrestricted and admitted.
  </Step>

  <Step title="Fail: re-prompt or deny">
    Score below threshold → user gets one re-prompt with a different question from the same brief. Second failure → user denied, 24-hour cooldown applied. No payout on either failure.
  </Step>

  <Step title="Advertiser notified">
    Advertiser receives: transcript, Kimi score, group context, payout transaction hash, remaining budget.
  </Step>
</Steps>

## What the user sees

From the user's side:

1. They tap Join on a Telegram group
2. They receive a DM from `@CanvasVerificationBot`
3. They have a short conversation — typically 3–4 messages, under 30 seconds
4. They receive a confirmation and are admitted

Canvas does not surface USDC amounts, wallet addresses, or any crypto terminology to end users.