TRACaBot

TRACaBot is an OpenClaw + Telegram + OriginTrail DKG v10 intelligent anti-scam bot. It monitors Telegram communities, detects scam patterns, records local working memory, and writes evidence-backed fraud intelligence to DKG v10 Shared Memory so all instances of TRACaBot can query reusable scam context and apply it on their respective communities. Imagine a Telegram anti-scam bot that updates real time with knowledge from all communities to create a safe environment for users to exchange.

The default Context Graph is tracabot. Every community running TRACaBot against that Context Graph contributes to the same DKG v10 Shared Memory layer. TRACaBot writes events with provenance, local/DKG confidence, stable Telegram IDs, usernames/display-name aliases, reporter metadata, scam type, wallet/pattern indicators, and moderation outcomes. High-confidence fraud findings, accepted high-confidence reports, and executed bans are automatically published from Shared Memory into the Context Graph so other communities can query them immediately.

Why It Exists

Telegram scam moderation usually stays trapped inside one chat. TRACaBot turns each meaningful scan, report, and moderation action into structured fraud knowledge that can be queried across communities. If a fraudster is banned or reported in one channel, another TRACaBot instance can flag the same Telegram user ID, reused username/display-name alias, wallet, or scam pattern when that actor appears elsewhere.

Commands

• /scan checks a user, Telegram ID, wallet, replied user, or replied SangMata rename alert against local heuristics and DKG Shared Memory, then returns a friendly risk verdict.
• /report accepts replied reports and bare @username reports, analyzes replied or recently observed Telegram context for scam patterns like support-DM lures and admin impersonation, applies duplicate/rate-limit/reporter checks, and writes accepted reports to DKG Shared Memory.
• /ban is restricted to configured admins or Telegram chat admins; it bans replied users or users extracted from replied SangMata rename alerts only when the bot has Telegram ban rights and logs full evidence.
• /stats returns readable DKG aggregate activity for recent fraud events, high-confidence findings, risk types, and action guidance.
• /stats campaigns shows repeated domains, wallets, scam patterns, or text fingerprints from recent local memory.
• /why <event-id> explains the local and DKG evidence behind a tracabot decision.
• /watch and /unwatch are admin-only scrutiny controls when replying to a user or SangMata rename alert; /watch <telegram-id>, /watch @user, /unwatch <telegram-id>, and /unwatch @user also work. ID/reply-based use creates a clickable Telegram mention and boosts future risk scoring without banning by itself.
• /watchlist is admin-only and shows local active watches, temporary mutes, and pending review items for follow-up.
• /appeal <event-id> reason records a correction request to DKG Shared Memory.
• /review <event-id> uphold|overturn reason is admin-only and writes a DKG review decision for future audits and false-positive correction.
• /digest summarizes recent bans, restrictions, reports, watches, appeals, reviews, and campaign signals.
• /status is admin-only and shows DKG reachability, Telegram permissions, thresholds, and conversational mode status without exposing secrets.
• /help explains commands, autonomous thresholds, safeguards, and the DKG shared-memory loop for admins.

DKG Join Challenge

TRACaBot can replace generic captcha bots with a DKG-native onboarding gate. When TRACABOT_JOIN_CHALLENGE=true, low-risk new members are allowed to send text only and must verify by finding any Knowledge Asset on https://dkg.origintrail.io/, copying its UAL, and pasting it as their first message. TRACaBot validates that the UAL starts with did:dkg: and, by default, checks it against the live DKG before restoring normal chat permissions.

A Knowledge Asset is a verifiable data item on the Decentralized Knowledge Graph. Its UAL is the unique address for that item, similar to a link for DKG data. The challenge gives new members a practical first interaction with DKG while TRACaBot continues checking shared scam memory for high-risk joins, impersonators, and scam patterns.

High-risk joins still bypass the challenge and go directly to the configured risk action. Challenge starts, failed attempts, solves, and expirations stay local-only; evidence-backed scam findings and enforcement outcomes remain the events written to DKG Shared Memory.

DKG v10 Integration

TRACaBot uses the official DKG/OpenClaw adapter setup as its DKG boundary. DkgDaemonClient points at the local DKG v10 daemon at DKG_NODE_URL and keeps TRACaBot aligned with the same DKG service OpenClaw uses:

• DkgDaemonClient.createContextGraph ensures the configured Context Graph exists.
• DkgDaemonClient.share writes reports, findings, and moderation evidence to DKG Shared Memory.
• DkgDaemonClient.publishSharedMemory automatically publishes eligible high-confidence fraud memory into the Context Graph.
• DkgDaemonClient.query reads shared DKG evidence before scoring a target.

