☁️
Zus Docs
  • About Züs
  • System
    • Providers and Services
      • Miner
      • Sharder
      • Blobber
      • Validator
      • Authorizer
      • Node Locator (0DNS)
    • Storage
      • Architecture and Data Management
      • Protocol
        • Allocations
        • Reference Objects
        • Challenges
        • Write Markers
          • Chain Hashing
          • Two Commit
        • Blobber Repair Protocol
      • ZS3 Server
        • Backup, Recovery and Replication
        • Encryption and Compression
        • S3FS Setup and Usage
        • Backup & Recovery with Restic on Blimp + ZS3 Server
        • Backup & Recovery with Veeam on Blimp + ZS3 Server
      • File Operations
        • Upload
        • Download
        • File Sharing
        • Partial Error Recovery
        • Streaming
        • Rent a Blobber
    • Smart Contracts
      • Storage S.C.
      • Miner S.C.
      • ZCN S.C.
      • ERC-20 S.C.s
      • Bridge Protocol
    • Blockchain & Consensus
      • Entities
    • User Authentication and Wallet Management System
      • OKTA Integration
      • Key Management System (KMS)
  • APIs
    • 0DNS API
    • JS API
    • Mobile API
  • CLIs
    • Storage CLI
      • Quickstart
      • Configuring the tool
    • Wallet CLI
      • Wallet Configuration
      • Quickstart
      • Configuring the tool
  • SDKs
    • Go SDK
      • GO SDK Microservices
    • JS SDK
  • Tokenomics
    • Staking
    • Reward & Penalty
  • ✨Züs Apps
    • 🗝️Vult
      • Getting Started
        • Web
        • Mobile
      • Vult AI
        • Batch Processing
        • Memory Retention
        • Technical Implementation
        • Architecture Overview
      • Login / Register
      • File Management Pages
      • File Sharing
      • Storage Management Dashboard
      • Storage Maintenance and Troubleshooting
      • Züs Subscription
      • Wallet Management
      • Refer a friend
      • Settings
    • 🏗️Blimp
      • Getting Started
      • Login / Register
      • Configure Storage
        • Create Standard Storage Allocation
        • Create Enterprise Allocation
        • Create S3 Server Allocation
        • Create Cloud Migration Allocation
        • Allocation Maintenance and Troubleshooting
      • File Management Pages
      • File Sharing
      • Manage Allocations
      • Upgrade Storage
      • Blimp Vault
      • Refer a friend
      • Settings
      • Launching ZS3 Server
      • Using CLI to backup files into Blimp + ZS3 Server
    • 🏠Chimney
      • Getting Started
      • Login / Register
      • Create New Deployment
      • Manage Your Deployments
      • Homepage
      • Staking Dashboard
      • Rank Dashboard
      • Monitor Dashboard
      • Stats Dashboard
      • Logs Dashboard
      • Wallet Dashboard
      • Operations on your Deployments
      • Restricted Blobbers
      • Settings
        • Manage Profile
        • Wallet Settings
        • Update Blobber Settings
        • Update Blobber Version
        • Refer a friend
        • Help
    • 🌐Atlus
      • Getting Started
      • Home page
      • Service Providers Page
      • Charts Page
        • Market Charts
        • Network Charts
        • Storage Charts
      • Blockchain Page
      • Server Map Page
      • Storage Explainer Page
      • Details Pages
        • Block Details Page
        • Transaction Details Page
        • Wallet Details Page
        • Miner Details Page
        • Sharder Details Page
        • Blobber Details Page
        • Validator Details Page
        • Authorizer Details Page
        • Allocation Details Page
      • Appendix: Common Components
    • ⚡Bolt
      • Getting Started
        • Web
        • Mobile
      • Login / Register
      • Sign In with external wallet
      • Staking Dashboard
      • Staking/Unstaking a provider
      • Claiming Rewards
      • Send/Receive ZCN tokens
      • Buy ZCN
      • Deposit/Withdraw ZCN tokens
      • Activity Dashboard
      • Refer a friend
      • Settings
  • Releases
    • Hardfork
Powered by GitBook
On this page
  • The Block Entity
  • Transaction
  • Transaction Confirmation
  • Magic Block
  1. System
  2. Blockchain & Consensus

Entities

The Züs blockchain is structured around key entities that ensure the secure and efficient execution of transactions, state updates, and consensus.

