# Technical Architecture

The Virality Leaderboard is built on a transparent, data-driven architecture engineered to quantify attention with precision and distribute rewards with verifiable fairness. 

This section provides a complete technical breakdown of both core modules: **Infomarket** (the mindshare indexing engine) and **City Rewards** (the programmable incentive distribution layer).

<figure><img src="/files/H2Ry7iqGMEhnjYT5ufoE" alt=""><figcaption></figcaption></figure>

***

### Infomarket Architecture

<figure><img src="/files/Y4PIFbnlhBJQ2DCC3aSC" alt=""><figcaption></figcaption></figure>

***

### Market Map: Treemap Visualization

The Market Map renders the top 15 projects by mindshare as a weighted treemap. Each block represents a single indexed project, and the visual encoding is as follows:

<figure><img src="/files/g6E1ssrUd8v1lW0B4K2j" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="142.3203125">Property</th><th>Encoding</th></tr></thead><tbody><tr><td><strong>Size</strong></td><td>Proportional to mindshare percentage. Larger block = higher relative attention dominance.</td></tr><tr><td><strong>Color</strong></td><td>Green indicates a positive trend; red indicates a negative trend, computed against the currently selected time window.</td></tr><tr><td><strong>Content</strong></td><td>Displays the project slug, current mindshare percentage, and trend delta.</td></tr><tr><td><strong>Sparkline</strong></td><td>An embedded mini-chart plotting the project's recent mindshare trajectory over time.</td></tr><tr><td><strong>Rank Badge</strong></td><td>Medal indicator for the top three projects by mindshare.</td></tr></tbody></table>

Clicking any block navigates to the corresponding Project Detail page.

***

#### Time Window Configuration

All Infomarket views support multiple temporal scopes. Users can toggle between the following time windows, each defining the boundaries of the aggregation period:

<table><thead><tr><th width="111.2734375">Window</th><th>Scope</th></tr></thead><tbody><tr><td><strong>TODAY</strong></td><td>Since 00:00 UTC of the current day.</td></tr><tr><td><strong>WTD</strong></td><td>Week-to-date, starting Monday 00:00 UTC.</td></tr><tr><td><strong>MTD</strong></td><td>Month-to-date, starting the 1st of the current month.</td></tr><tr><td><strong>QTD</strong></td><td>Quarter-to-date.</td></tr><tr><td><strong>YTD</strong></td><td>Year-to-date.</td></tr><tr><td><strong>Trend</strong></td><td>A 72-hour rolling window with exponential time decay. More recent content is weighted more heavily than older content within the window. This is the primary signal for identifying real-time momentum and surfacing what is gaining traction right now.</td></tr></tbody></table>

The distinction between **Trend** and **Calendar Windows** is fundamental to how Infomarket surfaces different types of signal. Trend captures velocity: a viral cast from two days ago contributes less weight than one published yesterday. Calendar windows capture cumulative volume: total engagement across the full period with no decay applied, making them better suited for reporting and historical comparison.

***

#### Sidebar: Top Gainers and Top Losers

The sidebar module surfaces projects exhibiting the sharpest mindshare movements within the selected time window:

<table><thead><tr><th width="138.07421875">View</th><th>Definition</th></tr></thead><tbody><tr><td><strong>Top Gainers</strong></td><td>Projects with the largest positive mindshare delta for the selected period.</td></tr><tr><td><strong>Top Losers</strong></td><td>Projects with the largest negative mindshare delta for the selected period.</td></tr></tbody></table>

The sidebar also exposes aggregate ecosystem statistics including total indexed projects, total coverage percentage, average mindshare change, and the ratio of gainers to losers. Clicking any project in the sidebar navigates to its detail page.

***

#### Project Detail Page

Each project's detail page provides a granular breakdown of the contributors and content driving its mindshare score.

**Top Contributors** ranks creators who contributed the most to the project's mindshare within the selected window. Each entry displays the creator's rank, display name, username handle, follower count, cast count, and individual contribution score.

**Top Casts** surfaces the highest-performing casts mentioning the project, displaying the author, publication date, cast content, and a full engagement breakdown including likes, recasts, and replies.

***

#### Creator Detail Page

Each creator profile provides both quantitative metrics and behavioral classification.

**Raw Activity (7D)** displays the creator's trailing seven-day output: total casts, likes received, recasts received, replies received, and a composite engagement score.

**Behavioral Attributes** classify each creator along two axes:

<table><thead><tr><th width="135.44921875">Attribute</th><th width="150.9609375">Classification</th><th>Criteria</th></tr></thead><tbody><tr><td><strong>Activity Level</strong></td><td>Casual / Moderate / Hardcore</td><td>Based on average casts per day. Casual is fewer than 1 cast/day, Moderate is 1 to 2 casts/day, Hardcore is greater than 3 casts/day.</td></tr><tr><td><strong>Impact Style</strong></td><td>Volume Focused / Balanced / Quality Curator</td><td>Based on average engagement per cast. Volume Focused indicates lower per-cast engagement, Balanced indicates medium, and Quality Curator indicates consistently higher engagement yield per cast.</td></tr></tbody></table>

**Top Projects** lists projects the creator has contributed to, with individual contribution scores for each. **Top Casts** surfaces their highest-performing content with full engagement metrics.

***

#### Key Metrics Reference

