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

# Storage Namespaces

> Tenant-owned TEE contracts and data are named in z-namespace

## Overview

T3N is a confidential-computing network. TEE contracts and data run inside hardware-secured TEE nodes. Data are stored in a shared key-value (KV) store, and that store is divided into namespaces so tenant data and T3N data stay isolated.

A namespace is a prefix on a map name. T3N uses that prefix to route each KV operation through the right access policy. There are two main worlds of namespaces:

* **Tenant-owned namespaces (`z:`)** — open-ended. Tenants create maps and TEE contracts at runtime (i.e., register new maps and contracts while the cluster is running; do not need to be built into the T3N node ahead of time), and access is governed dynamically by tenant identity, contract identity, and map policy.
* **T3N-owned namespaces (everything else)** — fixed. These are system maps such as `users`, `auth`, `dids`, `scripts`, `outbox_*`, and`idx:_tenant_*`, with strict built-in rules.

## Canonical format

As an external developer, your TEE contracts and data belongs in z-namespace. Every z-namespace resource uses this canonical name: `z:<tid>:<tail>`

| Part     | Meaning                                           | Example             |
| -------- | ------------------------------------------------- | ------------------- |
| `z:`     | Marks a tenant-owned resource                     | `z:`                |
| `<tid>`  | 40-hex suffix of your tenant DID, `did:t3n:<tid>` | `8f3a...c91d`       |
| `<tail>` | Tenant-local map or contract name                 | `secrets, bookings` |

Example:
`z:8f3a0123456789abcdef0123456789abcdefc91d:secrets`

```
All KV maps can be categorized as either:
|-- System maps
|   |-- users, auth, dids, scripts, outbox_*
|   `-- idx:_tenants, idx:_tenant_contracts, idx:_tenant_maps
|
`-- Tenant maps
    |-- z:<your-tid>:secrets
    |-- z:<your-tid>:bookings
    |-- z:<your-tid>:public:profile
    `-- z:<other-tid>:secrets
```

<Note>Use the full canonical name when documenting, debugging, or reading audit output. High-level SDK helpers may ask only for the tenant-local tail.</Note>

## Access model

T3N enforces tenant-map policy in the governed transaction path before writes commit. By default, a tenant contract can access only maps allowed by that map's policy:

* Writers controls which **tenant contracts** may write.
* Readers controls which **tenant contracts** may read.
* If readers is omitted on map creation, it defaults from writers.
* Cross-tenant access is denied unless the map owner explicitly grants another tenant contract access.

This means cross-tenant access is possible by deliberate policy, but not by accident.

<Warning>
  **`writers`/`readers` gate your contracts, not you.** They confine which *contracts* may touch a map at runtime. They do **not** restrict the map's owner. As the tenant that owns a map, you can always write or delete its entries directly through the authenticated control plane — e.g. `tenant.executeControl("map-entry-set", …)` — regardless of a `writers: { only: [...] }` grant. (This is exactly how [seeding an API key](/developers/adk/tips/seed-api-key) writes into a contract-only `secrets` map.)

  So a "contract-only" map is **not tamper-proof against its own owner** — the ACL is a boundary between *your contracts* (and other tenants), not an integrity guarantee against you. If you need an audit trail that even the owner cannot silently rewrite, the map ACL is the wrong tool; that calls for a host-stamped, append-only primitive, which T3N does not yet expose.
</Warning>

## Public tenant maps

A tenant-public map must use both:

```
z:<tid>:public:<tail>
visibility = Public
```

Public maps are for data that is safe to expose. Never store PII, secrets, API keys, session data, or user-authentication material in a public map. Public visibility does not automatically let another tenant contract read through the authenticated contract path. Cross-tenant contract reads still require an explicit grant.

## User PII

Tenant contracts cannot directly read the T3N users system map. Treat user profile data as outside z-space. If a product flow needs user profile fields, use the approved host capability path for that cluster. Do not copy PII into tenant maps just to make it easier for a contract to read.

## Rules of thumb

* Use `z:<tid>:<tail>` for canonical tenant names.
* Use SDK tail inputs when the SDK asks for a tenant-local name.
* Keep secrets and private contract state in private maps.
* Put public data only under `z:<tid>:public:<tail>`.
* Set readers and writers deliberately.
* Use explicit grants for intentional cross-tenant contract access.
* Never put PII in public maps.
* Do not expect tenant contracts to read platform maps directly.