pset

package
v0.3.8-rc.0 Latest Latest
Warning

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

 Go to latest Published: Feb 15, 2022 License: MIT Imports: 21 Imported by: 5

README

PSET

A modification of the BIP-174 standard for Partial Signed Elements Transaction.

Changes from the standard reference

This package is designed in order to apply the possible fewer changes to the reference spec so that it can be used for Elements unblinded and blinded transactions.

Essentially this version of partial transaction uses an underlying Elements unsigned transaction instead of a Bitcoin one, and the partial input WitnessUtxo field represents an Elements output rather than a Bitcoin one.

NOTE: The Elements implementation of PSET is under development at the moment (take a look here) and this package will likely change in the future to adapt to this standard.

Creator

The creator is an exported factory function named simply New with the following signature:

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

The role of this function is to simply create an unsigned partial transaction wiwht the given inputs, outputs, version and locktime.
The unblinded asset and amounts of the outputs are encoded into the "unsigned tx" field of the partial transaction.

Updater

The updater, as the name suggests, has the responsibility of updating the fields of any partial input or output. It consists of a collection of methods that, basically, has the purpose of adding any new field to an existing partial input (included issuance or reissuance placed in the unsigned tx) or output.
It also allows to add new inputs or outputs to the underlying unsigned transaction.

The updater can be instantiated by calling the NewUpdater factory function passing a partial transasction object.

Blinder

At the moment the blinder role is designed to blind ALL the outputs of the partial transaction, but this will change soon, letting one to blind only the set of outputs he wants.
Also, this version of the blinder requires that all the private keys necessary to unblind all the confidential inputs used must be provided.
Given this, the pset package is not useful in case multiple parties want to create a transaction by joining their inputs/outputs since they would need to reveal their blinding private keys and share them with the one encharged of assuming the blinder role.
The pset package will change in the future to support the use case mentioned before, but this is not yet planned in the development.

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 expecting a finalized partial transaction that returns the final signed transaction by adding the signatures of the partial inputs to the underlying unsigned transaction.

Documentation

Index

Constants

View Source 
const (
	NonConfidentialReissuanceTokenFlag = 0
	ConfidentialReissuanceTokenFlag    = 1
)

Variables

View Source 
var (
	// ErrGenerateSurjectionProof is returned if the computation of the
	// surjection proof fails.
	ErrGenerateSurjectionProof = errors.New(
		"failed to generate surjection proof, please retry",
	)
	// ErrNeedPrevout is returned if a BlindingDataLike needs the input's prevout but received nil
	ErrNeedPrevout = errors.New(
		"need prevout to get blinding data",
	)
)

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.

func VerifyBlinding added in v0.0.4 

func VerifyBlinding(
	pset *Pset,
	blindingDataLikes []BlindingDataLike,
	outBlindKeysByIndex map[int][]byte,
	inIssuanceKeys []IssuanceBlindingPrivateKeys,
) (bool, error)

VerifyBlinding verifies the proofs of all the confidential outputs of the given transaction, with the given in/out private blinding keys.

Types

type AddIssuanceArgs added in v0.1.0 

type AddIssuanceArgs struct {
	Precision    uint
	Contract     *transaction.IssuanceContract
	AssetAmount  uint64
	TokenAmount  uint64
	AssetAddress string
	TokenAddress string
}

AddIssuanceArgs is a struct encapsulating all the issuance data that can be attached to any specific transaction of the PSBT.

type AddReissuanceArgs added in v0.1.0 

type AddReissuanceArgs struct {
	PrevOutHash    string
	PrevOutIndex   uint32
	PrevOutBlinder []byte
	WitnessUtxo    *transaction.TxOutput
	NonWitnessUtxo *transaction.Transaction
	Entropy        string
	AssetAmount    uint64
	AssetAddress   string
	TokenAmount    uint64
	TokenAddress   string
}

AddReissuanceArgs defines the mandatory fields that one needs to pass to the AddReissuance method of the *Updater type 

