Quick Reference

info

Here is a collection of the most commonly used methods within Subsocial SDK. For more in-depth look into this library, please reference the TypeDocs.

Setup

Install

yarn add @subsocial/api

Add type definitions and utils library:

yarn add @subsocial/types @subsocial/definitions @subsocial/utils

Import

import { newFlatSubsocialApi } from '@subsocial/api'

Configuration

TestNet

const config = {

substrateNodeUrl: 'wss://rpc.subsocial.network',

offchainUrl: 'https://app.subsocial.network/offchain',

ipfsNodeUrl: 'https://app.subsocial.network/ipfs'

}

MainNet

const config = {

substrateNodeUrl: 'wss://testnet.subsocial.network',

offchainUrl: 'https://staging.subsocial.network/offchain',

ipfsNodeUrl: 'https://staging.subsocial.network/ipfs'

}

LocalNet

const config = {

substrateNodeUrl: 'http://127.0.0.1:9944',

offchainUrl: 'http://127.0.0.1:3001',

ipfsNodeUrl: 'http://127.0.0.1:8080'

}

caution

Make sure to run local Subsocial & IPFS node before using these configs in your project.

const flatApi = await newFlatSubsocialApi(config)

Reading Data

Space

Space is the place where all content on SubSocial lives. It holds multiple posts from different people depending upon the permission. Read More

By Id

const spaceId = 1

const space = await flatApi.findSpace({id: spaceId})

By Owner

const ownerAccountId = '<owner_account_public_key>'

// Fetching ids of all the spaces by owner.

const spaceIds = await flatApi.subsocial.substrate.spaceIdsByOwner(ownerAccountId)

// Fetching space data from all ids.

const spaces = await flatApi.subsocial.findSpaces({ids: spaceIds})

By Handle

const handleName = 'subsocial'

// Fetching spaceId by Handle.

const spaceId = await flatApi.subsocial.substrate.getSpaceIdByHandle(handleName)

// Fetching space by spaceId.

const space = await flatApi.findSpace({id: spaceId})

Check full docs here.

Post

Post is the piece of content that provides value for the readers. It can be some written text, an image, or a video. Read More

By Id

const postId = 1

const post = await flatApi.findPost(postId)

By Space Id

const spaceId = 1

const postIds = await flatApi.subsocial.substrate.postIdsBySpaceId(spaceId)

const posts = await flatApi.subsocial.findPosts({ids: postIds})

Check full docs here.

Profile

Profile is linked to your Subsocial account address, and is an overview of your activity on Subsocial. You can set a profile picture and a username for your account, as well as a personal website link. Read More

Single Account

const accountId = '<account_public_key>'

const profile = await flatApi.findProfile(accountId)

Multiple Accounts

const accountIds = ['<account_public_key_1>', '<account_public_key_2>']

const profiles = await flatApi.findProfiles(accountIds)

Check full docs here.

Writing Data

Space

Add following import statement:

import {

IpfsContent,

OptionBool,

SpaceUpdate

} from "@subsocial/types/substrate/classes"

Storing space details in IPFS, and generating a CID.

const ipfsImageCid = await api.subsocial.ipfs.saveFile(file)

const cid = await ipfs.saveContent({

about: 'Subsocial is an open protocol for decentralized social networks and marketplaces. It`s built with Substrate and IPFS',

image: ipfsImageCid,

name: 'Subsocial',

tags: [ 'subsocial' ]

})

Creating a Space transaction object

Create Space

const substrateApi = await api.subsocial.substrate.api

const spaceTransaction = substrateApi.tx.spaces.createSpace(

null, // Parent Id (optional)

null, // Handle name (optional)

IpfsContent(cid),

null // Permissions config (optional)

)

Update Space

const substrateApi = await api.subsocial.substrate.api

const update = new SpaceUpdate({

content: IpfsContent(cid),

hidden: OptionBool(true),

})

const spaceTransaction = substrateApi.tx.spaces.updateSpace('1', update)

Signing a transaction and sending to blockchains

const keyring = (new Keyring({ type: "sr25519" }))

const senderKeyPair = keyring.addFromMnemonic('<your_mnemonic_here>')

spaceTransaction.signAndSend(senderKeyPair, async (result) => {

const { status } = result

if(!result || !status){

return;

}

if (status.isFinalized || status.isInBlock) {

const blockHash = status.isFinalized

? status.asFinalized

: status.asInBlock;

console.log('✅ Tx finalized. Block hash', blockHash.toString());

} else if (result.isError) {

console.log(JSON.stringify(result));

} else {

console.log('⏱ Current tx status:', status.type);

}

})

Check full docs here.

Post

Add following import statement:

import {

IpfsContent,

OptionBool,

SpaceUpdate

} from "@subsocial/types/substrate/classes"

Storing post details in IPFS, and generating a CID.

const ipfsImageCid = await api.subsocial.ipfs.saveFile(file)

const cid = await ipfs.saveContent({

title: "What is Subsocial?",

image: ipfsImageCid,

tags: [ 'Hello world', 'FAQ' ],

body: 'Subsocial is an open protocol for decentralized social networks and marketplaces. It`s built with Substrate and IPFS.'

})

Creating a post transaction object

Regular Post

const spaceId = '1' // The space in which you're posting.

const substrateApi = await api.subsocial.substrate.api

const postTransaction = substrateApi.tx.posts.createPost(

spaceId,

{ RegularPost: null }, // Creates a regular post.

IpfsContent(cid)

)

Shared Post

const spaceId = '1' // The space in which you're posting.

const parentPostId = '2' // The original post you want to share.

// Creating new sharedPostCid having shared message.

const sharedPostCid = await ipfs.saveContent({

body: 'Keep up the good work!'

})

const substrateApi = await api.subsocial.substrate.api

const postTransaction = substrateApi.tx.posts.createPost(

spaceId,

{ SharedPost: parentPostId }, // Creates a shared post.

IpfsContent(sharedPostCid)

)

Update Post

const postId = '7' // Id of post which you want to update.

const substrateApi = await api.subsocial.substrate.api

const update = new PostUpdate({

content: IpfsContent(cid),

hidden: OptionBool(true),

})

const postTransaction = substrateApi.tx.spaces.posts.updatePost(postId, update)

Signing a transaction and sending to blockchain

const keyring = (new Keyring({ type: "sr25519" }))

const senderKeyPair = keyring.addFromMnemonic('<your_mnemonic_here>')

postTransaction.signAndSend(senderKeyPair, async (result) => {

const { status } = result

if(!result || !status){

return;

}

if (status.isFinalized || status.isInBlock) {

const blockHash = status.isFinalized

? status.asFinalized

: status.asInBlock;

console.log('✅ Tx finalized. Block hash', blockHash.toString());

} else if (result.isError) {

console.log(JSON.stringify(result));

} else {

console.log('⏱ Current tx status:', status.type);

}

})

Check full docs here.

Profile

Add the following import statement:

import { IpfsContent } from "@subsocial/types/substrate/classes"

Storing profile details in IPFS, and generating a CID to add on blockchain:

const ipfsImageCid = await api.subsocial.ipfs.saveFile(file)

const cid = await ipfs.saveContent({

about: 'Subsocial official account.',

avatar: ipfsImageCid,

name: 'Subsocial',

})

Creating profile transaction object:

Create Profile

const substrateApi = await api.subsocial.substrate.api

const profileTransaction = substrateApi.tx.profiles.createProfile(

IpfsContent(cid)

)

Update Profile

const update = { content: IpfsContent(cid) }

const profileTransaction = substrateApi.tx.profiles.updateProfile(update)

Signing a transaction and sending to blockchain

const keyring = (new Keyring({ type: "sr25519" }))

const senderKeyPair = keyring.addFromMnemonic('<your_mnemonic_here>')

profileTransaction.signAndSend(senderKeyPair, async (result) => {

const { status } = result

if(!result || !status){

return;

}

if (status.isFinalized || status.isInBlock) {

const blockHash = status.isFinalized

? status.asFinalized

: status.asInBlock;

console.log('✅ Tx finalized. Block hash', blockHash.toString());

} else if (result.isError) {

console.log(JSON.stringify(result));

} else {

console.log('⏱ Current tx status:', status.type);

}

})

Check full docs here.

Comments

Comments are replies to a post that are visible below a post.

Reading Comments

import { idToBn } from "@subsocial/utils"

const substrate = flatApi.subsocial.substrate

const postId = '1'

// Get reply ids (comments) by parent post id and fetch posts by ids

const replyIds = await substrate.getReplyIdsByPostId(idToBn(postId))

// For getting comments use posts functions

const replies = await flatApi.findPublicPosts(replyIds)

Writing Comments

Create Profile

import { IpfsContent } from "@subsocial/types/substrate/classes"

const spaceId = '1' // Optional.

const rootPostId = '1'

const cid = await ipfs.saveContent({

body: 'Keep up the good work!'

})

const substrateApi = flatApi.subsocial.substrate

const tx = await substrateApi.tx.posts.createPost(spaceId, { Comment: { parentId: null, rootPostId}}, IpfsContent(cid))

Update Profile

import { IpfsContent } from "@subsocial/types/substrate/classes"

const spaceId = '1' // Optional.

const parentId = '2' // Parent comment id.

const rootPostId = '1'

const cid = await ipfs.saveContent({

body: 'Agree' // Reply message.

})

const substrateApi = flatApi.subsocial.substrate

const tx = substrateApi.tx.posts.createPost(spaceId, { Comment: { parentId, rootPostId}}, IpfsContent(cid))

Check full docs here.

Follows

Check if follower

This checks if an account is following a particular space.

Is Space Follower

const accountId = '<any_public_key>'

const spaceId = '1'

const substrateApi = flatApi.subsocial.substrate

const isFollower = await substrateApi.isSpaceFollower(accountId, spaceId)

Is Account Follower

const yourAccountId = '<any_public_key>'

const otherAccountId = '<any_public_key>'

const substrateApi = flatApi.subsocial.substrate

const isFollower = await substrateApi.isAccountFollower(yourAccountId, otherAccountId)

Fetch list of followers

For Spaces

By Space Id

import { bnsToIds } from '@subsocial/utils'

const spaceId = '1'

const substrateApi = flatApi.subsocial.substrate

const res = await (await substrateApi.api).query.spaceFollows.spaceFollowers(spaceId)

const followersSpaceIds = bnsToIds(res)

Followed by Account Id

import { bnsToIds } from '@subsocial/utils'

const accountId = '<any_public_key>'

const substrateApi = flatApi.subsocial.substrate

const res = await (await substrateApi.api).query.spaceFollows.spacesFollowedByAccount(accountId)

const followedSpaceIds = bnsToIds(res)

For Accounts

Followers

import { bnsToIds } from '@subsocial/utils'

const accountId = '<any_public_key>'

const substrateApi = flatApi.subsocial.substrate

const res = await (await substrateApi.api).query.profileFollows.accountFollowers(accountId)

const followersOfAccount = bnsToIds(res)

Following

import { bnsToIds } from '@subsocial/utils'

const accountId = '<any_public_key>'

const substrateApi = flatApi.subsocial.substrate

const res = await (await substrateApi.api).query.profileFollows.accountsFollowedByAccount(accountId)

const followingOfAccount = bnsToIds(res)

Check full docs here.

Follow / Unfollow

For Spaces

Follow

const spaceId = '1'

const substrateApi = flatApi.subsocial.substrate

const tx = substrateApi.tx.spaceFollows.followSpace(spaceId)

Unfollow

const spaceId = '1'

const substrateApi = flatApi.subsocial.substrate

const tx = substrateApi.tx.spaceFollows.unfollowSpace(spaceId)

