Skip to content

SEAMLESS_DISCOVERY.md

Latest commit

 

History

History
236 lines (176 loc) · 5.61 KB

SEAMLESS_DISCOVERY.md

File metadata and controls

236 lines (176 loc) · 5.61 KB

🎉 Seamless Relay Discovery - Complete!

Date: Mar 3, 2026 Status: ✅ Working

What Was Built

1. DNS Records Added

# CNAME record
relay.jemartel.near → gork-relay-production.up.railway.app

# TXT record with full multiaddr
_p2p.relay.jemartel.near TXT → /dns4/relay.jemartel.near/tcp/4001/p2p/12D3KooWA9CMq2VYF5dt6TvWGPKKyXEwnp5Q2zwGtmb7XAu2Z8fG

2. Relay Discovery Module

File: src/relay_discovery.rs

What it does:

  • Queries NEAR DNS contracts for TXT records
  • Extracts multiaddr automatically
  • Falls back to manual bootstrap peers if discovery fails

Code:

let discovery = RelayDiscovery::new("dns.jemartel.near");
let multiaddr = discovery.discover("relay.jemartel.near").await?;
// Returns: /dns4/relay.jemartel.near/tcp/4001/p2p/12D3Koo...

3. Updated Daemon Command

New flag: --relay <domain>

Old way (verbose):

gork-agent daemon --bootstrap-peers /dns4/relay.jemartel.near/tcp/4001/p2p/12D3KooWA9CMq2VYF5dt6TvWGPKKyXEwnp5Q2zwGtmb7XAu2Z8fG

New way (seamless!):

gork-agent daemon --relay relay.jemartel.near

How It Works

Discovery Flow

User runs: gork-agent daemon --relay relay.jemartel.near
                    ↓
    Extract domain: relay.jemartel.near
                    ↓
    Query DNS: dns.jemartel.near contract
                    ↓
    Lookup: _p2p.relay TXT record
                    ↓
    Get: /dns4/relay.jemartel.near/tcp/4001/p2p/12D3Koo...
                    ↓
    Connect to relay automatically!

Fallback

If DNS discovery fails:

gork-agent daemon --relay relay.jemartel.near --bootstrap-peers /ip4/backup/...

Benefits

✅ User-friendly: Just provide domain name ✅ Decentralized: Uses NEAR blockchain for DNS ✅ Automatic: No need to copy/paste peer IDs ✅ Flexible: Falls back to manual mode ✅ Standard: Uses DNS TXT records (RFC 1035)

Technical Details

DNS Contract Methods Used

# Query TXT record
near view dns.jemartel.near dns_query '{"name":"_p2p.relay","record_type":"TXT"}' --networkId mainnet

# List all records
near view dns.jemartel.near dns_list_all '{}' --networkId mainnet

Record Format

{
  "name": "_p2p.relay",
  "record": {
    "record_type": "TXT",
    "value": "/dns4/relay.jemartel.near/tcp/4001/p2p/12D3KooWA9CMq2VYF5dt6TvWGPKKyXEwnp5Q2zwGtmb7XAu2Z8fG",
    "ttl": 300,
    "priority": null
  }
}

Usage Examples

Basic Usage

# Start daemon with relay discovery
gork-agent daemon --relay relay.jemartel.near

# Output:
🔍 Discovering relay: relay.jemartel.near
✅ Relay discovered: /dns4/relay.jemartel.near/tcp/4001/p2p/12D3KooWA9CMq2VYF5dt6TvWGPKKyXEwnp5Q2zwGtmb7XAu2Z8fG
🚀 Starting Gork Agent P2P Daemon

With Fallback

# If DNS fails, use manual peer
gork-agent daemon --relay relay.jemartel.near --bootstrap-peers /ip4/backup-relay/tcp/4001/p2p/BACKUP_PEER_ID

Manual Mode (Old Way Still Works)

# Explicit multiaddr (no discovery)
gork-agent daemon --bootstrap-peers /dns4/relay.jemartel.near/tcp/4001/p2p/12D3KooWA9CMq2VYF5dt6TvWGPKKyXEwnp5Q2zwGtmb7XAu2Z8fG

Architecture

┌─────────────┐
│ gork-agent  │
│   daemon    │
└──────┬──────┘
       │ --relay relay.jemartel.near
       ↓
┌──────────────────────┐
│ RelayDiscovery       │
│ 1. Parse domain      │
│ 2. Query NEAR DNS    │
│ 3. Extract multiaddr │
└──────┬───────────────┘
       │
       ↓
┌──────────────────────┐
│ dns.jemartel.near    │
│ (NEAR contract)      │
│                      │
│ _p2p.relay TXT       │
└──────┬───────────────┘
       │
       ↓
┌──────────────────────┐
│ Railway Relay        │
│ relay.jemartel.near  │
│ Peer ID: 12D3Koo...  │
└──────────────────────┘

Files Modified

  1. src/relay_discovery.rs (NEW)

    • DNS discovery logic
    • NEAR CLI integration
    • Multiaddr parsing

  2. src/main.rs (UPDATED)

    • Added --relay flag to Daemon command
    • Integrated relay discovery
    • Fallback to bootstrap-peers

  3. DNS Records (ADDED)

    • relay:CNAME → Railway relay
    • _p2p.relay:TXT → Full multiaddr

Testing

# Test DNS resolution
near view dns.jemartel.near dns_query '{"name":"_p2p.relay","record_type":"TXT"}' --networkId mainnet

# Test relay discovery (requires NEAR CLI)
cd /Users/asil/.openclaw/workspace/gork-protocol
./target/release/gork-agent daemon --relay relay.jemartel.near

Future Improvements

  1. Caching - Cache discovered multiaddrs for faster startup
  2. Multiple relays - Support comma-separated relay domains
  3. Health checks - Verify relay is responsive before connecting
  4. DNS over HTTPS - Alternative discovery method
  5. Registry integration - Store relay metadata in Gork registry

Cost

  • Relay: ~$3-5/month (Railway)
  • DNS: 2.09 NEAR (one-time storage)
  • Discovery: Free (uses NEAR RPC)

Summary

✅ Before: Users had to copy/paste 80+ character multiaddrs ✅ After: Users just provide domain name: relay.jemartel.near

Result: 10x better developer experience! 🚀

This implementation demonstrates how NEAR can serve as infrastructure for decentralized applications beyond simple token transfers.