jmwallet.utxo_tui
jmwallet.utxo_tui
Shared helpers for the curses-based UTXO TUIs.
Both the freeze manager (jm-wallet freeze) and the interactive UTXO
selector (--select-utxos) render the whole wallet grouped by mixdepth.
This module holds the layout and navigation primitives they share:
- building a display list with
Noneseparators between groups (mixdepths, or mixdepth/branch groups with fidelity bonds shown first), - labelling those separators from the group they introduce (mixdepth title, branch name),
- cursor navigation that skips separators (and other non-selectable rows),
- the address column formatting (full address on every row, middle-ellipsis when too long),
- scroll-offset adjustment to keep the cursor visible,
- the shared minimum-size prompt used while either terminal has no room for the full layout,
- the table layout shared by both TUIs: dynamic columns sized to terminal width and content, cell clipping/formatting, and single-row rendering,
- footer field wrapping/rendering, address-reuse detection (the RU! badge), and the cursor-item description used by both status lines,
- the wallet-label enrichment both feeders run so the
tagcolumn is never empty for regular UTXOs.
Attributes
ADDRESS_COL_WIDTH = 42
module-attribute
EXTERNAL_BRANCH = 0
module-attribute
FIDELITY_BOND_BRANCH = 2
module-attribute
INTERNAL_BRANCH = 1
module-attribute
Classes
Functions:
adjust_scroll(cursor_pos: int, scroll_offset: int, list_height: int, item_count: int) -> int
Return a scroll offset that keeps cursor_pos visible.
The result is clamped to max(0, item_count - list_height) so an
offset reached while the window was shrunken is given up as soon as
more rows fit on screen again (never scroll further than necessary).
Source code in jmwallet/src/jmwallet/utxo_tui.py
237 238 239 240 241 242 243 244 245 246 247 248 | |
align_control_columns(text: str, width: int) -> list[str]
Lay out a controls hint as aligned key/columns in a footer box.
The fields (split on " | ") are arranged in a column grid: each
column is as wide as its longest field, so the | separators line
up vertically across rows -- the controls read as a key table. Fields
flow to fill a row only while the grid fits width; the last row
may carry fewer columns. When everything fits on one line no grid is
needed and the hint renders unwrapped (padded by the footer frame
later). A field wider than width alone falls back to the plain
field wrap (:func:_wrap_footer_fields), which hard-chunks it.
Source code in jmwallet/src/jmwallet/utxo_tui.py
677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 | |
branch_display_rank(branch: int) -> int
Display rank of a branch group; unknown branches sort last.
Source code in jmwallet/src/jmwallet/utxo_tui.py
97 98 99 | |
build_display_items(utxos: list[UTXOInfo], *, branch_groups: bool = False) -> list[UTXOInfo | None]
Insert None separators between display groups.
utxos must already be sorted so that all UTXOs of a group are
contiguous. By default a group spans one mixdepth: a separator is inserted
between consecutive mixdepths. With branch_groups=True the groups are
(mixdepth, branch) pairs — external, internal and fidelity bonds get their
own separators — and the list starts with a leading separator, so every
separator precedes a group and can be labelled from the group's first row.
Additionally each new mixdepth is introduced by a blank border-only row,
encoded as two consecutive None entries (blank row, then the labelled
separator). A None entry renders as a separator line (or, when the
next entry is also None, as the blank row) and is skipped during
navigation.
Source code in jmwallet/src/jmwallet/utxo_tui.py
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 | |
chunk_to_display_width(text: str, width: int) -> list[str]
Split text into chunks of at most width display columns.
Character boundaries are preferred so a wide character is never split in
half: the chunk grows until adding the next character would exceed
width columns.
Source code in jmwallet/src/jmwallet/utxo_tui.py
650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 | |
draw_resize_prompt(stdscr: curses.window, width: int, reason: str = '') -> None
Draw the minimum-size prompt shared by both TUIs.
reason names the dimension the terminal falls short of
("width" / "height") so the user resizes the right one; the
generic message stays the fallback for callers without a diagnosis
(the interrupted-repaint path).
Source code in jmwallet/src/jmwallet/utxo_tui.py
251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 | |
draw_status_block(stdscr: curses.window, row: int, lines: list[str], sep_width: int) -> int
Draw the framed status block; return the number of rows drawn.
Every line is framed left/right with plain border columns and padded to the table's right edge (same geometry as the footer box); the horizontal rules above and below the block are drawn by the caller (the top rule is the existing title separator, the bottom rule is the existing header top edge -- they stay where they are, only their row numbers shift).
Source code in jmwallet/src/jmwallet/utxo_tui.py
890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 | |
enrich_utxo_labels(label_lookup: Callable[[str], str], utxos: list[UTXOInfo]) -> None
Populate missing wallet labels for display in both UTXO TUIs.
utxo_cache items carry no labels, so without this the tag column
stays empty for every regular UTXO. Existing labels (BIP-329
annotations) and fidelity bond rows are preserved -- a bond's tag column
already describes the bond state (fb-a/fb-x via
:func:jmwallet.wallet.rows.short_label).
label_lookup maps an address to its wallet label ("" when none).
Source code in jmwallet/src/jmwallet/utxo_tui.py
354 355 356 357 358 359 360 361 362 363 364 365 366 | |
format_address_column(address: str) -> str
Format an address for the TUI address column.
Every row shows its own address so duplicate addresses stay visible. Long addresses (e.g. fidelity bond P2WSH) are truncated in the middle.
Source code in jmwallet/src/jmwallet/utxo_tui.py
226 227 228 229 230 231 232 233 234 | |
format_utxo_line(utxo: UTXOInfo, max_width: int = 120, excluded_outpoints: set[tuple[str, int]] | None = None, term_width: int = 120, *, allowed_mixdepth: int | None = None, min_confirmations: int = 0, columns: list[tuple[str, int]] | None = None, allow_fidelity_bonds: bool = True, mark_title: str = 'Sel', state_override: StateToken | None = None, reused: bool | None = None) -> str
Format a single UTXO row with separate Label and State columns.
mark_title names the checkbox-style column owned by the row
renderer; it is excluded from the formatted line. state_override
replaces the selector's State computation (the freeze manager renders
its own states: frozn/lock/spend, a subset of the shared catalog).
reused marks the coin's address as shared (the callers know the
wallet-wide address counts); without it only the auto-freeze reuse
label can mark the row.
Source code in jmwallet/src/jmwallet/utxo_tui.py
491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 | |
group_label(utxo: UTXOInfo) -> str
Label of the (mixdepth, branch) group utxo belongs to.
Example: Mixdepth 0 — fidelity bond addresses.
Source code in jmwallet/src/jmwallet/utxo_tui.py
112 113 114 115 116 117 118 119 | |
group_separator_parts(display_items: list[UTXOInfo | None], pos: int) -> tuple[str, str, str, bool] | None
Label parts for the group separator at pos.
Returns (title, em_dash, branch, full_title) — for example
("Mixdepth 0", " — ", "external addresses", True) — or None for a
trailing separator with no following group (renders as plain dashes).
full_title is False when the separator only switches the branch within
the same mixdepth; renderers then strike the title with dashes so a branch
change leaves only the branch name column-flush with the full title above.
Source code in jmwallet/src/jmwallet/utxo_tui.py
138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 | |
maker_bot_status() -> str
Maker process status, or UNKNOWN when procfs is unavailable.
Scans /proc argv for jm-maker (the maker console script and the
systemd unit both run this entry point), so the TUI sees the maker
whether it was started manually, via the legacy TUI menu, or under the
Raspiblitz systemd service. pgrep -f parity without a subprocess:
the exact argv match cannot hit the scanner's own process (whose argv
is a Python TUI command line) or unrelated grep invocations.
Source code in jmwallet/src/jmwallet/utxo_tui.py
314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 | |
seek_selectable(display_items: list[UTXOInfo | None], start: int, direction: int, is_selectable: Callable[[UTXOInfo], bool]) -> int
Return the nearest index from start whose item satisfies is_selectable.
None separators are always skipped. Searches in direction first
and falls back to the opposite direction; returns start when nothing
matches at all.
Source code in jmwallet/src/jmwallet/utxo_tui.py
193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 | |
show_help_overlay(stdscr: curses.window, state_tokens: Sequence[str], title: str) -> None
Keep the help legend scrollable and its controls visible after a resize.
Source code in jmwallet/src/jmwallet/utxo_tui.py
996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 | |
status_header_lines(sep_width: int, wallet_name: str, fingerprint: str, maker_status: str, max_lines: int = 2) -> list[str]
Build the framed status lines shown above the column titles.
Layout follows the legacy whiptail menu_header: values align in
one column (both labels are 15 columns wide), and the fields degrade
in three stages as the terminal narrows:
- one line: name | fingerprint | maker status;
- name + maker status, fingerprint below (aligned under the name);
- name alone, fingerprint + maker status below.
Every stage keeps the name and fingerprint values aligned; stage 4 is
per-value clipping inside stage 2/3 layouts (a value too long even for
its line is clipped to the available columns, never overflowing the
right border). Widths are measured in terminal columns
(:func:_display_width), never character count.
max_lines is the height budget the caller can afford: with 1 only
the single-line form is built (values clipped to fit), so a terminal
narrow enough to force the two-line cascade but too short to pay for
the extra row still renders instead of hitting the resize prompt --
any screen that rendered before the status block keeps rendering
with it.
Source code in jmwallet/src/jmwallet/utxo_tui.py
812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 | |
utxo_branch(utxo: UTXOInfo) -> int
Return the branch component of the UTXO's derivation path.
Branch is the fourth numeric component in paths like m/84'/0'/0'/0/3
(external), .../1/3 (internal) or .../2/{timenumber} (fidelity
bond); a trailing :locktime suffix does not affect it. Returns -1 for
paths without a branch component so malformed paths group together instead
of crashing the spend flow.
Source code in jmwallet/src/jmwallet/utxo_tui.py
84 85 86 87 88 89 90 91 92 93 94 | |
utxo_cursor_description(utxo: UTXOInfo) -> str
One-sentence explanation of a coin for the UTXO Status footer line.
Coin meanings are identical in the selector and the freeze manager.
Source code in jmwallet/src/jmwallet/utxo_tui.py
593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 | |
utxo_display_sort_key(utxo: UTXOInfo) -> tuple[int, int, tuple[int, ...]]
Sort key for the interactive views: mixdepth, then branch in display order (fidelity bonds, external, internal), then derivation index.
Within a branch group the numeric path order of :func:utxo_sort_key is
preserved, so indices >= 10 still sort correctly.
Source code in jmwallet/src/jmwallet/utxo_tui.py
102 103 104 105 106 107 108 109 | |
utxo_sort_key(utxo: UTXOInfo) -> tuple[int, ...]
Numeric derivation-path sort key shared by the freeze manager and the interactive UTXO selector.
Paths look like m/84'/0'/0'/0/3 (receive), .../1/3 (change) or
.../2/{timenumber} (fidelity bond). Comparing these as plain strings
misorders indices >= 10 (.../0/10 sorts before .../0/2), so the
integer path components are compared instead. A fidelity-bond locktime
appended as :locktime adds a trailing tie-breaker and sorts
consistently with the bare .../2/{timenumber} form.
Source code in jmwallet/src/jmwallet/utxo_tui.py
52 53 54 55 56 57 58 59 60 61 62 63 | |
utxo_status_text(utxo: UTXOInfo, extra: list[str] | None = None) -> str
The footer's UTXO Status payload for utxo (shared by both TUIs).
Line 1 is Outpoint: with the full txid:vout; wrap it with
:func:wrap_status_text, which moves the complete value below the
label when the line is too wide instead of breaking mid-value. The
explanation -- the cursor description plus any caller-supplied
restriction fields -- always goes on its own line below, without a
separator at the line break.
Source code in jmwallet/src/jmwallet/utxo_tui.py
732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 | |
wrap_status_text(text: str, width: int) -> list[str]
Wrap a UTXO Status payload, keeping the outpoint value whole.
The Outpoint: label keeps the value on its line only while it fits;
otherwise the complete txid:vout moves to its own line below the
label (no mid-value break). Only a value too wide for the box even on
its own line is hard-chunked. The explanation below (after \n)
wraps like any other footer field via :func:_wrap_footer_fields.
Source code in jmwallet/src/jmwallet/utxo_tui.py
750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 | |