FIP: farcaster: URI scheme

[vrypan]

Title: farcaster: URI scheme
Type: Standards FIP
Author: Panagiotis Vryonis
Status: Early Draft

Abstract

Defines a URI scheme for farcaster-related resources that can be used to point to these resources in a standard, client-agnostic manner.

Problem

The farcaster protocol is implemented by many clients, but we lack a standard, client-agnostic way of pointing to farcaster resources, such as casts or users. The only way to do this right now, by using client-dependant URIs.

For example, pointing to a cast is usually implemented by using the warpcast link, such as https://warpcast.com/user/castId. This approach introduces a number of problems:

1. Centralisation: These URIs are under the control of the specific client/service, and the way they are presented can be altered, manipulated, or censored.
2. Lifespan: The lifespan of URIs depends on the lifespan of specific client. If the client/service goes away, these URIs break.
3. The current status favourites the most popular client and leaves no space for alternatives. For example, if all farcaster-related URIs depend on warpcast, users are forced to use warpcast and all other clients are in a disadvantage.

By defining a standard farcaster:// URI scheme, we create a standard, client-independent way of pointing to farcaster resources. Any client that implements the specification and registers with the underlying operating system, will be able to handle these URIs.

Specification

The farcaster URI specification is a universal standard for representing canonical identifiers for objects on the farcaster protocol.

A valid farcaster URI has the form farcaster://uri or farcaster-wallet://uri (TBD: max length?).

• farcaster:// is used for resources living on hubs and actions that require interactions with hubs
• farcaster-wallet:// is used for resources that live on the blockchain and require interactions with smart contracts.

The uri component is the unique identifier of the object and has the following structure which is largely influenced by the Farcaster hub rpc specification.

Syntax

Overview

- <user>
- <user>/(pfp|display|bio|url|username|casts|<link_type>)?
- <user>/(pfp|display|bio|url|username)=<value>
- <user>/<link_type>
- <user>/(+|-)<link_type>
- <user>/0x<hash>
- <user>/0x<hash>/<reaction_type>s?
- <user>/0x<hash>/(+|-)<reaction_type>
- <user>/0x<hash>/replies
- <user>/0x<hash>/+reply=<text>
- <user>/0x<hash>/delete
- +cast=<text>
- url/<base64(<url>)/
- url/<base64(<url>)/(+|-)like
- url/<base64(<url>)/replies
- url/<base64(<url>)/+reply=<text>
- url/<base64(<url>)/+mention=<text>
- -signer/0x<hash>
- +signer/0x<hash>

farcaster://

Users

URIs whose target is a user (fid). user is either an fid (integer value) or @<username>.

- <user>
- <user>/(pfp|bio|url|username|casts|<link_type>)?
- <user>/(pfp|bio|url|username)=<value>
- <user>/<link_type>
- <user>/(+|-)<link_type>

Examples:

• farcaster://280: User profile by fid
• farcaster://@vrypan: User profile by username proof.
• farcaster://@vrypan/pfp: the value of the pfp user data for a user.
• farcaster://@vrypan/pfp=https%3A%2F%2Fvrypan.net%2Fassets%2Fimg%2Fvrypan.jpg: set the value of the pfp user data to a specific value.
• farcaster://280/follow: Show the accounts that fid=280 follows.
• farcaster://280/+follow: Follow the account fid=280.
• farcaster://280/+follow: Unfollow the account fid=280.

Casts

Format:

- <user>/0x<hash>
- <user>/0x<hash>/<reaction_type>s?
- <user>/0x<hash>/(+|-)<reaction_type>
- <user>/0x<hash>/replies
- <user>/0x<hash>/+reply=<text>
- <user>/0x<hash>/delete
- +cast=<text>

Examples:

• farcaster://@dwr.eth/0xe22ae240d690ffe800ef11344d65c32ac9d3fcd6: link to a specific cast
• farcaster://@dwr.eth/0xe22ae240d690ffe800ef11344d65c32ac9d3fcd6/likes: link to a specific casts's likes
• farcaster://@dwr.eth/0xe22ae240d690ffe800ef11344d65c32ac9d3fcd6/+like: like a specific cast.
• farcaster://@dwr.eth/0xe22ae240d690ffe800ef11344d65c32ac9d3fcd6/-like: unlike a specific cast.
• farcaster://@dwr.eth/0xe22ae240d690ffe800ef11344d65c32ac9d3fcd6/replies: Casts with this cast as a parent.
• farcaster://@dwr.eth/0xe22ae240d690ffe800ef11344d65c32ac9d3fcd6/+reply=I%20agree: reply to a cast.
• farcaster://+cast=Hello%20World!: Create a new cast.

FIP-2

URIs related to FIP-2.

Note: It is assumed that url is a reserved fname.

Format:

- url/<base64(<url>)/
- url/<base64(<url>)/(+|-)like
- url/<base64(<url>)/replies
- url/<base64(<url>)/+reply=<text>
- url/<base64(<url>)/+mention=<text>

Examples:

Note: base64-padding is not required by the URI scheme. Clients should add padding if needed.

• farcaster://url/aHR0cDovL3dhcnBjYXN0LmNvbQo: Show farcaster content related to http://warpcast.com (casts, likes)
• farcaster://url/aHR0cDovL3dhcnBjYXN0LmNvbQo/+like: Like a URL
• farcaster://url/aHR0cDovL3dhcnBjYXN0LmNvbQo/-like: Unlike a URL
• farcaster://url/aHR0cDovL3dhcnBjYXN0LmNvbQo/+reply=I%20%love%this%app: Create a cast with parent_url=URL.
• farcaster://url/aHR0cDovL3dhcnBjYXN0LmNvbQo/+mention=I%20%love%this%app: Create a cast with embeded_url=URL.

farcaster-wallet://

Signer-related URIs

Format:

- -signer/0x<hash>
- +signer/0x<hash>

Examples:

• farcaster://+signer/0x532c81a2ea1d21bd17a4ba62adedc708ec0693b292398e6a8c8aec655f70bcea: Approve signer.
• farcaster://-signer/0x532c81a2ea1d21bd17a4ba62adedc708ec0693b292398e6a8c8aec655f70bcea: Remove signer.

Sign-in with Farcaster (TBA)

This section will be defined according to FIP: Sign in with Farcaster requirements.

• signin

Client Behavior

Clients can register as protocol handlers for the farcaster:// protocol with the underlying OS.

Client Recommendations

Handling URI exceptions

If a client is requested to open a farcaster:// URI that is not able to handle, it is recommended inform the user by presenting a message that states at least the following:

• is not able to handle this farcaster:// URI.
• the URL (not clickable)

Link sharing

When a client presents users the option to share a link to a specific resource, a farcaster:// URI should be used, instead of a client-specific URL or deep link.

If this is not feasible (for example, URI scheme is not adopted widely enough), clients are advised to use URLs that consist of app-specific prefix + farcaster URI. For example: https://example-farcaster-app.com/@dwr.eth/0xe22ae240d690ffe800ef11344d65c32ac9d3fcd6.

Following this convention will make it feasible to automatically migrate to farcaster: URIs in the future, and will also make it easier for apps to identify and parse these URLs.

Linking to farcaster

Sites and applications pointing to Farcaster resources such as user profiles or casts, are expected to to use farcaster:// URIs instead of client-specific URLs.

Release

TBD: Potential conflicts of clients already using some form of farcaster: URIs to be examined.

[vrypan]

One possible issue I see with this spec is that Farcaster URIs may not be FIP-1: Canonical URIs. A FIP-1 Canonical URI has a max length of 256 bytes. So a farcaster://1/message/cast_add?parent_url=... that uses it as a parent URI will be longer. Increasing the max length for canonical URIs will not solve this.

[0xSalman]

I think this is a good FIP. I have a couple of questions:

1. Is the version in the URI scheme necessary? What would this achieve? The other protocols, for example ipfs & arweave, do not have versions in the uri scheme

2. Who will be responsible for resolving/linking the URI to the resource? Does it require every client to implement the mapping layer?

3. Add/remove are write operations; so, what's the reasoning behind having a uri scheme for these operations?

[vrypan]

1. I think so, but I'm open to removing it.

2. I would expect clients to implement the URI scheme, just like browsers implement the http:// URI scheme. So, when you click a farcaster:// URI, I would expect that the browser opens a farcaster client and passes the URI. Most clients implement deep links which are not much different, anyway. Which client? Well, this depends on the OS and the app you are using.

3. The reason is to prepare an operation that will be casted by the farcaster client. Much like "tweet this" links that have a pre-filled text, or email: URIs that define the recipient and the subject. Cast/Reaction/Link are the equivalent of Tweet/Like/Follow actions on X (more or less).

[0xSalman]

1. yea, removing it would be better because I don't think it's necessary and will make the uri longer
2. 👍🏽
3. ok, that makes sense

[horsefacts]

For reference, here are all the farcaster:// protocol URIs in use by Warpcast today:

/wallet-connected
/login-mobile
/login-wallet
/login-desktop
/login-web
/profiles/:fid
/nfts/:address/:id
/discover
/collections/:name
/collections/:name/users
/casts/:fname/:hash
/notifications/all
/signed-key-request?token
/start-recovery?token&email
/recovery?email
/view-direct-casts