This cross-community loop is the core product behavior: observe locally, write structured evidence to DKG Shared Memory, auto-publish high-confidence events, then let every other TRACaBot instance query the same graph before the fraudster can repeat the attack in a different channel.

TRACaBot also ships an OpenClaw skill interface in skills/tracabot/skill.json and a JSON CLI bridge, tracabot-skill, so OpenClaw agents can call the same fraud intelligence without going through Telegram. Skill tools include scan_target, explain_event, get_watchlist, get_digest, query_campaigns, submit_appeal, and review_event.

TRACaBot can also run in conversational safety mode. It keeps its own standalone Telegram bot token, but can read local OpenClaw OAuth/model/gateway configuration to draft scam-safety replies through the same OpenClaw LLM account already configured on the host. If OpenClaw chat access is unavailable, TRACaBot falls back to deterministic evidence-based safety templates. Conversation is limited to scam/fraud/wallet-safety questions and proactive scam warnings; LLM text never executes Telegram bans, deletes, restrictions, or DKG writes by itself.

Local JSONL state is the bot's operational working memory for weak reports, watchlist state, digest state, and monitoring-only actions. Evidence-backed collaborative memory is written to DKG v10 Shared Memory through the OpenClaw adapter.

The bot separates local analysis confidence from DKG confidence. Report-only evidence does not automatically snowball into high-confidence bans; DKG evidence must be credible, and non-admin reports cannot directly trigger a Telegram ban. Plain watchlist monitoring stays local-only; DKG writes are reserved for evidence-backed actions, reports, campaigns, appeals, reviews, restrictions, and bans.

TRACaBot applies graduated autonomous enforcement by default: low-confidence events are logged, medium-confidence events can be deleted and restricted, and high-confidence events can be deleted and banned. It also writes and queries scam domains in DKG Shared Memory, so a phishing or Telegram lure domain seen in one community can be flagged in another. Repeated domains, wallets, scam patterns, or text fingerprints are clustered into local campaign signals and can be written as fraud_campaign DKG events when the same wave repeats.

There is no curator-controlled promotion step in TRACaBot. Once an event meets the high-confidence publish policy, the bot immediately asks the OpenClaw DKG adapter to publish that event root. If the publish step fails, the Shared Memory write is kept and the error is recorded for audit.

Security Model

• Secrets stay in .env or service environment files and are ignored by Git.
• Manual /ban requires a configured admin or Telegram chat admin.
• /report includes duplicate checks, reporter rate limits, self-report rejection, and evidence requirements.
• Telegram API calls have request timeouts.
• DKG reads/writes go through the OpenClaw DKG adapter HTTP client, not shell interpolation.
• Accepted DKG evidence is structured and bounded; duplicate, rate-limited, targetless, and no-pattern reports are local-only.
• Reporter reputation is tracked locally from accepted/high-confidence reports so consistently helpful reporters receive more trust without letting them bypass duplicate or rate-limit controls.
• High-confidence eligible fraud memory is auto-published with a targeted OpenClaw adapter publishSharedMemory call.
• Appeal, review, and watchlist events are evidence-backed DKG writes so operators can explain or correct decisions without silently mutating history.

Requirements

• Node.js >=22.20.0
• Running DKG v10 node with OpenClaw DKG adapter setup
• Telegram bot token from BotFather

Install

1. Install and set up DKG/OpenClaw on the host:

npm install -g @origintrail-official/dkg
dkg openclaw setup --workspace /root/.openclaw/workspace --name tracabot --port 9200 --no-fund

2. Create and configure a Telegram bot:

Open @BotFather
/newbot
Choose a display name and username
Copy the token into TELEGRAM_BOT_TOKEN
/setcommands

Paste this command list into BotFather:

scan - Check scam risk for a user, wallet, message, or SangMata alert
report - Report suspicious evidence to shared DKG memory
ban - Ban a replied target when admin safeguards pass
stats - Show recent fraud intelligence and source activity
why - Explain evidence behind a tracabot event
watch - Locally watch a user, ID, username, or SangMata target
unwatch - Remove a local watch target
watchlist - Show active watches, mutes, and review items
appeal - Submit a correction request for an event
review - Admin review decision for an event
digest - Summarize recent actions and campaign signals
help - Show tracabot commands and safeguards

Invite the bot to your group and grant admin rights for deleting messages, restricting users, and banning users.

3. Install TRACaBot:

git clone https://github.com/brxtrac/tracabot.git
cd tracabot
npm install
cp .env.example .env

4. Edit .env:

