{"_id":"@chainreactionom/nano-mcp","name":"@chainreactionom/nano-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@chainreactionom/nano-mcp","version":"1.0.0","type":"module","description":"NANO cryptocurrency wallet implementation for MCP with comprehensive testing","main":"src/index.js","scripts":{"test":"node --experimental-vm-modules node_modules/jest/bin/jest.js","start":"node src/index.js"},"keywords":["nano","cryptocurrency","wallet","blockchain","mcp","nanocurrency"],"author":{"name":"Chain Reaction"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/chainreactionom/nano-mcp.git"},"dependencies":{"axios":"^1.6.7","dotenv":"^16.4.5","nanocurrency":"^2.5.0","nanocurrency-web":"^1.4.3","node-fetch":"^3.3.2","qrcode-terminal":"^0.12.0"},"devDependencies":{"jest":"^29.7.0"},"publishConfig":{"access":"public"},"_id":"@chainreactionom/nano-mcp@1.0.0","gitHead":"7a7ee92b594fb88ee46b1669b9f54eed43990d7e","bugs":{"url":"https://github.com/chainreactionom/nano-mcp/issues"},"homepage":"https://github.com/chainreactionom/nano-mcp#readme","_nodeVersion":"22.13.1","_npmVersion":"11.1.0","dist":{"integrity":"sha512-9mlDzDSK0O9KdeiiljvA6QZe+gZO5cXVfUJfIofaQaiPhjU4hTj5ViYawhrZXgu6u8VlppY7EhAujVe3lcBlWg==","shasum":"bf678395da9207108ab95688289e1ffa0c1ea80c","tarball":"https://registry.npmjs.org/@chainreactionom/nano-mcp/-/nano-mcp-1.0.0.tgz","fileCount":66,"unpackedSize":719424,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQChC3MH/oCCPeQZy7KlXoLmWkvy+dMIIOLrQobqrgQc2gIhANge07f7vxIPu6hFBz+UudZE4+nFTwdtnkdCD/exoX/i"}]},"_npmUser":{"name":"chainreactionom","email":"dhyabi@gmail.com"},"directories":{},"maintainers":[{"name":"chainreactionom","email":"dhyabi@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/nano-mcp_1.0.0_1749073432233_0.7347730583254806"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-04T21:43:52.148Z","1.0.0":"2025-06-04T21:43:52.515Z","modified":"2025-06-04T21:43:52.797Z"},"maintainers":[{"name":"chainreactionom","email":"dhyabi@gmail.com"}],"description":"NANO cryptocurrency wallet implementation for MCP with comprehensive testing","homepage":"https://github.com/chainreactionom/nano-mcp#readme","keywords":["nano","cryptocurrency","wallet","blockchain","mcp","nanocurrency"],"repository":{"type":"git","url":"git+https://github.com/chainreactionom/nano-mcp.git"},"author":{"name":"Chain Reaction"},"bugs":{"url":"https://github.com/chainreactionom/nano-mcp/issues"},"license":"MIT","readme":"# NANO Transaction Utilities\r\n\r\n## What is NANO?\r\n\r\nNANO 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.\r\n\r\n### Configuration\r\n\r\nThe library requires proper configuration before use. There are three required parameters that must be set:\r\n\r\n1. `NANO_RPC_URL` - The URL of your NANO RPC server (default: https://rpc.nano.to/)\r\n2. `NANO_RPC_KEY` - Your RPC authentication key (get a free key from [nano.to](https://rpc.nano.to/))\r\n3. `NANO_GPU_KEY` - Your GPU service key for work generation\r\n\r\n#### Getting Your API Keys\r\n\r\n1. **RPC API Key**: \r\n   - Visit [rpc.nano.to](https://rpc.nano.to/)\r\n   - This is a high-performance public enterprise node (RPC) for the Nano blockchain\r\n   - Get your free RPC API key for development and testing\r\n   - The service is optimized for high-throughput and reliability\r\n\r\nOptional parameters:\r\n- `NANO_DEFAULT_REPRESENTATIVE` - The default representative for new accounts (defaults to `nano_3arg3asgtigae3xckabaaewkx3bzsh7nwz7jkmjos79ihyaxwphhm6qgjps4` if not set)\r\n\r\n#### Choosing a Representative\r\n\r\nThe representative you choose helps secure and decentralize the NANO network. To choose a good representative:\r\n\r\n1. Visit [NANO Representatives List](https://nanexplorer.com/nano/representatives)\r\n2. Look for representatives with:\r\n   - High uptime (reliability)\r\n   - Reasonable voting weight (not too concentrated)\r\n   - Good performance metrics\r\n3. Copy the representative's address and use it in your configuration\r\n\r\nA well-chosen representative contributes to:\r\n- Network decentralization\r\n- Better security\r\n- Faster consensus\r\n- Overall network health\r\n\r\nYou can configure the library in two ways:\r\n\r\n#### 1. Environment Variables\r\n\r\n```bash\r\n# Create a .env file in your project root\r\ncp .env.example .env\r\n\r\n# Edit the .env file with your configuration\r\nNANO_RPC_URL=https://rpc.nano.to/     # Required: Default public RPC node\r\nNANO_RPC_KEY=your-rpc-key-here        # Required: Get from https://rpc.nano.to/\r\nNANO_GPU_KEY=your-gpu-key-here        # Required\r\n\r\n# Choose your representative from https://nanexplorer.com/nano/representatives\r\nNANO_DEFAULT_REPRESENTATIVE=nano_3arg3asgtigae3xckabaaewkx3bzsh7nwz7jkmjos79ihyaxwphhm6qgjps4  # Optional\r\n```\r\n\r\n#### 2. Programmatic Configuration\r\n\r\n```typescript\r\nimport { NanoMCP } from '@chainreactionom/nano-mcp-server';\r\n\r\n// Initialize with custom configuration\r\nconst mcp = await NanoMCP.initialize({\r\n    rpcUrl: 'https://rpc.nano.to/',\r\n    rpcKey: 'your-rpc-key',\r\n    gpuKey: 'your-gpu-key',\r\n    defaultRepresentative: 'your-representative-address' // Optional\r\n});\r\n\r\n// The initialize method will validate the configuration\r\n// If validation fails, it will throw an error with details\r\n```\r\n\r\n### Configuration Validation\r\n\r\nThe library performs strict validation of the configuration:\r\n\r\n- Required parameters must be set\r\n- RPC URL must be a valid URL format\r\n- Configuration must be initialized before using the library\r\n- Warnings are issued for optional parameters using defaults\r\n\r\nIf validation fails, you'll receive detailed error messages:\r\n\r\n```typescript\r\ntry {\r\n    const mcp = await NanoMCP.initialize();\r\n} catch (error) {\r\n    console.error('Configuration validation failed:', error.message);\r\n    // Example error message:\r\n    // Configuration validation failed:\r\n    // Errors:\r\n    // - NANO_RPC_KEY is required but not set\r\n    // - NANO_GPU_KEY is required but not set\r\n    // Warnings:\r\n    // - Using default representative address\r\n}\r\n```\r\n\r\n### Why NANO is Ideal for Agentic Transactions\r\n\r\n1. **Instant Finality**: \r\n   - Transactions complete in less than 1 second\r\n   - Perfect for real-time agent-to-agent interactions\r\n   - No waiting for multiple block confirmations like Bitcoin (10+ minutes)\r\n\r\n2. **Zero Fees**:\r\n   - Completely fee-less transactions\r\n   - Agents can perform unlimited micro-transactions without cost\r\n   - Enables efficient resource allocation and micro-payments\r\n\r\n3. **Energy Efficiency**:\r\n   - Uses minimal energy compared to Proof-of-Work chains\r\n   - Environmentally sustainable for large-scale agent networks\r\n   - ~0.000112 kWh per transaction vs Bitcoin's 707 kWh\r\n\r\n4. **Scalability**:\r\n   - Block-lattice architecture allows parallel processing\r\n   - Each account has its own blockchain\r\n   - Perfect for large-scale agent networks with millions of transactions\r\n\r\n5. **Deterministic Finality**:\r\n   - No need for probabilistic confirmation\r\n   - Agents can be certain of transaction status immediately\r\n   - Enables reliable decision-making in agent systems\r\n\r\n6. **Simple Integration**:\r\n   - Straightforward API for basic operations\r\n   - No complex smart contract overhead\r\n   - Ideal for focused agent-to-agent value transfer\r\n\r\nThis package provides a comprehensive set of utilities for handling NANO cryptocurrency transactions, enabling seamless integration into agent-based systems.\r\n\r\n## Features\r\n\r\n- Work generation with multiple fallback services\r\n- Account information retrieval\r\n- Pending blocks management\r\n- Block creation and processing:\r\n  - Opening blocks\r\n  - Receive blocks\r\n  - Send blocks\r\n- Transaction utilities:\r\n  - Send NANO\r\n  - Receive pending transactions\r\n  - Balance conversion\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install nanocurrency nanocurrency-web node-fetch\r\n```\r\n\r\n## Usage\r\n\r\n### Basic Setup\r\n\r\n```typescript\r\nimport { NanoTransactions } from './utils/nano-transactions';\r\n\r\nconst nano = new NanoTransactions({\r\n    apiUrl: 'https://rpc.nano.to/',  // Your RPC node URL\r\n    rpcKey: 'your-rpc-key',          // Optional: Your RPC authentication key\r\n    gpuKey: 'your-gpu-key'           // Optional: Your GPU service key for work generation\r\n});\r\n```\r\n\r\n### Generate Work\r\n\r\n```typescript\r\nconst hash = '000000000000000000000000000000000000000000000000000000000000000A';\r\nconst work = await nano.generateWork(hash);\r\nconsole.log('Generated work:', work);\r\n```\r\n\r\n### Get Account Information\r\n\r\n```typescript\r\nconst account = 'nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3';\r\nconst info = await nano.getAccountInfo(account);\r\nconsole.log('Account info:', info);\r\n```\r\n\r\n### Send NANO\r\n\r\n```typescript\r\nconst fromAddress = 'your-source-address';\r\nconst privateKey = 'your-private-key';\r\nconst toAddress = 'destination-address';\r\nconst amount = '0.00001';\r\n\r\n// First get account info\r\nconst accountInfo = await nano.getAccountInfo(fromAddress);\r\nif (accountInfo.error) {\r\n    throw new Error(`Failed to get account info: ${accountInfo.error}`);\r\n}\r\n\r\nconst result = await nano.createSendBlock(fromAddress, privateKey, toAddress, amount, accountInfo);\r\nconsole.log('Send transaction result:', result);\r\n```\r\n\r\n### Receive Pending Transactions\r\n\r\n```typescript\r\nconst address = 'your-address';\r\nconst privateKey = 'your-private-key';\r\nconst result = await nano.receiveAllPending(address, privateKey);\r\nconsole.log('Receive transaction result:', result);\r\n```\r\n\r\n## Testing\r\n\r\nTo run the tests:\r\n\r\n```bash\r\n# Set up environment variables\r\nexport RPC_KEY=your-rpc-key\r\nexport GPU_KEY=your-gpu-key\r\nexport TEST_ADDRESS=your-test-address\r\nexport TEST_PRIVATE_KEY=your-test-private-key\r\nexport TEST_SOURCE_BLOCK=source-block-hash\r\nexport TEST_SOURCE_AMOUNT=0.0001\r\nexport SOURCE_ADDRESS=your-source-address\r\nexport SOURCE_PRIVATE_KEY=your-source-private-key\r\nexport RECEIVE_ADDRESS=your-receive-address\r\nexport RECEIVE_PRIVATE_KEY=your-receive-private-key\r\n\r\n# Run specific tests\r\nexport TEST_OPEN=true      # Test opening blocks\r\nexport TEST_SEND=true      # Test send transactions\r\nexport TEST_RECEIVE=true   # Test receive transactions\r\n\r\n# Run the test suite\r\nnode test-nano-utils.js\r\n```\r\n\r\n## Security Considerations\r\n\r\n- Never share your private keys\r\n- Always validate addresses before sending transactions\r\n- Use secure RPC nodes\r\n- Implement proper error handling\r\n- Consider using environment variables for sensitive data\r\n\r\n## Error Handling\r\n\r\nThe utilities include comprehensive error handling:\r\n\r\n- Invalid addresses\r\n- Insufficient balance\r\n- Network errors\r\n- Invalid private keys\r\n- Block processing failures\r\n\r\nEach function returns detailed error information when something goes wrong.\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n\r\n# NANO MCP Implementation\r\n\r\nThis is a NANO cryptocurrency wallet implementation for MCP that includes a comprehensive test scenario.\r\n\r\n## Test Scenario\r\n\r\nThe test scenario demonstrates the following workflow:\r\n\r\n1. **Wallet Creation and Validation**\r\n   - Creates a first wallet\r\n   - Validates the key pair\r\n   - Displays wallet address and QR code for receiving funds\r\n\r\n2. **Fund Reception**\r\n   - Waits for 4 minutes for funds to be received\r\n   - Checks balance every 10 seconds\r\n   - Processes pending transactions when detected\r\n   - Verifies successful fund reception\r\n\r\n3. **Second Wallet Creation**\r\n   - Creates a second wallet\r\n   - Validates the key pair\r\n   - Prepares for fund transfer\r\n\r\n4. **Fund Transfer Test**\r\n   - Sends all funds from Wallet 1 to Wallet 2\r\n   - Waits for transaction processing\r\n   - Verifies successful reception in Wallet 2\r\n\r\n5. **Return Transfer Test**\r\n   - Sends all funds back from Wallet 2 to Wallet 1\r\n   - Waits for transaction processing\r\n   - Verifies final balances\r\n\r\n## Implementation Details\r\n\r\n- Uses `nanocurrency-web` for cryptographic operations\r\n- Connects to NANO RPC node at rpc.nano.to\r\n- Includes proper error handling and logging\r\n- Validates all key pairs and transactions\r\n- Handles both send and receive operations\r\n\r\n## Running the Test\r\n\r\n```bash\r\n# Install dependencies\r\nnpm install\r\n\r\n# Run the test\r\nnpm start\r\n```\r\n\r\n## Test Flow\r\n\r\n1. The test will generate a new wallet and display its address\r\n2. Send exactly 0.00001 NANO to the displayed address\r\n3. The test will automatically:\r\n   - Monitor for incoming funds\r\n   - Create a second wallet\r\n   - Transfer funds between wallets\r\n   - Verify all transactions\r\n\r\n## Error Handling\r\n\r\nThe test includes comprehensive error handling for:\r\n- Network issues\r\n- Transaction failures\r\n- Invalid states\r\n- Timeout conditions\r\n\r\n## Logging\r\n\r\nAll operations are logged with timestamps and full details in the `logs` directory. ","readmeFilename":"README.md","_rev":"1-fcae3ec72e0ffc76e17d6ffc3d1380b6"}