## 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
```

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

## 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.

**`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](https://docs.terminal3.io/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.

## 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.