The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Bitcoin::Crypto::Script - Bitcoin Script instance

SYNOPSIS

        use Bitcoin::Crypto::Script;

        my $script = Bitcoin::Crypto::Script->from_standard(
                [P2WPKH => $my_segwit_address]
        );

        # getting serialized script
        my $serialized = $script->to_serialized();

        # getting P2WSH address from script
        my $sh_address = $script->get_segwit_adress();

        # getting back the address encoded in P2WPKH script
        my $address = $script->get_address();

DESCRIPTION

This class allows you to create Perl representation of a Bitcoin script.

You can use a script object to:

  • create a script from opcodes

  • serialize a script into byte string

  • deserialize a script into a sequence of opcodes

  • create legacy (p2sh), compat (p2sh(p2wsh)) and segwit (p2wsh) adresses

  • execute the script

ATTRIBUTES

type

Contains the type of the script, if the script is standard and the type is known. Otherwise, contains undef.

predicate: has_type

METHODS

new

        $script_object = $class->new()

A constructor. Returns a new empty script instance.

See "from_serialized" if you want to import a serialized script instead.

operations

        $ops_aref = $object->operations

Returns an array reference of operations contained in a script:

        [
                [OP_XXX (Object), raw (String), ...],
                ...
        ]

The first element of each subarray is the Bitcoin::Crypto::Script::Opcode object. The second element is the raw opcode string, usually single byte. The rest of elements are metadata and is dependant on the op type. This metadata is used during script execution.

add_operation, add

        $script_object = $object->add_operation($opcode)

Adds a new opcode at the end of a script. Returns the object instance for chaining.

add is a shorter alias for add_operation.

Throws an exception for unknown opcodes.

add_raw

        $script_object = $object->add_raw($bytes)

Adds $bytes at the end of the script without processing them at all.

Returns the object instance for chaining.

push_bytes, push

        $script_object = $object->push_bytes($bytes)

Pushes $bytes to the execution stack at the end of a script, using a minimal push opcode.

push is a shorter alias for push_bytes.

For example, running $script->push_bytes("\x03") will have the same effect as $script->add_operation('OP_3').

Throws an exception for data exceeding a 4 byte number in length.

Note that no data longer than 520 bytes can be pushed onto the stack in one operation, but this method will not check for that.

Returns the object instance for chaining.

to_serialized

        $bytestring = $object->to_serialized()

Returns a serialized script as byte string.

from_serialized

        $script = Bitcoin::Crypto::Script->from_serialized($bytestring);

Creates a new script instance from a bytestring.

from_standard

        $object = Bitcoin::Crypto::Script->from_standard([P2PKH => '1Ehr6cNDzPCx3wQRu1sMdXWViEi2MQnFzH'])
        $object = Bitcoin::Crypto::Script->from_standard([address => '1Ehr6cNDzPCx3wQRu1sMdXWViEi2MQnFzH'])

Creates a new object of standard type with given address. The address must be of the currently default network. In case of NULLDATA, P2MS and P2PK there is no address, and the second argument must be custom data (NULLDATA), public key (P2PK) or an array reference with number N of signatures followed by M public keys (N of M P2MS).

The first argument can also be specified as address to enable auto-detection of script type.

get_hash

        $bytestring = $object->get_hash()

Returns a serialized script parsed with HASH160 (ripemd160 of sha256).

set_network

        $script_object = $object->set_network($val)

Change key's network state to $val. It can be either network name present in Bitcoin::Crypto::Network package or an instance of this class.

Returns current object instance.

get_legacy_address

        $address = $object->get_legacy_address()

Returns string containing Base58Check encoded script hash (P2SH address)

get_compat_address

        $address = $object->get_compat_address()

Returns string containing Base58Check encoded script hash containing a witness program for compatibility purposes (P2SH(P2WSH) address)

get_segwit_address

        $address = $object->get_segwit_address()

Returns string containing Bech32 encoded witness program (P2WSH address)

get_address

        $address = $object->get_address()

This method does not return P2SH address, but instead the address encoded in the script of standard type. For example, if the script is of type P2WPKH, then the contained alegacy address will be returned. If the script is not of standard type or the type does not contain an address, returns undef.

Currently handles script of types P2PKH, P2SH, P2WPKH, P2WSH.

run

        $runner = $object->run(\@initial_stack)

Executes the script and returns Bitcoin::Crypto::Script::Runner instance after running the script.

This is a convenience method which constructs runner instance in the background. This helper is only meant to run simple scripts.

is_native_segwit

        $boolean = $object->is_native_segwit

Returns true if the type of the script is either P2WPKH or P2WSH.

is_empty

        $boolean = $object->is_empty

Returns true if the script is completely empty (contains no opcodes).

is_pushes_only

        $boolean = $object->is_pushes_only

Returns true if the script contains only opcodes pushing to the stack.

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:

  • ScriptOpcode - unknown opcode was specified

  • ScriptPush - data pushed to the execution stack is invalid

  • ScriptType - invalid standard script type name specified

  • ScriptSyntax - script syntax is invalid

  • ScriptRuntime - script runtime error

  • SegwitProgram - Segregated witness address error

  • NetworkConfig - incomplete or corrupted network configuration

  • NetworkCheck - address does not belong to the configured network

SEE ALSO

Bitcoin::Crypto::Script::Runner
Bitcoin::Crypto::Script::Opcode
Bitcoin::Crypto::Transaction