Home › Topics › Encoding › BIP 381

BIP 381: Non-Segwit Output Script Descriptors

Also known as: BIP381, BIP-0381.

In plain English: Defines the descriptor functions for Bitcoin's older address types: pay-to-public-key, pay-to-public-key-hash (classic addresses starting with '1'), and pay-to-script-hash (addresses starting with '3'). This lets descriptor-based wallets describe and recover coins held in these legacy formats.

Status
Deployed
Type
Specification
Layer
Applications
Authors
Pieter Wuille, Ava Chow
Assigned
Last changed
Requires
BIP 380
Topics
Encoding
Source
bip-0381.mediawiki on GitHub · Markdown

Full specification

Abstract

This document specifies pk(), pkh(), and sh() output script descriptors. pk() descriptors take a key and produces a P2PK output script. pkh() descriptors take a key and produces a P2PKH output script. sh() descriptors take a script and produces a P2SH output script.

This BIP is licensed under the BSD 2-clause license.

Motivation

Prior to the activation of Segregated Witness, there were 3 main standard output script formats: P2PK, P2PKH, and P2SH. These expressions allow specifying those formats as a descriptor.

Specification

Three new script expressions are defined: pk(), pkh(), and sh().

pk()

The pk(KEY) expression can be used in any context or level of a descriptor. It takes a single key expression as an argument and produces a P2PK output script. Depending on the higher level descriptors, there may be restrictions on the type of public keys that can be included. Such restrictions will be specified by those descriptors.

The output script produced is:

<KEY> OP_CHECKSIG

pkh()

The pkh(KEY) expression can be used as a top level expression, or inside of either a sh() or wsh() descriptor. It takes a single key expression as an argument and produces a P2PKH output script. Depending on the higher level descriptors, there may be restrictions on the type of public keys that can be included. Such restrictions will be specified by those descriptors.

The output script produced is:

OP_DUP OP_HASH160 <KEY_hash160> OP_EQUALVERIFY OP_CHECKSIG

sh()

The sh(SCRIPT) expression can only be used as a top level expression. It takes a single script expression as an argument and produces a P2SH output script. sh() expressions also create a redeemScript which is required in order to spend outputs which use its output script. This redeemScript is the output script produced by the SCRIPT argument to sh().

The output script produced is:

OP_HASH160 <SCRIPT_hash160> OP_EQUAL

Test Vectors

