Warden Documentation

Introduction

Warden is a production-oriented Discord moderation bot focused exclusively on structured punishments and staff workflows. It records warnings, role mutes, and Discord account bans as permanent case history; expirations are database-polled, so they recover after restarts. Warden cannot perform IP bans — Discord does not expose IP addresses to bots.

Inviting Warden

Invite Warden with both the bot and applications.commands scopes. The invite link on the Invite page grants Administrator by default so no role position or permission tweaks are needed at first — you can narrow it later.

Required Permissions

Warden requires the following permissions to operate correctly:

• View Channels
• Send Messages
• Embed Links
• Read Message History
• Manage Roles
• Manage Channels
• Moderate Members
• Mute Members
• Ban Members

Recommended Permissions

Manage Messages is optional but useful for clearing accidental staff panels in public channels. For most servers the default invite (Administrator) is the simplest path.

Role Hierarchy

Place the Warden role above every member and mute role it manages. Channel-specific overwrites can affect mute behavior; audit them if a mute appears to leak.

Quick Setup

1. Invite Warden using the invite link.
2. Assign at least one whitelist role per punishment type you plan to use.
3. Configure a moderation log channel with /logchannel set.
4. (Optional) Configure a shift log channel with /shiftlogs set.
5. Run /help to confirm setup and share the reference embed with staff.

Advanced Setup

For larger teams, split moderation powers by role: give trial moderators only /whitelist warn, seniors /whitelist chatmute and /whitelist voicemute, and administrators /whitelist ban. Grant revoke to a small, trusted role via /toprole set.

/whitelist warn role:@Trial Mod
/whitelist chatmute role:@Moderator
/whitelist voicemute role:@Moderator
/whitelist ban role:@Senior Mod
/toprole set role:@Head Mod
/logchannel set channel:#mod-logs
/shiftlogs set channel:#shift-logs

Punishment Flow

/punish user:@Member opens a private panel with Warn, Chat Mute, Voice Mute, and Ban buttons. Each choice reveals its predefined reasons; picking one issues the punishment, writes it to the database, DMs the user, and logs an embed to the moderation log channel.

Warning System

Warnings are active for 12 hours and expire automatically via the scheduler. Expired warnings remain in case history and appear in lookup and timeline views.

Chat Mute System

Chat mutes assign the Warden Chat Muted role, which Warden creates or reuses. It applies restrictive overwrites to new text channels so the mute persists across future channels. Predefined reasons and durations:

• Excess Spam — 1h
• Inappropriate Language — 30m
• Advertising / Hate Speech — 7d
• Ping Spam — 1h
• Chat Disruption — 3h
• Toxic Behaviour — 6h
• Harassment — 1d

Voice Mute System

Voice mutes assign the Warden Voice Muted role, apply voice and stage overwrites, and attempt an immediate server voice mute when the member is currently in a voice channel.

Ban System

Bans are standard Discord account bans with a configurable message-delete window. Warden attempts a DM before banning and records DM failures without cancelling the punishment.

Temporary vs Permanent Punishments

Warnings, chat mutes, voice mutes, and most bans are time-boxed. Bans for Raiding, Scamming, NSFW Content, Hate Speech, Threats, Ban Evasion, and Malicious Links are permanent by design.

Revoking Punishments

Owner, Administrator, and configured toprole members can revoke any active punishment — including bans by raw user ID. Revocation writes an audit event, DMs the user (without appeal text), and reverses the underlying Discord change.

Punishment Timeline

/timeline user:@Member opens a read-only, chronological audit view of every recorded moderation event for that user: tags, warnings, chat mutes, voice mutes, bans, revokes, and expirations. Precoded filters: All, Punishments, Tags, Active, Expired, Revoked.

Shift Tracking

/shift opens a Mark In / Mark Out panel. Mark Out ends the active shift, calculates duration from timestamps, and stores action totals per shift. Shifts are attendance and statistics only — they do not grant permissions.

Private User Tags

Tags are staff-only notes. They never DM the member and never appear publicly. Severities are precoded as Information, Watchlist, Suspicious, and High Risk. Tags appear in lookup and timeline views.

Whitelist Roles

Punishment whitelist roles are separate and noncumulative. A ban whitelist role does not grant warning, chat mute, or voice mute powers. Server owner and Administrator members bypass whitelists.

Permission Model

• • Punishment permissions are separate per type.
• • Manage Guild / Administrator / Owner is required for configuration commands.
• • Revoke requires Owner, Administrator, or a configured toprole.
• • Lookup, tags, timeline, and shifts are available to any punishment whitelist role or higher.

Logging

Punishment logs are embed messages sent to the configured moderation log channel. Missing log channels never delete or cancel database records — the case is still written, just not announced.

Database Behaviour

Warden uses MySQL 8+ with normalized tables for guild settings, whitelist roles, toproles, punishments, punishment events, user tags, moderator shifts, and shift events. Case history is immutable; expired or revoked cases are never deleted.

Automatic Expiration

The scheduler atomically claims due active punishment rows using FOR UPDATE SKIP LOCKED, removes roles or unbans, logs the expiration, and attempts an expiration DM. Because it polls the database, expirations recover cleanly after restarts.

Recovery After Restart

Warden does not use in-memory timers. When the process restarts, the scheduler immediately re-checks the database for due punishments and processes them, so hosting panel reboots or redeploys never leave stuck mutes.

Case IDs

Case IDs are formatted as WD000001 and are derived from the MySQL identity value on the punishments table, so they are globally unique and race-condition free.

Time & Durations

MySQL sessions are forced to UTC and the Node pool converts to UTC on each connection. All displayed dates use Discord timestamp markup, so every viewer sees local time automatically. Invalid ranges never render negative durations — Warden logs the anomaly and displays Invalid Duration.

Best Practices

• • Run staff panels in dedicated staff-only channels.
• • Split whitelist roles by seniority; keep toproles small.
• • Back up MySQL regularly, especially punishments, punishment_events, user_tags, and moderator_shifts.
• • Review the timeline before every non-trivial punishment.

Security

Warden isolates moderator interfaces through ephemeral slash panels and rechecks panel ownership, guild, moderator permissions, target validity, role hierarchy, evidence URLs, and duplicate submissions during interactive flows.

Troubleshooting

Slash commands don't appear. Ensure the bot was invited with the applications.commands scope and wait for Discord's global command propagation.

Mute leaks in a single channel. Inspect that channel's overwrites — a manual overwrite can override the mute role.

DMs fail. The user has DMs disabled. The database case still exists; only the DM step is skipped.

Displays "Invalid Duration". Legacy rows from before UTC enforcement. New pool connections force UTC on session.