tapfreighter

package
v0.4.0-alpha.rc3 Latest Latest
Warning

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

 Go to latest Published: Jul 10, 2024 License: MIT Imports: 33 Imported by: 0

Documentation

Index

Constants

View Source 
const Subsystem = "FRTR"

Subsystem defines the logging code for this subsystem.

Variables

View Source 
var (

	// ErrFullBurnNotSupported is returned when we attempt to burn all
	// assets of an anchor output, which is not supported.
	ErrFullBurnNotSupported = errors.New("burning all assets of an " +
		"anchor output is not supported")
)
View Source 
var (
	// ErrMatchingAssetsNotFound is returned when an instance of
	// AssetStoreListCoins cannot satisfy the given asset identification
	// constraints.
	ErrMatchingAssetsNotFound = fmt.Errorf("failed to find coin(s) that " +
		"satisfy given constraints; if previous transfers are un-" +
		"confirmed, wait for them to confirm before trying again")
)

Functions

func DisableLog 

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until UseLogger is called.

func UseLogger 

func UseLogger(logger btclog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using btclog.

Types

type AddrBook 

type AddrBook interface {
	// FetchScriptKey attempts to fetch the full tweaked script key struct
	// (including the key descriptor) for the given tweaked script key. If
	// the key cannot be found, then ErrScriptKeyNotFound is returned.
	FetchScriptKey(ctx context.Context,
		tweakedScriptKey *btcec.PublicKey) (*asset.TweakedScriptKey,
		error)

	// FetchInternalKeyLocator attempts to fetch the key locator information
	// for the given raw internal key. If the key cannot be found, then
	// ErrInternalKeyNotFound is returned.
	FetchInternalKeyLocator(ctx context.Context,
		rawKey *btcec.PublicKey) (keychain.KeyLocator, error)
}

AddrBook is an interface that provides access to the address book.

type AddressParcel 

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

AddressParcel is the main request to issue an asset transfer. This packages a destination address, and also response context.

func NewAddressParcel 

func NewAddressParcel(feeRate *chainfee.SatPerKWeight,
	destAddrs ...*address.Tap) *AddressParcel

NewAddressParcel creates a new AddressParcel.

func (*AddressParcel) Validate added in v0.3.0 

func (p *AddressParcel) Validate() error

Validate validates the parcel. The validation focuses on the necessary fields being present in order for the porter not to panic. Any business logic validation is assumed to already have happened.

type Anchor 

type Anchor struct {
	// OutPoint is the chain location of the anchor output.
	OutPoint wire.OutPoint

	// Value is output value of the anchor output.
	Value btcutil.Amount

	// InternalKey is the new internal key that commits to the set of assets
	// anchored at the new outpoint.
	InternalKey keychain.KeyDescriptor

	// TaprootAssetRoot is the Taproot Asset commitment root hash of the
	// anchor output.
	TaprootAssetRoot []byte

	// CommitmentVersion is the version of the Taproot Asset commitment
	// anchored in this output.
	CommitmentVersion *uint8

	// MerkleRoot is the root of the tap script merkle tree that also
	// contains the Taproot Asset commitment of the anchor output. If there
	// is no tapscript sibling, then this is equal to the TaprootAssetRoot.
	MerkleRoot []byte

	// TapscriptSibling is the serialized preimage of the tapscript sibling
	// of the Taproot Asset commitment.
	TapscriptSibling []byte

	// NumPassiveAssets is the number of passive assets in the commitment
	// for this anchor output.
	NumPassiveAssets uint32
}

Anchor represents the database level representation of an anchor output.

type AnchorVTxnsParams 

type AnchorVTxnsParams struct {
	// FeeRate is the fee rate that should be used to fund the anchor
	// transaction.
	FeeRate chainfee.SatPerKWeight

	// ActivePackets is a list of all the virtual transactions that should
	// be anchored by the anchor transaction.
	ActivePackets []*tappsbt.VPacket

	// PassivePackets is a list of all the virtual transactions which
	// re-anchor passive assets.
	PassivePackets []*tappsbt.VPacket
}

AnchorVTxnsParams holds all the parameters needed to create a BTC level anchor transaction that anchors multiple virtual transactions.

type AnchoredCommitment 

type AnchoredCommitment struct {
	// AnchorPoint is the outpoint that the Commitment below is anchored on
	// in the main chain.
	AnchorPoint wire.OutPoint

	// AnchorOutputValue is output value of the anchor output.
	AnchorOutputValue btcutil.Amount

	// InternalKey is the internal key that's used to anchor the commitment
	// in the above out point.
	InternalKey keychain.KeyDescriptor

	// TapscriptSibling is the tapscript sibling preimage of this asset.
	// This will usually be nil.
	TapscriptSibling *commitment.TapscriptPreimage

	// Commitment is the full Taproot Asset commitment anchored at the above
	// outpoint. This includes both the asset to be used as an input, along
	// with any other assets that might be collocated in this commitment.
	Commitment *commitment.TapCommitment

	// Asset is the asset that ratifies the above constraints, and should
	// be used as an input to a transaction.
	Asset *asset.Asset
}

AnchoredCommitment is the response to satisfying the set of CommitmentConstraints. This includes the asset itself, and also information needed to locate the asset on-chain and also prove its existence.

type AssetConfirmEvent 

type AssetConfirmEvent struct {
	// AnchorTXID is the anchor transaction's hash that was previously
	// unconfirmed.
	AnchorTXID chainhash.Hash

	// BlockHash is the block hash that confirmed the above anchor point.
	BlockHash chainhash.Hash

	// BlockHeight is the height of the block hash above.
	BlockHeight int32

	// TxIndex is the location within the block that confirmed the anchor
	// point.
	TxIndex int32

	// FinalProofs is the set of final full proof chain files that are going
	// to be stored on disk, one for each output in the outbound parcel.
	FinalProofs map[asset.SerializedKey]*proof.AnnotatedProof

	// PassiveAssetProofFiles is the set of passive asset proof files that
	// are re-anchored during the parcel confirmation process.
	PassiveAssetProofFiles map[asset.ID][]*proof.AnnotatedProof
}

AssetConfirmEvent is used to mark a batched spend as confirmed on disk.

type AssetSendEvent added in v0.4.0 

type AssetSendEvent struct {

	// SendState is the state that was just executed successfully, unless
	// Error below is set, then it means executing this state failed.
	SendState SendState

	// Error is an optional error, indicating that something went wrong
	// during the execution of the SendState above.
	Error error

	// Parcel is the parcel that is being sent.
	Parcel Parcel

	// VirtualPackets is the list of virtual packets that describes the
	// "active" parts of the asset transfer.
	VirtualPackets []*tappsbt.VPacket

	// PassivePackets is the list of virtual packets that describes the
	// "passive" parts of the asset transfer.
	PassivePackets []*tappsbt.VPacket

	// AnchorTx is the BTC level anchor transaction with all its information
	// as it was used when funding/signing it.
	AnchorTx *tapsend.AnchorTransaction

	// Transfer is the on-disk level information that tracks the pending
	// transfer.
	Transfer *OutboundParcel
	// contains filtered or unexported fields
}

AssetSendEvent is an event which is sent to the ChainPorter's event subscribers after a state was executed.

func (*AssetSendEvent) Timestamp added in v0.4.0 

func (e *AssetSendEvent) Timestamp() time.Time

Timestamp returns the timestamp of the event.

type AssetWallet 

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

AssetWallet is an implementation of the Wallet interface that can create virtual transactions, sign them and commit them on-chain.

func NewAssetWallet 

func NewAssetWallet(cfg *WalletConfig) *AssetWallet

NewAssetWallet creates a new AssetWallet instance from the given configuration.

func (*AssetWallet) AnchorVirtualTransactions 

func (f *AssetWallet) AnchorVirtualTransactions(ctx context.Context,
	params *AnchorVTxnsParams) (*tapsend.AnchorTransaction, error)

AnchorVirtualTransactions creates a BTC level anchor transaction that anchors all the virtual transactions of the given packets (for both sending and passive asset re-anchoring).

This method returns both the funded anchor TX with all the output information intact for later exclusion proof creation, and the fully signed and finalized anchor TX along with the total amount of sats paid in chain fees by the anchor TX.

func (*AssetWallet) CreatePassiveAssets added in v0.4.0 

func (f *AssetWallet) CreatePassiveAssets(ctx context.Context,
	activePackets []*tappsbt.VPacket,
	inputCommitments tappsbt.InputCommitments) ([]*tappsbt.VPacket, error)

CreatePassiveAssets creates passive asset packets for the given active packets and input Taproot Asset commitments.

func (*AssetWallet) FetchInternalKeyLocator added in v0.4.0 

func (f *AssetWallet) FetchInternalKeyLocator(ctx context.Context,
	rawKey *btcec.PublicKey) (keychain.KeyLocator, error)

FetchInternalKeyLocator attempts to fetch the key locator information for the given raw internal key. If the key cannot be found, then address.ErrInternalKeyNotFound is returned.

func (*AssetWallet) FetchScriptKey added in v0.4.0 

func (f *AssetWallet) FetchScriptKey(ctx context.Context,
	tweakedScriptKey *btcec.PublicKey) (*asset.TweakedScriptKey, error)

FetchScriptKey attempts to fetch the full tweaked script key struct (including the key descriptor) for the given tweaked script key. If the key cannot be found, then address.ErrScriptKeyNotFound is returned.

func (*AssetWallet) FundAddressSend 

func (f *AssetWallet) FundAddressSend(ctx context.Context,
	receiverAddrs ...*address.Tap) (*FundedVPacket, error)

FundAddressSend funds a virtual transaction, selecting assets to spend in order to pay the given address. It also returns supporting data which assists in processing the virtual transaction: passive asset re-anchors and the Taproot Asset level commitment of the selected assets.

NOTE: This is part of the Wallet interface.

func (*AssetWallet) FundBurn added in v0.3.0 

func (f *AssetWallet) FundBurn(ctx context.Context,
	fundDesc *tapsend.FundingDescriptor) (*FundedVPacket, error)

FundBurn funds a virtual transaction for burning the given amount of units of the given asset.

func (*AssetWallet) FundPacket 

func (f *AssetWallet) FundPacket(ctx context.Context,
	fundDesc *tapsend.FundingDescriptor,
	vPkt *tappsbt.VPacket) (*FundedVPacket, error)

FundPacket funds a virtual transaction, selecting assets to spend in order to pay the given recipient. The selected input is then added to the given virtual transaction.

func (*AssetWallet) SignOwnershipProof 

func (f *AssetWallet) SignOwnershipProof(
	ownedAsset *asset.Asset) (wire.TxWitness, error)

SignOwnershipProof creates and signs an ownership proof for the given owned asset. The ownership proof consists of a signed virtual packet that spends the asset fully to the NUMS key.

func (*AssetWallet) SignPassiveAssets 

func (f *AssetWallet) SignPassiveAssets(
	passiveAssets []*tappsbt.VPacket) error

SignPassiveAssets signs the given passive asset packets.

func (*AssetWallet) SignVirtualPacket 

func (f *AssetWallet) SignVirtualPacket(vPkt *tappsbt.VPacket,
	signOpts ...SignVirtualPacketOption) ([]uint32, error)

SignVirtualPacket signs the virtual transaction of the given packet and returns the input indexes that were signed (referring to the virtual transaction's inputs).

NOTE: This is part of the Wallet interface.

type ChainBridge 

type ChainBridge = tapgarden.ChainBridge

ChainBridge aliases into the ChainBridge of the tapgarden package.

type ChainPorter 

type ChainPorter struct {
	*fn.ContextGuard
	// contains filtered or unexported fields
}

ChainPorter is the main sub-system of the tapfreighter package. The porter is responsible for transferring your bags (assets). This porter is responsible for taking incoming delivery requests (parcels) and generating a final transfer transaction along with all the proofs needed to complete the transfer.

func NewChainPorter 

func NewChainPorter(cfg *ChainPorterConfig) *ChainPorter

NewChainPorter creates a new instance of the ChainPorter given a valid config.

func (*ChainPorter) QueryParcels added in v0.4.0 

func (p *ChainPorter) QueryParcels(ctx context.Context,
	anchorTxHash fn.Option[chainhash.Hash],
	pending bool) ([]*OutboundParcel, error)

QueryParcels returns the set of confirmed or unconfirmed parcels. If the anchor tx hash is Some, then a query for an parcel with the matching anchor hash will be made.

func (*ChainPorter) RegisterSubscriber 

func (p *ChainPorter) RegisterSubscriber(
	receiver *fn.EventReceiver[fn.Event],
	deliverExisting bool, deliverFrom bool) error

RegisterSubscriber adds a new subscriber to the set of subscribers that will be notified of any new events that are broadcast.

TODO(ffranr): Add support for delivering existing events to new subscribers.

func (*ChainPorter) RemoveSubscriber 

func (p *ChainPorter) RemoveSubscriber(
	subscriber *fn.EventReceiver[fn.Event]) error

RemoveSubscriber removes a subscriber from the set of subscribers that will be notified of any new events that are broadcast.

func (*ChainPorter) RequestShipment 

func (p *ChainPorter) RequestShipment(req Parcel) (*OutboundParcel, error)

RequestShipment is the main external entry point to the porter. This request a new transfer take place.

func (*ChainPorter) Start 

func (p *ChainPorter) Start() error

Start kicks off the chain porter and any goroutines it needs to carry out its duty.

func (*ChainPorter) Stop 

func (p *ChainPorter) Stop() error

Stop signals that the chain porter should gracefully stop.

type ChainPorterConfig 

type ChainPorterConfig struct {
	// Signer implements the Taproot Asset level signing we need to sign a
	// virtual transaction.
	Signer Signer

	// TxValidator allows us to validate each Taproot Asset virtual
	// transaction we create.
	TxValidator tapscript.TxValidator

	// ExportLog is used to log information about pending parcels to disk.
	ExportLog ExportLog

	// ChainBridge is our bridge to the chain we operate on.
	ChainBridge ChainBridge

	// GroupVerifier is used to verify the validity of the group key for a
	// genesis proof.
	GroupVerifier proof.GroupVerifier

	// Wallet is used to fund+sign PSBTs for the transfer transaction.
	Wallet WalletAnchor

	// KeyRing is used to generate new keys throughout the transfer
	// process.
	KeyRing KeyRing

	// AssetWallet is the asset-level wallet that we'll use to fund+sign
	// virtual transactions.
	AssetWallet Wallet

	ProofWriter ProofImporter

	ProofReader ProofExporter

	// ProofCourierDispatcher is the dispatcher that is used to create new
	// proof courier handles for sending proofs based on the protocol of
	// a proof courier address.
	ProofCourierDispatcher proof.CourierDispatch

	// ProofWatcher is used to watch new proofs for their anchor transaction
	// to be confirmed safely with a minimum number of confirmations.
	ProofWatcher proof.Watcher

	// ErrChan is the main error channel the custodian will report back
	// critical errors to the main server.
	ErrChan chan<- error
}

ChainPorterConfig is the main config for the chain porter.

type CoinLister 

type CoinLister interface {
	// ListEligibleCoins takes the set of commitment constraints and returns
	// an AnchoredCommitment that returns all the information needed to use
	// the commitment as an input to an on chain Taproot Asset transaction.
	//
	// If coin selection cannot be completed, then ErrMatchingAssetsNotFound
	// should be returned.
	ListEligibleCoins(context.Context,
		CommitmentConstraints) ([]*AnchoredCommitment, error)

	// LeaseCoins leases/locks/reserves coins for the given lease owner
	// until the given expiry. This is used to prevent multiple concurrent
	// coin selection attempts from selecting the same coin(s).
	LeaseCoins(ctx context.Context, leaseOwner [32]byte, expiry time.Time,
		utxoOutpoints ...wire.OutPoint) error

	// ReleaseCoins releases/unlocks coins that were previously leased and
	// makes them available for coin selection again.
	ReleaseCoins(ctx context.Context, utxoOutpoints ...wire.OutPoint) error

	// DeleteExpiredLeases deletes all expired leases from the database.
	DeleteExpiredLeases(ctx context.Context) error
}

CoinLister attracts over the coin selection process needed to be able to execute moving taproot assets on chain.

type CoinSelect 

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

CoinSelect selects asset coins to spend in order to fund a send transaction.

func NewCoinSelect 

func NewCoinSelect(coinLister CoinLister) *CoinSelect

NewCoinSelect creates a new CoinSelect.

func (*CoinSelect) LeaseCoins added in v0.3.0 

func (s *CoinSelect) LeaseCoins(ctx context.Context, leaseOwner [32]byte,
	expiry time.Time, utxoOutpoints ...wire.OutPoint) error

LeaseCoins leases/locks/reserves coins for the given lease owner until the given expiry. This is used to prevent multiple concurrent coin selection attempts from selecting the same coin(s).

func (*CoinSelect) ReleaseCoins added in v0.3.0 

func (s *CoinSelect) ReleaseCoins(ctx context.Context,
	utxoOutpoints ...wire.OutPoint) error

ReleaseCoins releases/unlocks coins that were previously leased and makes them available for coin selection again.

func (*CoinSelect) SelectCoins added in v0.3.0 

func (s *CoinSelect) SelectCoins(ctx context.Context,
	constraints CommitmentConstraints,
	strategy MultiCommitmentSelectStrategy,
	maxVersion commitment.TapCommitmentVersion) ([]*AnchoredCommitment,
	error)

SelectCoins returns a set of not yet leased coins that satisfy the given constraints and strategy. The coins returned are leased for the default lease duration.

type CoinSelector 

type CoinSelector interface {
	// SelectCoins returns a set of not yet leased coins that satisfy the
	// given constraints and strategy. The coins returned are leased for the
	// default lease duration.
	SelectCoins(ctx context.Context, constraints CommitmentConstraints,
		strategy MultiCommitmentSelectStrategy,
		maxVersion commitment.TapCommitmentVersion,
	) ([]*AnchoredCommitment,
		error)

	// ReleaseCoins releases/unlocks coins that were previously leased and
	// makes them available for coin selection again.
	ReleaseCoins(ctx context.Context, utxoOutpoints ...wire.OutPoint) error
}

CoinSelector is an interface that describes the functionality used in selecting coins during the asset send process.

type CommitmentConstraints 

type CommitmentConstraints struct {
	// GroupKey is the required group key. This is an optional field, if
	// set then the asset returned may have a distinct asset ID to the one
	// specified below.
	GroupKey *btcec.PublicKey

	// AssetID is the asset ID that needs to be satisfied.
	AssetID *asset.ID

	// MinAmt is the minimum amount that an asset commitment needs to hold
	// to satisfy the constraints.
	MinAmt uint64

	// Bip86ScriptKeysOnly is a flag that when set, will exclude any assets
	// that have a script key with a tapscript tree (a non-empty tweak).
	Bip86ScriptKeysOnly bool
}

CommitmentConstraints conveys the constraints on the type of Taproot asset commitments needed to satisfy a send request. Typically, for Bitcoin we just care about the amount. In the case of Taproot Asset, we also need to worry about the asset ID, and also the type of asset we need.

NOTE: Only the GroupKey or the AssetID should be set.

func (*CommitmentConstraints) String added in v0.4.0 

func (c *CommitmentConstraints) String() string

String returns the string representation of the commitment constraints.

type ExportLog 

type ExportLog interface {
	// LogPendingParcel marks an outbound parcel as pending on disk. This
	// commits the set of changes to disk (the asset deltas) but doesn't
	// mark the batched spend as being finalized.
	LogPendingParcel(context.Context, *OutboundParcel, [32]byte,
		time.Time) error

	// PendingParcels returns the set of parcels that haven't yet been
	// finalized. This can be used to query the set of unconfirmed
	// transactions for re-broadcast.
	PendingParcels(context.Context) ([]*OutboundParcel, error)

	// ConfirmParcelDelivery marks a spend event on disk as confirmed. This
	// updates the on-chain reference information on disk to point to this
	// new spend.
	ConfirmParcelDelivery(context.Context, *AssetConfirmEvent) error

	// QueryParcels returns the set of confirmed or unconfirmed parcels.
	QueryParcels(ctx context.Context, anchorTxHash *chainhash.Hash,
		pending bool) ([]*OutboundParcel, error)
}

ExportLog is used to track the state of outbound Taproot Asset parcels (batched spends). This log is used by the ChainPorter to mark pending outbound deliveries, and finally confirm the deliveries once they've been committed to the main chain.

type FundedVPacket 

type FundedVPacket struct {
	// VPacket is the virtual transaction that was created to fund the
	// transfer.
	VPacket *tappsbt.VPacket

	// InputCommitments is a map from virtual package input index to its
	// associated Taproot Asset commitment.
	InputCommitments tappsbt.InputCommitments
}

FundedVPacket is the result from an attempt to fund a given Taproot Asset address send request via a call to FundAddressSend.

type KeyRing 

type KeyRing = tapgarden.KeyRing

KeyRing aliases into the KeyRing of the tapgarden package.

type MultiCommitmentSelectStrategy 

type MultiCommitmentSelectStrategy uint8

MultiCommitmentSelectStrategy is an enum that describes the strategy that should be used when preferentially selecting multiple commitments. 

const (
	// PreferMaxAmount is a strategy which considers commitments in order of
	// descending amounts and selects the first subset which cumulatively
	// sums to at least the minimum target amount.
	PreferMaxAmount MultiCommitmentSelectStrategy = iota
)

type OutboundParcel 

type OutboundParcel struct {
	// AnchorTx is the new transaction that commits to the set of Taproot
	// Assets found at the above NewAnchorPoint.
	AnchorTx *wire.MsgTx

	// AnchorTxHeightHint is a block height recorded before the anchor tx is
	// broadcast, used as a starting block height when registering for
	// confirmations.
	AnchorTxHeightHint uint32

	// TransferTime holds the timestamp of the outbound spend.
	TransferTime time.Time

	// ChainFees is the amount in sats paid in on-chain fees for the
	// anchor transaction.
	ChainFees int64

	// PassiveAssets is the set of passive assets that are re-anchored
	// during the parcel confirmation process.
	PassiveAssets []*tappsbt.VPacket

	// PassiveAssetsAnchor is the anchor point for the passive assets. This
	// might be a distinct anchor from any active transfer in case the
	// active transfers don't create any change going back to us.
	PassiveAssetsAnchor *Anchor

	// Inputs represents the list of previous assets that were spent with
	// this transfer.
	Inputs []TransferInput

	// Outputs represents the list of new assets that were created with this
	// transfer.
	Outputs []TransferOutput
}

OutboundParcel represents the database level delta of an outbound Taproot Asset parcel (outbound spend). A spend will destroy a series of assets listed as inputs, and re-create them as new outputs. Along the way some assets may have been split or sent to others. This is reflected in the set of TransferOutputs.

func ConvertToTransfer added in v0.4.0 

func ConvertToTransfer(currentHeight uint32, activeTransfers []*tappsbt.VPacket,
	anchorTx *tapsend.AnchorTransaction, passiveAssets []*tappsbt.VPacket,
	isLocalKey func(asset.ScriptKey) bool) (*OutboundParcel, error)

ConvertToTransfer prepares the finished send data for storing to the database as a transfer. We generally understand a "transfer" as everything that happened on the asset level within a single bitcoin anchor transaction. Virtual transactions grouped into "active" transfers are movements that the user explicitly initiated. These usually can be identified as either creating a split (for partial amounts) or (for full value sends) as sending to a script key. Passive virtual transactions are state updates for all assets that were committed to in the same anchor transaction as the active assets being spent but remain under the daemon's control. These can be identified as 1-input-1-output virtual transactions that send to the same script key as they were already committed at.

func (*OutboundParcel) Copy added in v0.4.0 

func (o *OutboundParcel) Copy() *OutboundParcel

Copy creates a deep copy of the OutboundParcel.

type Parcel 

type Parcel interface {

	// Validate validates the parcel. The validation focuses on the
	// necessary fields being present in order for the porter not to panic.
	// Any business logic validation is assumed to already have happened.
	Validate() error
	// contains filtered or unexported methods
}

Parcel is an interface that each parcel type must implement.

type PendingParcel added in v0.2.1 

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

PendingParcel is a parcel that has not yet completed delivery.

func NewPendingParcel added in v0.2.1 

func NewPendingParcel(outboundPkg *OutboundParcel) *PendingParcel

NewPendingParcel creates a new PendingParcel.

func (*PendingParcel) Validate added in v0.3.0 

func (p *PendingParcel) Validate() error

Validate validates the parcel. The validation focuses on the necessary fields being present in order for the porter not to panic. Any business logic validation is assumed to already have happened.

type Porter 

type Porter interface {
	// RequestShipment attempts to request that a new send be funneled
	// through the chain porter. If successful, an initial response will be
	// returned with the pending transfer information.
	RequestShipment(req Parcel) (*OutboundParcel, error)

	// QueryParcels returns the set of confirmed or unconfirmed parcels. If
	// the anchor tx hash is Some, then a query for an parcel with the
	// matching anchor hash will be made.
	QueryParcels(ctx context.Context,
		anchorTxHash fn.Option[chainhash.Hash], pending bool,
	) ([]*OutboundParcel, error)

	// Start signals that the asset minter should being operations.
	Start() error

	// Stop signals that the asset minter should attempt a graceful
	// shutdown.
	Stop() error

	// EventPublisher is a subscription interface that allows callers to
	// subscribe to events that are relevant to the Porter.
	fn.EventPublisher[fn.Event, bool]
}

Porter is a high level interface that wraps the main caller execution point to the ChainPorter.

type PreAnchoredParcel added in v0.4.0 

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

PreAnchoredParcel is a request to log and publish an asset transfer of a pre-anchored parcel. All virtual PSBTs and the on-chain BTC level anchor transaction must be fully signed and ready to be broadcast.

func NewPreAnchoredParcel added in v0.4.0 

func NewPreAnchoredParcel(vPackets []*tappsbt.VPacket,
	passiveAssets []*tappsbt.VPacket,
	anchorTx *tapsend.AnchorTransaction) *PreAnchoredParcel

NewPreAnchoredParcel creates a new PreAnchoredParcel.

func (*PreAnchoredParcel) Validate added in v0.4.0 

func (p *PreAnchoredParcel) Validate() error

Validate validates the parcel. The validation focuses on the necessary fields being present in order for the porter not to panic. Any business logic validation is assumed to already have happened.

type PreSignedParcel 

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

PreSignedParcel is a request to issue an asset transfer of a pre-signed parcel. This packages a virtual transaction, the input commitment, and also the response context.

func NewPreSignedParcel 

func NewPreSignedParcel(vPackets []*tappsbt.VPacket,
	inputCommitments tappsbt.InputCommitments) *PreSignedParcel

NewPreSignedParcel creates a new PreSignedParcel.

func (*PreSignedParcel) Validate added in v0.3.0 

func (p *PreSignedParcel) Validate() error

Validate validates the parcel. The validation focuses on the necessary fields being present in order for the porter not to panic. Any business logic validation is assumed to already have happened.

type ProofExporter added in v0.4.0 

type ProofExporter interface {
	// FetchProof attempts to fetcb a serialized proof file from the local
	// archive based on the passed locator.
	FetchProof(ctx context.Context, id proof.Locator) (proof.Blob, error)
}

ProofExporter is used to fetch input proofs to

type ProofImporter added in v0.4.0 

type ProofImporter interface {
	// ImportProofs attempts to store fully populated proofs on disk. The
	// previous outpoint of the first state transition will be used as the
	// Genesis point. The final resting place of the asset will be used as
	// the script key itself. If replace is specified, we expect a proof to
	// already be present, and we just update (replace) it with the new
	// proof.
	ImportProofs(ctx context.Context, headerVerifier proof.HeaderVerifier,
		merkleVerifier proof.MerkleVerifier,
		groupVerifier proof.GroupVerifier,
		chainVerifier proof.ChainLookupGenerator, replace bool,
		proofs ...*proof.AnnotatedProof) error
}

ProofImporter is used to import proofs into the local proof archive after we complete a trransfer.

type SendState 

type SendState uint8

SendState is an enum that describes the current state of a pending outbound parcel (asset transfer). 

const (
	// SendStateVirtualCommitmentSelect is the state for performing input
	// coin selection to pick out which assets inputs should be spent.
	SendStateVirtualCommitmentSelect SendState = iota

	// SendStateVirtualSign is used to generate the Taproot Asset level
	// witness data for any inputs being spent.
	SendStateVirtualSign

	// SendStateAnchorSign is the state we enter after the PSBT has been
	// funded. In this state, we'll ask the wallet to sign the PSBT and
	// then finalize to place the necessary signatures in the transaction.
	SendStateAnchorSign

	// SendStateLogCommit is the final in memory state. In this state,
	// we'll extract the signed transaction from the PSBT and log the
	// transfer information to disk. At this point, after a restart, the
	// transfer can be resumed.
	SendStateLogCommit

	// SendStateBroadcast broadcasts the transfer transaction to the
	// network, and imports the taproot output back into the wallet to
	// ensure it properly tracks the coins allocated to the anchor output.
	SendStateBroadcast

	// SendStateWaitTxConf is a state in which we will wait for the transfer
	// transaction to confirm on-chain.
	SendStateWaitTxConf

	// SendStateStoreProofs is the state in which we will write the sender
	// and receiver proofs to the proof archive.
	SendStateStoreProofs

	// SendStateReceiverProofTransfer is the state in which we will commence
	// the receiver proof transfer process.
	SendStateReceiverProofTransfer

	// SendStateComplete is the state which is reached once entire asset
	// transfer process is complete.
	SendStateComplete
)

func (SendState) String 

func (s SendState) String() string

String returns a human-readable version of SendState.

type SignVirtualPacketOption 

type SignVirtualPacketOption func(*SignVirtualPacketOptions)

SignVirtualPacketOption is a functional option that allows a caller to modify the virtual packet signing process.

func SkipInputProofVerify 

func SkipInputProofVerify() SignVirtualPacketOption

SkipInputProofVerify sets an optional argument flag such that SignVirtualPacket skips virtual input proof verification.

func WithValidator added in v0.4.0 

func WithValidator(
	validator tapscript.WitnessValidator) SignVirtualPacketOption

WithValidator sets an optional argument that allows the caller to specify a custom witness validator to use when signing the virtual packet.

type SignVirtualPacketOptions 

type SignVirtualPacketOptions struct {
	// SkipInputProofVerify skips virtual input proof verification when
	// true.
	SkipInputProofVerify bool

	// WitnessValidator validates a signature after it's been created.
	WitnessValidator tapscript.WitnessValidator
}

SignVirtualPacketOptions is a set of functional options that allow callers to further modify the virtual packet signing process.

type Signer 

type Signer = tapscript.Signer

Signer aliases into the Signer interface of the tapscript package.

type TransferInput 

type TransferInput struct {
	// PrevID contains the anchor point, ID and script key of the asset that
	// is being spent.
	asset.PrevID

	// Amount is the input amount that was spent.
	Amount uint64
}

TransferInput represents the database level input to an asset transfer.

type TransferOutput 

type TransferOutput struct {
	// Anchor is the new location of the Taproot Asset commitment referenced
	// by this transfer output.
	Anchor Anchor

	// Type indicates what type of output this is, which has an influence on
	// whether the asset is set or what witness type is expected to be
	// generated for the asset.
	Type tappsbt.VOutputType

	// ScriptKey is the new script key.
	ScriptKey asset.ScriptKey

	// ScriptKeyLocal indicates whether the script key is known to the lnd
	// node connected to this daemon. If this is false, then we won't create
	// a new asset entry in our database as we consider this to be an
	// outbound transfer.
	ScriptKeyLocal bool

	// Amount is the new amount for the asset.
	Amount uint64

	// LockTime, if non-zero, restricts an asset from being moved prior to
	// the represented block height in the chain. This value needs to be set
	// on the asset that is spending from a script key with a CLTV script.
	LockTime uint64

	// RelativeLockTime, if non-zero, restricts an asset from being moved
	// until a number of blocks after the confirmation height of the latest
	// transaction for the asset is reached. This value needs to be set
	// on the asset that is spending from a script key with a CSV script.
	RelativeLockTime uint64

	// AssetVersion is the new asset version for this output.
	AssetVersion asset.Version

	// WitnessData is the new witness data for this asset.
	WitnessData []asset.Witness

	// SplitCommitmentRoot is the root split commitment for this asset.
	// This will only be set if a split was required to complete the send.
	SplitCommitmentRoot mssmt.Node

	// ProofSuffix is the fully serialized proof suffix of the output which
	// includes all the proof information other than the final chain
	// information.
	ProofSuffix []byte

	// ProofCourierAddr is the bytes encoded proof courier service address
	// associated with this output.
	ProofCourierAddr []byte
}

TransferOutput represents the database level output to an asset transfer.

type Wallet 

type Wallet interface {
	// FundAddressSend funds a virtual transaction, selecting assets to
	// spend in order to pay the given address. It also returns supporting
	// data which assists in processing the virtual transaction: passive
	// asset re-anchors and the Taproot Asset level commitment of the
	// selected assets.
	FundAddressSend(ctx context.Context,
		receiverAddrs ...*address.Tap) (*FundedVPacket, error)

	// FundPacket funds a virtual transaction, selecting assets to spend
	// in order to pay the given recipient. The selected input is then added
	// to the given virtual transaction.
	FundPacket(ctx context.Context, fundDesc *tapsend.FundingDescriptor,
		vPkt *tappsbt.VPacket) (*FundedVPacket, error)

	// FundBurn funds a virtual transaction for burning the given amount of
	// units of the given asset.
	FundBurn(ctx context.Context,
		fundDesc *tapsend.FundingDescriptor) (*FundedVPacket, error)

	// SignVirtualPacket signs the virtual transaction of the given packet
	// and returns the input indexes that were signed.
	SignVirtualPacket(vPkt *tappsbt.VPacket,
		optFuncs ...SignVirtualPacketOption) ([]uint32, error)

	// CreatePassiveAssets creates passive asset packets for the given
	// active packets and input Taproot Asset commitments.
	CreatePassiveAssets(ctx context.Context,
		activePackets []*tappsbt.VPacket,
		inputCommitments tappsbt.InputCommitments) ([]*tappsbt.VPacket,
		error)

	// SignPassiveAssets signs the given passive asset packets.
	SignPassiveAssets(passiveAssets []*tappsbt.VPacket) error

	// AnchorVirtualTransactions creates a BTC level anchor transaction that
	// anchors all the virtual transactions of the given packets (for both
	// sending and passive asset re-anchoring).
	//
	// This method returns both the funded anchor TX with all the output
	// information intact for later exclusion proof creation, and the fully
	// signed and finalized anchor TX along with the total amount of sats
	// paid in chain fees by the anchor TX.
	AnchorVirtualTransactions(ctx context.Context,
		params *AnchorVTxnsParams) (*tapsend.AnchorTransaction, error)

	// SignOwnershipProof creates and signs an ownership proof for the given
	// owned asset. The ownership proof consists of a valid witness of a
	// signed virtual packet that spends the asset fully to the NUMS key.
	SignOwnershipProof(ownedAsset *asset.Asset) (wire.TxWitness, error)

	// FetchScriptKey attempts to fetch the full tweaked script key struct
	// (including the key descriptor) for the given tweaked script key. If
	// the key cannot be found, then address.ErrScriptKeyNotFound is
	// returned.
	FetchScriptKey(ctx context.Context,
		tweakedScriptKey *btcec.PublicKey) (*asset.TweakedScriptKey,
		error)

	// FetchInternalKeyLocator attempts to fetch the key locator information
	// for the given raw internal key. If the key cannot be found, then
	// address.ErrInternalKeyNotFound is returned.
	FetchInternalKeyLocator(ctx context.Context,
		rawKey *btcec.PublicKey) (keychain.KeyLocator, error)
}

Wallet is an interface for funding and signing asset transfers.

type WalletAnchor 

type WalletAnchor interface {
	tapgarden.WalletAnchor

	// SignPsbt signs all the inputs it can in the passed-in PSBT packet,
	// returning a new one with updated signature/witness data.
	SignPsbt(ctx context.Context, packet *psbt.Packet) (*psbt.Packet, error)
}

WalletAnchor aliases into the WalletAnchor of the taparden package.

type WalletConfig 

type WalletConfig struct {
	// CoinSelector is the interface used to select input coins (assets)
	// for the transfer.
	CoinSelector CoinSelector

	// AssetProofs is used to write the proof files on disk for the
	// receiver during a transfer.
	//
	// TODO(roasbeef): replace with proof.Courier in the future/
	AssetProofs proof.Archiver

	// AddrBook is used to fetch information about local address book
	// related data in the database.
	AddrBook AddrBook

	// KeyRing is used to generate new keys throughout the transfer
	// process.
	KeyRing KeyRing

	// Signer implements the Taproot Asset level signing we need to sign a
	// virtual transaction.
	Signer Signer

	// TxValidator allows us to validate each Taproot Asset virtual
	// transaction we create.
	TxValidator tapscript.TxValidator

	// WitnessValidator allows us to validate the witnesses of vPSBTs
	// we create.
	WitnessValidator tapscript.WitnessValidator

	// Wallet is used to fund+sign PSBTs for the transfer transaction.
	Wallet WalletAnchor

	// ChainParams is the chain params of the chain we operate on.
	ChainParams *address.ChainParams
}

WalletConfig holds the configuration for a new Wallet.

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.