Getting storage units allocation of Farcaster user

In the Farcaster protocol, a storage unit is a measure used to allocate and track the amount of data that a user (identified by their Farcaster ID or fid) can store within the network. This system is critical for managing the storage resources of the Farcaster network effectively and ensuring that the network remains scalable and efficient.

The specific allocation of storage per unit varies depending on the type of data being stored.

Here's the list of storage allocations per unit:

• 5000 cast messages
• 2500 reaction messages
• 2500 link messages
• 50 user_data messages
• 25 verifications messages
• 5 username_proof messages

The allocation is controlled and tracked by the Storage Registry contract. This contract keeps a record of the storage allocated to each fid, denominated in integer units.

If a user exceeds their storage allocation, their old messages will be pruned by Farcaster Hub. Users can buy more storage units by sending a transaction to the Storage Registry contract, or by using a web app from @sammdec.eth: caststorage.com.

This guide demonstrates how to lookup the storage usage and allocation of a Farcaster user with the Neynar SDK.

Check out this Getting started guide to learn how to set up your environment and get an API key.

First, initialize the client:

// npm i @neynar/nodejs-sdk
import { NeynarAPIClient } from "@neynar/nodejs-sdk";

// make sure to set your NEYNAR_API_KEY .env
// don't have an API key yet? get one at neynar.com
const client = new NeynarAPIClient(process.env.NEYNAR_API_KEY);

Then fetch the storage usage and allocation:

const rishFID = 194;
const storageUsage = await client.lookupUserStorageUsage(rishFID);

console.log(storageUsage);

Example output:

{
  object: "storage_usage",
  user: {
    object: "user_dehydrated",
    fid: 194
  },
  total_active_units: 2,
  casts: {
    object: "storage",
    used: 3707,
    capacity: 10000
  },
  reactions: {
    object: "storage",
    used: 4984,
    capacity: 5000
  },
  links: {
    object: "storage",
    used: 472,
    capacity: 5000
  },
  verifications: {
    used: 2,
    capacity: 25
  },
  username_proofs: {
    used: 1,
    capacity: 5
  },
  signers: {
    used: 17,
    capacity: 1000
  }
}

To fetch the storage allocation of a user, use the lookupUserStorageAllocation function:

const storageAllocation = await client.lookupUserStorageAllocations(rishFID);
console.log(storageAllocation);

Example output:

{
  total_active_units: 2,
  allocations: [
    {
      object: "storage_allocation",
      user: [Object ...],
      units: 2,
      expiry: "2024-08-28T22:23:31.000Z",
      timestamp: "2023-08-29T22:23:31.000Z"
    }
  ]
}

That's it! You can now lookup the storage usage and allocation of any Farcaster user.

🚀

Ready to start building?

Get your subscription at neynar.com and reach out to us on Telegram with any questions!