mixpool

Documentation

Overview

Package mixpool provides an in-memory pool of mixing messages for full nodes that relay these messages and mixing wallets that send and receive them.

Index

• Variables
• func IsBannable(err error, services wire.ServiceFlag) bool
• func UseLogger(logger slog.Logger)
• type BlockChain
• type MissingOwnPRError
  • func (e *MissingOwnPRError) Error() string
• type Pool
  • func NewPool(blockchain BlockChain) *Pool
  • func (p *Pool) AcceptMessage(msg mixing.Message) (accepted []mixing.Message, err error)
  • func (p *Pool) CompatiblePRs(pairing []byte) []*wire.MsgMixPairReq
  • func (p *Pool) Epoch() time.Duration
  • func (p *Pool) ExpireMessages(height uint32)
  • func (p *Pool) ExpireMessagesInBackground(height uint32)
  • func (p *Pool) HaveMessage(query *chainhash.Hash) bool
  • func (p *Pool) Message(query *chainhash.Hash) (mixing.Message, error)
  • func (p *Pool) MixPRs() []*wire.MsgMixPairReq
  • func (p *Pool) Receive(ctx context.Context, r *Received) error
  • func (p *Pool) ReceiveKEsByPairing(pairing []byte, epoch uint64) []*wire.MsgMixKeyExchange
  • func (p *Pool) RecentMessage(query *chainhash.Hash) (mixing.Message, bool)
  • func (p *Pool) RemoveConfirmedMixes(txHashes []chainhash.Hash)
  • func (p *Pool) RemoveConfirmedSessions()
  • func (p *Pool) RemoveMessage(msg mixing.Message)
  • func (p *Pool) RemoveSession(sid [32]byte)
  • func (p *Pool) RemoveSpentPRs(txs []*wire.MsgTx)
  • func (p *Pool) RemoveUnresponsiveDuringEpoch(prs []*wire.MsgMixPairReq, epoch uint64)
• type Received
• type RuleError
  • func (e *RuleError) Error() string
  • func (e *RuleError) Unwrap() error
• type UtxoEntry
• type UtxoFetcher

Variables

var (
	// ErrChangeDust is returned by AcceptMessage if a pair request's
	// change amount is dust.
	ErrChangeDust = newBannableError("change output is dust", 0)

	// ErrLowInput is returned by AcceptMessage when not enough input value
	// is provided by a pair request to cover the mixed output, any change
	// output, and the minimum required fee.
	ErrLowInput = newBannableError("not enough input value, or too low fee", 0)

	// ErrInvalidMessageCount is returned by AcceptMessage if a
	// pair request contains an invalid message count.
	ErrInvalidMessageCount = newBannableError("message count must be positive", 0)

	// ErrInvalidScript is returned by AcceptMessage if a pair request
	// contains an invalid script.
	ErrInvalidScript = newBannableError("invalid script", 0)

	// ErrInvalidSessionID is returned by AcceptMessage if the message
	// contains an invalid session id.
	ErrInvalidSessionID = newBannableError("invalid session ID", 0)

	// ErrInvalidSignature is returned by AcceptMessage if the message is
	// not properly signed for the claimed identity.
	ErrInvalidSignature = newBannableError("invalid message signature", 0)

	// ErrInvalidTotalMixAmount is returned by AcceptMessage if a pair
	// request contains the product of the message count and mix amount
	// that exceeds the total input value.
	ErrInvalidTotalMixAmount = newBannableError("invalid total mix amount", 0)

	// ErrInvalidUTXOProof is returned by AcceptMessage if a pair request
	// fails to prove ownership of each utxo.
	ErrInvalidUTXOProof = newBannableError("invalid UTXO ownership proof", wire.SFNodeNetwork)

	// ErrMissingUTXOs is returned by AcceptMessage if a pair request
	// message does not reference any previous UTXOs.
	ErrMissingUTXOs = newBannableError("pair request contains no UTXOs", 0)

	// ErrPeerPositionOutOfBounds is returned by AcceptMessage if the
	// position of a peer's own PR is outside of the possible bounds of
	// the previously seen messages.
	ErrPeerPositionOutOfBounds = newBannableError("peer position cannot be a valid seen PRs index", 0)
)

