Storage Namespaces - Terminal 3 Documentation

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>

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