pset

package
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 21, 2020 License: MIT Imports: 14 Imported by: 5

README

PSET

A BIP174 compatible partial signed elements transaction encoding go package.

Creator

The creator is an exported factory function named just New that accepts a list of tx inputs, a list of tx outputs, a tx version and locktime, and returns a new instance of *Pset containing an unsigned transaction.

Updater

The updater, as the name suggests, has the responsibility of updating the fields of any partial input or output. Thus, basically, for any field of the PInput and POutput type, the Updater type exposes a function AddIn<PInputfieldName> and AddOut<POutputFieldName>.
To create a new updater, a factory function NewUpdater accepting a *Pset instance and returning a *Updater one is exposed.

Signer

The signer is in charge of checking that when adding a signature to an input of the pset, this is valid and that also the pset is correctly structured.
Given that, this role is implemented as a function Sign of the *Updater type.
This function accepts an input index, a signature, a public key, and one between a redeem or witness script and checks that the signature is valid against the given script and pubkey, along with setting the partial input's signature script to the one provided.

Finalizer

The finalizer takes a partial transaction and combines every input's PartialSignature into the final input's SignatureScript. After finalizing, the partial transaction is complete, and it's ready to be extracted from the Pset wrapper and broadcasted to the network.
This role is accomplished by a Finalize function that accepts a *Pset instance and an input index, and performs the operations described above, returning an error if any occurs during the process. It previously checks that the provided partial transaction is valid in the sense that it's ready to be finalized; otherwise, an error is returned.
A handy FinalizeAll that runs the above method for every input of the provided *Pset is also exported.

Extractor

The extractor is a simple Extract function that accepting a *Pset instance that checks that the provided partial transaction is complete (it returns an error otherwise), then make a copy of the pset's UnsignedTx and for every partial input adds the final input SignatureScript and PublicKey to the input witnesses. After this, the *Transaction instance is returned.

Documentation

Overview

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Extract 

func Extract(p *Pset) (*transaction.Transaction, error)

Extract takes a finalized pset.Pset and outputs a finalized transaction instance. Note that if the PSET is in-complete, then an error ErrIncompletePSET will be returned. As the extracted transaction has been fully finalized, it will be ready for network broadcast once returned.

func Finalize 

func Finalize(p *Pset, inIndex int) error

Finalize assumes that the provided pset.Pset struct has all partial signatures and redeem scripts/witness scripts already prepared for the specified input, and so removes all temporary data and replaces them with completed sigScript and witness fields, which are stored in key-types 07 and 08. The witness/non-witness utxo fields in the inputs (key-types 00 and 01) are left intact as they may be needed for validation (?). If there is any invalid or incomplete data, an error is returned.

func FinalizeAll 

func FinalizeAll(p *Pset) error

FinalizeAll finalizes all inputs of a partial elements transaction by calling the Finalize function for every partial input

func MaybeFinalize 

func MaybeFinalize(p *Pset, inIndex int) (bool, error)

MaybeFinalize attempts to finalize the input at index inIndex in the PSET p, returning true with no error if it succeeds, OR if the input has already been finalized.

func MaybeFinalizeAll 

func MaybeFinalizeAll(p *Pset) error

MaybeFinalizeAll attempts to finalize all inputs of the pset.Pset that are not already finalized, and returns an error if it fails to do so.

Types

type PInput 

type PInput struct {
	NonWitnessUtxo     *transaction.Transaction
	WitnessUtxo        *transaction.TxOutput
	PartialSigs        []*psbt.PartialSig
	SighashType        txscript.SigHashType
	RedeemScript       []byte
	WitnessScript      []byte
	Bip32Derivation    []*psbt.Bip32Derivation
	FinalScriptSig     []byte
	FinalScriptWitness []byte
	Unknowns           []*Unknown
}

PInput is a struct encapsulating all the data that can be attached to any specific input of the PSBT.

func NewPsetInput 

func NewPsetInput(nonWitnessUtxo *transaction.Transaction,
	witnessUtxo *transaction.TxOutput) *PInput

NewPsetInput creates an instance of PsbtInput given either a nonWitnessUtxo or a witnessUtxo.

