This document describes in detail the process of generating Keypairs (public and private key pairs) and how to generate an address and sign a transaction based on keypairs. It introduces two interface methods and related processes for executing the transaction call. It provides reference information for ProtoBuf data structures. Finally, it illustrates two methods to submit transactions by showing how to generate transaction_blob with interface call and how to generate transaction_blob by yourself.
Schematic Diagram
The following diagram illustrates how the private, public keys and address are generated.
Generating Private Keys
Generating a private key requires multiple algorithms such as a random algorithm and SHA256. Generating a private key includes the following steps:
Generate a 256-bit random number (a private key in the mathematical sense) with a random algorithm and get a byte array, the raw private key, as shown below:
Add a 3-byte prefix and a 1-byte version number before the raw private key, and then add a 1-byte Fill after the raw private key to get a new byte array, as shown below:
After performing SHA256 calculation twice on the byte array obtained in Step 2,take the first 4 bytes of the operation result.
4 Bytes
This table illustrates the Prefix, Version, Fill and Checksum used in generating the private key.
Generating Public Keys
The public key can be generated with the ED25519 algorithm after the private key is generated. Generating a public key includes the following steps:
Generate a 32-bit byte array (raw public key) by processing the raw private key with the ED25519 algorithm. For example, the raw public key of the private key privbsGZFUoRv8aXZbSGd3bwzZWFn3L5QKq74RXAQYcmfXhhZ54CLr9z is shown below:
Note : For the Prefix, Version and Checksum, please refer to Table 2.
Perform SHA256 calculation twice on the byte array in Step 2. Take the first 4 bytes of the operation result as the byte array of the Checksum, as shown below:
[116,171,22,107]
Combine the byte array in Step 2 and the checksum byte array in Step 3 in order, resulting in a new byte array, as shown below:
After performing SHA256 calculation twice on the byte array obtained in step 2, take the first 4 bytes of the operation result
4 Bytes
This table illustrates the Prefix, Version and Checksum used in generating the public key.
Generating Addresses
The address can be further generated by an algorithm after generating the private key and the public key. Generating an address includes the following steps:
Generate a 32-bit byte array (raw public key) by processing the raw private key with the ED25519 algorithm. For example, the raw public key of the private key privbsGZFUoRv8aXZbSGd3bwzZWFn3L5QKq74RXAQYcmfXhhZ54CLr9z is shown below:
Note : For the Prefix, Version and Checksum, please refer to Table 3.
Perform SHA256 calculation twice on the byte array in Step 3. Take the first 4 bytes of the operation result as the byte array of the Checksum, as shown below:
[255,77,167,51]
Combine the byte array in Step 3 and the Checksum byte array in Step 4 in order, resulting in a new byte array, as shown below:
Encode the byte array generated in Step 5 with Base58, and get the string starting with adx, namely the address, as shown below:
ztxSixLyrba6UyVXVhUoT1wSA3nNzY5qrTift
Note : Now the address is generated.
Table 3
Name
Data
Length
Prefix
0xF0 0x26
2 Bytes
Version
0x01
1 Byte
PublicKey
Take the last 20bytes in raw public key
20 Bytes
Checksum
After performing SHA256 calculation twice on the byte array obtained in step 3, take the first 4 bytes of the operation result
4 Bytes
This table illustrates the Prefix, Version and Checksum used in generating the address.
Signing Transactions
Sign the pending transaction (the byte array obtained by the inverse hexadecimal encoding of the transaction_blob) with the ED25519 algorithm and the private key to get sign_data, the signature string.
The following example shows how to sign the transaction_blob with ED25519 and the private key.
After signing the pending transaction (the byte array obtained by the inverse hexadecimal encoding of the transaction_blob) with the signature interface of ED25519 and performing hexadecimal conversion, the resulting sign_data is:
There are two methods of calling the interface to execute transactions: Generating Transaction_blobs by Calling the Interface and Generating Transaction_blobs by Yourself.
Generating Transaction_blobs by Calling the Interface
Attention : As the transaction_blob is likely to be intercepted and tampered with, it is not recommended to generate transaction_blobs in this way.
If you need to call the interface to generate transaction_blobs, sign and submit transactions, please refer to the Serializing Transaction Data interface of http.
Calling the interface to generate a transaction_blob includes the following steps:
Call the getAccount interface to get the nonce value of the account that is to initiate a transaction. The code is shown below:
HTTP GET host:port/getAccount?address=accountAddress
Populate the json data as needed and complete filling the transaction data. The format is shown below:
{"source_address":"xxxxxxxxxxx",//The source transaction account, the originator of the transaction"nonce":2,//Nonce value"ceil_ledger_seq":0,//Optional"fee_limit":1000,//Fee paid in transaction"gas_price":1000,//Gas price (Not less than the configured value)"metadata":"0123456789abcdef",//Optional, metadata for the transaction given by users, in hexadecimal format"operations":[ {//Populate according to specific operations }, {//Populate according to specific operations } ...... ]}
Note : The nonce value needs to be incremented by 1 based on the value obtained in Step 1.
By calling the getTransactionBlob interface, the json data generated in Step 2 is passed as a parameter, and a transaction hash and a transaction_blob are obtained to implement transaction serialization. The format is shown below:
{"error_code":0,"error_desc":"","result": {"hash":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",//Transaction hash"transaction_blob":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"//The hexadecimal representation after the transaction is serialized }}
Sign the transaction and populate the transaction data. Sign the transaction_blob according to the previously generated private key, and then populate the json data of the submitted transaction. The format is shown below:
{"items": [{"transaction_blob":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",//The hexadecimal representation after the transaction is serialized"signatures": [{//The first signature"sign_data":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",//Signature data"public_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"//Public key }, {//The second signature"sign_data":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",//Signature data"public_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"//Public key }] }]}
By calling the submitTransaction interface, the json data generated in Step 4 is passed as a parameter, the response result is obtained and transaction submission is completed. The format of the response result is shown below:
Generating the transaction_blob by yourself, signing, and submitting the transaction include the following steps:
Call the getAccount interface to get the nonce value of the account that is to initiate a transaction. The code is shown below:
HTTP GET host:port/getAccount?address=accountAddress
Populate the transaction object Transaction of the protocol buffer and serialize it to get the transaction_blob. For details of the specific transaction data structure, please refer to ProtoBuf Data Structure.
Sign the transaction and populate the transaction data. Generate a public key based on the private key, sign the transaction_blob with the private key, and then populate the json data of the submitted transaction. The format is shown below:
{"items": [{"transaction_blob":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",//The hexadecimal representation after the transaction is serialized"signatures": [{//The first signature"sign_data":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",//Signature data"public_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"//Public key }, {//The second signature"sign_data":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",//Signature data"public_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"//Public key }] }]}
By calling the submitTransaction interface, the json data generated in Step 3 is passed as a parameter to complete the transaction submission. The response result format is shown below:
Protocol Buffer (ProtoBuf) is a lightweight and efficient structured data storage format that can be used for serializing structured data. It is ideal for data storage or RPC data exchange formats. It can be used in communication protocols, data storage and other fields of language-independent, platform-independent, scalable serialized structured data formats. Currently the APIs in C++, Java, and Python are available.
For more information aobut ProtoBuf, please refer to the protocol.
Now, we will introduce the data structure details of Protocol Buffer, and provide the file and simple test program for the protocol buffer of various languages generated by the script.
Data Structure
The following section describes the various ProtoBuf data structures that might be used in transactions and their uses for your reference.
Transaction
This data structure is for complete transactions.
message Transaction {enum Limit{ UNKNOWN =0; OPERATIONS =1000; };string source_address =1; // Account address of the transaction initiatorint64 nonce =2; // Transaction sequence numberint64 fee_limit =3; // The transaction fee, by default is 1000Gas; the unit is UGas, 1 Gas = 10^8 UGasint64 gas_price =4; // The packaging fee of transactions, by default is 1000; the unit is UGas,1 Gas = 10^8 UGasint64 ceil_ledger_seq =5; // Block boundbytes metadata =6; // Transaction metadatarepeatedOperation operations =7; // Operation list }
Operation
This data structure is for operations in transactions.
message Operation {enum Type { UNKNOWN =0; CRGasTE_ACCOUNT =1; ISSUE_ASSET =2; PAY_ASSE =3; SET_METADATA =4; SET_SIGNER_WEIGHT =5; SET_THRESHOLD =6; PAY_COIN =7; LOG =8; SET_PRIVILEGE =9; };Type type =1; // Operation typestring source_address =2; // Source account address for the operationbytes metadata =3; // Operation metadataOperationCreateAccount create_account =4; // Create an account operationOperationIssueAsset issue_asset =5; // Issue assets operationOperationPayAsset pay_asset =6; // Transfer assets operationOperationSetMetadata set_metadata =7; // Set metadataOperationSetSignerWeight set_signer_weight =8; // Set privilege for signerOperationSetThreshold set_threshold =9; // Set transaction thresholdOperationPayCoin pay_coin =10; // Transfer coinOperationLog log =11; // Record logOperationSetPrivilege set_privilege =12; // Set privilege }
This data structure is for setting account threshold.
message AccountThreshold{int64 tx_threshold =1; // Transaction thresholdrepeatedOperationTypeThreshold type_thresholds =2; // Specify the transaction threshold list for the operations. The threshold for the transactions with unspecified operation is set by tx_threshold. }
OperationTypeThreshold
This data structure is for operation threshold of specified types.
message OperationTypeThreshold{Operation.Type type =1; // Operation typeint64 threshold =2; // Corresponding threshold of this operation }
OperationIssueAsset
This data structure is for issuing assets.
message OperationIssueAsset{string code =1; // Asset encoding to be issuedint64 amount =2; // Asset amount to be issued }
This data structure is for identifying the uniqueness of asset.
message AssetKey{string issuer =1; // Account address of asset issuerstring code =2; // Asset encodingint32 type =3; // Asset type(by default is 0, which indicates the amount is not limited) }
OperationSetMetadata
This data structure is for setting Metadata.
message OperationSetMetadata{string key =1; // keyword, uniquestring value =2; // Contentint64 version =3; // Version control, optionalbool delete_flag =4; // Whether it is deletable }
message OperationSetThreshold{int64 tx_threshold =1; // Transaction thresholdrepeatedOperationTypeThreshold type_thresholds =2; // The transaction threshold list for specified operations. The threshold for the transactions with unspecified operation is set by tx_threshold }
This data structure is for setting account privilege.
message OperationSetPrivilege{string master_weight =1; // Account weightrepeatedSigner signers =2; // Signer weight liststring tx_threshold =3; // Transaction thresholdrepeatedOperationTypeThreshold type_thresholds =4; // The transaction threshold list for specified operations. The threshold for the transactions with unspecified operation is set by tx_threshold }
Examples for Transaction Submission
Scenario: Account A(ztxSrb2CPEcE7gK7AUPLorFW8sE3JTgrKX51z) creates account B(Generate an address by Generating Addresses in keypair).
Generating Transaction_blobs by Interface
Generating transaction_blobs by the interface includes the following steps:
Obtain the nonce value of the account to initiate a transaction by GET.
GET http://seed1-node.zetrix.com/getAccount?address=ztxSrb2CPEcE7gK7AUPLorFW8sE3JTgrKX51z
Response message:
{"error_code":0,"result": {"address":"ztxSrb2CPEcE7gK7AUPLorFW8sE3JTgrKX51z","assets": [ {"amount":1000000000,"key": {"code":"HNC","issuer":"ztxSZw4A3MYYNGSAejkbb7RuZvu5wd8GUTfUE" } } ],"assets_hash":"3bf279af496877a51303e91c36d42d64ba9d414de8c038719b842e6421a9dae0","balance":27034700,"metadatas":null,"metadatas_hash":"ad67d57ae19de8068dbcd47282146bd553fe9f684c57c8c114453863ee41abc3","nonce":5,"priv": {"master_weight":1,"thresholds": [{"tx_threshold":1 }] } }}address: Current query account address.assets: Account asset list.assets_hash: Asset list hash.balance: Account balance.metadata: Account metadata in hexadecimal format.metadatas_hash: Transaction metadata hash.nonce: The sending transaction serial number, the nonce+1 returned by querying the account information interface.priv: Privilege.master_weight: Current account weight.thresholds: Threshold.tx_threshold: Transaction default threshold.
Complete populating the transaction data.
The account address of account B generated by Generating Address in keypair is ztxSWs62LxjYERH3qo22QjGAw4hrjZNt9LaUG, the populated json data is shown below:
POST http://seed1-node.zetrix.com/submitTransaction
Response message:
{"results": [{"error_code":0,"error_desc":"","hash":"be4953bce94ecd5c5a19c7c4445d940c6a55fb56370f7f606e127776053b3b51" }],"success_count":1//1 represents that the submission succeeded.}
Generating Transaction_blobs by Yourself
Generating transaction_blobs by yourself (take Java as an example) includes the following steps:
Obtain the nonce value of the account that is to initiate a transaction by GET.
GET http://seed1-node.zetrix.com/getAccount?address=ztxSrb2CPEcE7gK7AUPLorFW8sE3JTgrKX51z
Response message:
{"error_code":0,"result": {"address":"ztxSrb2CPEcE7gK7AUPLorFW8sE3JTgrKX51z","assets": [ {"amount":1000000000,"key": {"code":"HNC","issuer":"ztxSZw4A3MYYNGSAejkbb7RuZvu5wd8GUTfUE" } } ],"assets_hash":"3bf279af496877a51303e91c36d42d64ba9d414de8c038719b842e6421a9dae0","balance":27034700,"metadatas":null,"metadatas_hash":"ad67d57ae19de8068dbcd47282146bd553fe9f684c57c8c114453863ee41abc3","nonce":5,"priv": {"master_weight":1,"thresholds": [{"tx_threshold":1 }] } }}address: Current query account address.assets: Account asset list.assets_hash: Asset list hash.balance: Account balance.metadata: Account metadata in hexadecimal format.metadatas_hash: Transaction metadata hash.nonce: The sending transaction serial number, the nonce+1 returned by querying the account information interface.priv: Privilege.master_weight: Current account weight.thresholds: Threshold.tx_threshold: Transaction default threshold.
Populate the transaction data structure and generate a transaction_blob.
POST http://seed1-node.zetrix.com/submitTransaction
Response message:
{"results": [{"error_code":0,"error_desc":"","hash":"be4953bce94ecd5c5a19c7c4445d940c6a55fb56370f7f606e127776053b3b51" }],"success_count":1//1 represents that the submission succeeded.}