ecosystem/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the Logos Ecosystem Wiki - a static site built with Quartz 4 to document Logos ecosystem-related information. The repository may be made public in the future, so never commit sensitive information.

The content focuses on the Integration effort which enables bi-directional feedback between the Logos technical stack and community by identifying technological needs, translating them into requirements, and propagating information about deliveries to encourage ecosystem building.

---

For Content Contributors

Quick Start

Primary workflow:

1. Open content/ folder as Obsidian vault (see Content Management section below)
2. Create or edit markdown files following the structure templates
3. Use wikilinks [[path/to/file|Display Text]] to connect concepts
4. Add > [!ai-generated] indicator after section headers for LLM-generated content
5. Run "check" command to validate structure and links

File naming convention:

• Use underscores instead of spaces: activity_hub.md not Activity Hub.md

Integration Content Taxonomy

The Integration effort organizes content into three main categories:

1. Infrastructure Essentials (infrastructure_essentials/)

What belongs here: Core blockchain infrastructure that the network needs to operate and be accessible

Examples:

• Block explorers
• RPC endpoints and infrastructure
• Indexers and data availability layers
• Network monitoring and analytics
• Faucets and testnets
• Logos Storage
• Logos Messaging

2. Application Essentials (application_essentials/)

What belongs here: Developer tools and primitives needed to build applications on Logos

Examples:

• Smart contract toolchain (compilers, debuggers, testing frameworks)
• Development environments and IDEs
• Token creation standards and tools
• On-chain primitives (storage, compute, messaging)
• UI libraries and component kits
• SDK and API libraries
• Contract templates and boilerplates

3. Desired Projects (desired_projects/)

What belongs here: End-user applications and ecosystem projects that provide value to users

Examples:

• DeFi protocols (stablecoins, lending, DEXs)
• NFT marketplaces
• DAOs and governance tools
• Social applications
• Entity formation and legal tools
• Gaming and consumer apps

---

Creating Integration Content

Determining the Right Category

Use this decision tree:

1. Is it infrastructure for network access/visibility? → infrastructure_essentials/

   • Block explorers, RPCs, indexers, monitoring, Logos Storage, Logos Messaging

2. Is it a tool/primitive for developers to build apps? → application_essentials/

   • Toolchains, SDKs, standards, templates, on-chain primitives

3. Is it an end-user application or protocol? → desired_projects/

   • DeFi, NFTs, DAOs, social apps, marketplaces

Standard Structure Template

All integration content files follow this structure:

---
title: Project Name
type: Desired Project | Core Primitive
priority:
flywheel: Liquidity | Security | Network Effects | Capital Efficiency
category: See category list below
---

Brief description paragraph (1-2 sentences explaining what the project does and why it matters).

> [!ai-generated]
> This entire document was generated by an LLM and has not yet been human-reviewed.

## FURPS+

### Functionality
- Core capabilities (what the system must DO)
- 5-8 concise numbered points maximum
- Focus on essential features, not implementation details

### Usability (optional)
- User experience and developer experience points
- 3-5 numbered points maximum

### Reliability (optional)
- Fault tolerance and recovery mechanisms
- 3-4 numbered points maximum

### Performance (optional)
- Critical performance requirements only
- 2-4 numbered points maximum

### Supportability (optional)
- Maintenance and extensibility concerns
- 2-3 numbered points maximum

### + (Privacy, Anonymity, Censorship-Resistance)

**IMPORTANT**: Keep this section concise (4-6 bullets). Focus on:
- **Privacy**: How user data and transaction details are protected
- **Anonymity**: How user identities and patterns are hidden
- **Security**: Key cryptographic guarantees
- **Censorship-Resistance**: How availability is ensured

Example (concise format):
- **Privacy**: Private transaction history not publicly visible
- **Anonymity**: Anonymous participation without identity disclosure
- **Security**: End-to-end encryption for sensitive operations
- **Censorship-Resistance**: Decentralized infrastructure prevents single points of failure

## Demand Validation

**Potential Users:** Description of target user groups

**Use Cases:**
- Specific scenario 1
- Specific scenario 2
- Specific scenario 3

## Possible Implementation

- **Implementation approach 1**: Brief description with key technical details
- **Implementation approach 2**: Alternative approach with trade-offs
- Technical considerations, protocols, or architectures

## Technical Validation

**Risks & Challenges:**
- Technical risk 1
- Implementation challenge 1
- Open research question 1

**Dependencies:** (optional)
List other projects, infrastructure, or tools required for this project to work:
- [[integration/desired_projects/other_project|Other Project Name]]
- External systems or protocols required
- Logos technology stack components needed

**Integration Points:** (optional)
- [[integration/desired_projects/related_project|Related Project]] for specific integration
- External systems or protocols
- Logos technology stack components

## Additional Project-Specific Sections (optional)

You may add project-specific sections as needed (e.g., "Gamification", "Sub-portals", "Tokenomics").
Place these AFTER the standard sections.

Writing FURPS+ Guidelines

