FIP: Primary Address Verification

[horsefacts]

FIP: Primary Address Verification

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

Abstract

Extend verifications to designate a "primary" address.

Problem

Users may create many verifications associated with their fid, but they cannot indicate which is their preferred address. This is frustrating for developers and users. Developers don't know which address to use in their applications, and users don't know where to look for token transfers associated with their fid.

Goals

• Users should be able to specify a verified address as their “primary” address to receive payments, mints, airdrops, etc.
• Applications should be able to easily read primary address from Hubs.
• Primary address should support multiple chains and address types (or be open to future extension).
• If we don’t support multichain addresses right away, we should limit preferred addresses to EOA verifications to prevent cross-chain sends to inaccessible accounts.

Specification

Extend VerificationAddEthAddressBody with a new is_primary field:

/** Adds a Verification of ownership of an Address based on Protocol */
message VerificationAddAddressBody {
  bytes address = 1; // Address being verified for a given Protocol
  bytes address_verification_signature = 2; // Signature produced by the user's address for a given Protocol
  bytes block_hash = 3; // Hash of the latest Ethereum block when the signature was produced
  uint32 verification_type = 4; // Type of verification. 0 = EOA, 1 = contract
  uint32 chain_id = 5; // 0 for EOA verifications, 1 or 10 for contract verifications
  bool is_primary = 6; // Whether this Verification is a "primary" address
}

Since existing verification signatures remain valid, users may send another VerificationAddAddressBody message with a new value of is_primary. Only EOA verifications may be designated as primary. Users may have one primary verification per protocol.

When a Hub receives a VerificationAddEthAddressBody message, it must:

• Follow existing validation rules for VerificationAddEthAddressBody.
• Validate that verification_type is EOA if is_primary is true, otherwise reject the message.
• Validate that no verification with the same protocol already is_primary, otherwise reject the message.

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.

Application developers SHOULD use the primary address for interactions on all chains when present.

Rationale

This proposal meets most of our goals:

• ✅ Users can specify a primary address.
• ✅ Applications can read primary address from the same Hub APIs.
• 🚫 Does not support multiple chains and address types, but ✅ open to future extension.
• ✅ Prevents use of inaccessible addresses by limiting to verified EOAs.

Why not support primary verifications per-chain now?
We can further extend these changes to support per-chain verifications (See "Extending to per-chain verifications" below), but designating a single primary EOA is better than the status quo and can ship fast. Additionally, this design avoids requiring users to re-sign existing verifications.

Release

Changes are backwards compatible and can go out in a patch relase.
Include changes formally in the 2024.02.21 release.

Appendix: Extending to per-chain verifications

We propose shipping the simple "primary EOA" model described above first, but it's possible to extend to per-chain verifications. The following changes are NOT part of this proposal, but describe how we can further extend primary verifications.

Currently, all EOA verifications have chain_id 0, while smart contract verifications have chain_id 1 (ETH mainnet) or 10 (OP mainnet).

To enable per-chain verifications we can:

• Index lookups on a composite key of chainId + address
• Allow nonzero chainIds for EOA verifications
• Add chainId to the EIP-712 domain separator for EOA verifications
• Reserve chainId zero as a special “cross-chain” verification

When hubs receive a VerificationSetPrimaryAddressBody message with a nonzero chainId and EOA verification type, they must remove any “cross-chain” verifications with the same address.

Users who want to configure per-chain addresses will need to sign once per chain to create a new verification.

Note: Extending smart contract verifications to to additional chains requires Hubs to have access to an RPC provider for each chain. We limited contract verifications to ETH mainnet and OP mainnet for this reason. We'll have to think about this.

[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]

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.

[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?