TELEGRAM_BOT_TOKEN=your-bot-token
TRACABOT_ADMINS=123456789,@your_admin_username
TRACABOT_CONTEXT_GRAPH=tracabot
TRACABOT_DKG_MODE=openclaw-adapter
TRACABOT_AUTO_BAN=true
TRACABOT_ACTION_THRESHOLD=85
TRACABOT_AUTO_DELETE=true
TRACABOT_AUTO_RESTRICT=true
TRACABOT_WARN_THRESHOLD=60
TRACABOT_RESTRICT_THRESHOLD=75
TRACABOT_BAN_THRESHOLD=90
TRACABOT_PROACTIVE_SCAN_MINUTES=30
TRACABOT_TELEGRAM_TIMEOUT_MS=30000
DKG_NODE_URL=http://127.0.0.1:9200
TRACABOT_STORE_PATH=./data/tracabot-events.jsonl
TRACABOT_CONVERSATIONAL=true
TRACABOT_LLM_PROVIDER=auto
TRACABOT_LLM_BASE_URL=
TRACABOT_LLM_API_KEY=
TRACABOT_LLM_MODEL=
OPENCLAW_CONFIG_PATH=
TRACABOT_CONVERSATION_MIN_CONFIDENCE=60
TRACABOT_PROACTIVE_REPLY_THRESHOLD=75
TRACABOT_CONVERSATION_RATE_LIMIT_SECONDS=60
TRACABOT_CONVERSATION_MAX_CHARS=700
TRACABOT_JOIN_CHALLENGE=false
TRACABOT_JOIN_CHALLENGE_TTL_SECONDS=60
TRACABOT_JOIN_CHALLENGE_ACTION=kick
TRACABOT_JOIN_CHALLENGE_DELETE_ON_PASS=true
TRACABOT_JOIN_CHALLENGE_DELETE_BAD_ATTEMPTS=true
TRACABOT_JOIN_CHALLENGE_DKG_VALIDATE=true

5. Start manually:

npm start

6. Optional systemd service: create a unit with WorkingDirectory=/root/tracabot, EnvironmentFile=/root/tracabot/.env, and ExecStart=/usr/bin/node /root/tracabot/bin/tracabot.js, then run sudo systemctl daemon-reload and sudo systemctl enable --now tracabot.service.

[Unit]
Description=TRACaBot Telegram anti-scam agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/root/tracabot
EnvironmentFile=/root/tracabot/.env
ExecStart=/usr/bin/node /root/tracabot/bin/tracabot.js
Restart=always
RestartSec=5
User=root

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now tracabot.service
sudo systemctl status tracabot.service

Run the DKG write/read demo without Telegram:

npm run demo

Run OpenClaw skill tools directly:

npm run skill -- scan_target '{"telegramUserId":"8388593201","text":"possible support impersonation"}'
npm run skill -- get_digest '{}'
npm run skill -- get_watchlist '{"filter":"all"}'

Run tests:

npm test
npm audit --omit=dev
npm run test:commands

Troubleshooting

• Bot does not respond: confirm TELEGRAM_BOT_TOKEN, service logs, group privacy settings, and that the bot was invited to the correct group.
• Bot cannot delete, restrict, ban, or run join challenge enforcement: confirm Telegram admin permissions for deleting messages, restricting users, and banning users.
• /ban says admin required: add your numeric Telegram ID or username to TRACABOT_ADMINS, or run the command from a Telegram chat-admin account.
• DKG evidence is missing: confirm dkg status, DKG_NODE_URL, TRACABOT_DKG_MODE=openclaw-adapter, and any DKG_AUTH_TOKEN required by your adapter.
• Skill command returns JSON error: run from the project root, pass valid JSON, and check OPENCLAW_DKG_ADAPTER_PATH only if the adapter is installed outside standard OpenClaw paths.
• Conversational replies are template-only: confirm OpenClaw gateway is running, TRACABOT_CONVERSATIONAL=true, and TRACABOT_LLM_PROVIDER=auto. Run /status as an admin to see the discovered OpenClaw model without exposing credentials.
• Demo refuses to write: set TRACABOT_TEST_MODE=true for npm run demo; this prevents accidental production test writes.

OpenClaw Setup

The DKG v10 OpenClaw setup command can be used before running TRACaBot:

dkg openclaw setup --workspace /root/.openclaw/workspace --name tracabot --port 9200 --no-fund

The OpenClaw-facing skill manifest lives at skills/tracabot/skill.json. The CLI entrypoint is node ./bin/tracabot-skill.js <tool> <json-input> and returns JSON suitable for OpenClaw agent tooling.

Example systemd unit:

[Service]
Type=simple
WorkingDirectory=/root/tracabot
EnvironmentFile=/root/tracabot/.env
ExecStart=/usr/bin/node /root/tracabot/bin/tracabot.js
Restart=always
RestartSec=5
User=root