FIP: Farcaster Mini App Contract Address Metadata

[SamuelLHuber]

FIP: Farcaster Mini App Contract Address Metadata

FIP: Farcaster Mini App Contract Address Metadata
Title: Farcaster Mini App Contract Address Metadata
Authors: @samuellhuber

Problem

Farcaster Mini Apps launch tokens and get popular. That leaves fraudulent actors trying to launch impersonations and always leaves users wondering which tokens and contracts are legit.

This could be used to show in the transaction confirmation screen that this token belongs to a mini app or that a contract your interacting with is from a mini app. Overall increasing trust across the ecosystem with these verifications.

One example is Mini Apps integrating with Megapot where they allow the buying of tickets. Well how do I as the user know that these are from the real megapot? I could know if my client shows me these contracts are from the megapot mini app.

An analog case can be made for DeFi integrations like Morpho, Uniswap and others.

Specification

For Mini Apps

Add an array of known contract addresses associated with the mini app to .well-known/farcaster.json manifest.

The format of each contract address shall be defined as per CAIP-19

The result is an extended .well-known/farcaster.json looking like the following samples:

add in a single contract address

{
  "contracts": ["eip155:8453/erc20:0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed"]
  "accountAssociation": { ... }
  "miniapps" : { ... }
}

add in a set of contract addresses across chains

{
  "contracts": [
     "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
     "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
  ]
  "accountAssociation": { ... }
  "miniapps" : { ... }
}

Ideas for Client Developers

Anyone rendering the data from this extension may decide to now honor it as any contract address could be arbitrarily be used, though this can be extended similarly to FID account associations, where the smart contract deployer wallet has to sign a message including the account association's FID or similar for verification. This is something to be discussed here.

Changelog

2025-08-26: created FIP

[horsefacts]

Thanks for opening a discussion on this. As you identified, the main challenge here is verifying ownership or association with the contract address. The problem is pretty similar to claiming ownership of an NFT collection on a marketplace, which is probably a good place to look for inspiration and past challenges, like edge cases around spoofing.

It might be harder in our case because these are more arbitrary contracts that will less often have an "owner". A simple place to start might be something like "contract deployer or owner() must be a verified address associated with the mini app creator" might work but I suspect it will still exclude a lot of cases we'd like to be able to handle.

[SamuelLHuber]

by will still exclude a lot of cases we'd like to be able to handle. what cases come to mind?

[horsefacts]

Tokens launched from factory contracts are the main one.

[varunsrin]

Thanks for putting this together.

We've also been thinking about this but haven't found a design for verification that would work for all tokens / miniapps, as @horsefacts points out. I think that might be the most important thing to nail, because associations without verifications aren't very useful.

The second thing that this design implies is a many:many relationship between tokens and miniapps. While that is flexible, I wonder if that will be very confusing for users to reason about. It may be worth mocking the exact UI that a client should show to a user, and thinking through whether that is understandable

[varunsrin]

An alternative is to go for a 1:1 or 1:many relationship instead.

[SamuelLHuber]

the 1:1 or 1:many is hard to enforce though unless that e.g. happens like a unique verification e.g. primary address on an app (fid) level on the protocol.

say you have deployed $NATIVE like Derek has and built multiple mini apps for it, then you'd have a 1 token to many apps relationship.

Likely a one app can specify one token flow is a good first step for devs with project bound tokens to signify that.

this way if one starts with allowing each mini app to just verify one contract/token to start with then the UI is clear for token associations in my eyes that adds verification steps to the UI.

How one does the token <> mini app verification is TBD though the above indicates a potential client implementation on the app side

[jfarid27]

I do believe you should definitely do at least one to many, and also a way to update the token. We do a decent amount of client work and can confirm there's usually a token and various staking tokens associated to a mini app.

A good example is TIPN where they have both TIPN, and sTIPN, and recent campaigns with partner tokens like BETR. I imagine as the farcaster economy grows, yield bearing assets will become more prominent so the interaction with the user might need to support a range of tokens, staked tokens, etc., and they will need to be updated over time to add and remove tokens.