<table><thead><tr><th width="129.31640625">Metric</th><th width="305.4921875">Definition</th><th>Use Case</th></tr></thead><tbody><tr><td><strong>Mindshare %</strong></td><td>A project's proportional share of total ecosystem attention. All indexed projects sum to 100%.</td><td>Relative attention dominance across the ecosystem.</td></tr><tr><td><strong>Change (Δ)</strong></td><td>Percentage change in mindshare compared to the previous equivalent period. Green indicates an increase; red indicates a decrease.</td><td>Identifying acceleration or decay in attention capture.</td></tr><tr><td><strong>Top Curators vs. Most Active</strong></td><td>Curators are ranked by quality (average score per cast). Most Active are ranked by volume (casts per day).</td><td>Curators surface influential voices; Most Active surfaces frequent contributors. These are intentionally separate rankings because high volume does not imply high influence.</td></tr></tbody></table>

***

### City Rewards Architecture

#### Campaign Task Types

Each City Rewards campaign is composed of discrete, verifiable tasks. The system currently supports four task types, each mapped to a specific engagement action:

<table><thead><tr><th width="127.21484375">Task Type</th><th width="246.2265625">Description</th><th>Required Configuration</th></tr></thead><tbody><tr><td><strong>Follow</strong></td><td>Participant must follow one or more specified Farcaster accounts.</td><td>Handle and FID (Farcaster ID) per target. FID is required for on-chain verification. Multiple targets can be specified per task. If Handle is omitted, FID alone is used for verification.</td></tr><tr><td><strong>Post</strong></td><td>Participant must publish posts containing required keywords or mentions on a specified platform.</td><td>Platform (Farcaster, Base, or X), post text template (optional), required keywords, required mention handles, and minimum post count (default: 1).</td></tr><tr><td><strong>Mindshare Growth</strong></td><td>Participant must contribute posts that increase a target project's mindshare score on the Infomarket leaderboard.</td><td>Project slug and post text. Any project currently featured on Infomarket can be selected as a target, enabling cross-project collaborative campaigns.</td></tr><tr><td><strong>Description</strong></td><td>An informational block displayed to participants. No verification is required.</td><td>Description text only.</td></tr></tbody></table>

***

#### Campaign Step Schema

Each campaign contains an ordered `steps` array with a minimum of 1 and a maximum of 50 steps. Each step is defined by the following fields:

<table><thead><tr><th width="200.796875">Field</th><th width="135.50390625">Required</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>steps[].id</code></td><td>Yes</td><td>Unique identifier within the campaign scope.</td><td><code>"follow"</code></td></tr><tr><td><code>steps[].type</code></td><td>Yes</td><td>The social action type to be verified.</td><td><code>"FOLLOW_ACCOUNT"</code></td></tr><tr><td><code>steps[].title</code></td><td>Yes</td><td>User-facing task title displayed in the campaign UI.</td><td><code>"Follow @polymarket on Base App"</code></td></tr><tr><td><code>steps[].description</code></td><td>Yes</td><td>Detailed instruction text for the participant.</td><td><code>"Follow the official project account."</code></td></tr><tr><td><code>steps[].target_id</code></td><td>No</td><td>Farcaster entity identifier for the verification target.</td><td><code>"fid:12345"</code> or <code>"cast:0xPM1024"</code></td></tr><tr><td><code>steps[].sort_order</code></td><td>No</td><td>Display order within the campaign UI (0-indexed).</td><td><code>0</code></td></tr></tbody></table>

Supported action types: `FOLLOW_ACCOUNT`, `LIKE_POST`, `COMMENT_POST`, `REPOST_POST`.

***

#### Task Participation Metrics

The system tracks granular participation data for every active campaign:

<table><thead><tr><th width="183.26171875">Metric</th><th>Definition</th></tr></thead><tbody><tr><td><strong>Participants</strong></td><td>Total unique users who have joined the campaign.</td></tr><tr><td><strong>Completed</strong></td><td>Users who have successfully verified all tasks.</td></tr><tr><td><strong>In Progress</strong></td><td>Users who have verified at least one but not all tasks.</td></tr><tr><td><strong>Not Started</strong></td><td>Users who joined but have not yet verified any task.</td></tr><tr><td><strong>Avg Completion</strong></td><td>Average completion rate across all participants.</td></tr><tr><td><strong>Total Tasks</strong></td><td>Total number of discrete tasks within the campaign.</td></tr></tbody></table>

***

#### Progress Tracking

Participant progress is displayed as "X/Y Verified" alongside a percentage completion bar. The bar renders green at 100% completion and accent blue for all intermediate states. A "Completed" badge is applied to the campaign card upon full verification of all steps. The timestamp of the most recent successful verification is displayed after the first verified step. All progress is tracked on a per-user, per-campaign basis.

***

#### Verification Rules

All verification requests are subject to the following constraints:

<table><thead><tr><th width="189.765625">Rule</th><th>Specification</th></tr></thead><tbody><tr><td><strong>Campaign Identity</strong></td><td>Each campaign must have a globally unique <code>id</code>.</td></tr><tr><td><strong>Required Fields</strong></td><td><code>name</code>, <code>handle</code>, <code>tag</code>, <code>category</code>, <code>rewardPool</code>, <code>rewardSub</code>, <code>recipients</code>, <code>activityPeriod</code>, <code>distribution</code>, <code>steps</code>.</td></tr><tr><td><strong>Timing</strong></td><td>The Verify button is disabled for campaigns that have not yet started or have already ended.</td></tr><tr><td><strong>API Validation</strong></td><td>Each verification request requires <code>campaignId</code>, <code>accountHandle</code>, and a <code>steps</code> array.</td></tr><tr><td><strong>Step Limit</strong></td><td>Maximum of 50 steps per verification request.</td></tr><tr><td><strong>Authentication</strong></td><td>User must be signed in to trigger verification.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://city-protocol.gitbook.io/docs/attention-as-a-servcie/virality-leaderboard/technical-architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.