FIP-7: Onchain Signers

[varunsrin]

Onchain Signers

Title: Onchain Signers
Type: Implementation FIP
Authors: horsefacts, sanjay, v

Abstract

Signers should be set onchain on an L2 contract to avoid usability problems with CRDT consensus.

Problem

Signers are used to delegate permissions to post on a user's behalf without giving up control over the Farcaster identity. The Signer is a key pair whose public key is signed by the fid's custody address and stored on a hub. Signers are tracked using a CRDT which allows keys to be added and removed. There are a few usability problems in the current implementation:

1. The CRDT must have a limit on how many signers can be added. Crossing the limit causes the earliest signer to be removed (FIFO). A user adding a signer may accidentally erase data created by their first signer. LIFO rules would be ideal, but this isn't possible without reliable timestamps.

2. When an fid transfers custody addresses, the signature chain from address to fid to signer is broken. Hubs will discard unsigned messages after a short delay, unless the new address submits a signature, which could cause unintentional data loss.

There are mitigations to these problems — a compaction can solve (1) and an approach like multi-signatures can make (2) bearable. But these solutions come at the cost of storage and additional complexity, and do not solve the problem entirely.

Specification

We propose tracking signers onchain with a Key Registry which maps fids to signers. The registry is extensible so that we can change the kinds of keys we use for signers or add keys for other purposes like encryption.

When a key is added, the KeyRegistry checks the IdRegistry and assigns the keys to the caller's fid. Mapping keys to the fid instead of the custody address solves (2) by maintaining the relationship when the fid is transferred. Storing keys onchain lets hubs avoid limits since the blockchain implements its own fee system, avoiding (1).

Four inputs are needed to register a new key pair to a caller:

1. key - the public key material
2. keyType- the type of key material provided
3. metadata - additional information about the key request
4. metadataType - the type of metadata being provided

Keys are stateful and exist in the states null, added or removed. The owner may add and remove keys at any time, but removed keys can never be re-added. The same key can be added by other fids and may exist in different states across fids. A sample implementation of the Key Registry can be seen in Appendix A.

Validation

The Key Registry must validate the key and metadata by calling a validation contract which returns a boolean. Each tuple of (keyType, metadataType) encodes validation rules in a contract registered with the Key Registry. Each validation contract must have a validate method that requires:

1. fid - the fid of the user registering the key
2. key - the public key material
3. metadata - information about the request

The owner can add and update the validation contracts at any time. A sample interface for the validator can be seen in Appendix B.

Key Types

1. Ed25519

A valid public key on Curve25519 used to sign Farcaster messages on behalf of an fid. The key is not validated onchain but is validated by Farcaster Hubs.

Metadata Types

1. Signed Key Request

A signature that proves that an fid (requesting fid) asked another fid (primary fid) to authorize a key pair. For example, if an app asks a user for a key it would sign a message proving that it made the ask. This lets us attribute signers to specific entities which is useful for a wide range of things from knowing which apps are being used to filtering content based on the applications that generated them. This type-specific metadata must be an ABI-encoded struct with the following format:

struct SignedKeyRequest {
    uint256 requestingFid;
    address requestSigner;
    bytes signature;
}

Where requestingFid is the fid requesting the key, requestSigner is the owner of requestingFid, and signature is an EIP-712 signature with the following format:

SignedKeyRequest(uint256 userFid,uint256 requestingFid,bytes signerPubKey)

Hub Changes

Hubs must implement KeyRegistrySignerStore which tracks currently active keys for each fid. When the KeyRegistry emits an event for a key where keyType ==1 and metadataType == 1, it is added or removed from the store. The existing SignerStore CRDT to track SignerAdd/SignerRemove messages is deprecated. The Hubs also expose APIs for this new functionality and deprecate unused APIs which are described in Appendix C. The exact process for transitioning from SignerStore to KeyRegistrySignerStore is described in Release.

The General Rules for CRDTs are simplified to:

