diff --git a/fixed_hljs_documentation.md b/fixed_hljs_documentation.md new file mode 100644 index 0000000..e6da0dc --- /dev/null +++ b/fixed_hljs_documentation.md @@ -0,0 +1,148 @@ +# Highlight.js and Library Loading Fix Documentation + +## Issue Summary +The book website was experiencing a critical error where highlight.js was not being properly loaded, resulting in the error message "hljs is not defined" when attempting to load chapters. This prevented proper chapter loading and syntax highlighting, particularly for Rust code blocks. + +## Root Causes +1. **Library Loading Order**: The highlight.js library was not fully loaded before the code attempted to use it +2. **CDN Reliability**: Single CDN source without fallbacks created a single point of failure +3. **Initialization Timing**: The code was not waiting for all required libraries to be fully loaded before initialization +4. **Error Handling**: Insufficient error handling around highlight.js operations + +## Implemented Solutions + +### 1. Robust Script Loading with Fallbacks +- Implemented a custom script loader function that attempts to load from primary CDN source first +- Added fallback CDN sources for each library to ensure availability +- Added proper error handling and logging for script loading failures + +```javascript +function loadScript(src, fallbackSrc, callback) { + var script = document.createElement('script'); + script.src = src; + script.onload = callback; + script.onerror = function() { + console.warn('Failed to load script from primary source:', src); + if (fallbackSrc) { + console.log('Trying fallback source:', fallbackSrc); + var fallbackScript = document.createElement('script'); + fallbackScript.src = fallbackSrc; + fallbackScript.onload = callback; + fallbackScript.onerror = function() { + console.error('Failed to load script from fallback source:', fallbackSrc); + }; + document.head.appendChild(fallbackScript); + } + }; + document.head.appendChild(script); +} +``` + +### 2. Improved Initialization Sequence +- Moved initialization code inside DOMContentLoaded event +- Added a library check function that verifies all required libraries are loaded +- Implemented a polling mechanism to wait for libraries to load before initializing the app + +```javascript +document.addEventListener('DOMContentLoaded', function() { + // Check if libraries are loaded + var librariesLoaded = function() { + return typeof hljs !== 'undefined' && + typeof marked !== 'undefined' && + typeof DOMPurify !== 'undefined'; + }; + + // Initialize app when libraries are loaded + var initializeApp = function() { + if (librariesLoaded()) { + console.log('All libraries loaded, initializing app'); + initApp(); + } else { + console.log('Waiting for libraries to load...'); + setTimeout(initializeApp, 100); + } + }; + + // Start checking for libraries + initializeApp(); +}); +``` + +### 3. Enhanced Error Handling +- Added robust error handling around all highlight.js operations +- Implemented fallbacks for when syntax highlighting fails +- Added explicit checks to verify highlight.js is available before use + +```javascript +// Highlight code blocks +if (typeof hljs !== 'undefined') { + document.querySelectorAll('pre code').forEach((block) => { + try { + hljs.highlightElement(block); + } catch (e) { + console.error('Error highlighting element:', e); + } + }); +} else { + console.warn('highlight.js not available for syntax highlighting'); +} +``` + +### 4. Improved Code Block Rendering +- Enhanced the code block renderer to handle different types of code blocks +- Added proper type checking for code content +- Improved detection of ASCII diagrams vs. code blocks + +```javascript +renderer.code = function(code, language) { + // Ensure code is a string + code = typeof code === 'string' ? code : String(code); + + // Check if this is an ASCII diagram + const isAsciiDiagram = code.includes('+-') || code.includes('|') || code.includes('--') || code.includes('==') || code.includes('[]'); + + if (isAsciiDiagram) { + return `
${code}
`; + } + + // Determine if this is a shell command + const isShellCommand = language === 'bash' || language === 'sh' || language === 'shell'; + + // Create code block with buttons + let html = '
';
+    html += '';
+    
+    if (isShellCommand) {
+        html += '';
+    }
+    
+    html += '
${hljs.highlightAuto(code, language ? [language] : undefined).value}
`; + + return html; +}; +``` + +### 5. Visual Enhancements +- Improved styling for code blocks, tables, and ASCII diagrams +- Enhanced field tag styling in bullet lists +- Added better visual feedback for copy and execute buttons + +## Testing and Verification +- Verified that all chapters load correctly without errors +- Confirmed that Rust syntax highlighting works properly +- Tested sidebar expansion and sub-chapter navigation +- Verified search functionality across all chapters +- Ensured copy and execute buttons work on code blocks +- Tested responsive design on various screen sizes + +## Additional Improvements +- Enhanced table styling for better readability +- Improved ASCII diagram presentation +- Added field tag styling for better visual hierarchy +- Improved keyboard navigation and accessibility diff --git a/index.html b/index.html index 9f82c99..34efebe 100644 --- a/index.html +++ b/index.html @@ -3,722 +3,1295 @@ - - SVMAI role in the future for Autonomous Economic Agents: Technical Overview + Solana Protocol Design for Agent and MCP Server Registries + + + + + + - - - - - - - - - - -
- -
+ /* Enhanced table styles for better readability */ + table { + width: 100%; + border-collapse: collapse; + margin: 1.5rem 0; + font-size: 0.95em; + } -
+ table.table-corporate th { + background-color: #A3A3A3; + color: white; + font-weight: bold; + text-align: left; + padding: 8px 12px; + border: 1px solid #737373; + } -
-

Pioneering the Future of Decentralized AI on Solana

-

The rapid emergence of autonomous agents and sophisticated AI model integrations is reshaping the digital frontier. These intelligent entities offer transformative potential across diverse sectors. However, their proliferation introduces a critical challenge: enabling effective discovery, verification, and interoperability within decentralized networks. Without standardized infrastructure, the growth of a cohesive AI ecosystem is impeded.

-

This document outlines a strategic solution: two interconnected Solana-based program protocols – an Agent Registry and an MCP Server Registry – and the integral $SVMAI utility token. These on-chain registries are engineered to serve as foundational pillars, fostering a robust, trustworthy, and interoperable environment for AI components. By harnessing Solana's high-performance blockchain, these protocols aim to deliver a scalable and efficient framework for managing and discovering AI services, powered by a dedicated ecosystem token.

-
-

Key Strategic Objectives:

-
    -
  • Define precise on-chain data specifications for registry entries.
    • -
  • Outline secure, gas-efficient Solana program instructions for lifecycle management.
    • -
  • Introduce the $SVMAI token and detail its utility in payments, staking, and governance.
    • -
  • Propose a multi-layered discovery approach (on-chain & off-chain indexing).
    • -
  • Align Agent Registry with AEA & A2A principles, utilizing $SVMAI for A2A payments.
    • -
  • Ensure MCP Server Registry adheres to official MCP specifications.
    • -
-
-
+ table.table-corporate td { + padding: 8px 12px; + border: 1px solid #737373; + vertical-align: top; + } -
-

Core Solana Architecture for On-Chain Registries

-

The design of these registries is intrinsically linked to Solana's unique architecture. Understanding these foundational elements—Program Derived Addresses (PDAs), data serialization with Borsh, and the rent model—is crucial for appreciating the efficiency and security of the proposed protocols.

- -
-
-

Program Derived Addresses (PDAs)

-

PDAs are unique addresses controlled by a program, not a private key. They are derived from the program's ID and custom "seeds" (e.g., an agent's unique ID). This ensures tamper-proof storage and authorized modifications for each registry entry.

-
-

PDA = Program ID + Seeds (e.g., "agent_v1", agent_unique_id)

-

Benefit: Unique, secure, program-controlled account for each entry.

-
-
-
-

Account Structures & Borsh Serialization

-

All data on Solana is stored in accounts. For registry entries, data is serialized into a compact, deterministic binary format using Borsh. This is vital for efficiency and data integrity on-chain.

-
-

Borsh: Efficient, deterministic binary serialization.

-

Constraint: Fixed format; direct on-chain querying of arbitrary fields is complex.

-
-
-
+ table.table-corporate tr:nth-child(even) { + background-color: #F0F0F0; + } -
-

Rent, Storage & Hybrid Data Model

-

Storing data on Solana incurs "rent". Accounts must be rent-exempt by holding a SOL balance. Given Solana's 10MB per-account limit and rent costs, a hybrid storage model is essential:

-
-
-

On-Chain Core Data

-
    -
  • Essential Identifiers (IDs, Owner)
    • -
  • Key Status Flags & Timestamps
    • -
  • Primary Service Endpoints
    • -
  • Hashes of Off-Chain Data
    • -
  • URI Pointers to Off-Chain Details
    • -
-

Optimized for verifiability & performance.

-
-
<-->
-
-

Off-Chain Extended Metadata

-
    -
  • Full AgentCard JSON / AEA Manifests
    • -
  • Complete MCP Tool/Resource/Prompt Schemas
    • -
  • Detailed Descriptions & Documentation
    • -
  • Large Media or Auxiliary Files
    • -
-

Hosted on IPFS/Arweave for richness & scalability.

-
-
-

This balances on-chain integrity with the need for comprehensive information, managing costs and storage limits effectively.

-
-
+ table.table-corporate tr:hover { + background-color: #E8E8E8; + } -
-

Agent Registry Protocol

-

The Agent Registry provides a decentralized directory for autonomous agents, drawing inspiration from Google's A2A AgentCard and AEA principles. It emphasizes advertising agent capabilities, endpoints, identity, and economic intent to facilitate discovery and robust interaction.

-
-

Agent Entry Data Specification (`AgentRegistryEntryV1`)

-

Each agent's data is stored in a PDA. The structure balances on-chain essentials with links to comprehensive off-chain metadata. Key fields from Table 1 of the report include:

-
    -
  • owner_authority, agent_id, name, description
    • -
  • service_endpoints (Vec, limited to Max 3 on-chain)
    • -
  • capabilities_flags (A2A bitmask), skills (Vec summary, Max 10 on-chain)
    • -
  • status, timestamps, extended_metadata_uri (link to full AgentCard)
    • -
-
-

For the complete `AgentRegistryEntryV1` structure, please refer to Table 1 in the source "Solana Protocol Design for Agent and MCP Server Registries" report. The table details each field, its Solana (Rust) type, description, AEA/A2A mapping, and constraints.

-
+ /* Enhanced code block styles */ + pre { + margin: 1.5rem 0; + padding: 1rem; + background-color: #F5F5F5; + border: 1px solid #737373; + overflow-x: auto; + position: relative; + } -

Registration & Management Flow

-

Lifecycle management is handled via specific Solana program instructions, ensuring only the owner can modify entries.

-
-
1. Prepare Agent Data: Assemble all required on-chain fields and off-chain metadata (AgentCard JSON).
-
\/
-
2. Invoke `register_agent`: Transaction signed by owner, funds PDA for rent-exemption.
-
\/
-
3. PDA Created & Populated: Agent data stored on-chain.
-
\/
-
4. Event Emitted: `AgentRegistered` event broadcast for indexers.
-
-

Update (update_agent_details, update_agent_status) and deregistration (deregister_agent) follow similar owner-verified flows.

-
-
+ pre code { + font-family: "Courier New", Courier, monospace; + font-size: 0.9em; + line-height: 1.4; + display: block; + padding-top: 0.5rem; /* Space for buttons */ + } -
-

MCP Server Registry Protocol

-

The MCP Server Registry facilitates the discovery of Model Context Protocol (MCP) compliant servers. It allows providers to advertise their services, including Tools, Resources, and Prompts, aligning with the official MCP specification.

-
-

MCP Server Entry Data Specification (`McpServerRegistryEntryV1`)

-

MCP Server entries also use PDAs and a hybrid data model. Key fields from Table 2 of the report include:

-
    -
  • owner_authority, server_id, name, service_endpoint (HTTPS REQUIRED)
    • -
  • Boolean flags: supports_tools, supports_resources, supports_prompts
    • -
  • On-chain summaries/hashes for key onchain_tool_definitions, onchain_resource_definitions, etc. (limited Vecs, Max 5 each)
    • -
  • status, timestamps, full_capabilities_uri (link to complete MCP schema JSON)
    • -
-
-

For the complete `McpServerRegistryEntryV1` structure, refer to Table 2 in the source report. It details each field, its type, description, MCP schema mapping, and constraints.

-
+ /* Improved code buttons */ + .code-buttons { + position: absolute; + top: 5px; + right: 5px; + display: flex; + gap: 5px; + z-index: 10; + } -

Conceptual Data Distribution (Illustrative)

-

Both registries balance on-chain data for core verification and off-chain data for richness. This conceptual chart illustrates the idea:

-
- -
-

This hybrid model is crucial for scalability and cost-efficiency.

-
-
+ .copy-button, .execute-button { + background-color: #E5E5E5; + border: 1px solid #737373; + padding: 3px 8px; + font-size: 0.75rem; + cursor: pointer; + box-shadow: 1px 1px 0px #A3A3A3; + } -
-

Service Endpoints & Connectivity

-

Clear endpoint definitions are crucial for enabling communication and interaction with registered Agents and MCP Servers. The protocol specifies how these endpoints are advertised on-chain.

+ .copy-button:hover, .execute-button:hover { + background-color: #D5D5D5; + } -
-

Agent Service Endpoints

-

Agents can expose multiple service endpoints to support various interaction protocols. The AgentRegistryEntryV1 structure includes a field service_endpoints: Vec<ServiceEndpoint> for this purpose.

-
    -
  • Each ServiceEndpoint struct contains protocol (String, e.g., "a2a_http_jsonrpc"), url (String), and is_default (bool) fields.
    • -
  • A maximum of 3 service endpoints can be stored on-chain per agent.
    • -
  • Exactly one endpoint must be marked as is_default if any endpoints are provided.
    • -
-

Conceptual Example of Agent Endpoint Configurations:

-
-
-

Agent_TradingBot_001

-
Endpoint 1 (Default):
-
Protocol: a2a_http_jsonrpc
-
URL: https://trading.example.com/api/a2a
-
Endpoint 2:
-
Protocol: websocket_feed
-
URL: wss://trading.example.com/feed
-
-
-

Agent_InfoOracle_002

-
Endpoint 1 (Default):
-
Protocol: rest_api_v1
-
URL: https://info.example.com/v1/query
-
-
-
+ .copy-button:active, .execute-button:active { + box-shadow: none; + transform: translate(1px, 1px); + } -
-

MCP Server Service Endpoint

-

MCP Servers advertise a primary service endpoint for standardized communication, typically JSON-RPC 2.0 over HTTP(S). The McpServerRegistryEntryV1 structure includes a field service_endpoint: String for this.

-
    -
  • This URL is the main point of contact for clients wishing to utilize the server's Tools, Resources, or Prompts.
    • -
  • The protocol specifies that this endpoint URL must be HTTPS for secure communication.
    • -
  • The maximum length for this URL is 256 characters.
    • -
-

Conceptual Example of an MCP Server Endpoint:

-
-

MCPServer_DataTools_XYZ

-
Primary Service Endpoint:
-
URL: https://mcp.datatools.example.com/rpc
-
Note: Must be HTTPS. Max 256 Chars.
-
-
-
+ /* Improved ASCII diagram styles */ + .ascii-diagram { + font-family: "Courier New", Courier, monospace; + white-space: pre; + line-height: 1.2; + background-color: #F5F5F5; + padding: 1.5rem; + border: 1px solid #737373; + overflow-x: auto; + margin: 1.5rem 0; + box-shadow: 2px 2px 0px #A3A3A3; + } -
-

The $SVMAI Token: Powering the Ecosystem

-

The $SVMAI token is an integral utility token designed to facilitate interactions, incentivize participation, and govern the Solana AI Registries ecosystem. Its multifaceted role ensures the smooth operation and sustainable growth of the decentralized AI network.

+ /* Improved tag styles for field names */ + .field-tag { + display: inline-block; + background-color: #A3A3A3; + color: white; + padding: 0.1rem 0.4rem; + margin: 0 0.2rem; + font-family: "Courier New", Courier, monospace; + } -
-

Core Utility: AEA Payments in A2A Protocol

-

A primary function of the $SVMAI token is to serve as the native currency for Autonomous Economic Agent (AEA) payments within the Agent-to-Agent (A2A) communication protocol. When one agent consumes a service or requests a task from another registered agent, $SVMAI tokens are used for settlement.

-
-

Mechanism: Agents list their services and associated costs in $SVMAI within their extended_metadata_uri (AgentCard). A2A protocols facilitate the negotiation and execution of these service agreements, with payments settled on-chain using $SVMAI.

-
-

Conceptual AEA Payment Flow using $SVMAI:

-
-
-
1. Agent A (Consumer) discovers Agent B (Provider) via Agent Registry.
-
->
-
2. Agent A requests service from Agent B (A2A Protocol). Service cost specified in $SVMAI.
-
-
\/
-
-
3. Agent B performs service.
-
->
-
4. Agent A transfers agreed $SVMAI amount to Agent B on Solana.
-
-
\/
-
5. Transaction recorded on-chain; service considered paid.
-
-

This creates a direct economic incentive for agents to offer valuable services and participate actively in the ecosystem, fostering a vibrant agent economy.

-
+ /* Improved bullet lists with tags */ + ul.field-list { + list-style-type: none; + padding-left: 1rem; + } -
-

Additional Utilities for $SVMAI Token Holders

-

Beyond AEA payments, $SVMAI empowers token holders through several key mechanisms:

-
-
-

Staking & Incentives

-

Holders can stake $SVMAI tokens to:

-
    -
  • Earn staking rewards from network activity or treasury allocations.
    • -
  • Potentially gain priority access or reduced fees for certain registry operations or indexed data services.
    • -
  • Signal support for reputable agents or MCP servers, influencing their visibility (details TBD by DAO).
    • -
-
-
-

Curation & Quality Control

-

$SVMAI tokens can be used in community-driven curation processes:

-
    -
  • Staking tokens to vouch for the legitimacy or quality of registered agents/servers.
    • -
  • Participating in challenge-response mechanisms to flag and remove malicious or low-quality entries (details TBD by DAO).
    • -
  • Dispute resolution for service agreements between agents.
    • -
-
-
-

Governance & Protocol Evolution

-

$SVMAI token holders will form a Decentralized Autonomous Organization (DAO) to govern the registries and the token's ecosystem:

-
    -
  • Voting on protocol upgrades and parameter changes (e.g., registration fees, on-chain data limits).
    • -
  • Managing the community treasury, potentially funded by a portion of registration fees or token emissions.
    • -
  • Guiding the development of new features and ecosystem initiatives.
    • -
  • Overseeing the evolution of curation and reputation mechanisms.
    • -
-
-
-
-
+ ul.field-list li { + margin-bottom: 0.5rem; + position: relative; + padding-left: 1rem; + } -
-

Advanced Discovery & Querying Strategies

-

Effective discovery requires a multi-layered strategy, combining direct on-chain lookups with powerful off-chain indexing fueled by on-chain events. This approach overcomes Solana's limitations for complex on-chain database-like queries.

+ ul.field-list li:before { + content: "•"; + position: absolute; + left: 0; + } + + + +
+ + +
- -
-

Ensuring Registry Security & Trustworthiness

-

Security is foundational. The protocols incorporate robust measures for access control, data integrity, and mitigation of spam or malicious entries, aiming to build a trustworthy ecosystem.

-
-
-

Ownership & Access Control

-

Each entry is controlled by an owner_authority. Modifications require a transaction signed by this authority, enforced at the program instruction level.

-
-
-

Data Integrity & Validation

-

Rigorous input validation within program instructions. On-chain hashes verify the integrity of linked off-chain data.

-
-
-

Spam & Malice Mitigation

-

Strategies include nominal registration fees (potentially in $SVMAI) and optional curation mechanisms (DAO-based, $SVMAI staking). Links to external reputation systems are encouraged.

-
-
-

Program Upgradability

-

Registry programs are upgradeable. Secure management of the upgrade authority (e.g., multisig, DAO governed by $SVMAI holders) is critical, along with clear data migration plans for schema changes.

-
+ + -
- -
-

Conclusion & Future Outlook

-

The proposed Agent and MCP Server Registries, in conjunction with the $SVMAI token, offer a comprehensive framework for a decentralized AI ecosystem on Solana. By enabling efficient discovery, facilitating economic interactions, fostering interoperability, and building trust through community governance, these protocols can significantly accelerate innovation in AI applications and services.

-
-

Potential Future Enhancements:

-
    -
  • On-Chain Reputation/Attestation Systems: Integrating verifiable credentials or community-driven reputation scores, potentially influenced by $SVMAI staking.
    • -
  • Sophisticated On-Chain Indexing: Leveraging future Solana advancements for more granular on-chain queries.
    • -
  • Native Decentralized Storage Integration: Deeper links with IPFS/Arweave for metadata management.
    • -
  • Cross-Chain Discovery Mechanisms: Enabling interaction with agents and services on other blockchains.
    • -
  • Standardized Off-Chain Indexer Interfaces: Promoting a competitive ecosystem of discovery services.
    • -
  • Automated Verification Services: For endpoint liveness, protocol adherence, and metadata integrity checks, possibly incentivized by $SVMAI.
    • -
-

Addressing the fundamental need for service discovery, verification, and economic settlement, these Solana-based registries and the $SVMAI token are poised to play a pivotal role in shaping a more intelligent, autonomous, and interconnected digital future.

+ +
+ +
+ +
+ +
-
- -
- - - + + +