FIP: Primary Address Verification

[horsefacts]

FIP: Primary Address Verification

Title: Primary Address Verification
Type: Implementation FIP
Authors: @horsefacts, @sanjay, @pirosb3, @v

Abstract

Extend User Data to designate a primary Ethereum and Solana address for a Farcaser user.

Problem

Users have multiple wallets associated with their Farcaster accounts but often use one as their primary address. There is no way to indicate this, and this makes it difficult for developers or other users to send them things onchain.

Specification

Users should be able to specify a primary address for the Ethereum and Solana ecosystems by setting a UserData property.

The UserDataType is extended to support new types for Ethereum and Solana. A user can set these values to an address that they have previously verified or unset it to indicate that they do not have a primary address.

enum UserDataType {
  USER_DATA_PRIMARY_ADDRESS_ETHEREUM = 7; 
  // Primary Ethereum Address
  // "0xd5596099ec95b32ddC3F22814785a253f6a09D56" 

  USER_DATA_PRIMARY_ADDRESS_SOLANA = 8; 
  // Primary Solana Address
 // "4TciSRW38RGNiTSKmQamQvxUg4epWKBirBvG8LCh3ahZ" 
}

Validation Rules

The validation rules for both user data types are validated with existing rules and the following added ones:

1. value should be either an empty string or valid base58 encoded Solana address or valid checksummed Ethereum address
2. value if not an empty string must match a known Verification's address

The post-processing rules for Verifications are changed to include:

1. If there exists a USER_DATA_PRIMARY_ADDRESS_ETHEREUM or USER_DATA_PRIMARY_ADDRESS_SOLANA that matches this address, set its value to ""

Rationale

Why not make this something that scales to N chains instead of just Solana an Ethereum?
The majority of users are on EVM or Solana chains today and we don't foresee adding any more ecosystems soon. If this becomes more common we can revisit creating a new data type.

Why not update Verifications to include an is_primary field?
If verification messages are received out of order, it could result in a user ending up in incorrect state. It is much easier to manage this state correctly as a separate property due to the limitations of CRDTs.

Release

The change is fully backwards compatible as it adds new optional types. We will make this available in the next hub release and on Snapchain.

[androidsixteen]

LGTM - only feedback is that it may be nice to have a fallback primary designated when VerificationRemoveBody is used. The end goal should be to have a primary at all times because it makes for a much better ux. So if the user ever removes a verified address that was the primary, falling back gracefully to another address would be nice.

That said, this could be done by just having the client prompt the user and send a VerificationAddAddressBody afterwards. But it reduces message overhead if it's coupled with the remove message.

Either way, documenting the expected behavior for clients on edge cases like removing a primary address will take care of this 👍

[vrypan]

Do you mean this? #141 (comment)

[deodad]

similar! my suggestion is simpler and more space efficient :)

[vrypan]

Not sure I understand. If I have two verifications, both with is_primary=true, how are they ordered?

[deodad]

all messages in a CRDT are ordered by timestamp and then hash
https://github.com/farcasterxyz/protocol/blob/main/docs/SPECIFICATION.md#timestamp-hash-ordering

[vrypan]

Oh, yes :-) It will work.

[vrypan]

If we are going to do this, would it be good to replace bool is_primary with a uint8 priority? Ordering verifications may be useful in the future, for example if a service has to decide which address to use based on some rules (balance, nft or something else).

For now, we could treat int8 as bool (with a convention like 1,0 or 255,0), but it will be future proof if we want to extend its use in the future.

[vrypan]

@horsefacts , maybe this FIP should get some more love. It's been a year.

[i001962]

If we are going to do this, would it be good to replace bool is_primary with a uint8 priority? Ordering verifications may be useful in the future, for example if a service has to decide which address to use based on some rules (balance, nft or something else).

For now, we could treat int8 as bool (with a convention like 1,0 or 255,0), but it will be future proof if we want to extend its use in the future.

OR
by signing app

[sidrisov]

One small suggestion once this change goes live - include the primary flag in SIWF returned verifications meta)

[yijuchung]

This sounds like is_primary is on user level. So it's technically possible to have same one address marked as primary for multiple users. Might become a problem if we ever want to link fname to just one primary address.

To change primary address, users must remove their primary address verification before designating another. Clients can hide this complexity from users by sending a remove followed by an add with the user's new primary address.

Could we introduce a new message to set this flag instead?

[cboscolo]

It is also currently possible to associate multiple Solana addresses with your FID.
Should there also be a way to make a Solana addresses primary for SVM network in addition to a primary EOA?

[manan19]

Users may have one primary verification per protocol.

This FIP supports adding different primary addresses for Solana & Ethereum

[PirosB3]

Update: this FIP has been refreshed this week and takes into consideration the changes that have happened over a year ago, including the move to Snapchain.

[manan19]

Primary address UserData entries should be automatically revoked if the corresponding verification is deleted.

@PirosB3 will snapchain logic generate a new message for revoking or removing userdata when the corresponding verification is deleted? afaik there is no UserDataRemove

[manan19]

have you considered an alternative approach where

• removing a verification marked as primary will get discarded as an invalid message on the snapchain.
• to remove such verification, you need to mark something else as primary and then revoke the verification.

[varunsrin]

yes, it will just get set to the empty string which is the equivalent of a remove operation

[PirosB3]

Farcaster Primary Address update and stewardship guidelines

Farcaster now relies on Snapchain for canonical primary‑address data. To keep the network predictable and user‑centric, these guidelines outline best practices for designating and updating a user’s primary address.

Guiding Principles

• Deliberate choice — A primary‑address update must always be a deliberate, confirmed action by the user.
• No silent flips — A change should never occur without clear confirmation that explains its impact.
• Network consistency — All apps and signers follow the same baseline rules so every user’s decision stays consistent everywhere—this prevents accidental overrides and confusion.

Communication Expectations

• Advance notice — Announce any bulk update or backfill at least 7 days in advance via a public GitHub Discussion and direct notice to major clients.
• Signer coordination — If your client serves more than 1 % of Farcaster daily active users, coordinate with other major signers to avoid overlapping writes within a 30‑day window.