Manager API

The GenVM Manager exposes an HTTP server for administration (status, modules, permits, log level, manifest, LLM checks, error descriptions, contract version detection) and a framed socket for driving executions (Manager Socket Protocol).

The execution endpoints below – POST /genvm/run, GET /genvm/{id}, DELETE /genvm/{id} – are deprecated: they remain for one release train as a thin adapter over the same execution core the socket uses, then get removed. New host integrations MUST use the socket protocol.

Two endpoints below are tightly coupled with the runner manifest (the per-line available-runners listing, generated from runners-versions.json, published on each executor line’s docs sub-site):

• POST /contract/detect-version returns the public-ABI specified_major that the node MUST persist into the contract’s root-slot major field (see Version Management and Storage System).

• POST /manifest/reload re-reads the runner manifest from disk; until reload, runner versions added to the JSON are not visible to the manager.

GET /ws

Upgrade to the manager socket protocol

WebSocket upgrade. Everything past the handshake – framing, methods, events, error codes – is specified in the Manager Socket Protocol appendix, not here; OpenAPI cannot describe a bidirectional message stream. Listed so this file stays a complete route table.

This is the supported way to drive executions. The /genvm/* paths below are deprecated adapters over the same core.

Status Codes:

• 101 Switching Protocols – Switching protocols; the connection becomes a manager socket

• 400 Bad Request – Not a WebSocket handshake; the body is plain text

• 426 Upgrade Required – A handshake on a connection that cannot be upgraded, such as HTTP/1.0

GET /status

Get manager status

Returns the current status of the manager, its modules, permits, and running executions.

Status Codes:

• 200 OK – Manager status

POST /module/start

Start a module

Start a module with the specified configuration.

Status Codes:

• 200 OK – Module started successfully

• 400 Bad Request – Error response

• 500 Internal Server Error – Error response

POST /module/stop

Stop a module

Stop a running module.

Status Codes:

• 200 OK – Module stop result

• 400 Bad Request – Error response

• 500 Internal Server Error – Error response

POST /module/restart

Restart a module

Atomically restart a module. Stops the currently running module (if any) and starts a new one with the specified configuration, all under a single lock to prevent concurrent access during the transition.

Status Codes:

• 200 OK – Module restarted successfully

• 400 Bad Request – Error response

• 500 Internal Server Error – Error response

POST /genvm/run

Start a GenVM execution (deprecated)

Deprecated adapter over the socket protocol’s run (see the Manager Socket Protocol appendix); kept for one release train while hosts migrate. Unlike the socket run, this call responds only after the execution has started (or failed to start).

Both entry points decode GenvmRunRequest and share the start path and host_genvm_id idempotency token. A failed HTTP start created by this request is released, freeing its token for a corrected retry. A retry that finds an existing retained run does not release it. Socket startup failures remain retained until ack or until the retention TTL expires

The body is calldata, not JSON; GenvmRunRequest says how its types map onto calldata.

Status Codes:

• 200 OK – GenVM instance started

• 500 Internal Server Error – Error response

GET /genvm/{genvm_id}

Get GenVM status (deprecated)

Deprecated adapter over the socket protocol’s attach + ack; kept for one release train while hosts migrate

The optional wait parameter exists so hosts that cannot use the socket protocol can stop busy-polling. It does not un-deprecate this route; the socket protocol remains the supported interface

The route preserves the historical destructive semantics: a returned non-null status acknowledges the execution, so a second GET answers null. Socket clients get non-destructive reads with an explicit ack instead

Parameters:

• genvm_id (integer) – Unique identifier of the GenVM instance

Query Parameters:

• wait (string) –

  Maximum time to wait for a terminal status, as a number followed by ms, s, m, or h, for example 500ms, 30s, or 1m

  Values above 120 seconds are clamped to 120 seconds. If the wait times out, the response has a null status rather than an error

Status Codes:

• 200 OK – GenVM status

• 400 Bad Request – Error response

• 404 Not Found – The genvm_id path segment is not a decimal 64-bit unsigned integer

• 500 Internal Server Error – Error response

DELETE /genvm/{genvm_id}

Shutdown GenVM instance (deprecated)

Deprecated adapter over the socket protocol’s cancel; kept for one release train while hosts migrate. Socket clients should rely on the request-carried deadline plus cancel instead of a client-side timeout that fires DELETE.

Parameters:

• genvm_id (integer) – Unique identifier of the GenVM instance

Status Codes:

• 200 OK – Shutdown result

• 400 Bad Request – Error response

• 404 Not Found – The genvm_id path segment is not a decimal 64-bit unsigned integer

GET /genvm/{genvm_id}/artifact

Get retained GenVM artifact

Debug convenience adapter over the socket protocol’s get_artifact. Returns a base64-encoded chunk from one retained artifact. Socket clients should use the framed get_artifact method instead.

Parameters:

• genvm_id (integer) – Unique identifier of the GenVM instance

Query Parameters:

• field (string) – Artifact field to read (Required)

• offset (integer) – Byte offset within the artifact

• max_len (integer) – Maximum bytes to return before server-side chunk capping (Required)

Status Codes:

• 200 OK – Artifact chunk

• 400 Bad Request – Error response

• 404 Not Found – The genvm_id path segment is not a decimal 64-bit unsigned integer

• 500 Internal Server Error – Error response

POST /contract/detect-version

Detect contract version

Detect the major version specification from contract bytecode.

Status Codes:

• 200 OK – Detected version

• 400 Bad Request – Error response

• 500 Internal Server Error – Error response

Request Headers:

• Deployment-Timestamp – Contract deployment timestamp in RFC3339 format (Required)

POST /log/level

Set log level

Set the logging level for the manager.

Status Codes:

• 200 OK – Log level set

• 400 Bad Request – Error response

• 500 Internal Server Error – Error response

POST /manifest/reload

Reload manifest

Reload the executor version manifest.

Status Codes:

• 200 OK – Manifest reloaded

• 500 Internal Server Error – Error response

GET /permits

Get permits

Get the current maximum number of execution permits; /status reports how many are free.

Status Codes:

• 200 OK – Maximum permits

POST /permits

Set permits

Set the number of execution permits, one permit is one gigabyte of RAM. A value below the cost of the most expensive run is rejected, and the response carries the unchanged maximum.

Status Codes:

• 200 OK – Permits set

• 400 Bad Request – Error response

• 500 Internal Server Error – Error response

POST /llm/check

Check LLM availability

Test availability and functionality of LLM provider configurations.

Status Codes:

• 200 OK – LLM availability results

• 400 Bad Request – Error response

• 500 Internal Server Error – Error response

GET /vm-error/describe

Describe VM error

Get a human-readable description for a VM error code.

Query Parameters:

• error (string) – The VM error code to describe (Required)

Status Codes:

• 200 OK – Error description

• 400 Bad Request – Error response

• 500 Internal Server Error – Error response

openapi: 3.0.3
info:
  title: GenVM Manager API
  description: HTTP API for managing GenVM instances, modules, and related operations.
  version: 1.0.0

servers:
  - url: http://localhost:3999
    description: Default local development server

paths:
  /ws:
    get:
      summary: Upgrade to the manager socket protocol
      description: |
        WebSocket upgrade. Everything past the handshake -- framing, methods,
        events, error codes -- is specified in the Manager Socket Protocol
        appendix, not here; OpenAPI cannot describe a bidirectional message
        stream. Listed so this file stays a complete route table.

        This is the supported way to drive executions. The `/genvm/*` paths
        below are deprecated adapters over the same core.
      operationId: managerSocket
      responses:
        '101':
          description: Switching protocols; the connection becomes a manager socket
        '400':
          description: Not a WebSocket handshake; the body is plain text
        '426':
          description: A handshake on a connection that cannot be upgraded, such as HTTP/1.0

  /status:
    get:
      summary: Get manager status
      description: Returns the current status of the manager, its modules, permits, and running executions.
      operationId: getStatus
      responses:
        '200':
          description: Manager status
          content:
            application/json:
              schema:
                type: object
                properties:
                  llm_module:
                    type: string
                    enum: [running, stopping, stopped]
                    description: Status of the LLM module
                  web_module:
                    type: string
                    enum: [running, stopping, stopped]
                    description: Status of the web module
                  permits:
                    type: object
                    properties:
                      current:
                        type: integer
                        description: Current number of available permits
                      max:
                        type: integer
                        description: Maximum number of permits
                      per_sync_run:
                        type: integer
                        description: Permits a sync run costs
                      per_nondet_run:
                        type: integer
                        description: Permits a nondet run costs
                  executions:
                    type: object
                    description: Known executions, keyed by GenVM id
                    additionalProperties:
                      type: object
                      properties:
                        result:
                          type: object
                          nullable: true
                          description: >-
                            Stored finished result; null for pending runs and retained startup failures
                          properties:
                            finished_at:
                              type: string
                              format: date-time
                        version:
                          type: string
                          description: Executor version the run resolved to, empty until resolved
                        started_at:
                          type: string
                          format: date-time
                        strict_deadline:
                          type: string
                          format: date-time

  /module/start:
    post:
      summary: Start a module
      description: Start a module with the specified configuration.
      operationId: startModule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModuleStartRequest'
      responses:
        '200':
          description: Module started successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: module_started
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /module/stop:
    post:
      summary: Stop a module
      description: Stop a running module.
      operationId: stopModule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - module_type
              properties:
                module_type:
                  type: string
                  enum: [Llm, Web]
                  description: Type of module to stop
              example:
                module_type: Llm
      responses:
        '200':
          description: Module stop result
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    enum: [module_stopped, module_not_running]
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /module/restart:
    post:
      summary: Restart a module
      description: |
        Atomically restart a module. Stops the currently running module (if any) and starts
        a new one with the specified configuration, all under a single lock to prevent
        concurrent access during the transition.
      operationId: restartModule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModuleStartRequest'
      responses:
        '200':
          description: Module restarted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: module_restarted
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /genvm/run:
    post:
      summary: Start a GenVM execution (deprecated)
      deprecated: true
      description: |
        Deprecated adapter over the socket protocol's `run` (see the Manager
        Socket Protocol appendix); kept for one release train while hosts
        migrate. Unlike the socket `run`, this call responds only after the
        execution has started (or failed to start).

        Both entry points decode `GenvmRunRequest` and share the start path and
        `host_genvm_id` idempotency token. A failed HTTP start created by this
        request is released, freeing its token for a corrected retry. A retry
        that finds an existing retained run does not release it. Socket startup
        failures remain retained until `ack` or until the retention TTL expires

        The body is calldata, not JSON; `GenvmRunRequest` says how its types map
        onto calldata.
      operationId: runGenvm
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              $ref: '#/components/schemas/GenvmRunRequest'
      responses:
        '200':
          description: GenVM instance started
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: started
                  id:
                    type: integer
                    description: Unique identifier for the GenVM instance
                    example: 12345
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /genvm/{genvm_id}:
    get:
      summary: Get GenVM status (deprecated)
      deprecated: true
      description: |
        Deprecated adapter over the socket protocol's `attach` + `ack`; kept
        for one release train while hosts migrate

        The optional `wait` parameter exists so hosts that cannot use the
        socket protocol can stop busy-polling. It does not un-deprecate this
        route; the socket protocol remains the supported interface

        The route preserves the historical destructive semantics: a returned
        non-null status acknowledges the execution, so a second GET answers
        null. Socket clients get non-destructive reads with an explicit `ack`
        instead
      operationId: getGenvmStatus
      parameters:
        - name: genvm_id
          in: path
          required: true
          schema:
            type: integer
          description: Unique identifier of the GenVM instance
        - name: wait
          in: query
          required: false
          schema:
            type: string
            example: 30s
          description: |
            Maximum time to wait for a terminal status, as a number followed
            by `ms`, `s`, `m`, or `h`, for example `500ms`, `30s`, or `1m`

            Values above 120 seconds are clamped to 120 seconds. If the wait
            times out, the response has a null status rather than an error
      responses:
        '200':
          description: GenVM status
          content:
            application/json:
              schema:
                type: object
                properties:
                  genvm_id:
                    type: integer
                  status:
                    type: object
                    nullable: true
                    description: >-
                      Stored finished result; null for pending runs, retained startup failures,
                      acknowledged runs, or unknown ids
                    properties:
                      finished_at:
                        type: integer
                        format: int64
                        description: Unix time in milliseconds
                      stdout:
                        type: string
                      stderr:
                        type: string
                      genvm_log:
                        type: array
                        items:
                          type: object
                      metrics:
                        type: object
                        nullable: true
                      consumed_result:
                        type: string
                        format: byte
                        nullable: true
                      version_major:
                        type: integer
                      version_minor:
                        type: integer
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      summary: Shutdown GenVM instance (deprecated)
      deprecated: true
      description: |
        Deprecated adapter over the socket protocol's `cancel`; kept for one
        release train while hosts migrate. Socket clients should rely on the
        request-carried deadline plus `cancel` instead of a client-side
        timeout that fires DELETE.
      operationId: shutdownGenvm
      parameters:
        - name: genvm_id
          in: path
          required: true
          schema:
            type: integer
          description: Unique identifier of the GenVM instance
      responses:
        '200':
          description: Shutdown result
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    required: [result, genvm_id]
                    properties:
                      result:
                        type: string
                        example: shutdown_completed
                      genvm_id:
                        type: integer
                  - type: object
                    required: [error, genvm_id]
                    properties:
                      error:
                        type: string
                        example: timeout during shutdown
                      genvm_id:
                        type: integer
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'

  /genvm/{genvm_id}/artifact:
    get:
      summary: Get retained GenVM artifact
      description: |
        Debug convenience adapter over the socket protocol's `get_artifact`.
        Returns a base64-encoded chunk from one retained artifact. Socket
        clients should use the framed `get_artifact` method instead.
      operationId: getGenvmArtifact
      parameters:
        - name: genvm_id
          in: path
          required: true
          schema:
            type: integer
          description: Unique identifier of the GenVM instance
        - name: field
          in: query
          required: true
          schema:
            type: string
            enum: [stdout, stderr, genvm_log]
          description: Artifact field to read
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            format: uint64
            default: 0
          description: Byte offset within the artifact
        - name: max_len
          in: query
          required: true
          schema:
            type: integer
            format: uint32
          description: Maximum bytes to return before server-side chunk capping
      responses:
        '200':
          description: Artifact chunk
          content:
            application/json:
              schema:
                type: object
                properties:
                  genvm_id:
                    type: integer
                  field:
                    type: string
                  total_len:
                    type: integer
                    format: uint64
                  data_base64:
                    type: string
                    format: byte
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /contract/detect-version:
    post:
      summary: Detect contract version
      description: Detect the major version specification from contract bytecode.
      operationId: detectContractVersion
      parameters:
        - name: Deployment-Timestamp
          in: header
          required: true
          schema:
            type: string
            format: date-time
          description: Contract deployment timestamp in RFC3339 format
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
              description: Contract bytecode
      responses:
        '200':
          description: Detected version
          content:
            application/json:
              schema:
                type: object
                properties:
                  specified_major:
                    type: integer
                    description: Detected major version
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /log/level:
    post:
      summary: Set log level
      description: Set the logging level for the manager.
      operationId: setLogLevel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - level
              properties:
                level:
                  type: string
                  enum: [trace, debug, info, warn, warning, error]
                  description: Log level to set, matched case-insensitively
              example:
                level: debug
      responses:
        '200':
          description: Log level set
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: log_level_set
                  level:
                    type: string
                    enum: [Trace, Debug, Info, Warn, Error]
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /manifest/reload:
    post:
      summary: Reload manifest
      description: Reload the executor version manifest.
      operationId: reloadManifest
      responses:
        '200':
          description: Manifest reloaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: manifest_reloaded
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /permits:
    get:
      summary: Get permits
      description: Get the current maximum number of execution permits; `/status` reports how many are free.
      operationId: getPermits
      responses:
        '200':
          description: Maximum permits
          content:
            application/json:
              schema:
                type: object
                properties:
                  permits:
                    type: integer
                    description: Maximum number of permits
    post:
      summary: Set permits
      description: >-
        Set the number of execution permits, one permit is one gigabyte of RAM.
        A value below the cost of the most expensive run is rejected, and the
        response carries the unchanged maximum.
      operationId: setPermits
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - permits
              properties:
                permits:
                  type: integer
                  description: New number of permits to allocate
              example:
                permits: 10
      responses:
        '200':
          description: Permits set
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: permits_set
                  permits:
                    type: integer
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /llm/check:
    post:
      summary: Check LLM availability
      description: Test availability and functionality of LLM provider configurations.
      operationId: checkLlm
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - configs
                - test_prompts
              properties:
                configs:
                  type: array
                  items:
                    type: object
                    required:
                      - host
                      - provider
                      - model
                      - key
                    properties:
                      host:
                        type: string
                        description: LLM provider host URL
                        example: https://api.openai.com
                      provider:
                        type: string
                        enum: [ollama, openai-compatible, anthropic, google]
                        description: Provider type
                      model:
                        type: string
                        description: Model name
                        example: gpt-4o
                      key:
                        type: string
                        description: API key (supports ${ENV[VAR]} syntax)
                        example: ${ENV[OPENAIKEY]}
                test_prompts:
                  type: array
                  items:
                    type: object
                    required:
                      - user_message
                      - temperature
                      - images
                      - max_tokens
                      - use_max_completion_tokens
                    properties:
                      system_message:
                        type: string
                        nullable: true
                      user_message:
                        type: string
                      temperature:
                        type: number
                      images:
                        type: array
                        description: Each image is its raw bytes as an array of integers
                        items:
                          type: array
                          items:
                            type: integer
                            minimum: 0
                            maximum: 255
                      max_tokens:
                        type: integer
                        format: uint32
                      use_max_completion_tokens:
                        type: boolean
                      seed:
                        type: integer
                        format: uint64
                        nullable: true
                      extra:
                        type: object
                        default: {}
                        description: Provider-specific request fields
                      extra_merge_strategy:
                        $ref: '#/components/schemas/MergeStrategy'
                      timeout:
                        oneOf:
                          - type: number
                            nullable: true
                          - type: string
                        description: Seconds as a number, or a string such as `500ms`, `1.5s` or `2m`
            example:
              configs:
                - host: https://api.openai.com
                  provider: openai-compatible
                  model: gpt-4o
                  key: ${ENV[OPENAIKEY]}
              test_prompts:
                - system_message: null
                  user_message: |
                    I am testing that your API works and you are capable for understanding the simplest request.
                    For it I need you to respond with two letters "ok" (without quotes) and nothing else.
                    Lowercase, no repetition or punctuation
                  temperature: 0.2
                  images: []
                  max_tokens: 200
                  use_max_completion_tokens: true
      responses:
        '200':
          description: LLM availability results
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    config_index:
                      type: integer
                    prompt_index:
                      type: integer
                    available:
                      type: boolean
                    error:
                      type: string
                      nullable: true
                    response:
                      type: string
                      nullable: true
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /vm-error/describe:
    get:
      summary: Describe VM error
      description: Get a human-readable description for a VM error code.
      operationId: describeVmError
      parameters:
        - name: error
          in: query
          required: true
          schema:
            type: string
          description: The VM error code to describe
      responses:
        '200':
          description: Error description
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    nullable: true
                    description: Human-readable error description, or null if unknown
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'

components:
  schemas:
    MergeStrategy:
      description: How `extra` merges into the provider request; null means `none`, maps select strategies per key
      default: none
      oneOf:
        - type: string
          nullable: true
          enum: [null, none, replace, merge_left, merge_right]
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/MergeStrategy'

    ModuleStartRequest:
      type: object
      required:
        - module_type
        - config
      properties:
        module_type:
          type: string
          enum: [Llm, Web]
        config:
          type: object
          nullable: true
          description: Module configuration; null loads the module's default config file
        allow_empty_backends:
          type: boolean
          default: false
          description: Start the LLM module even with no valid backend
        user_error:
          type: boolean
          default: false
          description: Load the config but answer every module request with a user error
      example:
        module_type: Llm
        config: null

    Address:
      type: string
      format: hex
      description: A calldata address (20 bytes), shown here in hex
      example: "0x1234567890abcdef1234567890abcdef12345678"

    ExecutorSelector:
      description: Which executor line runs a request
      oneOf:
        - $ref: '#/components/schemas/ExecutorSelectorMajor'
        - $ref: '#/components/schemas/ExecutorSelectorVersion'
      discriminator:
        propertyName: kind
        mapping:
          major: '#/components/schemas/ExecutorSelectorMajor'
          version: '#/components/schemas/ExecutorSelectorVersion'

    ExecutorSelectorMajor:
      type: object
      additionalProperties: false
      description: |
        Resolved by the manifest's rules, falling back to the newest line when
        none provides this major. Cannot separate lines that share a semver
        major, which every released line does
      required:
        - kind
        - major
      properties:
        kind:
          type: string
          enum: [major]
        major:
          type: integer
          format: uint32

    ExecutorSelectorVersion:
      type: object
      additionalProperties: false
      description: |
        Names a line: an executor directory used as it stands, or a `re:`-prefixed
        regular expression over manifest version keys, the newest match winning.
        No match fails the run
      required:
        - kind
        - version
      properties:
        kind:
          type: string
          enum: [version]
        version:
          type: string
          example: "v0.2.17"

    InternalMessageParams:
      type: object
      additionalProperties: false
      required:
        - leader_timeunits_allocation
        - validator_timeunits_allocation
        - execution_budget_per_round
        - rotations
        - max_price_gen_per_time_unit
        - storage_fee_max_gas_price
        - receipt_fee_max_gas_price
      properties:
        leader_timeunits_allocation:
          type: integer
          format: uint256
        validator_timeunits_allocation:
          type: integer
          format: uint256
        execution_budget_per_round:
          type: integer
          format: uint256
        rotations:
          type: array
          items:
            type: integer
            format: uint256
          description: Per-round rotation allocations, the initial round first, then appeal rounds
        max_price_gen_per_time_unit:
          type: integer
          format: uint256
        storage_fee_max_gas_price:
          type: integer
          format: uint256
        receipt_fee_max_gas_price:
          type: integer
          format: uint256

    ExternalMessageParams:
      type: object
      additionalProperties: false
      required:
        - gas_limit
        - max_gas_price
      properties:
        gas_limit:
          type: integer
          format: uint256
        max_gas_price:
          type: integer
          format: uint256

    MessageData:
      type: object
      additionalProperties: false
      description: Contract execution message data
      required:
        - contract_address
        - sender_address
        - origin_address
        - signer_address
        - chain_id
        - value
        - is_init
      properties:
        contract_address:
          $ref: '#/components/schemas/Address'
        sender_address:
          $ref: '#/components/schemas/Address'
        origin_address:
          $ref: '#/components/schemas/Address'
        signer_address:
          $ref: '#/components/schemas/Address'
        chain_id:
          type: integer
          example: 1
        value:
          type: integer
          description: Transaction value
          example: 0
        is_init:
          type: boolean
          description: Whether this is a contract initialization call
        transaction_timestamp:
          type: string
          format: date-time
          default: "2024-11-26T06:42:42.424242Z"
          description: Transaction timestamp

    GenvmRunRequest:
      type: object
      additionalProperties: false
      description: |
        GenVM execution request, encoded as calldata (see the spec's Calldata
        Encoding page) rather than JSON. This schema and every schema it
        references map onto calldata kinds:

        - `integer` is a calldata number, never a decimal string
        - `format: binary` is calldata bytes
        - `Address` is a calldata address, never a hex string
        - `date-time` is an RFC 3339 string
        - `format: uint256` is a number in `[0, 2^256)`

        A value of another kind or an unknown key fails decoding, which the
        socket answers with `malformed_frame`. A required nullable property must
        be present, possibly as null. The range and non-empty-map constraints on
        `bucket_totals` are checked when the run starts, not at decode
      required:
        - selector
        - message
        - is_sync
        - bucket_totals
        - host_data
        - timestamp
        - host
        - calldata
        - code
        - leader_public_data
        - initial_time_units_allocation
      properties:
        selector:
          $ref: '#/components/schemas/ExecutorSelector'
        message:
          $ref: '#/components/schemas/MessageData'
        is_sync:
          type: boolean
          description: Whether execution is synchronous
        debug_mode:
          type: string
          default: disabled
          enum: [disabled, safe, safe-unbounded, unsafe, unsafe-tracing]
          description: |
            Executor debug level (see the Executor "Debug modes" section). Each level
            adds to the previous one and also sets output capture.

            The manager accepts every level as sent, so a host on a consensus network
            must not pass `unsafe` or `unsafe-tracing` from untrusted callers: `unsafe`
            enables `:latest`/`:test` resolution (different nodes may diverge) and
            `unsafe-tracing` exposes real time (breaks single-machine determinism).
        max_execution_minutes:
          type: integer
          format: uint64
          default: 20
          description: Maximum execution time in minutes, capped at 24 hours
        bucket_totals:
          type: object
          minProperties: 1
          additionalProperties:
            type: integer
            format: uint256
          description: |
            Per-bucket data-fee balances, keyed by the non-empty names the
            executor's fee config references
        host_data:
          type: string
          description: JSON object carrying at least string `node_address` and `tx_id`
          example: '{"node_address":"0x00","tx_id":"0x00"}'
        timestamp:
          type: string
          format: date-time
          description: Execution timestamp
        host:
          type: string
          description: Address of host connection 0, `unix://<path>` or a TCP `host:port`
        extra_args:
          type: array
          items:
            type: string
          default: []
          description: Extra arguments for the executor's `run` command
        calldata:
          type: string
          format: binary
          description: Contract calldata (method name and arguments)
        code:
          type: string
          format: binary
          nullable: true
          description: Contract bytecode for a deployment, or null for a call
        leader_public_data:
          type: string
          format: binary
          nullable: true
          description: |
            Opaque executor-owned leader public data for a validator run, or null
            for a leader run
        initial_time_units_allocation:
          type: integer
          format: uint32
          description: Initial time-unit budget for the execution
        permissions:
          type: string
          default: wscn
          description: |
            Permission meta-properties granted to the entry VM, as a subset of the
            characters `w` (write storage), `s` (send messages), `c` (call other
            contracts) and `n` (spawn nondet). **Defaults to all four**, so a host
            that computes narrower permissions must send this field explicitly
        no_modules:
          type: boolean
          default: false
          description: |
            Run without the LLM and web modules even when the permissions would
            otherwise require them
        gas_data:
          type: object
          additionalProperties:
            type: string
          default: {}
          description: Host-provided `node` fee constants
        message_fee_allocation:
          type: array
          items:
            type: object
            additionalProperties: false
            required: [recipient, call_key, budget, 'on', fee_params, children_budget, subtree]
            properties:
              recipient:
                type: string
                format: hex
                nullable: true
                description: Calldata address (20 bytes), or null for an open allocation
              call_key:
                type: string
                format: binary
                minLength: 32
                maxLength: 32
                nullable: true
                description: 32-byte call key, or null for a wildcard
              budget:
                type: integer
                format: uint256
                nullable: true
                description: |
                  Stored chain budget, or the allowance of a synthetic recipient wildcard; null is uncapped.
                  A zero-budget entry with a recipient still matches internal messages and is absent for
                  external ones, as on chain
              'on':
                type: string
                enum: [decided, finalized]
              fee_params:
                type: object
                additionalProperties: false
                minProperties: 1
                maxProperties: 1
                description: Single-key map naming the message kind
                properties:
                  Internal:
                    $ref: '#/components/schemas/InternalMessageParams'
                  External:
                    $ref: '#/components/schemas/ExternalMessageParams'
              children_budget:
                type: integer
                format: uint256
                description: Sum of direct descendant allocation budgets, funded per emitted child
              subtree:
                type: string
                format: binary
                description: Opaque bytes for the matched subtree, including any required Merkle proof
          default: []
          description: |
            Flat funding allocations. The node supplies the exact subtree transport
            bytes for the transaction's pinned storage mode. GenVM forwards these bytes
            unchanged and meters their length. External and open allocations without a
            committed subtree use empty bytes. children_budget and subtree are required
            on every entry, including allocations without descendants.
            Omit allocations absent on-chain. Recipient wildcards are
            synthetic entries for open-pool or view execution, not chain allocations
        record_actions:
          type: array
          items:
            type: string
            enum: [runner_load, vm_spawn]
          default: []
          description: Auditable supervisor action kinds to return in the result
        host_genvm_id:
          type: string
          nullable: true
          default: null
          description: |
            Client correlation token, echoed in this run's events. Also an
            idempotency key on the socket protocol; see the `run` method in the
            manager socket protocol page
        deadline:
          type: string
          nullable: true
          default: null
          example: 30s
          description: |
            Duration, a decimal number followed by `ms`, `s`, `m` or `h`, that
            overrides `max_execution_minutes` as the strict deadline when set.
            Capped at 24 hours
        host_hello_data:
          type: array
          items:
            type: string
            format: binary
          default: []
          description: |
            Bytes written verbatim to each host connection, indexed by connection
            index, before the first method byte. The manager rejects a non-empty
            entry for a connection it owns itself
        hook_cross_contract_calls:
          type: boolean
          default: false
          description: |
            Whether the host wants to answer `resolve_call_contract_executor`. When
            false the manager answers it with a null reply and every `CallContract`
            stays in-process
        unsafe_overrides:
          type: object
          additionalProperties: false
          default: {}
          description: |
            Overrides that reach boundaries production traffic cannot. Each member
            states the `debug_mode` it needs; with debugging disabled none apply
          properties:
            reroute_to:
              type: string
              default: ""
              description: |
                Run this version instead of the one `selector` resolves to, in
                the same two forms `selector`'s version variant accepts. Empty is
                no override. Honored from `safe` up
            initial_recursion:
              type: integer
              format: uint32
              nullable: true
              default: null
              description: |
                Seeds the chain's recursion budget, replacing the executor's own
                `VM_RECURSION`. Honored from `unsafe` up
            allow_two_workers:
              type: boolean
              nullable: true
              default: null
              description: |
                Overrides the manager's `allow_two_workers` config. v0.2 warns
                when false and keeps its existing scheduling.
                Honored from `unsafe` up. Null keeps the configured value

  responses:
    ErrorResponse:
      description: Error response
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message
    NotFound:
      description: The `genvm_id` path segment is not a decimal 64-bit unsigned integer
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Not Found