Solana AI Registries

Created By

openSVM7 months ago

Solana Protocol Design for Agent and MCP Server Registries

Content

Solana AI Registries

A comprehensive on-chain registry system for autonomous AI agents and Model Context Protocol (MCP) servers on the Solana blockchain.

🚀 Live on Devnet

Agent Registry: BruRLHGfNaf6C5HKUqFu6md5ePJNELafm1vZdhctPkpr | Explorer MCP Server Registry: BCBVehUHR3yhbDbvhV3QHS3s27k3LTbpX5CrXQ2sR2SR | Explorer

🌟 Overview

The Solana AI Registries protocol provides essential infrastructure for discovering, verifying, and interacting with autonomous AI agents and Model Context Protocol (MCP) servers. This implementation consists of two interconnected on-chain registries:

Agent Registry: A decentralized directory for autonomous agents following the Autonomous Economic Agent (AEA) and Agent-to-Agent (A2A) paradigms
MCP Server Registry: A directory for Model Context Protocol compliant servers, enabling discovery of AI tools, resources, and prompts

🏗️ Architecture

Core Design Principles

Hybrid Storage Model: Essential data on-chain, detailed metadata off-chain with verification hashes
Event-Driven Architecture: Comprehensive events for off-chain indexing and querying
Protocol Compliance: Aligned with A2A, AEA, and MCP specifications
Security First: Ownership verification and comprehensive input validation
Scalability: Designed for high-throughput discovery and interaction

Key Features

✅ 100% Protocol Compliance with A2A, AEA, and MCP specifications
✅ Hybrid Data Model for cost-effective storage and rich metadata
✅ Comprehensive Validation with security-focused input sanitization
✅ Event Emission for powerful off-chain indexing capabilities
✅ Owner-Based Access Control with cryptographic verification
✅ 100% Test Coverage with comprehensive edge case testing

🚀 Quick Start

Prerequisites

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Solana CLI
curl --proto '=https' --tlsv1.2 -sSfL https://solana-install.solana.workers.dev | bash

# Set up Solana for local development
solana config set --url localhost
solana-test-validator

Building

# Clone the repository
git clone https://github.com/openSVM/aeamcp.git
cd aeamcp

# Build all programs
./scripts/build.sh

# Or build manually
cargo build --all
cargo test --all

Testing

# Run comprehensive test suite
cargo test --all

# Run specific registry tests
cargo test agent_registry_tests
cargo test mcp_server_registry_tests

# Run with verbose output
cargo test -- --nocapture

📋 Project Structure

aeamcp/
├── programs/
│   ├── common/                    # Shared utilities and types
│   ├── agent-registry/            # Agent Registry program
│   └── mcp-server-registry/       # MCP Server Registry program
├── tests/                         # Integration tests
├── scripts/                       # Build and deployment scripts
├── docs/                          # Protocol documentation
└── README.md                      # This file

🔧 Usage Examples

Agent Registry

Registering an Agent

use solana_ai_registries_common::*;
use agent_registry::instruction::AgentRegistryInstruction;

// Create registration instruction
let instruction = AgentRegistryInstruction::RegisterAgent {
    agent_id: "my-trading-agent".to_string(),
    name: "Advanced Trading Agent".to_string(),
    description: "AI agent for automated trading strategies".to_string(),
    agent_version: "1.0.0".to_string(),
    provider_name: Some("TradingCorp".to_string()),
    provider_url: Some("https://tradingcorp.com".to_string()),
    documentation_url: Some("https://docs.tradingcorp.com/agent".to_string()),
    service_endpoints: vec![
        ServiceEndpointInput {
            protocol: "a2a_http_jsonrpc".to_string(),
            url: "https://api.tradingcorp.com/agent".to_string(),
            is_default: true,
        }
    ],
    capabilities_flags: 0x01, // Streaming support
    supported_input_modes: vec!["application/json".to_string()],
    supported_output_modes: vec!["application/json".to_string()],
    skills: vec![
        AgentSkillInput {
            id: "market-analysis".to_string(),
            name: "Market Analysis".to_string(),
            description_hash: Some([0u8; 32]), // Hash of detailed description
            tags: vec!["trading".to_string(), "analysis".to_string()],
        }
    ],
    security_info_uri: Some("https://tradingcorp.com/security".to_string()),
    aea_address: None,
    economic_intent_summary: Some("Maximize trading profits".to_string()),
    supported_aea_protocols_hash: None,
    extended_metadata_uri: Some("https://ipfs.io/ipfs/QmAgent...".to_string()),
    tags: vec!["trading".to_string(), "defi".to_string()],
};

