NAME
Bitcoin::Crypto::Script::Tree - BIP341 Script trees
SYNOPSIS
DESCRIPTION
This module contains implementation of script trees described in BIP341. These trees are used by taproot and are necessary to build custom taproot scripts.
Tree leaves
Each leaf in the tree is represented with this Perl structure:
{
id => integer (optional),
leaf_version => integer,
script => Bitcoin::Crypto::Script instance (or its coercible),
}Optional id is used to identify the leaf in the tree, which is used in methods like "get_control_block".
Currently, leaf_version must be equal to Bitcoin::Crypto::Constants::tapscript_leaf_version, since other versions are reserved for future use.
If the leaf is prehashed or not known, it can be represented as this structure instead:
{
hash => bytestring with prehashed leaf,
}INTERFACE
Attributes
tree
Available in the constructor.
Internal structure of the tree. This structure represents a binary tree and must contain an array reference of array or hash references.
Each level of a tree must be an array reference with up to two values in it. Each leaf must be a hash with either a prehashed value under hash key (bytestring or something which can be coerced into a bytestring) or a script to be hashed represented by keys leaf_version (integer up to 255) and script (an instance of Bitcoin::Crypto::Script or something which can be coerced into it).
Example structure:
# tree with all scripts known
[
{
id => 0,
leaf_version => Bitcoin::Crypto::Constants::tapscript_leaf_version,
script => [hex => '2071981521ad9fc9036687364118fb6ccd2035b96a423c59c5430e98310a11abe2ac']
},
[
{
id => 1,
leaf_version => Bitcoin::Crypto::Constants::tapscript_leaf_version,
script => [hex => '20d5094d2dbe9b76e2c245a2b89b6006888952e2faa6a149ae318d69e520617748ac']
},
{
id => 2,
leaf_version => Bitcoin::Crypto::Constants::tapscript_leaf_version,
script => [hex => '20c440b462ad48c7a77f94cd4532d8f2119dcebbd7c9764557e62726419b08ad4cac']
}
]
]Each element may be prehashed, which represents the same tree, but without disclosing information about a script:
# same tree, but only one script is known and can be executed
[
{hash => [hex => 'f154e8e8e17c31d3462d7132589ed29353c6fafdb884c5a6e04ea938834f0d9d']},
[
{
leaf_version => Bitcoin::Crypto::Constants::tapscript_leaf_version,
script => [hex => '20d5094d2dbe9b76e2c245a2b89b6006888952e2faa6a149ae318d69e520617748ac']
},
{hash => [hex => 'd7485025fceb78b9ed667db36ed8b8dc7b1f0b307ac167fa516fe4352b9f4ef7']},
]
]Methods
new
$tree = $class->new(%args)Standard Moo constructor - see "Attributes".
from_path
$tree = $class->from_path($leaf, \@path)This static method builds a new $tree object from key path @path. Key path represents a script tree by a series of prehashed leaves. $leaf is a tree leaf deserialized from transaction data.
@path must only contain bytestrings or their coercibles. Example @path could look like this:
(
[hex => 'd7485025fceb78b9ed667db36ed8b8dc7b1f0b307ac167fa516fe4352b9f4ef7'],
[hex => 'f154e8e8e17c31d3462d7132589ed29353c6fafdb884c5a6e04ea938834f0d9d'],
)get_merkle_root
$hash = $tree->get_merkle_root()Calculates a merkle root of the script tree. Returns a bytestring which is the root hash of the tree.
get_tapleaf_hash
$hash = $tree->get_tapleaf_hash($leaf_id)Calculates a tapleaf hash of a leaf with given $leaf_id. If such leaf does not exist, an exception is thrown. Returns a bytestring.
get_control_block
$block = $tree->get_control_block($leaf_id, $pubkey)Builds a taproot control block used in taproot witness data. $leaf_id must be a valid identifier of a leaf existing in the tree. $pubkey is a public key that associated with the address for key path spending. Returns an instance of Bitcoin::Crypto::Transaction::ControlBlock.
get_tree_paths
$paths = $tree->get_tree_paths()Returns a hash reference of paths for each of leaves in the tree which have an id. Each path is an array reference - same as what "from_path" takes as input.
EXCEPTIONS
This module throws an instance of Bitcoin::Crypto::Exception if it encounters an error. It can produce the following error types from the Bitcoin::Crypto::Exception namespace:
ScriptTree - general error with the tree