Response Schemas#

Operations that return data via file descriptor use specific encoding formats based on operation type.

Sub-VM Result Encoding#

Operations that spawn sub-VMs (CallContract, RunNondet, Sandbox) return results through a file descriptor with the following binary format:

[result_code: u8][data: bytes]

Where result_code is a gvm-def-enum-result-code:

  • gvm-def-enum-value-result-code-return (0): Successful execution

  • gvm-def-enum-value-result-code-user-error (1): Contract-initiated error via Rollback

  • gvm-def-enum-value-result-code-vm-error (2): VM-level error

The data portion depends on the result code:

  • return: Calldata Encoded return value

  • user_error: UTF-8 encoded error message string (from Rollback message)

  • vm_error: UTF-8 encoded gvm-def-str-trie-vm-error string

Module Result Encoding#

Operations that invoke external modules (WebRender, WebRequest, ExecPrompt, ExecPromptTemplate) return results as Calldata Encoded data with a success/error wrapper:

// On success
{
  "ok": <result>
}

// On error
{
  "error": <error_details>
}

The <result> structure depends on the operation:

WebRender Response#

Returns one of the following based on render mode:

// For mode "text"
{"ok": {"text": String}}

// For mode "html" (returns HTTP response)
{"ok": {"response": Response}}

// For mode "screenshot"
{"ok": {"image": Bytes}}

Where Response is:

{
  "status": Number,           // HTTP status code (u16)
  "headers": Map,             // String -> Bytes mapping
  "body": Bytes               // Response body
}

WebRequest Response#

{
  "ok": {
    "status": Number,         // HTTP status code (u16)
    "headers": Map,           // String -> Bytes mapping of response headers
    "body": Bytes             // Response body
  }
}

ExecPrompt Response#

// When response_format is "text"
{"ok": String}

// When response_format is "json"
{"ok": Object}

ExecPromptTemplate Response#

// For EqComparative template (boolean result)
{"ok": Bool}

// For EqNonComparativeValidator template (boolean result)
{"ok": Bool}

// For EqNonComparativeLeader template (text result)
{"ok": String}

Module Error Format#

When a module operation fails, the error is returned as:

{
  "error": <GenericValue>
}

Where <GenericValue> may contain error details from the module.