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:

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

Getting Your API Keys

1. 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:

1. Visit NANO Representatives List
2. Look for representatives with:
   • High uptime (reliability)
   • Reasonable voting weight (not too concentrated)
   • Good performance metrics
3. 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

1. 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)

2. Zero Fees:

   • Completely fee-less transactions
   • Agents can perform unlimited micro-transactions without cost
   • Enables efficient resource allocation and micro-payments

3. 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

4. Scalability:

   • Block-lattice architecture allows parallel processing
   • Each account has its own blockchain
   • Perfect for large-scale agent networks with millions of transactions

5. Deterministic Finality:

   • No need for probabilistic confirmation
   • Agents can be certain of transaction status immediately
   • Enables reliable decision-making in agent systems

6. 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:

1. Wallet Creation and Validation

   • Creates a first wallet
   • Validates the key pair
   • Displays wallet address and QR code for receiving funds

2. 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

3. Second Wallet Creation

   • Creates a second wallet
   • Validates the key pair
   • Prepares for fund transfer

4. Fund Transfer Test

   • Sends all funds from Wallet 1 to Wallet 2
   • Waits for transaction processing
   • Verifies successful reception in Wallet 2

5. 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

1. The test will generate a new wallet and display its address
2. Send exactly 0.00001 NANO to the displayed address
3. 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.