FIP-1: Canonical URIs

[varunsrin]

Title: Canonical URIs
Type: Standards FIP
Author: Varun Srinivasan, Paul Fletcher-Hill

Abstract

Canonical URIs are a meta-standard for creating pointers to onchain and offchain objects that have canonical, unique identifiers (e.g. NFTs, Casts). They can be used in Farcaster messages to reference an object directly giving applications the flexibility when rendering them to users.

Problem

Open protocols like Ethereum create objects that have canonical identifiers but lack canonical URLs. An Ethereum transaction has a unique hash which can be used to look it up on a blockchain node. Such transactions do not have a canonical representation as a URL, and each blockexplorer has its own URL for rendering content. Using non-canonical URLs to reference such objects is sub-optimal. In the example above, if the block explorer shuts down all its URLs become invalid even though the transaction continues to exist.

Specification

A Canonical URI is a universal standard for representing canonical identifiers for objects on different protocols. A valid Canonical URI must have a protocol identifier and a protocol uri of the form id://uri and be less than 256 bytes in length. The id component identifies the object's protocol and the uri component is the unique identifier of the object.

Canonical URI Regex: ([a-zA-Z0-9]+:\/\/)(.+)$

HTTP Protocol

The HTTP protocol is used to point to valid resources on the web.

Example: https://www.farcaster.xyz/
Protocol Identifier Regex: ^https?:\/\/
Protocol URI Regex: ^(www\.)?[-a-zA-Z0-9@:%._\+~#=]+\.[a-zA-Z0-9()]{1,6}([-a-zA-Z0-9()@:%_\+.~#?&//=])*$

Chain Protocol

The chain protocol is used to point to onchain objects like assets or NFT collections. URIs must adhere to the the CAIP-19 asset URI specification.

Example (NFT): chain://eip155:1/erc721:0xa723a8a69d9b8cf0bc93b92f9cb41532c1a27f8f/11
Example (NFT collection): chain://eip155:1/erc721:0xa723a8a69d9b8cf0bc93b92f9cb41532c1a27f8f

Protocol Identifier Regex: ^chain:\/\/
Protocol URI Regex: ^eip155:(\d+)\/([a-zA-Z0-9]+):([a-zA-Z0-9]+)(\/([a-zA-Z0-9]+))?$

Client Expectations

When Canonical URIs are used in Farcaster messages, clients must parse the id of each Canonical URI to determine if they understand the protocol. Clients can choose to either to render the message and a representation of the URI, render the message and a symbol that represents an unknown URI, or to not render the message at all. Clients must not render the message without any indication of the URI, since that may change the meaning of the message.

Extensions

Anyone can propose an extension to FIP-1 by writing a new FIP that includes:

• a new protocol id
• a regular expression for parsing ids and uris
• a suggestion for how URIs should be rendered
• an argument for why this is valuable for applications and users.

FIP-1 extensions are moved into the review stage without taking up a number, and are merged into this document when finalized as a new revision. They do not get an FIP number of their own.

Rationale

Why not allow unstructured URIs for maximal flexibility?

A finite and mutually agreed upon set of URIs will result in maximal cross compatibility across different clients. Each client can deterministically know if it can render all valid content produced by other applications.

Release

Canonical URIs can be adopted lazily by clients and are already implicitly implemented by some clients. They will be presented at the April 27, 2023 developer call and finalized soon after.

[betashop]

A topic I’d like to bubble up: Proliferation of Embeds, and standardizing some processes and making them manageable for developers.

By my count as of writing this there are the following types of embeds already. It’s easy to imagine there being hundreds of different embeds in the near future. At Jam we spent many hours the past few days trying to reverse engineer embeds by other clients so that we can contemplate how to render them for users. As embeds proliferate this will create a lot of cycles by clients just trying to catch up to other clients adding new embeds, so that their UX’s don’t break. (e.g. today’s it NFT mints, tomorrow it’s ticketing, POAPs, DAO votes, etc.)

I think it behooves us as a community to create a place in FC docs for developers to help each other by posting details about their embeds in a standard format/doc that will help other clients as single reference point for all things embeds, with details on what is passed to hubs, recommendations on how handled on the client side, etc. (It may or may not be possible to fully coordinate this but, worth a try IMO).

Embeds currently that I’m aware of:

1. NFT embeds casted with WC prompted URI (e.g. from user sharing Warpcast notification). This is sent as an embed to Hubs. However embed does not contain link to OpenSea, that’s WC custom/proprietary UX.

2. NFT embeds casted with user entered URI (e.g. https://warpcast.com/blobs/0x3d79cb this was created by user entering
   chain://eip155:1/erc721:0x54f81a09021c21a5b968c2b46ccc57d974a26965/21 in their cast.). In this case WC seems to have treated it like an embed in unfurling it as an NFT, however the embed is not passed to Hubs so clients cannot handle it:

{
embedsDeprecated: [],
mentions: [],
parentCastId: {
fid: 557,
hash: <Buffer db 7c 0a 40 6b e1 d4 48 8e 27 83 06 92 1b e3 63 78 10 2a f4>
},
parentUrl: undefined,
text: "can't wait to try it!!\n" +
'chain://eip155:1/erc721:0x54f81a09021c21a5b968c2b46ccc57d974a26965/21',
mentionsPositions: [],
embeds: []
}

3. NFT embeds casted with NFT URL by user.

4. NFT Mint pages casted with URL by user (e.g. https://warpcast.com/dwr/0x027b79 )

5. Longcasts on Jam without photos. Longcast URL is passed in the embed with OG metadata. Soon will also be hosted on IPFS or Arweave so any client can display the full content of the longcast)

6. Longcasts on Jam with photos. Longcast URL is passed in the emebed along with the first photo uploaded by user.

7. Multiple photos. (coming soon to Jam, Warpcast)

8. Videos (Discove)