Introduction to ChainSocial

ChainSocial is an on-chain social protocol deployed on Base. It provides the building blocks for social applications where users own their identity, content, and relationships.

What is ChainSocial?

ChainSocial is a set of smart contracts that implement social primitives:

• Profiles — User identities with usernames, bios, avatars, and metadata
• Posts — Text and media content with replies, quotes, and reactions
• Social Graph — Follow relationships and blocking
• Messaging — Direct messages between users
• Delegation — Let other addresses act on your behalf (for gasless UX)
• Plugins — Extend the protocol with custom functionality

All of this data lives on-chain, making it:

1. Portable — Switch apps without losing your followers or content
2. Composable — Other apps can build on your data
3. Censorship-resistant — No single entity controls your account
4. Verifiable — Anyone can audit social actions on the blockchain

Why On-Chain Social?

Traditional social platforms have a fundamental problem: they own your data.

The Composability Advantage

When social data lives on-chain, interesting things become possible:

• Universal Social Login — Sign in once, carry your profile everywhere
• Cross-App Feeds — Aggregate content from multiple apps in one view
• On-Chain Reputation — Your follower count, engagement history, and social graph are verifiable credentials
• Permissionless Innovation — Anyone can build new social experiences without asking permission

Key Concepts

MUD Framework

ChainSocial is built on MUD , a framework for building on-chain applications. MUD provides:

• World Contract — A single entry point that routes calls to systems
• Systems — Stateless contracts containing business logic
• Tables — Structured on-chain storage for data

This architecture means ChainSocial can be extended without permission. You can add new systems that interact with existing tables.

Content-Addressed Storage

Post content can be stored in three ways:

1. Inline — Small text stored directly on-chain (up to 4KB)
2. IPFS — Content hash stored on-chain, actual content on IPFS
3. URL — Reference to external content

For images and media, ChainSocial stores IPFS CIDs on-chain while the actual files live in decentralized storage.

Delegation

Users can delegate specific permissions to other addresses. This enables:

• Gasless Transactions — A relayer can submit transactions on your behalf
• Session Keys — Temporary keys for smoother UX (no wallet popup for every action)
• Bot Accounts — Automated posting with limited permissions

Delegation is granular. You can grant permission to post but not to follow users, for example.

Namespaced Systems

All ChainSocial systems live under the chainsocial namespace. When you call a function, you’re calling:

IWorld(worldAddress).chainsocial__createPost(contentId, visibility)

This namespacing means other protocols can coexist in the same World contract without conflicts.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      World Contract                          │
│  (Single entry point, routes calls, enforces access)        │
├─────────────────────────────────────────────────────────────┤
│                         Systems                              │
│  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐      │
│  │ ProfileSystem │ │   PostCore    │ │ FollowSystem  │      │
│  └───────────────┘ └───────────────┘ └───────────────┘      │
│  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐      │
│  │PostInlineSys  │ │PostBatchSys   │ │ PostFeeSys    │      │
│  └───────────────┘ └───────────────┘ └───────────────┘      │
│  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐      │
│  │ContentSystem  │ │ReactionSystem │ │  BlockSystem  │      │
│  └───────────────┘ └───────────────┘ └───────────────┘      │
│  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐      │
│  │DirectMsgSys   │ │DelegationSys  │ │ PluginSystem  │      │
│  └───────────────┘ └───────────────┘ └───────────────┘      │
├─────────────────────────────────────────────────────────────┤
│                         Tables                               │
│  Profile, Post, Content, Follow, Reaction, Block,           │
│  DirectMessage, Delegation, Plugin, Notification...         │
└─────────────────────────────────────────────────────────────┘

Data Flow Example: Creating a Post

1. User calls client.post.createInlinePost("Hello world")
2. SDK encodes the call and sends it via walletClient
3. Transaction hits the World contract
4. World routes to PostInlineSystem.createInlinePost()
5. System calls ContentSystem to store the text
6. System creates a Post record in the Post table
7. System updates PostStats and author index tables
8. Event emitted, indexer picks it up
9. API serves the new post to other clients

Integration Options

You have three ways to build on ChainSocial:

1. TypeScript SDK (Recommended for Apps)

Best for: Client-side apps, bots, scripts

import { createChainSocialClient } from '@chainsocial/client'
 
const client = createChainSocialClient({
  worldAddress: '0x...',
  publicClient,  // viem public client
  walletClient   // viem wallet client
})
 
await client.post.createInlinePost('Hello!')

2. REST API

Best for: Server-side integrations, read-heavy apps

# Get a user's posts
curl https://api.chainsocial.cc/api/users/0x.../posts
 
# Get the global feed
curl https://api.chainsocial.cc/api/feed

3. Direct Contract Calls

Best for: Other smart contracts, advanced use cases

import { IWorld } from "@chainsocial/contracts/src/codegen/world/IWorld.sol";
 
IWorld(worldAddress).chainsocial__createPost(contentId, PostVisibility.PUBLIC);

Network Information

ChainSocial is deployed on:

Next Steps

• Quick Start — Get posting in 5 minutes
• SDK Guide — Learn the SDK in detail
• API Reference — REST endpoint documentation
• Smart Contracts — Understand the on-chain architecture