1. Messages must have an Ed25519 signature scheme.
2. Messages must be signed by a Signer for the message's fid tracked by the KeyRegistrySignerStore.

Changes in the KeyRegistry may cause a Signer to be removed for an fid, which should revoke all messages created by that signer for that fid.

Rationale

Will the additional cost deter users from adding applications?

It will likely cost between $.1 and $1 to add a signer at today’s L2 gas prices, though we expect that to reduce over time. Wallet clients like Warpcast can simplify the user experience by allowing payments to be made via fiat methods or L1. They can reduce the friction to add signers by charging a flat “signup fee” which covers the cost of signers being added later.

Why can’t users re-add the same signer?

The only use case for this is re-adding an accidentally deleted signer. In such cases, its more secure to issue a new signer and re-sign the messages. Disallowing signer reuse also simplifies sync logic for Hubs.

Why is the smart contract not upgradeable?

An upgradeable contract would allow changing logic without having to re-initialize the contract. However, it reduces trust since an administrator can upgrade the contract, change the logic, add keys to a user and forge messages under their identity.

Why can’t a signer be revoked without deleting the messages created by it?

A user revoking a signer typically expects that the owner of the signer can no longer create messages. However, this won’t be true since new messages created with an incorrect, older timestamp before the revocation will be accepted. Allowing this will lead to confusion, and its preferable to create a new signer and resign messages if they need to be preserved.

Why not have counterfactual signers that exist off-chain and on-chain?

A counterfactual system is possible but at the cost of significant complexity. The likely outcome in such a case is that wallets and apps will design their experiences around the off-chain signers, resulting in all the same problems that we face today.

Release

1. The Key Registry is deployed to the L2 on 0x00000000fc9e66f1c6d86d750b4af47ff0cc343d.
2. Hubs listen for events emitted by this contract and track signers in a SmartContractSignerStore
3. During the broader L2 migration, the Key Registry is seeded with all known Signers from the Hubs.
4. Once complete, a migration timestamp is set onchain after which Hubs will reject offchain Signers produced with a timestamp ≥ the migration timestamp.
5. An administrator can add or remove signers to this contract for 24 hours, used to clean up any inconsistencies that have arisen.
6. Another release of the Hubs will deprecate the Signer CRDT and all offchain Signer messages.

Appendix A: Key Registry

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.19;

import {IdRegistry} from "./IdRegistry.sol";

contract KeyRegistry is Ownable2Step {
    /**
     *  @notice State enumeration for a key in the registry. During migration, an admin can change
     *          the state of any fids key from NULL to ADDED or ADDED to NULL. After migration, an
     *          fid can change the state of a key from NULL to ADDED or ADDED to REMOVED only.
     *
     *          - NULL: The key is not in the registry.
     *          - ADDED: The key has been added to the registry.
     *          - REMOVED: The key was added to the registry, but is now removed.
     */
    enum KeyState {
        NULL,
        ADDED,
        REMOVED
    }

    /**
     *  @notice Data about a key.
     *
     *  @param state   The current state of the key.
     *  @param scheme  The manner in which the key should be used.
     */
    struct KeyData {
        KeyState state;
        uint200 scheme;
    }

    /*//////////////////////////////////////////////////////////////
                                 ERRORS
    //////////////////////////////////////////////////////////////*/

    /// @dev Revert if a key violates KeyState transition rules.
    error InvalidState();

    /*//////////////////////////////////////////////////////////////
                                 EVENTS
    //////////////////////////////////////////////////////////////*/

    /**
     * @dev Emit an event when an admin or fid adds a new key.
     *
     * @param fid       The fid associated with the key.
     * @param scheme    The type of the key.
     * @param key       The key being registered. (indexed as hash)
     * @param keyBytes  The bytes of the key being registered.
     * @param metadata  Metadata about the key.
     */
    event Add(uint256 indexed fid, bytes indexed key, bytes keyBytes, uint200 indexed scheme, bytes metadata);

    /**
     * @dev Emit an event when an fid removes an added key.
     *
     * @param fid       The fid associated with the key.
     * @param key       The key being registered. (indexed as hash)
     * @param keyBytes  The bytes of the key being registered.
     */
    event Remove(uint256 indexed fid, bytes indexed key, bytes keyBytes);

    /**
     * @dev Emit an event when the admin sets a metadata validator contract for a given
     *      scheme and typeId.
     *
     * @param scheme       The key scheme associated with this validator.
     * @param typeId       The metadata typeId associated with this validator.
     * @param oldValidator The previous validator contract address.
     * @param newValidator The new validator contract address.
     */
    event SetValidator(uint32 scheme, uint8 typeId, address oldValidator, address newValidator);

    /*//////////////////////////////////////////////////////////////
                              CONSTANTS
    //////////////////////////////////////////////////////////////*/

    /**
     * @dev Period in seconds after migration during which admin can bulk add/reset keys.
     *      Admins can make corrections to the migrated data during the grace period if necessary,
     *      but cannot make changes after it expires.
     */
    uint24 public immutable gracePeriod;

    /*//////////////////////////////////////////////////////////////
                                STORAGE
    //////////////////////////////////////////////////////////////*/

    /**
     * @dev The IdRegistry contract.
     */
    IdRegistry public immutable idRegistry;

    /**
     * @dev Timestamp at which keys migrated. Hubs will cut over to use this key registry as their
     *      source of truth after this timestamp.
     */
    uint40 public keysMigratedAt;

    /**
     * @dev Mapping of fid to a key to the key's metadata.
     *
     * @custom:param fid       The fid associated with the key.
     * @custom:param key       Bytes of the key.
     * @custom:param data      Struct with the state and key type.
     */
    mapping(uint256 fid => mapping(bytes key => KeyData data)) public keys;
    
    /**
     * @dev Mapping of scheme to metadata typeId to validator contract.
     *
     * @custom:param scheme    Numeric key scheme.
     * @custom:param typeId    Metadata typeId.
     * @custom:param validator Validator contract implementing IMetadataValidator.
     */
    mapping(uint32 scheme => mapping(uint8 typeId => IMetadataValidator validator)) public validators;



    /*//////////////////////////////////////////////////////////////
                               CONSTRUCTOR
    //////////////////////////////////////////////////////////////*/

    /**
     * @notice Set the IdRegistry, migration grace period, and owner.
     *
     * @param _idRegistry  IdRegistry contract address. Immutable.
     * @param _gracePeriod Migration grace period in seconds. Immutable.
     * @param _owner       Contract owner address.
     */
    constructor(address _idRegistry, uint24 _gracePeriod, address _owner) {
        _transferOwnership(_owner);

        gracePeriod = _gracePeriod;
        idRegistry = IdRegistry(_idRegistry);
    }

    /*//////////////////////////////////////////////////////////////
                                MODIFIERS
    //////////////////////////////////////////////////////////////*/

    /**
     * @notice Revert if caller does not own the associated fid.
     */
    modifier onlyFidOwner(uint256 fid) {
        if (idRegistry.idOf(msg.sender) != fid) revert Unauthorized();
        _;
    }

    /*//////////////////////////////////////////////////////////////
                                  VIEWS
    //////////////////////////////////////////////////////////////*/

    /**
     * @notice Retrieve state and type data for a given key.
     *
     * @param fid   The fid associated with the key.
     * @param key   Bytes of the key.
     *
     * @return KeyData struct that contains the state and scheme.
     */
    function keyDataOf(uint256 fid, bytes calldata key) external view returns (KeyData memory) {
        return keys[fid][key];
    }

    /*//////////////////////////////////////////////////////////////
                              REGISTRATION
    //////////////////////////////////////////////////////////////*/

    /**
     * @notice Add a key to an fid, setting the key state to ADDED.
     *
     * @param fid      The fid associated with the key. Caller must own the fid.
     * @param scheme   The key's numeric scheme.
     * @param key      Bytes of the key to add.
     * @param metadata Metadata about the key, which is not stored and only emitted in an event.
     */
    function add(uint256 fid, uint200 scheme, bytes calldata key, bytes calldata metadata) external onlyFidOwner(fid) {
        _add(fid, scheme, key, metadata); // calls the validator
    }

    /**
     * @notice Remove a key associated with an fid, setting the key state to REMOVED.
     *         The key must be in the ADDED state.
     *
     * @param fid   The fid associated with the key. Caller must own the fid.
     * @param key   Bytes of the key to remove.
     */
    function remove(uint256 fid, bytes calldata key) external onlyFidOwner(fid) {
        _remove(fid, scheme, key, metadata);

    }
}

Appendix B: Validator

interface IMetadataValidator {
    function validate(uint256 userFid, bytes memory signerKey, bytes memory metadata) external returns (bool);
}

Appendix C: Hub API Changes

The following APIs calls will be added:

message OnChainEventResponse {
  repeated OnChainEvent events = 1;
}

enum OnChainEventType {
  EVENT_TYPE_NONE = 0;
  EVENT_TYPE_SIGNER = 1;
  EVENT_TYPE_SIGNER_MIGRATED = 2;
  EVENT_TYPE_ID_REGISTER = 3;
  EVENT_TYPE_STORAGE_RENT = 4;
}

message OnChainEvent {
  OnChainEventType type = 1;
  uint32 chain_id = 2;
  uint32 block_number = 3;
  bytes block_hash = 4;
  uint64 block_timestamp = 5;
  bytes transaction_hash = 6;
  uint32 log_index = 7;
  uint64 fid = 8;
  oneof body {
    SignerEventBody signer_event_body = 9;
    SignerMigratedEventBody signer_migrated_event_body = 10;
    IdRegisterEventBody id_register_event_body = 11;
    StorageRentEventBody storage_rent_event_body = 12;
  }
}

message SignerEventBody {
  bytes key = 1;
  uint32 scheme = 2;
  SignerEventType event_type = 3;
  bytes metadata = 4;
}


rpc GetOnChainSigner(SignerRequest) returns (OnChainEvent);      
rpc GetOnChainSignersByFid(FidRequest) returns (OnChainEvent);  // Returns only active signers
rpc GetOnChainEvents(OnChainEventRequest) returns (OnChainEventResponse);  // Can be used to get all on chain events (e.g. including signer removal events)

The following API calls will be deprecated:

rpc GetSigner(SignerRequest) returns (Message);
rpc GetSignersByFid(FidRequest) returns (MessagesResponse);
rpc GetAllSignerMessagesByFid(FidRequest) returns (MessagesResponse);

// submitMessage will no longer accept SignerAdd or SignerRemove, which will be deprecated

[TimDaub]

Still processing this. Anyways, I had independently worked on something like this which is probably more gas efficient considering storage writes. But dunno what constraints you‘re optimizing for so your‘s probably fits FC architecture a bit better. Anyways, here‘s what I‘m looking to implement with Kiwi

https://github.com/attestate/delegator2#readme

Biggest drawback I see with mine: A relayer cannot easily send the TX for a user
Biggest drawback from FC ecosystem PoV: My thing works with Ethereum addresses as IDs

[TimDaub]

Are you preventing bots from front running and hence DoS‘ing or stealing signers?
E.g. in the delegator2 the ‚address to‘ signs an EIP-712 struct (address from, bool true|false) so that while a front runner can steal this payload, they wouldn‘t gain anything from it has delegator2 indexers would only consider a struct (address from, boom true) valid if „from“ on that transaction‘s receipt is the same as the struct‘s ‚address from‘.

[TimDaub]

Say I run an MEV bot that can front run

• You submit key_v to the mem pool by calling add
• I see it and because I want to annoy you, I also call add with my throw-away fid but your key_v. I‘ll make sure my tx gets in the block before you
• ???

[varunsrin]

my transaction will still go through. the keys are not unique per address.

[varunsrin]

there's a draft PR here if you want to dig into the logic: farcasterxyz/contracts#257

[TimDaub]

that‘s fine if the tx goes through (same as in the attestate/delegator v1 design), but as FC hubble node, which transaction sender do you now consider the real originator of the signer add request? Hence in delegator2 we generate the signer add key through ecrecover of a signature

say

keys[fid_v][key_v].state = ADDED

but also

keys[fid_tim][key_v] = ADDED

and now you encounter cast with signature_v

as a hubble node, how can you tell if either fid_v or fid_tim wrote it, considering you‘re not witnessing the front running in the mem pool?

[varunsrin]

The cast includes an fid, so it clearly claims to belong to a certain fid.

If fid_v and fid_tim both have the private key to key_v and both chose to add key_v to their fids KeyRegistry, then they're explicitly choosing to share permissions to write with each other.

[musnit]

There exist solutions to these problems — a compaction strategy that examines signers can solve (1) and an approach like multi-signatures can mitigate (2). But these solutions come at the cost of storage and complexity, and do not eliminate the problem entirely.

Can you elaborate what you mean by a compaction strategy and cost/complexity? Is the complexity that bad?

A LIFO-like rule and reliable ordering could possibly be created as follows, similar to how it's done in Secure Scuttlebutt:

• All signer messages are arranged in a keychain, ie, each new signer-related message includes a pointer to the previous message and so all messages link together into an append-only keychain. Messages are now relatively-ordered due to their pointers.
• Entire Keychains can be erased, or just their suffixes can be sliced off by submitting an onchain message from any valid signer in the prefix of the slice. The message should includes a specific link in the chain to slice off, effectively removing keys from the end of the chain and achieving LIFO-like behavior.
• Forks cause invalidation of all signers on all suffix branches after the fork. The user must go onchain to slice off forks to get their keychain back in order

With regards to UX, I think it comes down to building for what is likely to happen most often, ie, will new signers need to be created more often, or will forks and errors occur more often? Especially if this is all happening just from a Custody Wallet app, most likely for 95% of users a high quality, trusted wallet app, imo it's the former.

Use the blockchain to protect in times of chaos & war without it constraining in times of co-ordination & peace 😝?

[varunsrin]

Good feedback, and we've explored similar designs in the past. Farcaster v1 had a hash-chain design, but we decided against using them in v2 because of the problems it introduced.

Consider the case where a user has a signer chain S, and adds a new tip S(t1) using a Hub. The request fails and the user tries again later with a different Hub, but didn't preserve the key so adds another tip S(t2). Now the original Hub comes back online and still has S(t1). This creates a situation where one of these must be dropped which might create data loss.

You could resolve such conflicts on chain, but a) these conflicts are surprisingly common and b) they add a ton of non-encapsulated complexity to the system. Now the Hubs must keep track of the state of off-chain and on-chain systems and reconcile them, and deal with conflicts that arise between these systems. Users and developers must also be aware of whether the true state of their chain resides on-chain or offchain. Put another way, a lot of this complexity starts leaking into the user and developer domain and makes the system much harder to use correctly.

While payment always adds friction, I think the system as a whole is better off if we have to pay ~50c to register a signer and avoid a lot of this complexity. Especially as that cost will decrease over time.

[varunsrin]

Especially if this is all happening just from a Custody Wallet app, most likely for 95% of users a high quality, trusted wallet app, imo it's the former.

I was surprised at how often this doesn't hold true in practice. People have done all kinds of weird things, and if the failure is painful (i.e. involves data loss) they're very likely to leave and never come back.

[musnit]

Makes sense. I think the design can only work really well in practice if this conflict-resolution is super cleanly abstracted such that it's fairly easy for hubs, third party developers, client developers and their clients to all take ownership of conflict resolution and be developed with an offline-first, recovery-centric p2p mentality. This ofc is complex to achieve and unless perfected, does add a lot of overhead, especially for newer third party developers.

[varunsrin]

They’re both valid , but only one of them has the private key and can produce signed messages with it

…

On Sun, Jul 9, 2023 at 11:59 AM Tim Daubenschütz ***@***.***> wrote: that‘s fine if the tx goes through (same as in the attestate/delegator v1 design), but as FC hubble node, which transaction sender do you now consider the real originator of the signer add request? Hence in delegator2 we generate the signer add key through ecrecover — Reply to this email directly, view it on GitHub <#103 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAEBD4XGSOAG3XQ4XQFBNGDXPL5Q5ANCNFSM6AAAAAA2DIU4SQ> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[TimDaub]

do all user signed messages always include the fid and is it signed too? Because otherwise, I think as hubble you couldn‘t tell which user name to assign to a message where the ecrecovered address is key_v. You could chose both @v and @TimDaub and wouldn‘t have a way of telling who of us genuinely added their delegation key and who just front ran the other in an attempt of griefing or impersonation

edit: seems to be included at least in casts: https://github.com/farcasterxyz/hub-monorepo/blob/2bfcaf4ec3d00a424757847144ad065943861eb3/packages/core/src/protobufs/generated/message.ts#L344

[Hmac512]

Typically this is done to give an application the ability to post for a user, without giving it control over the users identity. Users authorize a keypair as a signer by creating a SignerAdd message, which is tracked using a CRDT in the Hub.

This is a great example of where BLS keys/signatures can be useful. With pairing based curves, you can do delegated/signatures. So one BLS keys authorizes another BLS key to sign messages on it's behalf.

Using proxy signatures, you don't have to add a signer if a fid wants to let an application sign on it's behalf.

An article that mentions proxy signatures: https://medium.com/harmony-one/exploring-bls-keys-on-the-harmony-protocol-understanding-generation-management-and-use-cases-b8722f7219fc

Here is an interesting article on Forward secure signatures using pairing based crypto: https://www.sciencedirect.com/science/article/abs/pii/S0020025517300403

Forward secure signatures address the issue of backdating a signature before a key was revoked.

https://medium.com/cryptoadvance/bls-signatures-better-than-schnorr-5a7fe30ea716

Adding/Revoking a key through a smart contract call that costs a fee will pose problems in gaining adoption. A cryptographic accumulator can be used to reduce the amount of on-chain calls: https://github.com/Hmac512/accumulator/blob/main/test/accumulator/ecc/main.go

It will require some system design changes to support. Cryptographic accumulators are the basis of Verkle trees.

[Hmac512]

Found this paper that talks about how to revoke proxy signing with identity based signatures.

https://ink.library.smu.edu.sg/cgi/viewcontent.cgi?article=6209&context=sis_research

[varunsrin]

discussed offline with @Hmac512

conclusion is that we still need a key registry to map custody addresses to bls signatures in a highly consistent manner, at least for now. the path forward is to ship with EdDSA keys but leave the road open for a future FIP to propose a new key type which would allow implementation of BLS on top of this.

[Hmac512]

Given the spec handles different key types, it is quite extensible.

I am curious how you expect the standardization process for adding new key will work, because:

1. Hubs will need to update to add new sig verification logic
2. Clients will need to update to add new signing logic

A new key type can't be added unless the hubs agree to support verifying the sigs.

What if a separate farcaster-signatures repo was setup that was a separate npm package that the hubs and clients used. Later it can be split up into different languages (question of mono repo of all languages or separate repos for each).

So the hub-monorepo would just have to regularly update that dependency.

For each key type a HubSignatureTests class can be exposed that are added to the hubs unit-tests dynamically.

[varunsrin]

the new design that @horsefacts proposed in #107 addresses this

[varunsrin]

we merged this design into this spec, and the general process to add a new key type will require an FIP that defines the new validation contract, and change to hub logic.