our-network

Privacy-preserving P2P networking with onion-routed circuits, seed node discovery, and quality of service for the ourochronos ecosystem.

Overview

our-network implements the transport layer for Valence's federated architecture. Messages are end-to-end encrypted at the source and relayed through multi-hop onion circuits — routers only know the previous and next hop, never the full path or message content. The system includes decentralized seed nodes for router discovery, contribution-based QoS, and configurable traffic analysis mitigations.

Install

pip install our-network

Requires cryptography>=42.0 and aiohttp>=3.9.

Usage

Discovery

from our_network import create_discovery_client

discovery = create_discovery_client(
    seed_urls=["https://seed1.example.com", "https://seed2.example.com"],
    cache_ttl_seconds=3600,
)

# Find routers (signature-verified, health-ranked)
routers = await discovery.discover_routers(count=5)

Node Client

from our_network import create_node_client

node = await create_node_client(
    node_id="user-123",
    discovery=discovery,
    target_connections=5,
    min_connections=2,
)

# Send message through onion circuit
await node.send_message(message_data, recipient_id)

End-to-End Encryption

from our_network import (
    generate_identity_keypair,
    generate_encryption_keypair,
    encrypt_message,
    decrypt_message,
)

# Ed25519 for signing, X25519 for encryption
identity = generate_identity_keypair()
encryption = generate_encryption_keypair()

ciphertext = encrypt_message(b"belief data", recipient_public_key)
plaintext = decrypt_message(ciphertext, recipient_private_key)

Onion Routing

from our_network import create_onion, peel_onion

# Build layered encryption for a 3-hop circuit
onion = create_onion(payload, circuit_keys=[hop1_key, hop2_key, hop3_key])

# Each router peels one layer
next_payload = peel_onion(onion, hop1_key)

Quality of Service

from our_network import ContributionScore, ContributionDimension, QoSPolicy

score = ContributionScore(node_id="user-123")
score.set_dimension(ContributionDimension.ROUTING_CAPACITY, 0.8)
score.set_dimension(ContributionDimension.UPTIME_RELIABILITY, 0.9)

policy = QoSPolicy()
tier = policy.assign_tier(score.overall)       # PriorityTier enum
priority = policy.compute_priority(score.overall, load_factor=0.7)

Privacy Levels

from our_network import PrivacyLevel, get_recommended_config

# LOW: minimal latency, basic encryption
# MEDIUM: batching + jitter
# HIGH: constant-rate padding
# PARANOID: mix network integration
config = get_recommended_config(PrivacyLevel.HIGH)

API

Core Crypto

generate_identity_keypair(), generate_encryption_keypair(), encrypt_message(), decrypt_message(), create_onion(), peel_onion()

Networking

QoS

Traffic Analysis Mitigations

PrivacyLevel, BatchingConfig, TimingJitterConfig, ConstantRateConfig, MixNetworkConfig

Key Properties

• End-to-end encryption: AES-256-GCM with X25519 key exchange
• Onion routing: Per-hop keys, routers can't see full path
• Anti-Sybil: Proof-of-work registration, reputation scoring, correlation detection
• IP/ASN diversity: Prevents eclipse attacks by enforcing diverse connections
• Connection recovery: State persistence and automatic failover
• 662 tests covering routing, discovery, QoS, security, and state recovery

Development

# Install with dev dependencies
make dev

# Run linters
make lint

# Run tests
make test

# Run tests with coverage
make test-cov

# Auto-format
make format

State Ownership

Owns connection state, circuit state, router records (at seed nodes), and QoS scores. Node clients can persist connection state for recovery across restarts.

Part of Valence

This brick is part of the Valence knowledge substrate. See our-infra for ourochronos conventions.

License

MIT