ParallelChain F Protocol Types

ParallelChain F Protocol Types (pchain_types) defines data structures and serialization formats prescribed by the ParallelChain F Blockchain Protocol. These definitions help Web Applications, light clients, and differing implementations of 'Node' software developed by different groups communicate with each other and exhibit correct, protocol-specified semantics and behavior.

Table of Contents

• Design Characteristics
• Specification of Encoding Formats
  • Block Header
  • Block Data
  • Transaction
  • Transaction Event
  • Transaction Receipt
  • Transaction Receipt Status Code
  • Transaction CallData
  • Merkle Proof
  • State Proof
  • Unpadded Base64URL
  • More general types

Design Characteristics

ParallelChain F Protocol Types is designed with three desired properties in mind:

1. Obvious determinism.
2. Compact encoding.
3. Fast, parallelizable serialization and deserialization.

Determinism refers to the uniqueness of resulting bytes serialized from a data structure. Same data should be able to be serialized to one and only one series of bytes. Determinism is essential for Blockchain systems, since a single off-place byte totally changes cryptographic hashes and signatures produced over the data, making them much more difficult to verify. Additionally, this 'predictability' in the encoding allow serializer implementations to make more assumptions about the data, and possibly use memory allocation or parallel-processing tricks to speed up serialization and deserialization.

General-purpose serialization protocols (e.g. Protocol Buffers) do not require, nor guarantee determinism. Therefore, we do not rely on third parity serialization protocol.

Message format (e.g. definition of a block) is well-known, consistent and unchanged all over the time. Hence, extra information to describe the message format itself is not required, allowing for more compact messages.

Given the above design considerations, we achieve the characteristics by enforcing the data to be strictly sized. In case of requiring variable length of data, we specify the length of the data beforehand, which is similar to the data pattern of TLV.

A few features shared by all data types defined by ParallelChain F Protocol Types are:

1. Data type consists of only unsigned integers and vector of bytes
2. Maximum size of the block should be less than 4GB (we use u32 as data type to define size, length, offset)
3. Little endian integer

Specification of Encoding Formats

Block Header

Block Data

Transaction

Transaction Receipt

Transaction Receipt Status Code

Categorization Receipt Status Code

• 1x - Pre-Inclusion Decision failures. Not included in blocks.
• 2x - Deploy errors.
• 3x - EtoC errors (not in internal transaction)
• 4x - Internal transaction errors

Transaction Event

Transaction CallData

Transaction CallData is used to select the Action or View method to be called in an EtoC transaction on a contract written using the ParallelChain F Smart Contract SDK and to provide the selected method with its arguments.

Merkle Proof

Note: MerkleProof message definition is compatible to crate rs_merkle. After deserializing to rust struct, fields can be passed to the function verify.

// example 
let merkle_proof = MerkleProof::<Sha256>::try_from(proof)?;
let verify_result = merkle_proof.verify(root_hash, leaf_indices, leaf_hashes, total_leaves_count);

State Proof

Note: StateProofs message definition is compatible to crate trie-db.

// example 
verify_proof::<NoExtensionLayout, _, _, _>(&root_hash, &proof, items.iter())

Unpadded Base64URL

In some components of the ParallelChain F system, There is a need for a way to represent arbitrary byte sequences as UTF-8, url-safe strings. Two examples are: 1. The GET /account routes, where clients have to specify address of the account to GET from by including its address in the request URL, and 2. very-light, which stores keypairs in a JSON file (keypair.json).

The standard bytes-to-characters encoding that all ParallelChain F components use is Base64URL, as defined in IETF RFC 4648, without padding characters. protocol-types exports an alias of String, Base64URL, alongside two functions encode and decode to convert from bytes to Base64URL and the other way around.

Generalizations

Protocol Types supports serialization on data types in rust such as Vec, Option, and tuple, where the generic type T that used can be u8, Vec<u8> or the mentioned message definitions.

Vector of T (Rust: Vec)

Optional Field (Rust: Option)

2-Tuple