Skip to content

architecture.md

Latest commit

 

History

History
170 lines (130 loc) · 5.62 KB

architecture.md

File metadata and controls

170 lines (130 loc) · 5.62 KB

Architecture

How Stealth Agent Tools is structured and how its components interact.

Stealth Agent Tools is composed of four skills and an MCP server. Each skill manages a distinct piece of Stealth infrastructure (running a node, managing credentials, querying state) and they compose together to give agents full transactional capability on the Stealth blockchain. The skills are shell scripts and documentation that work with any agent framework capable of executing commands. The MCP server follows the Model Context Protocol standard and works with any compatible client.

Component Overview

graph TD
    CC["AI Agent"] --> Skills

    subgraph Skills["Skills Layer"]
        stealthd["stealthd"]
        ssm["stealth-security-module"]
        mcp["stealth-mcp-server"]
        com["commerce"]
    end

    subgraph Daemons["Runtime Layer"]
        xst_daemon["StealthCoind<br/>RPC :46502 / P2P :4437"]
        mcp_server["stealth-mcp-server<br/>stdio"]
    end

    subgraph External["External"]
        network["Stealth Network"]
    end

    stealthd --> xst_daemon
    ssm --> xst_daemon
    mcp --> mcp_server

    xst_daemon <--> network
    mcp_server <-->|"JSON-RPC"| xst_daemon

    com -.->|"orchestrates"| stealthd
Loading

StealthCoind Node

The stealthd skill manages a StealthCoind instance. StealthCoind is the reference implementation of the Stealth blockchain, a standalone C++ daemon that provides:

  • Quantum Proof-of-Stake (QPoS) consensus with 5-second block times
  • Feeless transactions via memory-hard proof-of-work (Argon2)
  • Stealth addresses for transaction privacy (dual-key system)
  • Built-in Tor integration for network privacy
  • StealthNode validator management (purchase, enable, delegate, claim)

Container Deployment

The default deployment builds StealthCoind from source inside a multi-stage Docker container. The build stage installs all C++ dependencies (Boost, OpenSSL, BDB, libevent, Crypto++, LevelDB) and compiles with CMake. The runtime stage is a minimal Ubuntu image with only the shared libraries needed to run the binary.

Configuration

StealthCoind reads configuration from ~/.StealthCoin/StealthCoin.conf. The start-stealthd.sh script auto-generates this file with random RPC credentials on first run. Key settings:

Setting Default Purpose
rpcuser rpc JSON-RPC authentication username
rpcpassword (random) JSON-RPC authentication password
rpcallowip 127.0.0.1 Allowed RPC client IPs
rpcport 46502 JSON-RPC port
server 1 Enable JSON-RPC server
listen 1 Accept P2P connections

Security Module

The stealth-security-module manages three aspects of security:

  1. Wallet encryption — encrypts the wallet.dat file with a passphrase
  2. RPC credentials — generates strong random passwords
  3. Role-based access — creates restricted CLI wrappers per agent role

Agent Roles

Role Allowed Operations
read-only All query/get methods, no state modification
pay-only Send XST, create addresses, list transactions
staker-admin Read-only + staker management operations
full-access All RPC methods (testing only)

MCP Server

The stealth-mcp-server connects AI assistants to StealthCoind via the Model Context Protocol. It communicates with the node over JSON-RPC and exposes read-only tools over stdio transport.

sequenceDiagram
    participant AI as AI Assistant
    participant MCP as stealth-mcp-server
    participant XST as StealthCoind

    AI->>MCP: stealth_connect(host, port, user, password)
    MCP->>XST: JSON-RPC getinfo
    XST-->>MCP: Node state
    MCP-->>AI: Connected + node info

    AI->>MCP: stealth_get_qpos_info()
    MCP->>XST: JSON-RPC getqposinfo
    XST-->>MCP: QPoS state
    MCP-->>AI: Formatted staker data
Loading

The server exposes 25+ tools across six categories: Connection, Node, Blockchain, Wallet, QPoS/Stakers, and Explorer. All tools are read-only.

Commerce Flow

Stealth's feeless transactions simplify agent commerce dramatically compared to Lightning Network's channel-based model:

sequenceDiagram
    participant Buyer as Buyer Agent
    participant BuyerNode as Buyer's StealthCoind
    participant Network as Stealth Network
    participant SellerNode as Seller's StealthCoind
    participant Seller as Seller Agent

    Buyer->>Seller: Request data + ask for payment address
    Seller-->>Buyer: Stealth address

    Buyer->>BuyerNode: sendtostealthaddress(addr, amount)
    BuyerNode->>Network: Broadcast feeless transaction
    Network->>SellerNode: Transaction propagation
    Note over Network: ~5 second confirmation

    Buyer->>Seller: Payment proof (txid)
    Seller->>SellerNode: gettransaction(txid)
    SellerNode-->>Seller: Confirmed
    Seller-->>Buyer: Delivers data/service
Loading

File System Layout

Host Files

Path Owner Contents
~/.stealth-agent/wallet-password.txt security module Wallet passphrase (0600)
~/.stealth-agent/rpc-password.txt security module RPC password (0600)
~/.stealth-agent/profiles/ security module Role-restricted CLI wrappers
~/.StealthCoin/StealthCoin.conf stealthd Node configuration
~/.StealthCoin/wallet.dat StealthCoind Wallet database
stealth-mcp-server/.env MCP server Connection configuration

Ports

Port Service Description
4437 P2P Stealth mainnet peer-to-peer
4438 P2P Stealth testnet peer-to-peer
46502 RPC JSON-RPC mainnet
46503 RPC JSON-RPC testnet