Python Borsh Library

This is an unofficial Python library for serializing and deserializing data in the Borsh binary serialization format.

Borsh stands for Binary Object Representation Serializer for Hashing. It was originally implemented in Rust for use with the Near protocol with a focus on "consistency, safety, and speed." It is used for serializing data in a number of applications, including the Solana blockchain.

Installation

This library can be installed using pip:

pip install borsh-python

Usage

All Borsh byte streams have a schema that specifies name and type pairs for each of the values in the stream. The names of the available types are based on Rust and may be found on this page.

In this library, schemas may be declared as follows:

import borsh
from borsh import types

# create an example dict that we will serialize
example_dict = {
  'w': 123,
  'x': 30000,
  'y': 'hello',
  'z': [1, 2, 3, 4]
}

# define the schema for the dict
example_dict_schema = borsh.schema({
  'w': types.u8,
  'x': types.i16,
  'y': types.string,
  'z': types.dynamic_array(types.i8)
})

We can serialize example_dict by calling the serialize method and providing the schema:

serialized_bytes = borsh.serialize(example_dict_schema, example_dict)

print(serialized_bytes)
# b'{0u\x05\x00\x00\x00hello\x04\x00\x00\x00\x01\x02\x03\x04'

This byte string can be deserialized by calling the deserialize method and providing the same schema:

deserialized_data = borsh.deserialize(example_dict_schema, serialized_bytes)

print(deserialized_data)
# {'w': 123, 'x': 30000, 'y': 'hello', 'z': [1, 2, 3, 4]}

Borsh data streams are often base64 encoded. This library can handle these streams when used in conjunction with the base64 library. For example:

import base64
import borsh
from borsh import types

base64_borsh_data = base64.b64decode('ezB1BQAAAGhlbGxvBAAAAAECAwQ=')

example_dict_schema = borsh.schema({
  'w': types.u8,
  'x': types.i16,
  'y': types.string,
  'z': types.dynamic_array(types.i8)
})

print(borsh.deserialize(example_dict_schema, base64_borsh_data))
# {'w': 123, 'x': 30000, 'y': 'hello', 'z': [1, 2, 3, 4]}

Structs

The Borsh format supports a struct type which is similar in function to its counterparts in C-family languages. Consider that we are trying to wrap our example_dict into a struct. We may declare our data and schema as follows:

import borsh
from borsh import types

# define the data dict with our data wrapped in a struct called 'example'
example_struct_dict = {
  'example': types.struct({
    'w': 123,
    'x': 30000,
    'y': 'hello',
    'z': [1, 2, 3, 4]
  })
}

# define a schema for our new struct
example_struct_schema = {
  'example': types.struct({
    'w': types.u8,
    'x': types.i16,
    'y': types.string,
    'z': types.dynamic_array(types.i8)
  })
}

We may serialize and deserialize our struct like this:

serialized_bytes = borsh.serialize(example_struct_schema, example_struct_dict)

example_struct = borsh.deserialize(example_struct_schema, serialized_bytes)['example']
print(example_struct['y'])
# hello

Type Mapping

This library supports the following Borsh types, each of which is mapped to a respective Python type during deserialization.

Unimplemented Types

The following Borsh types are not yet implemented in this library: