Web3 Shoutbox

A decentralized, embeddable shoutbox widget powered by XMTP for end-to-end encrypted messaging and GunDB for real-time presence. No backend server required — the entire system runs in the browser.

What is this?

Web3 Shoutbox is a real-time chat widget that any website can embed via an <iframe>. Identity is anchored to crypto wallets, all messages are end-to-end encrypted via XMTP's MLS protocol, and presence (who is online) is tracked peer-to-peer through GunDB. Zero server infrastructure required — just static hosting.

Features

🔐 End-to-end encryption — MLS protocol (RFC 9420) via XMTP, mandatory on all messages
👛 Wallet-based identity — connect with MetaMask, Rainbow, Coinbase, or any WalletConnect wallet
👥 Real-time presence — see who is online via GunDB CRDT-based peer-to-peer sync
📦 Embeddable widget — drop an <iframe> on any website with a single line of HTML
🔄 Sliding window groups — XMTP groups rotate on a schedule, naturally resetting member counts
🏗️ No backend — fully JAMstack, deploy to any static host
🗳️ Deterministic leader election — client-side, coordination-free group creation
🌙 Dark mode — full light/dark theme support
📱 Mobile responsive — works down to 280px width
🔔 Toast notifications — real-time feedback for connections, errors, and transitions

Quick Start

Clone the repository

git clone <repository-url>
cd web3-shoutbox-platform

Install dependencies
```
npm install
```

Configure environment variables

cp .env.local.example .env.local
# Edit .env.local — set VITE_XMTP_ENV=dev and
# VITE_APP_URL=http://localhost:3000

Run the development server
```
npm run dev
```
Open in browser Navigate to http://localhost:3000

Embed the Widget

Add this to any website to embed the shoutbox:

<iframe
  src="https://your-shoutbox-domain.com/embed/shoutbox"
  width="400"
  height="600"
  frameborder="0"
  style="border-radius: 12px; box-shadow: 0 4px 24px rgba(0,0,0,0.12);"
  allow="clipboard-write">
</iframe>

The widget auto-detects the parent page URL as the chat room. Pass ?room=my-room&theme=dark for customization.

👉 Full Embed Guide →

Tech Stack

Technology	Version	Purpose
Vite	7.x	Build tool & dev server
React	19.x	UI library
TypeScript	5.x	Type safety
Tailwind CSS	4.x	Styling
XMTP browser-sdk	7.x	E2E encrypted messaging (MLS)
GunDB	0.2020.x	CRDT-based real-time presence
wagmi	3.x	Ethereum React hooks
viem	2.x	Ethereum library
@reown/appkit	1.x	Wallet connection (WalletConnect)
Zustand	5.x	State management
Zod	4.x	Runtime validation
Sonner	2.x	Toast notifications

Architecture Overview

The shoutbox is a dual-protocol, browser-only system:

XMTP handles encrypted message transport — messages are signed with wallet keys and encrypted via MLS
GunDB handles ephemeral presence — who is currently on the page, tracked via heartbeat TTL. GunDB should be on https if the shoutbox is on https.

These layers are intentionally decoupled. GunDB owns the UI roster; XMTP owns message delivery. Presence changes do not trigger XMTP group mutations.

Groups use a sliding window model — instead of one permanent group per URL, groups rotate on a time-based schedule (default: 60 minutes). This avoids the 250-member cap and eliminates expensive removeMembers MLS operations.

👉 Full Architecture Doc →

Project Structure

web3-shoutbox-platform/
├── src/
│   ├── components/
│   │   ├── auth/              # ConnectWallet button
│   │   ├── chat/              # ChatContainer, MessageList, MessageBubble, MessageInput
│   │   ├── layout/            # AppLayout, Header
│   │   ├── presence/          # PresencePanel, UserAvatar
│   │   ├── providers/         # Web3Provider, XmtpProvider, GunProvider, ThemeProvider
│   │   ├── ui/                # Skeleton, XmtpStepIndicator
│   │   └── ErrorBoundary.tsx  # Top-level error boundary
│   ├── config/
│   │   └── env.ts             # Zod-validated environment variables
│   ├── hooks/
│   │   ├── useEmbed.ts        # Embed detection, PostMessage API, auto-resize
│   │   ├── useGroupLifecycle.ts # Window management, leader election orchestration
│   │   ├── useLeaderElection.ts # Deterministic leader computation
│   │   ├── useOnlineUsers.ts  # Presence subscription → OnlineUser[]
│   │   ├── usePresence.ts     # Join/leave room, heartbeat lifecycle
│   │   ├── useShoutboxRoom.ts # Unified room hook (presence + messaging + groups)
│   │   ├── useXmtpClient.ts   # XMTP client state from provider
│   │   └── useXmtpConversation.ts # Group message send/receive
│   ├── lib/
│   │   ├── embed-messaging.ts # PostMessage protocol, auto-resize, config parsing
│   │   ├── group-lifecycle.ts # GunDB group read/write/subscribe
│   │   ├── gun.ts             # GunDB singleton instance
│   │   ├── gun-presence.ts    # Low-level presence read/write
│   │   ├── leader-election.ts # Deterministic leader election algorithm
│   │   ├── retry.ts           # Generic retry with exponential backoff
│   │   ├── url-utils.ts       # URL normalization + SHA-256 room keys
│   │   ├── utils.ts           # Tailwind cn() helper
│   │   └── xmtp.ts            # XMTP client factory
│   ├── pages/
│   │   ├── embed/
│   │   │   └── EmbedShoutboxPage.tsx  # Compact embed widget page
│   │   ├── NotFoundPage.tsx
│   │   ├── RoomBrowserPage.tsx
│   │   ├── SettingsPage.tsx
│   │   └── ShoutboxPage.tsx   # Main standalone shoutbox page
│   ├── services/
│   │   ├── groupLifecycleService.ts  # Group creation, discovery, failover
│   │   ├── messagingService.ts       # XMTP send/receive with retry
│   │   └── presenceService.ts        # GunDB presence join/leave/heartbeat
│   ├── stores/
│   │   ├── authStore.ts       # Wallet connection state
│   │   ├── chatStore.ts       # Messages and chat UI state
│   │   └── presenceStore.ts   # Online users state
│   ├── types/
│   │   ├── embed.ts           # PostMessage event/command types
│   │   ├── errors.ts          # Typed error classes + error classifiers
│   │   ├── group.ts           # GroupWindow, GroupState
│   │   ├── gun.d.ts           # GunDB type declarations
│   │   ├── message.ts         # ShoutboxMessage
│   │   ├── presence.ts        # PresenceRecord, OnlineUser
│   │   └── result.ts          # Result<T, E> pattern (ok/err)
│   ├── App.tsx                # Router + provider tree
│   ├── globals.css            # Tailwind base + custom animations
│   └── main.tsx               # Entry point
├── public/
│   ├── test-embed.html        # Interactive embed test page
│   ├── _headers               # CDN headers for iframe embedding
│   └── _redirects              # SPA fallback redirects
├── scripts/
│   ├── copy-spa-routes.mjs    # Materialize routes for IPFS (no SPA rewrite)
│   └── gun-relay.mjs          # Local GunDB relay
├── .github/workflows/
│   ├── ci.yml                 # Tests, lint, static export verification
│   └── deploy.yml             # Pin `out/` to IPFS with PinMe on main
├── docs/                      # Documentation
│   ├── ARCHITECTURE.md
│   ├── CONTRIBUTING.md
│   ├── EMBED_GUIDE.md
│   └── SETUP.md
├── e2e/                       # Playwright E2E test directory
├── .env.local.example         # Environment variable template
├── eslint.config.mjs          # ESLint configuration
├── index.html                 # Vite entry HTML
├── package.json               # Dependencies & scripts
├── playwright.config.ts       # Playwright configuration
├── postcss.config.mjs         # PostCSS (Tailwind)
├── tsconfig.json              # TypeScript configuration
├── vite.config.ts             # Vite configuration
└── vitest.config.ts           # Vitest configuration

Development

Command	Description
`npm run dev`	Start development server on port 3000
`npm run build`	Type-check and build for production (output: `out/`)
`npm run preview`	Preview production build locally
`npm run test`	Run unit tests with Vitest
`npm run test:watch`	Run unit tests in watch mode
`npm run test:e2e`	Run Playwright E2E tests
`npm run lint`	Run ESLint

Environment Variables

Create a .env.local file from the template:

cp .env.local.example .env.local

Variable	Required	Default	Description
`VITE_WALLETCONNECT_PROJECT_ID`	No	—	Accepted for backwards compatibility; unused
`VITE_XMTP_ENV`	Yes	—	XMTP network environment: `dev` or `production`
`VITE_APP_URL`	Yes	—	Public base URL where the app is served. A full URL or a bare hostname both work; bare hostnames are normalized to HTTPS (`shoutbox.pinme.dev` → `https://shoutbox.pinme.dev`). Use `http://localhost:3000` locally.
`VITE_GUN_RELAY_PEERS`	No	`http://localhost:8765/gun`	Comma-separated GunDB relay peer URLs; use a hosted HTTPS relay in production
`VITE_SLIDING_WINDOW_MINUTES`	No	`60`	Duration of each sliding window epoch in minutes
`VITE_SHOUTBOX_BRIDGE_ADDRESSES`	No	—	Optional bridge addresses seated in every room
`VITE_XMTP_MLS_DIAGNOSTICS`	No	`false`	Set to `true` to emit `[xmtp-mls-diagnostics-v1]` JSON in production builds

VITE_* values are embedded in the public browser bundle. Never put private keys, API tokens, or other credentials in them.

Unit tests do not require a .env.local: vitest.config.ts supplies safe test defaults for VITE_XMTP_ENV and VITE_APP_URL.

Deployment

The shoutbox is a static site — out/ is the whole application. Pushes to main pin that directory to IPFS with PinMe via .github/workflows/deploy.yml, the same deployment pattern as the redhaven and fairhaven repos. There is no server.

npm run build

