### Getting Started with Snapchain Development

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/README.md

This snippet provides the necessary commands to initialize the project dependencies and start the local development server for the Farcaster Snapchain project. It assumes Node.js and Yarn are already installed.

```bash
yarn
yarn dev
```

--------------------------------

### Quickstart: Sync Snapchain Data to Postgres with Shuttle

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/guides/syncing-to-db.mdx

This comprehensive quickstart guide provides the steps to set up and run the `shuttle` package to mirror Snapchain data into a Postgres database. It includes cloning the repository, installing Node.js dependencies, building necessary packages, starting database services with Docker Compose, and initiating the worker, backfill, and main synchronization processes.

```bash
git clone git@github.com:farcasterxyz/hub-monorepo.git

# Ensure you have node 21 installed, use nvm to install it
nvm install 21

# If necessary, build packages/core dependency
( cd packages/core && yarn install && yarn build; )

# If necessary, build packages/hub-nodejs dependency
( cd packages/hub-nodejs && yarn install && yarn build; )

# Do remainder within the packages/shuttle directory
cd packages/shuttle
yarn install && yarn build

# Start the db dependencies
docker compose up postgres redis

# To perform reconciliation/backfill, start the worker (can run multiple processes to speed this up)
POSTGRES_URL=postgres://shuttle:password@0.0.0.0:6541 REDIS_URL=0.0.0.0:16379 HUB_HOST=<host>:<port> HUB_SSL=false yarn start worker

# Kick off the backfill process (configure with MAX_FID=100 or BACKFILL_FIDS=1,2,3)
POSTGRES_URL=postgres://shuttle:password@0.0.0.0:6541 REDIS_URL=0.0.0.0:16379 HUB_HOST=<host>:<port> HUB_SSL=false yarn start backfill

# Start the app and sync messages from the event stream
POSTGRES_URL=postgres://shuttle:password@0.0.0.0:6541 REDIS_URL=0.0.0.0:16379 HUB_HOST=<host>:<port> HUB_SSL=false yarn start start
```

--------------------------------

### Set up Farcaster Snapchain Node with Docker Compose

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/getting-started.mdx

This snippet outlines the initial steps to deploy a Farcaster Snapchain node using Docker Compose. It involves fetching the official `docker-compose.yml` file from the repository and then starting the containerized services. Users can choose to run the containers in the background using the `-d` flag.

```bash
curl -L https://raw.githubusercontent.com/farcasterxyz/snapchain/refs/heads/main/docker-compose.mainnet.yml -o docker-compose.yml
docker compose up # -d to run in background, may need to run with sudo depending on your docker setup
```

--------------------------------

### Farcaster Snapchain Node HTTP API Reference

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/getting-started.mdx

This section provides a reference for the primary HTTP API endpoints exposed by a running Farcaster Snapchain node. It details how to retrieve node status information and query for user-specific data like casts, including parameters and expected return structures.

```APIDOC
GET /v1/info
  - Description: Retrieves comprehensive information about the Snapchain node's current status, including database statistics, the number of shards, and detailed information for each shard.
  - Returns: JSON object containing:
    - "dbStats": Object with "numMessages", "numFidRegistrations", "approxSize".
    - "numShards": Integer, total number of shards.
    - "shardInfos": Array of objects, each with:
      - "shardId": Integer, unique identifier for the shard.
      - "maxHeight": Integer, maximum block height for the shard.
      - "numMessages": Integer, number of messages in the shard.
      - "numFidRegistrations": Integer, number of FID registrations.
      - "approxSize": Integer, approximate size of the shard in bytes.
      - "blockDelay": Integer, delay in blocks from the network tip (lower is better).
      - "mempoolSize": Integer, current size of the mempool.

GET /v1/castsByFid?fid={fid}
  - Description: Fetches all cast messages associated with a specific Farcaster ID (FID) from the node's database.
  - Parameters:
    - fid (integer, required): The Farcaster ID of the user whose casts are to be retrieved.
  - Returns: JSON object containing an array of "messages", where each message object includes nested data such as "data.castAddBody.text" for the cast's content.
```

--------------------------------

### Install Snapchain Development Prerequisites

Source: https://github.com/farcasterxyz/snapchain/blob/main/README.md

These commands install essential development tools required for building Snapchain from source. They use Homebrew to install the Protocol Buffers compiler and CMake, which are dependencies for the Rust project.

```bash
brew install protobuf
brew install cmake
```

--------------------------------

### Monitor Snapchain Node Snapshot Download Progress

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/getting-started.mdx

This command allows real-time monitoring of the Snapchain Docker container's logs, specifically to track the progress of the initial snapshot download and decompression. It displays messages indicating the retrieval of various data chunks, which can take several hours depending on network speed and snapshot size.

```bash
sudo docker logs -f snapchain-snap_read-1
```

--------------------------------

### Run a Snapchain Node with Docker Compose

Source: https://github.com/farcasterxyz/snapchain/blob/main/README.md

This command sequence sets up a new Snapchain node using Docker Compose. It creates a dedicated directory, downloads the mainnet configuration, and starts the services. It also includes a step to stop any previously running versions to ensure a clean start.

