Priority-based broadcast messaging across the Yakmesh network.

v3.5.10

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_CONFIG } from 'yakmesh/mesh/beacon-broadcast';

// Create a broadcast message
const message = new StupaMessage({
  payload: { alert: 'Node cluster offline', region: 'asia-1' },
  priority: STUPA_CONFIG.priorities.FLASH,
  ttl: 20,              // hop count (default 10, max 50)
  originNodeId: nodeId
});

// Message properties
console.log(message.id);            // Unique message ID
console.log(message.priority);      // Priority level
console.log(message.hopPath);       // Nodes traversed so far
console.log(message.isValid());     // TTL/expiry/integrity check
console.log(message.ypc27);         // YPC-27 quantum-hard checksum

StupaBroadcast

The broadcast controller managing message propagation:

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

// Initialize the broadcast system (callbacks, not EventEmitter)
const stupa = new StupaBroadcast({
  nodeId,
  onBroadcast: (msg) => mesh.sendToAll(msg.serialize()),
  onReceive:   (msg) => console.log(`Received from ${msg.originNodeId}`),
  onReceipt:   (rcpt) => console.log('Delivery receipt:', rcpt),
});

// Register peers that carry broadcasts
for (const peerId of mesh.peerIds) stupa.addPeer(peerId);

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

// Priority helpers
await stupa.sendFlash({ alert: 'partition detected' });
await stupa.sendEmergency({ alert: 'critical' });
await stupa.sendRevocation('revocation:key_compromise', { dokoId });

Callbacks

STUPA uses constructor callbacks for broadcast lifecycle events:

Callback	Payload	Description
onReceive	StupaMessage	New broadcast received from the network
onBroadcast	StupaMessage	Message ready to send to peers (wire it to your transport)
onReceipt	DeliveryReceipt	Signed delivery receipt from a peer

Duplicates are filtered internally by the DeduplicationTracker; expired/invalid messages are dropped by receive() and counted in getStats().

Configuration

export const STUPA_CONFIG = {
  priorities: {
    ROUTINE: 0, PRIORITY: 1, IMMEDIATE: 2,
    FLASH: 3, CRITICAL: 4, REVOCATION: 5,
  },
  defaultTTL: 10,             // Default hop count
  maxTTL: 50,                 // Maximum hop count
  revocationTTL: 100,         // Extra hops for revocation broadcasts
  deduplicationWindowMs: 60000, // 1 minute dedup window
  receiptTimeout: 30000,      // 30s to collect delivery receipts
  minRedundantPaths: 3,       // Minimum paths for critical messages
  maxRetransmissions: 5,
  maxMessagesPerSecond: 100,  // Per-node rate limit
  priorityBoost: {            // Rate limit multiplier by priority
    ROUTINE: 1, PRIORITY: 2, IMMEDIATE: 5,
    FLASH: 10, CRITICAL: 100, REVOCATION: 1000,
  },
};

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

Provenance full version history →

Introduced in v1.3.1 — Beacon broadcast.

• v2.7.1 — STUPA broadcast protocol