Updating Agent Status

let update_instruction = AgentRegistryInstruction::UpdateAgentStatus {
    new_status: AgentStatus::Active as u8,
};

MCP Server Registry

Registering an MCP Server

use mcp_server_registry::instruction::McpServerRegistryInstruction;

let instruction = McpServerRegistryInstruction::RegisterMcpServer {
    server_id: "financial-data-server".to_string(),
    name: "Financial Data MCP Server".to_string(),
    server_version: "2.1.0".to_string(),
    service_endpoint: "https://api.findata.com/mcp".to_string(),
    documentation_url: Some("https://docs.findata.com".to_string()),
    server_capabilities_summary: Some("Real-time financial data and analysis tools".to_string()),
    supports_resources: true,
    supports_tools: true,
    supports_prompts: false,
    onchain_tool_definitions: vec![
        McpToolDefinitionOnChainInput {
            name: "get-stock-price".to_string(),
            description_hash: [1u8; 32],
            input_schema_hash: [2u8; 32],
            output_schema_hash: [3u8; 32],
            tags: vec!["stocks".to_string(), "price".to_string()],
        }
    ],
    onchain_resource_definitions: vec![
        McpResourceDefinitionOnChainInput {
            uri_pattern: "stock://symbol/*".to_string(),
            description_hash: [4u8; 32],
            tags: vec!["stocks".to_string()],
        }
    ],
    onchain_prompt_definitions: vec![],
    full_capabilities_uri: Some("https://ipfs.io/ipfs/QmServer...".to_string()),
    tags: vec!["finance".to_string(), "data".to_string()],
};

🔍 Discovery and Querying

Direct Lookup

// Derive PDA for direct agent lookup
let (agent_pda, _) = Pubkey::find_program_address(
    &[AGENT_REGISTRY_PDA_SEED, "my-agent-id".as_bytes()],
    &agent_registry::id(),
);

// Fetch agent data
let agent_data = client.get_account_data(&agent_pda)?;
let agent_entry = AgentRegistryEntryV1::try_from_slice(&agent_data)?;

Event-Based Indexing

// Listen for agent registration events
client.on_logs_subscribe(
    RpcTransactionLogsFilter::Mentions(vec![agent_registry::id().to_string()]),
    RpcTransactionLogsConfig {
        commitment: Some(CommitmentConfig::confirmed()),
    },
)?;

// Process events for off-chain indexing
for log in logs {
    if log.contains("AgentRegistered") {
        // Parse and index agent data
        let event: AgentRegistered = parse_event(&log)?;
        index_agent(event).await?;
    }
}

🛡️ Security Features

Access Control

Owner Authority: Only the owner can modify registry entries
Signature Verification: All modifications require valid signatures
PDA-Based Security: Program-controlled accounts prevent unauthorized access

Input Validation

Length Constraints: All strings validated against maximum lengths
Format Validation: URLs, IDs, and other fields validated for proper format
Boundary Checking: Array lengths and numeric values checked against limits

Data Integrity

Hash Verification: Off-chain content verified using on-chain hashes
Immutable History: Registration timestamps and ownership records preserved
Rent Protection: Accounts protected against rent collection

📊 Performance Characteristics

Account Sizes

