hub-monorepo/packages/hub-nodejs/docs/Builders.md

Builders

Builders are factory methods that construct and sign Farcaster Messages which can be broadcast to Hubs.

• Prerequisites
  • Ed25519Signer
  • Eip712Signer
  • Data Options
• Methods
  • makeSignerAdd
  • makeSignerRemove
  • makeCastAdd
  • makeCastRemove
  • makeReactionAdd
  • makeReactionRemove
  • makeUserDataAdd
  • makeVerificationAddEthAddress
  • makeVerificationRemove

Prerequisites

Before you can build messages, you'll need to construct the following objects:

• An ed25519Signer, used to sign most messages.
• A eip712Signer, used to sign some messages.
• A dataOptions, which contains message metadata.

Ed25519Signer

A Ed25519Signer is an EdDSA key pair which is necessary for signing most messages on behalf of an fid. This example below shows how to construct a new NobleEd25519Signer using the @noble library:

import { NobleEd25519Signer } from '@farcaster/hub-nodejs';
import * as ed from '@noble/ed25519';

const privateKey = ed.utils.randomPrivateKey(); // Applications must store this key securely.

const ed25519Signer = new NobleEd25519Signer(privateKey);

Eip712Signer

An Eip712Signer is an ECDSA key pair which is necessary signing for some messages like SignerAdds and Verifications. This example shows how to construct an EthersEip712Signer from a wallet's recovery phrase:

import { EthersEip712Signer } from '@farcaster/hub-nodejs';
import { Wallet } from 'ethers';

const mnemonic = 'ordinary long coach bounce thank quit become youth belt pretty diet caught attract melt bargain';
const wallet = Wallet.fromPhrase(mnemonic);

const eip712Signer = new EthersEip712Signer(wallet);

Note: If you must use Ethers v5 in your application, you'll need to use the EthersV5Eip712Signer.

Data Options

Common message properties that must be passed into to any Builder method to produce a valid message.

Usage

import { FarcasterNetwork, toFarcasterTime } from '@farcaster/hub-nodejs';

const unixTimestamp = 1679029607159;

// Safety: timestamp is known and cannot error
const farcasterTimestamp = toFarcasterTime(unixTimestamp)._unsafeUnwrap();

const dataOptions = {
  fid: 1,
  network: FarcasterNetwork.DEVNET,
  timestamp: farcasterTimestamp,
};

Properties

Name	Type	Description
fid	number	Fid of the user creating the message
network	FarcasterNetwork	Farcaster network to broadcast the message to
timestamp?	number	(optional) Farcaster epoch message timestamp, defaults to now

Builder Methods

makeSignerAdd

Returns a message which authorizes a new Ed25519 Signer to create messages on behalf of a user.

Usage

import { makeSignerAdd, hexStringToBytes } from '@farcaster/hub-nodejs';

const signerHex = '0x027fb58156b2733495acb24248e5e3ddf7ad8be4b85321c1e598e06ed030f51f'; // public key of the Ed25519 key-pair to authorize
const signerBytes = hexStringToBytes(signerHex)._unsafeUnwrap(); // Safety: signerHex is known and cannot error
const name = 'foo'; // label to help the user identify this signers

const signerAdd = await makeSignerAdd({ signer: signerBytes, name }, dataOptions, eip712Signer);

Returns

Type	Description
HubAsyncResult<SignerAddMessage>	A HubAsyncResult that contains the valid SignerAddMessage.

Parameters

Name	Type	Description
body	SignerAddBody	A valid VerificationAddEd25519 body object containing the data to be sent.
dataOptions	DataOptions	Optional arguments to construct the message.
signer	Eip712Signer	An Eip712Signer generated from the user's custody address.

---

makeSignerRemove

Returns a message which revokes a previously authorized Ed25519 Signer.

Usage

import { makeSignerRemove, hexStringToBytes } from '@farcaster/hub-nodejs';

const signerHex = '0x027fb58156b2733495acb24248e5e3ddf7ad8be4b85321c1e598e06ed030f51f'; // public key of the Ed25519 key-pair to revoke
const signerBytes = hexStringToBytes(signerHex)._unsafeUnwrap(); // Safety: signerHex is known and cannot error