These entities form the foundation of the decentralized storage network, enabling users to interact with the blockchain through transactions while ensuring data integrity, security, and verifiability.

This section provides an overview of the essential blockchain entities, including:

  • Block Entity: Represents a summary of a finalized block, including its hash, miner information, round details, and cryptographic proofs.

  • Transaction Entity: Defines how clients interact with smart contracts and other network participants, encapsulating key details such as sender, recipient, transaction type, and cryptographic signatures.

  • Transaction Confirmation: Validates transaction finality by linking transactions to blocks and providing proof of execution.

  • Magic Block: Governs network-wide changes by defining the active set of miners and sharders, ensuring continuity and security across view changes.

The Block Entity

Block entity represents the summary of a block from the blockchain.

type BlockSummary struct {
	Version 	      string `json:"version" msgpack:"_v"`
	CreationDate 	      common.Timestamp `json:"creation_date"`
	Hash                  string        `json:"hash"`
	MinerID               datastore.Key `json:"miner_id"`
	Round                 int64         `json:"round"`
	RoundRandomSeed       int64         `json:"round_random_seed"`
	StateChangesCount     int           `json:"state_changes_count"`
	MerkleTreeRoot        string        `json:"merkle_tree_root"`
	ClientStateHash       util.Key      `json:"state_hash"`
	ReceiptMerkleTreeRoot string        `json:"receipt_merkle_tree_root"`
	NumTxns               int           `json:"num_txns"`
	*MagicBlock           `json:"maigc_block,omitempty" msgpack:"mb,omitempty"`
}
Field
Description

version

Version of the block. Latest is "1.0".

creation_date

Time when the block is created.

hash

Hash of the block, which represents a SHA256 hash represented in hex string for all the fields of the block concatenated together and separated with :.

miner_id

The ID of the miner generated the block.

round

Round when the block was generated.

round_random_seed

Seed number used to generate random numbers.

state_changes_count

Count of changes applied on the MPT state.

merkle_tree_root

Current root of the MPT computed from the transactions contained inside the block.

state_hash

Hex hash of the root of the MPT.

receipt_merkle_tree_root

The root of an MPT computed from the transactions of the block.

num_txns

Number of the transactions in the block.

magic_block

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

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

miner_id

ID of the miner generated the block contained this transaction.

round

Round when the block contained this transaction was generated.

transaction_status

round_random_seed

Random seed of the round contained this txn.

state_changes_count

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.

Magic Block

Magic Block is an entity that contains meta information and configuration of the blockchain. It's changed during the view change process where it defines the new Active Set (set of miners/sharders contributing to the generation of the blocks in the blockchain) and the new hyper-parameter of the view change process (T, K, N).

type MagicBlock struct {
	Hash 		       string		   `json:"hash"`
	PreviousMagicBlockHash string              `json:"previous_hash"`
	MagicBlockNumber       int64               `json:"magic_block_number"`
	StartingRound          int64               `json:"starting_round"`
	Miners                 *node.Pool          `json:"miners"`
	Sharders               *node.Pool          `json:"sharders"`
	ShareOrSigns           *GroupSharesOrSigns `json:"share_or_signs"`
	Mpks                   *Mpks               `json:"mpks"`
	T                      int                 `json:"t"`
	K                      int                 `json:"k"`
	N                      int                 `json:"n"`
}

Field
Description

Hash

SHA256 Hash of the magic block fields concatenated with each other, in Hexadecimal format.

PreviousMagicBlockHash

The hash of the magic block previous to this magic block.

MagicBlockNumber

The order of this magic block.

StartingRound

Round where this magic block started to be used.

Miners

The set of the miners used in generating the blocks.

Sharders

The set of the sharders used in generating the blocks.

ShareOrSigns

Shares and signs are pieces of information used to build the active set during the phases of the view change process.

Mpks

Set of Miner Public Keys.

T

Threshold of signatures to verify a signature.

K

The threshold of signatures needed for the view change to be successful.

N

The maximum number of miners, n.

PreviousBlockchain & ConsensusNextUser Authentication and Wallet Management System

Last updated 1 month ago

entity used while generating the block.

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 .

entity of the transaction related to this confirmation.

Status of the transaction. Same as in .

Count of change in state associated with the block. Explained in .

Magic Block
Block Entity
Transaction
Transaction Entity
Sharder API