```bash
mkdir snapchain
cd snapchain
docker compose down # If you have a previous version running
wget https://raw.githubusercontent.com/farcasterxyz/snapchain/refs/heads/main/docker-compose.mainnet.yml -O docker-compose.yml
docker compose up  # append -d to run in the background
```

--------------------------------

### Example Curl Command to Query VerificationsByFid

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/verification.md

Provides a practical `curl` command example demonstrating how to make a GET request to the `verificationsByFid` API endpoint. This snippet shows how to pass the `fid` query parameter to retrieve verifications for a specific Farcaster ID.

```bash
curl http://127.0.0.1:3381/v1/verificationsByFid?fid=2
```

--------------------------------

### Install Docker and Deploy Snapchain Node on AWS EC2

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/guides/running-a-node.mdx

This script automates the installation of Docker on an Ubuntu EC2 instance and subsequently downloads and executes the Snapchain mainnet Docker Compose configuration. It prepares the necessary directory structure and initiates the Snapchain node, with an option to run it in the background.

```bash
# Install docker
curl -fsSL https://get.docker.com -o get-docker.sh
chmod +x get-docker.sh
./get-docker.sh

# Start Snapchain
mkdir snapchain && cd snapchain
curl https://raw.githubusercontent.com/farcasterxyz/snapchain/refs/heads/main/docker-compose.mainnet.yml -o docker-compose.yml
sudo docker compose up # -d to run in background, if you set up rootless docker remove sudo
```

--------------------------------

### Curl Example: Query Farcaster FID Storage Limits

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/storagelimits.md

Demonstrates how to use the `curl` command-line tool to send a GET request to the `storageLimitsByFid` endpoint, querying the storage limits for a specific FID (6833) on a local Farcaster node.

```bash
curl http://127.0.0.1:3381/v1/storageLimitsByFid?fid=6833
```

--------------------------------

### Run Snapchain Unit and Integration Tests

Source: https://github.com/farcasterxyz/snapchain/blob/main/README.md

This command executes all defined tests within the Snapchain project. It's used to verify the correctness and stability of the codebase after setup or during development.

```bash
cargo test
```

--------------------------------

### Example cURL Commands for Farcaster Reactions API

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/reactions.md

Demonstrates how to query the Farcaster Reactions API endpoints using cURL from the command line to retrieve reaction data.

```bash
curl http://127.0.0.1:3381/v1/reactionById?fid=2&reaction_type=1&target_fid=1795&target_hash=0x7363f449bfb0e7f01c5a1cc0054768ed5146abc0
```

```bash
curl http://127.0.0.1:3381/v1/reactionsByFid?fid=2&reaction_type=1
```

```bash
curl http://127.0.0.1:3381/v1/reactionsByCast?target_fid=2&reaction_type=1&target_hash=0x7363f449bfb0e7f01c5a1cc0054768ed5146abc0
```

--------------------------------

### Query Farcaster Name Server for User FID

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/getting-started.mdx

This command illustrates how to use the public Farcaster name server API to resolve a Farcaster username to its corresponding Farcaster ID (FID). It's a crucial step for obtaining the necessary ID before querying the Snapchain node for user-specific data like messages.

```bash
curl https://fnames.farcaster.xyz/transfers?name=farcaster
```

--------------------------------

### Example JSON Responses for Farcaster Reactions API

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/reactions.md

Illustrates the expected JSON structure returned by the Farcaster Reactions API endpoints for various queries.

```json
{
  "data": {
    "type": "MESSAGE_TYPE_REACTION_ADD",
    "fid": 2,
    "timestamp": 72752656,
    "network": "FARCASTER_NETWORK_MAINNET",
    "reactionBody": {
      "type": "REACTION_TYPE_LIKE",
      "targetCastId": {
        "fid": 1795,
        "hash": "0x7363f449bfb0e7f01c5a1cc0054768ed5146abc0"
      }
    }
  },
  "hash": "0x9fc9c51f6ea3acb84184efa88ba4f02e7d161766",
  "hashScheme": "HASH_SCHEME_BLAKE3",
  "signature": "F2OzKsn6Wj...gtyORbyCQ==",
  "signatureScheme": "SIGNATURE_SCHEME_ED25519",
  "signer": "0x78ff9a7...647b6d62558c"
}
```

```json
{
  "messages": [
    {
      "data": {
        "type": "MESSAGE_TYPE_REACTION_ADD",
        "fid": 2,
        "timestamp": 72752656,
        "network": "FARCASTER_NETWORK_MAINNET",
        "reactionBody": {
          "type": "REACTION_TYPE_LIKE",
          "targetCastId": {
            "fid": 1795,
            "hash": "0x7363f449bfb0e7f01c5a1cc0054768ed5146abc0"
          }
        }
      },
      "hash": "0x9fc9c51f6ea3acb84184efa88ba4f02e7d161766",
      "hashScheme": "HASH_SCHEME_BLAKE3",
      "signature": "F2OzKsn6WjP8MTw...hqUbrAvp6mggtyORbyCQ==",
      "signatureScheme": "SIGNATURE_SCHEME_ED25519",
      "signer": "0x78ff9a768...62558c"
    }
  ],
  "nextPageToken": ""
}
```

