Show / Hide Table of Contents

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 sealed 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

| Improve this Doc View Source

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.

| Improve this Doc View Source

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

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.

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

| Improve this Doc View Source

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>
| Improve this Doc View Source

BytesLength

The bytes length in its serialized format.

Declaration
public int BytesLength { get; }
Property Value
Type Description
Int32
| Improve this Doc View Source

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.

Declaration
public BlockHash? GenesisHash { get; }
Property Value
Type Description
Nullable<BlockHash>
| Improve this Doc View Source

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
| Improve this Doc View Source

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
| Improve this Doc View Source

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
| Improve this Doc View Source

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.

| Improve this Doc View Source

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
| Improve this Doc View Source

Timestamp

The time this Transaction<T> is created and signed.

Declaration
public DateTimeOffset Timestamp { get; }
Property Value
Type Description
DateTimeOffset
| Improve this Doc View Source

UpdatedAddresses

Addresses whose states affected by Actions.

Declaration
public IImmutableSet<Address> UpdatedAddresses { get; }
Property Value
Type Description
IImmutableSet<Address>

Methods

| Improve this Doc View Source

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:

PropertyParameter the filled value derived from
SignerprivateKey
PublicKeyprivateKey
UpdatedAddressesactions 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.

| Improve this Doc View Source

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:

PropertyParameter the filled value derived from
SignerpublicKey
PublicKeypublicKey
UpdatedAddressesactions 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.

| Improve this Doc View Source

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.

InvalidTxPublicKeyException

Thrown when its Signer is not derived from its PublicKey.

See Also
Serialize(Boolean)
| Improve this Doc View Source

Equals(Transaction<T>)

Declaration
public bool Equals(Transaction<T> other)
Parameters
Type Name Description
Transaction<T> other
Returns
Type Description
Boolean
| Improve this Doc View Source

Equals(Object)

Declaration
public override bool Equals(object obj)
Parameters
Type Name Description
Object obj
Returns
Type Description
Boolean
| Improve this Doc View Source

GetHashCode()

Declaration
public override int GetHashCode()
Returns
Type Description
Int32
| Improve this Doc View Source

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>.

| Improve this Doc View Source

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>.

| Improve this Doc View Source

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.

InvalidTxPublicKeyException

Thrown when its Signer is not derived from its PublicKey.

See Also

IAction
PolymorphicAction<T>
  • Improve this Doc
  • View Source
In This Article
Back to top Copyright © 2018–2021 Planetarium