Frames are a standard for creating interactive and authenticated experiences on Farcaster, embeddable in any Farcaster client.
A frame is a set of <meta> tags returned within the <head> of an HTML page. If a page contains all required frame properties, Farcaster apps will render the page as a frame. The frame <meta> tags extend the OpenGraph protocol.
Frames can be linked together to create dynamic applications embedded inside casts.
Lifecycle of a frame app
A frame app begins with an initial frame which is cached by apps and shown to users. A frame must have an image. It may have buttons, which when clicked load other frames or redirect the user to external websites.
A frame is an HTML web application that lives at a URL (e.g. foo.com/app) on a web server. We'll refer to this web server as the "frame server."
When a user clicks a button on a frame, the app makes a POST request to the frame server with a frame signature which proves that the request came from the user. The server must respond with a new frame that is sent back to the user.
When a frame server receives a POST request:
Follow these best practices to work around the limitations of frames:
A frame enters Farcaster when a user creates a cast and embeds the frame URL in it. An app that wants to support frames must:
A frame must include required properties and may contain optional properties. Frames can be validated using the Frame Validator tool provided by Warpcast.
A frame property is a meta tag with a property and a content value. The properties are always prefixed with fc:frame.
There are a few rules for serving images in fc:frame:image tags:
Clients may resize larger images or crop those that do not fit in their aspect ratio. SVG images are not because they can contain scripts and extra work must be done by clients to sanitize them.
Displaying frames in a feed
Farcaster apps are responsible for rendering frames to users and proxying their interactions back to the frame server on their behalf.
When a URL is encountered embedded in a cast:
Apps may render frames any time they are showing a cast to a viewer. The following rules apply to the rendering of frames:
If the button is a post_redirect or link action:
If the button is a mint action, the following rules also apply:
If the button clicked is a post or post_redirect, apps must:
If the button clicked is a mint, apps should:
Applications will receive responses from frame servers after a POST request is submitted. The following rules apply to the handling of these responses:
Frames are highly sandboxed environments that do not allow direct access to Ethereum wallets. However, there are still some security concerns that must be addressed by both frame developers and apps that implement frames.
A Frame signature proves that a user clicked a frame button. It is created by the Farcaster app, signed by the user's account and sent to the Frame server.
When a frame button is clicked, the Farcaster app must generate a FrameAction protobuf. A FrameAction is a new type of Farcaster message. Like all FC messages, it must be signed with an active Ed25519 account key (aka signer) that belongs to the user.
A FrameActionBody in a message m is valid only if it passes these validations:
A signature packet is a JSON object sent to the Frame server when a button is clicked. It contains two objects:
Unsigned messages can be spoofed and should usually be ignored. It is only safe to use them if you are performing an unauthenticated request.
If you are unsure, always read the signed message by sending it into the validateMessage endpoint on hubs and only trust the data it returns.
The Signed Message can be validated by calling the validateMessage API on Hubs, as shown in the script below. See the Hub HTTP API for reference. The hub (assuming it’s fully in sync) will validate the following:
Hubs perform important validations in addition to verifying a signature packet's Ed25519 signature.
Although it may be possible to validate an Ed25519 signature onchain, a valid signature is insufficient to fully authenticate a frame message packet. Applications must also check that the fid is valid, the signer key is active, and the message body is valid. Outside of OP mainnet, it is difficult to perform these validations onchain.
The following ideas are being explored actively as extensions to the frame specification: