Websocket

Websocket Interfaces

The WebSocket interface of Zetrix processes a variety of predefined message types, enabling real-time communication for tasks such as transaction submission, event subscription, and status updates. Each message type corresponds to a specific action or query within the Zetrix network protocol.

Message Type

enum ChainMessageType {
    CHAIN_TYPE_NONE = 0;
    CHAIN_HELLO = 10; // response with CHAIN_STATUS = 2;
    CHAIN_TX_STATUS = 11;
    CHAIN_PEER_ONLINE = 12;
    CHAIN_PEER_OFFLINE = 13;
    CHAIN_PEER_MESSAGE = 14;
    CHAIN_SUBMITTRANSACTION = 15;
    CHAIN_LEDGER_HGasDER = 16; //Zetrix notifies the client ledger(protocol::LedgerHeader) when closed
    CHAIN_SUBSCRIBE_TX = 17; //response with CHAIN_RESPONSE
    CHAIN_TX_ENV_STORE = 18;
}

Notification Message Registration

• Function

  The client uses this interface to register message types it wants to receive from the blockchain (note: this feature is currently unavailable). Additionally, this is the only interface through which the blockchain version information can be retrieved.

• Request Message Type

  CHAIN_HELLO

• Request Data Object

  message ChainHello {
    repeated ChainMessageType api_list = 1; //By default, enable all apis
    int64   timestamp = 2;
  }

• Request Parameter

  Parameter	Type	Description
  api_list	array	List of message types for applying for registration
  timestamp	int64	Application time

• Reponse Message Type

  CHAIN_HELLO

• Reponse Data Object

  message ChainStatus {
    string self_addr        = 1;
    int64 ledger_version    = 2;
    int64 monitor_version   = 3;
    string buchain_version      = 4;
    int64   timestamp       = 5;
  }

• Reponse Result

  Variable	Type	Description
  self_addr	string	Connected node address
  ledger_version	int64	Ledger version
  monitor_version	int64	Monitor version
  zetrix_version	string	Zetrix version
  timestamp	int64	Timestamp

Submit Transaction

• Function

  The transaction to be executed is sent to the blockchain using a specific WebSocket message type. For full details on how to format the transaction, refer to the Transaction Structure documentation.

• Request Message Type

  CHAIN_SUBMITTRANSACTION

• Request Message Object

  //　Signature
  message Signature {
    string public_key = 1;
    bytes sign_data = 2;
  }
  
  //　Request object
  message TransactionEnv {
    Transaction transaction = 1;
    repeated Signature signatures   = 2;
    Trigger trigger = 3;
  }

• Request Parameter

  Parameter	Type	Description
  transaction	Transaction	Details for transaction structure。
  public_key	string	The public key of transaction sender
  sign_data	bytes	Signature data obtained by signing transaction_blob

• Reponse Message Type

  • CHAIN_TX_STATUS：This returns the result of the transaction submission note that a successful submission only confirms receipt by the blockchain, not successful execution.

  • CHAIN_TX_ENV_STORE：Returns the result of the transaction execution.

• CHAIN_TX_STATUS Object

  message ChainTxStatus {
    enum TxStatus {
        UNDEFINED   = 0;
        CONFIRMED   = 1;    // web server will check tx parameters, signatures etc fist, noitfy CONFIRMED if pass
        PENDING     = 2;    // master will check futher before put it into pending queue
        COMPLETE    = 3;    // notify if Tx write ledger successfully
        FAILURE     = 4;    // notify once failed and set error_code
    };
  
    TxStatus    status = 1;
    string      tx_hash = 2;
    string      source_address = 3;
    int64       source_account_seq = 4;
    int64       ledger_seq = 5;         //on which block this tx records
    int64       new_account_seq = 6;        //new account sequence if COMPLETE
    ERRORCODE   error_code = 7;         //use it if FAIL
    string      error_desc = 8  ;           //error desc
    int64       timestamp = 9;          
  }

• ChainTxStatus Member

  Variable	Type	Description
  status	TxStatus	Transaction status.
  tx_hash	string	Transaction hash.
  source_address	string	Source account address of transaction sender.
  source_account_seq	int64	Transaction sequence of transaction sender.
  ledger_seq	int64	Height of the block where this transaction record is located.
  new_account_seq	int64	Block height when the transaction is completed.
  error_code	ERRORCODE	Error code
  error_desc	string	Error description
  timestamp	int64	Timestamp

• CHAIN_TX_ENV_STORE Object

  message TransactionEnvStore{
    TransactionEnv transaction_env = 1;
    int32 error_code = 2;
    string error_desc = 3;
    int64 ledger_seq = 4;
    int64 close_time = 5;
    //for notify
    bytes hash = 6;
    int64 actual_fee = 7;
    repeated bytes contract_tx_hashes = 8;
  }

• TransactionEnvStore Member

  Variable	Type	Description
  transaction_env	TransactionEnv	Submitted transaction content.
  error_code	int32	Error code.
  error_desc	string	Error description.
  ledger_seq	int64	Height of the block where this transaction record is located.
  close_time	int64	Transaction completion time.
  hash	bytes	Transaction hash.
  actual_fee	int64	Actual transaction fee, uint is UGas
  contract_tx_hashes	bytes	contract transaction hashes

Message Subscription

• Function

  This interface implements transaction notifications that only specify the account address of the interface.

• Request Message Type

  CHAIN_SUBSCRIBE_TX

• Request Data Object

  message ChainSubscribeTx{
    repeated string address = 1;
  }

• Request Parameter

  Parameter	Type	Description
  address	Transaction	Account address for subscription

• Reponse Message Type

  ChainResponse

• Reponse Data Object

  message ChainResponse{
        int32 error_code = 1;
        string error_desc = 2;
  }

• Reponse Result

  Variable	Type	Description
  error_code	int32	Error code
  error_desc	string	Error description

Transaction structure

• In protobuf format

  message Transaction {
      enum Limit{
          UNKNOWN = 0;
          OPERATIONS = 1000;
      };
      string source_address = 1;
      int64 nonce = 2;
      int64  fee_limit = 3;
      int64  gas_price =4;
      int64 ceil_ledger_seq = 5;
      bytes metadata = 6;
      repeated Operation operations = 7;
      int64 chain_id = 8;
  }

• Keywords in protobuf

  Keyword	Type	Description
  source_address	string	Source Account: The address of the transaction initiator. Upon successful transaction execution, the account's nonce will automatically increase by 1, representing the total number of transactions completed by that account.
  nonce	int64	The nonce must equal the current nonce of the source account plus 1, ensuring each transaction is unique and preventing replay attacks. To check an account's nonce, use the getAccount HTTP interface. If the nonce is not shown in the response, the account’s current nonce is considered 0.
  fee_limit	int64	Fee Limit: The maximum fee the transaction is allowed to consume. If the transaction succeeds, only the actual cost is charged. If it fails, the full fee limit is deducted. Unit: UGas (1 Gas = 10⁸ UGas).
  gas_price	int64	Gas Price: Determines the handling fee per operation and contributes to the transaction's byte fee. Unit: UGas (1 Gas = 10⁸ UGas).
  ceil_ledger_seq	int64	Optional: Sets a block height limit for when the transaction can be included. This is an advanced feature for controlling transaction validity.
  operations	array	Operation List: Represents the core actions the transaction intends to perform. Refer to Operations Structure for detailed specifications.
  metadata	bytes	Optional: A user-defined field that can be left empty or used to include a custom note.

Operations structure

The corresponding operations in the protobuf structure of the transaction can contain one or more operations.

• In protobuf format

  message Operation {
      enum Type {
          UNKNOWN = 0;
          CREATE_ACCOUNT          = 1;
          ISSUE_ASSET             = 2;
          PAY_ASSET               = 3;
          SET_METADATA            = 4;
          SET_SIGNER_WEIGHT       = 5;
          SET_THRESHOLD           = 6;
          PAY_COIN                = 7;
          LOG                     = 8;
          SET_PRIVILEGE           = 9;
      };
      Type type = 1;
      string source_address = 2;
      bytes metadata  = 3;
  
      OperationCreateAccount      create_account     = 4;
      OperationIssueAsset         issue_asset        = 5;
      OperationPayAsset           pay_asset          = 6;
      OperationSetMetadata        set_metadata       = 7;
      OperationSetSignerWeight    set_signer_weight  = 8;
      OperationSetThreshold       set_threshold      = 9;
      OperationPayCoin            pay_coin           = 10;
      OperationLog                log                = 11;
      OperationSetPrivilege       set_privilege      = 12;
  }

• Keyword in protobuf

  Keyword	Type	Description
  type	Type	Operation Code: Specifies the type of operation to be executed. Each code corresponds to a distinct function. See Operation Codes for more details.
  source_address	string	Optional: Indicates the operation's source account (the operator). If not specified, it defaults to the transaction's source account.
  metadata	bytes	Optional: A custom field for user input, which can be left blank or used to add a note.
  create_account	OperationCreateAccount	Creating accounts operation
  issue_asset	OperationIssueAsset	Issuing assets operation
  pay_asset	OperationPayAsset	Transferring assets operation
  set_metadata	OperationSetMetadata	Setting metadata operation
  pay_coin	OperationPayCoin	Transferring gas assets operation
  log	OperationLog	Recording logs operation
  set_privilege	OperationSetPrivilege	Setting privileges operation

Operation Codes

Operation Code	Description
1	Creating Accounts
2	Issuing Assets
3	Transferring Assets
4	Setting Metadata
7	Transferring Gas Assets
8	Recording Logs
9	Setting Privileges

Creating Accounts

The source account creates a new account on the blockchain. Creating Accounts are divided into Creating Normal Accounts and Creating Contract Accounts.

Protobuf format as follow:

// Key-Value pair
message KeyPair{
    string key = 1;
    string value = 2;
    int64 version = 3;
}

// Privilege
message Signer {
    enum Limit{
        SIGNER_NONE = 0;
        SIGNER = 100;
    };
    string address = 1;
    int64 weight = 2;
}
message OperationTypeThreshold{
    Operation.Type type = 1;
    int64 threshold = 2;
}
message AccountThreshold{
    int64 tx_threshold = 1; //required, [-1,MAX(INT64)] -1: indicates no setting
    repeated OperationTypeThreshold type_thresholds = 2;
}
message AccountPrivilege {
    int64 master_weight = 1;
    repeated Signer signers = 2;
    AccountThreshold thresholds = 3;
}

// Contract
message Contract{
    enum ContractType{
        JAVASCRIPT = 0;
    }
    ContractType type = 1;
    string payload = 2;
}

//　Create Account Operation
message OperationCreateAccount{
    string dest_address = 1;
    Contract contract = 2;
    AccountPrivilege priv = 3;
    repeated KeyPair metadatas = 4; 
    int64   init_balance = 5;
    string  init_input = 6;
}

Creating Normal Accounts

Note: Both master_weight and tx_threshold must be 1 in the current operation. And only the following keywords are allowed to be initialized.

• Keyword in protobuf

  Keyword	Type	Description
  dest_address	string	Address of the target account. When creating a normal account, it cannot be empty
  init_balance	int64	Initial Gas value of the target account, in UGas, 1 Gas = 10^8 UGas
  master_weight	int64	Master weight of the target account, which ranges [0, MAX(UINT32)]
  tx_threshold	int64	The threshold for initiating a transaction below which the transaction cannot be initiated, which ranges ​​[0, MAX(INT64)]

• Query

  The account information is queried through the getAccount interface in HTTP.

Creating Contract Accounts

Note: In the current operation, master_weight must be 0 and tx_threshold must be 1. And only the following keywords are allowed to be initialized

• Keyword in protobuf

  Keyword	Type	Description
  payload	string	Contract code
  init_balance	int64	Initial Gas value of the target account, in UGas, 1 Gas = 10^8 UGas
  init_input	string	Optional: Provides input parameters for the init function in the contract code during contract creation.
  master_weight	int64	Master weight of the target account
  tx_threshold	int64	The threshold for initiating a transaction below which it is not possible to initiate a transaction.

• Query

  • The account information is queried through the getAccount interface in HTTP.

  • Query with the getTransactionHistory interface in HTTP, and the result is as follows:

    [
        {
            "contract_address": "ztxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV", //The contract account
            "operation_index": 0                                        //The operation index value in the transaction array, 0 means the first transaction
        }
    ]

Issuing Assets

• Function

  The source account in this operation issues a digital asset. Upon successful execution, the asset is added to the source account’s asset balance.

• In protobuf format

  message OperationIssueAsset{
      string code = 1;
      int64 amount = 2;
  }

• Keyword in protobuf

  Keyword	Type	Description
  code	string	Code of the asset to be issued, which ranges [1, 64]
  amount	int64	Amount of the asset to be issued, which ranges (0, MAX(int64))

Transferring Assets

Note: If the target account is a contract account, the current operation triggers the contract execution of the target account.

• Function

  The source account of this operation transfers an asset to the target account.

• In protobuf format

  message AssetKey{
       string issuer = 1;
       string code = 2;
       int32 type = 3;
  }
  message Asset{
       AssetKey   key = 1;
       int64      amount = 2;
  }
  
  //　Pay asset operation
  message OperationPayAsset{
      string dest_address = 1;
      Asset asset = 2;
      string input = 3;
  }

• Keyword in protobuf

  Keyword	Type	Description
  dest_address	string	Address of the target account
  issuer	string	Address of the issuer
  code	string	Asset code which ranges [1, 64]
  amount	int64	The amount of the asset which ranges (0,MAX(int64))
  input	string	Optional: If the target account is a contract, the input is passed as an argument to the main function of the contract code. This setting is ignored for normal accounts.

Setting Metadata

• Function

  The source account of this operation modifies or adds metadata to the metadata table.

• In protobuf format

  message OperationSetMetadata{
      string  key = 1;  
      string  value = 2;
      int64   version = 3;
      bool    delete_flag = 4;
  }

• Keyword in protobuf

  Keyword	Type	Description
  key	string	Keyword of metadata, which ranges (0, 1024].
  value	string	Content of metadata, which ranges [0, 256K].
  version	int64	Optional: Metadata version number, default is 0. 0: No version restriction >0: Must match this specific version <0: Invalid value
  delete_flag	bool	Whether to delete the metadata.

Setting Privileges

• Function

  Set the weights that the signer has and set the thresholds required for each operation. For details, see Assignment of Control Rights in HTTP.

• In protobuf format

  message Signer {
      enum Limit{
          SIGNER_NONE = 0;
          SIGNER = 100;
      };
      string address = 1;
      int64 weight = 2;
  }
  message OperationTypeThreshold{
      Operation.Type type = 1;
      int64 threshold = 2;
  }
  
  //　Set privilege object
  message OperationSetPrivilege{
      string master_weight = 1;
      repeated Signer signers = 2;
      string tx_threshold = 3;
      repeated OperationTypeThreshold type_thresholds = 4;
  }

• Keywords in protobuf

  Keyword	Type	Description
  master_weight	string	Optional: Defaults to "", representing the account’s master weight. "": No change "0": Set master weight to 0 "1" to "MAX(UINT32)": Assign specified weight Others: Invalid input
  signers	array	Optional: A list of signers required for the operation. Defaults to an empty object, which means no signers are configured.
  address	string	Signer Address: The address of the signer to be configured, which must comply with Zetrix’s address verification rules.
  weight	int64	Optional: Defaults to 0. 0: Removes the signer (0, MAX(UINT32)]: Sets the signer's weight Others: Invalid input
  tx_threshold	string	Optional: Defaults to "", indicating the minimum privilege (tx_threshold) for the account. "": Do not modify "0": Set tx_threshold to 0 "1" to "MAX(INT64)": Set specified weight Others: Invalid input
  type_thresholds	array	Optional: A list of required thresholds for different operations. Defaults to an empty object, meaning no thresholds are configured.
  type	int	Indicates a specific operation type within the valid range of (0, 100].
  threshold	int64	Optional: Defaults to 0. 0: Removes the specified operation type (0, MAX(INT64)]: Sets the weight for the operation Other values: Invalid input

Transferring Gas Assets

Note: If the target account is a contract account, this operation will trigger the execution of the contract code within that account.

• Function

  Two functions:

  1. The source account of this operation transfers a Gas asset to the target account.

  2. The source account of this operation creates a new account on the blockchain.

• In protobuf format

  message OperationPayCoin{
      string dest_address = 1;
      int64 amount = 2;
      string input = 3;
  }

