/
IStagePolicy.cs
105 lines (98 loc) · 5.02 KB
/
IStagePolicy.cs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
using System.Collections.Generic;
using Libplanet.Action;
using Libplanet.Tx;
namespace Libplanet.Blockchain.Policies
{
/// <summary>
/// An interface to configure a <see cref="BlockChain{T}"/>'s strategy to deal with staged
/// transactions.
/// </summary>
/// <typeparam name="T">An <see cref="IAction"/> type. It should match
/// the <see cref="BlockChain{T}"/>'s type parameter.</typeparam>
/// <remarks>
/// Every operation of an implementation of this <c>interface</c> must be thread-safe.
/// </remarks>
public interface IStagePolicy<T>
where T : IAction, new()
{
/// <summary>
/// Stages a <paramref name="transaction"/>.
/// </summary>
/// <param name="blockChain">The <see cref="BlockChain{T}"/> that the stage belongs to.
/// </param>
/// <param name="transaction">The <seealso cref="Transaction{T}"/> to be staged.</param>
/// <returns><c>true</c> if staging was successful, <c>false</c> otherwise.</returns>
/// <remarks>
/// <para>
/// This does not throw any exception regardless of whether <paramref name="transaction"/>
/// was successfully staged or not.
/// </para>
/// <para>
/// If the <see cref="Transaction{T}.Id"/> of <paramref name="transaction"/> is marked
/// as ignored, <paramref name="transaction"/> will not be staged.
/// </para>
/// </remarks>
public bool Stage(BlockChain<T> blockChain, Transaction<T> transaction);
/// <summary>
/// Unstages a transaction <paramref name="id"/>.
/// </summary>
/// <param name="blockChain">The <see cref="BlockChain{T}"/> that the stage belongs to.
/// </param>
/// <param name="id">The <seealso cref="Transaction{T}.Id"/> to unstage.</param>
/// <returns><c>true</c> if unstaging was successful, <c>false</c> otherwise.</returns>
/// <remarks>
/// This does not throw any exception regardless of whether <paramref name="id"/> was
/// successfully unstaged or not.
/// </remarks>
public bool Unstage(BlockChain<T> blockChain, TxId id);
/// <summary>
/// Marks given <paramref name="id"/> as ignored.
/// </summary>
/// <param name="blockChain">The <see cref="BlockChain{T}"/> that the stage belongs to.
/// </param>
/// <param name="id">The <see cref="Transaction{T}.Id"/> to ignore.</param>
/// <remarks>
/// If the <see cref="Transaction{T}"/> associated with <paramref name="id"/> is already
/// staged, this also unstages the <see cref="Transaction{T}"/>.
/// </remarks>
public void Ignore(BlockChain<T> blockChain, TxId id);
/// <summary>
/// Checks if given <paramref name="id"/> is marked as ignored.
/// </summary>
/// <param name="blockChain">The <see cref="BlockChain{T}"/> that the stage belongs to.
/// </param>
/// <param name="id">The <see cref="Transaction{T}.Id"/> to check.</param>
/// <returns><c>true</c> if <paramref name="id"/> is marked as ignored,
/// <c>false</c> otherwise.</returns>
public bool Ignores(BlockChain<T> blockChain, TxId id);
/// <summary>
/// Retrieves a staged <see cref="Transaction{T}"/> by its <paramref name="id"/>.
/// </summary>
/// <param name="blockChain">The <see cref="BlockChain{T}"/> that the stage belongs to.
/// </param>
/// <param name="id">The <see cref="Transaction{T}.Id"/> to get.</param>
/// <param name="filtered">Whether to filter masked staged <see cref="Transaction{T}"/>s
/// or not. Set to <c>true</c> by default.</param>
/// <returns>The staged <see cref="Transaction{T}"/> associated with <paramref name="id"/>
/// if found, <c>null</c> otherwise.</returns>
public Transaction<T>? Get(BlockChain<T> blockChain, TxId id, bool filtered = true);
/// <summary>
/// Enumerates all staged <see cref="Transaction{T}"/>s.
/// </summary>
/// <param name="blockChain">The <see cref="BlockChain{T}"/> that the stage belongs to.
/// </param>
/// <param name="filtered">Whether to filter masked staged <see cref="Transaction{T}"/>s
/// or not. Set to <c>true</c> by default.</param>
/// <returns>All staged transactions. No ordering is guaranteed.</returns>
public IEnumerable<Transaction<T>> Iterate(BlockChain<T> blockChain, bool filtered = true);
/// <summary>
/// Calculates the next nonce according for given <paramref name="address"/>.
/// </summary>
/// <param name="blockChain">The <see cref="BlockChain{T}"/> that the stage belongs to.
/// </param>
/// <param name="address">The <see cref="Address"/> to calculate the next nonce for.
/// </param>
/// <returns>The next appropriate nonce for <paramref name="address"/>.</returns>
public long GetNextTxNonce(BlockChain<T> blockChain, Address address);
}
}