Skip to Content
Building AppsSDK GuideInstallation & Setup

SDK Installation & Setup

🚧

Coming Soon — The ChainSocial SDK (@chainsocial/client) is currently under development and not yet published to npm. The documentation below describes the planned API and functionality that will be available when the SDK is released. For now, interact with ChainSocial via the REST API or directly with the smart contracts.

The ChainSocial SDK (@chainsocial/client) will be a TypeScript library for interacting with ChainSocial smart contracts.

Installation (Coming Soon)

When released, installation will be:

# Coming soon - not yet published
pnpm add @chainsocial/client viem

The SDK will use viem  for Ethereum interactions and require you to provide viem clients.

Creating a Client (Planned API)

The following shows the planned SDK API:

import { createPublicClient, createWalletClient, http } from 'viem'
import { base } from 'viem/chains'
import { createChainSocialClient } from '@chainsocial/client'
 
// Public client for reading data
const publicClient = createPublicClient({
  chain: base,
  transport: http('https://mainnet.base.org')
})
 
// Wallet client for writing data
const walletClient = createWalletClient({
  account,  // Your account from wallet connection
  chain: base,
  transport: http('https://mainnet.base.org')
})
 
// Create the ChainSocial client
const client = createChainSocialClient({
  worldAddress: '0x7405fCbEc24C00278b7e821Ace222f5CFfa6c6eA',
  publicClient,
  walletClient  // Optional - only needed for write operations
})

Configuration

ParameterTypeRequiredDescription
worldAddressAddressYesThe ChainSocial World contract address
publicClientPublicClientYesviem public client for reads
walletClientWalletClientNoviem wallet client for writes

You can create a read-only client by omitting walletClient. This is useful for server-side code that only reads data.

Available Systems

The client exposes these systems:

SystemPurpose
client.profileUser profiles (create, update, read)
client.postPosts (create, edit, delete, replies, quotes)
client.contentContent storage (inline, IPFS, URL)
client.followSocial following
client.reactionPost reactions (likes, etc.)
client.directMessageDirect messages
client.blockUser blocking
client.notificationNotification management
client.moderationContent reporting and hiding
client.delegationPermission delegation
client.usernameUsername registration
client.pluginInstallPlugin management

Using with React

With wagmi

import { usePublicClient, useWalletClient } from 'wagmi'
import { createChainSocialClient } from '@chainsocial/client'
import { useMemo } from 'react'
 
const WORLD_ADDRESS = '0x7405fCbEc24C00278b7e821Ace222f5CFfa6c6eA'
 
export function useChainSocialClient() {
  const publicClient = usePublicClient()
  const { data: walletClient } = useWalletClient()
 
  return useMemo(() => {
    if (!publicClient) return null
 
    return createChainSocialClient({
      worldAddress: WORLD_ADDRESS,
      publicClient,
      walletClient: walletClient ?? undefined
    })
  }, [publicClient, walletClient])
}

Context Provider Pattern

For larger apps, you might want a context:

import { createContext, useContext, useMemo, ReactNode } from 'react'
import { usePublicClient, useWalletClient } from 'wagmi'
import { createChainSocialClient, ChainSocialClient } from '@chainsocial/client'
 
const ChainSocialContext = createContext<ChainSocialClient | null>(null)
 
export function ChainSocialProvider({ children }: { children: ReactNode }) {
  const publicClient = usePublicClient()
  const { data: walletClient } = useWalletClient()
 
  const client = useMemo(() => {
    if (!publicClient) return null
    return createChainSocialClient({
      worldAddress: '0x7405fCbEc24C00278b7e821Ace222f5CFfa6c6eA',
      publicClient,
      walletClient: walletClient ?? undefined
    })
  }, [publicClient, walletClient])
 
  return (
    <ChainSocialContext.Provider value={client}>
      {children}
    </ChainSocialContext.Provider>
  )
}
 
export function useChainSocial() {
  const client = useContext(ChainSocialContext)
  if (!client) throw new Error('ChainSocial client not available')
  return client
}

Switching Accounts

If you need to switch wallet accounts:

// Create a new client with a different wallet
const newClient = client.withWallet(newWalletClient)

Error Handling

All SDK methods can throw. Common error types:

try {
  await client.post.createInlinePost('Hello!')
} catch (error) {
  if (error.message.includes('ProfileNotFound')) {
    // User needs to create a profile first
  } else if (error.message.includes('InsufficientBalance')) {
    // User doesn't have enough ETH for gas
  } else {
    // Other error
    console.error('Failed to post:', error)
  }
}

Type Exports

The SDK exports types you’ll need:

import {
  createChainSocialClient,
  ChainSocialClient,
  PostVisibility,
  ReactionType,
  ContentStorageType,
  DelegationPermission,
  type Bytes32,
} from '@chainsocial/client'

Next Steps

  • Profiles — Create and manage user profiles
  • Posts — Create posts, replies, quotes
  • Social Graph — Follow, unfollow, block users
  • Messaging — Send direct messages
  • Advanced — Delegation, meta-transactions
OverviewProfiles