Class Transaction<T>
Inherited Members
Namespace: Libplanet.Tx
Assembly: Libplanet.dll
Syntax
public class Transaction<T> : ISerializable, IEquatable<Transaction<T>> where T : IAction, new()
Type Parameters
Name | Description |
---|---|
T | A class implementing IAction to include. Each game usually defines its own concrete class which implements IAction, and uses it for this type parameter. This type parameter is aligned with Block<T>'s and BlockChain<T>'s type parameters. |
Constructors
| Improve this Doc View SourceTransaction(Int64, Address, PublicKey, IImmutableSet<Address>, DateTimeOffset, IEnumerable<T>, Byte[])
Creates a new Transaction<T>.
This constructor takes all required and only required values for a Transaction<T>, so gives you full control of creating a Transaction<T>, and in other words, this constructor is only useful when all details of a Transaction<T> need to be manually adjusted. For the most cases, the façade factory Create(Int64, PrivateKey, IEnumerable<T>, IImmutableSet<Address>, Nullable<DateTimeOffset>) is more useful.
Declaration
public Transaction(long nonce, Address signer, PublicKey publicKey, IImmutableSet<Address> updatedAddresses, DateTimeOffset timestamp, IEnumerable<T> actions, byte[] signature)
Parameters
Type | Name | Description |
---|---|---|
Int64 | nonce | The number of previous Transaction<T>s committed by the Signer of this transaction. This goes to the Nonce property. |
Address | signer | An Address of the account
who signs this transaction. If this is not derived from |
PublicKey | publicKey | A PublicKey of the account
who signs this transaction. If this does not match to |
IImmutableSet<Address> | updatedAddresses | Addresses whose
states affected by |
DateTimeOffset | timestamp | The time this Transaction<T> is created and signed. This goes to the Timestamp property. |
IEnumerable<T> | actions | A list of IActions. This
can be empty, but cannot be |
Byte[] | signature | A digital signature of the content of
this Transaction<T>. This has to be signed by
the account who corresponds to |
Exceptions
Type | Condition |
---|---|
ArgumentNullException | Thrown when |
InvalidTxSignatureException | Thrown when its
|
InvalidTxPublicKeyException | Thrown when its
|
Properties
| Improve this Doc View SourceActions
A list of IActions. These are executed in the order.
This can be empty, but cannot be null
.
Declaration
public IImmutableList<T> Actions { get; }
Property Value
Type | Description |
---|---|
IImmutableList<T> |
Id
A unique identifier derived from this Transaction<T>'s content.
For more characteristics, see TxId type.
Declaration
public TxId Id { get; }
Property Value
Type | Description |
---|---|
TxId |
See Also
| Improve this Doc View SourceNonce
The number of previous Transaction<T>s committed by the Signer of this transaction.
Declaration
public long Nonce { get; }
Property Value
Type | Description |
---|---|
Int64 |
PublicKey
A PublicKey of the account who signs this
Transaction<T>.
The Signer address is always corresponding to this
for each transaction. This cannot be null
.
Declaration
public PublicKey PublicKey { get; }
Property Value
Type | Description |
---|---|
PublicKey |
Signature
A digital signature of the content of this
Transaction<T>. This is signed by the account
who corresponds to PublicKey.
This cannot be null
.
Declaration
public byte[] Signature { get; }
Property Value
Type | Description |
---|---|
Byte[] | A new Byte array of this transaction's signature. Changing a returned array does not affect the internal state of this Transaction<T> object. |
Signer
Declaration
public Address Signer { get; }
Property Value
Type | Description |
---|---|
Address |
Timestamp
The time this Transaction<T> is created and signed.
Declaration
public DateTimeOffset Timestamp { get; }
Property Value
Type | Description |
---|---|
DateTimeOffset |
UpdatedAddresses
Declaration
public IImmutableSet<Address> UpdatedAddresses { get; }
Property Value
Type | Description |
---|---|
IImmutableSet<Address> |
Methods
| Improve this Doc View SourceCreate(Int64, PrivateKey, IEnumerable<T>, IImmutableSet<Address>, Nullable<DateTimeOffset>)
A façade factory to create a new Transaction<T>. Unlike the Transaction(Int64, Address, PublicKey, IImmutableSet<Address>, DateTimeOffset, IEnumerable<T>, Byte[]) constructor, it automatically fills the following values from:
Property | Parameter the filled value derived from |
---|---|
Signer | privateKey |
PublicKey | privateKey |
UpdatedAddresses | actions and
updatedAddresses |
Note that the privateKey
in itself is not
included in the created Transaction<T>.
Declaration
public static Transaction<T> Create(long nonce, PrivateKey privateKey, IEnumerable<T> actions, IImmutableSet<Address> updatedAddresses = null, DateTimeOffset? timestamp = default(DateTimeOffset? ))
Parameters
Type | Name | Description |
---|---|---|
Int64 | nonce | The number of previous Transaction<T>s committed by the Signer of this transaction. This goes to the Nonce property. |
PrivateKey | privateKey | A PrivateKey of the account who creates and signs a new transaction. This key is used to fill the Signer, PublicKey, and Signature properties, but this in itself is not included in the transaction. |
IEnumerable<T> | actions | A list of IActions. This
can be empty, but cannot be |
IImmutableSet<Address> | updatedAddresses | Addresses whose
states affected by |
Nullable<DateTimeOffset> | timestamp | The time this Transaction<T>
is created and signed. This goes to the Timestamp
property. If |
Returns
Type | Description |
---|---|
Transaction<T> | A created new Transaction<T> signed by
the given |
Remarks
This factory method tries its best to fill the UpdatedAddresses property by actually evaluating
the given actions
(we call it “rehearsal
mode”), but remember that its result
is approximated in some degree, because the result of
actions
are not deterministic until
the Transaction<T> belongs to a Block<T>.
If an IAction depends on previous states or
some randomness to determine what Address to update,
the automatically filled UpdatedAddresses became
mismatched from the Addresses
actions
actually update after
a Block<T> is mined.
Although such case would be rare, a programmer could manually give
the updatedAddresses
parameter
the Addresses they predict to be updated.
If an IAction oversimplifies the assumption
about the Block<T> it belongs to,
runtime exceptions could be thrown from this factory method.
The best solution to that is not to oversimplify things,
there is an option to check IActionContext's
Rehearsal is true
and
a conditional logic for the case.
Exceptions
Type | Condition |
---|---|
ArgumentNullException | Thrown when |
UnexpectedlyTerminatedTxRehearsalException | Thrown when one of This exception is thrown probably because the logic of some of
the The actual exception that an IAction threw is stored in its InnerException property. |
Equals(Transaction<T>)
Declaration
public bool Equals(Transaction<T> other)
Parameters
Type | Name | Description |
---|---|---|
Transaction<T> | other |
Returns
Type | Description |
---|---|
Boolean |
Equals(Object)
Declaration
public override bool Equals(object obj)
Parameters
Type | Name | Description |
---|---|---|
Object | obj |
Returns
Type | Description |
---|---|
Boolean |
Overrides
| Improve this Doc View SourceEvaluateActions(HashDigest<SHA256>, Int64, IAccountStateDelta, Address, Boolean)
Executes the Actions and gets the result states.
Declaration
[Pure]
public IAccountStateDelta EvaluateActions(HashDigest<SHA256> blockHash, long blockIndex, IAccountStateDelta previousStates, Address minerAddress, bool rehearsal = false)
Parameters
Type | Name | Description |
---|---|---|
HashDigest<SHA256> | blockHash | The Hash of Block<T> that this Transaction<T> will belong to. |
Int64 | blockIndex | The Index of Block<T> that this Transaction<T> will belong to. |
IAccountStateDelta | previousStates | The states immediately before Actions being executed. Note that its UpdatedAddresses are remained to the returned next states. |
Address | minerAddress | An address of block miner. |
Boolean | rehearsal | Pass |
Returns
Type | Description |
---|---|
IAccountStateDelta | The states immediately after Actions
being executed. Note that it maintains
UpdatedAddresses of the given
|
Exceptions
Type | Condition |
---|---|
UnexpectedlyTerminatedTxRehearsalException | Thrown when one of Actions throws some
exception during |
EvaluateActionsGradually(HashDigest<SHA256>, Int64, IAccountStateDelta, Address, Boolean)
Executes the Actions step by step, and emits an action, input context, and output states for each step.
If the needed value is only the final states, use EvaluateActions(HashDigest<SHA256>, Int64, IAccountStateDelta, Address, Boolean) method instead.
Declaration
[Pure]
public IEnumerable<ActionEvaluation<T>> EvaluateActionsGradually(HashDigest<SHA256> blockHash, long blockIndex, IAccountStateDelta previousStates, Address minerAddress, bool rehearsal = false)
Parameters
Type | Name | Description |
---|---|---|
HashDigest<SHA256> | blockHash | The Hash of Block<T> that this Transaction<T> will belong to. |
Int64 | blockIndex | The Index of Block<T> that this Transaction<T> will belong to. |
IAccountStateDelta | previousStates | The states immediately before Actions being executed. Note that its UpdatedAddresses are remained to the returned next states. |
Address | minerAddress | An address of block miner. |
Boolean | rehearsal | Pass |
Returns
Type | Description |
---|---|
IEnumerable<ActionEvaluation<T>> | Enumerates an action, input context, and output states for each one in Actions. The order is the same to the Actions. Note that each Random object has a unconsumed state. |
Exceptions
Type | Condition |
---|---|
UnexpectedlyTerminatedTxRehearsalException | Thrown when one of Actions throws some
exception during |
FromBencodex(Byte[])
Decodes a transaction's Bencodex representation.
Declaration
public static Transaction<T> FromBencodex(byte[] bytes)
Parameters
Type | Name | Description |
---|---|---|
Byte[] | bytes | A Bencodex representation of a transaction. |
Returns
Type | Description |
---|---|
Transaction<T> | A decoded Transaction<T> object. |
See Also
| Improve this Doc View SourceGetHashCode()
Declaration
public override int GetHashCode()
Returns
Type | Description |
---|---|
Int32 |
Overrides
| Improve this Doc View SourceGetObjectData(SerializationInfo, StreamingContext)
Declaration
public void GetObjectData(SerializationInfo info, StreamingContext context)
Parameters
Type | Name | Description |
---|---|---|
SerializationInfo | info | |
StreamingContext | context |
ToBencodex(Boolean)
Encodes this Transaction<T> into a Byte array.
This is an inverse function of
FromBencodex(Byte[]) method
where sign
is true
.
Declaration
public byte[] ToBencodex(bool sign)
Parameters
Type | Name | Description |
---|---|---|
Boolean | sign | Whether to include its Signature. Note that an encoding without signature cannot be decoded using FromBencodex(Byte[]) method. |
Returns
Type | Description |
---|---|
Byte[] | A Bencodex representation of this Transaction<T>. |
See Also
| Improve this Doc View SourceValidate()
Validates this Transaction<T>. If there is something invalid it throws an exception. If valid it does nothing.
Declaration
public void Validate()
Exceptions
Type | Condition |
---|---|
InvalidTxSignatureException | Thrown when its Signature is invalid or not signed by the account who corresponds to its PublicKey. |
InvalidTxPublicKeyException |