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 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!

0. Install beta version of @privy-io/react-auth

In order to use embedded signers, you need to first install a public beta version of our sdk.

npm install @privy-io/[email protected]

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 from a user's existing Warpcast account.

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

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

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

<button
  onClick={() => requestFarcasterSignerFromWarpcast()}
  // 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 from Warpcast
</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 an external signer

In order to interface with Farcaster libraries, we need to build a simple signer object. This can easily be constructed using the Privy Farcaster signer interfaces.

This step requires that you install @standard-crypto/farcaster-js.

First, define an ExternalEd25519Signer:

import {ExternalEd25519Signer} from '@standard-crypto/farcaster-js';

const {getFarcasterSignerPublicKey, signFarcasterMessage} = useExperimentalFarcasterSigner();

const privySigner = new ExternalEd25519Signer(getFarcasterSignerPublicKey, signMessageHash);

4. Building the hub client

Now that we have a signer object built, we can build our @standard-crypto/farcaster-js client for interacting with Farcaster!

import {HubRestAPIClient} from '@standard-crypto/farcaster-js';

const client = new HubRestAPIClient({
  hubUrl: 'https://hub.farcaster.standardcrypto.vc:2281',
});

5. Interact with other Farcasters!

Now that you have a client initialized, you can now begin submitting messages to the protocol!

Luckily, farcaster-js makes submitting a cast as easy as:

const submitCastResponse = await client.submitCast(
  {text: 'Hello world!'},
  user.farcaster.fid,
  privySigner,
);

6. Interact with other Farcasters!

Alright, your user has created a new cast, but how do they interact with other people?

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 followUserResponse = await client.followUser(5650, user.farcaster.fid, privySigner);

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

// Liking one of Vitalik's recent casts
// https://warpcast.com/vitalik.eth/0x3e9b3734
const submitLikeResponse = await client.submitReaction(
  {
    type: 'like',
    target: {
      fid: 5650,
      hash: '0x3e9b3734a29ad341f1c73912c42343a21d5df75a',
    },
  },
  user.farcaster.fid,
  privySigner,
);

// Recasting another one of Vitalik's recent casts
// https://warpcast.com/vitalik.eth/0x6be44f32
const submitRecastResponse = await client.submitReaction(
  {
    type: 'recast',
    target: {
      fid: 5650,
      hash: '0x6be44f32011a59e239d5a00bb6302c3105ad3214',
    },
  },
  user.farcaster.fid,
  privySigner,
);

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

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

const unfollowUserResponse = await client.unfollowUser(5650, user.farcaster.fid, privySigner);

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 requestFarcasterSignerFromWarpcast 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.