Farcaster Docs

Appearance

Messages ​

Farcaster accounts interact by signing and publishing messages. Alice can create a message that says "Hello @bob" and sign it with her key.

Messages are stored on a peer-to-peer network of nodes. A node in the Farcaster network is called a Hub, and each Hub stores a copy of the entire network. A user can publish a message to one Hub and it will propagate to the entire network in a few seconds. Farcaster's compact message format and eventually consistent model lets this architecture scale to millions of users.

An account can generate a key and give it to an app which can use it to sign messages. Users can use multiple apps with the same account, and each application can have its own key. Separating the signing keys from the ownership keys helps keep the account secure.

Types ​

Accounts can publish five different kinds of messages to the network:

TypeDescriptionExample
CastsPublic messages that can be seen by anyone."Hello world!"
ReactionsA relationship between an account and a cast.Alice liked Bob's cast.
LinksA relationship between two accounts.Alice follows Bob.
Profile DataMetadata about the account.Profile picture, display name.
VerificationsA proof of ownership of something.An Ethereum address.

Storage ​

An account must pay rent to keep their messages on the Farcaster network. Charging rent prevents users from spamming the network.

An account can rent a unit of storage by making an onchain transaction to the Storage Registry. A unit of storage costs $7 today, lasts for one year and lets each account store a certain number of messages of each type. The limits for each type today are:

  • 5000 Casts
  • 2500 Reactions
  • 2500 Links
  • 50 Profile Data
  • 50 Verifications

If an account exceeds its limit for a message type, the oldest message is pruned to make space for the new one. The user can keep using the network without paying for more storage and Hubs can keep the storage load under control. An account can always purchase more storage to increase its limits.

An account that lets its storage expire may lose all its messages. There is a 30-day grace period after a storage unit expires during which an account must renew or lose its messages.

The price and size of each storage unit is re-calculated periodically to balance growth and quality of the network. See FIP-6 for more details.

Deletion ​

An account can delete messages at any time by publishing a corresponding delete message. The delete message will remove the contents of the original message, leaving a tombstone in its place. A deleted message will still count towards the account's storage limit until it expires by being pushed out by a newer message.

Timestamps ​

Messages have timestamps which count seconds from the Farcaster Epoch, which began on Jan 1, 2021 00:00:00 UTC. Using a recent epoch makes timestamps and messages much smaller, which is important for the network.

Timestamps are unverified and can be backdated by users, similar to a blog post. They cannot be more than 15 minutes into the future, as the network will reject such messages.

Resources ​

Specifications ​

  • Messages - the atomic unit of change on Farcaster
  • CRDTs - rules for keeping messages in sync on the network
  • Storage Registry - contract to acquire storage units

APIs ​

Tutorials ​