Based on industry best practices, follow these principles when writing FURPS+ requirements:

General Principles:

• Use FURPS+ as a checklist for coverage, not rigid categorization
• Focus on specific, measurable, actionable requirements
• Avoid technical jargon - write for all stakeholders (developers to executives)
• Keep requirements testable and verifiable
• Prioritize essential requirements over exhaustive lists

Writing Effective Bullets:

• ✅ Be Specific: "Process 10,000 requests/second" not "perform well"
• ✅ Be Measurable: Include metrics, thresholds, or clear criteria
• ✅ Be Concise: One requirement per bullet point
• ✅ Be Actionable: Focus on "what" not "how"
• ❌ Avoid Vague Terms: "fast", "secure", "scalable" need quantification

Good vs Bad Examples:

Good ✅	Bad ❌
Support 1000 concurrent users with <2s response time	System should be fast and scalable
Encrypt all user data at rest using AES-256	Data should be secure
99.9% uptime (max 8.76 hours downtime/year)	System should be reliable
Complete transaction in <500ms under normal load	Transactions should be quick
Private transaction history not publicly visible	Good privacy

Category-Specific Guidance:

• Functionality: Core capabilities and feature set (what system must DO)
• Usability: Human factors, consistency, ease of use, documentation
• Reliability: Mean time between failures, recoverability, accuracy
• Performance: Response time, throughput, resource consumption limits
• Supportability: Testability, maintainability, extensibility, compatibility, platforms
• + (Privacy): Specific privacy, anonymity, censorship-resistance guarantees

Choosing Frontmatter Values

type:

• Desired Project: Standard ecosystem application or service
• Core Primitive: Foundational infrastructure component

priority:

• IMPORTANT: When creating new entries, ALWAYS leave this field empty
• 0-9: Numeric priority (0 = highest, see content/integration/concerns/sustainability.md for tier definitions)
• Priority is assigned later through dedicated prioritization processes
• Empty: Unassigned priority (this is the default and expected state for new entries)

flywheel: Choose the primary economic flywheel this project drives:

• Liquidity: Attracts capital and trading activity (DEXs, lending, stablecoins)
• Security: Secures the network and user assets (staking, multisig, custody)
• Network Effects: Grows with user adoption (social apps, DAOs, marketplaces)
• Capital Efficiency: Maximizes utility of locked capital (liquid staking, lending)

category: Existing categories include:

• DeFi Core: Fundamental DeFi primitives (DEX, lending, stablecoins)
• Advanced DeFi: Sophisticated financial instruments (derivatives, perps)
• Infrastructure: Base-layer services (bridges, oracles)
• Custody & Security: Asset protection (multisig, vaults)
• Staking & Security: Network security mechanisms
• NFTs & Identity: Digital ownership and identity
• Governance: Decision-making systems (DAOs)
• Token Infrastructure: Token creation and distribution (launchpads)
• Consumer Apps: End-user applications (social, gaming)
• Organisation Tools: Team coordination (CMS, project management)
• Movement Tools: Logos movement-specific tools (activity hub)
• Winnable Issues: Projects addressing specific movement goals

Create a new category if none fit, using Title Case.

Wikilink Best Practices

When to add wikilinks:

• First mention of another desired project in the document
• Key integration points in "Technical Validation" or "Integration Points" sections
• Dependencies section (always link)

When NOT to add wikilinks:

• Repeated mentions of the same project within a document (link only the first)
• Generic references (e.g., "users need a DEX" vs "integrate with integration/desired_projects/private_dex")
• Within section headers

Format:

[[integration/desired_projects/file_name|Display Name]]

⚠️ Content Authorship Indicators

CRITICAL: This applies to ALL files in content/ folder - integration docs, processes, protocols, guides, and any other generated documents.

To clearly distinguish LLM-generated content from human-curated content, use the following markdown blockquote indicator:

LLM-Generated Content Marker

> [!ai-generated]
> This section was generated by an LLM and has not yet been human-reviewed.

Scope Rules:

