Writing to Farcaster (experimental)

WARNING

Farcaster writes with Privy embedded signers is an experimental feature. It is under active development and interfaces will change. Accordingly this feature should be used with care given breaking interface changes are likely to follow.

Farcaster is a sufficiently decentralized social network whose core social graph is stored on-chain. Users can choose how content they create is stored and it enables unique, composable experiences by enabling users to link their accounts with a wallet of their choosing.

Getting started

Privy enables your users to easily log in to and write with their Farcaster account. This means you can easily integrate Privy with Farcaster to compose experiences with a user's existing social graph or network.

You can see a demo here: https://farcaster-demo.vercel.app. The example repo is at https://github.com/privy-io/farcaster-demo.

Here's how to get started!

1. Login with Farcaster

The following assumes you have set up Privy with your app. If you haven't, start by following the instructions in the Privy Quickstart to get your app set up with Privy.

You must also enable Farcaster as a sign-in method for your app from the developer console. Please see the Farcaster Integration recipe to get set up.

2. Create an embedded Farcaster signer

The first step to write to Farcaster is to create an embedded signer.

What is an embedded Farcaster signer?

Farcaster data is shared across a network of servers called "hubs". Hubs are responsible for verifying and sharing messages on the protocol. In order to submit messages, you need to create a Farcaster signer.

This is an ed25519 key-pair that is authorized to sign messages on your user's behalf. Privy generates a new non-custodial signer for your user.

A user can authorize their embedded Farcaster signer to post on their behalf via Warpcast's signer connect flow. This allows your app to post messages with your user's Warpcast account!

---

In order to do so, a user must go through an authorization flow, which grants their new Farcaster signer permission to submit casts on their behalf. Use the useExperimentalFarcasterSigner() hook to request a new signer.

import { useExperimentalFarcasterSigner, usePrivy } from @privy-io/react-auth;

const { user } = usePrivy();
const { requestFarcasterSigner } = useExperimentalFarcasterSigner();

const farcasterAccount = user.linkedAccounts.find((account) => account.type === 'farcaster');

<button
  onClick={() => requestFarcasterSigner()}
  // Prevent requesting a Farcaster signer if a user has not already linked a Farcaster account
  // or if they have already requested a signer
  disabled={!farcasterAccount || farcasterAccount.signerPublicKey}
>
  Authorize my Farcaster signer
</button>

TIP

You can see if your user already has an embedded Farcaster signer authorized by checking if user.linkedAccounts.find((account) => account.type === 'farcaster').signerPublicKey is defined!

3. Create a cast

Now that your user has authorized their embedded Farcaster signer to write, you can begin submitting messages to the protocol!

Let's start with creating a cast.

const {submitCast} = useExperimentalFarcasterSigner();

Writing a basic message is as easy as:

const {hash} = await submitCast({text: 'Hello world!'});

INFO

All Farcaster write methods from useExperimentalFarcasterSigner return a "hash". This is the identifier of the message submitted to the protocol. You can use this value to take additional actions on a cast such as liking or recasting.

4. Interact with other Farcasters!

Alright, your user has created a new cast, but how do they interact with other people? Privy exposes several methods for this:

const {
  submitCast,
  removeCast,
  likeCast,
  recastCast,
  followUser,
  unfollowUser,
  requestFarcasterSigner,
} = useExperimentalFarcasterSigner();

First off, we need our user to follow people to display casts on their feed! Let's go ahead and follow Vitalik.

// Vitalik's Farcaster ID (FID) is 5650
const {hash} = await followUser({fid: 5650});

Next, let's like and recast some of his casts.

// Liking one of Vitalik's recent casts
// https://warpcast.com/vitalik.eth/0x3e9b3734
const {hash: likeMessageHash} = await likeCast({
  castHash: '0x3e9b3734a29ad341f1c73912c42343a21d5df75a',
  castAuthorFid: 5650,
});

// Recasting another one of Vitalik's recent casts
// https://warpcast.com/vitalik.eth/0x6be44f32
const {hash: recastMessageHash} = await recastCast({
  castHash: '0x6be44f32011a59e239d5a00bb6302c3105ad3214',
  castAuthorFid: 5650,
});

Awesome! We've already submitted, liked, and recasted a cast + followed a user.

Now, your user wants to shake up their feed their feed, so they are going to unfollow Vitalik.

const {hash} = await unfollowUser({fid: 5650});

That's it!

Your user has now logged in with Farcaster, authorized a new non-custodial signer, and started writing to the protocol. Wowow!

Experimental Caveats

Farcaster embedded signers is an experimental feature. For that reason, some Privy features cannot be used alongside Farcaster embedded signers.

1. A user must always have an embedded wallet to use Farcaster embedded signers. Before calling requestFarcasterSigner be sure to either manually or automatically create an embedded wallet.
2. MFA cannot be enabled when using Farcaster embedded signers.
3. Passwords on embedded wallets cannot be added when using Farcaster embedded signers.

Resources

If you're new to Farcaster, here are some great places to get started:

• https://docs.farcaster.xyz/
• https://www.thehubble.xyz/

Interacting with the Farcaster protocol requires reading existing data. The Farcaster team has a set of open source libraries for reading from hubs directly:

• https://github.com/farcasterxyz.

Alternatively, you can use data APIs built for Farcaster developers that drastically improve developer and user UX:

• Airstack
• Neynar
• Pinata

FAQ

Q: How do I revoke my embedded Farcaster signer?

A: If your account was created on Warpcast, you can go to Settings -> Advanced -> Manage connected apps. Then, delete the key you wish to revoke. Note that this will delete all messages posted by that signer. Revoking a signer without Warpcast is a somewhat involved process. Using your custody address (wallet from Warpcast), you can call remove(mySignerPublicKey) on the Farcaster Key Registry contract to permanently deauthorize an embedded Farcaster signer. Here is an example.

Q: Why can't I use this in production?

A: We are actively iterating on interfaces for Farcaster writes with Privy embedded signers. For that reason, interfaces will change rapidly and ed25519 key derivation may change. Technically, this is recoverable for your user, but it is not a trivial process and will lead to degraded UX. If you have any feedback on the interfaces so far, please let us know!

Q: I really like/dislike 'X'. How do I tell someone?

A: We would love ANY feedback on your experience so far! Please reach out to us on Warpcast or Slack.