Essential ASM Specification.

This crate parses the Essential ASM specification from YAML and provides a structured model for deserializing and traversing the tree of operations.

The primary use is to assist in generating the official ASM declaration and implementations, though is likely useful for other tooling based on the essential ASM spec.

Operation Declaration

Each operation is identified by a unique name and contains the following fields:

• opcode: A hexadecimal representation of the operation code, uniquely identifying the operation.
• description: A brief explanation of what the operation does.
• panics (optional): A list of reasons why the operation might cause the virtual machine to panic.
• num_arg_bytes (optional): Specifies the number of bytes expected as arguments for the operation.
• stack_in: Defines the inputs taken from the stack before operation execution. This is a list of symbolic identifiers representing the expected values. If stack_in is omitted, an empty list is assumed.
• stack_out: Describes the outputs pushed onto the stack after operation execution. The stack output can either be "fixed" or "dynamic".
  • fixed: Used when the number of items pushed to the stack is constant. Represented as a list of strings representing the output values.
  • dynamic: Used when the number of items pushed to the stack can vary. Represented as a mapping with the following fields:
    • The elem field is a symbolic identifier representing the output values.
    • The len field specifies which stack_in word the length is derived from.

Examples

Push:
  opcode: 0x01
  description: Push one word onto the stack.
  num_arg_bytes: 8
  stack_out: [word]

ReadWordRange:
  opcode: 0x60
  description: |
    Read a range of words from state starting at the key.

    Reads the state key and the number of words from the stack input.

    Returns the memory address at which the data was written via the stack output.
  panics:
    - Not enough memory allocated to store the read state.
  stack_in: [key_w0, key_w1, key_w2, key_w3, n_words]
  stack_out: [mem_addr]

Operation Group

An operation group organizes related operations. It can include:

• description: A brief overview of the group's purpose.
• group: A mapping from names to operations (or other groups) within this group.

Example

    Stack:
      description: Operations related to stack manipulation.
      group:
        # Push:
        # etc

Multi-word Values

When a multi-word value (like a state key or an address) is read from the stack, the most-significant bits are assumed to have been pushed to the stack first.