Fields

• addTx ∷ AddTxOnBehalfOf → GenTx blk → m (MempoolAddTxResult blk)

  Add a single transaction to the mempool.

  The new transaction provided will be validated, in order, against the ledger state obtained by applying all the transactions already in the Mempool to it. Transactions which are found to be invalid, with respect to the ledger state, are dropped, whereas valid transactions are added to the mempool.

  Note that transactions that are invalid, with respect to the ledger state, will never be added to the mempool. However, it is possible that, at a given point in time, transactions which were once valid but are now invalid, with respect to the current ledger state, could exist within the mempool until they are revalidated and dropped from the mempool via a call to syncWithLedger or by the background thread that watches the ledger for changes.

  This action returns one of two results

  • A MempoolTxAdded value if the transaction provided was found to be valid. This transactions is now in the Mempool.
  • A MempoolTxRejected value if the transaction provided was found to be invalid, along with its accompanying validation errors. This transactions is not in the Mempool.

  Note that this is a blocking action. It will block until the transaction fits into the mempool. This includes transactions that turn out to be invalid: the action waits for there to be space for the transaction before it gets validated.

  Note that it is safe to use this from multiple threads concurrently.

  POSTCONDITION: > let prj = case > MempoolTxAdded vtx -> txForgetValidated vtx > MempoolTxRejected tx _err -> tx > processed <- addTx wti txs > prj processed == tx

  Note that previously valid transaction that are now invalid with respect to the current ledger state are dropped from the mempool, but are not part of the first returned list (nor the second).

  In principle it is possible that validation errors are transient; for example, it is possible that a transaction is rejected because one of its inputs is not yet available in the UTxO (the transaction it depends on is not yet in the chain, nor in the mempool). In practice however it is likely that rejected transactions will still be rejected later, and should just be dropped.

  It is important to note one important special case of transactions being "invalid": a transaction will also be considered invalid if that very same transaction is already included on the blockchain (after all, by definition that must mean its inputs have been used). Rejected transactions are therefore not necessarily a sign of malicious behaviour. Indeed, we would expect most transactions that are reported as invalid by tryAddTxs to be invalid precisely because they have already been included. Distinguishing between these two cases can be done in theory, but it is expensive unless we have an index of transaction hashes that have been included on the blockchain.

  As long as we keep the mempool entirely in-memory this could live in STM m; we keep it in m instead to leave open the possibility of persistence.

• removeTxs ∷ [GenTxId blk] → m ()

  Manually remove the given transactions from the mempool.

• syncWithLedger ∷ m (MempoolSnapshot blk)

  Sync the transactions in the mempool with the current ledger state of the ChainDB.

  The transactions that exist within the mempool will be revalidated against the current ledger state. Transactions which are found to be invalid with respect to the current ledger state, will be dropped from the mempool, whereas valid transactions will remain.

  We keep this in m instead of STM m to leave open the possibility of persistence. Additionally, this makes it possible to trace the removal of invalid transactions.

  n.b. in our current implementation, when one opens a mempool, we spawn a thread which performs this action whenever the ChainDB tip point changes.

• getSnapshot ∷ STM m (MempoolSnapshot blk)

  Get a snapshot of the current mempool state. This allows for further pure queries on the snapshot.

  This doesn't look at the ledger state at all.

• getSnapshotFor ∷ ForgeLedgerState blk → STM m (MempoolSnapshot blk)

  Get a snapshot of the mempool state that is valid with respect to the given ledger state

  This does not update the state of the mempool.

• getCapacity ∷ STM m MempoolCapacityBytes

  Get the mempool's capacity in bytes.

  Note that the capacity of the Mempool, unless it is overridden with MempoolCapacityBytesOverride, can dynamically change when the ledger state is updated: it will be set to twice the current ledger's maximum transaction capacity of a block.

  When the capacity happens to shrink at some point, we do not remove transactions from the Mempool to satisfy this new lower limit. Instead, we treat it the same way as a Mempool which is at capacity, i.e., we won't admit new transactions until some have been removed because they have become invalid.

• getTxSize ∷ GenTx blk → TxSizeInBytes

  Return the post-serialisation size in bytes of a GenTx.

Fields

• snapshotTxs ∷ [(Validated (GenTx blk), TicketNo)]

  Get all transactions (oldest to newest) in the mempool snapshot along with their ticket number.

• snapshotTxsAfter ∷ TicketNo → [(Validated (GenTx blk), TicketNo)]

  Get all transactions (oldest to newest) in the mempool snapshot, along with their ticket number, which are associated with a ticket number greater than the one provided.

• snapshotLookupTx ∷ TicketNo → Maybe (Validated (GenTx blk))

  Get a specific transaction from the mempool snapshot by its ticket number, if it exists.

• snapshotHasTx ∷ GenTxId blk → Bool

  Determine whether a specific transaction exists within the mempool snapshot.

• snapshotMempoolSize ∷ MempoolSize

  Get the size of the mempool snapshot.

• snapshotSlotNo ∷ SlotNo

  The block number of the "virtual block" under construction

• snapshotLedgerState ∷ TickedLedgerState blk

  The ledger state after all transactions in the snapshot