Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@mysten/bcs

Package Overview
Dependencies
Maintainers
4
Versions
524
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@mysten/bcs

BCS - Canonical Binary Serialization implementation for JavaScript

  • 0.0.0-experimental-20220907170123
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
81K
increased by7.74%
Maintainers
4
Weekly downloads
 
Created
Source

BCS - Binary Canonical Serialization

This library implements Binary Canonical Serialization (BCS) in JavaScript, making BCS available in both Browser and NodeJS environments.

Feature set

  • Move's primitive types de/serialization: u8, u64, u128, bool
  • Ability to define custom types such as vector<T> or struct
  • Extendable and allows registering any custom types (e.g. vectors of structs)
  • Custom addresses length. Example: BCS.registerAddressType('Address', 20, 'hex') - 20 bytes
  • Built-in support for enums (and potentially tuples)
  • And again - full browser support!

Examples

At the high level, BCS gives a set of handy abstractions to (de)serialize data.

Important: by default there's no type address in this library. To define it, use registerAddressType. Also, there's no built-in support for generics yet. For each vector<T> you have to define custom type using registerVectorType('vector<u8>', 'u8'). Default support for vectors is intentionally omitted (for now) because of type difference between Rust and Move vector types.

Struct

In BCS structs are merely sequences of fields, they contain no type information but the order in which fields are defined. It also means that you can use any field names - they won't affect serialization!

bcs.registerStructType(<TYPE>, {
    [<FIELD>]: <FIELD_TYPE>,
    ...
})
import { bcs } from "@mysten/bcs";

// MyAddr is an address of 20 bytes; encoded and decoded as HEX
bcs.registerAddressType('MyAddr', 20, 'hex');
bcs.registerStructType('Item', {
    owner: 'MyAddr',
    price: 'u64'
});

// bcs preserves order of fields according to struct definition, so you're free to
// use any order while serializing your structs
let bcs_bytes = bcs.ser('Item', {
    price: '100000000000',
    owner: '9c88e852aa66b346860ada31aa75c6c27695ae4b',
});
let item = bcs.de('Item', bcs_bytes);

console.log(item);

Vector

Vector generics are not supported by default. To use a vector type, add it first:

bcs.registerVectorType(<TYPE>, <ELEMENT_TYPE>);
import { bcs } from "@mysten/bcs";

bcs.registerVectorType('vector<u8>', 'u8');
let array = bcs.de('vector<u8>', '06010203040506', 'hex'); // [1,2,3,4,5,6];
let again = bcs.ser('vector<u8>', [1,2,3,4,5,6]).toString('hex');

console.assert(again === '06010203040506', 'Whoopsie!');

Address

Even though the way of serializing Move addresses stays the same, the length of the address varies depending on the network. To register an address type use:

bcs.registerAddressType(<TYPE>, <LENGTH>);
import { bcs } from "@mysten/bcs";

bcs.registerAddressType('FiveByte', 5);
bcs.registerAddressType('DiemAddress', 20);

let de = bcs.de('FiveBytes', '0x00C0FFEE00', 'hex');
let ser = bcs.ser('DiemAddress', '9c88e852aa66b346860ada31aa75c6c27695ae4b').toString('hex');

console.assert(de === '00c0ffee00', 'Short address mismatch');
console.assert(ser === '9c88e852aa66b346860ada31aa75c6c27695ae4b', 'Long address mismatch');

Primitive types

To deserialize data, use a BCS.de(type: string, data: Uint8Array). Type parameter is a name of the type; data is a BCS encoded as hex.

import { bcs } from '@mysten/bcs';

// BCS has a set of built ins:
// U8, U32, U64, U128, BOOL, STRING
console.assert(bcs.U64 === 'u64');
console.assert(bcs.BOOL === 'bool');
console.assert(bcs.STRING === 'string');

// De/serialization of primitives is included by default;
let u8 = bcs.de(bcs.U8, '00', 'hex'); // '0'
let u32 = bcs.de(bcs.U32, '78563412', 'hex'); // '78563412'
let u64 = bcs.de(bcs.U64, 'ffffffffffffffff', 'hex'); // '18446744073709551615'
let u128 = bcs.de(bcs.U128, 'FFFFFFFF000000000000000000000000', 'hex'); // '4294967295'
let bool = bcs.de(bcs.BOOL, '00', 'hex'); // false

// There's also a handy built-in for ASCII strings (which are `vector<u8>` under the hood)
let str = bcs.de(bcs.STRING, '0a68656c6c6f5f6d6f7665', 'hex'); // hello_move

console.log(str);

To serialize any type, use bcs.ser(type: string, data: any). Type parameter is a name of the type to serialize, data is any data, depending on the type (can be object for structs or string for big integers - such as u128).

import { bcs } from '@mysten/bcs';

let bcs_u8 = bcs.ser('u8', 255).toString('hex'); // uint Array
console.assert(bcs_u8 === 'ff');

let bcs_ascii = bcs.ser('string', 'hello_move').toString('hex');
console.assert(bcs_ascii === '0a68656c6c6f5f6d6f7665');

Working with Move structs

import { bcs } from '@mysten/bcs';

// Move / Rust struct
// struct Coin {
//   value: u64,
//   owner: vector<u8>, // name // Vec<u8> in Rust
//   is_locked: bool,
// }

bcs.registerStructType('Coin', {
    value: bcs.U64,
    owner: bcs.STRING,
    is_locked: bcs.BOOL
});

// Created in Rust with diem/bcs
let rust_bcs_str = '80d1b105600000000e4269672057616c6c65742047757900';

console.log(bcs.de('Coin', rust_bcs_str, 'hex'));

// Let's encode the value as well
let test_ser = bcs.ser('Coin', {
    owner: 'Big Wallet Guy',
    value: '412412400000',
    is_locked: false
});

console.log(test_ser.toBytes());
console.assert(test_ser.toString('hex') === rust_bcs_str, 'Whoopsie, result mismatch');

Keywords

FAQs

Package last updated on 07 Sep 2022

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc