Universal Ledger Access Node (ULAN)

A Model-Context-Protocol (MCP) orchestration layer designed for secure and abstracted interfacing with numerous decentralized networks, including Solana, Ethereum Virtual Machine (EVM) compatible chains, Cardano, THORChain, XRP Ledger, TON, and traditional UTXO ledgers (like Bitcoin). This service exposes uniformly structured RPC methods for routine blockchain interactions, managed securely via environment configuration.

Core Capabilities

Solana Ecosystem Management: - Query native SOL account reserves. - Retrieve comprehensive account metadata. - Execute SOL value transmission between addresses. - Inspect holdings of associated SPL tokens. - Derivation of public key from private cryptographic material. - Automated token arbitrage via Jupiter Aggregator integration (optimizing swap execution across DEXs).

Ethereum & EVM Compatibility Suite: - Balance checks for native currency across supported L1s/L2s. - Verification of ERC-20 token holdings. - Initiation of native asset disbursements (keys sourced from configuration). - Transfer execution for ERC-20 tokens (keys sourced from configuration). - Authorization of ERC-20 expenditure limits (keys sourced from configuration).

Cardano Network Operations: - Retrieval of current network parameters and statistical data. - Examination of address holdings and ledger transaction history. - Inspection of Unspent Transaction Outputs (UTxOs) for specified addresses. - Exploration of stake pool metrics and delegation status. - Querying details for native Cardano assets. - In-depth viewing of specific transaction records. - Acquisition of current epoch performance indicators.

THORChain Interoperability: - RUNE token reserve measurement. - Detailed inspection of liquidity pool compositions. - Generation of price quotations for asset exchanges within the ecosystem. - Facilitation of native cross-chain swaps utilizing the THORChain protocol.

UTXO Family Support (BTC, LTC, DOGE, BCH): - Balance Inquiries: Determine asset reserves for specified addresses. - History Retrieval: Access historical transaction records. - Address Validation: Confirm format and structure validity. - Network Diagnostics: Obtain current fee structures and general network statistics.

XRP Ledger Functionality: - XRP balance ascertainment. - Transaction lineage review. - XRP address format verification. - XRP value dispatch to designated recipients. - Querying the most recent state of the XRPL. - Token balance checks (IOUs). - Establishment of new asset trust relationships.

The Open Network (TON) Services: - TON coin balance reports. - Transaction log retrieval. - TON address structure validation. - TON value remittance, optionally including memo payloads. - Retrieval of prevailing TON network operational metrics.

Compatible EVM Environments: - Ethereum Mainnet - Base - Arbitrum - Optimism - Binance Smart Chain (BSC) - Polygon - Avalanche - Berachain

Deployment Procedure

1. Obtain source code and install prerequisites: bash git clone https://github.com/strangelove-ventures/web3-mcp.git cd web3-mcp npm install

2. Prepare the configuration file: bash cp .env.example .env

3. Configure secrets and operational parameters within .env:

Essential Credentials

env

Module Activation Flags

ENABLE_SOLANA_TOOLS=true # Toggle Solana modules ENABLE_ETHEREUM_TOOLS=true # Toggle Ethereum/EVM modules ENABLE_CARDANO_TOOLS=true # Toggle Cardano modules

UTXO Component Activation

ENABLE_BITCOIN_TOOLS=true # Enable/disable BTC tools ENABLE_LITECOIN_TOOLS=true # Enable/disable LTC tools ENABLE_DOGECOIN_TOOLS=true # Enable/disable DOGE tools ENABLE_BITCOINCASH_TOOLS=true # Enable/disable BCH tools ENABLE_THORCHAIN_TOOLS=true # Enable/disable THORChain tools ENABLE_RIPPLE_TOOLS=true # Enable/disable XRP Ledger tools ENABLE_TON_TOOLS=true # Enable/disable TON tools

Transaction Signing Material

ETH_PRIVATE_KEY=your-ethereum-private-key SOLANA_PRIVATE_KEY=your-base58-encoded-solana-private-key

XRP Ledger Credentials

XRP_PRIVATE_KEY=your-xrp-private-key-in-hex

OR

XRP_MNEMONIC=your-xrp-mnemonic-recovery-phrase XRP_ADDRESS=your-xrp-account-address

TON Wallet Material

TON_MNEMONIC=word1 word2 word3 ... word24 # 24-word phrase TON_ADDRESS=your-ton-wallet-address # Wallet Address TON_API_KEY=your-toncenter-api-key # Optional, for enhanced API access TON_RPC_URL=https://toncenter.com/api/v2/jsonRPC # Default endpoint