NOTE: Only one of the two arguments should be specified, with the other being `nil`; otherwise the created PsbtInput object will fail IsSane() checks and will not be usable.

func (*PInput) IsSane 

func (pi *PInput) IsSane() bool

IsSane returns true only if there are no conflicting values in the Psbt PInput. It checks that witness and non-witness utxo entries do not both exist, and that witnessScript entries are only added to witness inputs.

type POutput 

type POutput struct {
	RedeemScript    []byte
	WitnessScript   []byte
	Bip32Derivation []*psbt.Bip32Derivation
}

POutput is a struct encapsulating all the data that can be attached to any specific output of the PSBT.

func NewPsbtOutput 

func NewPsbtOutput(redeemScript []byte, witnessScript []byte,
	bip32Derivation []*psbt.Bip32Derivation) *POutput

NewPsbtOutput creates an instance of PsbtOutput; the three parameters redeemScript, witnessScript and Bip32Derivation are all allowed to be `nil`.

type Pset 

type Pset struct {
	// UnsignedTx is the decoded unsigned transaction for this PSET.
	UnsignedTx *transaction.Transaction
	// Inputs contains all the information needed to properly sign this
	// target input within the above transaction.
	Inputs []PInput
	// Outputs contains all information required to spend any outputs
	// produced by this PSET.
	Outputs []POutput
	// Unknowns are the set of custom types (global only) within this PSET.
	Unknowns []Unknown // Data of unknown type at global scope
}

Pset is the actual psbt repreesntation. It is a is a set of 1 + N + M key-value pair lists, 1 global, defining the unsigned transaction structure with N inputs and M outputs. These key-value pairs can contain scripts, signatures, key derivations and other transaction-defining data.

func New 

func New(inputs []*transaction.TxInput,
	outputs []*transaction.TxOutput, version int32, nLockTime uint32) (*Pset, error)

New on provision of an input and output 'skeleton' for the transaction, a new partially populated PSET. The populated pset will include the unsigned transaction, and the set of known inputs and outputs contained within the unsigned transaction. The values of nLockTime and transaction version (must be 1 of 2) must be specified here. Note that the default nSequence value is wire.MaxTxInSequenceNum. Referencing the PSBT BIP, this function serves the roles of the Creator.

func NewPsetFromBase64 

func NewPsetFromBase64(psetBase64 string) (*Pset, error)

NewPsetFromBase64 returns a new Pset from a serialized pset in base64 encoding

func NewPsetFromHex 

func NewPsetFromHex(psetHex string) (*Pset, error)

NewPsetFromHex returns a new Pset from serialized pset in hex encoiding.

func NewPsetFromUnsignedTx 

func NewPsetFromUnsignedTx(tx *transaction.Transaction) (*Pset, error)

NewPsetFromUnsignedTx creates a new Pset struct, without any signatures (i.e. only the global section is non-empty) using the passed unsigned transaction.

func (*Pset) IsComplete 

func (p *Pset) IsComplete() bool

IsComplete returns true only if all of the inputs are finalized; this is particularly important in that it decides whether the final extraction to a network serialized signed transaction will be possible.

func (*Pset) SanityCheck 

func (p *Pset) SanityCheck() error

SanityCheck checks conditions on a PSBT to ensure that it obeys the rules of BIP174, and returns true if so, false if not.

func (*Pset) ToBase64 

func (p *Pset) ToBase64() (string, error)

ToBase64 returns the base64 encoding of the serialization of the current PSET, or an error if the encoding fails.

func (*Pset) ToHex 

func (p *Pset) ToHex() (string, error)

ToHex returns the hex encoding of the serialization of the current PSET, or an error if the encoding fails.

type Unknown 

type Unknown struct {
	Key   []byte
	Value []byte
}

Unknown is a struct encapsulating a key-value pair for which the key type is unknown by this package; these fields are allowed in both the 'Global' and the 'Input' section of a PSET.

type Updater 

type Updater struct {
	Upsbt *Pset
}

Updater encapsulates the role 'Updater' as specified in BIP174; it accepts Psbt structs and has methods to add fields to the inputs and outputs.

func NewUpdater 

func NewUpdater(p *Pset) (*Updater, error)

