back to posts
changelog

Welcome to V3.0.0

Explore the technical evolution of Krondor.Org v3.0.0, featuring the development of Leaky CMS - a content-addressable system that moved from expensive Ethereum transactions to pure IPFS-based content addressing.

al miller•February 2, 2025
Welcome to V3.0.0

The Journey from v2 to v3: Solving Real Problems

Welcome to the third iteration of Krondor.Org! After running v2 for several months and gathering real-world experience with blockchain-based content management, I realized it was time for a significant architectural shift. While the decentralized approach was philosophically sound, the practical challenges were mounting.

Version 3 represents not just an incremental improvement, but a fundamental rethinking of how to build truly decentralized content management systems that actually work in practice. This post details the journey from v2's blockchain dependency to v3's pure IPFS implementation, and introduces Leaky - the content-addressable CMS that powers this new architecture.

What Drove the Need for Change?

After months of running v2, several critical limitations became apparent that demanded a new approach:

  • Prohibitive Gas Fees: Ethereum transaction costs made simple blog content updates extremely expensive. Every content change required a blockchain transaction, turning routine content management into a costly operation.

  • Limited Content Management: The v2 implementation lacked the robust content management capabilities needed for a sophisticated website. The flat object structure made organization difficult.

  • Infrastructure Constraints: While maintaining decentralized capabilities was important, the need for self-hosted infrastructure with better performance became increasingly apparent.

  • Complex Gateway Traversal: Custom IPFS structures created complications in accessing content through standard gateways, limiting accessibility.

These challenges led to a fundamental question: How could I maintain the distributed, decentralized philosophy while solving these practical problems? The answer was Leaky.

Introducing Leaky: A Content-Addressable CMS

Leaky represents a complete paradigm shift from v2's blockchain-dependent architecture to a pure IPFS-based content addressing system. Rather than relying on expensive Ethereum transactions for content updates, Leaky creates a content-addressable CMS that maintains all the benefits of decentralized storage while eliminating the cost barriers.

The system is built around the principle of content addressing - where each piece of content is identified by its cryptographic hash rather than a mutable location. This creates an immutable, verifiable content system that can be distributed across the IPFS network without requiring blockchain consensus for simple content operations.

Key advantages of the Leaky approach include:

  • Zero Transaction Costs: Content updates happen purely in IPFS without blockchain transactions

  • Enhanced Flexibility: Rich metadata support with schema validation for content management

  • Better Performance: Self-hosted infrastructure with improved access patterns

  • Improved Accessibility: Standard HTTP server interfaces alongside IPFS gateway access

Major Technical Improvements in v3

The architectural shift from v2 to v3 brought several significant technical improvements that address the core limitations of the previous implementation:

  • Complete Blockchain Removal: Eliminated all Ethereum dependencies, moving to pure IPFS-based content addressing. This removes gas costs and transaction delays from content management.

  • Clean Architecture: Implemented clear separation between CLI tools, server components, and common libraries, making the system more modular and maintainable.

  • Headless CMS Design: Complete separation between content management and content serving, allowing the frontend to focus purely on presentation.

  • Intuitive Git-Like Interface: Enhanced CLI experience that mirrors familiar version control workflows for content management.

The Revolutionary Data Model

The v3 data model represents a significant evolution from v2's flat object structure. The system is built around four key concepts that work together to create a flexible, hierarchical content management system:

1. Nodes: Directory-Like Structures

Nodes act as directory-like containers that can hold links to other nodes or data objects. Each node can include links to other nodes for nested directories, links to data with optional metadata for files, and schema definitions for validating metadata at the directory level.

2. Objects: Rich Metadata Containers

Objects serve as metadata containers that include creation and update timestamps, custom properties validated against schemas, and flexible property types including strings, integers, floats, booleans, links, lists, and maps.

3. Schemas: JSON Schema-Like Validation

Schemas provide JSON Schema-like definitions that validate object metadata at the node level. They support type validation for all data types, required field specifications, property descriptions, and per-directory schema inheritance.

4. Manifests: Version Control Structures

Manifests contain a pointer to the root node, a link to the previous version, and build and version information - essentially providing Git-like version control for the entire content structure.

Here's an example JSON representation showing how these components work together:

{
  "type": "directory",
  "links": {
    "blog": {
      "type": "directory",
      "links": {
        "post.md": {
          "type": "file",
          "data": "<cid>",
          "metadata": {
            "created_at": "2024-01-01T00:00:00Z",
            "updated_at": "2024-01-02T00:00:00Z",
            "properties": {
              "title": "My First Post",
              "author": "Alex Miller",
              "tags": ["blog", "tech"]
            }
          }
        }
      },
      "schema": {
        "title": {
          "type": "string",
          "required": true
        },
        "author": {
          "type": "string",
          "required": true
        },
        "tags": {
          "type": "list",
          "required": false
        }
      }
    }
  }
}

This hierarchical structure offers several key advantages over the previous version:

  • Natural Path-Based Organization: Content maps directly to web URLs, making navigation intuitive

  • Rich Metadata Support: Type validation at both directory and file levels ensures data consistency

  • Improved Content Discovery: Directory traversal makes content exploration straightforward

  • Clean Separation of Concerns: Content, metadata, and validation rules are properly isolated

Developer Experience: Git-Like Simplicity

One of the key improvements in v3 is the enhanced developer experience. The CLI interface maintains the familiar git-like feel from v2, but with significant improvements in functionality and usability:

# Initialize a new leaky project
leaky-cli init --remote https://leaky.krondor.org

# Add and commit content
echo "About us" > about.md
leaky-cli add -v
leaky-cli push

# Pull latest content
leaky-cli pull

Content is now accessible through multiple channels, providing flexibility for both developers and end users:

# Access via IPFS gateway
ipfs.io/ipfs/<root-cid>/about

# Access via Leaky server
https://leaky.krondor.org/<root-cid>/about

The CLI workflow now mirrors familiar development patterns, making it intuitive for developers already comfortable with version control systems. The dual-access model means content remains available through the decentralized IPFS network while also being accessible through traditional HTTP interfaces for better performance and user experience.

Looking Forward: What's Next for Krondor.Org

While v3 represents a significant improvement over its predecessor, there are still exciting areas to explore and enhance in future iterations:

  • Enhanced Caching and Performance Optimizations: While the current system performs well, there are opportunities to implement more sophisticated caching strategies and performance optimizations.

  • Support for Complex Content Types: Expanding the schema system to handle more complex relationships between content types and richer metadata structures.

  • Native Static Site Generation: Rather than relying on the frontend to stylize and format content, implementing native static site generation capabilities with the new data model and server implementation.

The move to a pure IPFS-based solution with Leaky as the dedicated CMS provides a solid foundation for these future improvements. By eliminating blockchain dependencies while maintaining the distributed nature that made the previous versions unique, v3 strikes a balance between idealism and pragmatism.

This evolution from v2 to v3 demonstrates that sometimes the best technical decisions involve knowing when to step back from complexity. By focusing on what users actually need - fast, reliable content management with decentralized benefits - Leaky CMS provides a practical foundation for the future of distributed web publishing.