# Grape Verification Discord Bot

## Overview

The Grape Verification Discord Bot connects Discord users to on-chain identity records in the Grape Verification Registry (GVR) on Solana.

It provides a Discord-first verification flow:

1. User runs `/gv verify` and opens the web verification portal.
2. User completes verification on the portal.
3. User runs `/gv check` to confirm on-chain verification and sync Discord role access.

### Core Features

* Secure Discord interaction handling (Ed25519 signature verification).
* DAO-aware verification per server (guild).
* Per-guild configuration via `/gv setup`.
* Automatic verified-role sync on `/gv check`.
* Admin tools for on-chain GVR operations (space init, attest, revoke, wallet link/unlink).

### Slash Commands

#### User Commands

* `/gv verify`\
  Opens the verification portal with Discord user and guild context.
* `/gv check`\
  Checks if the user has a verified identity in GVR for the configured DAO.
* `/gv ping`\
  Health check command.

#### Admin Command

* `/gv setup dao:<pubkey> verified_role:<role?>`\
  Stores server-specific DAO and optional verified role.\
  Requires **Manage Server** or **Administrator** permission.

#### Advanced Admin Subcommands (`/gv admin ...`)

* `status` — Shows derived PDAs and current on-chain status.
* `space-init` — Initializes DAO space account (requires signer key).
* `attest` — Attests an identity.
* `revoke` — Revokes an identity.
* `link` — Links wallet to identity (attestor-driven).
* `link-self` — Links wallet requiring wallet signer.
* `unlink` — Unlinks a wallet from identity.

### Architecture

* `pages/api/interactions.js`\
  Primary Discord interaction webhook endpoint.
* `lib/discord/slash-commands.js`\
  Command schema, dispatch, DAO resolution, role sync, and Solana/GVR logic.
* `scripts/register-commands.js`\
  Registers slash commands with Discord API.
* `pages/api/discord.js`\
  Separate endpoint for a `points` command flow (independent from `/gv`).

### Configuration

#### Required

* `DISCORD_PUBLIC_KEY`
* `DISCORD_BOT_TOKEN`
* `DISCORD_APPLICATION_ID` (or `DISCORD_APP_ID`)

#### Strongly Recommended

* `DISCORD_TEST_GUILD_ID` (for fast guild-scoped command registration during development)
* `SOLANA_RPC_URL` (or compatible RPC env variant)
* `VERIFICATION_URL` (defaults to `https://verification.governance.so`)

#### DAO / Role Resolution

* `GVR_DAO` (default DAO)
* `GVR_GUILD_DAO_MAP` (JSON map: guild ID -> DAO pubkey)
* `GVR_VERIFIED_ROLE_ID` (default role ID)
* `GVR_GUILD_ROLE_MAP` (JSON map: guild ID -> role ID)
* `GVR_REMOVE_ROLE_ON_UNVERIFIED` (`true` by default)

#### On-chain Admin Operations

* `BOT_FEE_PAYER_SECRET_KEY` (JSON array, base58, or base64)
* `BOT_WALLET_SIGNER_SECRET_KEY` (only for `link-self`)

#### Optional Persistent Guild Config

If Vercel KV is configured, `/gv setup` persists per-guild DAO/role in KV and overrides static defaults.

### Operational Notes

* All command responses are ephemeral by default.
* Role assignment/removal is attempted during `/gv check`.
* If DAO space is not initialized, `/gv check` prompts admin action.
* Command registration supports both global and guild-scoped modes.

### Quick Start

1. Set environment variables.
2. Run command registration:
   * `yarn register:commands`
3. Configure Discord Interactions endpoint to your deployed API route:
   * `POST /api/interactions`
4. In a server, run:
   * `/gv setup`
   * `/gv verify`
   * `/gv check`

### Security Notes

* Never expose bot tokens or private keys in documentation.
* Rotate credentials immediately if leaked.
* Limit admin command usage to trusted roles.


---

# 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://grapedao.gitbook.io/products/grape-verification/grape-verification-discord-bot.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.