NAP domain reference
A NAP (Nostr Applet Protocol) is one capability contract between a napplet and its runtime — what the runtime provides (relay access, storage, intents, …) and exactly how a napplet asks for it. On the web, NIP-5D binds each NAP to a message domain: a NAP named foo owns all foo.* JSON envelope messages, their payload shapes, and the expected shell behavior. NAP contracts are proposed and maintained in the NAPs track.
This reference is non-normative. Every domain page defers to its living proposal in the NAPs track, which governs protocol behavior.
The protocol is modular by design. A NAP must be independently implementable, and shells may support any subset of NAPs. That's why napplets feature-gate with injected domain property presence before using a domain and degrade gracefully when it's absent — see Core concepts.
Domains by purpose
Each domain has its own page with its purpose, a minimal example, and its implementation maturity. Examples assume the runtime injected window.napplet before napplet code ran; the same calls are also importable as named helpers from @napplet/sdk, and each domain ships as a subpath of @napplet/nap (barrel / types / shim / sdk).
Runtime and environment
| Domain | Purpose | Maturity |
|---|---|---|
shell | Optional environment snapshot, readiness, and domain presence checks. | supported |
theme | Read-only shell theme — colors, fonts, background, and live updates. | supported |
config | Schema-driven per-napplet settings rendered and persisted by the shell. | exploratory |
keys | Named actions and keyboard bindings owned by the shell. | experimental |
notify | Shell-rendered notifications, badges, and action callbacks. | experimental |
media | Media sessions with shell-side playback controls. | supported |
link | User-visible external link opening under shell policy. | supported |
Identity and social
| Domain | Purpose | Maturity |
|---|---|---|
identity | Read-only user queries — pubkey, profile, follows. Never signs. | supported |
common | Common social actions — follows, reactions, reports, NIP-19 helpers. | experimental |
lists | NIP-51 list add/remove with runtime-owned signing and encryption. | experimental |
dm | Direct-message conversations, history, and sending via the runtime. | experimental |
Nostr events and relays
| Domain | Purpose | Maturity |
|---|---|---|
outbox | Outbox-aware reads and publishes — the default event boundary. | supported |
relay | Low-level relay proxy for explicit relay-local behavior. | supported |
count | Aggregate counts for NIP-01 filters. | experimental |
Napplet to napplet
| Domain | Purpose | Maturity |
|---|---|---|
inc | Topic-based publish/subscribe between running napplets. | supported |
intent | URI-addressed intents routed to a handler napplet. | supported |
Data, files, and network
| Domain | Purpose | Maturity |
|---|---|---|
storage | Scoped key-value storage isolated per napplet. | supported |
fs | Virtual filesystem — pickers, reads, writes, and change events. | experimental |
resource | Sandboxed byte fetching over https, blossom, nostr, and data URIs. | supported |
upload | File and blob upload over NIP-96 and Blossom rails. | supported |
cvm | ContextVM bridge — MCP tools and resources over Nostr. | experimental |
Devices and realtime
| Domain | Purpose | Maturity |
|---|---|---|
gamepad | Focus-scoped controller snapshots. | supported |
ble | Bluetooth LE / GATT sessions with opaque session ids. | experimental |
serial | User-approved serial port sessions. | experimental |
webrtc | Runtime-owned WebRTC sessions carrying application payloads. | experimental |
AI
| Domain | Purpose | Maturity |
|---|---|---|
llm | User-selected language model inference through the runtime. | exploratory |
Implementation maturity
These release-time labels describe our shipped implementation, separately from upstream proposal status. Supported does not mean frozen; experimental does not waive conformance requirements. All capabilities remain subject to change. See maturity and opt-in policy.
| Domain | Implementation maturity | Proposal status | Assessment |
|---|---|---|---|
shell | supported | merged | Optional readiness and environment binding has focused shim and reference-runtime coverage. |
relay | supported | in-review | Relay reads, publishing, and subscription lifecycle have maintained shim and integration tests; upstream naming remains under review. |
identity | supported | merged | Read-only identity queries and updates have focused binding and reference-runtime coverage. |
storage | supported | in-review | Key-value binding has focused request/result tests and tutorial usage; host storage isolation remains the host responsibility. |
inc | supported | merged | Topic and channel bindings have compatibility tests and authenticated-endpoint reference-runtime coverage. |
theme | supported | merged | Theme queries and pushed updates have focused binding and opaque-iframe integration coverage. |
keys | experimental | in-review | Keyboard binding ships, but dedicated domain regression coverage is limited; retain explicit evaluation opt-in. |
media | supported | in-review | Session creation and playback binding have focused regression coverage; proposed torrent playback amendments are not implied. |
notify | experimental | in-review | Notification binding ships with limited dedicated domain regression evidence; broader host integration confidence is unverified. |
config | exploratory | draft | Configuration binding is tested, but the upstream draft is marked MAY DEFER; use for design exploration. |
resource | supported | in-review | Resource fetching has focused shim and type tests; the reverted merge and reopened proposal do not change that implementation assessment. |
cvm | experimental | in-review | Session and registry bindings are tested; upstream explicitly marks the contract NEEDS WORK. |
outbox | supported | in-review | Routing and subscription bindings have focused tests and an integration regression for structured-clone boundaries. |
upload | supported | in-review | Upload binding has focused tests for request/result behavior; host rail support remains runtime-specific. |
intent | supported | merged | Convention normalization and dispatch have focused binding and reference-runtime integration tests. |
ble | experimental | in-review | GATT binding has unit coverage; real-device behavior across host backends is not established by these tests. |
webrtc | experimental | in-review | Signaling and session binding have unit coverage; interoperable live peer sessions remain unverified here. |
link | supported | in-review | The small link-opening binding has focused regression coverage; navigation authorization stays with the host. |
count | experimental | in-review | Count binding is tested, but accuracy and aggregation across real relay backends remain outside that evidence. |
lists | experimental | in-review | List mutation binding is tested; concurrent real-host mutation behavior is not established by binding tests. |
serial | experimental | in-review | Serial binding has unit coverage; device and native-host integration evidence is limited. |
fs | experimental | in-review | Filesystem binding has MVP coverage; portability and authorization across storage backends remain under evaluation. |
common | experimental | in-review | Social action binding is tested; broader host integration and evolving action semantics warrant explicit opt-in. |
dm | experimental | draft | Direct-message binding has shim and type coverage; transport interoperability is not established by those tests. |
gamepad | supported | in-review | Cross-repository delivery includes binding, security, runtime, and conformance verification; the reopened proposal is still subject to change. |
llm | exploratory | draft | Early published draft has binding and mock-runtime tests; provider behavior and API design remain exploratory. |
Core domain union
@napplet/core exports a NapDomain string union for the foundational domains — shell, relay, identity, storage, inc, theme, keys, media, notify, config, resource, cvm, outbox, upload, intent, ble, webrtc, link, count, lists, serial, fs, common, dm, gamepad, llm — used as the discriminant for envelope routing and domain presence.
Where to go next
@napplet/nap— the package and its subpath patterns@napplet/sdk— typed helpers and per-domain message unions- NIP-5D explained — the NAP framework