> For the complete documentation index, see [llms.txt](https://docs.urbit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.urbit.org/urbit-os/base/wasm/lia-data-types.md).

# Lia Types

Data types for Lia, Urbit's deterministic Wasm interpreter

The `+lia-sur` core builds on top of `+wasm-sur` and `+engine-sur` to define Lia's monadic approach to making Wasm function calls and handling their results.

### `+lia-sur` <a href="#lia-sur" id="lia-sur"></a>

```hoon
++  lia-sur
  =,  wasm-sur
  =,  engine-sur
  |%
  ::  ...
::  ...
```

Wrapper arm around the Lia core, making its arms and types addressable by limb resolution paths like `lia-value:lia-sur`. Also exposes the `+wasm-sur` and `+engine-sur` namespaces so this core can access the underlying Wasm types.

### `+lia-value` <a href="#lia-value" id="lia-value"></a>

```hoon
++  lia-value
  $~  [%i32 0]
  $%  [%octs octs]
      $<(%ref coin-wasm)
  ==
```

Lia value type. Can be:

* `%octs`: Byte data with length and content (see [`$octs`](/urbit-os/base/wasm/wasm-data-types.md#octs)).
* Any [`$coin-wasm`](/urbit-os/base/wasm/wasm-data-types.md#coin-wasm) except references. That leaves integers, floats and SIMD vectors.

### `+import` <a href="#import" id="import"></a>

```hoon
++  import
  |$  [acc]
  %+  pair  acc
  %+  map  (pair cord cord)
  $-  (list coin-wasm)
  (script-raw-form (list coin-wasm) acc)
```

Wasm module import.

Pair of the given `$acc` accumulator type with a map of imports to functions. Each `(pair cord cord)` key in the map is a cell of \[module-name export-name]. Each value in the map is a gate that takes a list of [`$coin-wasm`](/urbit-os/base/wasm/wasm-data-types.md#coin-wasm) arguments and returns the script.

### `+lia-state` <a href="#lia-state" id="lia-state"></a>

```hoon
++  lia-state
  |$  [acc]
  (trel store (list (list lia-value)) (import acc))
```

Execution state for a Lia script, returning a tuple of:

* [`$store`](/urbit-os/base/wasm/wasm-interpreter-data-types.md#store): Wasm module state.
* Stack of [`+lia-value`s](#lia-value) representing the current script state.
* [`+import`](#import): Available import functions and their implementations.

### `+script-yield` <a href="#script-yield" id="script-yield"></a>

```hoon
++  script-yield
  |$  [a]
  $%  [%0 p=a]
      [%1 name=term args=(list lia-value)]
      [%2 ~]
  ==
```

Result of executing a Lia script step:

* `%0`: Step completed with result of type `$a`.
* `%1`: Step blocked on external call to function `.name`, with the provided list of `.args` for that function to be resolved outside of Lia.
* `%2`: Step crashed or errored.

### `+script-result` <a href="#script-result" id="script-result"></a>

```hoon
++  script-result
  |$  [m-yil m-acc]
  [(script-yield m-yil) (lia-state m-acc)]
```

Mold for the complete result of script execution including:

* [`$script-yield`](#script-yield) with the execution outcome.
* [`$lia-state`](#lia-state) with updated state.

### `+script-raw-form` <a href="#script-raw-form" id="script-raw-form"></a>

```hoon
++  script-raw-form
  |*  [yil=mold acc=mold]
  $-((lia-state acc) (script-result yil acc))
```

Raw form of a Lia script: a gate that takes a [`$lia-state`](#lia-state) and produces a [`$script-result`](#script-result). This represents a stateful computation in the Lia monad.

### `+script` <a href="#script" id="script"></a>

```hoon
++  script
  |*  [m-yil=mold m-acc=mold]
  |%
  ::  +output
  ::  +yield
  ::  +form
  ::  +m-sat
  ::  +return
  ::  +try
  ::  +catch
  --
```

Monadic interface for Lia scripts with yield mold `.m-yil` and accumulator mold `.m-acc`.

#### `+output` <a href="#output" id="output"></a>

```hoon
++  output  (script-result m-yil m-acc)
```

Final `$script-result` of this script.

#### `+yield` <a href="#yield" id="yield"></a>

```hoon
++  yield  (script-yield m-yil)
```

Final `$script-yield` of this script.

#### `+form` <a href="#form" id="form"></a>

```hoon
++  form  (script-raw-form m-yil m-acc)
```

Built script mold, analogous to `+form:m` from thread [strands](/urbit-os/base/threads/basics/fundamentals.md#strands).

#### `+m-sat` <a href="#m-sat" id="m-sat"></a>

```hoon
++  m-sat  (lia-state m-acc)
```

Execution state for this script with the provided `.m-acc`.

#### `+return` <a href="#return" id="return"></a>

```hoon
++  return  ::  pure
  |=  arg=m-yil
  ^-  form
  |=  s=m-sat
  [0+arg s]
```

Monadic (pure) return: lifts a value into the Lia monad without changing script state.

#### `+try` <a href="#try" id="try"></a>

```hoon
++  try  ::  monadic bind
  |*  m-mond=mold
  |=  [mond=(script-raw-form m-mond m-acc) cont=$-(m-mond form)]
  ^-  form
  |=  s=m-sat
  =^  mond-yil=(script-yield m-mond)  s  (mond s)
  ^-  output
  ?.  ?=(%0 -.mond-yil)  [mond-yil s]
  ((cont p.mond-yil) s)
```

Monadic bind: sequences two computations, passing the result of the first to the second if successful (`%0`). Handles early termination for blocked (`%1`) or crashed (`%2`) states.

#### `+catch` <a href="#catch" id="catch"></a>

```hoon
++  catch  ::  bind either
  |*  m-mond=mold
  |=  $:  $:  try=(script-raw-form m-mond m-acc)
              err=(script-raw-form m-mond m-acc)
          ==
          cont=$-(m-mond form)
      ==
  ^-  form
  |=  s=m-sat
  =^  try-yil=(script-yield m-mond)  s  (try s)
  ^-  output
  ?:  ?=(%0 -.try-yil)
    ((cont p.try-yil) s)
  ?:  ?=(%1 -.try-yil)
    [try-yil s]
  =^  err-yil  s  (err s)
  ?.  ?=(%0 -.err-yil)  [err-yil s]
  ((cont p.err-yil) s)
```

Error handling combinator: attempts the first computation, and if it crashes (`%2`), tries the error handler. Blocked states (`%1`) are propagated immediately.

### `$seed` <a href="#seed" id="seed"></a>

```hoon
+$  seed
  $:
    module=octs
    past=(script-raw-form (list lia-value) *)
    shop=(list (list lia-value))
    import=(import *)
  ==
```

Complete Lia interpreter state containing all necessary components for module execution:

* `.module`: Wasm module binary data.
* `.past`: Previously executed script that established the current state.
* `.shop`: External results accumulator - lists of values from resolved import function calls.
* `.import`: Map of available import functions that the module can call.

This represents the "formal state" of the Lia interpreter, suitable for caching and resuming if necessary.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.urbit.org/urbit-os/base/wasm/lia-data-types.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.