YURT

Decentralized room discovery for YakApp chat rooms

The yak:// URI Scheme

YURT uses the yak:// URI scheme for direct room links. Like clicking a Zoom link, but for decentralized chat.

import { YurtLink } from 'yakmesh/mesh/yurt.js';

// Parse any yak:// link
const link = YurtLink.parse('yak://qrl-node.theqrl.org:8787/qrl-official');
console.log(link.host);     // 'qrl-node.theqrl.org'
console.log(link.port);     // 8787
console.log(link.bundleId); // 'qrl-official'
console.log(link.invite);   // null (or attestation object if present)

// Create a yak:// link
const uri = YurtLink.create('my-node.example.com', 'my-room');
// → 'yak://my-node.example.com/my-room'

// Browser fallback (for browsers without yak:// handler)
const httpsUrl = YurtLink.toHttpsGateway(uri);
// → 'https://yak.to/join/my-node.example.com:8787/my-room'

Discovery Modes

Room Entries

A YurtEntry represents a discoverable room listing. Entries are signed by the host node and can be propagated via gossip or accessed directly.

import { YurtEntry, YURT_CONFIG } from 'yakmesh/mesh/yurt.js';

// Create a room entry
const entry = new YurtEntry({
  bundleId: 'qrl-official',
  hostNodeId: myNode.identity.nodeId,
  hostEndpoint: 'qrl-node.theqrl.org:8787',
  name: 'QRL Official',
  description: 'Official Quantum Resistant Ledger community chat',
  visibility: YURT_CONFIG.visibility.PUBLIC,
  tags: ['qrl', 'crypto', 'quantum', 'official'],
  memberCount: 500,
});

// Sign with host's secret key (proves ownership)
entry.sign(myNode.identity.secretKey);

// Generate shareable link
const link = entry.toUri();
// → 'yak://qrl-node.theqrl.org:8787/qrl-official'

// For invite-only rooms, include attestation
const inviteLink = entry.toInviteUri(attestation);
// → 'yak://...?invite=...'

Visibility Types

Local Directory

The YurtDirectory maintains a local index of known rooms. It handles searching, indexing by tags/host, and automatic cleanup of expired entries.

import { YurtDirectory } from 'yakmesh/mesh/yurt.js';

const directory = new YurtDirectory();

// Add entries (from gossip or manual)
directory.add(entry);

// Search rooms
const results = directory.search({ 
  query: 'QRL', 
  tags: ['crypto'],
  visibility: 'public',
  limit: 20,
});

// Get by bundle ID
const room = directory.getByBundle('qrl-official');

// List all public rooms
const publicRooms = directory.listPublic(100);

// Get rooms by a specific host
const qrlRooms = directory.getByHost(qrlNodeId);

// Manual cleanup of expired entries
directory.cleanup();

Gossip Propagation

The YurtGossip module handles advertising rooms to the mesh network. Entries expire after 7 days without refresh, preventing stale listings.

import { YurtGossip, YurtDirectory } from 'yakmesh/mesh/yurt.js';

const directory = new YurtDirectory();
const gossip = new YurtGossip(identity, directory, mesh);

// Start gossip (periodic announcements + refresh)
gossip.start();

// Announce a new room
gossip.announce(entry);

// Search the network
const queryId = gossip.query({ query: 'QRL', tags: ['crypto'] });
gossip.on('query:response', (response) => {
  console.log('Found rooms:', response.entries);
});

// Withdraw a room from the network
gossip.withdraw('my-bundle-id');

// Stop gossip
gossip.stop();

Integration with GUMBA

YURT handles discovery. GUMBA handles access control. They work together seamlessly.

YurtHub

YurtHub combines directory, gossip, and GUMBA integration into one convenient interface.

import { YurtHub } from 'yakmesh/mesh/yurt.js';

const hub = new YurtHub(identity, gumbaHub, mesh, options);
hub.start();

// Publish a room from your GUMBA hub
hub.publishRoom('my-bundle-id', {
  name: 'My Awesome Room',
  description: 'A great place to chat',
  visibility: 'public',
  tags: ['community', 'tech'],
});

// Browse public rooms
const rooms = hub.browse({ limit: 50 });

// Search by query
const results = hub.search('crypto', { tags: ['qrl'] });

// Join via direct link
const joinResult = await hub.joinViaLink('yak://example.com/room-id');

// Get a shareable link
const link = hub.getJoinLink('my-bundle-id');

// With invite for private rooms
const inviteLink = hub.getJoinLink('private-room', { invite: attestation });

Real-World Example: QRL Official

// On the QRL server (qrl-node.theqrl.org)
import { YurtHub, YurtEntry } from 'yakmesh/mesh/yurt.js';
import { GumbaHub } from 'yakmesh/mesh/gumba.js';

// Create the GUMBA bundle for the room
const gumbaHub = new GumbaHub(identity, annex);
const bundle = gumbaHub.createBundle('qrl-official', {
  name: 'QRL Official',
  description: 'Official Quantum Resistant Ledger community',
});

// Create the YURT hub and publish the room
const yurtHub = new YurtHub(identity, gumbaHub, mesh, {
  endpoint: 'qrl-node.theqrl.org:8787',
});
yurtHub.start();

yurtHub.publishRoom('qrl-official', {
  name: 'QRL Official',
  description: 'Official Quantum Resistant Ledger community chat',
  tags: ['qrl', 'crypto', 'quantum', 'official'],
  visibility: 'public',
});

// Get the link to post on theqrl.org
const joinLink = yurtHub.getJoinLink('qrl-official');
console.log('Post this on the website:', joinLink);
// → yak://qrl-node.theqrl.org:8787/qrl-official

Security Considerations

Himalayan Protocol Family