• protobufKeyword

  Keyword	Type	Description
  dest_address	string	Receiver account
  amount	array	Optional: A list of signers required for the operation. Defaults to an empty object, meaning no signers are specified.
  input	string	Optional: If the target is a contract account, the input is passed to the main function of the contract code. This setting is ignored for normal accounts.

Recording Logs

• Function

  The source account of this operation writes the log to the blockchain.

• In protobuf format

  message OperationLog{
      string topic = 1;
      repeated string datas = 2;
  }

• protobufKeyword

  Keyword	Type	Description
  topic	string	The log topic and parameter length must fall within the range (0, 128].
  datas	array	Log Content: Each element must have a length within the range (0, 1024].

Error Codes

The error code is composed of two parts:

• error_code : Error code, approximate error classification

• error_desc : Error Description, which can accurately find the error specific information from the error description

The error list is as follows:

Error code	Name	Description
0	ERRCODE_SUCCESS	Successful operation
1	ERRCODE_INTERNAL_ERROR	Inner service defect
2	ERRCODE_INVALID_PARAMETER	Parameters error
3	ERRCODE_ALRDY_EXIST	Objects already exist, such as repeated transactions submitted
4	ERRCODE_NOT_EXIST	Objects do not exist, such as null account, transactions and blocks etc
5	ERRCODE_TX_TIMEOUT	Transactions expired. It means the transaction has been removed from the buffer, but it still has probability to be executed
7	ERRCODE_MATH_OVERFLOW	Math calculation is overflown
20	ERRCODE_EXPR_CONDITION_RESULT_FALSE	The expression returns false. It means the TX failed to be executed currently, but it still has probability to be executed in the following blocks
21	ERRCODE_EXPR_CONDITION_SYNTAX_ERROR	The syntax of the expression returns is false. It means that the TX must fail
90	ERRCODE_INVALID_PUBKEY	Invalid public key
91	ERRCODE_INVALID_PRIKEY	Invalid private key
92	ERRCODE_ASSET_INVALID	Invalid assets
93	ERRCODE_INVALID_SIGNATURE	The weight of the signature does not match the threshold of the operation
94	ERRCODE_INVALID_ADDRESS	Invalid address
97	ERRCODE_MISSING_OPERATIONS	Absent operation of TX
98	ERRCODE_TOO_MANY_OPERATIONS	Over 100 operations in a single transaction
99	ERRCODE_BAD_SEQUENCE	Invalid sequence or nonce of TX
100	ERRCODE_ACCOUNT_LOW_RESERVE	Low reserve in the account
101	ERRCODE_ACCOUNT_SOURCEDEST_EQUAL	Sender and receiver accounts are the same
102	ERRCODE_ACCOUNT_DEST_EXIST	The target account already exists
103	ERRCODE_ACCOUNT_NOT_EXIST	Accounts do not exist
104	ERRCODE_ACCOUNT_ASSET_LOW_RESERVE	Low reserve in the account
105	ERRCODE_ACCOUNT_ASSET_AMOUNT_TOO_LARGE	Amount of assets exceeds the limitation ( int64 )
106	ERRCODE_ACCOUNT_INIT_LOW_RESERVE	Insufficient initial reserve for account creation
111	ERRCODE_FEE_NOT_ENOUGH	Low transaction fee
114	ERRCODE_OUT_OF_TXCACHE	TX buffer is full
120	ERRCODE_WEIGHT_NOT_VALID	Invalid weight
121	ERRCODE_THRESHOLD_NOT_VALID	Invalid threshold
144	ERRCODE_INVALID_DATAVERSION	Invalid data version of metadata
146	ERRCODE_TX_SIZE_TOO_BIG	TX exceeds upper limitation
151	ERRCODE_CONTRACT_EXECUTE_FAIL	Failure in contract execution
152	ERRCODE_CONTRACT_SYNTAX_ERROR	Failure in syntax analysis
153	ERRCODE_CONTRACT_TOO_MANY_RECURSION	The depth of contract recursion exceeds upper limitation
154	ERRCODE_CONTRACT_TOO_MANY_TRANSACTIONS	the TX submitted from the contract exceeds upper limitation
155	ERRCODE_CONTRACT_EXECUTE_EXPIRED	Contract expired
160	ERRCODE_TX_INSERT_QUEUE_FAIL	Failed to insert the TX into buffer