FIP: Notifications as protocol primitives

[vrypan]

Title: Notifications as protocol primitives
Type: Standards FIP
Authors: @vrypan

Abstract

A proposal to make Notifications a protocol primitive.

Problem

Right now, notifications are a client-specific feature. Clients may decide to notify users when an onchain event happened (someone minted a NFT), when there was a reaction (reply, recast) to one of their casts, when their storage is running low, or a new DAO proposal is open for voting.

However, there is no standard way for an app other than the client the user makes use of to send notifications.

Also, client-specific notifications are not portable between clients. For example, if Warpcast implements storage limits/expiration notifications, users of alternative clients will not receive them.

Specification

Notifications can be considered as "light" casts (no embeds) intended to appear in a single user's notification feed. A notification is valid ONLY if the recipient (m.data.body.to) follows the sender (m.data.fid).

A new NotificationsStore CRDT to track NotificationAdd/NotificationRemove messages must be implemented.

NotificationAddBody messages contain the fid of the recipient, an action (CastID or URL and a label) that can be presented as a call to action button, a text and an optional displayBefore timestamp that can be used by clients (but has no impact on CRDT) to hide a time-sensitive notification after a point in time.

A NotificationAddBody in a message m is valid only if it passes these validations:

1. m.signature_scheme must be SIGNATURE_SCHEME_ED25519.
2. m.data.type must be MESSAGE_TYPE_NOTIFICATION_ADD.
3. m.data.body.type must be NotificationAddBody.
4. m.data.body.to must be a known fid.
5. m.data.body.to must follow m.data.fid
6. m.data.body.text must contain <= 160 bytes and be a valid UTF8 string.
7. m.data.displayBefore must be a valid Farcaster epoch timestamp.

message NotificationAddBody {
  uint64 to = 1;                          // fid of user to receive the notification
  repeated uint64 mentions = 2;           // User fids mentioned in the text
  string text = 3;                        // Text of the cast
  optional string image = 4;              // Optional image URL
  optional NotificationAction action = 5; // Call to action.
  optional uint32 displayBefore = 6;      // Don't show this Notification after displayBefore
  repeated uint32 mentions_positions = 7; // Byte positions of the mentions in the text
}

message NotificationRemoveBody {
  bytes target_hash = 1;                    // Message.hash value of the notification being removed
}

message NotificationAction {
  oneof target {                         // Required target of the notification
    CastId cast_id = 1;
    string url = 2;                      // Action URL <= 256 bytes
  };
  string label = 3;                      // How to present the call to action. <=32 bytes
}

Hub changes

Hubs must implement NotificationStore which tracks Notifications for each fid. The Hubs also expose the following APIs for this new functionality:

rpc GetNotification(NotificationId) returns (Message);   
rpc GetNotificationsByFid(FidRequest) returns (MessagesResponse);  // Returns notifications for an fid.

message NotificationId {
  uint64 fid = 1;                           // Fid of the cast's author
  bytes hash = 2;                           // Message.hash value of the notification
}

Storage limits

One storage unit increases CRDT limits by 1000 Notifications.

Rationale

Notifications will allow applications to implement custom flows that require notifying a user, without polluting the timeline.

Spam is prevented by requiring that the recipient already follows the sender at the time the notification was posted to hubs. Abuse is also prevented and penalized because users can unfollow the account that abuses the system, and block them from sending notifications in the future.

While Notifications are a premium way of communicating with users, this is why 1 storage unit = 1000 Notifications. An application that wants to send 100,000 notifications per day, will either have to pay 100 storage units, or 99% of its notifications will be pruned by hubs before they are read by their recipients.

There is nothing preventing clients to continue populating notifications streams with custom notifications as they wish.

Example flows that could take advantage of Notifications:

1. DAOs can notify their members of DAO-related activities: new proposals, new members. The custom Warpcast flow for Purple ()"X joined Purple. Welcome with a cast") could be implemented by any DAO, permissionlessly just by deploying a simple bot.
2. Newsletters can notify subscribers when a new issue is out. (Paragraph offers an XMTP notification, which will probably become useless as XMTP is flooded by spam.)
3. Event-related apps may notify their fans/subscribers that an event is about to start, such as a ticket sale, or a live stream.
4. ENS could notify users of domain expirations.
5. Zora could implement custom notifications for new drops, creator fees available to claim, mints of a specific collection, etc.
6. OpenSea could notify a user of offers or sales.

Examples of current Warpcast notifications that could be implemented by other apps using this FIP:

Limitations

The design does not have a way to update a notification. Notification updates may be a desirable feature (for example, a notification about the number of mints of a specific NFT will have to be updated over time). The current design assumes that applications will use a NotificationRemoveBody to remove the outdated notification and post a new NotificationAddBody.

[varunsrin]

Thanks for writing out this proposal, it's very thorough!

I'm a little hesitant to finalize this until there's another client that wants to work through the implementation. It's sometimes hard to predict the right design until there is a practical use case to validate it against.

For example, most in-app notifications are time based -- that is, i know the last time a user looked at their notifications and simply compute the number of "new things", and as soon as they open notifications they get reset to zero. Perhaps all that is necessary is a single message per user that stores the 'last viewed' timestamp and each client can compute their notifications accordingly.

I propose leaving this in draft and collecting more feedback as we go.

[vrypan]

I agree that this FIP should stay in draft. A lot has changed since I submitted it and it is outdated in some ways.

Anyone designing the Direct Casts, should have a look at it, because if DCs are opened up (even as a Warpcast API), they will be used as notifications. Actually, DC notifications are much better before they provide privacy. So, it might be easy to integrate some ideas from this proposal into DCs, or at least design them in a way that could be extended to offer better support for app notifications in the future. (For example some version of a TTL.)

[vrypan]

I want to come back to this one, because frames have changed the landscape.

Dan's argument that any successful app has a mobile client, and they get notifications for free, does not hold in the Frames context.

Frames are mini-apps that live inside farcaster. They can do amazing things, but they have no way of notifying a user. I can think of numerous use cases where a notification mechanism would make a Frame 100x more valuable and useful (in addition to the use cases mentioned in the FIP):

• Notify me when the event starts
• Notify me when the mint goes live
• Overcome the like/follow etc delay in a smooth, user-friendly way

I expected that this would be partially solved using DCs, but you guys mentioned that due to the technical surface area, we should not expect DCs to become part of the protocol before 2025.

The details may have to be revised, but I think this FIP provides a solution in a much simpler way.

Reconsider? :-)

[vrypan]

One more thing: I believe that notifications will be a major revenue boost for storage units, because they will be paid by apps that expect to get value from them.

Example: Paragraph is using frames to enable on-click subscriptions from the timeline, if they could also notify the subscriber of new posts this holds a lot of value.

There are so many use cases, eshops for example: Frame promotes the product, user goes to the eshop, no login required (FID captured from the frame, username, avatar, etc are already there), pays, then gets notified when the item is shipped. It can't get much less frictionless than this.

DEX alerts: Notify me when price drops bellow X.