```json
{
  "messages": [
    {
      "data": {
        "type": "MESSAGE_TYPE_REACTION_ADD",
        "fid": 426,
        "timestamp": 72750141,
        "network": "FARCASTER_NETWORK_MAINNET",
        "reactionBody": {
          "type": "REACTION_TYPE_LIKE",
          "targetCastId": {
            "fid": 1795,
            "hash": "0x7363f449bfb0e7f01c5a1cc0054768ed5146abc0"
          }
        }
      },
      "hash": "0x7662fba1be3166fc75acc0914a7b0e53468d5e7a",
      "hashScheme": "HASH_SCHEME_BLAKE3",
      "signature": "tmAUEYlt/+...R7IO3CA==",
      "signatureScheme": "SIGNATURE_SCHEME_ED25519",
      "signer": "0x13dd2...204e57bc2a"
    }
  ],
  "nextPageToken": ""
}
```

--------------------------------

### Check Farcaster Snapchain Node Synchronization Status

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/getting-started.mdx

This snippet demonstrates how to query the local Snapchain node's HTTP API to ascertain its current synchronization status. It uses `curl` to fetch node information and `jq` to parse the JSON output, allowing users to verify sync by checking the `blockDelay` values for shards, which should be in single digits for a synchronized node.

```bash
curl localhost:3381/v1/info | jq
```

--------------------------------

### JavaScript Example for Paginated API Calls

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/httpapi.mdx

Demonstrates how to fetch all pages of a paginated API endpoint using `axios` in JavaScript, iterating until `nextPageToken` is empty to retrieve all available data.

```javascript
import axios from "axios";

const fid = 2;
const server = "http://127.0.0.1:3381";

let nextPageToken = "";
do {
    const response = await axios.get(`${server}/v1/castsByFid?fid=${fid}&pageSize=100&nextPageToken=${nextPageToken}`);
    // Process response....
    nextPageToken = response.nextPageToken;
} while (nextPageToken !== "")
```

--------------------------------

### HTTP API Pagination Parameters and Usage

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/httpapi.mdx

Describes the query parameters available for paginating API responses, including `pageSize`, `reverse`, and `pageToken`. It also provides examples for fetching the first and subsequent pages using `bash`.

```APIDOC
Pagination Query Parameters:
  pageSize: Maximum number of messages to return in a single response (Example: pageSize=100)
  reverse: Reverse the sort order, returning latest messages first (Example: reverse=1)
  pageToken: The page token returned by the previous query, to fetch the next page. If this parameters is empty, fetch the first page (Example: pageToken=AuzO1V0Dta...fStlynsGWT)

Usage Examples:
# Fetch first page
http://127.0.0.1:3381/v1/castsByFid?fid=2&pageSize=3

# Fetch next page. The pageToken is from the previous response(`response.nextPageToken`)
http://127.0.0.1:3381/v1/castsByFid?fid=2&pageSize=3&pageToken=AuzO1V0DtaItCwwa10X6YsfStlynsGWT
```

--------------------------------

### Run Multiple Snapchain Development Nodes

Source: https://github.com/farcasterxyz/snapchain/blob/main/README.md

This command starts multiple Snapchain nodes configured to communicate with each other in a local development environment. It's useful for testing multi-node interactions and network behavior without deploying to a live network.

```bash
make dev
```

--------------------------------

### Query Snapchain Node for User Casts by FID

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/getting-started.mdx

Once the node is synchronized and a user's Farcaster ID (FID) is known, this snippet shows how to retrieve all cast messages associated with that FID directly from the local Snapchain node's HTTP API. It uses `jq` to filter and extract only the text content of the casts.

```bash
curl http://localhost:3381/v1/castsByFid\?fid\=1 \
 | jq ".messages[].data.castAddBody.text \
 | select( . != null)"
```

--------------------------------

### Retrieve Farcaster Hub Info with Curl

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/info.md

An example `curl` command demonstrating how to query the `/v1/info` endpoint of a Farcaster Hub, specifically requesting the inclusion of database statistics in the response.

```bash
curl http://127.0.0.1:3381/v1/info?dbstats=1
```

--------------------------------

### Example Farcaster Hub Info API JSON Response

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/info.md

A sample JSON response illustrating the typical data structure returned by the `/v1/info` endpoint when requesting database statistics. It includes hub version, sync status, nickname, root hash, detailed database metrics, peer ID, and operator FID.

```json
{
  "version": "1.5.5",
  "isSyncing": false,
  "nickname": "Farcaster Hub",
  "rootHash": "fa349603a6c29d27041225261891bc9bc846bccb",
  "dbStats": {
    "numMessages": 4191203,
    "numFidEvents": 20287,
    "numFnameEvents": 20179
  },
  "peerId": "12D3KooWNr294AH1fviDQxRmQ4K79iFSGoRCWzGspVxPprJUKN47",
  "hubOperatorFid": 6833
}
```

--------------------------------

### Get Paginated Events from Hub API

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/events.md

Documents the `/v1/events` endpoint, which retrieves a paginated list of Hub events. It explains the `from_event_id` parameter for pagination and highlights the 3-day data retention policy. The snippet includes the API specification, a `curl` command example, and a sample JSON response showing the structure of the event list.

