WHITEPAPER

Gossy Protocol — Whitepaper

Version: 1.3
Date: August 2025

Executive Summary

Gossy is a decentralized, censorship-resistant social protocol built for anonymity and user sovereignty. Content lives on IPFS; on-chain coordination happens via a lightweight, gas-optimized core contract; fast user experiences are delivered via a secure relayer and a low-latency query layer. The system is designed for ultra-low cost and massive scalability while preserving cryptographic guarantees.

Privacy-first: Wallet-based pseudonymous identity; no emails/phones; minimal data surface.
Immutable content: Posts and media are stored on IPFS with content hashing.
On-chain verifiability: Post and reaction events are emitted by GossyCore for transparent state.
High performance: Query server provides sub-100ms feeds with caching and pre-aggregation.
Battle-tested auth: Dual-layer request authentication (HMAC) + wallet signature validation.
Scalable by design: Queue-driven relayer, Redis-backed processing, circuit breakers, clustering.

Why Now

Centralized social platforms monetize surveillance and control speech. Persistent identity coupling and opaque moderation enable unilateral takedowns and deplatforming. Gossy enables open, anonymous expression with cryptographic identity and verifiable integrity, while delivering a familiar, fast user experience for mainstream adoption.

Protocol Overview

Identity: Pseudonymous EOA wallets represent users. No usernames or PII. Sessions are lightweight.
Content: Posts are JSON objects on IPFS, optionally referencing media CIDs. Client enforces a versioned schema with a SHA-256 contentHash.
Coordination: The GossyCore contract emits canonical events for post creation and reactions.
Access: A secure relayer accepts wallet-signed requests, batches them efficiently, and submits to chain.
Reading: A query server aggregates on-chain events and resolves IPFS content to serve fast feeds.

Architecture

flowchart LR subgraph Client["Client Apps (React Native, Web)"] A["Embedded Wallet (ethers v6)\nSession (AsyncStorage)"] B["IPFS Uploads\n(text + media)"] C["Feed & Comments Viewer"] end subgraph Relayer["Relayer API"] D["HMAC request auth\nWallet-signature validation"] E["High-performance queue\nJobs: create post, react, report"] end subgraph Chain["Arbitrum Nova (42170)"] F["GossyCore (posts, reactions)"] G["GSX Token (ERC-20)"] end subgraph Storage["IPFS"] H["CIDs: post.json + media files"] end subgraph Query["Query Server"] I["HMAC auth"] J["Feeds & search\n(trending = qualityScore)"] K["Caching & aggregation"] end A -->|signs tx| D B --> H D -->|submit tx| F F -->|events| Query H -->|CID resolution| Query Query -->|feeds + comments| C C -->|reactions| D C -->|report user| D

Components

Client
- Embedded wallet and session management.
- IPFSService for content/media uploads; MediaService for thumbnails.
- QueryApiService for feeds (HMAC-SHA256) with TTL caching.
- RelayerApiService for wallet-signed writes: create posts, reactions, reports.
Blockchain (Arbitrum Nova, chainId 42170)
- Contracts are provided via environment configuration.
- Post types: Gossip = 1, Comment = 2. Reaction types: Like = 1, Dislike = 2.
Storage (IPFS)
- Versioned JSON structure with technical.contentHash (sha256).
- Media uploaded as multipart; optional thumbnails/previews.
Query Server
- HMAC-SHA256 auth with API key/secret (hex/base64).
- Feeds: main, user, hashtag, location (geohash), trending (sorted by qualityScore).
- Server aggregation + caching; client TTL cache.

Data Model: IPFS Post 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": "...", "label": "optional" }],
    "language": "en",
    "visibility": "public"
  },
  "technical": {
    "client": "GOSSYApp",
    "clientVersion": "1.0.0",
    "platform": "ios | android | web | desktop",
    "contentHash": "sha256:<64 hex>",
    "encrypted": false
  }
}

End-to-End Flows