Valid descriptors followed by the scripts they produce. Descriptors involving derived child keys will have the 0th, 1st, and 2nd scripts listed.

  • pk(L4rK1yDtCWekvXuE6oXD9jCYfFNV2cWRpVuPLBcCU2z8TrisoyY1)
    • 2103a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bdac
  • pk(03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd)
    • 2103a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bdac
  • pkh([deadbeef/1/2'/3/4']L4rK1yDtCWekvXuE6oXD9jCYfFNV2cWRpVuPLBcCU2z8TrisoyY1)
    • 76a9149a1c78a507689f6f54b847ad1cef1e614ee23f1e88ac
  • pkh([deadbeef/1/2'/3/4']03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd)
    • 76a9149a1c78a507689f6f54b847ad1cef1e614ee23f1e88ac
  • pkh([deadbeef/1/2h/3/4h]03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd)
    • 76a9149a1c78a507689f6f54b847ad1cef1e614ee23f1e88ac
  • pk(5KYZdUEo39z3FPrtuX2QbbwGnNP5zTd7yyr2SC1j299sBCnWjss)
    • 4104a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd5b8dec5235a0fa8722476c7709c02559e3aa73aa03918ba2d492eea75abea235ac
  • pk(04a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd5b8dec5235a0fa8722476c7709c02559e3aa73aa03918ba2d492eea75abea235)
    • 4104a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd5b8dec5235a0fa8722476c7709c02559e3aa73aa03918ba2d492eea75abea235ac
  • pkh(5KYZdUEo39z3FPrtuX2QbbwGnNP5zTd7yyr2SC1j299sBCnWjss)
    • 76a914b5bd079c4d57cc7fc28ecf8213a6b791625b818388ac
  • pkh(04a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd5b8dec5235a0fa8722476c7709c02559e3aa73aa03918ba2d492eea75abea235)
    • 76a914b5bd079c4d57cc7fc28ecf8213a6b791625b818388ac
  • sh(pk(L4rK1yDtCWekvXuE6oXD9jCYfFNV2cWRpVuPLBcCU2z8TrisoyY1))
    • a9141857af51a5e516552b3086430fd8ce55f7c1a52487
  • sh(pk(03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd))
    • a9141857af51a5e516552b3086430fd8ce55f7c1a52487
  • sh(pkh(L4rK1yDtCWekvXuE6oXD9jCYfFNV2cWRpVuPLBcCU2z8TrisoyY1))
    • a9141a31ad23bf49c247dd531a623c2ef57da3c400c587
  • sh(pkh(03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd))
    • a9141a31ad23bf49c247dd531a623c2ef57da3c400c587
  • pkh(xprv9s21ZrQH143K31xYSDQpPDxsXRTUcvj2iNHm5NUtrGiGG5e2DtALGdso3pGz6ssrdK4PFmM8NSpSBHNqPqm55Qn3LqFtT2emdEXVYsCzC2U/2147483647'/0)
    • 76a914ebdc90806a9c4356c1c88e42216611e1cb4c1c1788ac
  • pkh([bd16bee5/2147483647h]xpub69H7F5dQzmVd3vPuLKtcXJziMEQByuDidnX3YdwgtNsecY5HRGtAAQC5mXTt4dsv9RzyjgDjAQs9VGVV6ydYCHnprc9vvaA5YtqWyL6hyds/0)
    • 76a914ebdc90806a9c4356c1c88e42216611e1cb4c1c1788ac
  • pk(xprv9uPDJpEQgRQfDcW7BkF7eTya6RPxXeJCqCJGHuCJ4GiRVLzkTXBAJMu2qaMWPrS7AANYqdq6vcBcBUdJCVVFceUvJFjaPdGZ2y9WACViL4L/0)
    • 210379e45b3cf75f9c5f9befd8e9506fb962f6a9d185ac87001ec44a8d3df8d4a9e3ac
  • pk(xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y/0)
    • 210379e45b3cf75f9c5f9befd8e9506fb962f6a9d185ac87001ec44a8d3df8d4a9e3ac

Invalid descriptors

  • pk() only accepts key expressions: pk(pk(03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd))
  • pkh() only accepts key expressions: pkh(pk(03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd))
  • sh() only accepts script expressions: sh(03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd)
  • sh() is top level only: sh(sh(pkh(03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd)))

Backwards Compatibility

pk(), pkh(), and sh() descriptors use the format and general operation specified in 380. As these are wholly new descriptors, they are not compatible with any implementation. However the scripts produced are standard scripts so existing software are likely to be familiar with them.

Reference Implementation

pk(), pkh(), and sh() descriptors have been implemented in Bitcoin Core since version 0.17.

Questions about BIP 381

What is BIP 381?

BIP 381, “Non-Segwit Output Script Descriptors”, is a specification Bitcoin Improvement Proposal written by Pieter Wuille and Ava Chow and assigned in June 2021. Defines the descriptor functions for Bitcoin's older address types: pay-to-public-key, pay-to-public-key-hash (classic addresses starting with '1'), and pay-to-script-hash (addresses starting with '3'). This lets descriptor-based wallets describe and recover coins held in these legacy formats.

Is BIP 381 active?

Yes. BIP 381 has the status Deployed, which means it is live: adopted by the Bitcoin network or by widely used software.

Who wrote BIP 381?

BIP 381 was written by Pieter Wuille and Ava Chow. Its number was assigned on June 27, 2021.

What does BIP 381 build on?

BIP 381 requires BIP 380 (Output Script Descriptors General Operation). Read it first to understand this proposal.

Which BIPs build on BIP 381?

2 other BIPs reference BIP 381: BIP 380 (Output Script Descriptors General Operation) and BIP 129 (Bitcoin Secure Multisig Setup (BSMS)).

Where can I read the full BIP 381 specification?

The complete text of BIP 381 is on this page, taken unchanged from the official bitcoin/bips repository on GitHub. It is also available as Markdown and JSON.

BIPs that build on BIP 381

  • BIP 380: Output Script Descriptors General Operation: Deployed. Output script descriptors are a compact text language for describing exactly which addresses a wallet owns and how they are spent. This document defines their general syntax and checksum, giving…
  • BIP 129: Bitcoin Secure Multisig Setup (BSMS): Complete. Defines a step-by-step procedure for securely setting up a multisignature wallet, where several devices or people must approve spending. It helps participants verify each other's keys and confirm…

Learn more

Guides

Glossary

Related proposals