dart-scale-codec

scalecodec library for substrate based blockchains in native dart

This library does NOT

  • hash and digest serialized data
  • fetch/send any data from/to blockchain
  • sign extrinsics

Environment setup

Since scalecodec depends on reflectable package, users need to first build a reflectable file of the main entrypoint.

Usage of reflectable can be found in reflectable homepage

Setup these sections in your build.yaml file

targets:
  $default:
    builders:
      reflectable:
        generate_for:
          - src/your-entry-point.dart

After that, run build command to generate reflectable file

pub run build_runner build ./

And setup reflectable code in your main entrypoint

...
import 'your-entry-point.reflectable.dart'
...

void main() {
    initializeReflectable();
    ...
}

Usage

Global reader and writer instance

Global reader/writer instance is used to store on-way binary data when converting from/to binary. They are singleton instances, initialized by caller, used by library and finished by caller.

  • Global reader instance usage
createReaderInstance('hex string input');
// calling fromBinary will pop binary data from global reader and contruct structured data
  • Global writer instance usage
createWriterInstance();
object.objToBinary();
// return Uint8List
// calling finalize will return all encoded data
var encoded = getWriterInstance().finalize();

Initialize global metadata

Demo file at example/metadata_demo.dart

Current supported metadata version includes v11 and v12.

createReaderInstance(metaHex);
var magic = String.fromCharCodes(getReaderInstance().read(4));
if(magic != 'meta') {
    throw Exception("Invalid metadata");
}

// decode metadata binary to metadata object
var metadata = fromBinary('MetadataEnum');

// dumps metadata as json
print(jsonEncode(metadata));

// or you can cache metadata json and initialize metadata from json
// var metadata = MetadataEnum.fromJson(jsonDecode(jsonEncode(metadata)));

// set global runtime metadata
RuntimeConfigration().registMetadata(metadata);

Supported typenames

  • Numeric: u8, u16, u32, u64, u128, u256, i8, i16, i32, i64, i128, i256
  • Hash: H160, H256, H512
  • Basic types: Str, Bytes, Bool
  • Fixed length array: typename, repeatCount
  • Dynamic array: Vec
  • Compact: Compact
  • Optional: Option
  • Tuples: (typename1, typename2, ...)
  • Complex types: Address, Era, StorageHasher, Extrinsics, ExtrinsicsPayloadValue, GenericCall, MetadataEnum

Convert from json to object

var obj = fromJson('typename', json);

Convert from binary to object

createReaderInstance(hexStr);
var obj = fromBinary('typename');

Convert from object to json

var jsonStr = jsonEncode(obj);

Convert from object to binary

createWriterInstance();
obj.objToBinary();
// returns Uint8List
var bytes = getWriterInstance().finalize();

Libraries

scalecodec