CTFBot 🚩

UCS's specialized Discord bot for managing Capture The Flag (CTF) competitions, now with blockchain-backed task tracking, reputation, and document anchoring powered by Luce.

Features

📅 Event Scheduling — Schedule CTF events with timezone support
🏗️ Channel Management — Automatically create dedicated CTF channels
👥 User Registration — Track team member participation
🗄️ Database Storage — Persistent storage of CTF data and registrations
🔗 CTFd Integration — Ready for CTFd platform integration (coming soon)
⛓️ Blockchain-Backed Tasks — Create and track tasks with immutable audit trail
👍 Reputation System — Give +1/-1 rep via reactions, replies, or /rep command
📄 Document Anchoring — Permanently store documents on the blockchain
🎯 Activity Points Economy — Admin-granted points, a leaderboard, and a merchandise store (AP or Rp)
⏰ Automatic Reminders — Task deadline reminders sent to a dedicated channel

Commands

CTF Commands

/schedule — Schedule custom events with timezone support
/createctf — Create a CTF text channel and schedule its event
/registerctf — Register your participation for the CTF in the current channel
/addchalctf — Add challenges to a CTF
/solvectf — Mark a challenge as solved
/archivectf — Archive a completed CTF
/chalpts — View challenge points
/summarizectf — View CTF summary
/syncchallenges — Sync challenges from CTFd
/pact — Manage pacts

Task Commands

/task add — Create a new task (title, description, assignee, deadline, optional timezone)
/task list [period] — View remaining tasks for this week/month/quarter/year
/task done <task_id | task> — Mark a task as completed (by UUID or fuzzy title search)
/task cancel <task_id | task> — Confirm and cancel a pending task (by UUID or fuzzy title search), removing its reminders

Task reports use Asia/Jakarta calendar boundaries. Large lists are split into multiple responses.

Completing/cancelling by title: Personnel no longer need to copy the UUID — pass the task title (or a distinctive part of it, even its description) as the task option and the bot fuzzy-searches all pending tasks. Because a fuzzy match can be wrong, every title-based completion/cancellation requires an ephemeral confirmation (Confirm / Deny buttons) before anything is recorded; nothing is written to the blockchain or the database until you confirm. If several tasks match closely, a picker shows one button per candidate — pick the one you meant. UUID-based completion and cancellation also ask for confirmation for consistency. Cancellation additionally removes the task's reminders.

Reputation Commands

/rep [downvote] — Give +1 or -1 rep (must reply to someone's message; response is ephemeral)
/repleaderboard [limit] — View the reputation leaderboard

You can also give rep by:

Reacting with 👍 or 👎 to someone's message
Replying to someone with +1, -1, 👍, or 👎

Document Commands

/document add — Anchor a document to the blockchain
/document get — Retrieve an anchored document

Activity Points Commands

/activitypoints [user] — View your (or another user's) activity points balance
/activityleaderboard [limit] — View the activity points leaderboard
/giveap <user|role> <points> — Grant activity points to a user or every member of a role (admin only)
/giveapbulk <csv> — Grant activity points to many users from a CSV with discord_id and points columns (admin only)
/store — Browse and buy the merchandise store with AP or Rp (no subcommand)
/store-confirm <purchase_id> — Confirm a pending Rp purchase once offline payment arrives (admin only)

Utility Commands

/ping — Check bot responsiveness
/help — List all available commands

Quick Start

Prerequisites

Node.js v18.0.0 or higher
pnpm package manager
A Discord Bot Token (Create one here)
Luce blockchain server running locally on port 5500

Installation

Clone the repository

git clone https://github.com/ucsits/ctfbot.git
cd ctfbot

Install dependencies
```
pnpm install
```
Configure environment variables
```
cp .env.example .env
```
Edit .env and fill in the required values:
- DISCORD_TOKEN — Your Discord bot token
- GUILD_ID — Your Discord server ID (for development)
- CTF_CATEGORY_ID — Category ID where CTF channels will be created
- CTFD_API_TOKEN — Your CTFd API token (optional)
- LUCE_PORT — Luce blockchain RPC port (default: 5500)
Run the bot

Development mode (with auto-reload):
```
pnpm dev
```
Production mode:
```
pnpm start
```

Setting Up Your Discord Server

Create a CTF Category
- Right-click in your server's channel list
- Select "Create Category"
- Name it "CTF" or similar
- Right-click the category → Copy ID
- Paste the ID in .env as CTF_CATEGORY_ID
Invite the Bot
- Go to Discord Developer Portal
- Select your application
- Go to OAuth2 → URL Generator
- Select scopes: bot, applications.commands
- Select permissions: Manage Channels, Manage Events, Send Messages, Embed Links, Add Reactions, Read Message History
- Copy and visit the generated URL

Architecture

src/
├── commands/              # Slash command implementations
│   ├── createctf.js       # Create CTF channels and events
│   ├── registerctf.js     # User registration for CTFs
│   ├── schedule.js        # Generic event scheduling
│   ├── task.js            # Blockchain-backed task management
│   ├── rep.js             # Reputation command (ephemeral)
│   ├── repleaderboard.js  # Reputation leaderboard
│   ├── document.js        # Document anchoring
│   ├── help.js            # List all commands
│   └── ping.js            # Health check
├── listeners/             # Event listeners
│   ├── ready.js           # Bot ready event (starts reminder service)
│   ├── messageCreate.js   # Detects reply-based +1/-1/👍/👎
│   ├── messageReactionAdd.js  # Detects 👍/👎 reaction rep
│   └── applicationCommandRegistriesRegistered.js
├── services/
│   └── reminder.js        # Background reminder poller (every 30s)
├── lib/
│   ├── luce/
│   │   └── index.js       # Luce blockchain RPC client
│   ├── constants/
│   ├── embeds/
│   ├── errors/
│   ├── helpers/
│   ├── middleware/
│   ├── utils/
│   └── validators/
├── database/
│   ├── repositories/
│   │   ├── task.repository.js       # Tasks + reminders queries
│   │   ├── reputation.repository.js # Reputation ledger queries
│   │   └── document.repository.js   # Document queries
│   ├── connection.js
│   ├── index.js
│   └── migrations.js
├── migrations/            # SQL migration files
└── index.js               # Main entry point

Database Schema

Core tables (existing):

ctfs — Stores CTF competition details
ctf_registrations — Stores user registrations
ctf_challenges — Stores CTF challenges
ctf_challenge_solves — Tracks challenge solves
pacts — Pact agreements
admins — Admin user IDs

Blockchain-backed tables (new):

tasks — Tasks with reference to blockchain block height
task_reminders — Scheduled reminders for task deadlines
reputations — Reputation ledger (one entry per giver per day)
documents — Anchored documents with blockchain reference
activity_ledger — Append-only ledger of AP value movements (grants/spends)
activity_balances — Current AP balance per user
store_items — Merchandise catalog (Sticker, Keychain, Shirt, Jacket)
purchases — Purchase records (AP completed, Rp pending→confirmed)

Blockchain Block Data Schema

Every block stored on the Luce blockchain has a data field containing a JSON string. Below are the supported schemas with their type discriminator.

🔹 Task (`type: "task"`)

Created when a user runs /task add.

{
  "type": "task",
  "v": 1,
  "taskId": "a1b2c3d4-...",
  "title": "Implement login page",
  "description": "Build the user authentication UI",
  "assignedTo": "123456789012345678",
  "createdBy": "987654321098765432",
  "deadline": 1740000000
}

Field	Type	Description
`type`	`string`	Always `"task"`
`v`	`number`	Schema version (currently `1`)
`taskId`	`string`	UUID v4
`title`	`string`	Task title
`description`	`string`	Task description (may be empty)
`assignedTo`	`string`	Discord user ID of assignee
`createdBy`	`string`	Discord user ID of creator
`deadline`	`number`	Unix timestamp (seconds)

✅ Task Completion (`type: "task_done"`)

Created when a user runs /task done.

{
  "type": "task_done",
  "v": 1,
  "taskId": "a1b2c3d4-...",
  "title": "Implement login page",
  "assignedTo": "123456789012345678",
  "completedBy": "123456789012345678"
}

Field	Type	Description
`type`	`string`	Always `"task_done"`
`v`	`number`	Schema version (currently `1`)
`taskId`	`string`	UUID of the completed task
`completedBy`	`string`	Discord user ID of completer
`title`	`string`	Task title, for recognizable audit events
`assignedTo`	`string`	Discord user ID of assignee

🗑️ Task Cancellation (`type: "task_cancel"`)

Created when a user runs /task cancel confirm:True.

{
  "type": "task_cancel",
  "v": 1,
  "taskId": "a1b2c3d4-...",
  "title": "Implement login page",
  "assignedTo": "123456789012345678",
  "cancelledBy": "987654321098765432"
}

Field	Type	Description
`type`	`string`	Always `"task_cancel"`
`v`	`number`	Schema version (currently `1`)
`taskId`	`string`	UUID of the cancelled task
`title`	`string`	Task title
`assignedTo`	`string`	Discord user ID of assignee
`cancelledBy`	`string`	Discord user ID of canceller

👍 Reputation (`type: "rep"`)

Created via reaction (👍/👎), reply (+1/-1/👍/👎), or /rep command.

{
  "type": "rep",
  "v": 1,
  "toUser": "123456789012345678",
  "fromUser": "987654321098765432",
  "amount": 1,
  "reason": "reaction",
  "date": "2026-07-10"
}

Field	Type	Description
`type`	`string`	Always `"rep"`
`v`	`number`	Schema version (currently `1`)
`toUser`	`string`	Discord user ID of recipient
`fromUser`	`string`	Discord user ID of giver
`amount`	`number`	`1` (upvote) or `-1` (downvote)
`reason`	`string`	Trigger source: `"reaction"`, `"reply"`, or `""` (slash command)
`date`	`string`	UTC date in `YYYY-MM-DD` format (enforces daily limit)

Daily limit: A user may only give rep once per UTC calendar day, regardless of target or sign. This is enforced at both the application and database level.

📄 Document (`type: "document"`)

Created when a user runs /document add.

{
  "type": "document",
  "v": 1,
  "docId": "a1b2c3d4-...",
  "title": "Meeting Notes 2026-07-10",
  "content": "Discussed sprint goals for Q3...",
  "author": "123456789012345678",
  "mimeType": "text/plain"
}

Field	Type	Description
`type`	`string`	Always `"document"`
`v`	`number`	Schema version (currently `1`)
`docId`	`string`	UUID v4
`title`	`string`	Document title
`content`	`string`	Document content (plain text; base64 for binary in future versions)
`author`	`string`	Discord user ID of author
`mimeType`	`string`	MIME type (default: `"text/plain"`)

🎯 Activity Points Grant (`type: "ap_grant"`)

Created by /giveap (single user) and /giveapbulk / /giveap <role> (batch).

Single grant (v: 1):

{
  "type": "ap_grant",
  "v": 1,
  "grantedTo": "123456789012345678",
  "grantedBy": "987654321098765432",
  "amount": 50
}

Batch grant (v: 2) — one block for the whole batch, used by /giveapbulk and /giveap <role>:

{
  "type": "ap_grant",
  "v": 2,
  "grantedBy": "987654321098765432",
  "entries": [
    { "discord_id": "123456789012345678", "points": 50 },
    { "discord_id": "876543210987654321", "points": 50 }
  ],
  "count": 2,
  "total": 100
}

Field	Type	Description
`type`	`string`	Always `"ap_grant"`
`v`	`number`	`1` (single) or `2` (batch)
`grantedTo`	`string`	Discord user ID of recipient (v1 only)
`grantedBy`	`string`	Discord user ID of the granting admin
`amount`	`number`	Points granted (v1 only)
`entries`	`array`	`{discord_id, points}` list (v2 only)
`count`	`number`	Number of recipients (v2 only)
`total`	`number`	Total points granted (v2 only)

🛒 Store Purchase (`type: "ap_purchase"`)

Created when a user buys an item from the store. AP purchases complete immediately; Rp purchases start pending and are confirmed later.

{
  "type": "ap_purchase",
  "v": 1,
  "user": "123456789012345678",
  "itemName": "Shirt",
  "paymentMethod": "ap",
  "costAp": 200,
  "status": "completed"
}

Field	Type	Description
`type`	`string`	Always `"ap_purchase"`
`v`	`number`	Schema version (currently `1`)
`user`	`string`	Discord user ID of buyer
`itemName`	`string`	Name of the purchased item
`paymentMethod`	`string`	`"ap"` or `"rp"`
`costAp`	`number`	AP cost (when `paymentMethod` is `"ap"`)
`costRp`	`number`	Rp cost (when `paymentMethod` is `"rp"`)
`status`	`string`	`"completed"` (AP) or `"pending"` (Rp)

✅ Purchase Confirmation (`type: "ap_confirm"`)

Created when an admin confirms a pending Rp purchase via /store-confirm.

{
  "type": "ap_confirm",
  "v": 1,
  "user": "123456789012345678",
  "confirmedBy": "987654321098765432",
  "itemName": "Shirt",
  "paymentMethod": "rp"
}

Field	Type	Description
`type`	`string`	Always `"ap_confirm"`
`v`	`number`	Schema version (currently `1`)
`user`	`string`	Discord user ID of buyer
`confirmedBy`	`string`	Discord user ID of confirming admin
`itemName`	`string`	Name of the purchased item
`paymentMethod`	`string`	`"rp"` (or `"ap"` for completeness)

Schema Versioning

The v field allows future schema evolution without breaking existing blocks. When introducing a breaking change, increment v and handle both versions in your parser.

Reminder System

A background service (src/services/reminder.js) polls every 30 seconds for unsent task reminders. Reminders are sent to 1524933314119467200 one hour before the deadline and at 09:00 Asia/Jakarta on the day before the deadline when those times are still in the future. Failed sends remain retryable.

Daily digests run after 04:00 Asia/Jakarta and weekly digests run Monday after 05:00 Asia/Jakarta; Monday sends avoid redundant notifications. Digest ranges and task reports use Asia/Jakarta calendar boundaries, and empty results are explicitly reported.

Flow:

/task add → creates blockchain block + DB row + reminder schedule
Reminder service polls task_reminders table every 30s
Due reminders are sent to channel 1524933314119467200
Reminder is marked sent = 1 to prevent duplicates

Google Calendar Sync (Option A)

A background service (src/services/calendarSync.js) pushes bot tasks to a shared Google Calendar and reconciles bot-owned calendar events back into the task DB. This lets the team see task deadlines on their calendar and edit them there, with changes reflected back in Discord.

Push direction (bot → Calendar):

/task add creates a new Calendar event (1 hour before the deadline).
/task done deletes the event from the calendar.
/task cancel patches the event status to cancelled.

Pull direction (Calendar → bot):

Incremental sync using Google's syncToken to reduce API quota.
Only processes events with the private x-ctfbot-task extended property marker, so foreign events are never imported as tasks.
Detects: title changes, deadline changes, and event cancellation/deletion.
A reconciliation cycle runs every 60 seconds when enabled.

Setup

Google Cloud Project — create one at https://console.cloud.google.com/, enable the Google Calendar API.
OAuth 2.0 credentials — create an OAuth 2.0 Client ID (Desktop app type). Copy the client ID and client secret.
Shared Calendar ID — create or choose a Google Calendar that the bot will own. Copy its ID (find it in Calendar settings → Integrate calendar → Calendar ID).

Refresh token — visit the authorization URL below (generated by the bot or manually) with the calendar scope to obtain a one-time code, then exchange it for a refresh token:

https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code&scope=https://www.googleapis.com/auth/calendar&access_type=offline&prompt=consent

Configure .env:

GOOGLE_CALENDAR_ENABLED=true
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REFRESH_TOKEN=your_refresh_token
GOOGLE_CALENDAR_ID=your_calendar_id

Architecture

src/lib/google/oauth.js — OAuth 2.0 token refresh (fetch-based, no extra dependencies).
src/lib/google/calendar.js — Google Calendar API v3 REST wrappers and mapper functions (taskToCalendarEvent, calendarEventToTaskPatch).
src/services/calendarSync.js — poll loop (60s interval), push logic, incremental pull reconciliation.
migrations/019_add_calendar_sync.sql — adds calendar_event_id, calendar_synced_at, calendar_source columns to tasks, plus google_credentials and calendar_sync_state tables.

Development

Project Structure

The bot is built using the @sapphire/framework which provides:

Structured command handling
Event listener system
Plugin support
TypeScript-ready architecture

Running Tests

pnpm test

Code Style

This project uses tabs for indentation. Please ensure your editor is configured accordingly.

Logging

The bot includes a unified logging system built on top of the Sapphire framework's logger.

Log Levels

Set the LOG_LEVEL environment variable to control verbosity:

Level	Usage
`error`	Fatal errors and exceptions only
`warn`	Warnings + errors
`info`	Normal operational messages (default)
`debug`	Detailed debugging information
`trace`	Everything, including individual HTTP request logs

LOG_LEVEL=info

Where Logs Go

All logs are output to stdout (info/debug/trace) and stderr (error/warn). There is no file-based logging — use your process manager (e.g., systemd, Docker, PM2) to capture and rotate stdout/stderr.

Logger Architecture

The logger (src/lib/logger.js) works in two modes:

Pre-init mode: Before the bot has logged into Discord, the logger falls back to raw console calls with ISO timestamps.
Post-init mode: Once the SapphireClient is ready, the logger delegates to Sapphire's structured logger for consistent formatting across all commands and listeners.

Context Prefixes

Child loggers with a context prefix are used throughout the codebase:

Prefix	Module
`[ErrorHandler]`	`src/lib/errorHandler.js`
`[CTFd]`	`src/lib/ctfd/index.js`
`[DB]`	`src/database/index.js`
`[Migration]`	`src/database/migrations.js`
`[Luce]`	`src/lib/luce/index.js`

Adding Logging to a New Module

const { logger } = require('./lib/logger');
const myLog = logger.child('MyModule');

myLog.info('Operation completed successfully');
myLog.error('Something went wrong', error);
myLog.debug('Detailed info: %s', detail);

Logger methods follow the same signature as console.log: logger.info(message, ...optionalArgs).

Contributing

Contributions are welcome! Please read our comprehensive guides:

📖 Contributing Guide — Detailed contribution guidelines
🏗️ Project Structure — Understanding the codebase
🚀 Quick Reference — Fast reference for common tasks
🏛️ Architecture — System design and patterns
📊 Changelog — Version history

Quick Start for Contributors

Fork the repository
Clone your fork: git clone https://github.com/YOUR_USERNAME/ctfbot.git
Install dependencies: pnpm install
Create a branch: git checkout -b feature/your-feature
Make your changes
Run linting: pnpm run lint:fix
Commit: git commit -m "feat: add your feature"
Push: git push origin feature/your-feature
Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

Roadmap

Blockchain-backed task management
Reputation system (+1/-1 with daily limit)
Document anchoring
Additional rep triggers (message content, reactions on other platforms)
Web dashboard for blockchain explorer
Multi-chain support

License

This project is licensed under the MIT License — see the LICENSE file for details.

Support

Issues: GitHub Issues
Discord: Join our server for support and discussions

Acknowledgments

Built with discord.js
Powered by @sapphire/framework
Database: better-sqlite3
Blockchain: Luce

Made with ❤️ by UCS ITS

Name		Name	Last commit message	Last commit date
assets		assets
migrations		migrations
src		src
tests		tests
.editorconfig		.editorconfig
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc.json		.prettierrc.json
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
vitest.config.js		vitest.config.js

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

CTFBot 🚩

Features

Commands

CTF Commands

Task Commands

Reputation Commands

Document Commands

Activity Points Commands

Utility Commands

Quick Start

Prerequisites

Installation

Setting Up Your Discord Server

Architecture

Database Schema

Blockchain Block Data Schema

🔹 Task (type: "task")

✅ Task Completion (type: "task_done")

🗑️ Task Cancellation (type: "task_cancel")

👍 Reputation (type: "rep")

📄 Document (type: "document")

🎯 Activity Points Grant (type: "ap_grant")

🛒 Store Purchase (type: "ap_purchase")

✅ Purchase Confirmation (type: "ap_confirm")

Schema Versioning

Reminder System

Google Calendar Sync (Option A)

Setup

Architecture

Development

Project Structure

Running Tests

Code Style

Logging

Log Levels

Where Logs Go

Logger Architecture

Context Prefixes

Adding Logging to a New Module

Contributing

Quick Start for Contributors

Roadmap

License

Support

Acknowledgments

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

🔹 Task (`type: "task"`)

✅ Task Completion (`type: "task_done"`)

🗑️ Task Cancellation (`type: "task_cancel"`)

👍 Reputation (`type: "rep"`)

📄 Document (`type: "document"`)

🎯 Activity Points Grant (`type: "ap_grant"`)

🛒 Store Purchase (`type: "ap_purchase"`)

✅ Purchase Confirmation (`type: "ap_confirm"`)