Hero Image by Thomas G. from Pixabay

Farcaster - Get Connected Apps Keys

Note: The source code can be found here

Farcaster is a protocol for building decentralized social networks.

One of the key ideas in the design of the protocol is that the client applications that, usually, offer a UI for the user to interact with the network, they have to have been registered in the network. The registration is done by the user themselves.

For example, one of the most popular client applications is Wrapcast. So, if you want to create an account into Farcaster network, you can use Wrapcast. If you link the Wrapcast mobile app and the Wrapcast desktop app, then you will have registered two applications in Farcaster into your Farcaster ID (i.e. Farcaster account).

Key Registry

Farcaster links your Farcaster ID to the applications that you have registered and stores this association on chain (on Optimism), in the state of the KeyRegistry Contract.

Farcaster Application Registration

The address of the KeyRegistry contract is published in Farcaster documentation here.

App Keys

Each connected app is registered using a key. The objective of this exercise is to use some JavaScript programming to get the keys of the connected apps of a Farcaster ID.

Farcaster ID

The Farcaster ID is not the public username. It is an integer number.

Get Farcaster ID

Given a username (like for example panosm), we can get the Farcaster ID corresponding to this name using a public endpoint like this:

$ curl -v -X GET 'https://fnames.farcaster.xyz/transfers/current?name=panosm' | jq
...

which will return a response like this:

{
  "transfer": {
    "id": 360288,
    "timestamp": 1715836407,
    "username": "panosm",
    "owner": "0x37ce...8b2",
    "from": 0,
    "to": 539381,
    "user_signature": "0x2b0a...4d1b",
    "server_signature": "0x9a47...901b"
  }
}

Look at the value of to: It is 539381 in this case. That's the Farcaster ID.

Function `totalKeys`

The Farcaster ID is given as input to many of the functions of the KeyRegistry contract.

For example, you can use the totalKeys() to get the number of applications connected to a given Farcaster ID.

function totalKeys(uint256 fid, KeyState state) public view virtual returns (uint256) {...}

Function `keysOf`

Another example of a function that takes as input the Farcaster ID is the keysOf:

function keysOf(uint256 fid, KeyState state) external view returns (bytes[] memory) {...}

This returns the keys of the apps connected to the given Farcaster ID. It takes as input the state of the connection between the app and the Farcaster ID one wants to filter with. So, if you give 1 as the state argument, then you get the app keys which are ADDED, i.e. they are currently connected. If you give 2, then you get the app keys which are REMOVED, i.e. they are currently not connected.

Use JavaScript To Get The Connected Apps

Here are the steps I followed to get the connected apps of my Farcaster account.

Node.js Project

I created a new Node.js project with yarn init.

Add Hardhat Dependency

I then added the Hardhat dependency:

$ yarn add --dev hardhat

Initialize a Hardhat Typescript Project

Then I use Hardhat utilities to initialize the project as a hardhat Typescript project.

$ npx hardhat init
...

Set Up Optimism Network

Then I set up Hardhat configuration to be able to connect to Optimism network via Alchemy.

Here is my configuration

You can follow the instructions here on how to set up the Hardhat configuration variables. I am using environment variables technique. I save the vars values inside the file .envrc which is loaded as part of the environment with the help of direnv.

Note that the ACCOUNT_PRIVATE_KEY needs to have been set to hold the private key of the account that you have used to set up your Farcaster ID.

`KeyRegistry` Contract

In order to interact with the KeyRegistry contract and since we don't have its source code inside our repository, one thing that we can do is to import is ABI (Application Binary Interface).

So, I take the ABI from the public contract information in Optimism Etherscan:

KeyRegistry Contract ABI

This is a json document which I save in a new file called abis/KeyRegistry.sol/KeyRegistry.json.

Get App Keys Script

Now I am ready to write the script to get my Farcaster ID connected app keys.

I create the file scripts/main.ts with the following content:

Some notes about it:

lines 10-11: We hard code the public KeyRegistry contract address.
line 20: We use a function to load the ABI of the contract. See below about the implementation of this function.
line 22: We use ethers.getSigners() to get the first signer which is linked to the account we have registered inside the Hardhat configuration for the Optimism network.
lines 26-30: We instantiate the KeyRegistry contract. We will use the instance in order to call functions on the contract.
line 32: We have the Farcaster ID set to the value for the Farcaster ID we are interested in. See earlier about this.
line 34: We call the totalKeys() to get the total number of app keys.
line 34: We get the list of keys, using the keysOf() contract function.
line 39-41: We print the keys for each one of the apps connected to the given Farcaster ID.

That's it!

Closing Note

We used one of the Farcaster smart contracts to interact with the protocol. Farcaster has some more contracts you can interact with. Also, it stores a lot of information off-chain and exposed an API that allows you to interact with the off-chain storage too.