Output Descriptors¶

Output descriptors are a powerful way to describe Bitcoin addresses and scripts. This page provides a deep dive into descriptor syntax and usage in Vigil.

What Are Descriptors?¶

Output descriptors are strings that describe how to derive a set of Bitcoin addresses. They encode:

The script type (P2PKH, P2SH, P2WPKH, P2WSH, P2TR)
The public key(s) involved
The derivation path(s)
Any script conditions (multisig, timelocks, etc.)

Basic Syntax¶

script_type([fingerprint/path]xpub/child_derivation)

Example:

wpkh([d34db33f/84'/0'/0']xpub6DJ2...9Nvt/0/*)

Breaking it down:

Part	Meaning
`wpkh`	Script type (witness public key hash = P2WPKH)
`d34db33f`	Master key fingerprint
`84'/0'/0'`	BIP-84 derivation path
`xpub6DJ2...9Nvt`	Extended public key
`/0/*`	Derive external addresses at any index

Script Types¶

Single-Signature¶

Descriptor	Script Type	Address Format
`pk(KEY)`	P2PK	N/A (raw pubkey)
`pkh(KEY)`	P2PKH	`1...`
`wpkh(KEY)`	P2WPKH	`bc1q...`
`sh(wpkh(KEY))`	P2SH-P2WPKH	`3...`
`tr(KEY)`	P2TR	`bc1p...`

Multi-Signature¶

Descriptor	Description
`multi(k,KEY1,KEY2,...)`	k-of-n bare multisig
`sortedmulti(k,KEY1,KEY2,...)`	k-of-n multisig (sorted keys)
`wsh(multi(...))`	Native SegWit multisig
`sh(wsh(multi(...)))`	Nested SegWit multisig

Common Descriptor Examples¶

Standard Single-Sig Wallets¶

# BIP-44 Legacy (P2PKH)
pkh([fingerprint/44'/0'/0']xpub.../0/*)

# BIP-49 Nested SegWit (P2SH-P2WPKH)
sh(wpkh([fingerprint/49'/0'/0']xpub.../0/*))

# BIP-84 Native SegWit (P2WPKH) - Most common
wpkh([fingerprint/84'/0'/0']xpub.../0/*)

# BIP-86 Taproot (P2TR)
tr([fingerprint/86'/0'/0']xpub.../0/*)

Multisig Wallets¶

# 2-of-3 Native SegWit Multisig
wsh(sortedmulti(2,
  [fp1/48'/0'/0'/2']xpub1.../0/*,
  [fp2/48'/0'/0'/2']xpub2.../0/*,
  [fp3/48'/0'/0'/2']xpub3.../0/*
))

# 3-of-5 Multisig
wsh(sortedmulti(3,
  [fp1]xpub1.../0/*,
  [fp2]xpub2.../0/*,
  [fp3]xpub3.../0/*,
  [fp4]xpub4.../0/*,
  [fp5]xpub5.../0/*
))

Derivation Wildcards¶

Pattern	Meaning
`/0/*`	External chain, any index
`/1/*`	Internal chain (change), any index
`/*`	Any index (no chain distinction)
`/0`	Specific index 0

Checksums¶

Descriptors can include a checksum for validation:

wpkh([d34db33f/84'/0'/0']xpub6DJ2...9Nvt/0/*)#checksum

Vigil will:

Validate the checksum if present
Calculate and display the checksum for reference
Accept descriptors with or without checksums

Miniscript Support¶

Vigil supports miniscript descriptors for advanced spending conditions.

Example: Timelock with Fallback¶

wsh(or_d(
  pk(KEY1),
  and_v(v:pkh(KEY2),older(52560))
))

This creates an output spendable by:

KEY1 immediately, OR
KEY2 after 52560 blocks (~1 year)

Advanced Feature

Miniscript support is primarily for monitoring. Theft Shield may have limited support for complex scripts.

Using Descriptors in Vigil¶

Adding a Descriptor Wallet¶

Go to Wallets → Add Wallet
Select Descriptor
Paste your descriptor
Vigil will:
- Parse and validate the descriptor
- Detect the network
- Derive addresses
Click Create Wallet

Validation Errors¶

Error	Cause	Solution
Invalid checksum	Checksum mismatch	Remove checksum or fix it
Unknown script type	Unsupported descriptor	Simplify or contact support
Invalid xpub	Malformed key data	Verify the xpub is complete
Path parse error	Invalid derivation path	Check path syntax

Getting Your Descriptor¶

From Hardware Wallets¶

Most modern hardware wallets can export descriptors:

ColdcardTrezorLedger

Advanced → Export Wallet → Descriptor

Account → Show Address Path → Copy Descriptor

Export via Sparrow or Electrum

From Software Wallets¶

SparrowBitcoin CoreElectrum

Settings → Script Policy → Descriptor → Edit (copy and paste the full descriptor)

listdescriptors or getdescriptorinfo

Wallet → Information → Output Descriptors

Next: Extended Public Keys →