We Built a Web3 Points Library on Ceramic

For those in our community who have been staying up-to-date on our thoughts and experimenting thus far as they relate to points, you already know why we see points as a logical vehicle for Web3 reputation systems. As our co-founder, Danny importantly points out in his blog post entitled Points: How Reputation & Tokens Collide, points not only align the incentives of the platform and its users, but Web3 enables point systems to be more open and composable by "...making every event driving points both transparent and verifiable..."

Given Ceramic's native composability, provenance, performance, and flexible-by-design characteristics, "points built on Ceramic" became an obvious idea for a design pattern that would appeal to teams looking to integrate reward systems into their projects. In March, we released a post called Building Points on Ceramic - an Example and Learnings meant to walk readers through a points proof-of-concept application we deployed for EthDenver '24. Later that month, we also released another post to announce Oamo as the first points provider on Ceramic.

This is all to say - as an organization, we've strived to be thoughtful and deliberate about how we approach the opportunity Web3 points presents while aiming to maintain quick iteration and experimentation as engineering and product norms.

As such, we've been working on a new experiment that we're excited to share with you - a points library built on Ceramic!

Why Develop a Points Library?

Given that we identified points as an ideal use case for Ceramic, building a points library presented an opportunity to help developers start experimenting with and iterating on Ceramic much faster. We also predicted that the approach would accelerate developers' learning rate by packaging Ceramic within an easy-to-understand paradigm. Finally, a use case-specific library allowed us to:

1. Predefine library interfaces and base models for users, helping them bypass this development stage
2. Eliminate the friction of compiling and deploying a composite
3. Enable immediate utility and experimentation by removing the need for node setup
4. Help developers focus on their core application logic by baking straightforward functionality into the library

...and so on.

Which Use Cases is it Built for?

Throughout this post, we'll take a high-level walk through the anatomy of the points module (and the broader SDK it lives in) which should reveal how flexible and extendable the library is. However, here are some scenarios we considered that helped inform its design and utility:

Rewarding Community Engagement

• A project wants to incentivize meaningful participation by rewarding points for engagement across key social platforms
• The project must track a history of point allocation events per participant, as well as have easy access to a participant's total

Incentivizing Collaboration

• A project wants to reward collaborators for contributing to a codebase
• Various types of contributions under this system are eligible for point rewards

Quests or Education

• An education platform wants to reward students for completing class modules
• Points are distributed in correlation to quiz or test scores at the end of each module

What is the Points Library?

The points library is the first module within our larger Ceramic Solutions SDK, designed to be the eventual home for any experimental tooling our team creates for certain common patterns or use cases we've identified as priorities. While the individual libraries (points, for example) sit at the core of this SDK, this repository will also contain example applications, API documentation, and other helpful modules to support developers looking to get started.

The Points Library module (which is now available as an NPM module - @ceramic-solutions/points) removes the common points of tension mentioned above by:

Delivering a hosted node endpoint

This is the default endpoint if no alternate is provided by the user (for test purposes only - not intended for production). This feature was designed to accelerate developer experimentation. Of course, the library also supports private endpoints as well.

Predefined Interfaces and Default Models

The points library relies on two schema interfaces (implemented by two default models) for keeping track of points. These interfaces can easily be extended by developers who desire more complex use cases, or developers can leverage the default models out of the box with no additional configuration.

interface PointsAllocationInterface implements PointsInterface
  @createModel(description: "Interface for a single allocation of points to an account") {
  issuer: DID! @documentAccount
  recipient: DID! @accountReference
  points: Int!
}

interface PointsAggregationInterface implements PointsInterface
  @createModel(description: "Interface for an aggregation of points to an account") {
  issuer: DID! @documentAccount
  recipient: DID! @accountReference
  points: Int!
  date: DateTime!
}

While the Points Library Readme offers more detail, these interfaces broadly speak to the two primary utilities we anticipate developers will need. Model instances of PointsAllocationInterface will keep track of the history of allocation events (and if extended, can include fields to capture additional details such as when and why points were allocated). Conversely, PointsAggregationInterface is designed to keep track of the sum of points for a recipient at any given time (and like allocation docs, can also be extended to keep track of more nuanced data points like contextual subtotals).

Built-in Reader and Writer Classes

The two core library modules consist of a points reader class and a separate writer class, allowing developers multiple ways to instantiate an instance (the easiest of which simply requires a private key if using the default node endpoint and default models). Each class includes built-in methods to read or issue points and can accommodate extensions of the interfaces without the necessity of additional wrapping.

What Will You Build with Points?

While we covered a few examples of typical use cases for points, there are so many other possibilities out there for developers to explore. Perhaps you want to reward your community for showing up to in-person events or collaborating on projects. Maybe you want to build a service that analyzes on-chain behavior (such as interacting with certain smart contracts or holding certain assets) and uses a framework of weights to award contextual points.

We'd love to learn how you're using reward systems across your communities and projects, and whether this initial library has what it needs to support your use case. Feel free to contact me directly at mzk@3box.io, or start a conversation on the Ceramic Forum. We look forward to hearing from you!