DOCSEARCHbyAlgolia
Submit Docs

Farcaster Protocol

repository·main·Indexed 24 days ago

https://github.com/farcasterxyz/protocol

Technical specifications for the Farcaster decentralized social protocol. Covers the message-graph architecture, Farcaster IDs (fids), Hub synchronization, and CRDT-based conflict resolution. Includes detailed guides on message serialization using proto3, hashing with BLAKE3, signing with Ed25519 or EIP-712, and the use of delegated signers. Provides specifications for core smart contracts on Optimism (Id, Key, and Storage registries) and conformance vectors for verifying cryptographic implementation parity.

Tokens
11K
Snippets
16
Records
39
Agent score
81%

What's inside farcaster-protocol

  1. Understand Message Ordering (Timestamp-Hash)

    main

    Farcaster messages are totally ordered using a combination of timestamp and hash. For two messages $m$ and $n$:

    1. Timestamp Priority: If $m_t$ and $n_t$ are distinct, the larger timestamp has the highest order.
    2. Hash Tie-breaking: If timestamps are identical, compare the hashes $m_h$ and $n_h$ using pairwise ASCII character comparison. The hash with the higher ASCII character value at the first differing position has the highest order.
    3. Equality: If both timestamps and hashes are identical, the messages are considered the same.

  2. Understand the Conformance Vector layout

    main

    Vectors are organized by version (v<N>/) and contain the following files:

    • manifest.json: Contains vector metadata and expected values in hex format.
    • messages/<id>.pb: The authoritative encoded protobuf Message bytes.
    • messages/<id>.pb.txt: A human-reviewable wire disassembly of the .pb file for auditing purposes.
    v<N>/
  manifest.json          # vector metadata + expected values (hex)
  messages/<id>.pb       # the encoded protobuf Message for each vector (authoritative bytes)
  messages/<id>.pb.txt   # human-reviewable wire disassembly of the .pb (review aid)

  3. Understand Farcaster Identity (fids)

    main

    A user identity in Farcaster is a numeric identifier known as a Farcaster ID or fid.

    Key characteristics:

    • Control: Managed via a key pair registered on a blockchain smart contract.
    • Properties: Fids are cheap, meaningless, and in unlimited supply.
    • Namespaces: Human-readable names are managed in a separate namespace layer. This separation allows users to associate names with their fids without tying the identity to a specific namespace provider.
    • Security: The registry supports key rotation if a key is exposed, and smart contract wallets can be used to prevent identity loss.

  4. Structure of a Message Sync ID

    main

    To maintain a chronologically-ordered Merkle Patricia Trie, every message in a CRDT is assigned a 36-byte Sync ID. The ID is constructed using the following fields:

    • 10 bytes: timestamp
    • 1 byte: message type
    • 4 bytes: fid
    • 1 byte: crdt / set type
    • 20 bytes: hash

    Using a timestamp prefix ensures that the rightmost branch of the trie always contains the Sync ID of the newest message.

  5. How the Message-Graph and CRDTs work

    main

    The Farcaster message-graph is a data structure that allows concurrent state updates without a central authority. It is composed of anonymous $\Delta$-state Conflict-free Replicated Data Types (CRDTs). Each CRDT governs a specific data type and defines how it can be updated.

    Key Characteristics

    • Idempotent: Applying the same message multiple times has the same effect as applying it once.
    • Non-commutative/Non-associative: Because the graph depends on state, the order of operations matters.
    • Conflict Resolution: CRDTs use a 'last-write-wins' approach based on total message ordering (timestamp and lexicographical hash). Some also implement 'remove-wins' rules.
    • Pruning: To prevent infinite growth, CRDTs prune messages once a user's storage limit (defined by the Storage registry) is reached. Pruning occurs hourly at the top of the hour (UTC). If storage expires, a 30-day grace period is provided before hubs prune all messages for that user.

  6. Authenticate messages using FIDs and Signers

    main

    Every message must be signed by the user's key pair to be tamper-proof and self-authenticating. Recipients verify authenticity by looking up the public key associated with the fid in the onchain registry.

    Delegated Signing (Signers): To allow applications to act on a user's behalf without controlling their primary identity, Farcaster uses signers.

    1. An application generates a new Signer Key Pair.
    2. The user approves this signer by signing a message with their primary (Address) key pair.
    3. The application can then use the Signer Key Pair to sign messages (e.g., CastC, CastD) on behalf of the user.

    Note: If a user rotates their primary key, all delegated signers must be re-authorized/re-signed with the new key pair.

  7. Understand Farcaster Messages and Conflict Resolution

    main

    A message represents a user action (e.g., add-post, add-like, update-profile).

    Message Structure:

    • Contains text and metadata.
    • Uniquely identified by the hash of its contents.
    • Includes a user-reported timestamp for ordering.
    • Large assets (images/videos) must be stored externally and referenced via URLs.

    Conflict Resolution (CRDTs): Farcaster uses Conflict-free Replicated Data Types (CRDTs) to handle concurrent updates. Messages use implicit or explicit resource IDs (e.g., 123.display_name) to manage conflicts.

    Ordering Rules: When multiple messages target the same resource ID, the network resolves conflicts using:

    1. Timestamp: The message with the highest timestamp wins.
    2. Lexicographical Hash: If timestamps are equal, the message with the higher hash wins.

    Reversibility and Deletion:

    • Reversible Actions: Actions like 'likes' are reversed by sending a remove message (e.g., remove-like) with a higher order than the original add message.
    • Deletes: Privacy-preserving deletes for content (like posts) are achieved by creating a remove message containing the hash of the original add message.

  8. What are Conformance Vectors and how to use them

    main

    Conformance vectors are versioned, checked-in golden vectors that provide the byte-exact output of the Farcaster message cryptographic layer. They are used by alternative clients to prove in their own CI that they produce and verify messages identically to the reference implementation. This is a requirement for FIP validator-onboarding (gate L0).

    The scope is limited to the crypto layer (encoding, hashing, and signing) using protobuf, BLAKE3, and Ed25519. It does not currently include post-state merkle roots.

  9. General message validation rules for CRDTs

    main

    All CRDTs must enforce these three fundamental validation rules for any incoming message:

    1. EIP-712 Signatures: Valid only if the signing Ethereum address is the owner of the fid.
    2. ED25519 Signatures: Valid only if the signing key pair is a Signer present in the KeyRegistry contract for the fid and has not been removed.
    3. Ownership: Messages are valid only if the fid is owned by the custody address that signed the message, or the signer specified by the Id Registry.

    Revocation Rule

    If a Signer is removed from the KeyRegistry for an fid, all messages signed by that signer in any other CRDT must be immediately revoked and discarded.

  10. How Hub Syncing and Diff Sync work

    main

    Hubs maintain consistency across the network using a combination of gossip and an out-of-band process called diff sync. While gossip handles message propagation, it cannot guarantee order or delivery. To ensure strong eventual consistency, Hubs must:

    1. Perform a diff sync when connecting to the network to catch up to the current state.
    2. Periodically select a random peer and perform a diff sync.

    Diff sync leverages a Merkle Patricia Trie to identify missing messages between Hubs by comparing exclusion sets. Because the trie is chronologically ordered, Hubs can find the divergence point in constant time by comparing exclusion sets from left to right. Once the divergence point is found, the Hub requests the full trie under that node to identify and merge missing branches into its local CRDT.

  11. Understand Farcaster protocol versioning and upgrades

    main

    Farcaster uses date-based versioning (YYYY.MM.DD) and follows a strict upgrade cycle to ensure stability and compatibility:

    • Specification Releases: A new protocol specification is released every 6 weeks.
    • Hub Updates: Hubs must support the latest specification within 12 weeks of its release.
    • Transition Period: Hubs must peer with older hubs for up to 4 weeks after a new version release.
    • Cutoff Date: Hubs must implement a cutoff date set to 16 weeks after the specification release. Once reached, the Hub will shut down and refuse to start.
    • Backwards Compatibility: Breaking changes are managed via feature flags in the release train system, typically enabled after the 4-week transition period.

  12. Use Signers to Authorize Messages

    main

    A Signer is an Ed25519 key pair used by applications to authorize actions (like Casts or Reactions) on behalf of a user.

    Lifecycle of a Signer:

    1. Authorization: A user authorizes an application's Signer by signing the public key with their custody address (using ECDSA/EIP-1271) and registering it on the Key Registry contract.
    2. Usage: The application uses the Signer to produce EdDSA signatures for protocol messages.
    3. Revocation: A user can revoke a Signer at any time by signing a removal transaction with their custody address.