Skip to content

AGENTS.md

Latest commit

 

History

History
103 lines (77 loc) · 3.71 KB

AGENTS.md

File metadata and controls

103 lines (77 loc) · 3.71 KB
Raw

GhostLink

Private Relationship Protocol for Sui-native invisible social graph infrastructure.

Project Structure

Bun monorepo with workspaces:

apps/
  web/          # Vite + React + Sui dApp Kit frontend
  server/       # Bun + Hono + SQLite backend (relayer)
packages/
  shared/       # Shared TypeScript types (@ghostlink/shared)
contracts/
  ghostlink/    # Sui Move smart contracts

Development Commands

bun install           # Install dependencies
bun run seed          # Seed SQLite database (required first time)
bun run dev:server    # Start backend at http://localhost:3000
bun run dev:web       # Start frontend at http://localhost:5173

Build order matters: build:shared must run before build:web or build:server.

bun run build         # Builds all in correct order
bun run typecheck     # Typechecks all packages (builds shared first)

Environment Setup

Copy .env.example to .env in project root. Key variables:

Server:

  • DEMO_MODE=true — Local mode with simulated Sui objects (no on-chain writes)
  • DEMO_MODE=false — Testnet mode requiring SUI_PACKAGE_ID and SUI_RELAYER_PRIVATE_KEY

Frontend:

  • VITE_API_BASE_URL=http://localhost:3000
  • VITE_SUI_NETWORK=testnet

Architecture Notes

Shared Types

packages/shared/src/index.ts exports all domain types. Both apps/web and apps/server import from @ghostlink/shared. Types include: Relationship, RelationshipCap, HiddenGroup, GroupMember, MembershipProof, RelationshipEvent.

Server Entry

apps/server/src/index.ts — Hono app with SQLite via Drizzle ORM. Routes: /api/relationships, /api/groups, /api/proofs, /api/events. SSE endpoint at /api/events/stream.

Web Entry

apps/web/src/main.tsx — React 19 with SuiProvider (dApp Kit), QueryClientProvider, BrowserRouter. Routes defined in App.tsx using lazy loading.

Sui Integration

  • Frontend: @mysten/dapp-kit for wallet connection, @mysten/sui for client
  • Server: @mysten/sui for relayer transactions
  • Contract: contracts/ghostlink/sources/protocol.move defines Relationship, RelationshipCap, HiddenGroup, GroupMember, MembershipProof objects

ZK Proofs

Proof scheme is ghostlink-merkle-v1. Server maintains Merkle tree commitments in groupMemberCommitments and groupRoots tables. Proof verification checks path, nullifier uniqueness, expiry, and attestation signature.

Internationalization (i18n)

  • Library: react-i18next with i18next-browser-languagedetector
  • Config: apps/web/src/lib/i18n.ts
  • Locales: apps/web/src/locales/en.json, apps/web/src/locales/zh.json
  • Auto-detects browser language, persists choice to localStorage
  • Language switcher in top navigation bar

Key Files

Purpose Path
Shared types packages/shared/src/index.ts
DB schema apps/server/src/db/schema.ts
Server entry apps/server/src/index.ts
Web entry apps/web/src/main.tsx
Sui provider apps/web/src/lib/sui.tsx
i18n config apps/web/src/lib/i18n.ts
Move contract contracts/ghostlink/sources/protocol.move

Move Contract

Edition 2024. Entry functions for testnet relayer:

  • record_relationship — Creates relationship + caps for both members
  • record_hidden_group — Creates hidden group
  • record_membership_proof — Creates membership proof

User-facing functions (wallet-initiated):

  • create_relationship, accept_relationship
  • create_hidden_group, add_group_member
  • generate_membership_proof

Demo Flow

  1. Create/accept relationship → inspect capabilities
  2. Create hidden group → invite members
  3. Generate ZK membership proof
  4. Verify proof → unlock demo content
  5. Review Sui object references from relayer