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

# Database Schema

> LevelDB key-value structure and data models for the Watch Tower

# Database Schema

LevelDB key-value structure and data models for the Watch Tower.

The Watch Tower uses a NoSQL key-value database to store state about programmatic orders and processing progress.

## Storage keys

The database uses four primary keys to manage state:

### LAST\_PROCESSED\_BLOCK

Stores the last block that was successfully processed by the watch-tower.

**Structure:**

```json theme={null}
{
  "number": 12345678,
  "timestamp": 1234567890,
  "hash": "0x..."
}
```

This key is critical for recovery - if the watch-tower crashes or restarts, it resumes processing from this block number.

### CONDITIONAL\_ORDER\_REGISTRY

Contains the registry of all active programmatic orders grouped by owner (safe address).

**Structure:**

```typescript theme={null}
Map<Owner, Set<ConditionalOrder>>
```

Where each `ConditionalOrder` contains:

* `id` - keccak256 hash of the serialized programmatic order
* `tx` - transaction hash that created the order
* `params` - the programmatic order parameters
* `proof` - merkle proof if part of a merkle root, or null for single orders
* `orders` - map of discrete order UIDs to their status (SUBMITTED or FILLED)
* `composableCow` - address to poll for orders
* `pollResult` - result of the last poll with timestamp and block number

As orders expire or are cancelled, they are automatically removed from the registry to conserve storage space.

### CONDITIONAL\_ORDER\_REGISTRY\_VERSION

Stores the schema version number of the programmatic order registry.

**Current version:** `2`

This key is used to migrate the registry when the schema changes. Version 2 added the `id` field to programmatic orders.

### LAST\_NOTIFIED\_ERROR

Tracks the last time an error notification was sent via Slack.

**Structure:**

```json theme={null}
"2024-03-04T12:34:56.789Z"
```

This ISO 8601 timestamp is used to implement rate limiting - no more than one error notification is sent every 2 hours.

<Warning>
  All keys are prefixed with the network identifier (chain ID) to support multi-chain deployments in the same database.
</Warning>

## Data serialization

The database stores complex JavaScript objects (Maps and Sets) by using custom serialization:

* `Map` objects are serialized with a `dataType: "Map"` marker
* `Set` objects are serialized with a `dataType: "Set"` marker
* These are deserialized back to native JavaScript collections on read

This allows efficient storage while preserving the data structure semantics.

## Schema versioning

The registry implements forward-compatible schema migrations:

1. When loading data, the `CONDITIONAL_ORDER_REGISTRY_VERSION` is checked
2. If the version is older than current, data is migrated in-memory
3. The updated version is written back on the next save

Example: Version 1 to 2 migration adds the missing `id` field to all programmatic orders by computing it from the order parameters.