How do Farcaster Signers work?

You do not need to know how Hubs work or what Farcaster is to understand how Signers work. Start reading and in case you have advanced knowledge, jump directly to topics of interest.

What is a Signer?

A signer is like a special pen, that when you sign marks the document as signed by the one that owns the pen. Since you never give posession of the pen to anyone, we know it was you. No one is able to copy or change the signature of your special pen, without us being able to notice that it doesn’t come from your pen anymore.

So Signers are special pens, that we can use to attest that it is really us.

In Farcaster land we sign messages, like in the middle ages they signed letters and sent them off in envelopes. Only if the letter was signed by the king, people needed to respect it. Because of the special pen, we will know if it’s really signed by the king or not. The only risk left is that the kings pen was stolen.

In our digital age, we use cryptographic keys as the special pens in cryptographic signatures. We call a signer the key that is used for these signatures. In our example the special pen is the signer.

Why do we need Signers?

In a decentralized network we do not have a central instance that says “yes this is Samuel”, we need a way of proving it to each and everyone. Just imagine if someone posted in your name and it would show up, that shouldn’t happen right? but how do we know the post is really yours? If we require you to sign each post with your special pen, the signer, we know.

Only the one with the signer is able to post, because we will verify the signature before accepting your post (this happens on Hubs).

Think back of the king, that needs to sign all letters because of his authority. You are the king (or queen)! You own your profile, your account (your FID).

That is why we need you to prove everytime the authority to act as that profile, account (FID).

And this is why we need signers, they enable us to look up if any given special pen (signer) is associated with your account (FID) and if it is we know it is really you.

In the end we always know that everything happening comes authentically from each user (programmtic users like bots are users in this case too) or was authorized by them.

How are Signers added?

Initially when you create your account the client you use (if you don’t interact with the onchain programs directly) creates the key pair (your special pen) and uses that to register the account. This key pair (special pen) is now called your custody address and added as such. It is how we recognize you king or queen acting on Farcaster. If it’s not signed by that, we think it isn’t you.

Unless after registration at any point you add a signer. (Technically these are delegated signers, because you delegate some of your power, but people shorten it to just “signers”)

Here’s the flow of sign up and using custody address to add signers visualized.

Be aware that you can add a signer for yourself too! That may be the case if you are working on a bot and want to use the signer yourself, as a developer it may not always be another app, but your own app as well ;)

Only the custody address can be used to add signers!

What permissions do Signers have?

Since a signer identifies that it is really you, it can mostly do everything you should be able to do right?

Though not every signer can do everything. What? yes there is one pen, we expect to be only owned by you and not given out to other applications that you may want to use to post or similar.

This is your “custody address”. It is what is registered to be your master pen, the master key. In case you signed in with Warpcast, then it is managed for you by the client. In most cases this is true, the client you sign up with holds your custody address and registered your Farcaster account for you.

Why is this important?

Signers vs the Custody Address

The root of trust in Farcaster is your custody address.

Another signer can’t add a signer to your account. To add a signer we need to use the custody address.

To remove a signer it can be revoked by itself, an ancestor in its chain of trust, or by the custody address.

It is therefore really important to keep your custody address safe and not share it around.

By default the custody address is also used to recover your account in case you somehow lose control.

The custody address can do anything a signer can and more. More being adding/revoking signers and setting the recovery address for your whole account.

But what can any signer - be it a custody address or not - do?

Farcaster Signer Permissions

General rule is a signer (that isn’t the custody address) can do anything you can do purely on hubs. That means they can’t delete your account and can’t add new signers.

Where are Signers stored?

Signers are stored on the Optimism Blockchain in the Key Registry Smart Contracts. Remember Smart Contract means program that lives on the blockchain, nothing more.

Farcaster Hubs only synchronize that data from the blockchain and check that any message has a valid signature from one of the signers registered onchain.

The management of signers happens onchain. Meaning you can not interact with a Hub to change signer data, you need to do onchain transactions. These then synchronize to Hubs.

How are Signers managed?

A signer can be anything that creates EdDSA signatures on Curve25519. Usually this is an Ed255191 key pair.

These private keys (think special pen of our initial example) are then managed by who ever operates the signer.

That may be your client you use to post and consume Farcaster content (e.g. Warpcast) or an API provider, yourself if you program or use local first software or something else. In the end it’s important to make sure these private keys used as signers are secure and not exposed publicly.

The registry - what key pair is valid to act as signer for your account (FID) - lives on the blockchain.

It is called the Key Gateway and Key Registry.

Any valid signer (custody address or delegated signer) needs to be registered here, since all signer management is stored onchain.

Remember how signers are stored

What happens when I want to remove a signer/permissions?

If you want to remove a signer, you use a signature from your custody address and tell the Key Registry to remove the signer (via onchain transaction). You prove that it is really you authorizing the removal by the custody address signature.

Now what happens? We revoked a signer.

There are multiple things going on now:

• the signer can’t be used to act in your account (FID)‘s name anymore
• all signatures from the signer are deleted from hubs
• that specific signer can’t be added to your FID via Key Registry anymore

The cascade affect of that signer key being revoked is that in case the messages sent using it are not signed by another signer (rarely the case), these messages get deleted from hubs.

Say you’re using this new fancy Farcaster client and post from it, if you revoke that signer without having another signer sign the messages of the posts, they will be deleted.

Example: Signer A and Signer B valid for FID 1

• Signer A signs “Post “hello world” from FID 1”
• Signer A gets revoked
• cState

What happens at cState? the post “hello world” from FID 1 will be deleted from Hubs and not visible anymore.

Now take Signer B, we do the same from the new fancy client we gave Signer A to, but now we use Signer B to resign that post, but not the welcome post from the client.

• Signer A signs “Post “hello world” from FID 1”
• Signer A signs “Post “dtech.vision is the best, welcome to this fancy client” from FID 1
• Signer B also signs the message from Signer A saying “Post “hello world” from FID 1”
• Signer A gets revoked
• cState

What happens at cState now? The post “hello world” from FID 1 will stay since it still has a valid signer, namely signer B.

Though the second post from Signer A will be deleted, since no valid signer signed it. No valid signer since Signer A is now no longer valid.

This is not only for posting to the network (“casts”) but also for likes, follows and anything else that signer does no Hubs.