kabie/bcs

Bcs

Pure Elixir encoder/decoder for BCS format.

Features

Encoder/Decoder for:

• Booleans
• Signed 8-bit, 16-bit, 32-bit, 64-bit, and 128-bit integers
• Unsigned 8-bit, 16-bit, 32-bit, 64-bit, and 128-bit integers
• Option
• Unit (an empty value)
• Fixed and variable length sequences
• UTF-8 Encoded Strings
• Tuples
• Structures (aka “structs”)
• Externally tagged enumerations (aka “enums”)
• Maps

Installation

If available in Hex, the package can be installed by adding bcs to your list of dependencies in mix.exs:

def deps do
  [
    {:bcs, "~> 0.1.0"}
  ]
end

Usage

# Define the struct
defmodule MyStruct do
  @derive {Bcs.Struct,
    label: :string,
    chars: [:u8 | 4],  # <<= we use improper list for fixed length array
    boolean: :bool,
    maps: %{:u8 => :string},
  }

  defstruct [:label, :chars, :boolean, :maps, :field]
end

my_struct = %MyStruct{
  label: "hello",
  chars: 'abcd',
  boolean: true,
  maps: %{1 => "1", 2 => "2"},
  field: "this field will be ignored"
}

# encode
my_struct
|> Bcs.encode!()
# then decode
|> Bcs.decode!(MyStruct)

Define field Types

Rust Type	Syntax
u8, s8, u16, u256, ...	:u8, :s8, :u16, :u256, ...
bool	:bool
()	nil
Option<T>	[t | nil]
[T]	[t]
[T; N]	[t | n]
String	:string
(T1, T2)	{t1, t2}
MyStruct	MyStruct
enum E	E
Map<K, V>	%{k => v}

Also we have a special type for treating [u8] as binary instead of charlist

[u8] | [:byte] [u8; N] | [:byte \| n]

Define Tagged Enums

defmodule Foo do
  use Bcs.TaggedEnum, [
    {:variant0, :u16},
    {:variant1, :u8},
    {:variant2, :string},
    :variant3
  ]
end

Some valid values for type Foo: {:variant0, 42}, {:variant2, "hello"}, :variant3, etc.