feat: add configurable user requirements for community creation (#841)

* feat: add configurable user requirements for community creation

* fix: fail-closed on invalid COMMUNITY_CREATION_* env var values

* fix: reject negative values for COMMUNITY_CREATION_* thresholds

* harden the check on community creation configuration

* Code formatting

* Refactored threshold validation to helper functions, enforced fail-closed configuration checks, improved error logging levels, added explicit user date validation, and updated all locales to provide detailed feedback to the user on unmet requirements.

* Improve community creation requirement gating by:
- Renaming COMMUNITY_CREATION_MIN_VOLUME to COMMUNITY_CREATION_MIN_VOLUME_SATS and documenting the sats unit in .env-sample.
- Extracting validation logic to a new module with high test coverage.
- Implementing startup logging for misconfigurations.
- Dynamically constructing requirement messages to show only active thresholds.
- Splitting localization keys for granular control across all locales.

---------

Co-authored-by: Maxi Vila <matovi98@gmail.com>

Author: Luquitasjeffrey

.env-sample

@@ -86,6 +86,13 @@ NOSTR_SK=''
 
 # Enable community creation via the /community command (default: false, opt-in per instance)
 COMMUNITY_CREATION_ENABLED=false
+# Minimum requirements to create a community (leave unset to disable the restriction)
+# Note: It is recommended to combine MIN_REPUTATION with MIN_ORDERS to avoid gaming the system.
+# MIN_VOLUME is measured in satoshis.
+# COMMUNITY_CREATION_MIN_ORDERS=100
+# COMMUNITY_CREATION_MIN_VOLUME_SATS=10000000
+# COMMUNITY_CREATION_MIN_DAYS_USING_BOT=365
+# COMMUNITY_CREATION_MIN_REPUTATION=4.8
 
 # Number of currencies allowed in a community
 COMMUNITY_CURRENCIES=20

bot/modules/community/index.ts

@@ -1,4 +1,5 @@
 import { Telegraf } from 'telegraf';
+import { logger } from '../../../logger';
 import { userMiddleware, superAdminMiddleware } from '../../middleware/user';
 import * as actions from './actions';
 import * as commands from './commands';
@@ -9,12 +10,98 @@ import {
 } from './messages';
 import { CommunityContext } from './communityContext';
 import * as Scenes from './scenes';
+import {
+  getCommunityThresholds,
+  meetsCommunityCreationRequirements,
+} from './requirements';
 
 export const configure = (bot: Telegraf<CommunityContext>) => {
   bot.command('mycomm', userMiddleware, commands.communityAdmin);
   bot.command('mycomms', userMiddleware, commands.myComms);
   if (process.env.COMMUNITY_CREATION_ENABLED === 'true') {
+    // Parsing of these values only happens once, they are not reparsed every time a user wants to create a new community
+    const { invalidEnvVars, minOrders, minVolume, minDays, minReputation } =
+      getCommunityThresholds();
+
     bot.command('community', userMiddleware, async ctx => {
+      const { user } = ctx;
+
+      if (invalidEnvVars.length > 0) {
+        logger.error(
+          `Community creation is failing due to a misconfiguration in initialization time: ${invalidEnvVars.join(', ')}`,
+        );
+        return ctx.reply(ctx.i18n.t('generic_error'));
+      }
+
+      const { meets, daysUsing, hasInvalidDate } =
+        meetsCommunityCreationRequirements(
+          {
+            tg_id: user.tg_id,
+            trades_completed: user.trades_completed,
+            volume_traded: user.volume_traded,
+            total_rating: user.total_rating,
+            created_at: user.created_at,
+          },
+          {
+            minOrders,
+            minVolume,
+            minDays,
+            minReputation,
+          },
+        );
+
+      if (hasInvalidDate) {
+        logger.error(
+          `User ${user.tg_id} has invalid created_at timestamp: ${user.created_at}`,
+        );
+        return ctx.reply(ctx.i18n.t('generic_error'));
+      }
+
+      if (!meets) {
+        logger.warning(
+          `User ${user.tg_id} tried to create a community but does not meet the requirements - orders: ${user.trades_completed}, volume: ${user.volume_traded}, days: ${daysUsing}, reputation: ${user.total_rating}`,
+        );
+
+        // Build the message dynamically based on active thresholds
+        const lines = [
+          ctx.i18n.t('community_creation_requirements_not_met_header'),
+        ];
+        if (minOrders !== null) {
+          lines.push(
+            ctx.i18n.t('community_creation_requirements_not_met_orders', {
+              userOrders: user.trades_completed,
+              requiredOrders: minOrders,
+            }),
+          );
+        }
+        if (minVolume !== null) {
+          lines.push(
+            ctx.i18n.t('community_creation_requirements_not_met_volume', {
+              userVolume: user.volume_traded,
+              requiredVolume: minVolume,
+            }),
+          );
+        }
+        if (minDays !== null) {
+          lines.push(
+            ctx.i18n.t('community_creation_requirements_not_met_days', {
+              userDays: daysUsing,
+              requiredDays: minDays,
+            }),
+          );
+        }
+        if (minReputation !== null) {
+          lines.push(
+            ctx.i18n.t('community_creation_requirements_not_met_rep', {
+              userRep: user.total_rating.toFixed(2),
+              requiredRep: minReputation,
+            }),
+          );
+        }
+
+        return ctx.reply(lines.join('\n'));
+      }
+
       await ctx.scene.enter('COMMUNITY_WIZARD_SCENE_ID', {
         bot,
         user: ctx.user,

bot/modules/community/requirements.ts

@@ -0,0 +1,82 @@
+import { logger } from '../../../logger';
+
+export interface ParsedThresholds {
+  minOrders: number | null;
+  minVolume: number | null;
+  minDays: number | null;
+  minReputation: number | null;
+  invalidEnvVars: string[];
+}
+
+export interface UserMetrics {
+  tg_id: string;
+  trades_completed: number;
+  volume_traded: number;
+  total_rating: number;
+  created_at: Date | string;
+}
+
+export const parseOptionalNumber = (
+  raw: string | undefined,
+): { value: number | null; isValid: boolean } => {
+  if (raw == null || raw.trim() === '') return { value: null, isValid: true };
+  const n = Number(raw);
+  if (Number.isFinite(n) && n >= 0) return { value: n, isValid: true };
+  return { value: null, isValid: false };
+};
+
+export const getCommunityThresholds = (): ParsedThresholds => {
+  const thresholdResults = {
+    COMMUNITY_CREATION_MIN_ORDERS: parseOptionalNumber(
+      process.env.COMMUNITY_CREATION_MIN_ORDERS,
+    ),
+    COMMUNITY_CREATION_MIN_VOLUME_SATS: parseOptionalNumber(
+      process.env.COMMUNITY_CREATION_MIN_VOLUME_SATS,
+    ),
+    COMMUNITY_CREATION_MIN_DAYS_USING_BOT: parseOptionalNumber(
+      process.env.COMMUNITY_CREATION_MIN_DAYS_USING_BOT,
+    ),
+    COMMUNITY_CREATION_MIN_REPUTATION: parseOptionalNumber(
+      process.env.COMMUNITY_CREATION_MIN_REPUTATION,
+    ),
+  };
+
+  const invalidEnvVars = Object.entries(thresholdResults)
+    .filter(([_, res]) => !res.isValid)
+    .map(([key]) => key);
+
+  if (invalidEnvVars.length > 0) {
+    logger.error(
+      `Invalid COMMUNITY_CREATION_* threshold configuration: ${invalidEnvVars.join(', ')}`,
+    );
+  }
+
+  return {
+    minOrders: thresholdResults.COMMUNITY_CREATION_MIN_ORDERS.value,
+    minVolume: thresholdResults.COMMUNITY_CREATION_MIN_VOLUME_SATS.value,
+    minDays: thresholdResults.COMMUNITY_CREATION_MIN_DAYS_USING_BOT.value,
+    minReputation: thresholdResults.COMMUNITY_CREATION_MIN_REPUTATION.value,
+    invalidEnvVars,
+  };
+};
+
+export const meetsCommunityCreationRequirements = (
+  user: UserMetrics,
+  thresholds: Omit<ParsedThresholds, 'invalidEnvVars'>,
+): { meets: boolean; daysUsing: number | null; hasInvalidDate: boolean } => {
+  const createdAtTime = new Date(user.created_at).getTime();
+  if (!Number.isFinite(createdAtTime)) {
+    return { meets: false, daysUsing: null, hasInvalidDate: true };
+  }
+
+  const daysUsing = Math.floor((Date.now() - createdAtTime) / 86400000);
+  const { minOrders, minVolume, minDays, minReputation } = thresholds;
+
+  const meets =
+    (minOrders === null || user.trades_completed >= minOrders) &&
+    (minVolume === null || user.volume_traded >= minVolume) &&
+    (minDays === null || daysUsing >= minDays) &&
+    (minReputation === null || user.total_rating >= minReputation);
+
+  return { meets, daysUsing, hasInvalidDate: false };
+};

locales/de.yaml

@@ -722,6 +722,11 @@ payment_methods_reset: "Zahlungsmethoden entfernt. Benutzer können jetzt belieb
 payment_methods_wizard_commands: "/reset — alle Zahlungsmethoden entfernen und Standardverhalten wiederherstellen\n/exit — ohne Speichern beenden"
 community_disabled_by_admin: Ein Administrator hat deine Community ${communityName} deaktiviert
 community_enabled_by_admin: Ein Administrator hat deine Community ${communityName} wieder aktiviert
+community_creation_requirements_not_met_header: "Du erfüllst nicht die Anforderungen zur Erstellung einer Community:"
+community_creation_requirements_not_met_orders: "* Bestellungen: ${userOrders} / ${requiredOrders}"
+community_creation_requirements_not_met_volume: "* Volumen: ${userVolume} / ${requiredVolume}"
+community_creation_requirements_not_met_days: "* Tage der Nutzung des Bots: ${userDays} / ${requiredDays}"
+community_creation_requirements_not_met_rep: "* Reputation: ${userRep} / ${requiredRep}"
 community_already_disabled: Diese Community ist bereits deaktiviert
 community_already_enabled: Diese Community ist bereits aktiviert
 ambiguous_community_input: Mehrere Communities stimmen mit diesem Benutzernamen überein, bitte verwende stattdessen die Community-ID

locales/en.yaml

@@ -728,6 +728,11 @@ payment_methods_reset: "Payment methods removed. Users can now enter any payment
 payment_methods_wizard_commands: "/reset — remove all payment methods and restore default behavior\n/exit — exit without saving"
 community_disabled_by_admin: An administrator has disabled your community ${communityName}
 community_enabled_by_admin: An administrator has re-enabled your community ${communityName}
+community_creation_requirements_not_met_header: "You do not meet the requirements to create a community:"
+community_creation_requirements_not_met_orders: "* Orders: ${userOrders} / ${requiredOrders}"
+community_creation_requirements_not_met_volume: "* Volume: ${userVolume} / ${requiredVolume}"
+community_creation_requirements_not_met_days: "* Days using the bot: ${userDays} / ${requiredDays}"
+community_creation_requirements_not_met_rep: "* Reputation: ${userRep} / ${requiredRep}"
 community_already_disabled: This community is already disabled
 community_already_enabled: This community is already enabled
 ambiguous_community_input: Multiple communities match that username, please use the community ID instead

locales/es.yaml

@@ -725,6 +725,11 @@ payment_methods_reset: "Métodos de pago eliminados. Los usuarios ahora pueden i
 payment_methods_wizard_commands: "/reset — eliminar todos los métodos de pago y restaurar el comportamiento predeterminado\n/exit — salir sin guardar"
 community_disabled_by_admin: Un administrador ha deshabilitado tu comunidad ${communityName}
 community_enabled_by_admin: Un administrador ha reactivado tu comunidad ${communityName}
+community_creation_requirements_not_met_header: "No cumples con los requisitos para crear una comunidad:"
+community_creation_requirements_not_met_orders: "* Órdenes: ${userOrders} / ${requiredOrders}"
+community_creation_requirements_not_met_volume: "* Volumen: ${userVolume} / ${requiredVolume}"
+community_creation_requirements_not_met_days: "* Días usando el bot: ${userDays} / ${requiredDays}"
+community_creation_requirements_not_met_rep: "* Reputación: ${userRep} / ${requiredRep}"
 community_already_disabled: Esta comunidad ya está deshabilitada
 community_already_enabled: Esta comunidad ya está habilitada
 ambiguous_community_input: Varias comunidades coinciden con ese nombre de usuario, por favor usa el ID de la comunidad

locales/fa.yaml

@@ -821,6 +821,11 @@ payment_methods_reset: "روش‌های پرداخت حذف شدند. کاربر
 payment_methods_wizard_commands: "/reset — حذف همه روش‌های پرداخت و بازگرداندن رفتار پیش‌فرض\n/exit — خروج بدون ذخیره"
 community_disabled_by_admin: یک مدیر جامعه ${communityName} شما را غیرفعال کرد
 community_enabled_by_admin: یک مدیر جامعه ${communityName} شما را دوباره فعال کرد
+community_creation_requirements_not_met_header: "شما شرایط لازم برای ایجاد جامعه را ندارید:"
+community_creation_requirements_not_met_orders: "* سفارش‌ها: ${userOrders} / ${requiredOrders}"
+community_creation_requirements_not_met_volume: "* حجم: ${userVolume} / ${requiredVolume}"
+community_creation_requirements_not_met_days: "* روزهای استفاده از ربات: ${userDays} / ${requiredDays}"
+community_creation_requirements_not_met_rep: "* اعتبار: ${userRep} / ${requiredRep}"
 community_already_disabled: این جامعه از قبل غیرفعال است
 community_already_enabled: این جامعه از قبل فعال است
 ambiguous_community_input: چندین جامعه با این نام کاربری مطابقت دارند، لطفاً از شناسه جامعه استفاده کنید

locales/fr.yaml

@@ -721,6 +721,11 @@ payment_methods_reset: "Méthodes de paiement supprimées. Les utilisateurs peuv
 payment_methods_wizard_commands: "/reset — supprimer toutes les méthodes de paiement et restaurer le comportement par défaut\n/exit — quitter sans enregistrer"
 community_disabled_by_admin: Un administrateur a désactivé votre communauté ${communityName}
 community_enabled_by_admin: Un administrateur a réactivé votre communauté ${communityName}
+community_creation_requirements_not_met_header: "Vous ne remplissez pas les conditions pour créer une communauté :"
+community_creation_requirements_not_met_orders: "* Commandes : ${userOrders} / ${requiredOrders}"
+community_creation_requirements_not_met_volume: "* Volume : ${userVolume} / ${requiredVolume}"
+community_creation_requirements_not_met_days: "* Jours d'utilisation du bot : ${userDays} / ${requiredDays}"
+community_creation_requirements_not_met_rep: "* Réputation : ${userRep} / ${requiredRep}"
 community_already_disabled: Cette communauté est déjà désactivée
 community_already_enabled: Cette communauté est déjà activée
 ambiguous_community_input: Plusieurs communautés correspondent à ce nom d'utilisateur, veuillez utiliser l'ID de la communauté à la place

locales/it.yaml

@@ -719,6 +719,11 @@ payment_methods_reset: "Metodi di pagamento rimossi. Gli utenti possono ora inse
 payment_methods_wizard_commands: "/reset — rimuovere tutti i metodi di pagamento e ripristinare il comportamento predefinito\n/exit — uscire senza salvare"
 community_disabled_by_admin: Un amministratore ha disabilitato la tua comunità ${communityName}
 community_enabled_by_admin: Un amministratore ha riabilitato la tua comunità ${communityName}
+community_creation_requirements_not_met_header: "Non soddisfi i requisiti per creare una comunità:"
+community_creation_requirements_not_met_orders: "* Ordini: ${userOrders} / ${requiredOrders}"
+community_creation_requirements_not_met_volume: "* Volume: ${userVolume} / ${requiredVolume}"
+community_creation_requirements_not_met_days: "* Giorni di utilizzo del bot: ${userDays} / ${requiredDays}"
+community_creation_requirements_not_met_rep: "* Reputazione: ${userRep} / ${requiredRep}"
 community_already_disabled: Questa comunità è già disabilitata
 community_already_enabled: Questa comunità è già abilitata
 ambiguous_community_input: Più comunità corrispondono a quel nome utente, usa invece l'ID della comunità

locales/ko.yaml

@@ -719,6 +719,11 @@ payment_methods_reset: "결제 방법이 삭제되었습니다. 이제 사용자
 payment_methods_wizard_commands: "/reset — 모든 결제 방법을 삭제하고 기본 동작을 복원합니다\n/exit — 저장하지 않고 종료"
 community_disabled_by_admin: 관리자가 커뮤니티 ${communityName}을(를) 비활성화했습니다
 community_enabled_by_admin: 관리자가 커뮤니티 ${communityName}을(를) 다시 활성화했습니다
+community_creation_requirements_not_met_header: "커뮤니티를 생성하기 위한 요건을 충족하지 못했습니다:"
+community_creation_requirements_not_met_orders: "* 주문: ${userOrders} / ${requiredOrders}"
+community_creation_requirements_not_met_volume: "* 거래량: ${userVolume} / ${requiredVolume}"
+community_creation_requirements_not_met_days: "* 봇 사용 일수: ${userDays} / ${requiredDays}"
+community_creation_requirements_not_met_rep: "* 평판: ${userRep} / ${requiredRep}"
 community_already_disabled: 이 커뮤니티는 이미 비활성화되어 있습니다
 community_already_enabled: 이 커뮤니티는 이미 활성화되어 있습니다
 ambiguous_community_input: 해당 사용자 이름과 일치하는 커뮤니티가 여러 개 있습니다. 커뮤니티 ID를 사용해 주세요