# Orb bot platform: design proposal

> Current status reviewed September 29, 2026. See [the release index](README.md) for shipped versus planned features, network, wallet signing and deployment boundaries. Older dated experiments below are retained as history.

> **Status.** Slices 1, 2 and part of 3 are built: applications with hashed revocable tokens, a
> versioned HTTP API, signed webhook events, an install flow with a per-community role, and a bot
> badge in chat. `docs/orb-bots.md` is the reference for what actually answers today; this file
> stays as the design record, including the parts still unbuilt. Voice has a room-scoped LiveKit grant where the deployment has SFU credentials;
> unavailable deployments return an explicit reason. The API is shipped; hosted bot workers
> and automatic YouTube audio extraction are not.

> **Plan versus ship, October 5.** Three parts of this design did not ship as written: no event
> cursor was built; the `/poll`, moderation-log and trading-alert apps were replaced by a generic
> app-command registry; and encrypted chat bodies are returned to apps as null rather than offering
> a readable copy. The voice-call grant and the no-YouTube-extraction rule did ship as planned.

The current Orb exposes a versioned application HTTP API; it does not yet ship a standalone developer SDK. Do not implement bots by automating normal user accounts or sharing Privy sessions. Give every bot its own service identity, separate from people and wallets, with an install record for each community.

## First usable slice

1. Developer registers an application and receives a revocable, hashed API token. A community owner installs it after reviewing a narrow permission list and the channels it may access.
2. Versioned HTTP API lets the bot send messages and respond to commands. Signed webhook events carry event ID, timestamp and community/channel IDs; replay and delivery retries are bounded. An event cursor supports recovery after downtime. The gateway can be added for bots needing low-latency events.
3. Bot commands are registered with names, arguments and permission requirements. Start with `/poll`, moderation logs and read-only trading alerts. Bots must not see encrypted messages by default; a conversation can opt into sharing a separate readable copy with an installed bot.
4. A voice bot joins LiveKit as a distinct participant through a short-lived, room-scoped server token. Limit it to the room and media permissions it needs. Music playback needs a licensed audio source; a YouTube or Spotify URL is metadata, not permission to restream its audio.

## Security boundaries

- Bot tokens are never Privy tokens. Bots have no `wallet`, `sign`, `transfer`, `trade` or `manage_roles` permission by default. Onchain actions require a separate user-reviewed intent and a scoped authorization designed for that exact action.
- Check community installation, channel visibility and bot permissions on every request and event. Restrict bot mentions and messages, rate-limit per bot/community, audit actions, and let owners revoke access immediately.
- Developers host their code in their own process or a sandboxed worker. Orb never executes uploaded bot code in the web process or the LiveKit SFU.
- A future marketplace should show permissions, publisher identity, data access and an uninstall button; verified status should follow review, not self-declaration.

This matches the separation used by [Discord applications and OAuth2](https://discord.com/developers/docs/topics/oauth2) and [application commands](https://docs.discord.com/developers/docs/interactions/slash-commands). [LiveKit Agents](https://docs.livekit.io/intro/basics/agents/) can join rooms as programmatic participants. The trading-alert bot also strengthens the Metropolis demo: it turns onchain market activity into a shared community interaction without letting an agent spend from a user's wallet.