[vrypan]

Are some of them app-specific and definitely out of scope for the protocol? For example, I guess /recovery?email is not something that will be part of the protocol URI, right?

[vrypan]

Maybe a rule of thumb is "do I want this URI to open in any client, or only Warpcast"?

[horsefacts]

Yes, I think almost all of these are more application specific than protocol specific. On first glance, /casts and /profiles are the only two that seem like they might belong at the protocol level.

[vrypan]

I agree. Something like /casts that point to a number of casts (GetCastsByParent(), GetCastsByFid(), GetCastsByMention()) will probably have to be added.

/profiles is covered by /user/, right?

[vrypan]

I updated the spec to include /casts/by_... URIs.

[vrypan]

Should we add some guidelines for clients?

For example, I was thinking that if a client can not handle a specific URI, it is recommended to inform the user.
ex: testcaster in not able to handle /casts/by_parent_url.

These can only be recommendations, but it helps devs is we provide them with some guidelines.

[vrypan]

I update the spec to provide some guidance for clients.

[vrypan]

There is a big problem with transition/adoption:

If everyone uses this FIP the way they should, all public links to Farcaster resources will be using farcaster:// URIs. However, this makes Farcaster inaccessible to anyone without a Farcaster client, which will hurt attracting new users. If my public link to an interesting discussion on Farcaster is farcaster://cast/..., only existing Farcaster users will be able to see it.

How do we deal with this?

(A not-extremely-bad solution is to use farcaster.xyz/uri/ as a temporary http-to-farcaster "translator" but I'm not very excited about it.)

[vrypan]

I refactored user-related URIs, to add a way to point to a user using their username (how could this be missing).
I think the farcaster://@user format will be one of the most used ones, and even if @ is a reserved character in HTTP URLs, it will resonate with most users.

[vrypan]

Important question/decision: Do we want to go with farcaster:// or pick a shorter protocol identifier like fc:// or fcp://?

[montycheese]

farcaster:// seems more appropriate. Most protocols that use abbreviations directly map to individual words.

[vrypan]

While this FIP feels close to complete from a design point of view, we may have to consider if it can be changed to take advantage or increase compatibility with ERC-4804: Web3 URL to EVM Call Message Translation.

[vrypan]

I rewrote almost everything. It makes much more sense now, and it looks better.

[vrypan]

@horsefacts @varunsrin I think we should break the scheme into two separate schemes:

• one for onhub (🤣 ) interactions
• and one for onchain interactions.

The reason is that there may be apps that implement one or the other or both. For example, we have many clients that support onhub interactions, but only warpcast and flink support onchain interactions. In the future, we may have apps that support only onchain (for example, rainbow or metamask supporting Farcaster wallet actions). Apps should be able to pick the schemes (like farcaster:// and farcaster-wallet://) they can handle.

[varunsrin]

whats an example of an onhub interaction?

[vrypan]

casting and reacting

[alexanderkhitev]

Hello everyone! 👋

I'm currently working on integrating deep linking into our iOS app. I've tried using the URL scheme farcaster://+cast=Hello%20World! to open the Farcaster app and prepopulate a cast with the text from our app.

While the URL does launch the Farcaster app successfully, it doesn't seem to navigate directly to the cast writing screen as expected. Could someone provide guidance on how to achieve this? Your help is much appreciated!

Thanks.

[vrypan]

Hi Alexander. This FIP is just an early draft. There is no guarantee it will be adopted as it is (probably not), or even adopted at all.

However, since you would use a URI scheme if it was available, it would be valuable to share the use cases that are of interest to you.

[alexanderkhitev]

Hello @vrypan ! Got it, and thank you for the quick response. Currently, we are working on a use case that enables users to share specific events from our application on Farcaster, much like how users currently share events on Twitter through our app.

As an illustration, for Twitter, we utilize a deep link/universal scheme to compose a new post/tweet: twitter://post?message=.

And it would be awesome if we'll have something like this on Farcaster

[varunsrin]

@alexanderkhitev try https://docs.farcaster.xyz/reference/warpcast/cast-composer-intents

[alexanderkhitev]

Hey @varunsrin ! Thank you!

[vrypan]

@varunsrin @horsefacts
This FIP had a fundamental problem: The idea that apps (such as browsers) would support a farcaster URI scheme (which is unrealistic at the moment).

However, Frames introduced a lot of actions/intents that take place inside Farcaster clients, and this is an environment where a Farcaster URI scheme can be supported. Frames want to let users follow users, like casts, install Actions, etc.

Should we resurrect the FIP from the dead, and review it in this context?