```APIDOC
Endpoint: /v1/events
Method: GET
Description: Get a paginated list of Hub events.
Parameters:
  - Name: from_event_id
    Type: integer (Hub Id)
    Description: Optional. The Hub ID to start fetching events from. Use '0' to start from the first event. This value is returned as 'nextPageEventId' for subsequent pagination.
    Example: 350909155450880
Notes:
  - Hubs prune events older than 3 days; historical events beyond this period may not be available.
Response (JSON):
  {
    "nextPageEventId": 350909170294785,
    "events": [
      {
        "type": "HUB_EVENT_TYPE_MERGE_USERNAME_PROOF",
        "id": 350909155450880,
        "mergeUsernameProofBody": {
          "usernameProof": {
            "timestamp": 1695049760,
            "name": "nftonyp",
            "owner": "0x23b3c29900762a70def5dc8890e09dc9019eb553",
            "signature": "xp41PgeOz...9Jw5vT/eLnGphJpNshw=",
            "fid": 20114,
            "type": "USERNAME_TYPE_FNAME"
          }
        }
      },
      ...
    ]
  }
```

```bash
curl http://127.00.1:3381/v1/events?from_event_id=350909155450880
```

```json
{
  "nextPageEventId": 350909170294785,
  "events": [
    {
      "type": "HUB_EVENT_TYPE_MERGE_USERNAME_PROOF",
      "id": 350909155450880,
      "mergeUsernameProofBody": {
        "usernameProof": {
          "timestamp": 1695049760,
          "name": "nftonyp",
          "owner": "0x23b3c29900762a70def5dc8890e09dc9019eb553",
          "signature": "xp41PgeOz...9Jw5vT/eLnGphJpNshw=",
          "fid": 20114,
          "type": "USERNAME_TYPE_FNAME"
        }
      }
    },
    ...
  ]
}
```

--------------------------------

### Call Snapchain API using cURL

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/httpapi.mdx

Illustrates how to make a GET request to a Snapchain API endpoint using the cURL command-line tool, useful for scripting and testing.

```bash
curl http://127.0.0.1:3381/v1/castsByFid?fid=2
```

--------------------------------

### Fids API Endpoint Reference

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/fids.md

Comprehensive documentation for the `/v1/fids` API endpoint, detailing its purpose, parameters, and expected response structure, including usage examples and response formats.

```APIDOC
GET /v1/fids
  - Description: Get a list of all the FIDs.
  - Parameters:
    - None: This endpoint accepts no parameters.
  - Returns: JSON object
    - fids: array of integers (List of FIDs)
    - nextPageToken: string (Token for pagination, if more results are available)
  - Example Usage (cURL):
    curl http://127.0.0.1:3381/v1/fids
  - Example Response:
    {
      "fids": [1, 2, 3, 4, 5, 6],
      "nextPageToken": "AAAnEA=="
    }
```

--------------------------------

### Call Snapchain API with JavaScript and Axios

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/httpapi.mdx

Provides a JavaScript example using the Axios library to asynchronously fetch data from a Snapchain API endpoint, including basic error handling. This snippet shows how to construct the API URL and access the response data.

```javascript
import axios from "axios";

const fid = 2;
const server = "http://127.0.0.1:3381";

try {
    const response = await axios.get(`${server}/v1/castsByFid?fid=${fid}`);

    console.log(`API Returned HTTP status ${response.status}`);
    console.log(`First Cast's text is ${response.messages[0].data.castAddBody.text}`);
} catch (e) {
    // Handle errors
    console.log(response);
}
```

--------------------------------

### Retrieve Reactions by Target URL API

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/reactions.md

Documents the `reactionsByTarget` API endpoint, including its query parameters, an example `curl` request, and the structure of the JSON response for retrieving reactions to a specified URL.

```APIDOC
Endpoint: GET /v1/reactionsByTarget

Description: Get all reactions to a cast's target URL.

Query Parameters:
- url (string, required): The URL of the parent cast.
  Example: chain://eip155:1/erc721:0x39d89b649ffa044383333d297e325d42d31329b2
- reaction_type (string/integer, optional): The type of reaction, either as a numerical enum value or string representation.
  Example: 1 OR REACTION_TYPE_LIKE

Example Request:
```bash
curl http://127.0.0.1:3381/v1/reactionsByTarget?url=chain://eip155:1/erc721:0x39d89b649ffa044383333d297e325d42d31329b2
```

Response Schema:
```json
{
  "messages": [
    {
      "data": {
        "type": "MESSAGE_TYPE_REACTION_ADD",
        "fid": 1134,
        "timestamp": 79752856,
        "network": "FARCASTER_NETWORK_MAINNET",
        "reactionBody": {
          "type": "REACTION_TYPE_LIKE",
          "targetUrl": "chain://eip155:1/erc721:0x39d89b649ffa044383333d297e325d42d31329b2"
        }
      },
      "hash": "0x94a0309cf11a07b95ace71c62837a8e61f17adfd",
      "hashScheme": "HASH_SCHEME_BLAKE3",
      "signature": "+f/+M...0Uqzd0Ag==",
      "signatureScheme": "SIGNATURE_SCHEME_ED25519",
      "signer": "0xf6...3769198d4c"
    }
  ],
  "nextPageToken": ""
}
```
```

--------------------------------

### Farcaster Snapchain UserData API Specification

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/userdata.md

Comprehensive documentation for the Farcaster Snapchain UserData API, including supported user data types and the `userDataByFid` endpoint. It details query parameters, provides a cURL example for making requests, and illustrates the expected JSON response structure.

```APIDOC
UserData API Overview:
The UserData API accepts specific values for the `user_data_type` field to retrieve various user profile data points.

