Skip to content

Binary File Format

Jump to bottom
Matteo Ferretti edited this page Jul 10, 2023 · 3 revisions

This document provides an overview of the binary encoding used for proprietary Rusk binary files.

The following header is a standard component shared by all binary Rusk files.

Header

Offset Value Description
0000000 0072 736b Magic number ('\0rsk')
0000004 0100 File Type (e.g. 0x01 is a Rusk Smart Contract)
0000006 0000 Reserved
0000008 0000 0100 Version number

After the aforementioned header, the content that follows is specific to the file type. Each file type has its own unique content structure and encoding format.

Parsing and validation

  1. Read the first 4 bytes as u32 in BE, assert is equals to 0x0072_736b8
  2. Read the next 2 bytes as u16 in LE, assert is equals to the file type expected (e.g. 0x01)

Or:

  1. Read the first 8 bytes as u64 in BE, right shift by 2 bytes, assert is equals to 0x0072_736b_0100 (In case of a a Rusk Smart Contract)

Or, if Reserved is never used by that file type:

  1. Read the first 8 bytes as u64 in BE, assert is equals to 0x0072_736b_0100_0000 (In case of a a Rusk Smart Contract)

Reserved

The utilization of this field is at the discretion of the specific file type implementation. It can be employed according to the specific requirements and specifications of each file type.

Version

The version field are 8 bytes used to specify a subset of Semantic Versioning as followed:

Offset Value Description
0000008 0x00..0xff Major, value between 0..255
0000009 0x00..0xff Minor, value between 0..255
0000010 0x00..0xff Patch, value between 0..255
0000011 0x00..0xff Pre-release, value between 0..127. The higher bit is used to indicate if it's a pre-release (0 is not, 1 it is)

The version is determined at the discretion of the implementer. If the implementation expects a fixed value for the version (such as 0.1.0 without any pre-release), it can read the entire version as a u32 in big-endian format and compare it against the expected value (for example, 0x0001_0000).

Examples

SemVer Bytes representation
"0.13.5" 000d 0500
"1.0.19" 0100 1300
"3.21.30-rc.0" 0315 1e80
"3.21.30-rc.1" 0315 1e81
"3.21.30-pre.1" 0315 1e81

It's important to note that there is no distinction between the last two representations. Regardless of whether it is labeled as pre, alpha, or rc, within this particular subset of semver, it always indicates a pre-release version.

File types

Value Description
0x01 Rusk Smart Contract
0x02 Rusk Wallet
Clone this wiki locally