This guide documents debugging techniques and patterns discovered during development of the XLN visual debugger, specifically for consensus-related issues.
Use unique prefixes for different subsystems:
🔥 PROCESS-CASCADE - processUntilEmpty execution🗳️ - Voting and proposal operations🔍 - Frame and history analysis🚨 APPLY-ENTITY-TX - Transaction application🔄 - State refresh operationsProblem: Votes submitted by non-proposers weren’t appearing in proposals.
Root Cause: Race condition in entity-consensus.ts where commit notifications cleared mempool before transactions could be forwarded.
Solution: Move transaction forwarding logic to execute BEFORE commit processing:
// WRONG: Forwarding after commit (mempool gets cleared)
if (commitNotification) {
// ... commit processing clears mempool
}
if (!entityReplica.isProposer && entityReplica.mempool.length > 0) {
// ... forwarding (too late!)
}
// CORRECT: Forwarding before commit
if (!entityReplica.isProposer && entityReplica.mempool.length > 0) {
// ... forwarding first
}
if (commitNotification) {
// ... commit processing
}
Problem: Vote choices inconsistent between frontend (true/false) and backend ('yes'/'no').
Solution: Standardize on strings throughout:
// Frontend vote submission
const voteChoice = document.getElementById('vote-choice').value; // 'yes' or 'no'
Problem: Single-signer entities (1 validator, threshold 1) were going through full consensus rounds unnecessarily.
Solution: Direct execution bypass:
if (entityReplica.state.validators.size === 1 && entityReplica.state.threshold === 1n) {
// Direct execution for single signer
for (const tx of entityReplica.mempool) {
entityReplica.state = applyEntityTx(entityReplica.state, tx);
}
entityReplica.mempool = [];
}
submitVote()applyServerInput() processes vote🗳️ Vote form data: {proposalId: 'prop_123', voteChoice: 'yes', comment: 'agree'}
🔥 BOB-TO-ALICE: Bob forwarding 1 txs to proposer alice
🔥 ALICE-RECEIVES: Alice received input with 1 txs
🔥 ALICE-PROPOSES: Alice proposing frame with 1 txs
🚨 APPLY-ENTITY-TX: Processing vote tx for proposal prop_123
Error: Cannot mix BigInt and other types
Solution: Universal conversion utilities
function toNumber(value) {
return typeof value === 'bigint' ? Number(value) : value;
}
function safeStringify(obj) {
return JSON.stringify(obj, (key, value) =>
typeof value === 'bigint' ? value.toString() : value
);
}
Pattern: Global functions not exposed properly Solution: Explicit window assignments
window.submitVote = submitVote;
window.updateThresholdTab = updateThresholdTab;
Pattern: Multiple key formats for replica identification Solution: Robust lookup with fallbacks
// Try multiple key formats
let replica = xlnEnv.replicas.get(`${signerId}:${entityId}`) ||
xlnEnv.replicas.get(`${entityId}:${signerId}`);
// Fallback to property search
if (!replica) {
for (const [key, r] of xlnEnv.replicas) {
if (r.entityId === entityId && r.signerId === signerId) {
replica = r;
break;
}
}
}
// Check replica state
console.log('🔍 Replica state:', replica.state);
console.log('🔍 Mempool:', replica.mempool);
console.log('🔍 Proposals:', replica.state.proposals);
// Trace transaction through system
console.log('📤 TX-OUT:', tx);
console.log('📥 TX-IN:', receivedTx);
console.log('🔄 TX-APPLY:', appliedTx);
// Analyze historical frames
for (let i = 0; i < history.length; i++) {
const snapshot = history[i];
console.log(`🔍 Frame ${i}: entityInputs=${snapshot.entityInputs?.length || 0}`);
}
server.ts and export