Bannable errors wrapped by RuleError.

var (
	// ErrSecretsRevealed is returned by Receive if any peer has
	// unexpectedly revealed their secrets during a run stage
	// (Received.RSs field is nil).  This requires all other peers to quit
	// the run, reveal their secrets, and perform blame assignment.
	ErrSecretsRevealed = errors.New("secrets revealed by peer")
)

Functions

func IsBannable

func IsBannable(err error, services wire.ServiceFlag) bool

IsBannable returns whether the error condition is such that the peer with capabilities defined by services who sent the message should be immediately banned for malicious or buggy behavior.

func UseLogger

func UseLogger(logger slog.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 slog.

Types

type BlockChain

type BlockChain interface {
	// ChainParams identifies which chain parameters the mixing pool is
	// associated with.
	ChainParams() *chaincfg.Params

	// CurrentTip returns the hash and height of the current tip block.
	CurrentTip() (chainhash.Hash, int64)
}

BlockChain queries the current status of the blockchain. Its methods should be able to be implemented by both full nodes and SPV wallets.

type MissingOwnPRError

type MissingOwnPRError struct {
	MissingPR chainhash.Hash
}

MissingOwnPRError represents the error condition where a key exchange message cannot be accepted to the mixpool due to it not referencing the owner's own pair request. The KE is recorded as an orphan and may be processed later. The error contains all unknown PR hashes so they can be fetched from another instance.

func (*MissingOwnPRError) Error

func (e *MissingOwnPRError) Error() string

type Pool

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

Pool records in-memory mix messages that have been broadcast over the peer-to-peer network.

func NewPool

func NewPool(blockchain BlockChain) *Pool

NewPool returns a new mixing pool that accepts and validates mixing messages required for distributed transaction mixing.

func (*Pool) AcceptMessage

func (p *Pool) AcceptMessage(msg mixing.Message) (accepted []mixing.Message, err error)

AcceptMessage accepts a mixing message to the pool.

Messages must contain the mixing participant's identity and contain a valid signature committing to all non-signature fields.

PR messages will not be accepted if they reference an unknown UTXO or if not enough fee is contributed. Any other message will not be accepted if it references previous messages that are not recorded by the pool.

All newly accepted messages, including any orphan key exchange messages that were processed after processing missing pair requests, are returned.

func (*Pool) CompatiblePRs

func (p *Pool) CompatiblePRs(pairing []byte) []*wire.MsgMixPairReq

CompatiblePRs returns all MixPR messages with pairing descriptions matching the parameter. The order is unspecified.

func (*Pool) Epoch

func (p *Pool) Epoch() time.Duration

Epoch returns the duration between mix epochs.

func (*Pool) ExpireMessages

func (p *Pool) ExpireMessages(height uint32)

ExpireMessages immediately expires all pair requests and sessions built from them that indicate expiry at or after a block height.

func (*Pool) ExpireMessagesInBackground

func (p *Pool) ExpireMessagesInBackground(height uint32)

ExpireMessagesInBackground will, after the current epoch period ends, remove all pair requests that indicate an expiry at or before the height parameter and removes all messages that chain back to a removed pair request.

If a previous call is still waiting in the background to remove messages, this method has no effect, and proper usage to avoid a mixpool memory leak requires it to be consistently called as more blocks are processed.

func (*Pool) HaveMessage

func (p *Pool) HaveMessage(query *chainhash.Hash) bool

HaveMessage checks whether the mixing pool contains a message by its hash.

func (*Pool) Message

func (p *Pool) Message(query *chainhash.Hash) (mixing.Message, error)

Message searches the mixing pool for a message by its hash.

func (*Pool) MixPRs

func (p *Pool) MixPRs() []*wire.MsgMixPairReq

MixPRs returns all MixPR messages.

Any expired PRs that are still internally tracked by the mixpool for ongoing sessions are excluded from the result set.

func (*Pool) Receive

func (p *Pool) Receive(ctx context.Context, r *Received) error

Receive returns messages matching a session and message type, waiting until all described messages have been received, or earlier with the messages received so far if the context is cancelled before this point.

Receive only returns results for the session ID in the r parameter. If no such session has any messages currently accepted in the mixpool, the method immediately errors.

If r.RSs is nil and any secrets messages are received for the described session, Receive will count these messages towards the total number of expected messages based on the slice capacities (without overcounting if the identity has also sent an expected non-RS message) and will return ErrSecretsRevealed. An additional call to Receive with a non-nil RSs can be used to receive all of the secrets after each peer publishes their own revealed secrets.

func (*Pool) ReceiveKEsByPairing

func (p *Pool) ReceiveKEsByPairing(pairing []byte, epoch uint64) []*wire.MsgMixKeyExchange

ReceiveKEsByPairing returns the most recently received run-0 KE messages by a peer that reference PRs of a particular pairing and epoch.

func (*Pool) RecentMessage

func (p *Pool) RecentMessage(query *chainhash.Hash) (mixing.Message, bool)

RecentMessages attempts to find a message by its hash in both the mixing pool that contains accepted messages as well as the cache of recently removed messages.

func (*Pool) RemoveConfirmedMixes

func (p *Pool) RemoveConfirmedMixes(txHashes []chainhash.Hash)

RemoveConfirmedMixes removes sessions and messages belonging to a completed session that resulted in published or mined transactions. Transaction hashes not associated with a session are ignored. PRs from the successful mix session are removed from the pool.

func (*Pool) RemoveConfirmedSessions

func (p *Pool) RemoveConfirmedSessions()

RemoveConfirmedSessions removes all messages including pair requests from runs which ended in each peer sending a confirm mix message.

func (*Pool) RemoveMessage

func (p *Pool) RemoveMessage(msg mixing.Message)

RemoveMessage removes a message that was rejected by the network.

func (*Pool) RemoveSession

func (p *Pool) RemoveSession(sid [32]byte)

RemoveSession removes the PRs and all session messages involving them from a completed session. PR messages of a successful session are also removed.

func (*Pool) RemoveSpentPRs

func (p *Pool) RemoveSpentPRs(txs []*wire.MsgTx)

RemoveSpentPRs removes all pair requests that are spent by any transaction input.

func (*Pool) RemoveUnresponsiveDuringEpoch

func (p *Pool) RemoveUnresponsiveDuringEpoch(prs []*wire.MsgMixPairReq, epoch uint64)

RemoveUnresponsiveDuringEpoch removes pair requests of unresponsive peers that did not provide any key exchange messages during the epoch in which a mix occurred.

type Received

type Received struct {
	Sid [32]byte
	KEs []*wire.MsgMixKeyExchange
	CTs []*wire.MsgMixCiphertexts
	SRs []*wire.MsgMixSlotReserve
	DCs []*wire.MsgMixDCNet
	CMs []*wire.MsgMixConfirm
	FPs []*wire.MsgMixFactoredPoly
	RSs []*wire.MsgMixSecrets
}

Received is a parameter for Pool.Receive describing the session to receive messages for, and slices for returning results. A single non-nil slice with capacity of the expected number of messages is required and indicates which message slice will be will be appended to. Received messages are unsorted.

type RuleError

type RuleError struct {
	Err error
}

RuleError represents a mixpool rule violation.

Some RuleErrors should be treated as an automatic bannable offense. Use IsBannable to test for this condition.

func (*RuleError) Error

func (e *RuleError) Error() string

func (*RuleError) Unwrap

func (e *RuleError) Unwrap() error

type UtxoEntry

type UtxoEntry interface {
	IsSpent() bool
	PkScript() []byte
	ScriptVersion() uint16
	BlockHeight() int64
	Amount() int64
}

UtxoEntry provides details regarding unspent transaction outputs.

type UtxoFetcher

type UtxoFetcher interface {
	// FetchUtxoEntry defines the function to use to fetch unspent
	// transaction output information.
	FetchUtxoEntry(wire.OutPoint) (UtxoEntry, error)
}

UtxoFetcher defines methods used to validate unspent transaction outputs in the pair request message. It is optional, but should be implemented by full nodes that have this capability to detect and stop relay of spam and junk messages.