# Flywheel NFT Bot

This repo uses a **Telegram bot** (`telegram-frontend/`) to guide admins through configuration, and a **backend API** (`backend/`) to store settings, manage raffles, and perform XRPL operations.

### What `/setup` does

Run **`/setup` inside the group chat** you want to enable.

`/setup` walks you through:

* Selecting the **NFT collection** (issuer + taxon)
* Choosing the **raffle mode**
* Setting **ticket price** (used for next rounds)
* Linking the **payout wallet** (owner wallet for proceeds + vault returns)
* Seeding / changing the **prize NFT** in the vault (first round)
* Reviewing + submitting the config

After setup, a **Setup Panel** is available so admins can manage settings without rerunning the full wizard.

### Setup steps (wizard)

#### 1) NFT Collection

You can provide the collection in any of these ways:

* Paste an **xrp.cafe NFT URL** (best): `https://xrp.cafe/nft/<NFTokenID>`\
  The bot extracts issuer + taxon from that NFT.
* Paste a **raw NFTokenID** (64 hex chars)
* Or enter **issuer** (`r...`) first, then **taxon** (a non-negative integer)

The bot calls backend **validate-collection** to confirm:

* issuer/taxon are valid
* a floor snapshot can be resolved (used for seeded round minimum logic)

#### 2) Raffle Mode

Select how entries are handled for the group:

* **Open**: multiple tickets allowed per wallet (optional caps)
* **Fair**: stricter rules (one entry per wallet, etc.)

#### 3) Ticket Settings

Set ticket price (XRP). This is stored on the chat config and used for the **next round created**.

#### 4) Payout Wallet (Owner wallet)

You link a wallet that receives proceeds and is used for “return/empty vault” admin operations.

#### 5) Seed / Change Prize NFT (Vault)

For the first seeded round (or later reseeds), you send the prize NFT to the group vault address shown in the flow.

Buttons you may see:

* **Check wallet now**: re-reads the vault to confirm the NFT arrived

#### 6) Review & Submit

You’ll see a summary and can:

* **Submit configuration** (writes to backend + posts setup complete message)
* **Start over**
* **Cancel setup**

### Setup Panel (post-setup buttons)

After setup, admins get a panel with the current configuration and management buttons:

* **Post Raffle Entry To Group**
  * Reposts the “entry card” to the group (useful after message deletion / pin refresh).
* **Set / Change Prize NFT**
  * Starts a reseed flow to set the current/next prize NFT in the vault.
* **Change Ticket Price**
  * Updates the chat’s ticket price used for future rounds.
* **Change Collection**
  * Updates issuer/taxon used for floor reads + flywheel buys.
* **Update Wallets**
  * Re-links payout wallet / admin wallets as needed.
* **Pause Flywheel**
  * Stops the flywheel automation for that chat (does not delete history).
* **Cancel Live Raffle (Refund)**
  * Cancels the active raffle and triggers participant refunds (idempotent).
* **Empty Vault (Paused Only)**
  * Safety operation: pauses first, then offers vault assets back to payout wallet and sweeps spendable XRP.

### Common expectations

* **Floor tracking vs buying**
  * The backend can track “collection floor” cheaply for monitoring/goal logic.
  * When actually buying, the backend still validates the specific offer on-ledger before submitting.
* **Where data is stored**
  * Setup config is stored in Mongo on the `Chat` document for the group (`chatId`).


---

# 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://docs.waffl.fun/flywheel-nft-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.