Skip to main content

nexus-telegram

The Telegram command gateway. It turns high-level chat commands into Nexus goals/tasks and relays status and alerts back.

Responsibilities​

  • Receive high-level commands
  • Authenticate allowed users (allowlist)
  • Create Nexus goals
  • Reply with status
  • Send approval notifications
  • Send failure alerts

Stack​

LibraryUse
teloxideTelegram bot framework
tokioasync runtime
serdeserialization
tracinglogs / spans
reqwestcalls into Nexus Core
axum (optional)webhook receiver

teloxide lets you focus on bot business logic rather than Telegram API plumbing.

Commands​

/nexus create goal Build auth system
/nexus status
/nexus approve task_123
/nexus pause project nexus
/nexus run sprint current

Example interaction:

/nexus create goal "Build authentication system for my app"

→ Goal created.
→ Drafted 8 tasks.
→ Waiting for approval in Nexus UI.

Security​

Only allowlisted Telegram user IDs may issue commands (TELEGRAM_ALLOWED_USERS, set in prod); an audit of inbound commands lives in the telegram_commands collection. An empty list denies everyone — fail-closed since nexus-platform 445e107, deployed 2026-09-05 (audit C7 closed). Sensitive actions still route through the approvals flow in the UI.

Approval execution (2026-09-05). /approve <id> runs the proposal's actions strictly in order (save_digest, cancel_order, create_order, swap, ladder_cancel, ladder_reprice). The first failure stops the plan; the approval is recorded as failed with a per-action report and stays in /pending for a retry — it is never recorded as approved when an action did not run. ladder_cancel calls the exec's POST /v1/ladder/cancel and only counts as success when every expected rung is cancelled (or was already).

ladder_reprice (2026-09-09). The action behind a ladder_raise approval — the one the worker's accum_ladder job raises once the analysis, dream and decision cycles have voted for a rung move. It POSTs the approved {rung, trigger, budget_usdc?} set to the exec's POST /v1/ladder/reprice and fails the step if the exec applied a different number of moves than were approved. The exec re-checks its own bounds — each new trigger at least 5% below the live oracle index, no single call raising a trigger by more than 25%, the total ladder budget free to shrink but never to grow, rungs still strictly descending, Armed / Firing / fired / cancelled rungs refused — and applies the whole set or none of it (nexus-solana). It runs only from /approve <id> issued by a user in TELEGRAM_ALLOWED_USERS (there are no inline buttons), and it is the only way a rung's trigger price changes after boot. Built and unit-tested; the exec's refusal guards were exercised against the live SOL ladder on 2026-09-09, but no approval of this kind has been raised or approved yet, so the action itself is still unexercised end to end.

/ladder (2026-09-09). The same rung view on demand: per asset, each rung's trigger, distance from spot, budget and state, ending with the reminder that rungs move only through an owner approval.

Typed approvals (audit H3, nexus-platform e3d7c4c, deployed 2026-09-05 14:54Z). Approvals are records in accum_approvals with 22-char ids (/approve accepts a unique prefix of ≥ 8 chars), a 6 h TTL (ACCUM_APPROVAL_TTL_SECS), a compare-and-swap claim so two operators cannot run the same plan twice, per-action resume, and a decision hash that is re-validated before execution. Legacy six-hex approvals were expired by the upgrade and re-paged as typed records. Not yet exactly-once: an executor crash between an action and its progress write can leave a resumable stale claim (audit 2026-09-05 F2, open).