> 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/lib-wasm-lia.md).

# Lia Library

Reference for UrWasm's Lia interpreter

### Lia Interpreter

The `/lib/wasm/lia.hoon` library implements Lia (Language for Invocation of webAssembly), a high-level scripting interface for executing WebAssembly modules within Urbit. Lia provides deterministic execution of Wasm code while maintaining performance through caching and efficient state management.

Lia handles:

* Deterministic execution of Wasm modules.
* Memory read/write operations.
* Function invocation with automatic type conversion.
* Global variable access.
* Import function handling for external calls.

### `$run-input` <a href="#run-input" id="run-input"></a>

```hoon
+$  run-input
  (each (script-raw-form (list lia-value) *) (list lia-value))
```

Input type for [`+run`](#run). Either a new script to execute or cached values from previous execution.

### `+run-once` <a href="#run-once" id="run-once"></a>

```hoon
++  run-once
  |*  [type-yield=mold type-acc=mold]
  |=  [[binary=octs imp=(import type-acc)] hint=term script-in=form:m]
  ^-  [yield:m type-acc]
  ::  ...
```

Build a stateless execution arm for a Wasm module. Takes:

* `.type-yield`: Mold for the yield type.
* `.type-acc`: Mold for the accumulator type.
* `.binary`: WebAssembly module as [`$octs`](/urbit-os/base/wasm/wasm-data-types.md#octs).
* `.imp`: Import function map.
* `.hint`: Execution hint.
* `.script-in`: Lia script to execute.

Returns the script yield and final accumulator state.

#### `+init:run-once` <a href="#init-run-once" id="init-run-once"></a>

```hoon
++  init
  =/  m  (script ,~ type-acc)
  ^-  form:m
  |=  sat=(lia-state type-acc)
  ^-  output:m
  ::  ...
```

Initializes the Wasm module within [`+run-once`](#run-once). Handles module instantiation and processes any required imports by calling external functions.

This is an internal function, it should not be called by Lia scripts directly.

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

```hoon
++  run
  |=  [input=run-input =seed hint=term]
  ^-  [yield:m * _seed]
  ::  ...
```

Stateful execution of a Wasm module. Can be used to run a new script or resume computation with the provided `$seed` state.

#### `+init` <a href="#init-run" id="init-run"></a>

```hoon
++  init
  =/  m  (script ,~ *)
  ^-  form:m
  |=  sat=(lia-state)
  ^-  output:m
```

Initializes the Wasm module within [`+run`](#run). Similar to [`+init`](#init-run-once) in `+run-once` but operates on the monomorphic [`$lia-state`](/urbit-os/base/wasm/lia-data-types.md#lia-state).

This is an internal function, it should not be called by Lia scripts directly.

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

```hoon
++  arrows
  |*  m-acc=mold
  ^?  |%
  ::  ...
```

Core containing Kleisli arrows (monadic operations) for Lia script operations. Type-polymorphic over the accumulator type `.m-acc`.

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

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

Type alias for the polymorphic [`$lia-state`](/urbit-os/base/wasm/lia-data-types.md#lia-state) with accumulator type `.m-acc`.

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

```hoon
++  call
  |=  [name=cord args=(list @)]
  =/  m  (script (list @) m-acc)
  ^-  form:m
```

Invokes a WebAssembly function by name with the given arguments. Performs type conversion from Hoon atoms to [`$coin-wasm`](/urbit-os/base/wasm/wasm-data-types.md#coin-wasm) values and back. Handles import function resolution if the called function is not locally defined.

#### `+call-1` <a href="#call-1" id="call-1"></a>

```hoon
++  call-1
  |=  [name=cord args=(list @)]
  =/  m  (script @ m-acc)
  ^-  form:m
```

Convenience function for calling WebAssembly functions that return exactly one value. Wraps [`+call`](#call) and extracts the single return value.

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

```hoon
++  memread
  |=  [ptr=@ len=@]
  =/  m  (script octs m-acc)
  ^-  form:m
```

Reads `.len` bytes from WebAssembly linear memory starting at address `.ptr`. Returns the data as [`$octs`](/urbit-os/base/wasm/wasm-data-types.md#octs). Performs bounds checking against the current memory size.

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

```hoon
++  memwrite
  |=  [ptr=@ len=@ src=@]
  =/  m  (script ,~ m-acc)
  ^-  form:m
```

Writes `.len` bytes from atom `.src` to WebAssembly linear memory starting at address `.ptr`. Performs bounds checking and fails if the write would exceed memory bounds.

#### `+call-ext` <a href="#call-ext" id="call-ext"></a>

```hoon
++  call-ext
  |=  [name=term args=(list lia-value)]
  =/  m  (script (list lia-value) m-acc)
  ^-  form:m
```

Calls an external (import) function. If no cached result is available, yields the function call request to the host environment. Otherwise returns the cached result.

#### `+global-set` <a href="#global-set" id="global-set"></a>

```hoon
++  global-set
  |=  [name=cord value=@]
  =/  m  (script ,~ m-acc)
  ^-  form:m
```

Sets the value of an exported global variable by name. Verifies the global is mutable and performs type conversion from atom to the appropriate [`$coin-wasm`](/urbit-os/base/wasm/wasm-data-types.md#coin-wasm) type.

#### `+global-get` <a href="#global-get" id="global-get"></a>

```hoon
++  global-get
  |=  name=cord
  =/  m  (script @ m-acc)
  ^-  form:m
```

Gets the value of an exported global variable by name. Returns the value as an atom, performing type conversion from [`$coin-wasm`](/urbit-os/base/wasm/wasm-data-types.md#coin-wasm).

#### `+memory-size` <a href="#memory-size" id="memory-size"></a>

```hoon
++  memory-size
  =/  m  (script @ m-acc)
  ^-  form:m
```

Returns the current size of WebAssembly linear memory in pages. Each page is [`+page-size`](#page-size) bytes (65,536 bytes).

#### `+memory-grow` <a href="#memory-grow" id="memory-grow"></a>

```hoon
++  memory-grow
  |=  delta=@
  =/  m  (script @ m-acc)
  ^-  form:m
```

Grows WebAssembly linear memory by `.delta` pages. Returns the previous memory size in pages. Growing memory preserves existing data and zero-initializes the new pages.

#### `+get-acc` <a href="#get-acc" id="get-acc"></a>

```hoon
++  get-acc
  =/  m  (script m-acc m-acc)
  ^-  form:m
```

Returns the current accumulator value from the Lia state.

#### `+set-acc` <a href="#set-acc" id="set-acc"></a>

```hoon
++  set-acc
  |=  acc=m-acc
  =/  m  (script ,~ m-acc)
  ^-  form:m
```

Sets the accumulator value in the Lia state.

#### `+get-all-local-globals` <a href="#get-all-local-globals" id="get-all-local-globals"></a>

```hoon
++  get-all-local-globals
  =/  m  (script (list @) m-acc)
  ^-  form:m
```

Returns all local (non-import) global variable values as a list of atoms.

#### `+set-all-local-globals` <a href="#set-all-local-globals" id="set-all-local-globals"></a>

```hoon
++  set-all-local-globals
  |=  vals=(list @)
  =/  m  (script ,~ m-acc)
  ^-  form:m
```

Sets all local global variables from a list of atoms. Performs type conversion to the appropriate [`$coin-wasm`](/urbit-os/base/wasm/wasm-data-types.md#coin-wasm) types.

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

```hoon
++  runnable  (script (list lia-value) *)
```

Type alias for the monomorphic script type used by [`+run`](#run).

### `+cw-to-atom` <a href="#cw-to-atom" id="cw-to-atom"></a>

```hoon
++  cw-to-atom
  |=  cw=coin-wasm:wasm-sur
  ^-  @
```

Converts a [`$coin-wasm`](/urbit-os/base/wasm/wasm-data-types.md#coin-wasm) value to an atom. Fails if the coin represents a reference type.

### `+types-atoms-to-coins` <a href="#types-atoms-to-coins" id="types-atoms-to-coins"></a>

```hoon
++  types-atoms-to-coins
  |=  [a=(list valtype:wasm-sur) b=(list @)]
  ^-  (list coin-wasm:wasm-sur)
```

Converts parallel lists of [`$valtype`s](/urbit-os/base/wasm/wasm-data-types.md#valtype) and atoms into a list of [`$coin-wasm`](/urbit-os/base/wasm/wasm-data-types.md#coin-wasm) values. Used for function argument conversion.

### `+valtype-from-coin` <a href="#valtype-from-coin" id="valtype-from-coin"></a>

```hoon
++  valtype-from-coin
  |=  =cw
  ^-  valtype:wasm-sur
```

Extracts the [`$valtype`](/urbit-os/base/wasm/wasm-data-types.md#valtype) from a [`$coin-wasm`](/urbit-os/base/wasm/wasm-data-types.md#coin-wasm) value.

### `+page-size` <a href="#page-size" id="page-size"></a>

```hoon
++  page-size  ^~((bex 16))
```

WebAssembly page size constant: 65,536 bytes.

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

```hoon
++  yield-need
  |*  a=(script-yield *)
  ?>  ?=(%0 -.a)
  p.a
```

Extracts the payload from a successful script yield, crashing if the yield indicates failure or blocking.


---

# 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/lib-wasm-lia.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.