@chainreactionom/nano-mcp NPM

NANO Transaction Utilities

What is NANO?

NANO is a revolutionary digital currency designed for instant, fee-less transactions with unlimited scalability. Unlike traditional cryptocurrencies, NANO uses a unique block-lattice architecture where each account has its own blockchain, enabling near-instantaneous transactions and infinite scalability.

Configuration

The library requires proper configuration before use. There are three required parameters that must be set:

NANO_RPC_URL - The URL of your NANO RPC server (default: https://rpc.nano.to/)
NANO_RPC_KEY - Your RPC authentication key (get a free key from nano.to)
NANO_GPU_KEY - Your GPU service key for work generation

Getting Your API Keys

RPC API Key:
- Visit rpc.nano.to
- This is a high-performance public enterprise node (RPC) for the Nano blockchain
- Get your free RPC API key for development and testing
- The service is optimized for high-throughput and reliability

Optional parameters:

NANO_DEFAULT_REPRESENTATIVE - The default representative for new accounts (defaults to nano_3arg3asgtigae3xckabaaewkx3bzsh7nwz7jkmjos79ihyaxwphhm6qgjps4 if not set)

Choosing a Representative

The representative you choose helps secure and decentralize the NANO network. To choose a good representative:

Visit NANO Representatives List
Look for representatives with:
- High uptime (reliability)
- Reasonable voting weight (not too concentrated)
- Good performance metrics
Copy the representative's address and use it in your configuration

A well-chosen representative contributes to:

Network decentralization
Better security
Faster consensus
Overall network health

You can configure the library in two ways:

1. Environment Variables

# Create a .env file in your project root
cp .env.example .env

# Edit the .env file with your configuration
NANO_RPC_URL=https://rpc.nano.to/     # Required: Default public RPC node
NANO_RPC_KEY=your-rpc-key-here        # Required: Get from https://rpc.nano.to/
NANO_GPU_KEY=your-gpu-key-here        # Required

# Choose your representative from https://nanexplorer.com/nano/representatives
NANO_DEFAULT_REPRESENTATIVE=nano_3arg3asgtigae3xckabaaewkx3bzsh7nwz7jkmjos79ihyaxwphhm6qgjps4  # Optional

2. Programmatic Configuration

import { NanoMCP } from '@chainreactionom/nano-mcp-server';

// Initialize with custom configuration
const mcp = await NanoMCP.initialize({
    rpcUrl: 'https://rpc.nano.to/',
    rpcKey: 'your-rpc-key',
    gpuKey: 'your-gpu-key',
    defaultRepresentative: 'your-representative-address' // Optional
});

// The initialize method will validate the configuration
// If validation fails, it will throw an error with details

Configuration Validation

The library performs strict validation of the configuration:

Required parameters must be set
RPC URL must be a valid URL format
Configuration must be initialized before using the library
Warnings are issued for optional parameters using defaults

If validation fails, you'll receive detailed error messages:

try {
    const mcp = await NanoMCP.initialize();
} catch (error) {
    console.error('Configuration validation failed:', error.message);
    // Example error message:
    // Configuration validation failed:
    // Errors:
    // - NANO_RPC_KEY is required but not set
    // - NANO_GPU_KEY is required but not set
    // Warnings:
    // - Using default representative address
}

Why NANO is Ideal for Agentic Transactions

Instant Finality:
- Transactions complete in less than 1 second
- Perfect for real-time agent-to-agent interactions
- No waiting for multiple block confirmations like Bitcoin (10+ minutes)
Zero Fees:
- Completely fee-less transactions
- Agents can perform unlimited micro-transactions without cost
- Enables efficient resource allocation and micro-payments
Energy Efficiency:
- Uses minimal energy compared to Proof-of-Work chains
- Environmentally sustainable for large-scale agent networks
- ~0.000112 kWh per transaction vs Bitcoin's 707 kWh
Scalability:
- Block-lattice architecture allows parallel processing
- Each account has its own blockchain
- Perfect for large-scale agent networks with millions of transactions
Deterministic Finality:
- No need for probabilistic confirmation
- Agents can be certain of transaction status immediately
- Enables reliable decision-making in agent systems
Simple Integration:
- Straightforward API for basic operations
- No complex smart contract overhead
- Ideal for focused agent-to-agent value transfer

This package provides a comprehensive set of utilities for handling NANO cryptocurrency transactions, enabling seamless integration into agent-based systems.

Features

Work generation with multiple fallback services
Account information retrieval
Pending blocks management
Block creation and processing:
- Opening blocks
- Receive blocks
- Send blocks
Transaction utilities:
- Send NANO
- Receive pending transactions
- Balance conversion

Installation

npm install nanocurrency nanocurrency-web node-fetch

Usage

Basic Setup

import { NanoTransactions } from './utils/nano-transactions';

const nano = new NanoTransactions({
    apiUrl: 'https://rpc.nano.to/',  // Your RPC node URL
    rpcKey: 'your-rpc-key',          // Optional: Your RPC authentication key
    gpuKey: 'your-gpu-key'           // Optional: Your GPU service key for work generation
});

Generate Work

const hash = '000000000000000000000000000000000000000000000000000000000000000A';
const work = await nano.generateWork(hash);
console.log('Generated work:', work);

Get Account Information

const account = 'nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3';
const info = await nano.getAccountInfo(account);
console.log('Account info:', info);

Send NANO

const fromAddress = 'your-source-address';
const privateKey = 'your-private-key';
const toAddress = 'destination-address';
const amount = '0.00001';

// First get account info
const accountInfo = await nano.getAccountInfo(fromAddress);
if (accountInfo.error) {
    throw new Error(`Failed to get account info: ${accountInfo.error}`);
}

const result = await nano.createSendBlock(fromAddress, privateKey, toAddress, amount, accountInfo);
console.log('Send transaction result:', result);

Receive Pending Transactions

const address = 'your-address';
const privateKey = 'your-private-key';
const result = await nano.receiveAllPending(address, privateKey);
console.log('Receive transaction result:', result);

Testing

To run the tests:

# Set up environment variables
export RPC_KEY=your-rpc-key
export GPU_KEY=your-gpu-key
export TEST_ADDRESS=your-test-address
export TEST_PRIVATE_KEY=your-test-private-key
export TEST_SOURCE_BLOCK=source-block-hash
export TEST_SOURCE_AMOUNT=0.0001
export SOURCE_ADDRESS=your-source-address
export SOURCE_PRIVATE_KEY=your-source-private-key
export RECEIVE_ADDRESS=your-receive-address
export RECEIVE_PRIVATE_KEY=your-receive-private-key

# Run specific tests
export TEST_OPEN=true      # Test opening blocks
export TEST_SEND=true      # Test send transactions
export TEST_RECEIVE=true   # Test receive transactions

# Run the test suite
node test-nano-utils.js

Security Considerations

Never share your private keys
Always validate addresses before sending transactions
Use secure RPC nodes
Implement proper error handling
Consider using environment variables for sensitive data

Error Handling

The utilities include comprehensive error handling:

Invalid addresses
Insufficient balance
Network errors
Invalid private keys
Block processing failures

Each function returns detailed error information when something goes wrong.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

NANO MCP Implementation

This is a NANO cryptocurrency wallet implementation for MCP that includes a comprehensive test scenario.

Test Scenario

The test scenario demonstrates the following workflow:

Wallet Creation and Validation
- Creates a first wallet
- Validates the key pair
- Displays wallet address and QR code for receiving funds
Fund Reception
- Waits for 4 minutes for funds to be received
- Checks balance every 10 seconds
- Processes pending transactions when detected
- Verifies successful fund reception
Second Wallet Creation
- Creates a second wallet
- Validates the key pair
- Prepares for fund transfer
Fund Transfer Test
- Sends all funds from Wallet 1 to Wallet 2
- Waits for transaction processing
- Verifies successful reception in Wallet 2
Return Transfer Test
- Sends all funds back from Wallet 2 to Wallet 1
- Waits for transaction processing
- Verifies final balances

Implementation Details

Uses nanocurrency-web for cryptographic operations
Connects to NANO RPC node at rpc.nano.to
Includes proper error handling and logging
Validates all key pairs and transactions
Handles both send and receive operations

Running the Test

# Install dependencies
npm install

# Run the test
npm start

Test Flow

The test will generate a new wallet and display its address
Send exactly 0.00001 NANO to the displayed address
The test will automatically:
- Monitor for incoming funds
- Create a second wallet
- Transfer funds between wallets
- Verify all transactions

Error Handling

The test includes comprehensive error handling for:

Network issues
Transaction failures
Invalid states
Timeout conditions

Logging

All operations are logged with timestamps and full details in the logs directory.

nano cryptocurrency wallet blockchain mcp nanocurrency

axios dotenv nanocurrency nanocurrency-web node-fetch qrcode-terminal

1.0.0

5 months ago