Priority-based broadcast messaging across the Yakmesh network.

v2.5.0

Overview

STUPA (Signal Transmission Unit for Peer Awareness) provides priority-based broadcast messaging for the Yakmesh network. Unlike MANTRA's epidemic gossip, STUPA messages are explicitly broadcast to all connected peers with priority levels that determine propagation urgency.

Priority Levels

STUPA messages carry priority levels inspired by the tiers of a stupa's ascending structure. Higher priority messages propagate faster and with greater urgency:

Core Components

StupaMessage

The fundamental message unit for broadcasts:

import { StupaMessage, STUPA_PRIORITY } from 'yakmesh/mesh/beacon-broadcast';

// Create a broadcast message
const message = new StupaMessage({
  type: 'NETWORK_ALERT',
  payload: { alert: 'Node cluster offline', region: 'asia-1' },
  priority: STUPA_PRIORITY.FLASH,
  ttl: 300, // 5 minutes
  origin: nodeId
});

// Message properties
console.log(message.id);        // Unique message ID
console.log(message.priority);  // Priority level
console.log(message.hops);      // Propagation count
console.log(message.isExpired); // TTL check

StupaBroadcast

The broadcast controller managing message propagation:

import { StupaBroadcast, STUPA_CONFIG } from 'yakmesh/mesh/beacon-broadcast';

// Initialize the broadcast system
const stupa = new StupaBroadcast(node, {
  ...STUPA_CONFIG,
  maxHops: 10,
  deduplicationWindow: 60000 // 1 minute
});

// Broadcast a message
await stupa.broadcast({
  type: 'CONSENSUS_REACHED',
  payload: { decision: 'upgrade-v2', votes: 42 },
  priority: STUPA_PRIORITY.IMMEDIATE
});

// Listen for broadcasts
stupa.on('message', (message) => {
  console.log(`Received ${message.type} from ${message.origin}`);
  console.log(`Priority: ${stupa.getPriorityName(message.priority)}`);
});

Event System

STUPA emits events for broadcast lifecycle management:

Event	Payload	Description
message	StupaMessage	New broadcast received from the network
broadcast	StupaMessage	Message successfully broadcast to peers
forward	StupaMessage	Message forwarded to next-hop peers
expired	StupaMessage	Message TTL exceeded, dropped
duplicate	messageId	Duplicate message detected and filtered

Configuration

export const STUPA_CONFIG = {
  // Message propagation
  maxHops: 10,              // Maximum hop count before drop
  defaultTTL: 3600,         // Default message TTL (1 hour)
  
  // Deduplication
  deduplicationWindow: 60000, // Duplicate detection window (ms)
  maxSeenMessages: 10000,     // Message ID cache size
  
  // Priority handling
  priorityQueues: true,       // Enable priority-based queuing
  criticalBypass: true,       // CRITICAL skips normal queue
  
  // Rate limiting
  maxBroadcastsPerMinute: 60, // Outbound rate limit
  burstAllowance: 10          // Burst capacity
};

Message Flow

Security Considerations

• Message Signing: All broadcasts are cryptographically signed by origin
• Priority Abuse Prevention: Rate limiting prevents CRITICAL spam
• TTL Enforcement: Expired messages are dropped, preventing replay attacks
• Hop Limiting: Maximum hop count prevents infinite propagation loops
• Origin Verification: KARMA scores influence broadcast acceptance
• YPC-27 Checksums: Quantum-hard checksums protect message integrity. Learn more →

Integration with Other Protocols

Backward Compatibility

For existing codebases using the original "Beacon" naming, legacy exports are maintained:

// Legacy imports still work
import { BeaconBroadcast, BeaconMessage, BEACON_CONFIG } from 'yakmesh/mesh/beacon-broadcast';

// These map to the new STUPA names
// BeaconBroadcast → StupaBroadcast
// BeaconMessage → StupaMessage
// BEACON_CONFIG → STUPA_CONFIG