Skip to content
Branch: master
Find file Copy path
Find file Copy path
2 contributors

Users who have contributed to this file

@oed @zachferland
140 lines (101 sloc) 4.66 KB
3ip: 2
title: Threads: A p2p communication protocol
status: Final
created: 2018-11-20

Threads: A p2p communication protocol


Threads is a feature that enables multiple users to post messages in a sequence. This allows users to communicate asynchronously in many forms. For example it could be used for comments, chats, status updates, etc. Threads uses the orbitdb feed to create a log of messages that is eventually consistent.

Access control

Threads are allowed to have both moderators and members. Moderators can add other moderators, delete any posts in the thread and add members in a members only thread. Members can post in a members only thread.

Thread creation

Threads are created inside of Spaces. A thread has a name which could be any string. For example the name could be the address of a contract if you want to create a thread for commenting on that contract. This essentially means that two different spaces could have their own threads with the same name. When a thread is created it gets the name 3box.thread.<space-name>.<thread-name> for the orbitdb logstore. The main reason to keep threads separated by spaces is so that a dapp that only have permissions to space A should not be able to post in threads created in space B.


All of the calls below assume that you have opened a space, for example:

const space = box.openSpace('aGoodSpace')

Join a thread: To join a thread simply call the joinThread method with the name of the thread to join.

const thread = await space.joinThread(<name>)

A thread can also be given the moderation options when joining. You can pass firstModerator, a 3ID of the first moderator, and a members boolean which indicates if it is a members thread or not.

const thread = await space.joinThread(<name>, { firstModerator: <firstModerator>, members: <members>})

Lastly a thread can be joined by its address.

const thread = await space.joinThreadByAddress(<threadAddress>)

Post to a thread: To post in a thread the post method is used. It can be called with any Object. This post is appended to the end of the thread. By posting in a thread they automatically subscribe to it if not already subscribed.


Subscribe to a thread: Saves the thread to the space with the key "thread-/threadaddress". Mostly this only needs to be called if you wish to subscribe to a thread that you have not posted to already.

await space.subscribeThread(<threadAddress>, {name: <name>, firstModerator: <firstModerator>, members: <members>})

Read a thread: This function returns an array of posts made in the thread. It's also possible to pass options to limit the number of posts or what posts are return.

const posts = thread.getPosts()

Delete a thread post: Attempts to delete a post with given id. Deletion completes if the user has the capabilities in the access controller to do so.

await deletePost(<postID>)

Add a moderator to a thread: Attempts to add a moderator to a thread. Returns id if sucessful, otherwise throws.

await addModerator(<3ID>)

Get moderator list: Returns list of moderators for a thread.

const mods = await listModerators()

Add a member to a thread: Attempts to add a member to a thread. Returns id if sucessful, otherwise throws. Throws if not member thread.

await addMember(<3ID>)

Get member list: Returns list of members for a thread. Throws if not member thread.

const members = await listMembers()

Watch for updates: When we receive an update to the thread from the network, the provided function will get called.

thread.onUpdate(() => {})

Add listener for when capabilities are updated (member or moderator added), the provided function will get called.

thread.onNewCapabilities(() => {})

Unsubscribe from a thread Removes the thread from the list of threads that the user is subscribed to.

await space.unsubscribeThread(<address>)

List threads the user is subscribed to Lists all threads that the user has interacted with. Returns a list of objects as { address, firstModerator, members, name}

const threadNames = space.subscribedThreads()

Threads REST API

Our REST API is also available for viewing threads when the user doesn't have a space opened.

const threadData = await Box.getThread(<space-name>, <thread-name>, <firstModerator>, <members>)
const threadData = await Box.getThreadByAddress(<thread-address>)
You can’t perform that action at this time.