CI (.github/workflows/ci.yml) runs unit tests, lint, and a production build on pushes and pull requests to main and develop.

The build also materializes out/rooms/, out/settings/, and out/embed/shoutbox/. IPFS gateways have no SPA rewrite, so those copies are what keep deep links and the embeddable widget working after a PinMe deploy. public/_redirects and public/_headers only apply on hosts that support them (Netlify, Cloudflare Pages).

Custom domain or PinMe subdomain

VITE_APP_URL is the public base URL shown by the app; it does not control where PinMe publishes the build. PinMe treats the PINME_DOMAIN value differently depending on whether it contains a dot:

shoutbox (no dot) creates a PinMe subdomain: https://shoutbox.pinme.dev
shoutbox.pinme.dev (contains a dot) is treated as a custom DNS domain and requires you to control the DNS for pinme.dev

Since pinme.dev is PinMe's root domain, use the subdomain form to publish at shoutbox.pinme.dev:

VITE_APP_URL=shoutbox.pinme.dev
PINME_DOMAIN=shoutbox

VITE_APP_URL accepts a bare hostname and normalizes it to https://shoutbox.pinme.dev. If PINME_DOMAIN is omitted, PinMe deploys to its default gateway URL, and VITE_APP_URL should match that URL instead.

For a domain you own (for example chat.example.com), use the full hostname as PINME_DOMAIN and configure the DNS records PinMe provides.

Repository configuration

Add configuration under Settings → Secrets and variables → Actions. Use repository variables for VITE_* values and PINME_DOMAIN — they are public build configuration, not secrets. The workflows do not declare a GitHub environment, so environment-scoped variables are not available.

Required secret:

Secret	Description
`PINME_APPKEY`	PinMe API key (dashboard or `pinme show-appkey`)

Variables (the workflows read vars.*, then fall back to secrets.* for backwards compatibility, then to the defaults below):

Variable	Default	Description
`VITE_XMTP_ENV`	`production`	XMTP network (`dev` or `production`)
`VITE_APP_URL`	`https://web3-shoutbox.pinme.eth.limo/`	Public base URL. Bare hostnames are normalized to HTTPS. Set this to the same origin configured in `PINME_DOMAIN`
`VITE_GUN_RELAY_PEERS`	`http://localhost:8765/gun`	Comma-separated hosted GunDB relay URLs. Without a hosted relay, visitors cannot see each other
`VITE_SLIDING_WINDOW_MINUTES`	`60`	Sliding window epoch length
`VITE_SHOUTBOX_BRIDGE_ADDRESSES`	—	Optional bridge addresses seated in each room
`PINME_DOMAIN`	—	PinMe subdomain name without a dot (`shoutbox` → `https://shoutbox.pinme.dev`), or a full DNS domain you control (`chat.example.com`). Set together with `VITE_APP_URL`; omit for the default gateway URL
`VITE_XMTP_MLS_DIAGNOSTICS`	`false`	Set to `true` to emit `[xmtp-mls-diagnostics-v1]` JSON in production builds; keep off normally

VITE_WALLETCONNECT_PROJECT_ID is still accepted as a secret but is unused.

CI passes vars.X || secrets.X || <default> to both the test and build steps, so the pipeline still works when variables are not configured. CI falls back to dev and http://localhost:3000; the deploy workflow falls back to the production values in the table. Unit tests use their own safe defaults and never read repository secrets.

Manual deploy

npm ci
npm run build
npx pinme@2.0.12 set-appkey "$PINME_APPKEY"

if [ -n "${PINME_DOMAIN:-}" ]; then
  npx pinme@2.0.12 upload ./out --domain "$PINME_DOMAIN"
else
  npx pinme@2.0.12 upload ./out
fi

Other static hosts

Vercel, Netlify, and Cloudflare Pages still work with the same out/ directory:

npx vercel --prod
npx netlify deploy --prod --dir=out

For Cloudflare Pages, use build command npm run build and output directory out.

Documentation

Architecture — System design, data flow, and key decisions
Embed Guide — Third-party integration guide with PostMessage API
Setup Guide — Detailed environment setup and troubleshooting
Contributing — Code style, workflow, and PR guidelines

License

MIT License — see LICENSE for details.

Navigation Menu

Repository navigation

About

Repository files navigation

Web3 Shoutbox

What is this?

Features

Quick Start

Embed the Widget

Tech Stack

Architecture Overview

Project Structure

Development

Environment Variables

Deployment

Custom domain or PinMe subdomain

Repository configuration

Manual deploy

Other static hosts

Documentation

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
e2e		e2e
ops		ops
public		public
scripts		scripts
src		src
.env.local.example		.env.local.example
.gitignore		.gitignore
.npmrc		.npmrc
README.md		README.md
eslint.config.mjs		eslint.config.mjs
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

Web3 Shoutbox

What is this?

Features

Quick Start

Embed the Widget

Tech Stack

Architecture Overview

Project Structure

Development

Environment Variables

Deployment

Custom domain or PinMe subdomain

Repository configuration

Manual deploy

Other static hosts

Documentation

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages