Skip to content

Messages

Documentation for messages produced by Hubble.

1. Message

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.

FieldTypeLabelDescription
dataMessageDataContents of the message. Alternatively, you can use the data_bytes to serialize the MessageData
hashbytesHash digest of data
hash_schemeHashSchemeHash scheme that produced the hash digest
signaturebytesSignature of the hash digest
signature_schemeSignatureSchemeSignature scheme that produced the signature
signerbytesPublic key or address of the key pair that produced the signature
data_bytesbytesAlternate to the "data" field. If you are constructing the MessageData in a programing language other than Typescript, you can use this field to serialize the MessageData and calculate the hash and signature on these bytes. Optional.

1.1 MessageData

A MessageData object contains properties common to all MessagesTypes and wraps a body object which contains properties specific to the MessageType.

FieldTypeLabelDescription
typeMessageTypeType of Message contained in the body
fiduint64Farcaster ID of the user producing the message
timestampuint32Farcaster epoch timestamp in seconds
networkFarcasterNetworkFarcaster network the message is intended for
bodyCastAddBody,
CastRemoveBody,
ReactionBody,
VerificationAddEthAddressBody,
VerificationRemoveBody,
UserDataBody,
LinkBody,
UserNameProof
oneOfProperties specific to the MessageType

1.2 HashScheme

Type of hashing scheme used to produce a digest of MessageData

NameNumberDescription
HASH_SCHEME_NONE0
HASH_SCHEME_BLAKE31Default scheme for hashing MessageData

1.3 Signature Scheme

Type of signature scheme used to sign the Message hash

NameNumberDescription
SIGNATURE_SCHEME_NONE0
SIGNATURE_SCHEME_ED255191Ed25519 signature (default)
SIGNATURE_SCHEME_EIP7122ECDSA signature using EIP-712 scheme

1.4 Message Type

Type of the MessageBody

NameNumberDescription
MESSAGE_TYPE_NONE0Invalid default value
MESSAGE_TYPE_CAST_ADD1Add a new Cast
MESSAGE_TYPE_CAST_REMOVE2Remove an existing Cast
MESSAGE_TYPE_REACTION_ADD3Add a Reaction to a Cast
MESSAGE_TYPE_REACTION_REMOVE4Remove a Reaction from a Cast
MESSAGE_TYPE_LINK_ADD5Add a Link to a target
MESSAGE_TYPE_LINK_REMOVE6Remove a Link from a target
MESSAGE_TYPE_VERIFICATION_ADD_ETH_ADDRESS7Add a Verification of an Ethereum Address
MESSAGE_TYPE_VERIFICATION_REMOVE8Remove a Verification
MESSAGE_TYPE_USER_DATA_ADD11Add metadata about a user
MESSAGE_TYPE_USERNAME_PROOF12Add or replace a username proof

1.5 Farcaster Network

Farcaster network the message is intended for

NameNumberDescription
FARCASTER_NETWORK_NONE0
FARCASTER_NETWORK_MAINNET1Public primary network
FARCASTER_NETWORK_TESTNET2Public test network
FARCASTER_NETWORK_DEVNET3Private test network

2. UserData

A UserData is a delta that contains metadata information about the user.

2.1 UserDataBody

Adds metadata about a user

FieldTypeLabelDescription
typeUserDataTypeType of metadata
valuestringValue of the metadata

2.2 UserDataType

Type of UserData

NameNumberDescription
USER_DATA_TYPE_NONE0Invalid default value
USER_DATA_TYPE_PFP1Profile Picture for the user
USER_DATA_TYPE_DISPLAY2Display Name for the user
USER_DATA_TYPE_BIO3Bio for the user
USER_DATA_TYPE_URL5URL of the user
USER_DATA_TYPE_USERNAME6Preferred Farcaster Name for the user

3. Cast

A Cast is a delta that represents a new public update from a user. Casts can be added and removed at any time by the user.

3.1 CastAddBody

Adds a new Cast

FieldTypeLabelDescription
embeds_deprecatedstringrepeatedURLs to be embedded in the cast
mentionsuint64repeatedFids mentioned in the cast
parent_cast_idCastIdParent cast of the cast
parent_urlstringParent URL of the cast
textstringText of the cast
mentions_positionsuint32repeatedPositions of the mentions in the text
embedsEmbedrepeatedURLs or cast ids to be embedded in the cast

Embed

FieldTypeLabelDescription
urlstring
cast_idCastId

3.2 CastRemoveBody

Removes an existing Cast

FieldTypeLabelDescription
target_hashbytesHash of the cast to remove

3.3 CastId

Identifier used to look up a Cast

FieldTypeLabelDescription
fiduint64Fid of the user who created the cast
hashbytesHash of the cast

4. Reaction

A Reaction is a delta that is applied by a user to a specific Cast.

4.1 ReactionBody

Adds or removes a Reaction from a Cast

FieldTypeLabelDescription
typeReactionTypeType of reaction
target_cast_idCastIdCastId of the Cast to react to
target_urlstringURL to react to

4.2 ReactionType

Type of Reaction

NameNumberDescription
REACTION_TYPE_NONE0Invalid default value
REACTION_TYPE_LIKE1Like the target cast
REACTION_TYPE_RECAST2Share target cast to the user's audience

5.1 LinkBody

Adds or removes a Link

FieldTypeLabelDescription
typestringType of link, <= 8 characters
displayTimestampuint32optionalUser-defined timestamp that preserves original timestamp when message.data.timestamp needs to be updated for compaction
target_fiduint64The fid the link relates to

6. Verification

A Verification is a delta that contains a bi-directional signature proving that a fid has control over an Ethereum address.

6.1 VerificationAddEthAddressBody

Adds a Verification of ownership of an Ethereum Address

FieldTypeLabelDescription
addressbytesEthereum address being verified
eth_signaturebytesSignature produced by the user's Ethereum address
block_hashbytesHash of the latest Ethereum block when the claim was produced

6.2 VerificationRemoveBody

Removes a Verification of any type

FieldTypeLabelDescription
addressbytesAddress of the Verification to remove