README.md

BCS

Kotlin Multiplatform implementation of Binary Canonical Serialization (BCS) as an encoding format for the kotlinx.serialization library

Table of contents

• Quick start
  • Installation
    • Multiplatform
    • Platform specific (Android, JS, Native, JVM)
    • Serialization
      • Basic Types
      • User-defined Types
• For Rust Developers
  • Parity
• Reference
• Contribution

Quick Start

Installation

Multiplatform

Add the kotlinx-serialization-bcs dependency to the common sourceSet

implementation("xyz.mcxross.bcs:bcs:<$bcs_version>")

Platform specific (Android, JS, Native, JVM)

Add the kotlinx-serialization-bcs dependency to the Project's dependency block

Generic:

implementation("xyz.mcxross.bcs:<bcs-[platform]>:<$bcs_version>")

For example for Android and JS

Android:

implementation("xyz.mcxross.bcs:bcs-android:<$bcs_version>")

JS:

implementation("xyz.mcxross.bcs:bcs-js:<$bcs_version>")

Serialization

Basic Types

For basic types, simply call the Bcs.encodeToByteArray() function with the desired value, and in each case, you will get a ByteArray containing the state of this object in the BCS format

• Triple

val bcs = Bcs.encodeToByteArray(Triple(listOf(), "çå∞≠¢õß∂ƒ∫", Location(x = 3, y = 4)))

• String

val bcs = Bcs.encodeToByteArray("çå∞≠¢õß∂ƒ∫")

• List

val bcs = Bcs.encodeToByteArray(listOf(1, 2, 3, 4, 5))

• Map

val bcs = Bcs.encodeToByteArray(mapOf("a" to 1, "b" to 2, "c" to 3))

• Double

val bcs = Bcs.encodeToByteArray(3.14159265359)

• Boolean

val bcs = Bcs.encodeToByteArray(false)

Deserialization is done by calling the Bcs.decodeFromByteArray() function with the described type

User-defined Types

For use-defined types, first make a class serializable by annotating it with @Serializable

@Serializable
data class Data(
    val long: Long,
    val double: Double,
    val string: String,
    val boolean: Boolean
)

You can now serialize an instance of this class by calling Bcs.encodeToByteArray()

val bcs = Bcs.encodeToByteArray(
    Data(1_000_000, 3.14159265359, "çå∞≠¢õß∂ƒ∫", false)
)

As a result, you get a ByteArray containing the state of this object in the BCS format

To deserialize an object from BCS, use the decodeFromByteArray() function:

val obj = Bcs.decodeFromByteArray<Data>(byteArrayOf())

Note: BCS is not a self-describing format. As such, one must know the message type and layout ahead of time in order to deserialize.

For Rust Developers

Parity

For parity with the original Rust BCS implementation, the following type translations are used:

Rust type	Kotlin Type
Struct	Data class
Tuple	Pair, Triple, etc.
Unit	Unit
Option	T?

Reference

BCS specs can be found here

Contribution

All contributions to KMP BCS are welcome. Before opening a PR, please submit an issue detailing the bug or feature. When opening a PR, please ensure that your contribution builds on the KMM toolchain, has been linted with ktfmt <GOOGLE (INTERNAL)>, and contains tests when applicable. For more information, please see the contribution guidelines.

License

Copyright 2022 McXross

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.