Class Transaction<T>

Consists of IAction and is signed to be included in a Block<T> and transmitted over the network.

Inheritance

Object

Transaction<T>

Namespace: Libplanet.Tx

Assembly: Libplanet.dll

Syntax

public class Transaction<T> : 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

Transaction(Bencodex.Types.Dictionary)

Creates a Transaction<T> instance from its serialization.

Declaration

public Transaction(Bencodex.Types.Dictionary dict)

Parameters

Type	Name	Description
Bencodex.Types.Dictionary	dict	The representation of Transaction<T> instance.

Transaction(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 InvalidTxPublicKeyException is thrown. This goes to the Signer property.
PublicKey	publicKey	A PublicKey of the account who signs this transaction. If this does not match to signer address InvalidTxPublicKeyException is thrown. This cannot be null. This goes to the PublicKey property.
IImmutableSet<Address>	updatedAddresses	Addresses whose states affected by actions. This goes to the UpdatedAddresses property.
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 null. This goes to the Actions property.
Byte[]	signature	A digital signature of the content of this Transaction<T>. This has to be signed by the account who corresponds to publicKey, or it will throw InvalidTxSignatureException. This is copied and then assigned to the Signature property.

Exceptions

Type	Condition
InvalidTxSignatureException	Thrown when its signature is invalid or not signed by the account who corresponds to publicKey.
InvalidTxPublicKeyException	Thrown when its signer is not derived from its publicKey.

Properties

Actions

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

TxId

Nonce

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 array of this transaction's signature. Changing a returned array does not affect the internal state of this Transaction<T> object.

Signer

A PublicKey of the account who signs this transaction. This is derived from the PublicKey.

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

Addresses whose states affected by Actions.

Declaration

public IImmutableSet<Address> UpdatedAddresses { get; }

Property Value

Type	Description
IImmutableSet<Address>

Methods

Create(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 = null)

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 null. This goes to the Actions property, and IActions are evaluated before a Transaction<T> is created in order to fill the UpdatedAddresses. See also Remarks section.
IImmutableSet<Address>	updatedAddresses	Addresses whose states affected by actions. These Addresses are also included in the UpdatedAddresses property, besides Addresses projected by evaluating actions. See also Remarks section.
Nullable<DateTimeOffset>	timestamp	The time this Transaction<T> is created and signed. This goes to the Timestamp property. If null (which is default) is passed this will be the current time.

Returns

Type	Description
Transaction<T>	A created new Transaction<T> signed by the given privateKey.

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

UnexpectedlyTerminatedActionException

Thrown when one of actions throws some exception during their rehearsal. This exception is thrown probably because the logic of some of the actions is not enough generic so that it can cover every case including “rehearsal mode.” The Rehearsal property also might be useful to make the IAction can deal with the case of rehearsal mode. The actual exception that an IAction threw is stored in its property.

Deserialize(Byte[])

Decodes a Transaction<T>'s Bencodex representation.

Declaration

public static Transaction<T> Deserialize(byte[] bytes)

Parameters

Type	Name	Description
Byte[]	bytes	A Bencodex representation of a Transaction<T>.

Returns

Type	Description
Transaction<T>	A decoded Transaction<T> object.

See Also

Serialize(Boolean)

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

EvaluateActions(HashDigest<SHA256>, Int64, IAccountStateDelta, Address, Boolean)

Executes the Actions and gets the result states.

Declaration

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 true if it is intended to be dry-run (i.e., the returned result will be never used). The default value is false.

Returns

Type	Description
IAccountStateDelta	The states immediately after Actions being executed. Note that it maintains UpdatedAddresses of the given previousStates as well.

Exceptions

Type	Condition
UnexpectedlyTerminatedActionException	Thrown when one of Actions throws some exception during rehearsal mode. The actual exception that an IAction threw is stored in its property. It is never thrown if the rehearsal option is false.

EvaluateActionsGradually(HashDigest<SHA256>, Int64, IAccountStateDelta, Address, Boolean)

Executes the Actions step by step, and emits ActionEvaluation for each step.

If the needed value is only the final states, use EvaluateActions(HashDigest<SHA256>, Int64, IAccountStateDelta, Address, Boolean) method instead.

Declaration

public IEnumerable<ActionEvaluation> 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 true if it is intended to be dry-run (i.e., the returned result will be never used). The default value is false.

Returns

Type	Description
IEnumerable<ActionEvaluation>	Enumerates ActionEvaluations 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
UnexpectedlyTerminatedActionException	Thrown when one of Actions throws some exception during rehearsal mode. The actual exception that an IAction threw is stored in its property. It is never thrown if the rehearsal option is false.

GetHashCode()

Declaration

public override int GetHashCode()

Returns

Type	Description
Int32

Serialize(Boolean)

Encodes this Transaction<T> into a array.

Declaration

public byte[] Serialize(bool sign)

Parameters

Type	Name	Description
Boolean	sign	Whether to include its Signature.

Returns

Type	Description
Byte[]	A Bencodex representation of this Transaction<T>.

ToBencodex(Boolean)

Encodes this Transaction<T> into a .

Declaration

public Bencodex.Types.Dictionary ToBencodex(bool sign)

Parameters

Type	Name	Description
Boolean	sign	Whether to include its Signature. Note that an encoding without signature cannot be decoded.

Returns

Type	Description
Bencodex.Types.Dictionary	A typed Bencodex representation of this Transaction<T>.

Validate()

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	Thrown when its Signer is not derived from its PublicKey.

See Also

IAction

PolymorphicAction<T>