The Transaction Entities

Entities related to the transactions

Transaction

Transaction represents the format of communication between the clients and the smart contracts, securely and atomically, to execute an operation on their data. It also represents the unit of work and state change in the blockchain, and the main contents of the blocks. Transactions play an important role in any blockchain, by and large.

A transaction in the Züs Network consists of the following:

type Transaction struct {
	// Hash of the transaction, SHA256 of the fields of the transaction, concatenated
	// together and represented in HEX format. It's calculated automatically so no need to
	// be provided in the response body for the endpoints using this entity.
	//
	// required: false
	Hash 		string 		`json:"hash"`
	
	// Version of the transaction. Useful to differentiate between recent transactions and old ones.
	// When a change occur in the schema of the transactions and deployed to the mainnet, we need to 
	// sure that the old transactions are still replayable. That's why we use versioning here
	// along with Hard Forking in the smartcontract code.
	//
	// required: true
	// default: "1.0"
	Version 	string 		`json:"version"`
	
	// ClientID of the client issuing the transaction
	//
	// required: true
	ClientID  string `json:"client_id"`

	// Public key of the client issuing the transaction
	//
	// required: true
	PublicKey string `json:"public_key,omitempty"`

	// ToClientID - the client id of the recipient, the other party in the transaction. It can be a client id or the address of a smart contract
	//
	// required: true
	ToClientID      string           `json:"to_client_id,omitempty"`

	// ChainID - the chain id of the transaction
	//
	// required: true
	ChainID         string           `json:"chain_id,omitempty"`

	// TransactionData - the data associated with the transaction
	//
	// required: true
	TransactionData string           `json:"transaction_data"`

	// Value - a numeric value associated with this transaction. Its role is determined by the smart contract function
	//
	// required: true
	Value           currency.Coin    `json:"transaction_value"`

	// Signature - Issuer signature of the transaction
	//
	// required: true
	Signature       string           `json:"signature"`
	
	// CreationDate - the time when the transaction was created
	//
	// required: true
	CreationDate    common.Timestamp `json:"creation_date"`

	// Fee - the fee associated with the transaction
	//
	// required: true
	Fee             currency.Coin    `json:"transaction_fee"`
	
	// Nonce - the nonce associated with the transaction
	//
	// required: true
	Nonce           int64            `json:"transaction_nonce"`

	// TransactionType - the type of the transaction. 
	//	Possible values are:
	//		- 0: TxnTypeSend - A transaction to send tokens to another account, state is maintained by account.
	//		- 10: TxnTypeData - A transaction to just store a piece of data on the block chain.
	//		- 1000: TxnTypeSmartContract - A smart contract transaction type.
	// required: true
	TransactionType   int    `json:"transaction_type"`

	// TransactionOutput - the output of the transaction
	//
	// required: true
	TransactionOutput string `json:"transaction_output,omitempty"`

	// OutputHash - the hash of the transaction output
	//
	// required: true
	OutputHash        string `json:"txn_output_hash"`

	// Status - the status of the transaction.
	//
	// TxnSuccess = 1 - Indicates the transaction is successful in updating the state or smart contract
	// TxnError   = 2 - Indicates a transaction has errors during execution
	// TxnFail    = 3 - Indicates a transaction has failed to update the state or smart contract
	//
	// required: true
	Status            int    `json:"transaction_status"`
}

Transaction Confirmation

After the transaction is selected in a block and the block is finalized, the sharder fires an event to add transaction confirmation, which is then added to the EventDB. For a client to make sure their transaction was successful, or to check the error in case of failure, they need to query the confirmation from the Sharder API.

type Confirmation struct {
	Version           string       `json:"version"`
	Hash              string       `json:"hash"`
	BlockHash         string       `json:"block_hash"`
	PreviousBlockHash string       `json:"previous_block_hash"`
	Transaction       *Transaction `json:"txn,omitempty"`
	datastore.CreationDateField
	MinerID               datastore.Key `json:"miner_id"`
	Round                 int64         `json:"round"`
	Status                int           `json:"transaction_status"`
	
	// low level fields
	RoundRandomSeed       int64         `json:"round_random_seed"`
	StateChangesCount     int           `json:"state_changes_count"`
	MerkleTreeRoot        string        `json:"merkle_tree_root"`
	MerkleTreePath        *util.MTPath  `json:"merkle_tree_path"`
	ReceiptMerkleTreeRoot string        `json:"receipt_merkle_tree_root"`
	ReceiptMerkleTreePath *util.MTPath  `json:"receipt_merkle_tree_path"`
}

Field	Description
version	Default is "1.0". Reflects the used version of the schema.
hash	Hash of the transaction, acts as a unique identifier.
block_hash	Hash of the block, acts as a unique identifier.
previous_block_hash	Hash of the previous block, acts as a unique identifier.
txn	Transaction entity of the transaction related to this confirmation.
miner_id	ID of the miner generated the block contained this transaction.
round	Round when the block contained this transaction was generated.
transaction_status	Status of the transaction. Same as in Transaction Entity.
round_random_seed	Random seed of the round contained this txn.
state_changes_count	Count of change in state associated with the block. Explained in Block Entity.
merkle_tree_root	Current root of the merkle tree computed from the transactions contained inside the block.
merkle_tree_path	Path of the hash of the transaction in merkle tree of txns.
receipt_merkle_tree_root	The root of a merkle tree computed from the transaction hashes of the block.
receipt_merkle_tree_path	Path of the hash of the transaction in the merkle tree of txn receipts.