Supported User Data Types (user_data_type field values):
- USER_DATA_TYPE_PFP (1): Profile Picture for the user
- USER_DATA_TYPE_DISPLAY (2): Display Name for the user
- USER_DATA_TYPE_BIO (3): Bio for the user
- USER_DATA_TYPE_URL (5): URL of the user
- USER_DATA_TYPE_USERNAME (6): Preferred Name for the user
- USER_DATA_TYPE_LOCATION (7): Location for the user
- USER_DATA_TYPE_TWITTER (8): Twitter username for the user
- USER_DATA_TYPE_GITHUB (9): GitHub username for the user

Endpoint: userDataByFid
Description: Get UserData for a Farcaster ID (FID).

Method: GET
Path: /v1/userDataByFid

Query Parameters:
- fid (required, integer): The Farcaster ID (FID) for which user data is being requested.
  Example: fid=6833
- user_data_type (optional, integer or string): The type of user data to retrieve. Can be a numerical value (e.g., 1 for PFP) or a string (e.g., USER_DATA_TYPE_DISPLAY). If omitted, all available user data for the specified FID is returned.
  Example: user_data_type=1 OR user_data_type=USER_DATA_TYPE_DISPLAY

Example Request (bash):
curl http://127.0.0.1:3381/v1/userDataByFid?fid=6833&user_data_type=1

Example Response (json):
{
  "data": {
    "type": "MESSAGE_TYPE_USER_DATA_ADD",
    "fid": 6833,
    "timestamp": 83433831,
    "network": "FARCASTER_NETWORK_MAINNET",
    "userDataBody": {
      "type": "USER_DATA_TYPE_PFP",
      "value": "https://i.imgur.com/HG54Hq6.png"
    }
  },
  "hash": "0x327b8f47218c369ae01cc453cc23efc79f10181f",
  "hashScheme": "HASH_SCHEME_BLAKE3",
  "signature": "XITQZD7q...LdAlJ9Cg==",
  "signatureScheme": "SIGNATURE_SCHEME_ED25519",
  "signer": "0x0852...6e999cdd"
}
```

--------------------------------

### Farcaster Reactions API Endpoints Specification

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/reactions.md

Comprehensive documentation for the Farcaster Reactions API, including supported reaction types, endpoint paths, query parameters, and example response structures for retrieving reactions by ID, by FID, and by target cast.

```APIDOC
Farcaster Reactions API Endpoints

1. Reaction Types:
   The `reaction_type` field accepts either string or numerical values:
   - REACTION_TYPE_LIKE (1): Like the target cast
   - REACTION_TYPE_RECAST (2): Share target cast to the user's audience

2. GET /v1/reactionById
   Description: Get a specific reaction by its creator's FID and target Cast details.
   Query Parameters:
     - fid (integer): The FID of the reaction's creator. Example: `6833`
     - target_fid (integer): The FID of the cast's creator. Example: `2`
     - target_hash (string): The hash of the cast. Example: `0xa48dd46161d8e57725f5e26e34ec19c13ff7f3b9`
     - reaction_type (integer/string): The type of reaction (e.g., `1` or `REACTION_TYPE_LIKE`).
   Response Structure (Example):
     {
       "data": {
         "type": "MESSAGE_TYPE_REACTION_ADD",
         "fid": 2,
         "timestamp": 72752656,
         "network": "FARCASTER_NETWORK_MAINNET",
         "reactionBody": {
           "type": "REACTION_TYPE_LIKE",
           "targetCastId": {
             "fid": 1795,
             "hash": "0x7363f449bfb0e7f01c5a1cc0054768ed5146abc0"
           }
         }
       },
       "hash": "0x9fc9c51f6ea3acb84184efa88ba4f02e7d161766",
       "hashScheme": "HASH_SCHEME_BLAKE3",
       "signature": "F2OzKsn6Wj...gtyORbyCQ==",
       "signatureScheme": "SIGNATURE_SCHEME_ED25519",
       "signer": "0x78ff9a7...647b6d62558c"
     }

3. GET /v1/reactionsByFid
   Description: Get all reactions created by a specific FID.
   Query Parameters:
     - fid (integer): The FID of the reaction's creator. Example: `6833`
     - reaction_type (integer/string): The type of reaction (e.g., `1` or `REACTION_TYPE_LIKE`).
   Response Structure (Example):
     {
       "messages": [
         {
           "data": {
             "type": "MESSAGE_TYPE_REACTION_ADD",
             "fid": 2,
             "timestamp": 72752656,
             "network": "FARCASTER_NETWORK_MAINNET",
             "reactionBody": {
               "type": "REACTION_TYPE_LIKE",
               "targetCastId": {
                 "fid": 1795,
                 "hash": "0x7363f449bfb0e7f01c5a1cc0054768ed5146abc0"
               }
             }
           },
           "hash": "0x9fc9c51f6ea3acb84184efa88ba4f02e7d161766",
           "hashScheme": "HASH_SCHEME_BLAKE3",
           "signature": "F2OzKsn6WjP8MTw...hqUbrAvp6mggtyORbyCQ==",
           "signatureScheme": "SIGNATURE_SCHEME_ED25519",
           "signer": "0x78ff9a768...62558c"
         }
       ],
       "nextPageToken": ""
     }

4. GET /v1/reactionsByCast
   Description: Get all reactions associated with a specific cast.
   Query Parameters:
     - target_fid (integer): The FID of the cast's creator. Example: `6833`
     - target_hash (string): The hash of the cast. Example: `0x7363f449bfb0e7f01c5a1cc0054768ed5146abc0`
     - reaction_type (integer/string): The type of reaction (e.g., `1` or `REACTION_TYPE_LIKE`).
   Response Structure (Example):
     {
       "messages": [
         {
           "data": {
             "type": "MESSAGE_TYPE_REACTION_ADD",
             "fid": 426,
             "timestamp": 72750141,
             "network": "FARCASTER_NETWORK_MAINNET",
             "reactionBody": {
               "type": "REACTION_TYPE_LIKE",
               "targetCastId": {
                 "fid": 1795,
                 "hash": "0x7363f449bfb0e7f01c5a1cc0054768ed5146abc0"
               }
             }
           },
           "hash": "0x7662fba1be3166fc75acc0914a7b0e53468d5e7a",
           "hashScheme": "HASH_SCHEME_BLAKE3",
           "signature": "tmAUEYlt/+...R7IO3CA==",
           "signatureScheme": "SIGNATURE_SCHEME_ED25519",
           "signer": "0x13dd2...204e57bc2a"
         }
       ],
       "nextPageToken": ""
     }
```

--------------------------------

### Submit Farcaster Message using JavaScript with Axios

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/message.md

JavaScript example demonstrating how to submit a protobuf-encoded Farcaster message to the Hub using Axios, including handling content type and HTTP Basic Auth.

```Javascript
import axios from "axios";

const url = `http://127.0.0.1:3381/v1/submitMessage`;

const postConfig = {
  headers: { "Content-Type": "application/octet-stream" },
  auth: { username: "username", password: "password" },
};

// Encode the message into a Buffer (of bytes)
const messageBytes = Buffer.from(Message.encode(castAdd).finish());

try {
  const response = await axios.post(url, messageBytes, postConfig);
} catch (e) {
  // handle errors...
}
```

--------------------------------

### HTTP API Timestamp Filtering Parameters

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/httpapi.mdx

Explains the `startTimestamp` and `stopTimestamp` query parameters used to filter API results by a specific time range. An example shows how to use these parameters with a `bash` curl command.

```APIDOC
Timestamp Filtering Parameters:
  startTimestamp: Start of the time range (inclusive) (Example: startTimestamp=1000)
  stopTimestamp: End of the time range (inclusive) (Example: stopTimestamp=2000)

Usage Example:
# Get casts from FID 2 between timestamps 1000 and 2000
http://127.0.0.1:3381/v1/castsByFid?fid=2&startTimestamp=1000&stopTimestamp=2000
```

--------------------------------

### Snapchain Events API: Subscription Method and Request Structure

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/grpcapi/events.md

Documents the Snapchain Events API, including the 'Subscribe' method for real-time event streaming and the 'SubscribeRequest' message structure used to specify subscription parameters like event types, starting ID, and partitioning.

```APIDOC
Events API:

Method: Subscribe
  Request Type: SubscribeRequest
  Response Type: stream HubEvent
  Description: Streams new Events as they occur

SubscribeRequest:
  Fields:
    event_types:
      Type: [EventType] (repeated)
      Description: Types of events to subscribe to
    from_id:
      Type: uint64 (optional)
      Description: Event ID to start streaming from
    fid_partitions:
      Type: uint64 (optional)
      Description: Number of FID partitions
    fid_partition_index:
      Type: uint64 (optional)
      Description: Index of FID partition to subscribe to
    shard_index:
      Type: uint32 (optional)
      Description: Shard index to subscribe to
```

--------------------------------

### Submit Farcaster Message with HTTP Basic Auth using cURL

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/message.md

Example cURL command demonstrating how to submit a Farcaster message to the Hub using HTTP Basic Authentication when RPC auth is enabled.

```bash
curl -X POST "http://127.0.0.1:3381/v1/submitMessage" \
     -u "username:password" \
     -H "Content-Type: application/octet-stream" \
     --data-binary "@message.encoded.protobuf"
```

--------------------------------

### FidTimestamp Request Schema

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/grpcapi/reactions.md

Defines the request parameters for retrieving reactions by Farcaster ID with optional timestamp-based filtering. It allows specifying start and stop timestamps, along with pagination and result ordering options.

```APIDOC
FidTimestampRequest:
  fid: uint64 (Farcaster ID)
  page_size: uint32 (optional) (Number of results to return per page)
  page_token: bytes (optional) (Token for pagination)
  reverse: bool (optional) (Whether to return results in reverse order)
  start_timestamp: uint64 (optional) (Optional timestamp to start filtering from)
  stop_timestamp: uint64 (optional) (Optional timestamp to stop filtering at)
```

--------------------------------

### Farcaster Storage API: Get FID Storage Limits Endpoint

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/storagelimits.md

Documents the `storageLimitsByFid` endpoint, detailing its purpose, HTTP method, query parameters, and the comprehensive structure of the JSON response for an FID's storage limits across various store types.

```APIDOC
Endpoint: /v1/storageLimitsByFid
Method: GET
Description: Get an FID's storage limits.

Query Parameters:
  - fid (integer): The FID that's being requested. Example: 6833

Response (JSON):
  {
    "limits": [
      {
        "storeType": "STORE_TYPE_CASTS",
        "limit": 10000
      },
      {
        "storeType": "STORE_TYPE_LINKS",
        "limit": 5000
      },
      {
        "storeType": "STORE_TYPE_REACTIONS",
        "limit": 5000
      },
      {
        "storeType": "STORE_TYPE_USER_DATA",
        "limit": 100
      },
      {
        "storeType": "STORE_TYPE_USERNAME_PROOFS",
        "limit": 10
      },
      {
        "storeType": "STORE_TYPE_VERIFICATIONS",
        "limit": 50
      }
    ]
  }
```

--------------------------------

### Sample JSON Response for VerificationsByFid API

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/verification.md

Illustrates the typical JSON structure returned by the `verificationsByFid` API endpoint. This example shows a single verification message, detailing its data type, associated FID, timestamp, network, and the `verificationAddEthAddressBody` containing the Ethereum address and signature details, along with message hash and signer information.

```json
{
  "messages": [
    {
      "data": {
        "type": "MESSAGE_TYPE_VERIFICATION_ADD_ETH_ADDRESS",
        "fid": 2,
        "timestamp": 73244540,
        "network": "FARCASTER_NETWORK_MAINNET",
        "verificationAddEthAddressBody": {
          "address": "0x91031dcfdea024b4d51e775486111d2b2a715871",
          "ethSignature": "tyxj1...x1cYzhyxw=",
          "blockHash": "0xd74860c4bbf574d5ad60f03a478a30f990e05ac723e138a5c860cdb3095f4296"
        }
      },
      "hash": "0xa505331746ec8c5110a94bdb098cd964e43a8f2b",
      "hashScheme": "HASH_SCHEME_BLAKE3",
      "signature": "bln1zIZM.../4riB9IVBQ==",
      "signatureScheme": "SIGNATURE_SCHEME_ED25519",
      "signer": "0x78ff9...b6d62558c"
    }
  ],
  "nextPageToken": ""
}
```

--------------------------------

### Farcaster Links API Endpoints

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/links.md

This section describes the core API endpoints for interacting with Farcaster user links. It includes methods for retrieving individual links, all links originating from a specific user, and all links targeting a specific user, along with their respective query parameters, example requests, and expected JSON responses.

```APIDOC
Links API: Managing User Relationships

A Link represents a relationship between two users (e.g. follow).
The Links API accepts 'follow' for the `link_type` field.

1. linkById
   Description: Get a specific link by its originator's FID and target's FID.
   Endpoint: GET /v1/linkById
   Query Parameters:
     - fid (integer): The FID of the link's originator. Example: 6833
     - target_fid (integer): The FID of the target of the link. Example: 2
     - link_type (string): The type of link (e.g., 'follow'). Example: 'follow'
   Example Request:
     curl http://127.0.0.1:3381/v1/linkById?fid=6833&target_fid=2&link_type=follow
   Example Response:
     {
       "data": {
         "type": "MESSAGE_TYPE_LINK_ADD",
         "fid": 6833,
         "timestamp": 61144470,
         "network": "FARCASTER_NETWORK_MAINNET",
         "linkBody": {
           "type": "follow",
           "targetFid": 2
         }
       },
       "hash": "0x58c23eaf4f6e597bf3af44303a041afe9732971b",
       "hashScheme": "HASH_SCHEME_BLAKE3",
       "signature": "sMypYEMqSyY...nfCA==",
       "signatureScheme": "SIGNATURE_SCHEME_ED25519",
       "signer": "0x0852c07b56...06e999cdd"
     }

2. linksByFid
   Description: Get all links originating from a specific FID.
   Endpoint: GET /v1/linksByFid
   Query Parameters:
     - fid (integer): The FID of the link's originator. Example: 6833
     - link_type (string, optional): The type of link (e.g., 'follow').
   Example Request:
     curl http://127.0.0.1:3381/v1/linksByFid?fid=6833
   Example Response:
     {
       "messages": [
         {
           "data": {
             "type": "MESSAGE_TYPE_LINK_ADD",
             "fid": 6833,
             "timestamp": 61144470,
             "network": "FARCASTER_NETWORK_MAINNET",
             "linkBody": {
               "type": "follow",
               "targetFid": 83
             }
           },
           "hash": "0x094e35891519c0e04791a6ba4d2eb63d17462f02",
           "hashScheme": "HASH_SCHEME_BLAKE3",
           "signature": "qYsfX08mS...McYq6IYMl+ECw==",
           "signatureScheme": "SIGNATURE_SCHEME_ED25519",
           "signer": "0x0852c0...a06e999cdd"
         }
       ],
       "nextPageToken": ""
     }

3. linksByTargetFid
   Description: Get all links targeting a specific FID.
   Endpoint: GET /v1/linksByTargetFid
   Query Parameters:
     - target_fid (integer): The FID of the link's target. Example: 6833
     - link_type (string, optional): The type of link (e.g., 'follow').
   Example Request:
     curl http://127.0.0.1:3381/v1/linksByTargetFid?target_fid=6833
   Example Response:
     {
       "messages": [
         {
           "data": {
             "type": "MESSAGE_TYPE_LINK_ADD",
             "fid": 302,
             "timestamp": 61144668,
             "network": "FARCASTER_NETWORK_MAINNET",
             "linkBody": {
               "type": "follow",
               "targetFid": 6833
             }
           },
           "hash": "0x78c62531d96088f640ffe7e62088b49749efe286",
           "hashScheme": "HASH_SCHEME_BLAKE3",
           "signature": "frIZJGIizv...qQd9QJyCg==",
           "signatureScheme": "SIGNATURE_SCHEME_ED25519",
           "signer": "0x59a04...6860ddfab"
         }
       ],
       "nextPageToken": ""
     }
```

--------------------------------

### Submit Farcaster Messages to Hub (Set Username & Post Cast)

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/guides/writing-messages.mdx

This code demonstrates how to submit various Farcaster messages to the Hub, including setting a user's `fname` as their primary username and posting a new cast. It defines a `submitMessage` helper function to encapsulate the logic for submitting a `HubAsyncResult<Message>` and handling potential errors. The example then uses `makeUserDataAdd` and `makeCastAdd` to construct and submit the respective message types.

```typescript
const submitMessage = async (resultPromise: HubAsyncResult<Message>) => {
  const result = await resultPromise;
  if (result.isErr()) {
    throw new Error(`Error creating message: ${result.error}`);
  }
  const messageSubmitResult = await hubClient.submitMessage(result.value, metadata);
  if (messageSubmitResult.isErr()) {
    throw new Error(`Error submitting message to node: ${messageSubmitResult.error}`);
  }
};

const signer = new NobleEd25519Signer(signerPrivateKey);
const dataOptions = {
fid: fid,
network: FC_NETWORK,
};
const userDataPfpBody = {
type: UserDataType.USERNAME,
value: fname,
};
await submitMessage(makeUserDataAdd(userDataPfpBody, dataOptions, signer));

await submitMessage(
makeCastAdd(
    {
    text: "Hello World!",
    embeds: [],
    embedsDeprecated: [],
    mentions: [],
    mentionsPositions: [],
    type: CastType.CAST,
    },
    dataOptions,
    signer,
));
```

--------------------------------

### Get Single Event by ID from Hub API

Source: https://github.com/farcasterxyz/snapchain/blob/main/site/docs/pages/reference/httpapi/events.md

Documents the `/v1/eventById` endpoint, allowing retrieval of a specific Hub event using its unique identifier. This snippet includes the API specification, a `curl` command example for making the request, and a sample JSON response demonstrating the event structure.

```APIDOC
Endpoint: /v1/eventById
Method: GET
Description: Get a single event by its Hub ID.
Parameters:
  - Name: event_id
    Type: integer (Hub Id)
    Description: The unique Hub ID of the event to retrieve.
    Example: 350909155450880
Response (JSON):
  {
    "type": "HUB_EVENT_TYPE_MERGE_USERNAME_PROOF",
    "id": 350909155450880,
    "mergeUsernameProofBody": {
      "usernameProof": {
        "timestamp": 1695049760,
        "name": "nftonyp",
        "owner": "0x23b3c29900762a70def5dc8890e09dc9019eb553",
        "signature": "xp41PgeO...hJpNshw=",
        "fid": 20114,
        "type": "USERNAME_TYPE_FNAME"
      }
    }
  }
```

```bash
curl http://127.0.0.1:3381/v1/eventById?id=350909155450880
```

```json
{
  "type": "HUB_EVENT_TYPE_MERGE_USERNAME_PROOF",
  "id": 350909155450880,
  "mergeUsernameProofBody": {
    "usernameProof": {
      "timestamp": 1695049760,
      "name": "nftonyp",
      "owner": "0x23b3c29900762a70def5dc8890e09dc9019eb553",
      "signature": "xp41PgeO...hJpNshw=",
      "fid": 20114,
      "type": "USERNAME_TYPE_FNAME"
    }
  }
}
```

--------------------------------

### Clone and Build Snapchain from Source

Source: https://github.com/farcasterxyz/snapchain/blob/main/README.md

This sequence of commands clones the Snapchain repository along with its specific dependencies (eth-signature-verifier and malachite) from GitHub. It then checks out precise commit versions for these dependencies to ensure compatibility before building the main Snapchain project using Cargo.

```bash
git clone git@github.com:CassOnMars/eth-signature-verifier.git
cd eth-signature-verifier
git checkout 8deb4a091982c345949dc66bf8684489d9f11889
cd ..
git clone git@github.com:informalsystems/malachite.git
cd malachite
git checkout 13bca14cd209d985c3adf101a02924acde8723a5
cd ..
git clone git@github.com:farcasterxyz/snapchain.git
cd snapchain
cargo build
```