> ## Documentation Index
> Fetch the complete documentation index at: https://docs.herodotus.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# State Server

> Run and use the HDP state_server for injected state proofs

`state_server` is a REST API for managing persistent Merkle tries used by HDP injected state workflows.

It is different from [HDP Server API](/data-processor-api/introduction):

* **State Server**: injected-state trie service (`/create_trie`, `/read`, `/write`, `/get_state_proofs`).
* **HDP Server API**: orchestrated HDP task execution service (`/tasks`, task status, task outputs).

Repository:

* [hdp-cairo/crates/state\_server](https://github.com/HerodotusDev/hdp-cairo/tree/main/crates/state_server)

## What it provides

* Create and manage multiple tries by label
* Read and write key/value pairs
* Return trie roots for specific states
* Generate inclusion/non-inclusion and update proofs
* Persist trie data in SQLite-backed storage

## Run the server

```bash theme={null}
cargo run --release --bin state_server -- --host 0.0.0.0 --port 3000 --db_root_path db
```

Common options:

* `--host` (default `0.0.0.0`)
* `--port` (default `3000`)
* `--db_root_path` (default `db`)

Set HDP to use it with:

```bash theme={null}
INJECTED_STATE_BASE_URL=http://localhost:3000
```

## Core endpoints

* `POST /create_trie`
* `GET /read`
* `POST /write`
* `POST /get_state_proofs`
* `GET /get_trie_root_node_idx`

### Endpoint behavior

* `POST /create_trie`: create a trie label with initial keys/values
* `GET /read`: read a key for a specific trie root
* `POST /write`: upsert key/value and return the new trie root
* `POST /get_state_proofs`: generate proof payloads for read/write actions
* `GET /get_trie_root_node_idx`: resolve the internal node index for a root

## Quick examples

Create trie:

```bash theme={null}
curl -X POST http://localhost:3000/create_trie \
  -H "Content-Type: application/json" \
  -d '{
    "trie_label": "0x123",
    "keys": ["0x1", "0x2"],
    "values": ["0x42", "0x84"]
  }'
```

Read key:

```bash theme={null}
curl "http://localhost:3000/read?trie_label=0x123&trie_root=0x0&key=0x1"
```

Write key:

```bash theme={null}
curl -X POST http://localhost:3000/write \
  -H "Content-Type: application/json" \
  -d '{
    "trie_label": "0x123",
    "trie_root": "0x0",
    "key": "0x4",
    "value": "0x168"
  }'
```

Get state proofs:

```bash theme={null}
curl -X POST http://localhost:3000/get_state_proofs \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {
        "Read": {
          "trie_label": "0x123",
          "trie_root": "0x0",
          "key": "0x1"
        }
      }
    ]
  }'
```

All trie labels, keys, values, and roots are felt-compatible values (hex or decimal strings).

## HDP integration

In HDP flows, injected-state handlers use the state server during dry/fetch phases, and the resulting proofs are consumed during [sound-run](/data-processor/pipeline).

### End-to-end usage with HDP

This is the practical flow most teams use:

1. Start `state_server`
2. Set `INJECTED_STATE_BASE_URL`
3. Run `dry-run` with `--injected_state`
4. Run `fetch-proofs` (state proofs are pulled from state server)
5. Run `sound-run` with the same `--injected_state` file

Example:

```bash theme={null}
# 1) Start state server
cargo run --release --bin state_server -- --host 0.0.0.0 --port 3000 --db_root_path db

# 2) Point HDP to state server
export INJECTED_STATE_BASE_URL=http://localhost:3000

# 3) Run HDP pipeline with injected state
hdp dry-run -m target/dev/example_injected_state_module.compiled_contract_class.json \
  --injected_state examples/injected_state/injected_state.json \
  --print_output

hdp fetch-proofs

hdp sound-run -m target/dev/example_injected_state_module.compiled_contract_class.json \
  --injected_state examples/injected_state/injected_state.json \
  --print_output
```

During this flow:

* `dry-run` records injected-state read/write actions,
* `fetch-proofs` converts those actions into state proof payloads,
* `sound-run` verifies those proofs before your Cairo logic consumes the values.

### Cairo-side usage in modules

In your module, use `hdp.injected_state` helpers:

```cairo theme={null}
let root = hdp.injected_state.read_injected_state_trie_root('my_trie');
let maybe_value = hdp.injected_state.read_key('my_trie', 'my_key');
let new_root = hdp.injected_state.write_key('my_trie', 'my_key', 42);
```

### Working example to copy from

* Module: [examples/injected\_state/src/lib.cairo](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/injected_state/src/lib.cairo)
* Run script: [examples/injected\_state/run.sh](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/injected_state/run.sh)
* Injected state input: [examples/injected\_state/injected\_state.json](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/injected_state/injected_state.json)

See:

* [State management](/data-processor/state-management)
* [Examples (`injected_state`)](/data-processor/examples)
* [Debugging](/data-processor/debugging)