• IMPORTANT: The indicator belongs to a whole section and must ALWAYS be placed immediately after the section header (before any content)
• The indicator applies to the entire section, including all subsections, until the next same-level or higher-level header
• A section ends when you reach another header at the same level (e.g., ## to ##) or higher level (e.g., ### to ##)

Placement Guidelines:

For entirely AI-generated files (RECOMMENDED DEFAULT): place a single indicator at the very top of the file (after frontmatter and description) to cover the entire document - this applies to integration content, process documents, protocols, and any other content type

For partially AI-generated files:

• Place the indicator only under sections that are AI-generated
• Each major section (##) that is AI-generated needs its own indicator

Examples:

Example 1: Entire file is AI-generated (recommended approach)

---
title: Example Project
---

Brief description of the project.

> [!ai-generated]
> This entire document was generated by an LLM and has not yet been human-reviewed.

## FURPS+

### Functionality
1. Statement 1

## Demand Validation
...

Example 2: Only FURPS+ section is AI-generated

## FURPS+

> [!ai-generated]
> This section was generated by an LLM and has not yet been human-reviewed.

### Functionality
1. Statement 1
2. Statement 2

### + (Privacy, Anonymity, Censorship-Resistance)
- Statement 3

## Demand Validation

**Potential Users:** (manually written, no indicator)

After human review: Simply remove the > [!ai-generated] block from reviewed sections, leaving only the content.

Content Quality Commands

"check" Command

When the user says "check", perform comprehensive quality assurance checks on the repository.

All check instructions are in AGENT-CHECK.md - refer to that file for:

• Complete checklist of all quality assurance tasks
• Automated bash commands for each check
• Expected outputs and reporting format
• Common issues and how to fix them

Note: Always exclude the tmp/ directory when running checks.

Content Management Best Practices

Obsidian Integration

Open the content/ folder (not repo root) as Obsidian vault:

• Enable "Automatically update internal links"
• Set link format to "Absolute path in vault"
• Enable Wikilinks
• Use Templater plugin with templates/ folder for auto-populated files

Ignore Patterns

The following are ignored by Quartz (configured in quartz.config.ts):

• private/ - Private notes not for publication
• templates/ - Obsidian templates
• .obsidian/ - Obsidian configuration

---

Logos Integration Framework Reference

Mission

The Integration effort establishes bi-directional feedback between the Logos technical stack and ecosystem by:

• Identifying and evaluating technological needs of the community
• Translating needs into requirements for the technology stack
• Propagating information about deliveries to encourage building and contribution

Prioritization Framework

Three primary concerns drive requirement prioritization (defined in content/integration/index.md):

1. Sustainability: Enable onchain activity and value accrual to sustain technology stack development
2. Movement: Provide technological solutions for the movement to organize and solve winnable issues
3. Technology De-Risking: Enable early delivery and validation of technology with highest unknowns and risks

Priority tiers are documented in content/integration/concerns/sustainability.md (0 = highest priority).

Privacy-First Principles

All desired projects emphasize privacy-preserving implementations for the Logos L1:

• Shielded transactions and balances
• ZK proofs for eligibility/verification without revealing identity
• MEV resistance through encrypted mempools
• Anonymous participation in governance and DeFi

---

For Site Developers

Technology Stack

• Quartz 4: Static site generator for publishing digital gardens from Markdown
• TypeScript: Strict mode enabled, targeting ESNext
• Preact: UI framework (JSX runtime configured via tsconfig.json)
• Content Source: Markdown files in content/ directory

Key Commands

Development

# Build and serve with live reload (primary dev command)
npx quartz build --serve

# Build documentation with live reload
npm run docs

Code Quality

# Type checking and formatting check
npm run check

# Auto-format code with Prettier
npm run format

# Run tests
npm test

Architecture

Plugin System

Quartz uses a three-phase plugin architecture defined in quartz/plugins/types.ts:

1. Transformers (quartz/plugins/transformers/): Process markdown content (parse, syntax highlighting, link crawling, etc.)
2. Filters (quartz/plugins/filters/): Determine which content to publish (e.g., RemoveDrafts)
3. Emitters (quartz/plugins/emitters/): Generate output files (HTML pages, assets, sitemap, RSS, etc.)

Plugins are configured in quartz.config.ts and execute in the order: Transformers → Filters → Emitters.

Build Pipeline

The build process (quartz/build.ts) follows this flow:

1. Parse markdown files using transformers
2. Filter content based on filter plugins
3. Emit static assets and pages using emitter plugins
4. Support incremental builds via change detection

Component System

UI components (quartz/components/*.tsx) are Preact-based with three optional lifecycle hooks:

• css: Static stylesheet resource
• beforeDOMLoaded: Scripts that run before DOM ready
• afterDOMLoaded: Scripts that run after DOM ready

Layout structure is defined in cfg.ts as FullPageLayout with regions: head, header, beforeBody, pageBody, afterBody, left, right, footer.

Important Configuration

quartz.config.ts

Central configuration file containing:

• Site metadata (pageTitle, baseUrl, locale)
• Theme settings (typography, colors for light/dark mode)
• Analytics provider (currently set to Plausible)
• Plugin configuration for all three phases
• Ignore patterns for content filtering

Content Structure

• content/index.md: Site homepage
• content/integration/: Integration effort documentation
  • concerns/: Priority drivers (sustainability, movement, tech de-risking)
  • infrastructure_essentials/: Core blockchain infrastructure (block explorers, RPCs, Logos Storage/Messaging)
  • application_essentials/: Developer tools and primitives (toolchains, SDKs, on-chain primitives)
  • desired_projects/: End-user applications and protocols (DeFi, NFTs, DAOs, etc.)

Development Notes

• The site uses CustomOgImages plugin which is commented out in the default config to speed up build times
• File paths use FilePath type and utility functions from quartz/util/path.ts
• Build context (BuildCtx) flows through all plugins and components
• Date handling supports multiple sources with priority: frontmatter → git → filesystem
• Link resolution uses shortest markdown link resolution strategy