内容
# Solana AI Registries
Solana区块链上自主AI代理和Model Context Protocol (MCP)服务器的综合链上注册系统。
[](./scripts/build.sh)
[](./tests/)
[](LICENSE)
[](https://solana.com)
## 🚀 Live on Devnet
**Agent Registry**: `BruRLHGfNaf6C5HKUqFu6md5ePJNELafm1vZdhctPkpr` | [Explorer](https://explorer.solana.com/address/BruRLHGfNaf6C5HKUqFu6md5ePJNELafm1vZdhctPkpr?cluster=devnet)
**MCP Server Registry**: `BCBVehUHR3yhbDbvhV3QHS3s27k3LTbpX5CrXQ2sR2SR` | [Explorer](https://explorer.solana.com/address/BCBVehUHR3yhbDbvhV3QHS3s27k3LTbpX5CrXQ2sR2SR?cluster=devnet)
## 🌟 概述
Solana AI Registries协议为发现、验证和与自主AI代理和Model Context Protocol (MCP)服务器交互提供了必要的基础设施。此实现包括两个相互连接的链上注册表：
1. **Agent Registry**：遵循Autonomous Economic Agent (AEA)和Agent-to-Agent (A2A)范例的自主代理的去中心化目录
2. **MCP Server Registry**：Model Context Protocol兼容服务器的目录，支持发现AI工具、资源和提示
## 🏗️ 架构
### 核心设计原则
- **混合存储模型**：链上存储基本数据，链下存储详细元数据，并带有验证哈希
- **事件驱动架构**：全面的事件用于链下索引和查询
- **协议兼容性**：与A2A、AEA和MCP规范对齐
- **安全第一**：所有权验证和全面的输入验证
- **可扩展性**：专为高吞吐量发现和交互而设计
### 主要特性
- ✅ **100% Protocol Compliance**，符合A2A、AEA和MCP规范
- ✅ **混合数据模型**，用于经济高效的存储和丰富的元数据
- ✅ **全面验证**，具有以安全为中心的输入清理
- ✅ **事件发射**，用于强大的链下索引功能
- ✅ **基于所有者的访问控制**，具有加密验证
- ✅ **100% Test Coverage**，具有全面的边缘案例测试
## 🚀 快速开始
### 前提条件
```bash
# 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
```
### 构建
```bash
# 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
```
### 测试
```bash
# 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
```
## 📋 项目结构
```
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
```
## 🔧 使用示例
### Agent Registry
#### 注册代理
```rust
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()],
};
```
#### 更新代理状态
```rust
let update_instruction = AgentRegistryInstruction::UpdateAgentStatus {
new_status: AgentStatus::Active as u8,
};
```
### MCP Server Registry
#### 注册MCP服务器
```rust
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()],
};
```
## 🔍 发现和查询
### 直接查找
```rust
// 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)?;
```
### 基于事件的索引
```rust
// 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?;
}
}
```
## 🛡️ 安全特性
### 访问控制
- **所有者权限**：只有所有者才能修改注册表条目
- **签名验证**：所有修改都需要有效的签名
- **基于PDA的安全性**：程序控制的帐户可防止未经授权的访问
### 输入验证
- **长度约束**：所有字符串都针对最大长度进行验证
- **格式验证**：URL、ID和其他字段已验证是否具有正确的格式
- **边界检查**：数组长度和数值已针对限制进行检查
### 数据完整性
- **哈希验证**：使用链上哈希验证链下内容
- **不可变历史记录**：保留注册时间戳和所有权记录
- **租金保护**：帐户受到保护，免受租金收取
## 📊 性能特征
### 帐户大小
- **Agent Registry Entry**：~2.5KB（针对免租金进行了优化）
- **MCP Server Registry Entry**：~2.2KB（针对免租金进行了优化）
### 操作成本
- **注册**：~0.02 SOL（免租金+交易费用）
- **更新**：~0.001 SOL（仅交易费用）
- **查询**：免费（只读操作）
### 可扩展性
- **吞吐量**：仅受Solana网络容量的限制（~65,000 TPS）
- **存储**：无限条目（没有全局状态限制）
- **索引**：事件驱动的链下扩展
## 🧪 测试
### 测试覆盖率
- ✅ **100% Instruction Coverage**：已测试所有程序指令
- ✅ **Edge Case Testing**：边界条件和错误场景
- ✅ **Security Testing**：授权和验证测试
- ✅ **Integration Testing**：端到端工作流测试
### 运行测试
```bash
# 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
```
## 🚀 部署
### 本地开发
```bash
# Start local validator
solana-test-validator
# Deploy programs
./scripts/deploy-devnet.sh
```
### Devnet部署
```bash
# Configure for devnet
solana config set --url devnet
# Deploy with verification
./scripts/deploy-devnet.sh
./scripts/verify.sh
```
### 🌐 Live Devnet Deployment
Solana AI Registries当前已部署并在Solana Devnet上运行：
#### Program Addresses
- **Agent Registry**: `BruRLHGfNaf6C5HKUqFu6md5ePJNELafm1vZdhctPkpr`
- **MCP Server Registry**: `BCBVehUHR3yhbDbvhV3QHS3s27k3LTbpX5CrXQ2sR2SR`
#### Explorer Links
- [Agent Registry on Solana Explorer](https://explorer.solana.com/address/BruRLHGfNaf6C5HKUqFu6md5ePJNELafm1vZdhctPkpr?cluster=devnet)
- [MCP Server Registry on Solana Explorer](https://explorer.solana.com/address/BCBVehUHR3yhbDbvhV3QHS3s27k3LTbpX5CrXQ2sR2SR?cluster=devnet)
#### Query Examples
##### Using Solana CLI
```bash
# 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
```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
```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
```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部署
```bash
# Configure for mainnet
solana config set --url mainnet-beta
# Deploy (requires security audit)
./scripts/deploy-mainnet.sh
```
## 📚 API参考
### Agent Registry指令
- `RegisterAgent`：创建新的代理条目
- `UpdateAgentDetails`：修改代理信息
- `UpdateAgentStatus`：更改代理操作状态
- `DeregisterAgent`：将代理标记为已注销
### MCP Server Registry指令
- `RegisterMcpServer`：创建新的MCP服务器条目
- `UpdateMcpServerDetails`：修改服务器信息
- `UpdateMcpServerStatus`：更改服务器操作状态
- `DeregisterMcpServer`：将服务器标记为已注销
### 事件
#### Agent Registry事件
- `AgentRegistered`：新代理注册
- `AgentUpdated`：代理详细信息已修改
- `AgentStatusChanged`：代理状态已更新
- `AgentDeregistered`：代理已删除
#### MCP Server Registry事件
- `McpServerRegistered`：新服务器注册
- `McpServerUpdated`：服务器详细信息已修改
- `McpServerStatusChanged`：服务器状态已更新
- `McpServerDeregistered`：服务器已删除
## 🛠️ 开发
### 贡献
1. **Fork the repository**
2. **创建功能分支**：`git checkout -b feature/amazing-feature`
3. **进行更改**，并进行全面的测试
4. **运行测试套件**：`cargo test --all`
5. **提交pull request**，并附上详细说明
### 代码标准
- **格式**：使用`cargo fmt`进行一致的代码格式设置
- **Linting**：解决所有`cargo clippy`警告
- **文档**：包括全面的内联文档
- **测试**：为新功能维护100％的测试覆盖率
### 开发工具
```bash
# 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
```
## 🔮 路线图
### Phase 1: Ecosystem Tools (Q2 2024)
- [ ] TypeScript/JavaScript SDK
- [ ] Python SDK
- [ ] CLI tools for registry interaction
- [ ] Web dashboard for browsing registries
### Phase 2: Advanced Features (Q3 2024)
- [ ] Off-chain indexer reference implementation
- [ ] GraphQL API for complex queries
- [ ] Reputation and attestation systems
- [ ] Cross-chain discovery mechanisms
### Phase 3: Enterprise Features (Q4 2024)
- [ ] Advanced analytics and metrics
- [ ] Enterprise management tools
- [ ] SLA monitoring and alerting
- [ ] Professional support services
## 📄 许可证
该项目已获得MIT License的许可 - 有关详细信息，请参见[LICENSE](LICENSE)文件。
## 🤝 社区
- **GitHub**: [openSVM/aeamcp](https://github.com/openSVM/aeamcp)
- **Documentation**: [Protocol Specification](docs/protocol-specification.md)
- **Issues**: [GitHub Issues](https://github.com/openSVM/aeamcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/openSVM/aeamcp/discussions)
## 🙏 鸣谢
- **Solana Foundation**，感谢其强大的区块链基础设施
- **Google A2A Team**，感谢其Agent-to-Agent协议规范
- **Fetch.ai**，感谢其Autonomous Economic Agent框架
- **Anthropic**，感谢其Model Context Protocol规范
- **Open Source Community**，感谢其工具、库和灵感
## 📈 状态
**Current Status**: 🎉 **CORE IMPLEMENTATION COMPLETE**
Solana AI Registries的实现已准备好投入生产，具有：
- ✅ Full protocol compliance (A2A, AEA, MCP)
- ✅ 100% test coverage
- ✅ Comprehensive security validation
- ✅ Event-driven architecture for ecosystem development
- ✅ Optimized performance and scalability
准备好进行生态系统开发、客户端SDK创建和生产部署！
---
**Built with ❤️ for the Solana AI ecosystem**
