FIP-10: Gateways

[varunsrin]

Title: Gateways
Type: Implementation FIP
Author: @horsefacts, @sanjayprabhu, @varunsrin

Abstract

Farcaster contracts are redeployed with improvements to read state from the blockchain. The main changes are:

• A gateway contract allows changing registration logic without future redeployments
• Registration of fids now requires renting one unit of storage
• Registration of keys is limited to 1,000 active keys
• Active keys and custody addresses can be read from contract mappings.

Problem

Farcaster contracts emit events which are consumed by downstream apps. Apps will create a database row when they see register on IdRegistry and add on KeyRegistry. Since OP Mainnet gas is cheap, malicious actors can spend < $100k to add millions of events. It’s possible to lazily ingest events, but this raises the barrier to creating new apps.

Event spam can be resolved by changing the logic around registration of identities and keys. But such changes requires a contract redeployment which is expensive and time consuming. We may run into such issues again, and it would be ideal to not have to redeploy the contract each time.

Specification

We propose separating contract methods into two categories:

• Registration methods — govern getting into to the system, (e.g. registering a new fid)
• Transfer methods — govern changing ownership (e.g. transferring an fid)

Registration methods can only be called via a gateway contract which can implement additional limitations. The contract is swappable and the rules can be changed by the admins.

Transfer methods must never implement a gateway and remain immutable for the life of the contract. Once someone registers an asset it cannot change hands without their permission. This ensures the system remains sufficiently decentralized.

We propose classifying IdRegistry’s register , registerFor and KeyRegistry’s add and addFor as registration methods, as shown below.

Id Gateway

The IdGateway implements register and registerFor and requires that a storage unit is rented for either. This prevents registration of “empty” fids but users are unaffected since an fid without storage cannot post anything to the network.

The IdGateway does not implement transfer methods — doing so would compromise decentralization. Even though transfer methods can be spammed, apps can ignore all but the latest transfer event for an fid which makes spam much more manageable.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.21;

import {IStorageRegistry} from "./IStorageRegistry.sol";
import {IIdRegistry} from "./IIdRegistry.sol";

interface IIdGateway {
    /*//////////////////////////////////////////////////////////////
                                 ERRORS
    //////////////////////////////////////////////////////////////*/

    /// @dev Revert if the caller does not have the authority to perform the action.
    error Unauthorized();

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

    /**
     * @dev Emit an event when the admin sets a new StorageRegistry address.
     *
     * @param oldStorageRegistry The previous StorageRegistry address.
     * @param newStorageRegistry The new StorageRegistry address.
     */
    event SetStorageRegistry(address oldStorageRegistry, address newStorageRegistry);

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

    /**
     * @notice Contract version specified in the Farcaster protocol version scheme.
     */
    function VERSION() external view returns (string memory);

    /**
     * @notice EIP-712 typehash for Register signatures.
     */
    function REGISTER_TYPEHASH() external view returns (bytes32);

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

    /**
     * @notice The IdRegistry contract
     */
    function idRegistry() external view returns (IIdRegistry);

    /**
     * @notice The StorageRegistry contract
     */
    function storageRegistry() external view returns (IStorageRegistry);

    /*//////////////////////////////////////////////////////////////
                             PRICE VIEW
    //////////////////////////////////////////////////////////////*/

    /**
     * @notice Calculate the total price to register, equal to 1 storage unit.
     *
     * @return Total price in wei.
     */
    function price() external view returns (uint256);

    /**
     * @notice Calculate the total price to register, including additional storage.
     *
     * @param extraStorage Number of additional storage units to rent.
     *
     * @return Total price in wei.
     */
    function price(uint256 extraStorage) external view returns (uint256);

    /*//////////////////////////////////////////////////////////////
                             REGISTRATION LOGIC
    //////////////////////////////////////////////////////////////*/

    /**
     * @notice Register a new Farcaster ID (fid) to the caller. The caller must not have an fid.
     *
     * @param recovery Address which can recover the fid. Set to zero to disable recovery.
     *
     * @return fid registered FID.
     */
    function register(address recovery) external payable returns (uint256 fid, uint256 overpayment);

    /**
     * @notice Register a new Farcaster ID (fid) to the caller and rent additional storage.
     *         The caller must not have an fid.
     *
     * @param recovery     Address which can recover the fid. Set to zero to disable recovery.
     * @param extraStorage Number of additional storage units to rent.
     *
     * @return fid registered FID.
     */
    function register(
        address recovery,
        uint256 extraStorage
    ) external payable returns (uint256 fid, uint256 overpayment);

    /**
     * @notice Register a new Farcaster ID (fid) to any address. A signed message from the address
     *         must be provided which approves both the to and the recovery. The address must not
     *         have an fid.
     *
     * @param to       Address which will own the fid.
     * @param recovery Address which can recover the fid. Set to zero to disable recovery.
     * @param deadline Expiration timestamp of the signature.
     * @param sig      EIP-712 Register signature signed by the to address.
     *
     * @return fid registered FID.
     */
    function registerFor(
        address to,
        address recovery,
        uint256 deadline,
        bytes calldata sig
    ) external payable returns (uint256 fid, uint256 overpayment);

    /**
     * @notice Register a new Farcaster ID (fid) to any address and rent additional storage.
     *         A signed message from the address must be provided which approves both the to
     *         and the recovery. The address must not have an fid.
     *
     * @param to           Address which will own the fid.
     * @param recovery     Address which can recover the fid. Set to zero to disable recovery.
     * @param deadline     Expiration timestamp of the signature.
     * @param sig          EIP-712 Register signature signed by the to address.
     * @param extraStorage Number of additional storage units to rent.
     *
     * @return fid registered FID.
     */
    function registerFor(
        address to,
        address recovery,
        uint256 deadline,
        bytes calldata sig,
        uint256 extraStorage
    ) external payable returns (uint256 fid, uint256 overpayment);

    /*//////////////////////////////////////////////////////////////
                         PERMISSIONED ACTIONS
    //////////////////////////////////////////////////////////////*/

    /**
     * @notice Set the StorageRegistry address. Only callable by owner.
     *
     * @param _storageRegistry The new StorageREgistry address.
     */
    function setStorageRegistry(address _storageRegistry) external;
}

Key Gateway

The KeyGateway implements add and addFor and limits the number of active keys to 1,000 per user. Users may remove older keys and add new keys once the limit is reached, and an admin can increase this limit in the future.

The gateway does not implement remove and removeFor methods. While it is possible to spam adding and removing keys, apps can ignore all but the latest event, which simplified this issue.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.21;

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

interface IKeyGateway {
    /*//////////////////////////////////////////////////////////////
                              CONSTANTS
    //////////////////////////////////////////////////////////////*/

    /**
     * @notice Contract version specified in the Farcaster protocol version scheme.
     */
    function VERSION() external view returns (string memory);

    /**
     * @notice EIP-712 typehash for Add signatures.
     */
    function ADD_TYPEHASH() external view returns (bytes32);

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

    /**
     * @notice The KeyRegistry contract.
     */
    function keyRegistry() external view returns (IKeyRegistry);

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

    /**
     * @notice Add a key associated with the caller's fid, setting the key state to ADDED.
     *
     * @param keyType      The key's numeric keyType.
     * @param key          Bytes of the key to add.
     * @param metadataType Metadata type ID.
     * @param metadata     Metadata about the key, which is not stored and only emitted in an event.
     */
    function add(uint32 keyType, bytes calldata key, uint8 metadataType, bytes calldata metadata) external;

    /**
     * @notice Add a key on behalf of another fid owner, setting the key state to ADDED.
     *         caller must supply a valid EIP-712 Add signature from the fid owner.
     *
     * @param fidOwner     The fid owner address.
     * @param keyType      The key's numeric keyType.
     * @param key          Bytes of the key to add.
     * @param metadataType Metadata type ID.
     * @param metadata     Metadata about the key, which is not stored and only emitted in an event.
     * @param deadline     Deadline after which the signature expires.
     * @param sig          EIP-712 Add signature generated by fid owner.
     */
    function addFor(
        address fidOwner,
        uint32 keyType,
        bytes calldata key,
        uint8 metadataType,
        bytes calldata metadata,
        uint256 deadline,
        bytes calldata sig
    ) external;
}

Freezing Gateways

Gateways can be frozen to prevent any further changes. This may be necessary if we want to ossify the rules around registration, preventing even admins from changing them again. Freezing is a one-way operation that cannot be undone.

function freezeIdGateway() external onlyOwner {
    /* Freeze the gateway */
}

Guardians

Pausable contracts use a “pause guardian” pattern that allows one or more “guardian” addresses to pause, but not unpause contracts. This enables us to further decentralize ownership of the core registry contracts, for example to a higher-threshold multisig, while allowing a set of trusted operators to react quickly and pause contracts in the event of an emergency.

// SPDX-License-Identifier: MIT
pragma solidity 0.8.21;

import {Ownable2Step} from "openzeppelin/contracts/access/Ownable2Step.sol";
import {Pausable} from "openzeppelin/contracts/security/Pausable.sol";

import {IGuardians} from "../interfaces/abstract/IGuardians.sol";

abstract contract Guardians is IGuardians, Ownable2Step, Pausable {
    /**
     * @notice Mapping of addresses to guardian status.
     */
    mapping(address guardian => bool isGuardian) public guardians;

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

    /**
     * @notice Allow only the owner or a guardian to call the
     *         protected function.
     */
    modifier onlyGuardian() {
        if (msg.sender != owner() && !guardians[msg.sender]) {
            revert OnlyGuardian();
        }
        _;
    }

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

    /**
     * @notice Set the initial owner address.
     *
     * @param _initialOwner Address of the contract owner.
     */
    constructor(address _initialOwner) {
        _transferOwnership(_initialOwner);
    }

    /*//////////////////////////////////////////////////////////////
                         PERMISSIONED FUNCTIONS
    //////////////////////////////////////////////////////////////*/

    /**
     * @inheritdoc IGuardians
     */
    function addGuardian(address guardian) external onlyOwner {
        guardians[guardian] = true;
        emit Add(guardian);
    }

    /**
     * @inheritdoc IGuardians
     */
    function removeGuardian(address guardian) external onlyOwner {
        guardians[guardian] = false;
        emit Remove(guardian);
    }

    /**
     * @inheritdoc IGuardians
     */
    function pause() external onlyGuardian {
        _pause();
    }

    /**
     * @inheritdoc IGuardians
     */
    function unpause() external onlyOwner {
        _unpause();
    }
}

Lookup Methods

The number of events will grow over time and become time consuming to sync. We propose adding lookups for common state by storing it in a mapping in each registry. This increases gas costs but makes it possible to determine state without iterating through historical events.

IdRegistry

Allow looking up the custody address for a given fid.

/* Maps each fid to the address that currently owns it. */
function custodyOf(uint256 fid) external view returns (address owner);

KeyRegistry

Allow looking up added and removed keys for an fid.

enum KeyState {
  NULL,
  ADDED,
  REMOVED
}

/* total number of keys associated with the fid for the given state. */
function totalKeys(uint256 fid, KeyState state) external view returns (uint256);

/* Return key at the given index in the fid's key set. Can be
   called to enumerate all keys for a given fid and state. */
function keyAt(uint256 fid, KeyState state, uint256 index) external view returns (bytes memory);

/* Return an array of all keys for a given fid and state. */
function keysOf(uint256 fid, KeyState state) external view returns (bytes[] memory);

/* Return an array of all keys for a given fid and state, in paged batches. */
function keysOf(uint256 fid, KeyState state, uint256 startIdx, uint256 batchSize) external view returns (bytes[] memory page, uint256 nextIdx);

Disclosure

This disclosure will be circulated privately to known app developers in the ecosystem, and shared publicly only 24 hours before the migration. All fids previously registered will be considered valid, since they were in accordance with the rules of the contract. But any fids registered maliciously after this disclosure is published will be considered in violation and will not be migrated to the new contract. The list of skipped fids (if any) and rationale will be added to this proposal.

Rationale

Is this change absolutely necessary?

We could just leave it to all app developers to handle the parsing of dead events, but believe that fixing it today is important because it significantly improves the developer experience.

Why was this not announced publicly earlier?

A malicious actor who discovered the issue via public disclosure could start spamming the contract, causing further pain for app developers and increase the costs and complexity of migrating the contracts.

Release

The contracts will be deployed to the following address:

Name           Address                                   
IdRegistry     0x00000000fc6c5f01fc30151999387bb99a9f489b
IdGateway      0x00000000fc25870c6ed6b6c7e41fb078b7656f69
KeyRegistry    0x00000000fc1237824fb747abde0ff18990e59b7e
KeyGateway     0x00000000fc56947c7e7183f8ca4b62398caadf0b
Bundler        0x00000000fc04c910a0b5fea33b03e0447ad0b0aa
RecoveryProxy  0x00000000fcb080a4d6c39a9354da9eb9bc104cd7

• Hub operators must migrate to v1.7.0 by 2023-11-06.
• Old contracts will be paused on 2023-11-07 at ~ 9am PT.
• New contracts will be deployed on 2023-11-07 and state will be copied over.
• New contracts will be opened for registration on 2023-11-07 at ~ 2pm PT.

These are best effort and there’s a good chance that it may be possible sooner or later. Please be prepared for delays up to 48 hours in case issues are run into during migration.

Appendix A: Developer Migration Guide

Contracts

The IdRegistry and KeyRegistry contracts are redeployed and all events emitted will be semantically identical to the old contracts. However, the actual timestamps and transaction ids that created the events will be different. In addition to this, interfaces have changed:

Managing Fids

• IdRegistry register , registerFor → IdGateway register , registerFor
• IdGateway Register signatures must use the new KeyGateway domain separator.
• One unit of storage must be rented as part of registration.
• Registration methods have an extraStorage param to rent more than one unit.
• All other operations like transferring and recovering remain on IdRegistry.
• changeRecoveryAddress — signature hash has changed to include both previous and new recovery address.

Renting Storage

• No change

Adding Keys

• KeyRegistry add, addFor → KeyGateway add , addFor
• KeyGateway Add signatures must use the new KeyGateway domain separator.
• No more than 1,000 keys may be active at a time.

Bundler

• Bundler register now accepts an extraStorage param which asks for the number of additional units you want to rent beyond 1. Previously this was the total number of units.
• Bundler price now accepts an extraStorage param.

Hubs

If you are using the latest Hubble, no change should be necessary.

The hub will cut over to the new version of the contracts automatically when the global network config is changed. At this point, hubs will start ingesting all historical events from the new contracts and emitting them as events.

Replicator

If you are using the latest replicator, no change should be necessary.

The new onchain contract events for IdRegistry and KeyRegistry emitted by hubs will be inserted into the chainEvents table. All foreign keys will be updated to point to these new events instead of the older ones. The older entries will not be automatically removed, though they are safe to remove after you’ve verified that everything is working as expected.

Signatures

Any unused off-chain signatures will be invalid, and need to be regenerated. Code generating typed signatures will need to be updated to use domain separators for the new contracts.