FIP: Support for Token References using CAIP-19 Asset Identifiers

[Quazia]

Type: Implementation

Author: Art (@Quazia)

Abstract

This proposal would enable Casts to reference blockchain tokens via CAIP-19 asset identifiers.

This FIP outlines two implementation strategies (extending the mentions structure vs. adding a new field), specifies the format/behavior for token identifiers, protocol-level details, and a rollout plan for developers.

Problem

Farcaster currently supports mentioning users but lacks a standardized way to mention crypto tokens (or any other resources) in casts. Users often discuss tokens by ticker symbol (e.g. $BTC, $ETH), but without protocol support, these are just plain text. Without protocol level differentiators there's no guarantee which asset is meant (tickers can be ambiguous), and clients cannot link to additional info (such as a block explorer). We need a way to reference tokens in casts, similar to mentions, uniquely. The solution should integrate with Farcaster’s existing mention mechanics, preserve backward compatibility, and leverage an established standard for cross-chain asset identification.

Specification

Token Identifier Format: Token mentions will be stored using CAIP-19 (Chain Agnostic Improvement Proposal 19) asset identifiers. CAIP-19 defines a human-readable, unique format for assets consisting of a blockchain ID and asset reference. This ensures global uniqueness and aligns with Farcaster’s existing approach to on-chain objects in FIP-1. This also maintains Farcasters philosophy of being chain agnostic and sets us up to provide ticker information for non-evm assets (Tezos, Solana, etc).

Client-Side Ticker Resolution: When a user types $ followed by characters, clients SHOULD trigger a token select drop-down. This UI can query a token registry or list (e.g. popular tokens, on-chain registries) to find matching tickers. The user then selects the intended token from the dropdown. The client inserts the $ticker text into the cast (for display) and attaches the corresponding CAIP-19 asset ID as metadata. If multiple tokens share the same ticker, the dropdown will list all options with contextual info (network, contract address, icon) to disambiguate collisions. If a CAIP-19 asset ID can’t be resolved the fully qualified CAIP-19 URI should be inserted. Ideally these are validated before submission to the protocol.

Protocol Data Structures: There are two alternative approaches to encode token references in the Cast data:

1. Extend mentions Structure: Generalize the existing mentions array to support different entity types (users, channels, tokens, frames, etc.) instead of only user FIDs. This could be achieved by introducing a new Mention message type with a type discriminator and value. For example:

   message Mention {
     oneof entity {
       uint64 fid = 1;        // user Farcaster ID
       string asset_uri = 2;   // token asset CAIP-19 string
       uint64 channel_uri = 3; // (if channels were supported)
       // ... (future types like frames, etc.)
     }
   }
   repeated Mention mentions = 2;  // in CastAddBody
   repeated uint32 mentions_positions = 5; // positions in text
   
   message CastAddBody {
     repeated string embeds_deprecated = 1; // URLs to be embedded in the cast
     repeated uint64 mentions_deprecated = 2; // Fids mentioned in the cast
     oneof parent {
       CastId parent_cast_id = 3; // Parent cast of the cast
       string parent_url = 7; // Parent URL
     };
     string text = 4; // Text of the cast
     repeated uint32 mentions_positions = 5; // Positions of the mentions in the text
     repeated Embed embeds = 6; // URLs or cast ids to be embedded in the cast
     CastType type = 8; // Type of cast
     repeated Mention mentions = 9;  // new Mentions
   }

   In this scheme, the mentions field becomes a heterogeneous list. A cast can have @user mentions and $token mentions intermingled in one array, with a single mentions_positions list indicating insertion points in the text (sorted by index). For example, a cast text "Hello @alice, check $DAI!" might be stored as

   text: "Hello , check !", mentions: [fid=1466, asset_id="eip155:1/erc20:..."], mentions_positions: [6, 14]
   

   (with the client inserting @alice and $DAI at render time). This mirrors how user mentions are handled today (the mention text itself is omitted from stored test and replaced at render). The CAIP-19 asset_uri string would be stored in the new Mention object. This unified approach means one mentions list for all mentionable entities.

2. Add Dedicated Token Field: Introduce a new field in CastAddBody exclusively for token references, separate from the existing mentions. For instance:

   message CastAddBody {
     repeated string embeds_deprecated = 1; // URLs to be embedded in the cast
     repeated uint64 fid_mentions = 2; // Fids mentioned in the cast
     oneof parent {
       CastId parent_cast_id = 3; // Parent cast of the cast
       string parent_url = 7; // Parent URL
     };
     string text = 4; // Text of the cast
     repeated uint32 fid_mentions_positions = 5; // Positions of the mentions in the text
     repeated Embed embeds = 6; // URLs or cast ids to be embedded in the cast
     CastType type = 8; // Type of cast
   	repeated string token_mentions = 8;        // CAIP-19 asset IDs for tokens
   	repeated uint32 token_mentions_positions = 9;     // positions of token mentions 
   }

In this approach, token mentions are new fields and the existing mentions are handled alongside the new token mentions.

Rationale

Adding token mentions in one form or another will allow disambiguated token click through at the client level, and if we go the option of expanding mentions this gives us a clear path to frame mentions and channel mentions (granted this is messier since channels are only loosely codified in the protocol to-date). Token mentions also open up new possibilities with respect to trending and mention analytics.

Special attention should be paid to client rendering for either path, as both propose changes to how messages will need to be rendered by clients.

Release

Before release, ideally all existing clients who source message data directly from the protocol will need to modify their approach to rendering or integrate with a provider [such as Neynar] who handles cast transformation from the protocol. Fortunately, this is strictly additive so adding the additional field handling before release won’t be an issue and while there will be rendering issues for clients that don't upgrade, this should not be a breaking change.

TBD in terms of when, in order to avoid issues with rendering we should coordinate with any parties handling message construction directly from the protocol. This proposal will require weaving the mentions into the messages in order to properly render from a CAIP-19 URI to a $ticker but clients who don't opt in should not experience hard breakage. Also Release needs for the client are different depending on the path we choose in terms of expanding existing mentions or adding a parallel mentions system.

[vrypan]

I share the concerns, and I agree with the problem definition.

However, I'm skeptical about changing the protocol so much, in order to correctly present a specific type of URI. I mean how about dates, or locations, or any other popular data type, are we going to introduce new embed types, for each one of them?

I would prefer if we just agreed that <a href= links (the markup is indicative) are allowed inside casts, which moves the burden to properly present a CAIP-19 URI and link it to the right resource (a block explorer, an internal page, or something else).

[Quazia]

I hear you - I think if we went that path it would be more of a standards proposal vs an implementation proposal. We can always expand mentions at a later date too. Do you think it is worth writing up a parallel proposal to handle this using standards in a way similar to how you're recommending?

[vrypan]

I love standards proposals :-)

You may want to wait for some feedback from the MM team, first? Or maybe making the proposal will make it easier for them to share feedback? Not sure.