- 
- 
- 
- 
- 
- 
-
-
-
-
-
-
-
-
-
|
+| TypeScript, JavaScript | [borsh-js](https://github.com/near/borsh-js) | |
+| Java, Kotlin, Scala, Clojure, etc | [borshj](https://github.com/near/borshj) | |
+| Python | [borsh-py](https://github.com/near/borsh-py) | Work-in-progress |
## Benchmarks
We measured the following benchmarks on objects that blockchain projects care about the most: blocks, block headers,
-transactions, accounts. We took object structure from the [nearprotocol](https://nearprotocol.com) blockchain.
+transactions, accounts. We took object structure from the [NEAR Protocol](https://near.org) blockchain.
We used [Criterion](https://bheisler.github.io/criterion.rs/book/index.html) for building the following graphs.
The benchmarks were run on Google Cloud [n1-standard-2 (2 vCPUs, 7.5 GB memory)](https://cloud.google.com/compute/docs/machine-types).
@@ -125,159 +65,150 @@ Block de-serialization speed vs block size in bytes:
See complete report [here](http://borsh.io/criterion/report/index.html).
## Specification
-In short, Borsh is a non self-describing binary serialization format. It is designed to serialize any objects to canonical and deterministic set of bytes.
-
-General principles:
-* integers are little endian;
-* sizes of dynamic containers are written before values as `u32`;
-* all unordered containers (hashmap/hashset) are ordered in lexicographic order by key (in tie breaker case on value);
-* structs are serialized in the order of fields in the struct;
-* enums are serialized with using `u8` for the enum ordinal and then storing data inside the enum value (if present).
-
-Formal specification:
-| Informal type | Rust EBNF * | Pseudocode |
| Integers | -integer_type: ["u8" | "u16" | "u32" | "u64" | "u128" | "i8" | "i16" | "i32" | "i64" | "i128" ] | -little_endian(x) | -
| Floats | -float_type: ["f32" | "f64" ] | -err_if_nan(x) little_endian(x as integer_type) |
-
| Unit | -unit_type: "()" | We do not write anything | -
| Fixed sized arrays | -array_type: '[' ident ';' literal ']' | -for el in x repr(el as ident) |
-
| Dynamic sized array | -vec_type: "Vec<" ident '>' | -repr(len() as u32) - for el in x - repr(el as ident) - |
-
| Struct | -struct_type: "struct" ident fields | repr(fields) | -
| Fields | -fields: [named_fields | unnamed_fields] | -- |
| Named fields | -named_fields: '{' ident_field0 ':' ident_type0 ',' ident_field1 ':' ident_type1 ',' ... '}' | -repr(ident_field0 as ident_type0) - repr(ident_field1 as ident_type1) - ... - |
-
| Unnamed fields | -unnamed_fields: '(' ident_type0 ',' ident_type1 ',' ... ')' | repr(x.0 as type0) repr(x.1 as type1) ... |
-
| Enum | -enum: 'enum' ident '{' variant0 ',' variant1 ',' ... '}' - variant: ident [ fields ] ? - |
- Suppose X is the number of the variant that the enum takes. - repr(X as u8) - repr(x.X as fieldsX) - |
-
| HashMap | hashmap: "HashMap<" ident0, ident1 ">" |
- repr(x.len() as u32) - for (k, v) in x.sorted_by_key() { - repr(k as ident0) - repr(v as ident1) - } |
| HashSet | hashset: "HashSet<" ident ">" |
- repr(x.len() as u32) - for el in x.sorted() { - repr(el as ident) - } |
| Option | -option_type: "Option<" ident '>' | - if x.is_some() { - repr(1 as u8) - repr(x.unwrap() as ident) - } else { - repr(0 as u8) - } - |
-
| String | -string_type: "String" | - encoded = utf8_encoding(x) as Vec<u8> - repr(encoded.len() as u32) - repr(encoded as Vec<u8>) |
-
| Informal type | +Rust EBNF * | +Pseudocode | +
| Integers | +integer_type: ["u8" | "u16" | "u32" | "u64" | "u128" | "i8" | "i16" | "i32" | "i64" | "i128" ] | +little_endian(x) | +
| Floats | +float_type: ["f32" | "f64" ] | +
+ err_if_nan(x) + little_endian(x as integer_type) + |
+
| Unit | +unit_type: "()" | +We do not write anything | +
| Fixed sized arrays | +array_type: '[' ident ';' literal ']' | +
+ for el in x { + repr(el as ident) + } + |
+
| Dynamic sized array | +vec_type: "Vec<" ident '>' | +
+ repr(len() as u32) + for el in x { + repr(el as ident) + } + |
+
| Struct | +struct_type: "struct" ident fields | +repr(fields) | +
| Fields | +fields: [named_fields | unnamed_fields] | ++ |
| Named fields | +named_fields: '{' ident_field0 ':' ident_type0 ',' ident_field1 ':' ident_type1 ',' ... '}' | +
+ repr(ident_field0 as ident_type0) + repr(ident_field1 as ident_type1) + ... + |
+
| Unnamed fields | +unnamed_fields: '(' ident_type0 ',' ident_type1 ',' ... ')' | +
+ repr(x.0 as type0) + repr(x.1 as type1) + ... + |
+
| Enum | +
+ enum: 'enum' ident '{' variant0 ',' variant1 ',' ... '}' + variant: ident [ fields ] ? + |
+
+ Suppose X is the number of the variant that the enum takes. + repr(X as u8) + repr(x.X as fieldsX) + |
+
| HashMap | +hashmap: "HashMap<" ident0, ident1 ">" | +
+ repr(x.len() as u32) + for (k, v) in x.sorted_by_key() { + repr(k as ident0) + repr(v as ident1) + } + |
+
| HashSet | +hashset: "HashSet<" ident ">" | +
+ repr(x.len() as u32) + for el in x.sorted() { + repr(el as ident) + } + |
+
| Option | +option_type: "Option<" ident '>' | +
+ if x.is_some() { + repr(1 as u8) + repr(x.unwrap() as ident + } else { + repr(0 as u8) + } + |
+
| String | +string_type: "String" | +
+ encoded = utf8_encoding(x) as Vec<u8> + repr(encoded.len() as u32) + repr(encoded as Vec<u8>) + |
+