Cardano Keys & Network Context

BLOCKFROST_API_KEY=your-blockfrost-api-key # Required for Blockfrost interaction CARDANO_NETWORK=mainnet # Target network: 'mainnet', 'testnet', etc. CARDANO_MNEMONIC=your-cardano-mnemonic-phrase # Signing phrase CARDANO_ACCOUNT_INDEX=0 # Derivation path index

Supplementary Settings

env

Network Access Points (Overrides public defaults)

SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

EVM RPC Overrides

ETH_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/your-api-key ARBITRUM_RPC_URL=https://arb1.arbitrum.io/rpc BASE_RPC_URL=https://mainnet.base.org OPTIMISM_RPC_URL=https://mainnet.optimism.io

Other EVM Endpoints

BSC_RPC_URL=https://bsc-dataseed.binance.org POLYGON_RPC_URL=https://polygon-rpc.com AVALANCHE_RPC_URL=https://api.avax.network/ext/bc/C/rpc BERACHAIN_RPC_URL=https://rpc.berachain.com

XRP Node URL

XRP_RPC_URL=https://xrplcluster.com/

THORChain Node Configuration

THORCHAIN_NODE_URL=https://thornode.ninerealms.com
THORCHAIN_PRIVATE_KEY=your-thorchain-private-key THORCHAIN_MNEMONIC=your-thorchain-mnemonic

UTXO Data Provider Keys

BLOCKCYPHER_API_KEY=your-blockcypher-api-key SOCHAIN_API_KEY=your-sochain-api-key

1. Compile the service package: bash npm run build

2. Integrate the compiled entry point into your local MCP configuration file (claude_desktop_config.json):

{ "mcpServers": { "web3-rpc": { "command": "node", "args": [ "/PATH/TO/web3-mcp/build/index.js" ] } } }

Tool Activation Management

The registration status of individual blockchain interfaces is dynamically managed via boolean flags within the .env file, providing granular control over resource loading and minimizing the security perimeter:

• ENABLE_SOLANA_TOOLS
• ENABLE_ETHEREUM_TOOLS
• ENABLE_BITCOIN_TOOLS
• ENABLE_LITECOIN_TOOLS
• ENABLE_DOGECOIN_TOOLS
• ENABLE_BITCOINCASH_TOOLS
• ENABLE_THORCHAIN_TOOLS
• ENABLE_RIPPLE_TOOLS
• ENABLE_CARDANO_TOOLS
• ENABLE_TON_TOOLS

Setting these to true or false allows users to:

• Expedite service startup by skipping irrelevant modules.
• Decrease potential attack vectors by disabling extraneous chain integrations.
• Tailor the server deployment to specific operational needs.
• Optimize system resource utilization.

Operational Examples

Invoke Claude (or your preferred MCP client) with requests such as:

Solana Interactions (if enabled)

• "Determine my Solana account identifier."
• "Query the reserve balance for 62QXuWZ3WT6ws1ZFxJobVDVXn6bEsiYpLo5yG612U6u3."
• "Transfer 0.001 SOL to Cg6cVS4tjkxHthm3K9BHhmvqF7kSz8GnXqqYXnHBzGXd."
• "List all associated SPL token holdings."
• "Execute a token exchange: 0.1 SOL for USDC equivalent."

EVM Interactions (if enabled)

• "What is the current ETH reserve at address 0x556437c4d22ceaeeebf82006b85bdcc0ae67d933?"
• "Check USDC balance for 0x556437c4d22ceaeeebf82006b85bdcc0ae67d933 on the Ethereum network."
• "Dispatch 0.1 ETH to 0x556437c4d22ceaeeebf82006b85bdcc0ae67d933."
• "Report the present transaction fee rate on Arbitrum."
• "Send 100 USDC tokens to 0x556437c4d22ceaeeebf82006b85bdcc0ae67d933, targeting Polygon."

Cardano Interactions (if enabled)

• "Retrieve the balance for a specified Cardano identifier."
• "Display my wallet's consolidated ledger status."
• "Submit ADA remittance to a counterparty address."
• "Transfer native assets to another recipient address."

Bitcoin Interactions (if enabled)

• "What is the BTC balance for 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?"
• "Examine transaction history for bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh."
• "Confirm the structural validity of Bitcoin address 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa."

Litecoin Interactions (if enabled)

• "Report LTC balance for LM2WMpR1Rp6j3Sa59cMXMs1SPzj9eXpGc1."
• "Fetch recent Litecoin transaction records."
• "What is the current network service charge for LTC?"

Dogecoin Interactions (if enabled)

