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> customActions, byte[] signature)

Parameters

Type	Name	Description
ITxMetadata	metadata	The transaction metadata that contains data to copy.
IEnumerable<T>	customActions	A list of user-defined custom actions to include. This can be empty, but cannot be null. This goes to the CustomActions 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(ITxMetadata, IAction, Byte[])

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

Declaration

public Transaction(ITxMetadata metadata, IAction systemAction, byte[] signature)

Parameters

Type	Name	Description
ITxMetadata	metadata	The transaction metadata that contains data to copy.
IAction	systemAction	A system built-in action to include. This cannot be null, and goes to the SystemAction 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 is more useful.

Declaration

public Transaction(long nonce, Address signer, PublicKey publicKey, BlockHash? genesisHash, IImmutableSet<Address> updatedAddresses, DateTimeOffset timestamp, IEnumerable<T> customActions, 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 customActions. 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>	customActions	A list of user-defined custom actions to include. This can be empty, but cannot be null. This goes to the CustomActions 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<IAction> Actions { get; }

Property Value

Type	Description
IImmutableList<IAction>

Remarks

This property is deprecated. Use CustomActions or SystemAction instead.

CustomActions

Zero or more user-defined custom actions that this Transaction<T> contains. These are executed in the order.

Declaration

public IImmutableList<T>? CustomActions { get; }

Property Value

Type	Description
Nullable<IImmutableList<T>>

Remarks

This property is mutually exclusive with SystemAction; either one of them must be null and the other must not be null.

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.

Remarks

Although this cannot be null, it can be an empty array if the transaction is not signed yet.

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

SystemAction

A system action (if any) that this Transaction<T> contains.

Declaration

public IAction SystemAction { get; }

Property Value

Type	Description
IAction

Remarks

This property is mutually exclusive with CustomActions; either one of them must be null and the other must not be null.

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>, Nullable<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	customActions 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> customActions, 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>	customActions	A list of user-defined custom actions to include. This can be empty, but cannot be null. This goes to the CustomActions property, and these actionss are evaluated before a Transaction<T> is created in order to fill the UpdatedAddresses. See also Remarks section.
Nullable<IImmutableSet<Address>>	updatedAddresses	Addresses whose states affected by customActions. These Addresses are also included in the UpdatedAddresses property, besides Addresses projected by evaluating customActions. 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 customActions (we call it “rehearsal mode”), but remember that its result is approximated in some degree, because the result of customActions 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 customActions 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.

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

Almost same as Create(Int64, PrivateKey, Nullable<BlockHash>, IEnumerable<T>, Nullable<IImmutableSet<Address>>, Nullable<DateTimeOffset>) except that this factory method takes a systemAction instead of user-defined custom actions.

Declaration

public static Transaction<T> Create(long nonce, PrivateKey privateKey, BlockHash? genesisHash, IAction systemAction, IImmutableSet<Address>? updatedAddresses = null, DateTimeOffset? timestamp = null)

Parameters

Type	Name	Description
Int64	nonce	Specifies Nonce.
PrivateKey	privateKey	Derives PublicKey, Signer, and Signature from this.
Nullable<BlockHash>	genesisHash	Specifies GenesisHash.
IAction	systemAction	Specifies SystemAction.
Nullable<IImmutableSet<Address>>	updatedAddresses	Specifies UpdatedAddresses. The resulting Transaction<T> may contain more UpdatedAddresses than this argument.
Nullable<DateTimeOffset>	timestamp	Specifies Timestamp.

Returns

Type	Description
Transaction<T>	A created signed Transaction<T>.

CreateUnsigned(Int64, PublicKey, Nullable<BlockHash>, IEnumerable<T>, Nullable<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	customActions and updatedAddresses

Declaration

public static Transaction<T> CreateUnsigned(long nonce, PublicKey publicKey, BlockHash? genesisHash, IEnumerable<T> customActions, 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>	customActions	A list of user-defined custom actions to include. This can be empty, but cannot be null. This goes to the CustomActions property, and these actionss are evaluated before a Transaction<T> is created in order to fill the UpdatedAddresses. See also Remarks section.
Nullable<IImmutableSet<Address>>	updatedAddresses	Addresses whose states affected by customActions. These Addresses are also included in the UpdatedAddresses property, besides Addresses projected by evaluating customActions. 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 customActions (we call it “rehearsal mode”), but remember that its result is approximated in some degree, because the result of customActions 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 customActions 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>, IAction, Nullable<IImmutableSet<Address>>, Nullable<DateTimeOffset>)

Almost same as CreateUnsigned(Int64, PublicKey, Nullable<BlockHash>, IEnumerable<T>, Nullable<IImmutableSet<Address>>, Nullable<DateTimeOffset>) except that this factory method takes a systemAction instead of user-defined custom actions.

Declaration

public static Transaction<T> CreateUnsigned(long nonce, PublicKey publicKey, BlockHash? genesisHash, IAction systemAction, IImmutableSet<Address>? updatedAddresses = null, DateTimeOffset? timestamp = null)

Parameters

Type	Name	Description
Int64	nonce	Specifies Nonce.
PublicKey	publicKey	Specifies PublicKey.
Nullable<BlockHash>	genesisHash	Specifies GenesisHash.
IAction	systemAction	Specifies SystemAction.
Nullable<IImmutableSet<Address>>	updatedAddresses	Specifies UpdatedAddresses. The resulting Transaction<T> may contain more UpdatedAddresses than this argument.
Nullable<DateTimeOffset>	timestamp	Specifies Timestamp.

Returns

Type	Description
Transaction<T>	A created unsigned Transaction<T>.

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(Nullable<Object>)

Declaration

public override bool Equals(object? obj)

Parameters

Type	Name	Description
Nullable<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>