Signing a transaction and sending to blockchain

const keyring = (new Keyring({ type: "sr25519" }))

const senderKeyPair = keyring.addFromMnemonic('<your_mnemonic_here>')

tx.signAndSend(senderKeyPair, async (result) => {

const { status } = result

if(!result || !status){

return;

}

if (status.isFinalized || status.isInBlock) {

const blockHash = status.isFinalized

? status.asFinalized

: status.asInBlock;

console.log('✅ Tx finalized. Block hash', blockHash.toString());

} else if (result.isError) {

console.log(JSON.stringify(result));

} else {

console.log('⏱ Current tx status:', status.type);

}

})

For Accounts

Follow

const accountIdToFollow = '<any_public_key>'

const substrateApi = flatApi.subsocial.substrate

const tx = substrateApi.tx.profileFollows.followAccount(accountIdToFollow)

Unfollow

const accountIdToFollow = '<any_public_key>'

const substrateApi = flatApi.subsocial.substrate

const tx = substrateApi.tx.profileFollows.followAccount(accountIdToFollow)

Signing a transaction and sending to blockchain

const keyring = (new Keyring({ type: "sr25519" }))

const senderKeyPair = keyring.addFromMnemonic('<your_mnemonic_here>')

tx.signAndSend(senderKeyPair, async (result) => {

const { status } = result

if(!result || !status){

return;

}

if (status.isFinalized || status.isInBlock) {

const blockHash = status.isFinalized

? status.asFinalized

: status.asInBlock;

console.log('✅ Tx finalized. Block hash', blockHash.toString());

} else if (result.isError) {

console.log(JSON.stringify(result));

} else {

console.log('⏱ Current tx status:', status.type);

}

})

Check full docs here.

Reactions

Reactions are your signs to Upvote or Downvote a post.

Get all reactions

Single Reaction

const myAccount = '<any_account_public_key>';

const reaction = await flatApi.substrate.getPostReactionIdByAccount (myAccount, '1')

Multiple Reactions

import { ReactionId } from '@subsocial/types/substrate/interfaces';

const myAccount = '<any_account_public_key>';

const substrate = await flatApi.subsocial.substrate

const substrateApi = await flatApi.subsocial.substrate.api

const tuples = [ '1', '2', '3' ].map(postId => [ myAccount, postId ])

const reactionIds = await substrateApi.query.reactions.postReactionIdByAccount.multi(tuples)

const reactions = await substrate.findReactions(reactionIds as ReactionId[])

Reacting to a post

Create

const postId = '1' // Post Id you want to react on.

const substrateApi = flatApi.subsocial.substrate

const reactionTx = substrateApi.tx.reactions.createPostReaction(postId, 'Upvote')

Update

const postId = '1' // Post Id you want to update reaction on.

const reactionId = '2' // Reaction Id to update.

const substrateApi = flatApi.subsocial.substrate

const reactionTx = substrateApi.tx.reactions.updatePostReaction(postId, reactionId, 'Downvote')

Delete

const postId = '1' // Post Id on which reaction you want to delete reaction.

const reactionId = '2' // Reaction Id to delete.

const substrateApi = flatApi.subsocial.substrate

const reactionTx = substrateApi.tx.reactions.deletePostReaction(postId, reactionId)

Signing a transaction and sending to blockchain

const keyring = (new Keyring({ type: "sr25519" }))

const senderKeyPair = keyring.addFromMnemonic('<your_mnemonic_here>')

tx.signAndSend(senderKeyPair, async (result) => {

const { status } = result

if(!result || !status){

return;

}

if (status.isFinalized || status.isInBlock) {

const blockHash = status.isFinalized

? status.asFinalized

: status.asInBlock;

console.log('✅ Tx finalized. Block hash', blockHash.toString());

} else if (result.isError) {

console.log(JSON.stringify(result));

} else {

console.log('⏱ Current tx status:', status.type);

}

})

Check full docs here.