borsh

README

borsh-go

borsh-go is an implementation of the [Borsh] binary serialization format for Go projects.

Borsh stands for Binary Object Representation Serializer for Hashing. It is meant to be used in security-critical projects as it prioritizes consistency, safety, speed, and comes with a strict specification.

Features

• Based on Go Reflection. Avoids the need for create protocol file and code generation. Simply defining struct and go.

Usage

Example

package demo

import (
	"log"
	"reflect"
	"testing"

	"github.com/hmn-fnd/borsh-go"
)

type A struct {
	X uint64
	Y string
	Z string `borsh_skip:"true"` // will skip this field when serializing/deserializing
}

func TestSimple(t *testing.T) {
	x := A{
		X: 3301,
		Y: "liber primus",
	}
	data, err := borsh.Serialize(x)
	log.Print(data)
	if err != nil {
		t.Error(err)
	}
	y := new(A)
	err = borsh.Deserialize(y, data)
	if err != nil {
		t.Error(err)
	}
	if !reflect.DeepEqual(x, *y) {
		t.Error(x, y)
	}
}

For more examples of usage, refer to borsh_test.go.

Type Mappings

Borsh	Go	Description
bool	bool
u8 integer	uint8
u16 integer	uint16
u32 integer	uint32
u64 integer	uint64
u128 integer	big.Int
i8 integer	int8
i16 integer	int16
i32 integer	int32
i64 integer	int64
i128 integer		Not supported yet
f32 float	float32
f64 float	float64
fixed-size array	[size]type	go array
dynamic-size array	[]type	go slice
string	string
option	*type	go pointer
map	map
set	map[type]struct{}	go map with value type set to struct{}
structs	struct
enum	borsh.Enum	use type MyEnum borsh.Enum to define enum type

Documentation

Index

• func Compare(a reflect.Value, b reflect.Value) int
• func Deserialize(s interface{}, data []byte) error
• func Serialize(s interface{}) ([]byte, error)
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (d *Decoder) Close() error
  • func (d *Decoder) Decode(s interface{}) error
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (e *Encoder) Close() error
  • func (e *Encoder) Encode(s interface{}) error
• type Enum

Examples

• Deserialize
• NewDecoder
• NewEncoder
• Serialize

Functions

func Compare

func Compare(a reflect.Value, b reflect.Value) int

func Deserialize

func Deserialize(s interface{}, data []byte) error

Deserialize `data` according to the schema of `s`, and store the value into it. `s` must be a pointer type variable that points to the original schema of `data`.

Example

a := A{B: 123}
data, _ := borsh.Serialize(a)
b := &A{}
err := borsh.Deserialize(b, data)
if err != nil {
	log.Fatal(err)
}

func Serialize

func Serialize(s interface{}) ([]byte, error)

Serialize `s` into bytes according to Borsh's specification(https://borsh.io/).

The type mapping can be found at https://github.com/hmn-fnd/borsh-go.

Example

a := A{B: 123}
data, err := borsh.Serialize(a)
if err != nil {
	log.Fatal(err)
}
log.Print(data)

Types

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

Example

a := A{B: 123}
data, _ := borsh.Serialize(a)
b := &A{}
d := borsh.NewDecoder(bytes.NewReader(data))
if err := d.Decode(b); err != nil {
	log.Fatal(err)
}

func (*Decoder) Close

func (d *Decoder) Close() error

func (*Decoder) Decode

func (d *Decoder) Decode(s interface{}) error

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

Example

a := A{B: 123}
b := strings.Builder{}
e := borsh.NewEncoder(&b)
if err := e.Encode(a); err != nil {
	log.Fatal(err)
}

func (*Encoder) Close

func (e *Encoder) Close() error

func (*Encoder) Encode

func (e *Encoder) Encode(s interface{}) error

type Enum

type Enum uint8

Simple Enum type in Go.

type MyEnum borsh.Enum
const (
  A MyEnum = iota
  B
  C
)

Complex Enum type in Go.

 type MyEnum struct {
   Enum borsh.Enum `borsh_enum:"true"`
   Foo  Foo
   Bar  Bar
 }

 type Foo struct {
	  FooA int32
	  FooB string
 }

 type Bar struct {
	  BarA int64
	  BarB string
 }