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>

Implements

ITxExcerpt

ITxMetadata

Namespace: Libplanet.Tx

Assembly: Libplanet.dll

Syntax

public sealed class Transaction<T> : IEquatable<Transaction<T>>, ITxExcerpt, ITxMetadata 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(ITxMetadata, IEnumerable<T>, Byte[])

Creates a new Transaction<T> instance by copying data from a specified transaction metadata.

Declaration

public Transaction(ITxMetadata metadata, IEnumerable<T> actions, byte[] signature)

Parameters

Type	Name	Description
ITxMetadata	metadata	The transaction metadata that contains data to copy.
IEnumerable<T>	actions	A list of IActions to include. 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 metadata's PublicKey. This is copied and then assigned to the Signature property.

Transaction(Int64, Address, PublicKey, Nullable<BlockHash>, 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, Nullable<BlockHash>, IEnumerable<T>, IImmutableSet<Address>, Nullable<DateTimeOffset>) is more useful.

Declaration

public Transaction(long nonce, Address signer, PublicKey publicKey, BlockHash? genesisHash, 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	Ignored. Left only for backward compatibility. It will be completely gone in the future. See also publicKey parameter's description.
PublicKey	publicKey	A PublicKey used for signing this transaction. This cannot be null. This goes to the PublicKey property, and Signer property is also derived from this value.
Nullable<BlockHash>	genesisHash	A HashDigest<T> value of the genesis which this Transaction<T> is made from. This can be null iff the transaction is contained in the genesis block.
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.

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>

GenesisHash

A HashDigest<T> value of the genesis which this transaction is made from. This can be null iff the transaction is contained in the genesis block.

Declaration

public BlockHash? GenesisHash { get; }

Property Value

Type	Description
Nullable<BlockHash>

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. This nonce is used for preventing replay attack.

Declaration

public long Nonce { get; }

Property Value

Type	Description
Int64

Remarks

Don't confuse this with Nonce for proof-of-work.

PublicKey

A PublicKey of the account who signs this transaction. 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 is created and signed.

Declaration

public DateTimeOffset Timestamp { get; }

Property Value

Type	Description
DateTimeOffset

UpdatedAddresses

An approximated list of addresses whose states would be affected by actions in this transaction. However, it could be wrong.

Declaration

public IImmutableSet<Address> UpdatedAddresses { get; }

Property Value

Type	Description
IImmutableSet<Address>

Methods

Create(Int64, PrivateKey, Nullable<BlockHash>, IEnumerable<T>, IImmutableSet<Address>, Nullable<DateTimeOffset>)

A façade factory to create a new Transaction<T>. Unlike the Transaction(Int64, Address, PublicKey, Nullable<BlockHash>, 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, BlockHash? genesisHash, 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.
Nullable<BlockHash>	genesisHash	A HashDigest<T> value of the genesis which this Transaction<T> is made from. This can be null iff the transaction is contained in the genesis block.
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.

CreateUnsigned(Int64, PublicKey, Nullable<BlockHash>, IEnumerable<T>, IImmutableSet<Address>, Nullable<DateTimeOffset>)

A façade factory to create a new Transaction<T>. Unlike the Transaction(Int64, Address, PublicKey, Nullable<BlockHash>, IImmutableSet<Address>, DateTimeOffset, IEnumerable<T>, Byte[]) constructor, it automatically fills the following values from:

Property	Parameter the filled value derived from
Signer	publicKey
PublicKey	publicKey
UpdatedAddresses	actions and updatedAddresses

Declaration

public static Transaction<T> CreateUnsigned(long nonce, PublicKey publicKey, BlockHash? genesisHash, 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.
PublicKey	publicKey	A PublicKey of the account who creates a new transaction. This key is used to fill the Signer and PublicKey properties, but this in itself is not included in the transaction.
Nullable<BlockHash>	genesisHash	A HashDigest<T> value of the genesis which this Transaction<T> is made from. This can be null iff the transaction is contained in the genesis block.
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. 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> unsigned.

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.

Deserialize(Byte[], Boolean)

Decodes a Transaction<T>'s Bencodex representation.

Declaration

public static Transaction<T> Deserialize(byte[] bytes, bool validate = true)

Parameters

Type	Name	Description
Byte[]	bytes	A Bencodex representation of a Transaction<T>.
Boolean	validate	Whether to validate the transaction.

Returns

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

Exceptions

Type	Condition
InvalidTxSignatureException	Thrown when its Signature is invalid or not signed by the account who corresponds to PublicKey.

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

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> and throws an appropriate exception if not valid.

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.

Implements

ITxExcerpt

ITxMetadata

See Also

IAction

PolymorphicAction<T>