Overview

IPFS Mainnet AutoConf provides a standardized, extensible configuration format for IPFS implementations to discover and configure routing systems, bootstrap peers, DNS resolvers for special TLDs, and delegated endpoints dynamically.

What is AutoConf?

This version introduces a system-centric approach that moves away from hardcoded profiles to a flexible registry where routing systems declare their capabilities and endpoints specify which systems they support. This enables:

• Dynamic System Discovery: New routing systems can be added without breaking existing clients
• Future-Proof API Versioning: Endpoints can support multiple API versions simultaneously
• Clear Separation: Native configuration (bootstrap peers) vs delegated configuration (HTTP endpoints)
• Client Choice: Implementations decide whether to use native or delegated routing per system
• API Compatibility: Clients ignore unknown APIs and use only the endpoints they understand

Key Principles

1. Extensibility: Unknown APIs are safely ignored, allowing gradual ecosystem evolution
2. Endpoint-Level Capabilities: Each endpoint declares exactly which APIs it supports
3. Configurable Caching: Clients cache configurations locally based on CacheTTL with a maximum of 24 hours

Configuration Format

The AutoConf format consists of the following sections that work together to provide comprehensive routing configuration:

Well Known Routing Systems

The registry defines routing systems with their capabilities and access methods:

Adding New Systems

The schema supports gradual ecosystem evolution: add systems to the registry with their API paths, update endpoints to declare support, and existing clients will ignore unknown APIs while new clients can leverage them immediately.

This extensibility mechanism allows IPFS Mainnet to introduce new routing systems by providing delegated HTTP adapters that existing software can understand and query. For example, a novel routing system can be deployed with HTTP endpoints that speak the standard routing protocols, enabling immediate adoption without requiring native implementation support from existing IPFS clients. This approach enables:

• Zero-friction deployment: New systems work immediately with all existing IPFS implementations that support delegated routing
• Gradual native adoption: Implementations can add native support over time while using delegation as a bridge
• Innovation without fragmentation: Experimental routing systems can be tested in production without breaking compatibility
• Backward compatibility: Older clients continue working, simply ignoring systems they don't recognize

Client Implementation

Clients should process the configuration by checking available systems, determining native vs delegated routing support, and configuring DNS resolvers for special TLDs.

API Versioning Strategy

Delegated utility servers can support multiple API versions simultaneously:

{
  "DelegatedEndpoints": {
    "https://future-endpoint.example": {
      "Systems": ["AminoDHT", "NewSystem"],
      "Read": [
        "/routing/v1/providers",    // Legacy API
        "/routing/v2/providers",    // Enhanced API
        "/routing/v2/content"       // New capability
      ],
      "Write": [
        "/routing/v1/ipns",         // Legacy publishing
        "/routing/v2/ipns"          // Enhanced publishing
      ]
    }
  }
}

Implementations Status

Processing Algorithm

// 1. Check SystemRegistry for available routing systems
for system in autoconf.SystemRegistry:
    if client.supportsNative(system):
        // Use native implementation with NativeConfig
        client.configureNative(system, autoconf.SystemRegistry[system].NativeConfig)
    else:
        // Use delegated routing via HTTP endpoints
        for endpoint in autoconf.DelegatedEndpoints:
            if system in endpoint.Systems:
                // Filter to only APIs this client recognizes
                supportedReadAPIs = client.filterKnownAPIs(endpoint.Read)
                supportedWriteAPIs = client.filterKnownAPIs(endpoint.Write)
                // Configure delegated routing using only supported APIs
                client.configureDelegated(system, endpoint, supportedReadAPIs, supportedWriteAPIs)

// 2. Configure DNS resolvers for special TLDs
// Note: Implementations use OS default or explicit DoH resolver
for etld, resolvers in autoconf.DNSResolvers:
    client.configureDNS(etld, resolvers)

Example Implementation

async function configureIPFS() {
    // Fetch AutoConf
    const response = await fetch('https://conf.ipfs-mainnet.org/autoconf.json');
    const autoconf = await response.json();
    
    // Cache for minimum of 24 hours or CacheTTL from config
    const maxCacheSeconds = 24 * 60 * 60; // 24 hours
    const cacheTTL = Math.min(maxCacheSeconds, autoconf.CacheTTL || maxCacheSeconds);
    localStorage.setItem('ipfs-autoconf', JSON.stringify({
        data: autoconf,
        expires: Date.now() + (cacheTTL * 1000)
    }));
    
    // Define which systems this client supports natively
    const nativeSystems = ['AminoDHT']; // This client has native DHT support
    
    // Configure routing systems
    for (const [systemName, systemConfig] of Object.entries(autoconf.SystemRegistry)) {
        if (nativeSystems.includes(systemName)) {
            // Use native implementation
            if (systemName === 'AminoDHT' && canRunDHT()) {
                configureNativeDHT(systemConfig.NativeConfig.Bootstrap);
            }
        } else {
            // Delegate to HTTP endpoints for unsupported systems
            for (const [url, endpoint] of Object.entries(autoconf.DelegatedEndpoints)) {
                if (endpoint.Systems.includes(systemName)) {
                    configureDelegatedRouting(systemName, url, endpoint);
                }
            }
        }
    }
    
    // Configure DNS resolvers for special TLDs
    // Note: Use OS default resolver or explicit DoH for general domains
    for (const [etld, resolvers] of Object.entries(autoconf.DNSResolvers)) {
        configureDNSResolver(etld, resolvers);
    }
}

Implementation Guidance

Different IPFS implementations have different constraints and capabilities. Here are recommendations for common deployment scenarios:

// Browser-optimized configuration
const browserDefaults = {
    preferDelegated: ['AminoDHT', 'IPNI'],
    enableNative: [] // No native routing in browsers
};

// Daemon-optimized configuration
const daemonDefaults = {
    preferNative: ['AminoDHT'],
    preferDelegated: ['IPNI'],
    enableProviding: true // Only works with native AminoDHT
};

// Mobile-optimized configuration
const mobileDefaults = {
    preferDelegated: ['AminoDHT', 'IPNI'],
    enableNativeOnWifi: ['AminoDHT'],
    maxConnections: 50
};

Platform-Specific Considerations

Implementers should make these decisions at build time based on their target platform rather than reading them from the autoconf. The autoconf provides the what (available systems and endpoints), while your implementation decides the how (native vs delegated routing).

// Instead of reading profiles from autoconf, hard-code platform decisions:
function getRoutingStrategy() {
    if (typeof window !== 'undefined' && !window.require) {
        // Browser environment
        return { preferDelegated: true };
    } else if (process.env.IPFS_LITE_MODE) {
        // Resource-constrained environment
        return { preferDelegated: true, maxConnections: 50 };
    } else {
        // Full daemon environment
        return { preferNative: true, enableProviding: true }; // Providing requires native AminoDHT
    }
}

This approach provides clearer separation between configuration data (what services are available) and implementation decisions (how to use those services), making both the autoconf and implementations simpler and more maintainable.