Work Sample 2: Developer Documentation

This developer guide demonstrates how to create a Farcaster Frame that automates Farcaster channel invites based on POAP event attendance. For example, you could use this to invite everyone who attended your conference (and claimed a POAP) to join your community’s channel on Farcaster.

Who is This Guide For?

This documentation is designed for developers who are:

• Experienced with modern web development (TypeScript, Next.js)
• Familiar with Web3 concepts and Ethereum fundamentals
• Looking to integrate decentralized social features using the Farcaster protocol
• Building community tools that leverage blockchain-based verification

Technical Prerequisites

Ensure you have:

• Experience with API integration and environment configuration
• Basic familiarity with Ethereum blockchain terms and functionality
• Working knowledge of TypeScript and the Next.js framework
• Access to required API credentials:
  • POAP: for event attendance verification
  • Neynar: for Farcaster protocol interaction

What You’ll Build

The guide walks through creating a system that:

1. Identifies POAP holders from a specific event
2. Maps their wallet addresses to Farcaster IDs
3. Delivers automated channel invites through an interactive Farcaster Frame

Key Terms

Before diving in, here’s a quick reference for important terms used throughout this document:

• Farcaster: A decentralized social media protocol.
• Farcaster Frames: Interactive elements that can be embedded in Farcaster posts.
• Farcaster Channels: Topic-based discussion spaces within the Farcaster network, similar to subreddits.
• POAP: “Proof of Attendance Protocol” - digital badges on the Ethereum blockchain given to event attendees.
• Warpcast: The primary client application for accessing Farcaster
• FID: Farcaster ID - a unique identifier for each user on the Farcaster protocol.
• Frame Server: A web server that handles Frame interactions.
• cast: A post on the Farcaster network.
• Neynar: An API service provider for Farcaster development.
• Frog.fm: A framework for building Farcaster Frames.
• composer URL: A specially formatted URL that pre-fills a new cast in Warpcast.
• allowlist: A list of approved users (in this case, POAP holders eligible for invites).
• wallet address: The account on the Ethereum blockchain that holds POAP tokens.

Key Concepts

The project combines three main concepts:

• Wallet Resolution: The system matches Ethereum wallet addresses (from POAP) to Farcaster accounts (via Neynar).

• Farcaster Frame: An interactive frame that allows a user to access the Farcaster Channel invite or not.

• Channel Invites: The URL that grants a Farcaster user membership to a Farcaster Channel.

Technologies

1. Frog.fm - A framework to build the frame interaction
2. Next.js - A framework that runs the frame server and provides access to allowlisted users.
3. Poap.tech API - To fetch the list of Ethereum wallet addresses that hold a particular POAP.
4. Neynar SDK - To find corresponding Farcaster accounts that match the discovered Ethereum wallet addresses.

App Logic

Follow app logic in main.ts

Environment Variables

Four environment variables used:

1. POAP_EVENT_ID - the unique identifier for your POAP you wish to find the holders of.
2. POAP_API_KEY - Your API key from poap.tech (used to query POAP data).
3. NEYNAR_API_KEY - Your API key from Neynar (used to interact with Farcaster data).
4. WC_INVITE_LINK - The invite link for your Farcaster channel (must be generated by a channel moderator in Warpcast).

How to Invite POAP Holders to Your Farcaster Channel Using an Invite Frame

1. Clone repository to local

2. Install dependencies using your preferred package manager - I use pnpm

    npm install  
    # or  
    pnpm install  
    # or  
    yarn install  
   

3. Set up poap.tech and Neynar API keys

   • Obtain API credentials for POAP.tech to query POAP wallet holders
   • Obtain API credentials for Neynar to map wallet addresses to Farcaster IDs

4. Add these four variables to your .env.local file

   • POAP_EVENT_ID - the unique identifier for your POAP.
   • POAP_API_KEY - Your API key from poap.tech.
   • NEYNAR_API_KEY - Your API key from Neynar.
   • WC_INVITE_LINK - The invite link for your Farcaster channel.

You can find the event ID for your POAP using the poap.tech GET /token/{tokenId} endpoint.

1. Run main.ts script, it will:

   a. Find all POAP wallet addresses: - Calls the poap.tech API - GET event/{id}/poaps - Implemented in @getPoapWallets

   b. Convert wallet addresses to Farcaster accounts: - Uses the Neynar SDK/API to find matching Farcaster user profiles GET /v2/farcaster/user/bulk-by-address - Implemented in @getFids

2. Create and Deliver Invites

   • Build the invite flow using the repository’s utilities and APIs:
     • Generate an Allowlist: Compile Farcaster IDs eligible for channel invites.
       • Implemented in @processForFids
     • Deliver Invites: Use Farcaster frames or direct messages to send invites to Farcaster users.

3. Customize Farcaster Frame

   • Customize the frame at app/api/[[...routes]]/route.tsx - Uses frog.fm as framework for frames

   • Run dev server

       npm run dev
       # or
       pnpm dev
     

   • Visit http://localhost:3000/api/dev to inspect frame using frog.fm devtools
   • Customize your frame and repeat until satisfied

4. Customize the Announcement Cast in cast.ts

   • Replace the options properties in the @WarpcastUrlBuilder.composerUrl method call
     • options.text - the text of the cast delivering the frame invites
     • options.embeds - url of the live frame server api route
     • options.channelKey - the name of the channel to cast the frame in

    // example
      const url = warpcastUrlBuilder.composerUrl({
        text: `Welcome new frens! If you played a game and got a /poap from me at /devcon love to hear from you in /tabletop! 
           
        Click Start to get your channel invite!`,
        embeds: ['https://poap-invites-frame.vercel.app/api'],
        channelKey: 'tabletop',
      });
    // https://warpcast.com/~/compose?text=Welcome%2520new%2520frens%21%2520If%2520you%2520played%2520a%2520game%2520and%2520got%2520a%2520%252Fpoap%2520from%2520me%2520at%2520%252Fdevcon%2520love%2520to%2520hear%2520from%2520you%2520in%2520%252Ftabletop%21%2520%250A%2520%2520%2520%2520%250A%2520%2520%2520%2520Click%2520Start%2520to%2520get%2520your%2520channel%2520invite%21&embeds%5B%5D=https%3A%2F%2Fpoap-invites-frame.vercel.app%2Fapi&channelKey=tabletop
   

5. Deliver Invites via Frame Cast in Farcaster Channel

   • Run cast.ts to create the warpcast composer URL - @composerUrl.
   • Click the URL to open a Warpcast composer prefilled with the cast options you specified in step 7. It will include your Farcaster channel invite frame embedded within the cast.
   • Click the composer URL in the console to cast the frame and allow the public to access your invite frame!

---

The simplest way I’ve found to run single typescript files in Node is with ts-node dev dependency and the following command:

node --loader ts-node/esm file.ts

Note: Requires "allowImportingTsExtensions": true and "noEmit": true in tsconfig.json