Voicescape — on-chain identity and tipping for AI agents MCP server

Voicescape — Custom blockpages with on-chain tips

Status: MVP wired end-to-end. Contracts compile, all 10 tests pass, frontend typechecks and next build succeeds. Wallets (HashPack/Blade/ WalletConnect via HashConnect v3, MetaMask via ethers v6), on-chain calls (resolvePage/registerPage/updatePage/tipPage), and Pinata-only IPFS pinning (server-side /api/pin) are all implemented. Nothing was deployed anywhere, and no real keys exist in this repo.

Architecture

┌──────────────┐      ┌──────────────────┐      ┌─────────────────┐
│   Builder    │      │   /api/vibecode  │      │    IPFS         │
│  (Next.js)   │─────▶│  (Anthropic API) │      │ (Pinata-only)   │
│ template +   │ JSON │  NL instruction  │      │  page content   │
│ AI chat edit │◀─────│  → page JSON     │      │  via /api/pin   │
└──────┬───────┘      └──────────────────┘      └────────┬────────┘
       │  publish: pin JSON → registerPage()             │
       ▼                                                 │
┌────────────────────────────────────────────────────────┴────────┐
│  Hedera (primary) / Polygon (fallback) — EVM smart contracts    │
│                                                                  │
│  VoicescapeRegistry:  username → (owner wallet, IPFS hash)       │
│  VoicescapeTips:      tipPage(username) payable                  │
│                       98% → page owner, 2% → treasury (on-chain) │
└──────────────────────────────────────────────────────────────────┘
       ▲                                                 │
       │  /[username]: resolvePage() → fetch IPFS → render + Tip button
┌──────┴───────┐
│ Public page  │
│  (Next.js)   │
└──────────

Key design decision: page content lives on IPFS; the chain stores only a registry mapping username → owner wallet → IPFS content hash. Putting full page HTML on-chain would be cost-prohibitive. Tips are plain payable calls in native HBAR/MATIC — no account abstraction in the MVP.

Repo layout

voicescape/
├── contracts/          # Solidity + Hardhat
│   ├── contracts/VoicescapeRegistry.sol
│   ├── contracts/VoicescapeTips.sol
│   ├── scripts/deploy.js      # refuses mainnet without CONFIRM_MAINNET=1; DRY_RUN=1 validates spend-free
│   └── test/voicescape.test.js
├── frontend/           # Next.js App Router + TypeScript
│   ├── app/page.tsx               # landing
│   ├── app/builder/page.tsx       # template picker + editor + vibecode chat + publish
│   ├── app/[username]/page.tsx    # public page + tip button
│   ├── app/api/pin/route.ts       # server-side Pinata pinning (JWT never in browser)
│   ├── app/api/vibecode/route.ts  # Anthropic-backed page editor
│   ├── components/PageRenderer.tsx
│   └── lib/ (schema, templates, wallet, chains, contracts, ipfs, tx,
│             server/publish.js)
├── ipfs/               # IPFS strategy notes (live code lives in frontend/lib/server)
├── README.md
└── .env.example        # every variable, documented, no real values

Transaction wiring

All on-chain calls go through frontend/lib/tx.ts, a TxSender abstraction with two implementations:

resolvePage, signer for registerPage/updatePage/tipPage.

• EVM (MetaMask, Polygon): ethers v6 — read-only JsonRpcProvider for

ContractCallQuery for reads; ContractExecuteTransaction signed in the wallet for writes. Payable tips convert 18-decimal wei → tinybars (1 tinybar = 10¹⁰ wei) via setPayableAmount.

• Hedera (HashPack/Blade/WalletConnect, HashConnect v3): @hashgraph/sdk

frontend/lib/contracts.ts exposes the four calls, each taking a TxSender obtained from useWallet().getTxSender() — no hidden global state.

Setup

# 1. Contracts
cd contracts && npm install

# 2. Frontend
cd ../frontend && npm install

# 3. Copy and fill env (see .env.example — never commit real keys)
cp ../.env.example ../.env   # then edit; or per-directory .env files

Contracts: compile, test, deploy

Shortened. The full README is on GitHub.