Posting
1. Compose content and optional media. Select targets: hashtag/user/location.
2. Upload media to IPFS → receive media CIDs.
3. Assemble JSON; compute SHA-256 contentHash; upload → receive post CID.
4. Call relayer /api/v1/posts/create with cid, type, parentPostId, targets (prefix: h: hashtag, u: user, l: location).
5. Relayer validates HMAC + wallet signature, enqueues on-chain job, submits to GossyCore.
6. Query server updates feeds; client resolves IPFS content for render.
Reactions
- Like (1) / Dislike (2). Client optimistically updates UI; relayer enqueues and submits the reaction.

Sequence (post creation):

sequenceDiagram participant U as User Wallet participant C as Client App participant R as Relayer API participant SC as GossyCore participant Q as Query Server participant IP as IPFS U->>C: Compose + sign deterministic message C->>IP: Upload media files IP-->>C: Media CIDs C->>IP: Upload post JSON IP-->>C: Post CID C->>R: /posts/create (cid, type, targets, parentId + HMAC + wallet sig) R->>SC: createPost(cid, user, type, parentId, targets) SC-->>R: PostCreated(postId,...) R-->>C: 202 Accepted (jobId) SC-->>Q: Events indexed Q-->>C: Feeds updated

Security & Privacy

Wallet signatures: All write operations include a wallet-signed deterministic message binding key fields (e.g., cid, post type). See relayer/src/middleware/wallet-auth.ts and the Wallet Signature Guide.
HMAC-SHA256: Query/Relayer requests require X-API-Key, X-Signature, X-Timestamp. See relayer/src/middleware/auth.ts and query/src/middleware/server-auth.ts.
Replay protection: Timestamp validation; strict signature windows.
Content integrity: Client computes/validates technical.contentHash on retrieval.
Data minimization: No emails/usernames; coarse geohash targets instead of raw coordinates.
Nonce and submission safety: Relayer uses a nonce manager and queuing to prevent duplicate or out-of-order transactions.

Performance & Scalability

Targets and mechanisms are designed to keep user-perceived latency low while controlling infra costs.

Targets
- Main feed: <30–70ms
- User profile: <50ms
- Trending: <40ms (qualityScore pre-computed)
- Storage: subgraph aims for <50MB for 100K users (event-driven indexing)
Mechanisms
- High-performance queue with Redis backend for write operations.
- Circuit breakers around external dependencies to prevent cascade failures.
- Clustered workers and adaptive load balancing. See Ultra Scalability Guide.
- Pre-aggregation and caching in the query server for fast feeds.
- Event-driven subgraph schema optimized for low cost. See subgraph/schema.graphql.

GSX Token & Incentives

GSX appears in the client UI (wallet, analytics, notifications) as the protocol currency.
Intended uses: creator rewards for viral content, boosting, tipping, governance.
Distribution: Proposed allocations (community, contributors, growth, public, partnerships, liquidity, insurance) pending DAO/legal finalization and deployment.
Implementation note: Client integrations must remain gated by finalized contracts and environment configuration.

Deployment & Configuration

Network: Arbitrum Nova (42170). RPC and contract addresses are environment-driven.
Endpoints: QUERY_API_URL, RELAYER_API_URL, IPFS_API_URL, IPFS_GATEWAY_URL.
Auth: X-API-Key, X-Signature, X-Timestamp, X-Wallet-Address, X-Wallet-Signature.
References: Query API (docs), Relayer API (docs), Graph (guide), IPFS (reference).

Roadmap

Phase 1 (Q1–Q3 2025): Core client (IPFS posting, reactions), relayer integration, HMAC/signature hardening, post structure v2.0.0 audits.
Phase 2 (Q4 2025): Token launch and incentives; community programs; DAO bootstrap.
Phase 3 (2026): Public beta, creator rewards, premium channels with encryption and on-chain access control.
Phase 4 (2027–2029): Global scale, SDKs/APIs, cross-chain options, full DAO transition.

Glossary

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

Legal

Users are responsible for complying with local laws. Anonymity enables free expression, not crime.

Notes on Alignment to Reference Client

The mobile client reads via the query server; “The Graph” and event indexing are backend implementation details.
“Zero-Query” claims map to server-side pre-aggregation and caching for sub-100ms feeds; actual SLAs depend on deployment and cache strategy.
Premium channels with encryption and subscription enforcement remain roadmap features.

Contact

Website: gossy.io