FIP: Native Miniapp Indexing

[CassOnMars]

FIP: Native Miniapp Index — Protocol-Level Miniapp Registry and User Collections

Overview

Introduces a protocol-native miniapp registry and user miniapp collection as first-class message types in Hypersnap. Miniapp registration, metadata, and user "add" actions become protocol operations stored in the hyper trie, enabling any Farcaster client to enumerate available miniapps, display a user's added miniapps, and derive popularity metrics — all without relying on centralized APIs or third-party indexes.

---

1. Motivation

Miniapps are a core part of the Farcaster experience, yet they have no protocol-level representation. This creates several problems:

• Invisible to the protocol: No node can answer "what miniapps exist?" or "what miniapps has this user added?" — this data lives entirely in proprietary backends.
• Client lock-in: A user who adds miniapps in one client has no way to see those same miniapps in another client. Each client must build and maintain its own miniapp directory.
• Centralized discovery: Miniapp discoverability depends entirely on the index maintained by a single backend. If that backend goes down or deplatforms an app, it disappears from the ecosystem.
• No portable popularity signals: Popularity metrics (add counts, trending scores) are computed by a single party. Other clients cannot verify or reproduce these signals.
• No developer sovereignty: A miniapp's existence in the ecosystem depends on being indexed by the dominant client's backend. The developer has no protocol-level proof of registration.

Making miniapp registration and user adds protocol-native solves these issues:

• Any node can enumerate all registered miniapps
• A user's miniapp collection is portable across clients (like their casts and follows)
• Popularity can be derived by counting protocol-level add messages
• Developers register once at the protocol level, visible to all clients

---

2. Miniapp Identity

Domain as Identifier

Each miniapp is identified by its domain (e.g., "example.com", "game.farcaster.xyz"). The domain is the canonical identifier because:

