Diary of a Node Operator: Redesigning the tBTC Setup Experience

The client code is the heartbeat of the Threshold Network, enabling DevOps engineers and independent operators to run tBTC nodes. But setting up a node is a high-stakes, technically demanding process. While the core team had mapped out the user journey, those maps were built entirely on stakeholder assumptions. No one knew what the actual, unpolished operator experience looked like in the wild.

To bridge the gap between assumption and reality, I designed a mixed-methods study to track how users truly interacted with the client code across a multi-day configuration process.

"From all the nodes that I've set up, tBTC is in the top 3 most difficult nodes. My top 3 is: 1. Ethereum 2.0, 2. PRE, 3. tBTC & Random Beacon."

We needed to see the setup process through the eyes of the operators as it happened, not just hear about it after the fact.

The Methodology

I launched a 6-day longitudinal diary study. Using GitHub Gists, participants logged their real-time progress, commands, and frustrations using "Write-Along" and "Snippet" tracking techniques. When this part was finished, I followed up with 60-minute deep-dive interviews to unpack their diary entries.

The Participants

5 highly technical users. These were not beginners; they had extensive Linux, server configuration, and prior protocol node setup experience. All of them were already running PRE nodes on mainnet. The actual configuration work took them 2.6 hours on average, spread across the study's 4 working days.

The Benchmark

To quantify the qualitative chaos, I administered a Post-Setup System Usability Scale (SUS) survey via Typeform. The score landed at 73.125/100. While technically "above average" (68), the diary entries painted a much more vulnerable picture: the system was functional, but the risk of user error was alarmingly high.

The diary logs and interviews revealed that real-world operator behavior was drastically different from what the team had anticipated.

The Trust Gap: "I Would Not Run This on Mainnet"

The most severe finding: 4 out of 5 participants stated they would not run a node on mainnet yet. Not because the setup failed, but because the documentation offered no monitoring tooling or metrics, and none of them knew what a successful, healthy node actually looked like. For operators staking real funds, that opacity translated directly into a risk of loss they were not willing to take.

The Hardware Downgrade Risk

The Assumption: We expected operators to follow the high-resource server recommendations.

The Reality: Because the initial CPU and RAM usage idled below 5%, participants immediately concluded the system was over-specced and planned to downgrade their hardware. This exposed a critical blind spot: downgrading would put them at risk of catastrophic network slashing once modular features scaled up and load increased.

"Beside the first 16 hours or so, with a CPU usage of around 75%, the rest of the time the peak CPU usage has been of 5%, and the max RAM used the whole time has not reached even 30%. That would mean that with these same conditions a node with 1vCPU and 1GB RAM would also meet the needs. I think adjusting the requirements is important."

The False Sensation of Success

The client was designed to display a stylized ASCII art banner when the Docker container successfully launched. Users saw this visual cue, assumed their setup was flawless, and walked away. In reality, that banner masked severe downstream connectivity warnings, leaving broken nodes unattended. All participants reported frustration and confusion at this stage; some said the system made them "feel stupid" because they could not verify their own success.

"After following the logs a few more minutes it is still unclear if the node is running correctly or not. Even though it's not stopping I assume it's still not running correctly. I don't know how to test if the node runs correctly or not and have no idea what to do next."

The Address Overwhelm

The staking dashboard offered a 3-address setup (Provider, Authorizer, Beneficiary) to give enterprise users maximum flexibility. Instead, it caused severe cognitive overload. To bypass the friction, almost all users simply copied the exact same wallet address into all three fields, completely neutralizing the intended security architecture.

"I had some issues with the three addresses. I did not know why they were all displayed if they were pre-filled anyway. I still do not understand very well what's the relationship with them. I wish I'd have some tooltips in the Stake Details about them."

Cryptic Client Logging

System logs routinely mislabeled severe bootstrap warnings as harmless "INFO" messages. When errors did occur, the logs failed to communicate whether the failure was local (the user's fault) or global (network-wide), completely stalling the troubleshooting process.

"The warning messages were really cryptic, technical and hard to understand. Maybe the team understands what's happening but I for one had no clue where the problem was. Was it on my end or their end?"

What Held Up Under Pressure

Not everything broke. The documentation itself performed well: most participants completed the setup without hunting for external guides, and the bundled Docker script drew genuine enthusiasm. The gaps were specific, missing Monitoring and Troubleshooting sections, not systemic.

"The documentation was really good and straightforward. Far better than the official one for PRE. When I actually set up my PRE node I used an unofficial guide that was so well written and so easy to follow that I did not even bother to read the official one any more."

This research acted as a wake-up call, proving that an "above average" SUS score isn't enough to prevent catastrophic user errors in Web3 infrastructure. I synthesized these insights into an "Information Radiator" blueprint, giving the core team an exact roadmap for what to fix before the mainnet launch.

Strategic Recommendations Delivered

• Product Architecture: Split the staking UI into a "Default" mode for standard operators and an "Expert" mode, shielding standard users from the 3-address cognitive overload while retaining advanced parameters for enterprise teams.
• Documentation Strategy: Add dedicated "Monitoring & Troubleshooting" sections built directly from the participants' requested checklist (peer count alerts, bootstrap connectivity, ETH balance triggers, node health endpoints, a plug-and-play Grafana dashboard), and explain explicitly why the high machine requirements exist, to defuse the downgrade-and-get-slashed scenario.
• Developer Experience (DX): Re-engineer the client logging hierarchy with correct severity grades and verbose error messaging that differentiates between user-level and network-level failures, and gate the "success" banner on actual network connectivity.

The team committed to all three tracks, documentation, node messaging, and UI, as the direct next steps out of this study, folding the monitoring checklist into the official node docs ahead of the mainnet push.

Retrospective

With five expert participants, this study traded breadth for depth: it captured rich, honest longitudinal data but could not quantify how often each failure occurs across the wider operator base. The self-hosting finding in particular (this cohort defaulted to self-hosted machines despite recommendations against it) deserved a follow-up survey with a larger operator sample.