Skip to main content

Crate ab_contract_file

Crate ab_contract_file 

Source
Expand description

Utilities for working with contract files.

§File layout

Internally, a contract file contains the following sections in specified order:

  • a header: ContractFileHeader, which allows interpreting the rest of file contents
  • metadata about callable methods: ContractFileMethodMetadata for each method, which allows calling methods later
  • read-only data section: contains contract metadata among other things, allowing to decode names and ABI of the methods mentioned above, and the number of methods in this metadata must match the number of methods in the header
  • code section: contains only valid/supported RISC-V instructions or 16-bit zero padding, always ending with some kind of jump instruction

This file is created from an ELF source file and can, technically, be converted back to it. Note that due to the intentional lack of the .bss section equivalent and many other features, only simple RISC-V ELF shared library files can be converted into the contract file. Supporting more complex capabilities would be much more complex and error-prone.

ELF file is expected to have at most a single export for host calls, whose address is stored in the header and jumps to that address are intercepted by the runtime.

The format is designed to be very compact, easy to understand and use, and be such that it can be trivially loaded into a normal RISC-V process for debugging purposes using traditional tools like gdb.

ab-contracts-tooling crate exists that can build and convert contracts to this format both programmatically and using CLI interface.

Modules§

contract_instruction_prototype

Structs§

ContractFile
A container for a parsed contract file
ContractFileHeader
Header of the contract file
ContractFileMethod
ContractFileMethodMetadata
Metadata about each method of the contract that can be called from the outside

Enums§

ContractFileParseError
Error for ContractFile::parse()

Constants§

CONTRACT_FILE_MAGIC
Magic bytes at the beginning of the file

Type Aliases§

ContractInstruction
An instruction type used by contracts
ContractRegister
A register type used by contracts