XSWD Protocol Overview

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

const applicationData = {
    "id": string,          // REQUIRED: 64-character hex string (any valid hex)
    "name": string,        // REQUIRED: 1-255 characters, ASCII only
    "description": string, // REQUIRED: 1-255 characters, ASCII only
    "url": string,         // REQUIRED: Must match Origin header, start with http:// or https://
    "permissions": object, // OPTIONAL: Pre-set permissions (requires signature)
    "signature": string    // OPTIONAL: DERO signed message (required for pre-set permissions)
};

// App ID validation (lines 420-431):
id := strings.TrimSpace(app.Id)
if len(id) != 64 {
    response = "Invalid ID size"
}
if _, err := hex.DecodeString(id); err != nil {
    response = "Invalid hexadecimal ID"
}
 
// Result: Any 64-char hex string is valid
// No derivation from app name, no uniqueness check

const appId = Array.from({length: 64}, () => 
    Math.floor(Math.random() * 16).toString(16)
).join('');
localStorage.setItem('xswd_app_id', appId);

async function generateAppId(appName) {
    const encoder = new TextEncoder();
    const data = encoder.encode(appName);
    const hashBuffer = await crypto.subtle.digest('SHA-256', data);
    const hashArray = Array.from(new Uint8Array(hashBuffer));
    return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
}
 
const appId = await generateAppId('My TELA Application v1.0');

const appId = "71605a32e3b0c44298fc1c549afbf4c8496fb92427ae41e4649b934ca495991b";

// Get or create App ID (stored for permission continuity)
function getOrCreateAppId() {
    let appId = localStorage.getItem('xswd_app_id');
    if (!appId) {
        appId = Array.from({length: 64}, () => 
            Math.floor(Math.random() * 16).toString(16)
        ).join('');
        localStorage.setItem('xswd_app_id', appId);
    }
    return appId;
}
 
// Basic XSWD connection
function connectToXSWD() {
    const applicationData = {
        "id": getOrCreateAppId(),  // 64-char hex string
        "name": "My TELA Application",  // ASCII only, max 255 chars
        "description": "Read-only blockchain explorer - no wallet access required",  // ASCII only
        "url": window.location.origin  // Must match Origin header
    };
    
    const socket = new WebSocket("ws://localhost: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 !== undefined) {
            if (response.accepted) {
                console.log("XSWD connection accepted:", response.message);
                // Connection established - can now make API calls
            } else {
                console.error("XSWD connection rejected:", response.message);
                // Common rejection reasons:
                // - "Invalid ID size" (not 64 chars)
                // - "Invalid hexadecimal ID"
                // - "Invalid name" (empty, >255 chars, or non-ASCII)
                // - "Invalid description" (empty, >255 chars, or non-ASCII)
                // - "Invalid URL compared to origin"
            }
        } 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;
}

// 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 });

// These NEVER require user permission - wallet proxies to daemon
await xswd.call('DERO.GetInfo');      // Always works
await xswd.call('DERO.GetBlock', { height: 100 });  // Always works
await xswd.call('DERO.GetSC', { scid: '...' });     // Always works
 
// These ALWAYS prompt the user (in forceAsk mode)
await xswd.call('GetAddress');   // User must approve
await xswd.call('GetBalance');   // User must approve
await xswd.call('Transfer', {}); // User must approve

const applicationData = {
    "id": "a1b2c3d4...",  // 64-char hex
    "name": "My App",
    "description": "Needs balance access",
    "url": "https://myapp.com",
    "permissions": {
        "GetBalance": 3,   // AlwaysAllow (3)
        "GetAddress": 3,   // AlwaysAllow (3)
        "Transfer": 4      // AlwaysDeny (4) - explicitly deny
    },
    "signature": "-----BEGIN DERO SIGNED MESSAGE-----\n..."  // Required!
};

// Built-in rate limiter
class RateLimiter {
    constructor(rps = 10) {
        this.tokens = rps;
        this.maxTokens = rps * 2;  // Burst capacity
        this.lastRefill = Date.now();
        this.refillRate = 1000 / rps;  // ms per token
    }
    
    async acquire() {
        const now = Date.now();
        const elapsed = now - this.lastRefill;
        this.tokens = Math.min(this.maxTokens, this.tokens + elapsed / this.refillRate);
        this.lastRefill = now;
        
        if (this.tokens < 1) {
            const waitTime = (1 - this.tokens) * this.refillRate;
            await new Promise(r => setTimeout(r, waitTime));
            this.tokens = 0;
        } else {
            this.tokens -= 1;
        }
    }
}
 
const limiter = new RateLimiter(10);
 
async function rateLimitedCall(method, params) {
    await limiter.acquire();
    return xswd.call(method, params);
}

// Generate proper App ID
const appId = await generateAppId('DERO Block Explorer v1.0');
 
// GOOD: Clear, honest description - ASCII only!
const applicationData = {
    "id": appId,  // Any valid 64-char hex string
    "name": "DERO Block Explorer",
    "description": "Read-only blockchain explorer - no wallet access required",
    "url": "https://explorer.example.com"
};
 
// BAD: Invalid ID format
const badApp1 = {
    "id": "block-explorer-v1",  // ERROR: Not 64 hex chars!
    "name": "Explorer",
    "description": "Explores blocks",
    "url": "https://example.com"
};
 
// BAD: Unicode characters (will be rejected!)
const badApp2 = {
    "id": appId,
    "name": "DERO Explorer",  // OK
    "description": "View blocks and transactions",  // ERROR: Smart quote!
    "url": "https://example.com"
};
 
// BAD: Vague description
const badApp3 = {
    "id": appId,
    "name": "App",
    "description": "Does stuff",  // Users won't trust this
    "url": "https://example.com"
};

// The URL must match where your app is actually hosted
const applicationData = {
    "id": appId,
    "name": "My App",
    "description": "My application",
    "url": window.location.origin  // Use actual origin, not hardcoded
};
 
// If URL doesn't match Origin header, connection is rejected with:
// "Invalid URL compared to origin"

// 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);
}

// 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));
        }
    }
}