const signerRemove = await makeSignerRemove({ signer: signerBytes }, dataOptions, eip712Signer);

Returns

Type	Description
HubAsyncResult<SignerRemoveMessage>	A HubAsyncResult that contains the valid SignerRemoveMessage.

Parameters

Name	Type	Description
body	SignerRemoveBody	A valid SignerRemove body object containing the data to be sent.
dataOptions	DataOptions	Optional metadata to construct the message.
signer	Eip712Signer	An Eip712Signer generated from the user's custody address.

---

makeCastAdd

Returns a message that adds a new Cast.

Usage

import { makeCastAdd } from '@farcaster/hub-nodejs';

const cast = await makeCastAdd(
  { text: 'hello world', embeds: ['http://www.farcaster.xyz'], mentions: [], mentionsPositions: [] },
  dataOptions,
  ed25519Signer
);

Returns

Type	Description
HubAsyncResult<CastAddMessage>	A Result that contains the valid CastAddMessage

Parameters

Name	Type	Description
body	CastAddBody	A valid CastAdd body object containing the data to be sent.
dataOptions	DataOptions	Optional metadata to construct the message.
signer	Ed25519Signer	A currently valid Signer for the fid.

---

makeCastRemove

Returns a message that removes an existing Cast.

Usage

import { hexStringToBytes, makeCastRemove } from '@farcaster/hub-nodejs';

const targetHashHex = '006f082f70dfb2de81e7852f3b79f1cdf2aa6b86';

// Safety: targetHashHex is known and can't error
const targetHashBytes = hexStringToBytes(targetHashHex)._unsafeUnwrap();

const castRemove = await makeCastRemove(
  {
    targetHash: targetHashBytes,
  },
  dataOptions,
  ed25519Signer
);

Returns

Type	Description
HubAsyncResult<CastRemoveMessage>	A HubAsyncResult that contains the valid CastRemoveMessage.

Parameters

Name	Type	Description
body	CastRemoveBody	A valid CastRemove body object containing the data to be sent.
dataOptions	DataOptions	Optional metadata to construct the message.
signer	Ed25519Signer	A currently valid Signer for the fid.

---

makeReactionAdd

Returns a message that adds a Reaction to an existing Cast.

Usage

import { hexStringToBytes, makeReactionAdd, ReactionType } from '@farcaster/hub-nodejs';

const targetHashHex = '006f082f70dfb2de81e7852f3b79f1cdf2aa6b86';
// Safety: targetHashHex is known and can't error
const targetHashBytes = hexStringToBytes(targetHashHex)._unsafeUnwrap();

const reactionLikeBody = {
  type: ReactionType.LIKE,
  targetCastId: {
    fid: 1, // Fid of the Cast's author, which is being reacted to.
    hash: targetHashBytes, // Hash of the CastAdd message being reacted to
  },
};

const like = await makeReactionAdd(reactionLikeBody, dataOptions, ed25519Signer);

Returns

Type	Description
HubAsyncResult<ReactionAddMessage>	A HubAsyncResult that contains the valid ReactionAddMessage.

Parameters

Name	Type	Description
body	ReactionBody	A valid ReactionAdd body object containing the data to be sent.
dataOptions	DataOptions	Optional metadata to construct the message.
signer	Ed25519Signer	A currently valid Signer for the fid.

---

makeReactionRemove

Returns a message that removes an existing Reaction to an existing Cast.

Usage

import { hexStringToBytes, makeReactionRemove, ReactionType } from '@farcaster/hub-nodejs';

const targetHashHex = '006f082f70dfb2de81e7852f3b79f1cdf2aa6b86';

// Safety: targetHashHex is known and can't error
const targetHashBytes = hexStringToBytes(targetHashHex)._unsafeUnwrap();

const reactionLikeBody = {
  type: ReactionType.LIKE,
  targetCastId: {
    fid: 1, // Fid of the Cast's author, which is being reacted to.
    hash: targetHashBytes, // Hash of the CastAdd message being reacted to
  },
};

const like = await makeReactionRemove(reactionLikeBody, dataOptions, ed25519Signer);

Returns

Type	Description
HubAsyncResult<ReactionRemoveMessage>	A HubAsyncResult that contains the valid ReactionRemoveMessage.

Parameters

Name	Type	Description
body	ReactionBody	A valid ReactionRemove body object containing the data to be sent.
dataOptions	DataOptions	Optional metadata to construct the message.
signer	Ed25519Signer	A currently valid Signer for the fid.

---

makeUserDataAdd

Returns a message that updates metadata about the user.

Usage

import { makeUserDataAdd, UserDataType } from '@farcaster/hub-nodejs';

const userDataPfpBody = {
  type: UserDataType.PFP,
  value: 'https://i.imgur.com/yed5Zfk.gif',
};

const userDataPfpAdd = await makeUserDataAdd(userDataPfpBody, dataOptions, ed25519Signer);

Returns

Value	Description
HubAsyncResult<UserDataAddMessage>	A HubAsyncResult that contains a signed UserDataMessage.

Parameters

Name	Type	Description
body	UserDataBody	A valid UserData body object containing the data to be sent.
dataOptions	DataOptions	Optional metadata to construct the message.
signer	Ed25519Signer	A currently valid Signer for the fid.

---

makeVerificationAddEthAddress

Returns a message that proves that a user owns an Ethereum address.

Usage

import {
  FarcasterNetwork,
  hexStringToBytes,
  makeVerificationAddEthAddress,
  makeVerificationEthAddressClaim,
} from '@farcaster/hub-nodejs';

// Safety: eip712Signer is known and can't error
const addressBytes = (await eip712Signer.getSignerKey())._unsafeUnwrap();

const fid = 1;
const blockHashHex = '0x1d3b0456c920eb503450c7efdcf9b5cf1f5184bf04e5d8ecbcead188a0d02018';
const blockHashBytes = hexStringToBytes(blockHashHex)._unsafeUnwrap();

const claimResult = makeVerificationEthAddressClaim(fid, addressBytes, FarcasterNetwork.DEVNET, blockHashBytes);

if (claimResult.isOk()) {
  const claim = claimResult.value;

  // Sign the claim
  const ethSignResult = await eip712Signer.signVerificationEthAddressClaim(claim);
  const ethSignature = ethSignResult._unsafeUnwrap(); // Safety: claim is known and can't error

  // Construct a Verification Add Message with the claim signature
  const verificationBody = {
    address: addressBytes,
    ethSignature,
    blockHash: blockHashBytes,
  };

  const verificationMessage = await makeVerificationAddEthAddress(verificationBody, dataOptions, ed25519Signer);
}

Returns

Type	Description
HubAsyncResult<VerificationAddEthAddressMessage>	A HubAsyncResult that contains a signed VerificationAddEthAddressMessage.

Parameters

Name	Type	Description
body	VerificationAddEthAddressBody	An object which contains an Eip712 Signature from the Ethereum Address being verified.
dataOptions	DataOptions	Optional metadata to construct the message.
signer	Ed25519Signer	A currently valid Signer for the fid.

---

makeVerificationRemove

Returns a message that removes a previously added Verification.

Usage

import { makeVerificationRemove } from '@farcaster/hub-nodejs';

// Safety: eip712Signer is known and can't error
const addressBytes = (await eip712Signer.getSignerKey())._unsafeUnwrap();

const verificationRemoveBody = {
  address: eip712Signer.addressBytes, // Ethereum Address of Verification to remove
};

const verificationRemoveMessage = await makeVerificationRemove(verificationRemoveBody, dataOptions, ed25519Signer);

Returns

Type	Description
HubAsyncResult<VerificationRemoveMessage>	A HubAsyncResult that contains a signed VerificationRemoveMessage.

Parameters

Name	Type	Description
body	VerificationRemoveBody	An object which contains data about the Verification being removed.
dataOptions	DataOptions	Optional metadata to construct the message.
signer	Ed25519Signer	A currently valid Signer for the fid.