CIP-120: Multiple Pubsub Topics Source

Author Joel Thorstensson
Status Draft
Category Core
Created 2022-12-13

Simple Summary

Make the Ceramic protocol use multiple pubsub topics to gossip updates.


This CIP introduces the idea of separating into multiple pubsub topics based on a separator field in a streams genesis event, creating a unique pubsub topic for each value of this separator key. For streams that don’t specify this field, the current pubsub topic is used for backwards compatibitliy.


Currently Ceramic uses one pubsub topic to propagate update, query, and response messages in the network. As the network grows the scalability of this approach will be limited. Separating messages into multiple topics doesn’t neccessarily solve this problem entirely. However, it allows developers of less popular streams to not share the burden of message propagation for more scaled applications.


This CIP proposes a way to create a pubsub topic for any given stream given a separator key and a separator value. The separator key is defined by the sep field in the genesis event header and must be a string. The separator value is defined as the value of the field in the genesis header corresponding to the value of sep. The separator value is expected to be a byte string.

All pubsub messages for streams that include a value for the sep field in the genesis header MUST use the following topic:

  • network-name - the name of the Ceramic network used
  • separator-key - the value of the sep separator key field
  • separator-value - the value of the field specified by the sep field, encoded as base36


If a stream has the following genesis header,

  header: {
    sep: 'model',
    model: toBytes('k2t6wyfsu4pg1hnttc39koxlw0pdn1kemzrn33cdfhrbooozvo7wb14sa1uqwi', 'base36'))

it would use the following pubsub topic on main net:


Streams without sep

For backwards compatibility if a stream doesn’t have a sep field or no value for the field specified by sep, will use the following pubsub topic:


Which is the pubsub topic currently used by Ceramic.

Peer discovery

While gossipsub used by Ceramic enables ambient discovery of peers, an initial set of peers already in a topic is required to recieve messages. It is therefore recommended that peers announce to the libp2p DHT that they are subscribed to a given pubsub topic. Peers can thus also discover other peers by looking up the DHT records for the given topic. The key that should be used for DHT providing and lookup MUST be sha2-256(topic-name).


By separating tip gossip into multiple pubsub topics, each node only needs to hear about a smaller subset of messages. Each node will subscribe only to the topics that are relevant for the streams it currently cares about.

Backwards Compatibility

There are two approaches for how to transition to this new approach for pubsub topics.

Duplicate messages

For a transition period new nodes will publish updates in both the old main topic as well as the new topic. This ensures backwards compatibility in the system at the cost of some amount of time with, at worst, double the amount of messages.

Almost like a hard fork we can pick a particular blockheight (since we track the eth blockchain), or blocktimestamp. Once this time has passed all nodes would switch over to the new pubsub topics (with maybe a short phase out period). The main drawback of this approach is that the community would need to coordinate to upgrade their software in time. There would be no backwards compatibility for nodes that didn’t make the upgrade.


No implementation yet.

Security Considerations

The proposed use of the DHT for peer discovery opens Ceramic up for eclipse attacks. However, due to the use of libp2p gossipsub’s ambient peer discovery, the effects of this is minimal.

Copyright and related rights waived via CC0.


Please cite this document as:

Joel Thorstensson, "CIP-120: Multiple Pubsub Topics [DRAFT]," Ceramic Improvement Proposals, no. 120, December 2022. [Online serial]. Available: