The RPC Console and Debug Window (RPCConsole) is an advanced diagnostic and interaction interface integrated in the Bitcoin Core Qt GUI. Its main purposes include:
RPCConsole is designed to support both wallet-enabled and wallet-disabled builds, defaulting to central widget in the GUI when wallets are disabled.
This page covers the technical details of the RPCConsole class, its associated models, threading for RPC execution, UI structures, data flow, and key functions.
RPCConsole is implemented as a QWidget with a tabbed layout exposing four major functional tabs:
Supporting components and their relationships are as follows:
ClientModel provides node state and network information.WalletModel (if wallet is enabled) ties a specific wallet context for wallet RPC commands.RPCExecutor enables executing RPC commands asynchronously in a dedicated thread to keep UI responsive.Sources: src/qt/rpcconsole.h43-49 src/qt/rpcconsole.cpp437-551 src/qt/bitcoingui.cpp107-128
The initialization of RPCConsole happens during the construction of the main GUI window (BitcoinGUI):
RPCConsole restores its window geometry and UI state using QSettings.WalletFrame will be shown as the GUI central widget; otherwise, the RPCConsole itself becomes the central widget.ClientModel signal is set up to receive node status info.Sources: src/qt/bitcoingui.cpp107-128 src/qt/bitcoingui.cpp628-698 src/qt/rpcconsole.cpp437-551
The console tab is composed of:
| Component | Type | Role |
|---|---|---|
messagesWidget | PlainCopyTextEdit | Displays history and RPC response |
lineEdit | QLineEdit | Input field for new commands |
clearButton | QPushButton | Clears console output |
fontBiggerButton | QPushButton | Increases font size |
fontSmallerButton | QPushButton | Decreases font size |
autoCompleter | QCompleter | Provides command name autocompletion |
The UI supports navigation through command history, resizing font, and clearing output.
Sources: src/qt/forms/debugwindow.ui379-603 src/qt/rpcconsole.cpp525-548
When the user enters a command and presses Return:
UniValue.Sources: src/qt/rpcconsole.cpp381-435 src/qt/rpcconsole.cpp141-379 src/qt/rpcconsole.cpp88-102
RPCParseCommandLine implements a shell-like recursive parser:
getblockhash 0getblockhash(0)getblock(getblockhash(0) 1)getblock(...)[tx][0]Sensitive commands (handling private keys or wallet passphrase) are filtered out from the history buffer to protect user info.
Filtered commands include:
| Command |
|---|
createwallet |
createwalletdescriptor |
migratewallet |
signmessagewithprivkey |
signrawtransactionwithkey |
walletpassphrase |
walletpassphrasechange |
encryptwallet |
Sources: src/qt/rpcconsole.cpp74-83 src/qt/rpcconsole.cpp141-379
This tab displays real-time node state and network info fetched via the ClientModel, which in turn reads this data from the interfaces::Node.
The tab is divided into three sections: General, Network, and Blockchain.
Sources: src/qt/forms/debugwindow.ui41-385 src/qt/clientmodel.cpp84-96 src/qt/clientmodel.cpp133-162 src/qt/rpcconsole.cpp618-647
The Peers tab offers detailed insight into all peer connections and interactive management features.
Sources: src/qt/rpcconsole.cpp646-716 src/qt/rpcconsole.h153-161 src/qt/forms/debugwindow.ui604-918
Typical displayed information includes:
| Field | Source | Description |
|---|---|---|
| Direction | CNodeStats.fInbound | Inbound or outbound connection |
| Transport | CNodeStats.m_transport_type | Version 1 or 2, or detecting |
| Connection Type | CNodeStats.m_conn_type | Full relay, block relay, feeler, manual, or addr fetch |
| Network | CNodeStats.addr.GetNetwork() | IPv4, IPv6, Onion, I2P, CJDNS |
| Version | CNodeStats.nVersion | Protocol version |
| User Agent | CNodeStats.cleanSubVer | Client identification user agent |
| Services | CNodeStats.nServices | Services advertised |
| Ping Time | CNodeStats.m_last_ping_time | Latest ping round-trip time |
| Time Offset | CNodeStateStats.time_offset | Time offset compared with local |
| Bytes Sent | CNodeStats.nSendBytes | Total bytes sent |
| Bytes Received | CNodeStats.nRecvBytes | Total bytes received |
Sources: src/qt/rpcconsole.cpp1041-1262 src/qt/forms/debugwindow.ui695-918
User actions for peer and ban management operate as follows:
Sources: src/qt/rpcconsole.cpp947-1003 src/qt/rpcconsole.cpp864-913
The Traffic Graph tab displays network I/O updated in quasi-real-time.
paintEvent to draw network bytes history line graph.| Time Range (minutes) | Number of Samples Displayed |
|---|---|
| 2 | 480 |
| 10 | 2400 |
| 30 | 7200 |
| 60 | 14400 |
| 120 | 28800 |
| 360 | 86400 |
| 720 | 172800 |
| 1440 | 345600 |
Sources: src/qt/rpcconsole.cpp718-731 src/qt/forms/debugwindow.ui919-1032 src/qt/rpcconsole.cpp542
When multiple wallets are loaded, the console supports switching context to issue RPC commands to a selected wallet.
RPCConsole::addWallet(walletModel) and removed by removeWallet.RPCExecutor./wallet/<walletname>.Wallet Addition/Removal Sequence:
addWallet() → adds wallet to WalletFrame and console selector.RPCConsole::addWallet() updates the dropdown.setCurrentWallet().Sources: src/qt/rpcconsole.cpp1300-1330 src/qt/bitcoingui.cpp739-789 src/qt/rpcconsole.cpp300-303
| Shortcut(s) | Description | Scope |
|---|---|---|
Ctrl+Shift+C | Show console tab | Global (GUI) |
Ctrl+Shift+D | Show debug window | Global (GUI) |
Ctrl++ or Ctrl+= | Increase console font size | Console tab |
Ctrl+- or Ctrl+_ | Decrease console font size | Console tab |
Up Arrow | Browse history backward | Console line edit |
Down Arrow | Browse history forward | Console line edit |
PageUp / PageDown | Scroll console output | Console messages widget |
Ctrl+W | Close window | Debug window |
Sources: src/qt/bitcoingui.cpp494-496 src/qt/rpcconsole.cpp514-523 src/qt/rpcconsole.cpp574-614
The console recognizes a help-console command that presents usage information about supported shell command syntaxes, including parenthesized and nested calls.
Example help output:
help-console
This console accepts RPC commands using the standard syntax.
example: getblockhash 0
This console can also accept RPC commands using the parenthesized syntax.
example: getblockhash(0)
Commands may be nested when specified with the parenthesized syntax.
example: getblock(getblockhash(0) 1)
A space or a comma can be used to delimit arguments for either syntax.
example: getblockhash 0
getblockhash,0
Named results can be queried with a non-quoted key string in brackets.
example: getblock(getblockhash(0) 1)[tx]
Results without keys can be queried with an integer in brackets.
example: getblock(getblockhash(0),1)[tx][0]
Sources: src/qt/rpcconsole.cpp389-408
The Debug Window integrates with the main GUI Window menu to allow switching directly to any tab:
setTabFocus method triggers switching tabs and brings the debug window to front.RPCConsole::TabTypes: INFO, CONSOLE, GRAPH, PEERS.Sources: src/qt/bitcoingui.cpp575-583 src/qt/rpcconsole.h71-82 src/qt/rpcconsole.cpp861-862
The Information tab includes a button to open the node's debug log (debug.log) in the system's default text editor:
GUIUtil::openDebugLogfile().Sources: src/qt/rpcconsole.cpp789-790 src/qt/guiutil.cpp429-436 src/qt/forms/debugwindow.ui365-378
The RPC console performs RPC command processing on a separate thread to avoid blocking the UI thread:
RPCExecutor runs in QThread created inside RPCConsole.Qt::QueuedConnection.m_is_executing flag prevents concurrent command submission.lineEdit is temporarily disabled during execution to avoid queueing inputs.Sources: src/qt/rpcconsole.cpp750-766 src/qt/rpcconsole.cpp88-102 src/qt/rpcconsole.cpp381-435
Various UI settings for the debug window are saved and restored using QSettings:
| Setting Key | Purpose |
|---|---|
RPCConsoleWindowGeometry | Window size and position (wallet enabled) |
RPCConsoleWidgetPeersTabSplitterSizes | Splitter state for peers tab (wallet disabled) |
RPCConsoleWindowPeersTabSplitterSizes | Splitter state for peers tab (wallet enabled) |
PeersTabPeerHeaderState | Peer table column widths and order |
PeersTabBanlistHeaderState | Ban list table column widths and order |
consoleFontSize | Consoles' font size in points |
Settings lifecycle:
Sources: src/qt/rpcconsole.cpp444-461 src/qt/rpcconsole.cpp553-572
RPCConsole supports rich text formatting for messages categorized by type with clear visual distinctions:
Sources: src/qt/rpcconsole.cpp60-69 src/qt/rpcconsole.cpp57-58 src/qt/rpcconsole.cpp1359-1436
This completes the detailed technical documentation of the RPC Console and Debug Window implementation within Bitcoin Core's Qt GUI.
Sources:
Refresh this wiki