DogeNet P2P Network

Peer-to-peer gossip networking system for decentralized distribution of tokenization data

DogeNet is a peer-to-peer gossip networking system that enables decentralized distribution of tokenization data across the Fractal Engine network. This document provides comprehensive information about DogeNet's architecture, configuration, and operation.

Overview and Purpose

DogeNet serves as the communication backbone for the Fractal Engine ecosystem, enabling nodes to share tokenization data without requiring full blockchain synchronization. The system distributes:

Token Mints: New token creation announcements
Buy/Sell Offers: Trading proposals between users
Invoices: Payment requests for token transactions

Key Benefits

Decentralized: No central coordinator required
Resilient: Network continues operating even if nodes fail
Efficient: Only relevant tokenization data is shared
Secure: All messages are cryptographically signed
Real-time: Immediate propagation of market data

Gossip Protocol Mechanics

Message Types

DogeNet handles six distinct message types, each with specific purposes:

Message Type	Tag	Purpose
Mint	`TagMint`	Announce new token creation
Buy Offer	`TagBuyOffer`	Broadcast buy orders
Sell Offer	`TagSellOffer`	Broadcast sell orders
Invoice	`TagInvoice`	Share payment requests
Delete Buy Offer	`TagDeleteBuyOffer`	Cancel buy orders
Delete Sell Offer	`TagDeleteSellOffer`	Cancel sell orders

Protocol Structure

Message Envelope Format

All DogeNet messages use a standardized envelope structure:

type MessageEnvelope struct {
    Type      protocol.ActionType  // Message type identifier
    Version   int32               // Protocol version
    Payload   interface{}         // Message-specific data
    PublicKey string             // Sender's public key (for signed messages)
    Signature string             // Cryptographic signature (for signed messages)
}

Channel and Tag System

DogeNet uses the dnet protocol's channel/tag system for message routing:

Channel: ChanFE (FractalEngine) - All DogeNet messages use this channel
Tags: Specific message type identifiers for routing

Message Flow

Outbound Messages

Serialize: Convert data structures to Protocol Buffers format
Sign: Add cryptographic signature (for offers/invoices)
Encode: Wrap in dnet message format
Send: Transmit via TCP socket to DogeNet daemon

Inbound Messages

Receive: Read from TCP socket
Decode: Extract message from dnet format
Route: Direct to appropriate handler based on tag
Verify: Validate signatures and addresses
Process: Store or forward message as appropriate

Node Discovery and Peer Management

Connection Management

DogeNet clients connect to a local DogeNet daemon via TCP socket. The daemon handles:

Peer Discovery: Finding other nodes in the network
Connection Pooling: Managing connections to multiple peers
Message Routing: Forwarding messages between peers
Network Health: Monitoring connection status

HTTP Management API

DogeNet provides an HTTP API for node management:

Get Peers

GET /peers

Returns list of connected peers:

[
  {
    "pubkey": "03abc123...",
    "address": "192.168.1.100:42069",
    "identity": "node1"
  }
]

Add Peer

POST /addpeer
Content-Type: application/json

{
  "key": "03def456...",
  "addr": "192.168.1.200:42069"
}

Handshake Protocol

When connecting to DogeNet, clients perform a handshake:

Connect: Establish TCP connection to DogeNet daemon
Bind: Send BindMessage with client's public key and channel
Verify: Receive and validate BindMessage response
Ready: Begin message processing

bind := dnet.BindMessage{
    Version: 1, 
    Chan: ChanFE, 
    PubKey: *client.feKey.Pub
}

Network Topology and Message Propagation

Network Architecture

DogeNet forms a mesh network where:

Nodes: Run DogeNet daemon and connect to peers
Clients: Connect to local daemon via TCP
Messages: Propagate through gossip protocol

Message Propagation Strategy

DogeNet uses epidemic-style gossip propagation:

Initial Broadcast: Message originates from one node
Peer Selection: Node selects subset of connected peers
Forward: Send message to selected peers
Duplicate Detection: Receiving nodes check for duplicates
Continue: Process repeats until network saturation

Integration with Dogecoin Network

dnet Protocol

DogeNet builds on the code.dogecoin.org/gossip/dnet library, which provides:

Low-level Networking: TCP socket management
Message Encoding: Binary message format
Cryptography: Key pair generation and signing
Channel System: Message routing infrastructure

Key Pair Integration

DogeNet integrates with Dogecoin cryptography:

// Generate DogeNet key pair
kp, err := dnet.GenerateKeyPair()
cfg.DogeNetKeyPair = kp

// Convert to Dogecoin address for validation
address, err := doge.PublicKeyToDogeAddress(publicKey, doge.PrefixRegtest)

Address Validation

All signed messages (offers, invoices) verify that:

Public key matches the claimed Dogecoin address
Signature is valid for the message payload
Address format is correct for the network (mainnet/regtest)

Configuration Options

Core DogeNet Settings

Configure DogeNet through command-line flags or configuration struct:

type Config struct {
    DogeNetNetwork     string        // Network type (tcp)
    DogeNetAddress     string        // DogeNet daemon address
    DogeNetWebAddress  string        // HTTP API address
    DogeNetKeyPair     dnet.KeyPair  // Client key pair
}

Default Configuration

cfg := config.NewConfig()
// DogeNetNetwork:    "tcp"
// DogeNetAddress:    "0.0.0.0:42069"
// DogeNetWebAddress: "0.0.0.0:8085"

Command Line Options

# DogeNet daemon connection
--doge-net-network=tcp
--doge-net-address=0.0.0.0:8086
--doge-net-web-address=0.0.0.0:8085

# Rate limiting
--api-rate-limit-per-second=10
--invoice-limit=100
--buy-offer-limit=3
--sell-offer-limit=3

Docker Environment Variables

When running via Docker:

# DogeNet daemon settings
DOGENET_BIND_HOST=0.0.0.0
DOGENET_BIND_PORT=42000
DOGENET_WEB_PORT=8085
DOGE_NET_HANDLER=unix:///tmp/dogenet.sock

# Network configuration
DOGE_NET_ADDRESS=dogenet:42000
DOGE_NET_NETWORK=tcp

Running a DogeNet Node

Prerequisites

Go 1.24 or later
Access to Dogecoin RPC node
PostgreSQL database (for persistence)

Standalone Installation

Clone DogeNet daemon:

git clone https://github.com/Dogebox-WG/dogenet.git
cd dogenet
go build -o dogenet ./cmd/dogenet

Generate keys:

./dogenet genkey dev-key
./dogenet genkey ident-key ident-pub

Start daemon:

export KEY=$(cat dev-key)
export IDENT=$(cat ident-pub)
./dogenet --local --public 0.0.0.0 --handler unix:///tmp/dogenet.sock --web 0.0.0.0:8085 --bind 0.0.0.0:42000

Docker Deployment

Use the provided Docker setup:

# Start DogeNet dependencies
docker compose --profile deps up dogenet

# Start full Fractal Engine stack
docker compose --profile fractal up

Fractal Engine Integration

Run Fractal Engine with DogeNet:

./fractal-engine \
  --doge-net-address=127.0.0.1:42000 \
  --doge-net-web-address=127.0.0.1:8085 \
  --database-url="postgres://user:pass@localhost/fractal"

Client Connection Example

// Create DogeNet client
cfg := config.NewConfig()
cfg.DogeNetAddress = "127.0.0.1:42000"
cfg.DogeNetKeyPair, _ = dnet.GenerateKeyPair()

client := dogenet.NewDogeNetClient(cfg, tokenStore)

// Start client
statusChan := make(chan string)
go client.Start(statusChan)

// Wait for connection
status := <-statusChan
fmt.Printf("DogeNet status: %s", status)

Network Security and Spam Protection

Cryptographic Security

Message Signing

All offers and invoices require cryptographic signatures:

// Sign buy offer payload
offerPayload := protocol.BuyOfferPayload{
    OffererAddress: "DTC8Y8KEAL5V...",
    MintHash: "abc123...",
    Quantity: 100,
    Price: 1000,
}
payloadBytes, _ := protojson.Marshal(&offerPayload)
signature := sign(payloadBytes, privateKey)

Signature Verification

Receiving nodes validate all signatures:

// Verify signature matches claimed address
err := doge.ValidateSignature(payloadBytes, publicKey, signature)
if err != nil {
    return fmt.Errorf("invalid signature: %w", err)
}

// Verify public key matches Dogecoin address
address, err := doge.PublicKeyToDogeAddress(publicKey, networkPrefix)
if address != offer.OffererAddress {
    return fmt.Errorf("address mismatch")
}

Rate Limiting

DogeNet implements several spam protection mechanisms:

API Rate Limits

Global: 10 requests per second per client
Invoices: 100 per mint maximum
Buy Offers: 3 per buyer per mint
Sell Offers: 3 per seller per mint

Message Validation

Duplicate Detection: Messages with identical hashes are rejected
Address Validation: All Dogecoin addresses must be valid
Signature Requirements: Offers and invoices must be properly signed

Network-Level Protection

Connection Limits: DogeNet daemon manages peer connections
Message Size Limits: Large messages are rejected
Protocol Compliance: Invalid message formats are dropped

Troubleshooting Common Issues

Connection Problems

Cannot Connect to DogeNet Daemon

Symptoms: cannot connect: connection refused

Solutions:

Verify DogeNet daemon is running:

curl http://localhost:8085/peers

Check daemon logs:

docker logs dogenet-1

Verify network configuration:

netstat -ln | grep 42000

Handshake Failures

Symptoms: invalid BindMessage reply

Solutions:

Check protocol version compatibility
Verify key pair generation:

kp, err := dnet.GenerateKeyPair()
if err != nil {
    log.Fatalf("Key generation failed: %v", err)
}

Ensure proper channel configuration:

bind := dnet.BindMessage{
    Version: 1,
    Chan: dogenet.ChanFE,  // Must match expected channel
    PubKey: *keyPair.Pub,
}

Message Processing Issues

Signature Validation Failures

Symptoms: Error validating signature

Debugging:

Verify message payload format:

// Ensure consistent JSON marshaling
payload, err := protojson.Marshal(&offerPayload)

Check address derivation:

address, err := doge.PublicKeyToDogeAddress(publicKey, doge.PrefixRegtest)
log.Printf("Derived address: %s, Expected: %s", address, expectedAddress)

Validate signature creation:

signature := doge.SignMessage(payload, privateKey)
err := doge.ValidateSignature(payload, publicKey, signature)

Missing Messages

Symptoms: Messages not appearing in network

Debugging:

Check client status:

err := client.CheckRunning()
if err != nil {
    log.Printf("DogeNet not running: %v", err)
}

Monitor message channel:

select {
case msg := <-client.Messages:
    log.Printf("Received: %s", msg.Tag)
case <-time.After(10 * time.Second):
    log.Printf("No messages received")
}

Verify message encoding:

data, err := proto.Marshal(&envelope)
if err != nil {
    log.Printf("Marshal error: %v", err)
}
encodedMsg := dnet.EncodeMessageRaw(ChanFE, TagMint, keyPair, data)

Performance Issues

High Memory Usage

Solutions:

Implement message cleanup:

// Clean up old messages periodically
go func() {
    ticker := time.NewTicker(1 * time.Hour)
    for range ticker.C {
        store.CleanupOldMessages(time.Now().Add(-24 * time.Hour))
    }
}()

Monitor channel buffer:

if len(client.Messages) > 1000 {
    log.Println("Warning: Message channel backing up")
}

Network Congestion

Solutions:

Increase rate limits (if appropriate):

--api-rate-limit-per-second=20

Monitor peer connections:

curl http://localhost:8085/peers | jq length

Check network latency:

ping dogenet-peer-address

Testing and Debugging

Running DogeNet Tests

# Unit tests
go test ./pkg/dogenet/

# Integration tests
go test ./pkg/dogenet/ -run TestDogenet

# End-to-end tests
go test ./internal/test/e2e/dogenet/

# Verbose output
go test -v ./pkg/dogenet/

Mock Testing Setup

// Create mock connection for testing
clientConn, serverConn := net.Pipe()
client := dogenet.NewDogeNetClient(cfg, store)

// Test message flow
go client.StartWithConn(statusChan, clientConn)
// Send test messages via serverConn

Debug Logging

Enable detailed logging:

log.SetLevel(log.DebugLevel)
log.Printf("[FE] Message details: Chan=%s, Tag=%s, Size=%d", 
    msg.Chan, msg.Tag, len(msg.Payload))

Health Monitoring

Service Health Checks

# DogeNet daemon health
curl http://localhost:8085/

# Fractal Engine health
curl http://localhost:8891/health

# Database connectivity
curl http://localhost:8891/health | jq .database

Performance Metrics

Monitor key metrics:

Message throughput (messages/second)
Connection count
Memory usage
Network latency
Error rates

// Example metrics collection
type Metrics struct {
    MessagesReceived int64
    MessagesSent     int64
    Errors          int64
    LastUpdate      time.Time
}

This comprehensive guide covers all aspects of DogeNet operation. For additional support, refer to the test files in pkg/dogenet/ and the integration examples in internal/test/e2e/dogenet/.

DogeNet P2P Network

On this page