Integrate a Ceramic DataModel to Superfluid

By the end of the post, you should be equipped with the knowledge of what Ceramic is, what the Superfluid Console is and how to integrate Ceramic into your favourite applications. The following breaks down a pull request of integrating Ceramic into an application.

I had originally heard about Ceramic from a podcast. The concept of having a data model standard within Web3 made a lot of sense. This concept took a while for me to grasp technical concepts of how to make that magic actually happen but I documented it here so it is easier for you. When I saw a Gitcoin bounty to integrate this tech with Superfluid I knew it was the best opportunity of learning firsthand if there was substance to my intuition.

https://github.com/superfluid-finance/superfluid-console/pull/93/commits/b1ac01fb3c866ddc7442059d0f566fdfe92482c8

The website describes it as: “Ceramic is a decentralized data network that brings unlimited data composability to Web3 applications.” but what does that mean exactly, and why should you care?

Ceramic acts as a platform to store your user’s data and create standardized data models that, once adopted and reused by the industry, will allow the next layer of composability within Web3 and Defi. It uniquely allows the user to own their data using their DID(persistent decentralized identifier) that can be generated in many ways, but in this case, using the user’s crypto wallet.

It works by creating streams for data models that are then available for users using their DID. You can think of it as a data table, your DID is the row, and each stream created is a column. An example might look like the one below:

Imagine a world where value can be distributed in real-time at any interval and determined individually for the use case. Powerful, easy and one of the simplest product market fit for blockchain and crypto. Well, Superfluid is just that, a streaming service building block that can be used modularly with other products. But what good is this without a way to visualize that data in real-time across each of the networks superfluid is deployed to? In comes superfluid console - A way for users to do just that. It would be nice if this was using a common framework for the data so it could be even more composable in the ever-growing Defi ecosystem, wouldn’t it?

What we wanted to do in this PR is marry the two technologies while incubating the design of an Address Book Data Model to track a user’s connected wallets and their streams. Creating this would allow it to be packaged and stored decentrally on Ceramic while accessible to other applications that could leverage the existing model.

There are two parts to getting this completed.

1. Creating the Data Model and deploying it to the Ceramic registry. We covered this in a previous blog post.

2. Using the already available DID on ceramic to connect with Superfluid. Then creating the ability to add, edit and retrieve Address Book data to be used within the Super Fluid console.

Unfortunately this PR was completed before the concept of pull-requests-with-zoz was conceived and it was done with one large commit(Im now starting to expose just how little I knew🤦🏼). For purposes of this article we will breakdown this large commit into steps like it should have been done.

Let’s first break down what needed to done. I had no previous exposure to either Ceramic or Superfluid so I had to get a grasp of how these applications work. Ceramic was a large learning curve and my first post breaks it down for a dummy like me. Secondly, I really didn’t know how Address Books worked in the console and it took me a long time to even find where to add an entry(not a great user experience, but its Web3 so we will give it a pass - for now). With that said and maaannnny more hours than I should have spent. I determined I needed 4 pieces added:

• Add the necessary packages, and references to the data models and wrap the app in a provider.

• A button to connect to ceramic and recognize the user’s identity

• A neat way to package the interactions a keep them separately contained - maybe a React hook

• Replace the existing interactions with the applications state and use the newly created methods in the above step to instead use the new Data Model and interact with Ceramic.

Don’t worry the next steps will help describe and allow you to visualize this better if it doesn’t make sense.

1. Determining where the changes need to be made

This is always the biggest hurdle when trying to grasp a new concept and multiple products with different codebases. There is no shortcut. You must read the code, break things, and insert a billion console logs(well at least I do). I usually create a separate branch just to do this and use it as a messy draft of what I will actually submit as my final PR.

2. Add the necessary packages, and references to the data models and wrap the app in a provider

I suggest reading the first Ceramic post as this explanation will be briefer(with the assumption you have a little more knowledge than I did when I started). We will need two packages:

- @glazed/types: This will be used to give a defined structure and connect Data Models with aliases - @self.id/framework: This is a powerful wrapper that encaptures all the functionality of the Ceramic protocol into a neat package.

We want to wrap the application in the Provider(src/pages/_app.tsx - L66) and add our references to our Data Models(src/utils/ceramicModel.json to use later on. Where did we get these references from? We created and published them to the Ceramic network. We also could have got them from the Data Model Registry if they had been published previously.

3. A button to connect to ceramic and recognize the user’s identity

We will go ahead and create a new React component of a Button(src/components/CeramicConnect.tsx) that will allow us to log in and get our identity. *Note: the button will be using our React hook we create in the next step

The button performs a couple of functions: Connect, Disconnect with the @selfId framework(L11 - L28) and also gets our DID. It is using our Ethereum address from our injected wallet to recognize us.

4. Package the interactions in a React hook

Let’s first understand what a React hook is. A hook is a collection of functions that isolate the stateful logic to use within other components. That is any variables that need to be changed and managed. In this instance we would like to manage the Ceramic state. This article is helpful to give a more in depth explanation of hooks.

Here we create the useAddressBook hook and it is found in the src/hooks/useAddressBook.ts file. This hook is to manage the addressBook state within the Superfluid Console application so we want to bring in some other dependancies here like:

• useViewerConnection from the @self.id/framework.We want to use this as it will get our current connection to Ceramic

• Standard useAppDispatch and useAppSelector react hooks. Also the useCallback hook. These will help us interact with our application state and the app

• useViewerRecord from the @self.Id/react library. This will help us pull data from Ceramic by giving it an alias

Now we just want to create reusable functions within the hook that will help us achieve our task of creating, updating and deleting the data within ceramic. The functions between lines 29-87. The two functions below that are just a way to massage and transform the data in and out.

5. Replace the existing interactions with the applications state and use the newly created methods

Wow… Not really that much to it when its broken down and explained is there? On to our final boss… Connecting it in to the existing application and wiring it all up. This happens in the src/components/AddressBook.tsx file. This file was already doing much of the functions we need but it was using the state in react and on the client. So essentially we just refactor these existing functions. We need to bring in the following items:

• useViewerConnection and useViewerRecord from @self.id/framework

• And of course our new useAddressBook hook

When we bring in addAddressBookEntry and removeAddressBookEntry from useAddressBook we can now replace actions with these.

We also want to let the user know they need to connect to Ceramic to use this new functionality if they have not already. This is done by checking if we are connected and showing a warning if not. This happens between lines 111-120.

There we go!!! YOU now have the knowledge to integrate Ceramic with your favourite applications

This post first serves as an example to what not to do in a PR by showing a poor monolithic approach of using one large commit. But also providing a solution to how it could be done better. These are the commits I would do now if I was to integrate another application

Ceramic is a powerful tool that will only get better as more integrations use the network. How I view it is like an interoperable data service that is blockchain agnostic. A new model for any application, not even blockchain to leverage. The intention of this post is empower even a novice like myself to integrate and use Ceramic. It also breaks down just how easy it is!

https://paragraph.xyz/@0xZOZ/pull-requests-with-zoz

The image above(like my PP) is created with abraham.ai - an AI artwork generator

SEED: zoz.eth integrating a Ceramic Data Model into the Superfluid console

Twitter: @0xzoz

GitHub: @0xzoz

Mirror: @0xzoz

Discord: @zoz.eth#6952

ENS: zoz.eth