Stacks Transaction Composer - Electrum Plugin

An Electrum wallet plugin for composing Stacks blockchain transactions via Bitcoin OP_RETURN encoding, as defined in SIP-001 and SIP-007.

Features

Transaction Composer

Compose Stacks transactions via Bitcoin OP_RETURN outputs:

• Leader VRF Key Registration: Register a VRF proving key for Stacks mining
• Leader Block Commit: Commit Stacks blocks to the burnchain
• User Burn Support: Support miners by contributing burns to their block commitments
• Pre-STX Authorization: Authorize addresses for STX operations
• Stack STX: Lock STX tokens for Proof-of-Transfer participation
• Transfer STX: Transfer STX via Bitcoin transactions
• Delegate STX: Delegate STX to stacking pool operators

All transaction types include:

• Proper OP_RETURN encoding with Stacks magic bytes
• Network selection (Mainnet/Testnet)
• Coin control for UTXO selection (required for two-transaction flows)
• Preview of encoded data before broadcasting
• Real-time STX address and balance display for the sender

STX Address Integration

The plugin extends Electrum's interface with STX address support:

• STX Address Column: Adds an "STX Address" column to the address list showing the corresponding STX address for each Bitcoin address
• Extended Address Dialog: Right-click any address to see its STX address and live STX balance
• Address Context Menu: Right-click options include:
  • Copy STX Address to clipboard
  • View on Stacks block explorer (Hiro)
  • Compose Stacks transaction with preselected address

Address Conversion

Converts Bitcoin addresses to their corresponding STX addresses:

• Legacy P2PKH (addresses starting with 1 or m/n)
• P2SH (addresses starting with 3 or 2)
• Native SegWit P2WPKH (addresses starting with bc1q or tb1q)

Note: P2WSH and Taproot (P2TR) addresses are not supported as they use different hash constructions.

STX Balance Lookup

• Fetches live STX balances from the Stacks API
• Displays balance in address dialogs and transaction composer
• Supports both mainnet and testnet

Preferences

Configure plugin settings via Tools > Stacks preferences:

• Network Selection: Choose between Stacks Mainnet and Testnet
• Custom Node URL: Configure a custom Stacks API endpoint (defaults to Hiro API)

Installation

Electrum requires plugins to be installed as ZIP files. Use the included build script:

./dev-refresh.sh

This script:

1. Packages the plugin into the correct ZIP format
2. Installs it to ~/.electrum/plugins/stacks.zip
3. Excludes test files from the package

After running the script:

1. Restart Electrum
2. Enable the plugin: Tools > Plugins > Stacks Transaction Composer

Manual Installation

If you prefer to install manually:

1. Create a ZIP file named stacks.zip containing a stacks/ folder with:

   • All .py files (except test files)
   • manifest.json
   • stacks.svg

2. Copy stacks.zip to your Electrum plugins directory:

   • Linux/macOS: ~/.electrum/plugins/
   • Windows: %APPDATA%\Electrum\plugins\

3. Restart Electrum and enable the plugin

Usage

Accessing the Plugin

After enabling the plugin:

• Tools > Stacks preferences - Configure network and API settings
• Right-click any address in the Addresses tab to access STX features:
  • Copy STX Address
  • View on Stacks block explorer
  • Compose Stacks transaction
• Click any address to view the extended address dialog with STX address and balance
• The STX Address column appears automatically in the Addresses tab

Two-Transaction Flows

Several Stacks operations require two Bitcoin transactions with specific UTXO linkage:

VRF Registration -> Block Commit Flow

1. Create VRF Key Registration:

   • Select "Leader VRF Key Registration"
   • Enter your consensus hash and VRF public key
   • Use coin control to select the UTXO from your mining address
   • Create and broadcast the transaction

2. Wait for confirmation (typically 1+ confirmations required)

3. Create Block Commit:

   • Select "Leader Block Commit"
   • Fill in block hash, VRF seed, and reference data
   • Important: Use coin control to select a UTXO from the same address used in step 1
   • Set your burn amount
   • Create and broadcast

Pre-STX -> STX Operation Flow

1. Create Pre-STX Authorization:

   • Select "Pre-STX Authorization"
   • Use coin control to select the UTXO from the address you want to authorize
   • Create and broadcast

2. Wait for confirmation

3. Create STX Operation (Stack/Transfer/Delegate):

   • Select your desired STX operation
   • Important: Use coin control to select a UTXO from the Pre-STX transaction
   • Fill in the required parameters
   • Create and broadcast

Note on Transfer/Delegate STX recipients: The Stacks blockchain only accepts legacy Bitcoin addresses (P2PKH starting with 1 or P2SH starting with 3) for the recipient/delegate output. SegWit addresses (bc1...) are not supported per SIP-007. The plugin validates this and shows real-time feedback.

Wire Format Reference

All transactions use the following structure:

Bytes	Field	Description
0-1	Magic	Network identifier (X2 for mainnet, T2 for testnet)
2	Opcode	Operation type identifier
3+	Data	Operation-specific payload

Opcodes

Operation	Opcode	ASCII
Leader Block Commit	0x5B	[
Leader Key Register	0x5E	^
User Burn Support	0x5F	_
Pre-STX	0x70	p
Stack STX	0x78	x
Transfer STX	0x24	$
Delegate STX	0x23	#

Files

• manifest.json - Plugin metadata
• __init__.py - Package initialization
• qt.py - Main plugin class with hooks and context menu integration
• composer_dialog.py - Transaction composer dialog UI
• stacks_address_dialog.py - Extended address dialog with STX info
• stacks_address_list.py - Address list patches for STX column
• stacks_preferences.py - Preferences dialog and config helpers
• stacks_wire.py - Wire format encoding and address conversion library
• test_stacks_wire.py - Unit tests for wire format encoding

Requirements

• Electrum 4.0+
• PyQt6

References

• SIP-001: Burn Election
• SIP-007: Stacking Consensus
• Stacks Documentation
• Electrum Plugin Development

License

MIT License