PrevOutHash: the prevout hash of the token that will be added as input to the tx
PrevOutIndex: the prevout index of the token that will be added as input to the tx
PrevOutBlinder: the asset blinder used to blind the prevout token
WitnessUtxo: the prevout token in case it is a witness one
NonWitnessUtxo: the prevout tx that include the token output in case it is a non witness one
Entropy: the entropy used to generate token and asset
AssetAmount: the amount of asset to re-issue
TokenAmount: the same unblinded amount of the prevout token
AssetAddress: the destination address of the re-issuing asset
TokenAddress: the destination address of the re-issuance token

type Blinder added in v0.2.0 

type Blinder struct {
	// contains filtered or unexported fields
}

Blinder is designed to blind ALL the outputs of the partial transaction.

func NewBlinder added in v0.0.2 

func NewBlinder(
	pset *Pset,
	blindingDataLikes []BlindingDataLike,
	outputsPubKeyByIndex map[int][]byte,
	issuanceBlindingPrivateKeys []IssuanceBlindingPrivateKeys,
	rng randomNumberGenerator,
) (*Blinder, error)

NewBlinder is a factory function using a map to select outputs to blind

func (*Blinder) Blind added in v0.2.0 

func (b *Blinder) Blind() error

Blind method blinds the outputs of the partial transaction and also the inputs' issuances if any issuanceBlindingPrivateKeys has been provided

type BlindingData added in v0.2.0 

type BlindingData confidential.UnblindOutputResult

BlindingData = blinders

func (BlindingData) GetUnblindOutputResult added in v0.2.0 

func (blindingData BlindingData) GetUnblindOutputResult(prevout *transaction.TxOutput) (*confidential.UnblindOutputResult, error)

GetUnblindOutputResult only cast BlindingData to unblindOutputResult

type BlindingDataLike added in v0.2.0 

type BlindingDataLike interface {
	GetUnblindOutputResult(prevout *transaction.TxOutput) (*confidential.UnblindOutputResult, error)
}

BlindingDataLike defines data used to get blinders from input

type IssuanceBlindingPrivateKeys added in v0.0.3 

type IssuanceBlindingPrivateKeys struct {
	AssetKey []byte
	TokenKey []byte
}

IssuanceBlindingPrivateKeys stores the AssetKey and TokenKey that will be used in the Blinder.

func (IssuanceBlindingPrivateKeys) ToSlice added in v0.0.4 

func (ik IssuanceBlindingPrivateKeys) ToSlice() [][]byte

ToSlice get private keys as []byte from IssuanceBlindingPrivateKeys

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 PrivateBlindingKey added in v0.2.0 

type PrivateBlindingKey []byte

PrivateBlindingKey = a bytes slice | used on confidential input

func (PrivateBlindingKey) GetUnblindOutputResult added in v0.2.0 

func (privKey PrivateBlindingKey) GetUnblindOutputResult(prevout *transaction.TxOutput) (*confidential.UnblindOutputResult, error)

GetUnblindOutputResult for PrivateBlindingKey unblind the associated prevout using the private key or return zero value blinders in case of unconfidential input

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.

func (*Pset) ValidateAllSignatures added in v0.0.4 

func (p *Pset) ValidateAllSignatures() (bool, error)

func (*Pset) ValidateInputSignatures added in v0.0.4 

func (p *Pset) ValidateInputSignatures(inputIndex int) (
	bool,
	error,
)

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 {
	Data *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.a

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) AddInput added in v0.0.3 

func (p *Updater) AddInput(txInput *transaction.TxInput)

AddInput adds input to underlying unsignedTx

func (*Updater) AddIssuance added in v0.0.3 

func (p *Updater) AddIssuance(arg AddIssuanceArgs) error

AddIssuance adds an unblinded issuance to the transaction

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) AddOutput added in v0.0.3 

func (p *Updater) AddOutput(txOutput *transaction.TxOutput)

AddOutput adds output to underlying unsignedTx

func (*Updater) AddReissuance added in v0.1.0 

func (p *Updater) AddReissuance(arg AddReissuanceArgs) error

AddReissuance takes care of adding an input (the prevout token) and 2 outputs to the partial transaction. It also creates a new (re)issuance with the provided entropy, blinder and amounts and attaches it to the new input. NOTE: This transaction must be blinded later so that a new token blinding nonce is generated for the new token output

func (*Updater) Sign 

func (p *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.