Documentation
¶
Overview ¶
Package sim performs transaction queue simulations based on abstract inputs.
The inputs to a sim are a transaction source (type TxSource) a block source (type BlockSource), and the mempool state (type []*Tx).
A transaction source emits transactions into the mempool queue, given a time interval (implying that the source is time-homogeneous). A block source models the discovery of blocks by miners, while the mempool state is the graph of mempool transactions.
Miners are assumed to include transactions greedily by fee rate, considering each transaction in isolation (i.e. no child-pays-for-parent), and subject to a minimum fee rate and a maximum block size, which is specified by the BlockPolicy object.
The output of a sim is a sequence of blocks that are each represented by their "stranding fee rate" (SFR), which is approximately the minimum fee rate required for a transaction to be included in that block. From the SFR sequence, we can obtain many of the queue metrics that are of interest.
Package sim also contains transaction / block source models (i.e. implementations of the TxSource and BlockSource interfaces). Model estimation is performed by package estimate.
Index ¶
Constants ¶
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BlockPolicy ¶
If a block won't include any txs regardless of fee, set MinFeeRate = MaxFeeRate.
type BlockSource ¶
type BlockSource interface {
Next() (t time.Duration, b BlockPolicy)
BlockRate() float64 // Blocks per second
// Return n copies of this source, which must have isolated random states.
// This is so that:
// 1. The source will be concurrent-safe.
// 2. The sources' randomness are not coupled; this allows tests to be
// made deterministic.
Copy(n int) []BlockSource
// Returns the cumulative capacity byte rate in bytes/s with
// respect to fee rate.
RateFn() MonotonicFn
MarshalJSON() ([]byte, error)
}
A simulation block source.
type CapRateFn ¶
type CapRateFn struct {
// contains filtered or unexported fields
}
func NewCapRateFn ¶
func (CapRateFn) Approx ¶
func (f CapRateFn) Approx(n int) MonotonicFn
func (CapRateFn) Inverse ¶
For a given y, what is the min fee rate x such that the cumulative caprate is >= y. If y >= max cap, return MaxFeeRate
func (CapRateFn) MarshalJSON ¶
type IndBlockSource ¶
type IndBlockSource struct {
// contains filtered or unexported fields
}
Implements BlockSource; models max block size and min fee rate as independent random variables. Not concurrent safe.
func NewIndBlockSource ¶
func NewIndBlockSource(minfeerates []FeeRate, maxblocksizes []TxSize, blockrate float64) *IndBlockSource
func (*IndBlockSource) BlockRate ¶
func (b *IndBlockSource) BlockRate() float64
func (*IndBlockSource) Copy ¶
func (b *IndBlockSource) Copy(n int) []BlockSource
func (*IndBlockSource) MarshalJSON ¶
func (b *IndBlockSource) MarshalJSON() ([]byte, error)
func (*IndBlockSource) Next ¶
func (b *IndBlockSource) Next() (t time.Duration, p BlockPolicy)
func (*IndBlockSource) RateFn ¶
func (b *IndBlockSource) RateFn() MonotonicFn
type MonotonicFn ¶
type MonotonicFn interface {
Eval(x float64) float64
Inverse(y float64) float64
Approx(n int) MonotonicFn
MarshalJSON() ([]byte, error)
}
MonotonicFn represents a (non-strict) monotonic function.
type MultiTxSource ¶
type MultiTxSource struct {
// contains filtered or unexported fields
}
The typical tx source: poisson arrivals with independent (feerate, size). Implements TxSource. Not concurrent-safe.
func NewMultiTxSource ¶
func NewMultiTxSource(feerates []FeeRate, sizes []TxSize, weights []float64, txrate float64) *MultiTxSource
txs and weights must be nonzero.
func (*MultiTxSource) Copy ¶
func (s *MultiTxSource) Copy(n int) []TxSource
func (*MultiTxSource) MarshalJSON ¶
func (s *MultiTxSource) MarshalJSON() ([]byte, error)
func (*MultiTxSource) MinSize ¶
func (s *MultiTxSource) MinSize() TxSize
func (*MultiTxSource) RateFn ¶
func (s *MultiTxSource) RateFn() MonotonicFn
type Sim ¶
type Sim struct {
// contains filtered or unexported fields
}
func NewSim ¶
func NewSim(txsource TxSource, blocksource BlockSource, initmempool []*Tx) *Sim
NewSim ... initmempool must be closed; i.e. SimMempoolTx Children must be contained in initmempool.
type TransientConfig ¶
type TransientSim ¶
type TransientSim struct {
// contains filtered or unexported fields
}
func NewTransientSim ¶
func NewTransientSim(s *Sim, cfg TransientConfig) *TransientSim
func (*TransientSim) Run ¶
func (ts *TransientSim) Run() <-chan []FeeRate
func (*TransientSim) Stop ¶
func (ts *TransientSim) Stop()
Stop (abort) the sim and block until all goroutines terminate.
type TxRateFn ¶
type TxRateFn struct {
// contains filtered or unexported fields
}
func NewTxRateFn ¶
func (TxRateFn) Approx ¶
func (f TxRateFn) Approx(n int) MonotonicFn
func (TxRateFn) Inverse ¶
For a given byterate y, what is the lowest fee rate x such that the total byterate of transactions with fee rate >= x is <= y.
func (TxRateFn) MarshalJSON ¶
type TxSource ¶
type TxSource interface {
Generate(t time.Duration) (txs []*Tx)
// Return n copies of this source, which must have isolated random states.
// This is so that:
// 1. The source will be concurrent-safe.
// 2. The sources' randomness are not coupled; this allows tests to be
// made deterministic.
Copy(n int) []TxSource
// Returns the minimum tx size that this source will generate.
// It's used to optimize Sim.
MinSize() TxSize
// Returns the reverse cumulative transaction byte rate in bytes/s with
// respect to fee rate.
RateFn() MonotonicFn
MarshalJSON() ([]byte, error)
}
A simulation tx source. For a given time interval t, Generate returns a slice of transactions generated in that interval. For example, if tx arrivals are modeled as a Poisson process, then len(txs) is Poisson distributed with expected value txrate*t.
t is typically an inter-block time and hence an exponential random variable. Since Generate is not a function of time, we are modeling the tx arrival process as homogeneous.
A null source is permitted (i.e. a source which always Generates length-zero txs. TODO: Add unmarshalers
type UniTxSource ¶
type UniTxSource struct {
// contains filtered or unexported fields
}
func NewUniTxSource ¶
func NewUniTxSource(feerates []FeeRate, sizes []TxSize, txrate float64) *UniTxSource
func (*UniTxSource) Copy ¶
func (s *UniTxSource) Copy(n int) []TxSource
func (*UniTxSource) MarshalJSON ¶
func (s *UniTxSource) MarshalJSON() ([]byte, error)
func (*UniTxSource) MinSize ¶
func (s *UniTxSource) MinSize() TxSize
func (*UniTxSource) RateFn ¶
func (s *UniTxSource) RateFn() MonotonicFn
Source Files