Agent Registry Entry: ~2.5KB (optimized for rent-exemption)
MCP Server Registry Entry: ~2.2KB (optimized for rent-exemption)

Operation Costs

Registration: ~0.02 SOL (rent-exemption + transaction fees)
Updates: ~0.001 SOL (transaction fees only)
Queries: Free (read-only operations)

Scalability

Throughput: Limited only by Solana network capacity (~65,000 TPS)
Storage: Unlimited entries (no global state limitations)
Indexing: Event-driven off-chain scaling

🧪 Testing

Test Coverage

✅ 100% Instruction Coverage: All program instructions tested
✅ Edge Case Testing: Boundary conditions and error scenarios
✅ Security Testing: Authorization and validation testing
✅ Integration Testing: End-to-end workflow testing

Running Tests

# Run all tests
cargo test --all

# Run with coverage
cargo test --all -- --test-threads=1

# Run specific test categories
cargo test validation_tests
cargo test authorization_tests
cargo test integration_tests

🚀 Deployment

Local Development

# Start local validator
solana-test-validator

# Deploy programs
./scripts/deploy-devnet.sh

Devnet Deployment

# Configure for devnet
solana config set --url devnet

# Deploy with verification
./scripts/deploy-devnet.sh
./scripts/verify.sh

🌐 Live Devnet Deployment

The Solana AI Registries are currently deployed and live on Solana Devnet:

Program Addresses

Agent Registry: BruRLHGfNaf6C5HKUqFu6md5ePJNELafm1vZdhctPkpr
MCP Server Registry: BCBVehUHR3yhbDbvhV3QHS3s27k3LTbpX5CrXQ2sR2SR

Explorer Links

Query Examples

Using Solana CLI

# Configure for devnet
solana config set --url devnet

# Query Agent Registry program info
solana program show BruRLHGfNaf6C5HKUqFu6md5ePJNELafm1vZdhctPkpr

# Query MCP Server Registry program info
solana program show BCBVehUHR3yhbDbvhV3QHS3s27k3LTbpX5CrXQ2sR2SR

# List all agent accounts (requires custom RPC call)
solana account BruRLHGfNaf6C5HKUqFu6md5ePJNELafm1vZdhctPkpr --output json

# List all MCP server accounts (requires custom RPC call)
solana account BCBVehUHR3yhbDbvhV3QHS3s27k3LTbpX5CrXQ2sR2SR --output json

Using JavaScript/TypeScript

import { Connection, PublicKey } from '@solana/web3.js';

const connection = new Connection('https://api.devnet.solana.com');

// Program addresses
const AGENT_REGISTRY_PROGRAM_ID = new PublicKey('BruRLHGfNaf6C5HKUqFu6md5ePJNELafm1vZdhctPkpr');
const MCP_REGISTRY_PROGRAM_ID = new PublicKey('BCBVehUHR3yhbDbvhV3QHS3s27k3LTbpX5CrXQ2sR2SR');

// Query all agent accounts
async function getAllAgents() {
  const accounts = await connection.getProgramAccounts(AGENT_REGISTRY_PROGRAM_ID);
  return accounts.map(account => ({
    pubkey: account.pubkey.toString(),
    data: account.account.data,
    owner: account.account.owner.toString()
  }));
}

// Query all MCP server accounts
async function getAllMcpServers() {
  const accounts = await connection.getProgramAccounts(MCP_REGISTRY_PROGRAM_ID);
  return accounts.map(account => ({
    pubkey: account.pubkey.toString(),
    data: account.account.data,
    owner: account.account.owner.toString()
  }));
}

// Query specific agent by PDA
async function getAgentByOwner(ownerPubkey: PublicKey) {
  const [agentPda] = PublicKey.findProgramAddressSync(
    [Buffer.from("agent"), ownerPubkey.toBuffer()],
    AGENT_REGISTRY_PROGRAM_ID
  );
  
  const accountInfo = await connection.getAccountInfo(agentPda);
  return accountInfo;
}

// Query specific MCP server by PDA
async function getMcpServerByOwner(ownerPubkey: PublicKey) {
  const [serverPda] = PublicKey.findProgramAddressSync(
    [Buffer.from("mcp_server"), ownerPubkey.toBuffer()],
    MCP_REGISTRY_PROGRAM_ID
  );
  
  const accountInfo = await connection.getAccountInfo(serverPda);
  return accountInfo;
}

Using Python

from solana.rpc.api import Client
from solana.publickey import PublicKey

# Connect to devnet
client = Client("https://api.devnet.solana.com")

# Program addresses
AGENT_REGISTRY_PROGRAM_ID = PublicKey("BruRLHGfNaf6C5HKUqFu6md5ePJNELafm1vZdhctPkpr")
MCP_REGISTRY_PROGRAM_ID = PublicKey("BCBVehUHR3yhbDbvhV3QHS3s27k3LTbpX5CrXQ2sR2SR")

# Query all agent accounts
def get_all_agents():
    response = client.get_program_accounts(AGENT_REGISTRY_PROGRAM_ID)
    return response

# Query all MCP server accounts
def get_all_mcp_servers():
    response = client.get_program_accounts(MCP_REGISTRY_PROGRAM_ID)
    return response

# Query specific account
def get_account_info(pubkey_str):
    pubkey = PublicKey(pubkey_str)
    response = client.get_account_info(pubkey)
    return response

Using Rust

use solana_client::rpc_client::RpcClient;
use solana_sdk::pubkey::Pubkey;
use std::str::FromStr;

// Connect to devnet
let rpc_client = RpcClient::new("https://api.devnet.solana.com");

// Program addresses
let agent_registry_program_id = Pubkey::from_str("BruRLHGfNaf6C5HKUqFu6md5ePJNELafm1vZdhctPkpr").unwrap();
let mcp_registry_program_id = Pubkey::from_str("BCBVehUHR3yhbDbvhV3QHS3s27k3LTbpX5CrXQ2sR2SR").unwrap();

// Query all agent accounts
let agent_accounts = rpc_client.get_program_accounts(&agent_registry_program_id)?;

// Query all MCP server accounts
let mcp_accounts = rpc_client.get_program_accounts(&mcp_registry_program_id)?;

// Query specific account
let account_info = rpc_client.get_account(&some_pubkey)?;

Mainnet Deployment

# Configure for mainnet
solana config set --url mainnet-beta

# Deploy (requires security audit)
./scripts/deploy-mainnet.sh

📚 API Reference

Agent Registry Instructions

RegisterAgent: Create a new agent entry
UpdateAgentDetails: Modify agent information
UpdateAgentStatus: Change agent operational status
DeregisterAgent: Mark agent as deregistered

MCP Server Registry Instructions

RegisterMcpServer: Create a new MCP server entry
UpdateMcpServerDetails: Modify server information
UpdateMcpServerStatus: Change server operational status
DeregisterMcpServer: Mark server as deregistered

Events

Agent Registry Events

AgentRegistered: New agent registration
AgentUpdated: Agent details modified
AgentStatusChanged: Agent status updated
AgentDeregistered: Agent removed

MCP Server Registry Events

McpServerRegistered: New server registration
McpServerUpdated: Server details modified
McpServerStatusChanged: Server status updated
McpServerDeregistered: Server removed

🛠️ Development

Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes with comprehensive tests
Run the test suite: cargo test --all
Submit a pull request with detailed description

Code Standards

Formatting: Use cargo fmt for consistent code formatting
Linting: Address all cargo clippy warnings
Documentation: Include comprehensive inline documentation
Testing: Maintain 100% test coverage for new features

Development Tools

# Format code
cargo fmt --all

# Run linter
cargo clippy --all -- -D warnings

# Generate documentation
cargo doc --all --no-deps --open

# Security audit (requires cargo-audit)
cargo audit