FIP: Labels

[varunsrin]

Title: Labels
Type: Standards FIP
Authors: @akshaan, @v

Abstract

Labels are a standard to share metadata about Farcaster users and casts between apps.

Problem

Apps need to determine context about casts and users to improve their user experience. Services can provide such context either as a public good or as a paid service. For example, neynar provides an account score that helps apps filter out irrelevant accounts. Many other types of useful context also exist, like the language of a cast and whether an account is human or automated.

If we make it easy to discover service providers and provide a standard format to label data, we might see more context being produced which is beneficial for application developers.

Specification

A Label is a JSON object which can can be used to add context to a user or a cast. Labels can be served as flat files or over a stream.

{
  /** Fid of user who created the label (e.g. 912381)*/
  provider: number
  
  /** Target that this label applies to */
  target: {
    type: 'cast',
    hash: Uint8Array
  } | {
    type: 'account',
    fid: number
  }
  
  /** Type of the label */
  type: string (64 characters) (^[a-z_]+$)
  
  /** Value of the label */
  value: string (64 characters)  (^[a-z_]+$)
  
  /** Timestamp when this label was created or last updated */
  timestamp: number
}

File Format

If labels are provided as files, they should be in JSONL format as shown below.

{
  provider: 9152,
  target_fid: 24,
  label_type: 'spam',
  label_value: '0',
  timestamp: 1736200761000
},
{
  provider: 9152,
  target_fid: 42,
  label_type: 'spam',
  label_value: '1',
  timestamp: 1736200761000
},
...

Labels should be sorted in reverse order of timestamp so that consumers can easily read only those records that changed since their last read.

Directory

A github repo at farcaster/labels provides a directory of different label providers that serve labels over an API or a file format.

Rationale

What about a compact, high performance format like Parquet?
Data sets are fairly small and will see little benefit from high performance formats. A single label over the entire set of users would be roughly 0.2 GB. The JSON format is simpler and easier to work with and has fewer dependencies. If the network grows 10x in size we may propose a new format.

Why not have a way to stream labels efficiently from sources?
Our priority is to test the idea of labels and see if developers will start using them. If we see significant adoption and growth we may consider higher performance standards to allow streaming of labels from providers.

Release

Labels are a standards FIP and may be adopted by anyone at any time. Once this FIP is finalized, the farcaster/labels repository will be created as a directory of label providers. Warpcast plans to publish some labels about user relevance and bot categorizations.

[srijancse]

neat. excited to see this go forward!

[Rosetta19q9]

Thank you 😊 good luck

[polymutex]

As I wrote on Farcaster here, I suggest future-proofing the provider field by making it an object with subtypes similar to how the target field works. This trivially accommodates raw FIDs, can be expanded to support signing and to support non-single-FID sources (labels from collectives of FIDs? channels? onchain data sources?).

{
  /** Creator of the label */
  provider: {
    type: 'fid',
    /** Fid of user who created the label (e.g. 912381)*/
    fid: number
  } | /* Other types can go here... */;
  
  /** Target that this label applies to */
  target: {
    type: 'cast',
    hash: Uint8Array
  } | {
    type: 'account',
    fid: number
  }
  // ...
}

[web3pm]

we would contribute to labels if the format supported more generic providers and targets. We already use and publish our labels as open source verifiable credentials.

[varunsrin]

can you share more details on your lablels?

[web3pm]

Sure- Icebreaker supports over 100 labels (a basic registry in this repo). These are all based on data that can be hosted outside of Icebreaker (like an ipfs or onchain EAS attestation, token holding, membership based ZKP, or a cast from Farcaster), and can apply to Farcaster users, EVM addresses, and offchain social handles or other identifiers.

Labels like skill: engineering, human, verified: google.com, hiring, worked directly with XXX, etc.

Highly customizable logic for who can give the labels, whether they are public vs private, etc.

A list of all users who have a given label is available rn in our UI and via API

We also have an API route to get all the labels a given user has chosen to display (by wallet, ens, fname, or fid).

Every one of these labels is available right now for channel gating via modbot and channelkit (demo)

As you can see, we're big fans of interoperability, so would be interested in aligning around a standard if it is broad enough to work for both farcaster and non farcaster entities. You've already begun designing for external social channel verifications. One argument for expanding the standard is how users will inevitably want to make and see labels for these other social channels, in addition to the verifications which are arguably labels themselves.

[varunsrin]

i think you should be able to use this label set with some caveats:

1. this is a public architecture and doesn't support private labels.

2. you can just use the current format, set provider to icebreaker's fid (you are proxying the label into our system), set the label type to the service (e.g. EAS: was at this event) and then the value to 1 for people to hold it. let me know if this doesn't work for some reason.

[web3pm]

Nice, yes that would work for proxying ours.

Is the idea that we could only address fids or would there be value in us addressing entities across all namespaces (eg, labeling my twitter handle of web3pm)?

Also, to clarify the point on private vs public, our label registry is also public. However some of the individual labels may be privately made (eg, a private attestation of a specific user's attendance that conforms to a publicly registered "attendance" schema).

[thecompez]

@varunsrin The 9152 value apparently refers to the warpcast user by fid.
Are the provider's targets clients? I need some clarification on this to get some useful ideas about query categorization.

+--------+----------+--------+-----+------------+-------------+------------+
| id     | provider | target | fid | label_type | label_value | timestamp  |
+--------+----------+--------+-----+------------+-------------+------------+
| 437477 |     9152 | user   |   3 | spam       |           2 | 1723835492 |
+--------+----------+--------+-----+------------+-------------+------------+

Thanks!

[varunsrin]

I'm not sure I understand the question, can you elaborate?

[thecompez]

I'm not sure I understand the question, can you elaborate?

I mean, who exactly is the provider? According to my research, the fid (9152) for it is for the @warpcast user. So, What exactly will the provider field be used for?

[varunsrin]

the provider is the person or entity producing the labels.

in this case, we are claiming that the labels are produced by warpcast.

[thecompez]

+---------+----------+--------+--------+------------+-------------+------------+
| id      | provider | target | fid    | label_type | label_value | timestamp  |
+---------+----------+--------+--------+------------+-------------+------------+
| 4504458 |     9152 | user   | 493739 | spam       |           2 | 1737899168 |
+---------+----------+--------+--------+------------+-------------+------------+

Can we expect username to be provided along with fid? :)

[fahlizza]

How to get this result

[thecompez]

How to get this result
This is my server side data, use this for get friendly result.
https://warpcast.com/~/frames/launch?domain=labels.genyframe.xyz