XSWD Protocol Overview

XSWD (Cross-Platform Secure WebSocket for DERO) is the secure communication protocol that connects TELA applications to DERO wallets and the blockchain network.

🔐

Security First: XSWD provides secure, encrypted communication between your TELA application and the user's DERO wallet, ensuring private keys never leave the wallet environment.

What is XSWD?

XSWD enables TELA applications to:

Connect to DERO wallets (Engram, CLI wallet)
Access blockchain data through the user's node
Submit transactions securely through the wallet
Maintain privacy with encrypted communication
Work offline when wallet is local

Key Benefits

🔒 Secure: Private keys never exposed to applications
⚡ Fast: Direct WebSocket connection for real-time data
🛡️ Private: All communication through user's own node
🔄 Reliable: Built-in retry and error handling
📱 Cross-Platform: Works with all DERO wallet implementations

🔌 Connection Architecture

TELA Application ←→ XSWD Protocol ←→ DERO Wallet ←→ DERO Network
     (Your App)      (WebSocket)      (Engram/CLI)    (Blockchain)

Connection Flow

Application Start: TELA app attempts XSWD connection
Handshake: App sends identification data
Wallet Approval: User approves/denies connection
Secure Channel: Encrypted communication established
API Access: Full DERO RPC methods available

Basic Implementation

Connection Setup

// Basic XSWD connection
function connectToXSWD() {
    const applicationData = {
        "id": "your-unique-app-id",
        "name": "Your TELA Application",
        "description": "Description of your app functionality", 
        "url": "http://localhost:" + location.port
    };
    
    const socket = new WebSocket("ws://127.0.0.1:44326/xswd");
    
    socket.addEventListener("open", function(event) {
        console.log("🔗 XSWD connection opened");
        socket.send(JSON.stringify(applicationData));
    });
    
    socket.addEventListener("message", function(event) {
        const response = JSON.parse(event.data);
        
        if (response.accepted) {
            console.log("✅ XSWD connection accepted");
            // Connection established - can now make API calls
        } else if (response.jsonrpc) {
            // Handle API response
            handleAPIResponse(response);
        }
    });
    
    socket.addEventListener("close", function(event) {
        console.log("🔌 XSWD connection closed");
    });
    
    socket.addEventListener("error", function(event) {
        console.error("🚨 XSWD connection error:", event);
    });
    
    return socket;
}

Making API Calls

// Make RPC calls through XSWD
function makeXSWDCall(socket, method, params = {}) {
    return new Promise((resolve, reject) => {
        const request = {
            "jsonrpc": "2.0",
            "id": Math.random().toString(36),
            "method": method,
            "params": params
        };
        
        // Store pending request for response handling
        pendingRequests.set(request.id, { resolve, reject });
        
        // Send request
        socket.send(JSON.stringify(request));
        
        // Set timeout
        setTimeout(() => {
            if (pendingRequests.has(request.id)) {
                pendingRequests.delete(request.id);
                reject(new Error('Request timeout'));
            }
        }, 30000);
    });
}
 
// Usage examples
const networkInfo = await makeXSWDCall(socket, 'DERO.GetInfo');
const balance = await makeXSWDCall(socket, 'GetBalance');
const block = await makeXSWDCall(socket, 'DERO.GetBlock', { height: 12345 });

📚 Available Methods

DERO Core Methods

DERO.GetInfo - Network status and statistics
DERO.GetBlock - Block data by height or hash
DERO.GetTransaction - Transaction details
DERO.GetTxPool - Pending transactions
DERO.GetLastBlockHeader - Latest block header
DERO.GetSC - Smart contract data

Wallet Methods

GetAddress - Wallet address
GetBalance - Account balance
GetHeight - Wallet sync height
Transfer - Send transactions
MakeIntegratedAddress - Create payment addresses
SplitIntegratedAddress - Parse payment addresses

Gnomon Indexer Methods

Gnomon.GetLastIndexHeight - Indexer status
Gnomon.GetAllOwnersAndSCIDs - All smart contracts
Gnomon.GetSCIDVariableDetails - Contract variables
Gnomon.GetAllSCIDInvokeDetails - Contract interactions

EPOCH Mining Methods

AttemptEPOCH - Submit mining hashes
GetMaxHashesEPOCH - Mining limits
GetSessionEPOCH - Mining session stats

Security Considerations

User Privacy Protection

🔐

Privacy by Design: XSWD ensures that private keys and sensitive wallet data never leave the user's local environment.

// ✅ SECURE: Request only necessary permissions
const applicationData = {
    "id": "block-explorer-v1",
    "name": "DERO Block Explorer",
    "description": "Read-only blockchain explorer", // Clear about permissions
    "url": "http://localhost:8080"
};
 
// ❌ AVOID: Vague or misleading descriptions
const badApplicationData = {
    "id": "app123",
    "name": "App", 
    "description": "Does stuff", // Unclear - users won't trust this
    "url": "http://localhost:8080"
};

Performance Optimization

Connection Management

Performance Best Practices 👨‍💻

Rate Limiting: Never make more than 2-3 XSWD calls per second. I've seen connections drop when apps make 10+ simultaneous calls.

Caching Strategy: Cache GetInfo results for 15-30 seconds. Multiple modules requesting the same data will overwhelm the connection.

Timeout Handling: Different methods need different timeouts - Smart contract calls need 30s, basic calls need 10s.

// Rate limiting for XSWD calls
let lastCallTime = 0;
const MIN_CALL_INTERVAL = 500; // 500ms between calls
 
async function rateLimitedCall(socket, method, params) {
    const now = Date.now();
    const timeSinceLastCall = now - lastCallTime;
    
    if (timeSinceLastCall < MIN_CALL_INTERVAL) {
        await new Promise(resolve => 
            setTimeout(resolve, MIN_CALL_INTERVAL - timeSinceLastCall)
        );
    }
    
    lastCallTime = Date.now();
    return makeXSWDCall(socket, method, params);
}

Error Handling

Robust Error Management

// Comprehensive error handling
async function robustXSWDCall(socket, method, params, retries = 3) {
    for (let attempt = 1; attempt <= retries; attempt++) {
        try {
            return await makeXSWDCall(socket, method, params);
        } catch (error) {
            console.warn(`XSWD call attempt ${attempt} failed:`, error.message);
            
            if (attempt === retries) {
                throw new Error(`${method} failed after ${retries} attempts: ${error.message}`);
            }
            
            // Exponential backoff
            const delay = Math.pow(2, attempt) * 1000;
            await new Promise(resolve => setTimeout(resolve, delay));
        }
    }
}

XSWD is the foundation of TELA application development, providing secure and efficient access to the DERO blockchain through the user's own wallet and node.

XSWD Deep Dive:

Protocol Deep Dive - How XSWD works
TELA Integration - Using XSWD with TELA
Debugging - Troubleshooting XSWD

Build with XSWD:

Templates - XSWD-enabled templates
SDK Guide - Development workflow
API Reference - Complete docs

Understanding TELA:

TELA Overview - Platform architecture
Security Model - Privacy features
Deployment Guide - Publishing your app