Tx

class riemann.tx.Tx(version: bytes, flag: Optional[bytes], tx_ins: Sequence[riemann.tx.tx.TxIn], tx_outs: Sequence[riemann.tx.tx.TxOut], tx_witnesses: Optional[Sequence[riemann.tx.tx.InputWitness]], lock_time: bytes)

A complete transaction. It consists of a version, a flag that indicates the presence of witnesses (and breaks legacy parsers), a length-prepended vector of TxIn objects, a length-prepended vector of TxOut objects, and a locktime number. Compatibility and Segwit transactions MUST contain the witness flag. Signed Compatibility and Segwit transactions will additionally contain a vector of InputWitness objects.

This object provides a number of conveniences for interacting with transactions, including tx_id calculation, and sighash calculation.

To serialize the transaction, call to_bytes() or hex().

Note

The lock_time field is used to set absolute timelocks. These are complex and confusing. See this blog post for details.

Parameters

  • version – the 4-byte LE version number. Must be 1 or 2. Setting to 1 deactivates relative lock times.

  • tx_ins – the ordered sequence of TxIn objects representing TXOs. consumed by this transaction. Signed Legacy transaction will include spend authorization here.

  • tx_outs – the ordered sequence of TxOut objects representing TXOs created by this transaction.

  • tx_witnesses – the ordered sequence of InputWitness objects associated with this transaction. Always empty in Legacy transactions. In Compatibility and Segwit transactions there must be one witness per input.

  • lock_time – the 4-byte LE locktime number. Setting this invokes the absolute time lock system. If it is below 500,000,000 it is interpreted as a blockheight before which the transaction is invalid. If set above that, it is interpreted as a Unix timestamp before which the transaction is invalid.

version

the 4-byte LE version number. Must be 1 or 2. Setting to 1 deactivates relative lock times.

flag

the 2-byte witness transaction flag. Always empty for Legacy transaction, or ‘0001’ for Compatibility and Witness transactions

tx_ins

the ordered sequence of TxIn objects representing TXOs. consumed by this transaction. Signed Legacy transaction will include spend authorization here.

tx_outs

the ordered sequence of TxOut objects representing TXOs created by this transaction.

tx_witnesses

the ordered sequence of InputWitness objects associated with this transaction. Always empty in Legacy transactions. In Compatibility and Segwit transactions there must be one witness per input.

lock_time

the 4-byte LE locktime number. Setting this invokes the absolute time lock system. If it is below 500,000,000 it is interpreted as a blockheight before which the transaction is invalid. If set above that, it is interpreted as a Unix timestamp before which the transaction is invalid.

tx_id_le

the LE (in-protocol) hash committed to by the block header transaction merkle tree.

wtx_id_le

the LE (in-protocol) hash committed to by the coinbase transaction witness merkle tree. Not present in Legacy transactions.

tx_id

the BE (block explorer or human-facing) tx_id.

wtx_id

the BE (block explorer or human-facing) wtx_id. Not present in Legacy transactions.

calculate_fee(input_values: Sequence[int]) → int

Calculate the fee associated with a transaction. Caller must provide a sequence representing the value (in satoshi) of each input.

Parameters

input_values – The value of each input in order.

Returns

The total fee paid to miners by this transaction.

copy(version: Optional[bytes] = None, flag: Optional[bytes] = None, tx_ins: Optional[Sequence[riemann.tx.tx.TxIn]] = None, tx_outs: Optional[Sequence[riemann.tx.tx.TxOut]] = None, tx_witnesses: Optional[Sequence[riemann.tx.tx.InputWitness]] = None, lock_time: Optional[bytes] = None) → riemann.tx.tx.Tx

Make a new copy of the object with optional modifications.

classmethod from_bytes(byte_string: bytes) → riemann.tx.tx.Tx

Instantiate a Tx object from a bytestring

classmethod from_hex(hex_string: str) → riemann.tx.tx.Tx

Instantiate a Tx object from a hex string

is_witness() → bool

Return True if the transaction witness flag is set

no_witness() → bytes

Return the Tx as a bytestring stripped of witnesses. This is the preimage of tx_id and tx_id_le.

segwit_sighash(index: int, sighash_type: int, prevout_value: bytes, script: bytes, anyone_can_pay: bool = False) → bytes

Implements bip143 (witness) sighash. Prefer calling sighash_all or sighash_single.

For documentation see here: https://github.com/bitcoin/bips/blob/master/bip-0143.mediawiki

For an excellent pasta dinner, see here: https://ricette.giallozafferano.it/Spaghetti-alla-Norma.html

