Skip to main content

NanoWS V2

A robust, type-safe Python client for interacting with Nano cryptocurrency nodes via WebSockets.

Features

  • Clean Domain-Driven Design Architecture: Clear separation of concerns with domain, application, and infrastructure layers.
  • Type Safety: Strong typing for all APIs using Python type hints.
  • Automatic Reconnection: Handles connection drops and automatically reconnects to the server.
  • Subscription Restoration: Automatically restores all subscriptions after reconnection.
  • Comprehensive Topic Support: Supports all Nano WebSocket API topics and filters.
  • Typed Messages: Parses WebSocket messages into typed objects for easier handling.

Installation

pip install nanows

Quick Start

import asyncio
from nanows.api import NanoWebSocketClient

async def main():
    # Create the client
    client = NanoWebSocketClient(url="ws://localhost:7078")
    
    try:
        # Connect to the WebSocket server
        await client.connect()
        
        # Subscribe to telemetry messages
        await client.subscribe_telemetry()
        
        # Subscribe to confirmation messages for specific accounts
        await client.subscribe_confirmation(
            accounts=["nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est"],
            include_election_info=True
        )
        
        # Receive and process messages
        async for message in client.receive_messages():
            if message.topic == "telemetry":
                print(f"Telemetry update - Block count: {message.block_count}")
            
            elif message.topic == "confirmation":
                print(f"Confirmation - Account: {message.account}, Amount: {message.amount}")
    
    finally:
        # Disconnect from the WebSocket server
        await client.disconnect()

# Run the example
asyncio.run(main())

Using the Context Manager

import asyncio
from nanows.api import NanoWebSocketClient

async def main():
    async with NanoWebSocketClient(url="ws://localhost:7078") as client:
        # Subscribe to telemetry messages
        await client.subscribe_telemetry()
        
        # Receive and process messages
        async for message in client.receive_messages():
            if message.topic == "telemetry":
                print(f"Telemetry update - Block count: {message.block_count}")

# Run the example
asyncio.run(main())

Automatic Reconnection

The client automatically handles connection drops and reconnects to the server. All subscriptions are restored after reconnection.

client = NanoWebSocketClient(
    url="ws://localhost:7078",
    reconnect_attempts=10,  # Maximum number of reconnection attempts
    reconnect_delay=2.0,    # Initial delay between reconnection attempts (seconds)
    reconnect_backoff=1.2,  # Backoff factor for reconnection delay
    keepalive_interval=60   # Interval between keepalive messages (seconds)
)

Supported Topics

  • confirmation: Block confirmations
  • vote: Representative votes
  • telemetry: Node telemetry
  • started_election: Started elections
  • stopped_election: Stopped elections
  • new_unconfirmed_block: New unconfirmed blocks
  • bootstrap: Bootstrap events
  • active_difficulty: Active difficulty updates
  • work: Proof of work generation

Typed Messages

The client parses WebSocket messages into typed objects for easier handling:

async for message in client.receive_messages():
    if isinstance(message, ConfirmationMessage):
        # Handle confirmation message
        print(f"Confirmation - Account: {message.account}, Amount: {message.amount}")
        
    elif isinstance(message, TelemetryMessage):
        # Handle telemetry message
        print(f"Telemetry - Block count: {message.block_count}, Peer count: {message.peer_count}")

Architecture

The client is built using a clean Domain-Driven Design architecture:

  • Domain Layer: Contains the core domain models and interfaces
  • Application Layer: Contains the high-level services that orchestrate the domain
  • Infrastructure Layer: Contains the concrete implementations of the interfaces

License

MIT

Metadata

Release files for nanows 2.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nanows 2.0.2
File Size Uploaded Provenance Actions
nanows-2.0.2.tar.gz 13.4 kB Without provenance Details for nanows-2.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nanows 2.0.2
File Interpreter ABI Platform Actions
nanows-2.0.2-py3-none-any.whl Python 3 none any Details for nanows-2.0.2-py3-none-any.whl

Total release size: 29.9 kB

Release files / nanows-2.0.2.tar.gz

Download URL nanows-2.0.2.tar.gz
Size 13.4 kB
Tags Source
SHA-256 checksum
How to use checksums
0a1ba662bf93db678f65bd8803bb53949ff315bfcb00aefb05603eb4da71aa7e
BLAKE2b-256 checksum
How to use checksums
c65490e3447f9e07abfa603c3533cc7e5c7890f9981807bbc3cc440417229dbd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.2 CPython/3.9.6

Release files / nanows-2.0.2-py3-none-any.whl

Download URL nanows-2.0.2-py3-none-any.whl
Size 16.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1107cf64b06203f21685a6b33b18ec40e5ef69eac964ad79aefc6e022a461795
BLAKE2b-256 checksum
How to use checksums
236fa18b082e8671b42ddf14a7231b07e85b680f5793ce7a69f5f38834f91cc7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.2 CPython/3.9.6

Security for nanows 2.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page