GOSSY Logo
Whitepaper v1.3

Gossy Protocol — Technical Blueprint

Deep dive into the cryptography, infrastructure, and operational design that powers censorship-resistant social at scale.

01

Executive Summary

Gossy is a decentralized, censorship-resistant social protocol engineered for anonymity, verifiability, and mainstream performance. Content persists on IPFS, coordination happens on-chain, and ultra-fast feeds are delivered through a secure relayer and query stack.

  • Privacy-first identity: wallet-based pseudonyms with zero PII collection.
  • Immutable content: media and posts hashed to IPFS for permanent provenance.
  • On-chain verifiability: the GossyCore contract emits the canonical social event log.
  • High performance: relayer + query layer routinely delivers sub-100ms feeds.
  • Battle-tested auth: dual-layer HMAC and wallet signature validation across services.
  • Scalable infrastructure: queue-driven architecture with clustering, circuit breakers, and adaptive load management.

02

Why Now

Centralized networks monetize surveillance and mediate speech through opaque moderation. Users need a verifiable, anonymous alternative that feels familiar yet guarantees freedom of expression and data self-sovereignty.

03

Protocol Overview

Identity

  • Users interact via self-custodied EOA wallets; no usernames or KYC.
  • Sessions are lightweight and optional; every write is wallet-authenticated.

Content

  • Posts are versioned JSON envelopes; media is pinned to IPFS.
  • Each envelope includes a SHA-256 contentHash for integrity on retrieval.

Coordination

  • GossyCore emits all post + reaction events for transparent indexing.
  • Relayer batches signed requests, optimizes gas, and enforces policy.

Reading

  • Query server aggregates on-chain events and resolves IPFS content.
  • Feeds, search, and trending endpoints return near-real-time views.

04

Architecture Layers

Client Apps

  • React Native + web clients with embedded wallets (ethers v6).
  • Upload helper services manage IPFS media, thumbnails, and retries.
  • Local caching blends with server TTL for smooth offline-friendly UX.

Relayer API

  • HMAC request authentication plus wallet signature validation.
  • High-performance job queue submits posts, reactions, and reports.
  • Circuit breakers and rate controls guard the chain from bad actors.

Arbitrum Nova

  • GossyCore contract handles post lifecycle events.
  • Future-proof hooks for GSX token utility and governance events.

IPFS Storage

  • Pinned clusters replicate content across regions.
  • Optional encrypted payloads for premium or private channels.

Query Server

  • Aggregates events, resolves CIDs, computes trending quality scores.
  • Provides search, hashtag, location, and user feeds via HMAC-secured APIs.

05

Core Components

Client

  • Handles wallet key management, session auth, and optimistic UI updates.
  • Services: IPFSService, MediaService, QueryApiService, RelayerApiService.

Blockchain

  • Arbitrum Nova (chainId 42170) hosts the contracts.
  • Post types: Gossip (1) and Comment (2); reaction types map to likes/dislikes.

Storage

  • JSON envelopes with strict versioning and hashing requirements.
  • Media uploaded via multipart with optional transcoding for previews.

Query Server

  • HMAC-SHA256 auth with API key + secret.
  • Feeds include main, user, hashtag, geohash, and qualityScore-based trending.

06

IPFS Post Envelope v2.0.0

{
  "version": "2.0.0",
  "type": "gossip | comment",
  "content": {
    "text": "...",
    "media": [{
      "type": "image | video | audio | document",
      "cid": "...",
      "mimeType": "...",
      "size": 12345,
      "thumbnail": "optional-cid"
    }],
    "links": [{ "url": "https://...", "title": "..." }]
  },
  "metadata": {
    "author": "0x...",
    "timestamp": 1710000000,
    "targets": [{ "type": "hashtag | location | user", "value": "..." }],
    "language": "en",
    "visibility": "public"
  },
  "technical": {
    "client": "GOSSYApp",
    "clientVersion": "1.0.0",
    "platform": "ios | android | web | desktop",
    "contentHash": "sha256:<64 hex>",
    "encrypted": false
  }
}

07

End-to-End Flows

Posting

  • Compose gossip or comment, select discovery targets (hashtags, users, locations).
  • Upload media followed by JSON envelope; compute and store contentHash.
  • Signed request hits relayer /api/v1/posts/create; job queues a GossyCore transaction.
  • Events propagate to the query server, updating feeds in near real time.

Reactions

  • Clients optimistically update UI for like/dislike events.
  • Relayer validates signature + nonce, then submits reaction to chain.
  • Query server ingests events and recalculates qualityScore.

08

Security & Privacy

Signatures

  • Deterministic wallet signing for every write operation.
  • Replay protection enforced through timestamp validation and nonce management.

HMAC Layer

  • All relayer + query requests include HMAC-SHA256 headers.
  • Strict signature windows and API key lifecycle management.

Integrity

  • Clients verify technical.contentHash post-retrieval from IPFS.
  • Optional encrypted payloads maintain privacy for premium channels.

Abuse Controls

  • Rate limits, velocity caps, and per-address throttling.
  • Relayer queue isolates failure domains and enables kill-switches.

09

Performance & Scalability

Target SLAs

  • Main feed: 30–70ms
  • User profile: <50ms
  • Trending feed: <40ms
  • Subgraph footprint: <50MB for 100K users

Mechanisms

  • Redis-backed queue processing with clustered workers.
  • Circuit breakers for third-party dependencies.
  • Pre-aggregation and caching to maintain sub-100ms render times.
  • Event-driven subgraph schema optimized for low gas + storage.

10

GSX Token & Incentives

  • Protocol currency surfaced in wallet, analytics, and notifications.
  • Utility spans creator rewards, boosts, tipping, and governance signaling.
  • Distribution allocations are staged pending DAO + legal finalization.
  • Client integrations remain environment-gated until contracts finalize.

11

Deployment & Configuration

  • Primary network: Arbitrum Nova (42170); contracts resolved via env config.
  • Service endpoints: QUERY_API_URL, RELAYER_API_URL, IPFS_API_URL, IPFS_GATEWAY_URL.
  • Auth headers: X-API-Key, X-Signature, X-Timestamp, X-Wallet-Address, X-Wallet-Signature.
  • Reference docs: API specs, Graph guides, IPFS structure, and wallet signature playbooks.

12

Roadmap

Phase 1 · Q1–Q3 2025

  • Ship core clients with IPFS posting + reactions.
  • Integrate relayer security hardening and post schema audits.

Phase 2 · Q4 2025

  • Launch GSX token mechanics and incentive programs.
  • Bootstrap DAO governance + community operations.

Phase 3 · 2026

  • Public beta, creator rewards, encrypted premium channels.
  • On-chain access control + subscription tooling.

Phase 4 · 2027–2029

  • Global scale with SDKs/APIs and cross-chain options.
  • Full DAO transition and community-owned governance.

13

Glossary

Gossip
Top-level post (type = 1).
Comment
Reply post (type = 2) with parentPostId > 0.
Targets
Discovery hints prefixed with h: hashtag, u: user, l: location.
qualityScore
likeCount - dislikeCount; powers trending feeds.
CID
Content Identifier for IPFS-stored objects.

15

Client Alignment Notes

  • Mobile + web clients consume feeds via the query server; Graph indexing remains backend detail.
  • "Zero-Query" UX refers to server-side caching and pre-aggregation, subject to deployment SLAs.
  • Premium channel encryption and subscription enforcement remain roadmap deliverables.

16

Contact

  • Website: https://gossy.io
  • Confidential — do not redistribute without permission.