A library for writing and reading comments from the Swarm network utilizing the concept of graffiti feeds.
To install the library, use npm or pnpm:
pnpm i @solarpunkltd/comment-systemTo write a comment to the Swarm network, use the writeComment or writeCommentToIndex functions:
import { writeComment, writeCommentToIndex, MessageType } from "@solarpunkltd/comment-system";
const comment = {
id: "unique-comment-id",
type: MessageType.TEXT,
message: "This is a comment",
username: "user123",
address: "user-address",
timestamp: Date.now(),
index: "0",
topic: "your-feed-topic",
targetMessageId: "parent-message-id",
};
const options = {
stamp: "your-stamp-id",
signer: "your-private-key",
beeApiUrl: "https://your-bee-node-url",
address: "your-feed-address",
};
writeComment(comment, options)
.then(result => {
console.log("Comment written:", result);
})
.catch(error => {
console.error("Error writing comment:", error);
});
const index = FeedIndex.fromBigInt(123n);
writeCommentToIndex(comment, index, options)
.then(result => {
console.log(`Comment written to index ${index}:`, result);
})
.catch(error => {
console.error(`Error writing comment to index ${index}`, error);
});Function writeComment writes a comment to the next feed index and returns an UploadResult object. It needs to look up the latest feed index before writing. Function writeCommentToIndex writes a comment to the desired specific index and returns an UploadResult object.
To read comments from the Swarm network, use the readComments, readCommentsInRange or readSingleComment functions:
import { readComments, readCommentsInRange, readSingleComment } from "@solarpunkltd/comment-system";
const options = {
identifier: "your-identifier",
beeApiUrl: "https://your-bee-node-url",
address: "your-feed-address",
};
readComments(options)
.then(comments => {
console.log("Comments read:", comments);
})
.catch(error => {
console.error("Error reading comments:", error);
});
const start = FeedIndex.fromBigInt(0n);
const end = FeedIndex.fromBigInt(10n);
readCommentsInRange(start, end, options)
.then(comments => {
console.log(`Comments read from range ${start} to ${end}:`, comments);
})
.catch(error => {
console.error(`Error reading comments from range ${start} to ${end}:`, error);
});
const index = FeedIndex.fromBigInt(3n);
readSingleComment(index, options)
.then(comments => {
console.log(`Comment read at index ${index}:`, comments);
})
.catch(error => {
console.error(`Error reading comment at index ${index}:`, error);
});Function readComments reads comments from index 0 until the latest found index, in succession. It also supports legacy comment formats and automatically transforms them to the current MessageData format. Function readCommentsInRange reads comments from the desired index range, in parallel, with improved error handling that distinguishes between critical errors and missing comments (404 Not Found). Function readSingleComment reads one single comment at the given index, if not provided it looks up and reads the latest comment. It returns the comment data directly as MessageData.
There are multiple ways of handling reactions for the comments/messages, providing below 2 examples. Every Comment.id identifies a feed topic for its reactions. Or maintaing a separate feed, derived from the original feed topic. While the first method keeps the reaction state separately for each comment as a new feed (smaller sates but many requests - bandwidth issues ), the latter stores the whole reaction state (big state that can be split up but only one poll reqeust needed). Each topic can be determined the following way:
import { getReactionFeedId } from "@solarpunkltd/comment-system";
const reactionFeedId = getReactionFeedId("comment-feed-identifier");
const reactionFeedIdForComment = getReactionFeedIdForComment(comment.id);Each feed update stores the latest state of the reactions, so each feed entry is a reactions array containing the entire comment reaction state. This way only one fetch request is needed for getting the latest reactions. On the other hand, each new reaction requires a state change.
In order to update the state of the reactions feed with a new reaction, the following utility function is provided:
import { updateReactions, MessageType } from "@solarpunkltd/comment-system";
const commentId = comment.id;
const newReaction = {
id: "reaction-id",
type: MessageType.REACTION,
message: "like",
username: "user123",
address: "user-address",
timestamp: Date.now(),
index: "0",
topic: "reaction-topic",
targetMessageId: commentId,
};
const updatedState = updateReactions(reactionState, newReaction);The state is updated (aggregated) according to the reaction logic. If a reaction from the same user and type already exists, it will be removed (toggle behavior). If it doesn't exist, it will be added. The function returns undefined in case the state needs no update.
Writing and reading reactions works in a similar way to the comments. The writeReactionsToIndex function now returns an UploadResult object, and readReactionsWithIndex always returns a MessagesWithIndex object (never undefined). Once the new reaction state and feedId is determined, it can be simply written as the latest feed update:
import { writeReactionsToIndex, readReactionsWithIndex, getReactionFeedId } from "@solarpunkltd/comment-system";
const reactionFeedId = getReactionFeedId(commentId);
const reactionState = await readReactionsWithIndex(undefined, {
identifier: reactionFeedId,
address: "your-signer-address",
});
await writeReactionsToIndex(updatedState, reactionState?.nextIndex, {
stamp: "your-stamp-id",
identifier: reactionFeedId,
signer: "your-private-key",
address: "your-signer-address",
});The main interface for comments and reactions, complying with the interface at swarm-chat-js
interface MessageData {
id: string;
type: MessageType; // TEXT, THREAD, or REACTION
message: string;
username: string;
address: string;
timestamp: number;
index: string;
topic: string; // For the feed indentifier
targetMessageId?: string; // For replies and reactions
signature?: string; // For user verification
flagged?: boolean; // For UI filtering
reason?: string;
isLegacy?: boolean; // Indicates if this was transformed from legacy format
}Enum defining the type of message:
enum MessageType {
TEXT = "text",
THREAD = "thread",
REACTION = "reaction",
}Configuration options for reading and writing:
interface Options {
stamp?: string;
identifier?: string;
beeApiUrl?: string;
signer?: PrivateKey;
address?: string;
}writeComment(comment: MessageData, options?: Options): Promise<UploadResult | undefined>writeCommentToIndex(comment: MessageData, index?: FeedIndex, options?: Options): Promise<UploadResult | undefined>readComments(options?: Options): Promise<MessageData[] | undefined>readCommentsInRange(start?: FeedIndex, end?: FeedIndex, options?: Options): Promise<MessageData[] | undefined>readCommentsAsTree(start?: FeedIndex, end?: FeedIndex, options?: Options): Promise<CommentNode[] | undefined>readSingleComment(index?: FeedIndex, options?: Options): Promise<MessageData | undefined>
writeReactionsToIndex(reactions: MessageData[], index?: FeedIndex, options?: Options): Promise<UploadResult | undefined>readReactionsWithIndex(index?: FeedIndex, options?: Options): Promise<MessagesWithIndex>getReactionFeedId(identifier?: string): TopicupdateReactions(reactions: MessageData[], newReaction: MessageData): MessageData[] | undefined
getPrivateKeyFromIdentifier(identifier: string): PrivateKey- Generates a private key from a given identifier string
import { getPrivateKeyFromIdentifier } from "@solarpunkltd/comment-system";
const identifier = "my-unique-identifier";
const privateKey = getPrivateKeyFromIdentifier(identifier);Writing to a feed index that is already taken does not result in an error, therefore reading back the comment at the expected index is necessary as a verification of success.
See: comment-system-ui as a basic example.
swarm-chat-react-example as a complete chat-like/ comment-feed app.