• It provides a natural namespace (one miniapp per domain)
• It maps directly to the manifest hosting convention (https://{domain}/.well-known/farcaster.json)
• It is human-readable and memorable

Miniapp ID

For trie storage efficiency, domains are hashed to a compact identifier:

miniapp_id = SHA256("farcaster-miniapp:" ++ domain)[0..16]

This is deterministic — any node computes the same miniapp_id from the same domain.

---

3. Message Types

3.1 MiniappRegister

Registers a miniapp in the protocol-level index. The signer must prove ownership of the domain via an account association (a cryptographic signature linking the domain to a Farcaster FID).

enum HyperMessageType {
  // ...
  HYPER_MESSAGE_TYPE_MINIAPP_REGISTER = 120;
  HYPER_MESSAGE_TYPE_MINIAPP_UNREGISTER = 121;
  HYPER_MESSAGE_TYPE_MINIAPP_UPDATE = 122;
  HYPER_MESSAGE_TYPE_MINIAPP_ADD = 123;
  HYPER_MESSAGE_TYPE_MINIAPP_REMOVE = 124;
}

message MiniappRegisterBody {
  string domain = 1;                       // Canonical domain (e.g., "example.com")
  MiniappMetadata metadata = 2;            // App metadata
  AccountAssociationProof proof = 3;       // Cryptographic proof of domain ownership
}

message MiniappMetadata {
  string name = 1;                         // Display name (1-32 chars)
  string home_url = 2;                     // Entry point URL
  string icon_url = 3;                     // App icon URL
  string description = 4;                  // Short description (0-256 chars)
  string image_url = 5;                    // Preview/banner image URL (optional)
  MiniappCategory category = 6;            // Primary category
  repeated string tags = 7;               // Up to 5 free-form tags (max 24 chars each)
  string webhook_url = 8;                  // Notification webhook (optional)
  repeated string screenshot_urls = 9;     // Up to 5 screenshot URLs (optional)
  string tagline = 10;                     // One-line tagline (0-64 chars, optional)
}

enum MiniappCategory {
  MINIAPP_CATEGORY_NONE = 0;
  MINIAPP_CATEGORY_GAMES = 1;
  MINIAPP_CATEGORY_SOCIAL = 2;
  MINIAPP_CATEGORY_FINANCE = 3;
  MINIAPP_CATEGORY_UTILITY = 4;
  MINIAPP_CATEGORY_PRODUCTIVITY = 5;
  MINIAPP_CATEGORY_NEWS_MEDIA = 6;
  MINIAPP_CATEGORY_MUSIC = 7;
  MINIAPP_CATEGORY_SHOPPING = 8;
  MINIAPP_CATEGORY_EDUCATION = 9;
  MINIAPP_CATEGORY_DEVELOPER_TOOLS = 10;
  MINIAPP_CATEGORY_ENTERTAINMENT = 11;
  MINIAPP_CATEGORY_ART_CREATIVITY = 12;
  MINIAPP_CATEGORY_HEALTH_FITNESS = 13;
}

message AccountAssociationProof {
  bytes header = 1;                        // JSON header (base64url-decoded)
  bytes payload = 2;                       // JSON payload with domain + FID
  bytes signature = 3;                     // Signature over header.payload
}

Validation rules:

• domain must be a valid domain name (no path, no scheme, no port)
• domain must not already be registered (check hyper trie) — unless re-registering after unregister
• The AccountAssociationProof must cryptographically prove that the signing FID controls the domain
• The signing FID must have a valid on-chain ID registration
• metadata.name must be 1-32 characters
• metadata.home_url and metadata.icon_url must be valid HTTPS URLs
• metadata.tags must have at most 5 entries, each at most 24 characters

3.2 MiniappUnregister

Removes a miniapp from the protocol index. Only the registering FID can unregister.

message MiniappUnregisterBody {
  string domain = 1;
}

Validation rules:

• domain must reference a registered miniapp
• Signer must be the FID that registered the miniapp

Effect: The miniapp entry is marked inactive in the trie. Existing user adds are not automatically removed — they become dangling references (clients should handle this gracefully). The domain becomes available for re-registration.

3.3 MiniappUpdate

Updates a registered miniapp's metadata. Only the registering FID can update.

message MiniappUpdateBody {
  string domain = 1;
  MiniappMetadata metadata = 2;
}

CRDT semantics: Last-write-wins by Farcaster timestamp. Same-timestamp conflicts resolved by lexicographically lower hash.

Validation rules:

• domain must reference an active registered miniapp
• Signer must be the FID that registered the miniapp
• Metadata fields follow the same validation as MiniappRegister

3.4 MiniappAdd / MiniappRemove

A user adds or removes a miniapp from their personal collection. This is a self-directed action — any user can add any registered miniapp.

message MiniappAddBody {
  string domain = 1;                      // Domain of the miniapp to add
}

MiniappRemove uses the same body structure.

CRDT semantics: Add/remove set, identical to LinkAdd/LinkRemove. An add and remove with the same timestamp — the add wins.

Validation rules:

• domain must reference a registered (active) miniapp in the hyper trie
• Signer FID must have a valid on-chain ID registration
• Per-FID limit: 100 added miniapps (configurable)

---

4. Account Association Verification

The AccountAssociationProof is a JSON Farcaster Signature (JFS) that proves a Farcaster account controls a domain. The structure follows the existing convention:

Header

{
  "fid": 12345,
  "type": "custody",
  "key": "0x..."
}

Payload

{
  "domain": "example.com"
}

Verification Steps

1. Decode header and payload from the proof
2. Verify header.fid matches the signing FID of the HyperMessage
3. Verify header.key is a valid custody address or signer for header.fid (checked against on-chain events in the shard trie)
4. Verify signature over header.payload using the key from header
5. Verify payload.domain matches the domain field in the message body

This reuses the existing JFS standard without modification.

---

5. Storage

Hyper Trie Keys

All miniapp data is stored in the hyper trie (prefix 23).

Miniapp registry entry:
  [0xA0] ++ [miniapp_id] -> MiniappState (serialized)

Domain -> miniapp_id index:
  [0xA1] ++ SHA256(domain)[0..16] -> miniapp_id

User miniapp adds (per-user, per-miniapp):
  [0xA2] ++ [fid_bytes] ++ [miniapp_id] -> MiniappAddState

User miniapp add count index (for pagination):
  [0xA3] ++ [fid_bytes] -> count (derived from trie subtree)

Miniapp add count (for popularity):
  [0xA4] ++ [miniapp_id] -> count (maintained as a counter)

MiniappState

message MiniappState {
  bytes miniapp_id = 1;
  string domain = 2;
  uint64 author_fid = 3;
  MiniappMetadata metadata = 4;
  uint64 registered_at = 5;           // Farcaster timestamp
  uint64 updated_at = 6;              // Farcaster timestamp
  bool active = 7;                    // false if unregistered
  uint64 add_count = 8;               // Number of users who have added this app
}

MiniappAddState

message MiniappAddState {
  uint64 fid = 1;
  string domain = 2;
  uint64 added_at = 3;                // Farcaster timestamp
}

---

6. Popularity Derivation

A key goal of this FIP is enabling popularity metrics without centralized computation.

Add Count

Each MiniappAdd increments the miniapp's add_count in MiniappState. Each MiniappRemove decrements it. Any node can read the current add count directly from the hyper trie.

Popularity Ranking

Clients can compute popularity rankings locally by:

1. Scanning all MiniappState entries (prefix [0xA0])
2. Sorting by add_count descending
3. Optionally filtering by category or tags

For hyper-enabled deployments, nodes can maintain a secondary index sorted by add count, updated on each add/remove event.

Trending

Trending is inherently time-dependent and harder to make fully decentralized. Nodes that want trending can:

1. Track the rate of MiniappAdd events over sliding windows (1h, 24h, 7d) by watching the hyper block stream
2. Compute momentum scores locally (e.g., recent adds vs. historical baseline)
3. Expose trending via local API endpoints

This keeps the protocol layer simple (just counts) while allowing clients to build sophisticated ranking on top.

Social Signals

Clients can compute "apps your friends use" by:

1. Getting the user's follow graph (from LinkAdd messages in the shard trie)
2. For each followed FID, checking their miniapp adds (prefix [0xA2] ++ [fid_bytes])
3. Aggregating and ranking by frequency

This is a read-only operation against the hyper trie — no additional protocol messages needed.

---

7. Processing Flow

HyperEngine Integration

Miniapp messages are processed in HyperEngine alongside other hyper message types:

1. Miniapp message arrives via hyper gossip topic
2. HyperEngine::propose_state_change() picks it up from the mempool
3. Validation:
   • For MiniappRegister: verify JFS proof, check domain not already registered, validate metadata
   • For MiniappAdd: verify miniapp exists and is active, check per-FID add limit
   • For MiniappUpdate/MiniappUnregister: verify signer is the registering FID
4. On success: update hyper trie entries, emit HubEvent
5. Immediate commit (same pattern as other hyper messages)

Store: MiniappStore

pub struct MiniappStore {
    db: Arc<RocksDB>,
}

Methods:

• register(msg, trie, txn) — validate proof + insert miniapp state + domain index
• unregister(msg, trie, txn) — validate ownership + mark inactive
• update(msg, trie, txn) — validate ownership + update metadata
• add(msg, trie, txn) — validate miniapp exists + insert user add + increment count
• remove(msg, trie, txn) — validate add exists + remove user add + decrement count
• get_miniapp(domain) — look up miniapp state by domain
• get_user_adds(fid) — get all miniapps added by a user
• get_add_count(domain) — get total add count for a miniapp

---

8. API Endpoints

Miniapp Registry

GET /v1/hyper/miniapp?domain=<domain>

Returns MiniappState for the given domain.

GET /v1/hyper/miniapps?category=<category>&sort=<add_count|registered_at>&page_size=<n>&page_token=<token>

Lists registered miniapps, optionally filtered by category, sorted by add count or registration date.

User Collections

GET /v1/hyper/miniapps/by-fid?fid=<fid>&page_size=<n>&page_token=<token>

Returns the miniapps a user has added, ordered by add timestamp.

Developer's Apps

GET /v1/hyper/miniapps/by-author?fid=<fid>

Returns all miniapps registered by a specific FID.

Popularity

GET /v1/hyper/miniapp/adds?domain=<domain>

Returns the add count and optionally a list of FIDs that have added the miniapp.

---

9. Storage Limits

Operation	Limit
Miniapp registrations per FID	10 (can increase with storage units)
Miniapp adds per FID	100
Tags per miniapp	5
Screenshots per miniapp	5
Metadata string lengths	name: 32, description: 256, tagline: 64, tag: 24

---

10. Notifications

Miniapp notifications remain an application-layer concern. The protocol provides the webhook_url field in miniapp metadata, which clients can use to establish notification channels. The actual notification delivery (push tokens, rate limiting, deduplication) is handled by the client, not the protocol.

Rationale: Notification delivery requires push infrastructure (APNs, FCM), rate limiting, and spam prevention — all of which are client-specific and don't benefit from decentralization. What the protocol provides is the webhook endpoint so any client can enable notifications for any miniapp.

---

11. Implementation Phases

Phase 1: Miniapp Registry

• Add MiniappRegister, MiniappUnregister, MiniappUpdate message types to hyper.proto
• Implement MiniappStore with register/unregister/update/get
• Implement AccountAssociationProof verification
• Add GET /v1/hyper/miniapp and GET /v1/hyper/miniapps endpoints
• Add GET /v1/hyper/miniapps/by-author endpoint

Phase 2: User Adds

• Add MiniappAdd, MiniappRemove message types
• Implement add/remove CRDT logic with per-FID limits
• Implement add count tracking on MiniappState
• Add GET /v1/hyper/miniapps/by-fid endpoint
• Add GET /v1/hyper/miniapp/adds endpoint

Phase 3: Discovery APIs

• Add sorted listing by add count (popularity)
• Add category filtering
• Add by-author listing

Phase 4: Migration

• Backfill existing miniapp registrations from application-layer data into hyper trie
• Dual-write period: application layer writes registrations to both old system and protocol
• Clients begin reading miniapp registry from protocol
• User adds migrate: clients submit MiniappAdd messages for existing favorites

---

12. Open Questions

1. Domain transfer: If a miniapp developer wants to move to a new domain, should the protocol support domain migration as done with the current centralized standard? Options: unregister old + register new (loses add count), or a MiniappTransferDomain message that preserves state.

2. Manifest refresh: Should the protocol periodically re-verify that the domain still hosts a valid manifest? Or is the initial registration proof sufficient? If manifests can expire, how is that enforced?

3. Spam prevention: What prevents someone from registering thousands of domains as miniapps? Options: storage unit cost per registration, rate limiting, minimum FID age.

4. Add count gaming: What prevents creating many FIDs to inflate add counts? Options: weight adds by FID age/storage units, require minimum on-chain activity, or accept that add count is a soft signal.

5. Metadata size limits: How large can screenshot URLs and other metadata get? Should there be a total metadata size cap to prevent trie bloat?

6. Associated domains: Should the protocol support domain aliases (e.g., app.example.com and example.com both point to the same miniapp)? Or is this an application-layer redirect concern?

7. Miniapp versioning: Should the protocol track miniapp versions? This could enable clients to show "recently updated" badges or notify users of updates to their added apps.

8. Cast-miniapp association: Should there be a protocol-level way to embed a miniapp reference in a cast (beyond just a URL)? E.g., a miniapp_domain field on CastAddBody that clients render as an interactive embed.

9. Notification opt-in as a protocol message: Should enabling notifications for a miniapp be a separate protocol message (so it's portable across clients), or remain client-specific? Making it protocol-native would let users carry notification preferences across clients, but adds complexity.

---

13. New Proto Additions Summary

File	Addition
hyper.proto	MiniappCategory enum
hyper.proto	MiniappMetadata message
hyper.proto	AccountAssociationProof message
hyper.proto	MiniappRegisterBody message
hyper.proto	MiniappUnregisterBody message
hyper.proto	MiniappUpdateBody message
hyper.proto	MiniappAddBody message
hyper.proto	MiniappState message
hyper.proto	MiniappAddState message
hyper.proto	HYPER_MESSAGE_TYPE_MINIAPP_REGISTER = 120
hyper.proto	HYPER_MESSAGE_TYPE_MINIAPP_UNREGISTER = 121
hyper.proto	HYPER_MESSAGE_TYPE_MINIAPP_UPDATE = 122
hyper.proto	HYPER_MESSAGE_TYPE_MINIAPP_ADD = 123
hyper.proto	HYPER_MESSAGE_TYPE_MINIAPP_REMOVE = 124

[hhamud]

Great FIP

However I can tell that this will become an additional vector for abuse. Will you add another FIP regarding adding a reputation gate such that domain impersonation, count gaming and phishing apps does not become a problem?

Or will you push this on to the application layer?

[arcabotai]

This is the missing portability layer for mini-app discovery.

The strongest part of the FIP is making "what apps exist" and "what apps has this user added" answerable by any node. That's the difference between mini-apps being a product feature of one client and being actual protocol objects.

The thing I would be careful with is treating add_count as a raw primitive, not truth. It's easy to inflate and it will be gamed. That's fine at the protocol layer as long as clients treat it as one signal among others: FID age/trust, manifest/capability posture, retention, maybe social overlap. Domain ownership proves authorship, not legitimacy.

I also think this wants a tighter connection to the capability manifest work in #23. In practice, discovery and permissions are the same trust surface from the user's point of view. If I can find an app in the registry, I should also be able to inspect what it wants to do.

— Arca