NewUpdater returns a new instance of Updater, if the passed Psbt struct is in a valid form, else an error.

func (*Updater) AddInBip32Derivation 

func (p *Updater) AddInBip32Derivation(masterKeyFingerprint uint32,
	bip32Path []uint32, pubKeyData []byte, inIndex int) error

AddInBip32Derivation takes a master key fingerprint as defined in BIP32, a BIP32 path as a slice of uint32 values, and a serialized pubkey as a byte slice, along with the integer index of the input, and inserts this data into that input.

NOTE: This can be called multiple times for the same input. An error is returned if addition of this key-value pair to the Psbt fails.

func (*Updater) AddInNonWitnessUtxo 

func (p *Updater) AddInNonWitnessUtxo(tx *transaction.Transaction, inIndex int) error

AddInNonWitnessUtxo adds the utxo information for an input which is non-witness. This requires provision of a full transaction (which is the source of the corresponding prevOut), and the input index. If addition of this key-value pair to the Psbt fails, an error is returned.

func (*Updater) AddInRedeemScript 

func (p *Updater) AddInRedeemScript(redeemScript []byte,
	inIndex int) error

AddInRedeemScript adds the redeem script information for an input. The redeem script is passed serialized, as a byte slice, along with the index of the input. An error is returned if addition of this key-value pair to the Psbt fails.

func (*Updater) AddInSighashType 

func (p *Updater) AddInSighashType(sighashType txscript.SigHashType,
	inIndex int) error

AddInSighashType adds the sighash type information for an input. The sighash type is passed as a 32 bit unsigned integer, along with the index for the input. An error is returned if addition of this key-value pair to the Psbt fails.

func (*Updater) AddInWitnessScript 

func (p *Updater) AddInWitnessScript(witnessScript []byte,
	inIndex int) error

AddInWitnessScript adds the witness script information for an input. The witness script is passed serialized, as a byte slice, along with the index of the input. An error is returned if addition of this key-value pair to the Psbt fails.

func (*Updater) AddInWitnessUtxo 

func (p *Updater) AddInWitnessUtxo(txout *transaction.TxOutput, inIndex int) error

AddInWitnessUtxo adds the utxo information for an input which is witness. This requires provision of a full transaction *output* (which is the source of the corresponding prevOut); not the full transaction because BIP143 means the output information is sufficient, and the input index. If addition of this key-value pair to the Psbt fails, an error is returned.

func (*Updater) AddOutBip32Derivation 

func (p *Updater) AddOutBip32Derivation(masterKeyFingerprint uint32,
	bip32Path []uint32, pubKeyData []byte, outIndex int) error

AddOutBip32Derivation takes a master key fingerprint as defined in BIP32, a BIP32 path as a slice of uint32 values, and a serialized pubkey as a byte slice, along with the integer index of the output, and inserts this data into that output.

NOTE: That this can be called multiple times for the same output. An error is returned if addition of this key-value pair to the Psbt fails.

func (*Updater) AddOutRedeemScript 

func (p *Updater) AddOutRedeemScript(redeemScript []byte,
	outIndex int) error

AddOutRedeemScript takes a redeem script as a byte slice and appends it to the output at index outIndex.

func (*Updater) AddOutWitnessScript 

func (p *Updater) AddOutWitnessScript(witnessScript []byte,
	outIndex int) error

AddOutWitnessScript takes a witness script as a byte slice and appends it to the output at index outIndex.

func (*Updater) Sign 

func (u *Updater) Sign(inIndex int, sig []byte, pubKey []byte,
	redeemScript []byte, witnessScript []byte) (psbt.SignOutcome, error)

Sign allows the caller to sign a PSBT at a particular input; they must provide a signature and a pubkey, both as byte slices; they can also optionally provide both witnessScript and/or redeemScript, otherwise these arguments must be set as nil (and in that case, they must already be present in the PSBT if required for signing to succeed).

This serves as a wrapper around Updater.addPartialSignature; it ensures that the redeemScript and witnessScript are updated as needed (note that the Updater is allowed to add redeemScripts and witnessScripts independently, before signing), and ensures that the right form of utxo field (NonWitnessUtxo or WitnessUtxo) is included in the input so that signature insertion (and then finalization) can take place.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.