FarcasterAttestation / farcasterattestation-monorepo

Farcaster Attestation is a set of smart contracts that bring Farcaster wallet verification on-chain, making it easy to issue and consume attestations within the Superchain ecosystem.

The FarcasterResolver contract on Optimism securely decodes signed messages, validates signatures against Farcaster’s KeyRegistry, and records verified wallet-FID mappings. For projects requiring permissionless Farcaster verification, the FarcasterResolverConsumer contract can serve as a resolver in third-party EAS schemas, ensuring only properly verified wallet-FID pairs can attest.

Journey Overview

1. Users link their Ethereum wallet to their Farcaster FID (Farcaster ID) through Warpcast.
2. A verification message is signed using both the user’s wallet and the public key tied to their FID.
3. The signed verification message is broadcast across the Farcaster Hub network.
4. Either a relayer automatically detects the signed message from the Farcaster Hub or the user retrieves it manually.
5. The signed message is submitted to the FarcasterResolver contract on Optimism Mainnet.
6. Verification in FarcasterResolver:
   • The contract decodes the signed message.
   • Verifies the signature.
   • Checks the FID’s associated public key in the Farcaster KeyRegistry.
7. Upon successful verification, the FarcasterResolver records the wallet–FID pair on-chain and issues an attestation to the verified wallet.
8. Users can attest to third-party EAS schemas by specifying FarcasterResolverConsumer as the resolver.
9. Resolver Verification:
   • The wallet and FID are extracted from the attestation data.
   • FarcasterResolverConsumer verifies them against the FarcasterResolver contract.
10. If the wallet–FID pair is confirmed as valid, the attestation is authorized, enabling trustless Farcaster-based attestations for integrated applications.

Prize distribution and scoring

• Total Prize Pool: 60,378 OP

• Primary Prize Pool: 58478 OP

• 1900 OP of the prize pot is reserved for Low Severity findings. These reports are judged based on quality and reviewers are then ranked from 1st to 5th for the purpose of prize allocation.

  • 1st: 800 OP
  • 2nd: 400 OP
  • 3rd: 300 OP
  • 4th: 300 OP
  • 5th: 100 OP

• Scoring described in the competition scoring page.

• Findings Severities described in detail on our docs page.

Documentation

Here is an overview of the contract architecture

• FarcasterResolver - The primary contract that verifies and stores the relationship between a Farcaster-verified wallet address and its FID.
• FarcasterResolverInterop - A wrapper for FarcasterResolver, enabling interoperability across the Superchain with deterministic deployment to the same address.
• FarcasterPublicKeyVerifier - A contract that validates public keys and FIDs against the Farcaster KeyRegistry.
• FarcasterOnchainVerifier - A contract that fully computes and verifies Farcaster wallet verification add/remove messages directly on-chain.
• FarcasterOptimisticVerifier - A contract that verifies Farcaster wallet verification add/remove messages optimistically by relying on trusted, whitelisted relays. It includes a one-day challenge period, allowing anyone to dispute and verify the messages on-chain.
• FcVerificationDecoder - Library for decoding Farcaster verification GRPC-encoded messages.
• FcMessageVerification - Library for verifying Farcaster message signatures.
• FarcasterResolverConsumer - Abstract contract template for implementing resolvers requiring Farcaster verification.
• FarcasterResolverSimpleConsumer - Simple resolver for schemas allowing only attestations from Farcaster-verified wallets.
• FarcasterResolverStandardConsumer - Customizable resolver for schemas needing complex verification, such as reference and membership validation.
• FarcasterMembership - Membership system enabling attestation owners to invite other Farcaster users to reference the attestation.

Documentation for our smart contracts is available in the following repositories:

• farcaster-resolver
• farcaster-decoder

The farcaster-resolver contract uses farcaster-decoder to verify and decode Farcaster verification messages, which rely on both cryptographic contracts and gRPC decoders.

We use the following cryptography contracts for verification:

• Blake3
• Ed25519

These contracts function as expected, but currently there is no publicly available audit report for them.

Our gRPC decoder contracts are generated from a modified version of protobuf3-solidity. We have simplified these generated contracts by removing unused code, thereby reducing the attack surface.

We use Farcaster for the verification process and the KeyRegistry contract to validate public keys against FIDs. Relevant documentation:

• Farcaster Hub Verification API
• Farcaster KeyRegistry Contract
• Farcaster Contract Addresses

For attestations on Optimism and Superchains, we use the Ethereum Attestation Service (EAS). Additional references:

• Optimism EAS Scan
• Optimism Sepolia EAS Scan
• Optimism Identity Docs

Since interoperability is not yet live on the Optimism mainnet or testnet, we use Supersim to test cross-chain functionality.

We also provide an SDK for using Farcaster Attestation in external frontends and backends:
@farcaster-attestation/sdk

We will deploy live contracts on OP Sepolia with attestation streaming and an active challenger approximately one week after the audit begins.

Walkthrough

• Code walkthrough

Scope

• Repository:

  • https://github.com/Farcaster-Attestation/farcaster-decoder

• Commit: 53a5796b2f43a902d95f7c4ec81ac480e3661b6e

• Files: contracts/*

• Repository:

  • https://github.com/Farcaster-Attestation/farcaster-resolver

• Commit: b156ceeca5110334e64f04cb149ff3d12235d0b2

• Files: contracts/*

Build Instructions

The Farcaster Resolver is built using Hardhat. To run tests and deploy the contract, ensure you configure your private key and the Optimism RPC address in the .env file, as the tests are operated in fork mode.

Setting the environment

Create an .env file with the following secrets

RPC_URL=<Optimism mainnet RPC>
RPC_TESTNET_URL=<Optimism sepolia testnet RPC>
PRIVATE_KEY=<Private key for contract deployment>
ETHERSCAN_API_KEY=<Etherscsn API Key>

Compiling the contracts

npx hardhat compile

Running tests

npx hardhat test

Running coverage

npm run coverage

Deploying contracts on supersim

Supersim is a lightweight tool designed to simulate the Superchain. It is primarily used to test the FarcasterResolverInterop. The following command launches forked OP and Base chains simultaneously and sets up an L2 <-> L2 cross-chain interoperability simulation:

supersim fork --chains op,base --interop.autorelay

After starting Supersim, run the following command to deploy the necessary contracts:

./deploy-supersim.sh

Note that the FarcasterResolverExtended is deployed using a deterministic deployment strategy, ensuring it is deployed to the same address across all chains.

The first wallet in the test mnemonic (test junk) is designated as both the deployer and the admin of the contracts.

• Basic POC test

Out of scope

• Automated findings by Lightchaser Farcaster-Decoder: https://gist.github.com/ChaseTheLight01/bfcab8c88e13191259c023625bd36e71 Farcaster-Resolver: https://gist.github.com/ChaseTheLight01/0ef64b80a66c10efe5b0b19c5ddd5821

Contact Us

For any issues or concerns regarding this competition, please reach out to the Cantina core team through the Cantina Discord.