sighash_all(index, script, prevout_value=None, anyone_can_pay=False) → bytes

Calculate the hash to be signed when adding authorization information (a script sig or a witness) to an input using SIGHASH_ALL.

SIGHASH_ALL commits to ALL inputs, and ALL outputs. It indicates that no further modification of the transaction is allowed without invalidating the signature.

SIGHASH_ALL + ANYONECANPAY commits to ONE input and ALL outputs. It indicates that anyone may add additional value to the transaction, but that no one may modify the payments made. Any extra value added above the sum of output values will be given to miners as part of the tx fee.

We must specify the index of the input in the tx_ins sequence, the script controlling the TXO being spent by the input, and whether to use the ANYONECANPAY sighash modifier. Compatibility and Witness inputs must additionally supply the value of the TXO being consumed.

This function automatically selects between Legacy, Witness, and Bcash SIGHASH_FORKID based on the network selected, and whether the witness flag is present in the transaction.

For Legacy sighash documentation, see here:

For BIP143 (Witness and Compatibility) documentation, see here:

For the BitcoinCash specific rip-off of BIP143 documentation, see here:

Note

After signing the digest, you MUST append the sighash indicator byte to the resulting signature. This will be 0x01 (SIGHASH_ALL) or 0x81 (SIGHASH_ALL + SIGHASH_ANYONECANPAY).

Parameters

  • index – The index of the input being authorized

  • script – The length-prepended script associated with the TXO being spent. For PKH outputs this will be a pkh spend script ( i.e. ‘1976a914….88ac’). For SH outputs this will be the redeem_script (Legacy) or Witness Script (Compatibility and Segwit). If the TXO being spent has a non-standard output script, use that here.

  • prevout_value – The 8-byte LE integer-encoded value of the prevout

  • anyone_can_pay – True if using the ANYONECANPAY sighash modifier

Returns

The 32-byte digest to be signed.

sighash_none() → bytes

SIGHASH_NONE is a bad idea.

sighash_single(index, script, prevout_value=None, anyone_can_pay=False)

Calculate the hash to be signed when adding authorization information (a script sig or a witness) to an input using SIGHASH_SINGLE.

SIGHASH_SINGLE commits to ALL inputs, and ONE output. It indicates that/ anyone may append additional outputs to the transaction to reroute funds from the inputs. Additional inputs cannot be added without invalidating the signature. It is logically difficult to use securely, as it consents to funds being moved, without specifying their destination.

SIGHASH_SINGLE commits specifically the the output at the same index as the input being signed. If there is no output at that index, (because, e.g. the input vector is longer than the output vector) it behaves insecurely, and we do not implement that protocol bug.

SIGHASH_SINGLE + ANYONECANPAY commits to ONE input and ONE output. It indicates that anyone may add additional value to the transaction, and route value to any other location. The signed input and output must be included in the fully-formed transaction at the same index in their respective vectors.

When the input is larger than the output, a partial transaction signed this way cedes the difference to whoever cares to construct a complete transaction. However, when the output is larger than the input, it functions as a one-time-use payment invoice. Anyone may consume the input by adding value. This is useful for addressing race conditions in certain cross-chain protocols that the author of this documentation invented. :)

We must specify the index of the input in the tx_ins sequence, the script controlling the TXO being spent by the input, and whether to use the ANYONECANPAY sighash modifier. Compatibility and Witness inputs must additionally supply the value of the TXO being consumed.

This function automatically selects between Legacy, Witness, and Bcash SIGHASH_FORKID based on the network selected, and whether the witness flag is present in the transaction.

For Legacy sighash documentation, see here:

For BIP143 (Witness and Compatibility) documentation, see here:

For the BitcoinCash specific rip-off of BIP143 documentation, see here:

Note

After signing the digest, you MUST append the sighash indicator byte to the resulting signature. This will be 0x03 (SIGHASH_SINGLE) or 0x83 (SIGHASH_SINGLE + SIGHASH_ANYONECANPAY).

Parameters

  • index – The index of the input being authorized

  • script – The length-prepended script associated with the TXO being spent. For PKH outputs this will be a pkh spend script ( i.e. ‘1976a914….88ac’). For SH outputs this will be the redeem_script (Legacy) or Witness Script (Compatibility and Segwit). If the TXO being spent has a non-standard output script, use that here.

  • prevout_value – The 8-byte LE integer-encoded value of the prevout

  • anyone_can_pay – True if using the ANYONECANPAY sighash modifier

Returns

The 32-byte digest to be signed.