• "Verify DOGE balance for D8vFz4p1L37jdg47HXKtSHA5uYLYxbGgPD."
• "Show Dogecoin transaction log."
• "Query prevailing DOGE network levies."

Bitcoin Cash Interactions (if enabled)

• "Determine BCH account reserve."
• "List BCH transaction log."
• "Validate a Bitcoin Cash identifier."

THORChain Interactions (if enabled)

• "Report RUNE reserve for thor13zpdckczd0jvyhwxmrwnpap8gmy9m5kk2gzum3."
• "Retrieve liquidity pool details for BTC.BTC."
• "Calculate a cross-asset exchange quote: swap 0.1 BTC.BTC for ETH.ETH."

XRP Ledger Interactions (if enabled)

• "What is the XRP reserve for rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe?"
• "Review transaction history associated with rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe."
• "Validate address format rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe."
• "Send 10 XRP to rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe."
• "Fetch current state data from the XRP Ledger."
• "Enumerate token holdings for account rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe."
• "Establish a trustline for USD, issued by rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe, limit 1000."

TON Interactions (if enabled)

• "Get TON balance for EQAAFhjXzKuQ5N0c96nsdZQWATcJm909LYSaCAvWFQF8tvUZ."
• "Fetch transaction history for EQAAFhjXzKuQ5N0c96nsdZQWATcJm909LYSaCAvWFQF8tvUZ."
• "Is UQD0BRQt-QdIEbsjuRsMqzDlBkUAEfQixShDECoKEOXRc4eR a correctly formatted TON address?"
• "Remit 0.1 TON to EQAAFhjXzKuQ5N0c96nsdZQWATcJm909LYSaCAvWFQF8tvUZ."
• "Send 0.01 TON to UQD0BRQt-QdIEbsjuRsMqzDlBkUAEfQixShDECoKEOXRc4eR, memo='test payment'."
• "Report current operational status of the TON network."

Security Posture

1. Key Isolation: Cryptographic material is strictly confined to the .env configuration and never surfaces in interaction logs.
2. Fund Safety: Advised usage is restricted to non-value-bearing test wallets.
3. Endpoint Management: Custom RPC endpoints can be specified in .env to mitigate public endpoint rate limits and enhance connection stability.
4. Source Control Hygiene: The .env file is configured to be ignored by version control systems to prevent accidental exposure.
5. Surface Area Reduction: Dynamic module activation facilitates disabling unneeded ledger integrations.

Advanced Configuration Details

Custom Endpoint Configuration

Users can override default public access nodes by defining specific RPC URLs within the environment file to improve performance and reliability.

Network Context Selection (EVM)

For EVM operations, the target network (e.g., ethereum, base, arbitrum) can be specified, directing the request to the correctly configured RPC endpoint.

Cardano Integration

This module leverages the Blockfrost SDK/library for Cardano interaction: - BLOCKFROST_API_KEY: Mandatory key obtained from Blockfrost registration. - CARDANO_NETWORK: Specifies operational environment (e.g., mainnet). Defaults to mainnet. - CARDANO_MNEMONIC: Required for any signing operation, supplying the seed phrase. - CARDANO_ACCOUNT_INDEX: Defines the derivation path offset (default is 0).

THORChain Node Selection

Default connectivity relies on public Nine Realms nodes. Custom node URLs can be substituted in .env for dedicated access.

XRP Ledger Authentication

Authentication for transactions can be fulfilled via either a private key or a mnemonic phrase: - XRP_PRIVATE_KEY: Hex-encoded secret. - XRP_MNEMONIC: 12-word recovery phrase. - XRP_ADDRESS: Optional address for derivation confirmation.

TON Network Details

Interaction defaults to the TON Center API. Signing requires wallet material: - TON_MNEMONIC: 24-word seed phrase. - TON_ADDRESS: The associated wallet address. - TON_API_KEY: Recommended for avoiding rate restrictions from TON Center.

Internal mechanisms incorporate an adaptive retry mechanism with exponential delay to gracefully handle transient network congestion and rate limiting.

UTXO Data Sources

For supplementary data retrieval on UTXO chains, the service consults: - BlockCypher - SoChain - Haskoin (specifically for BCH)

API keys for these services can be optionally supplied in .env to enhance rate quota.

Development & Extension

1. Source code repository is located in the src folder.
2. Chain-specific logic is isolated within the src/chains subdirectory.
3. Ensure npm run build is executed following any modifications.
4. TypeScript is the mandated language for all new code additions.

Governance

Contributions, including fixes and enhancements, are actively encouraged via pull requests.

Licensing

ISC License