Module solana_libra_vm::file_format

Binary format for transactions and modules.

This module provides a simple Rust abstraction over the binary format. That is the format of modules stored on chain or the format of the code section of a transaction.

file_format_common.rs provides the constant values for entities in the binary format. (The binary format is evolving so please come back here in time to check evolutions.)

Overall the binary format is structured in a number of sections:

• Header: this must start at offset 0 in the binary. It contains a blob that starts every Libra binary, followed by the version of the VM used to compile the code, and last is the number of tables present in this binary.
• Table Specification: it's a number of tuple of the form (table type, starting_offset, byte_count). The number of entries is specified in the header (last entry in header). There can only be a single entry per table type. The starting offset is from the beginning of the binary. Tables must cover the entire size of the binary blob and cannot overlap.
• Table Content: the serialized form of the specific entries in the table. Those roughly map to the structs defined in this module. Entries in each table must be unique.

We have two formats: one for modules here represented by CompiledModule, another for transaction scripts which is CompiledScript. Building those tables and passing them to the serializer (serializer.rs) generates a binary of the form described. Vectors in those structs translate to tables and table specifications.

Structs

AddressPoolIndex	Index into the AddressPool table.
ByteArrayPoolIndex	Index into the ByteArrayPool table.
CodeUnit	A CodeUnit is the body of a function. It has the function header and the instruction stream.
CompiledModule	A CompiledModule defines the structure of a module which is the unit of published code.
CompiledModuleMut	A mutable version of CompiledModule. Converting to a CompiledModule requires this to pass the bounds checker.
CompiledProgram	A CompiledProgram defines the structure of a transaction to execute. It has two parts: modules to be published and a transaction script.
CompiledScript	Contains the main function to execute and its dependencies.
CompiledScriptMut	A mutable version of CompiledScript. Converting to a CompiledScript requires this to pass the bounds checker.
FieldDefinition	A FieldDefinition is the definition of a field: the type the field is defined on, its name and the field type.
FieldDefinitionIndex	Index into the FieldDefinition table.
FunctionDefinition	A FunctionDefinition is the implementation of a function. It defines the prototype of the function and the function body.
FunctionDefinitionIndex	Index into the FunctionDefinition table.
FunctionHandle	A FunctionHandle is a reference to a function. It is composed by a ModuleHandle and the name and signature of that function within the module.
FunctionHandleIndex	Index into the FunctionHandle table.
FunctionSignature	A FunctionSignature describes the types of a function.
FunctionSignatureIndex	Index into the FunctionSignature table.
IdentifierIndex	Index into the Identifier table.
LocalsSignature	A LocalsSignature is the list of locals used by a function.
LocalsSignatureIndex	Index into the LocalsSignature table.
ModuleHandle	A ModuleHandle is a reference to a MOVE module. It is composed by an address and a name.
ModuleHandleIndex	Index into the ModuleHandle table.
StructDefinition	A StructDefinition is a type definition. It either indicates it is native or
StructDefinitionIndex	Index into the StructDefinition table.
StructHandle	A StructHandle is a reference to a user defined type. It is composed by a ModuleHandle and the name of the type within that module.
StructHandleIndex	Index into the StructHandle table.
TypeSignature	A type definition. SignatureToken allows the definition of the set of known types and their composition.
TypeSignatureIndex	Index into the TypeSignature table.
UserStringIndex	Index into the UserString (VM string) table.

Enums

Bytecode	Bytecode is a VM instruction of variable size. The type of the bytecode (opcode) defines the size of the bytecode.
Kind	A Kind classifies types into sets with rules each set must follow.
SignatureToken	A SignatureToken is a type declaration for a location.
StructFieldInformation	StructFieldInformation indicates whether a struct is native or has user-specified fields

Constants

NO_TYPE_ACTUALS	Index 0 into the LocalsSignaturePool, which is guaranteed to be an empty list. Used to represent function/struct instantiation with no type actuals -- effectively non-generic functions and structs.
NUMBER_OF_BYTECODE_INSTRUCTIONS	The number of bytecode instructions. This is necessary for checking that all instructions are covered since Rust does not provide a way of determining the number of variants of an enum.

Functions

basic_test_module	Create the following module which is convenient in tests: // module { // struct Bar { x: u64 } // // foo() { // } // }
dummy_procedure_module	Create a dummy module to wrap the bytecode program in local@code
empty_module	Return the simplest module that will pass the bounds checker
self_module_name

Type Definitions

AddressPool	The pool of AccountAddress literals.
ByteArrayPool	The pool of ByteArray literals.
CodeOffset	Index into the code stream for a jump. The offset is relative to the beginning of the instruction stream.
FunctionSignaturePool	The pool of FunctionSignature instances.
IdentifierPool	The pool of identifiers.
LocalIndex	Index of a local variable in a function.
LocalsSignaturePool	The pool of LocalsSignature instances. Every function definition must define the set of locals used and their types.
MemberCount	Max number of fields in a StructDefinition.
TableIndex	Generic index into one of the tables in the binary format.
TypeParameterIndex	Type parameters are encoded as indices. This index can also be used to lookup the kind of a type parameter in the FunctionSignature/Handle and StructHandle.
TypeSignaturePool	The pool of TypeSignature instances. Those are system and user types used and their composition (e.g. &U64).
UserStringPool	The pool of string literals.