message.proto

syntax = "proto3";
import "username_proof.proto";

/**
  * A Message is a delta operation on the Farcaster network. The message protobuf is an envelope
  * that wraps a MessageData object and contains a hash and signature which can verify its authenticity.
  */
message Message {
  MessageData data = 1; // Contents of the message
  bytes hash = 2; // Hash digest of data
  HashScheme hash_scheme = 3; // Hash scheme that produced the hash digest
  bytes signature = 4; // Signature of the hash digest
  SignatureScheme signature_scheme = 5; // Signature scheme that produced the signature
  bytes signer = 6; // Public key or address of the key pair that produced the signature
  optional bytes data_bytes = 7; // MessageData serialized to bytes if using protobuf serialization other than ts-proto
}

  /**
 * A MessageData object contains properties common to all messages and wraps a body object which
 * contains properties specific to the MessageType.
 */
message MessageData {
  MessageType type = 1; // Type of message contained in the body
  uint64 fid = 2; // Farcaster ID of the user producing the message
  uint32 timestamp = 3; // Farcaster epoch timestamp in seconds
  FarcasterNetwork network = 4; // Farcaster network the message is intended for
  oneof body {
    CastAddBody cast_add_body = 5;
    CastRemoveBody cast_remove_body = 6;
    ReactionBody reaction_body = 7;
    VerificationAddAddressBody verification_add_address_body = 9;
    VerificationRemoveBody verification_remove_body = 10;
    // SignerAddBody signer_add_body = 11; // Deprecated
    UserDataBody user_data_body = 12;
    // SignerRemoveBody signer_remove_body = 13; // Deprecated
    LinkBody link_body = 14;
    UserNameProof username_proof_body = 15;
    FrameActionBody frame_action_body = 16;
    
    // Compaction messages
    LinkCompactStateBody link_compact_state_body = 17;
  } // Properties specific to the MessageType
}

/** Type of hashing scheme used to produce a digest of MessageData */
enum HashScheme {
  HASH_SCHEME_NONE = 0;
  HASH_SCHEME_BLAKE3 = 1; // Default scheme for hashing MessageData
}

/** Type of signature scheme used to sign the Message hash  */
enum SignatureScheme {
  SIGNATURE_SCHEME_NONE = 0;
  SIGNATURE_SCHEME_ED25519 = 1; // Ed25519 signature (default)
  SIGNATURE_SCHEME_EIP712 = 2; // ECDSA signature using EIP-712 scheme
}

/** Type of the MessageBody */
enum MessageType {
  MESSAGE_TYPE_NONE = 0;
  MESSAGE_TYPE_CAST_ADD = 1; // Add a new Cast
  MESSAGE_TYPE_CAST_REMOVE = 2; // Remove an existing Cast
  MESSAGE_TYPE_REACTION_ADD = 3; // Add a Reaction to a Cast
  MESSAGE_TYPE_REACTION_REMOVE = 4; // Remove a Reaction from a Cast
  MESSAGE_TYPE_LINK_ADD = 5; // Add a new Link
  MESSAGE_TYPE_LINK_REMOVE = 6; // Remove an existing Link
  MESSAGE_TYPE_VERIFICATION_ADD_ETH_ADDRESS = 7; // Add a Verification of an Ethereum Address
  MESSAGE_TYPE_VERIFICATION_REMOVE = 8; // Remove a Verification
//  Deprecated
//  MESSAGE_TYPE_SIGNER_ADD = 9; // Add a new Ed25519 key pair that signs messages for a user
//  MESSAGE_TYPE_SIGNER_REMOVE = 10; // Remove an Ed25519 key pair that signs messages for a user
  MESSAGE_TYPE_USER_DATA_ADD = 11; // Add metadata about a user
  MESSAGE_TYPE_USERNAME_PROOF = 12; // Add or replace a username proof
  MESSAGE_TYPE_FRAME_ACTION = 13; // A Farcaster Frame action
  MESSAGE_TYPE_LINK_COMPACT_STATE = 14; // Link Compaction State Message
}

/** Farcaster network the message is intended for */
enum FarcasterNetwork {
  FARCASTER_NETWORK_NONE = 0;
  FARCASTER_NETWORK_MAINNET = 1; // Public primary network
  FARCASTER_NETWORK_TESTNET = 2; // Public test network
  FARCASTER_NETWORK_DEVNET = 3; // Private test network
}

/** Adds metadata about a user */
message UserDataBody {
  UserDataType type = 1; // Type of metadata
  string value = 2; // Value of the metadata
}

/** Type of UserData */
enum UserDataType {
  USER_DATA_TYPE_NONE = 0;
  USER_DATA_TYPE_PFP = 1; // Profile Picture for the user
  USER_DATA_TYPE_DISPLAY = 2; // Display Name for the user
  USER_DATA_TYPE_BIO = 3; // Bio for the user
  USER_DATA_TYPE_URL = 5; // URL of the user
  USER_DATA_TYPE_USERNAME = 6; // Preferred Name for the user
  USER_DATA_TYPE_LOCATION = 7; // Current location for the user
  USER_DATA_TYPE_TWITTER = 8; // Username of user on twitter
  USER_DATA_TYPE_GITHUB = 9; // Username of user on github
}

message Embed {
  oneof embed {
    string url = 1;
    CastId cast_id = 2;
  }
}

/** Type of cast */
enum CastType {
  CAST = 0;
  LONG_CAST = 1;
}


/** Adds a new Cast */
message CastAddBody {
  repeated string embeds_deprecated = 1; // URLs to be embedded in the cast
  repeated uint64 mentions = 2; // Fids mentioned in the cast
  oneof parent {
    CastId parent_cast_id = 3; // Parent cast of the cast
    string parent_url = 7; // Parent URL
  };
  string text = 4; // Text of the cast
  repeated uint32 mentions_positions = 5; // Positions of the mentions in the text
  repeated Embed embeds = 6; // URLs or cast ids to be embedded in the cast
  CastType type = 8; // Type of cast
}

/** Removes an existing Cast */
message CastRemoveBody {
  bytes target_hash = 1; // Hash of the cast to remove
}

/** Identifier used to look up a Cast */
message CastId {
  uint64 fid = 1; // Fid of the user who created the cast
  bytes hash = 2; // Hash of the cast
}

/** Adds or removes a Reaction from a Cast */
message ReactionBody {
  ReactionType type = 1; // Type of reaction
  oneof target {
    CastId target_cast_id = 2; // CastId of the Cast to react to
    string target_url = 3; // URL to react to
  }
}

/** Type of Reaction */
enum ReactionType {
  REACTION_TYPE_NONE = 0;
  REACTION_TYPE_LIKE = 1; // Like the target cast
  REACTION_TYPE_RECAST = 2; // Share target cast to the user's audience
}

/** Type of Protocol to disambiguate verification addresses */
enum Protocol {
  PROTOCOL_ETHEREUM = 0;
  PROTOCOL_SOLANA = 1;
}

/** Adds a Verification of ownership of an Address based on Protocol */
message VerificationAddAddressBody {
  bytes address = 1; // Address being verified for a given Protocol
  bytes claim_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
  Protocol protocol = 7; // Protocol of the Verification
}

/** Removes a Verification of a given protocol */
message VerificationRemoveBody {
  bytes address = 1; // Address of the Verification to remove
  Protocol protocol = 2; // Protocol of the Verification to remove
}

/** Adds or removes a Link */
message LinkBody {
  string type = 1; // Type of link, <= 8 characters
  optional uint32 displayTimestamp = 2; // User-defined timestamp that preserves original timestamp when message.data.timestamp needs to be updated for compaction
  oneof target {
    uint64 target_fid = 3;  // The fid the link relates to
  }
}

/** A Compaction message for the Link Store */
message LinkCompactStateBody {
  string type = 1; // Type of link, <= 8 characters
  repeated uint64 target_fids = 2;
}

/** A Farcaster Frame action */
message FrameActionBody {
  bytes url = 1; // URL of the Frame triggering the action
  uint32 button_index = 2; // The index of the button pressed (1-4)
  CastId cast_id = 3; // The cast which contained the frame url
  bytes input_text = 4; // Text input from the user, if present
  bytes state = 5; // Serialized frame state value
  bytes transaction_id = 6; // Chain-specific transaction ID for tx actions
  bytes address = 7; // Chain-specific address for tx actions
}