30817:ea8ce2ec-1dd6-425f-8fcc-51bd4f266188
NIP-SHORT
NIP-SHORT defines short, compact references for Nostr events. Instead of sharing a long `nevent1…`, `naddr1…`, or `note1…`, the author embeds a compact code **directly inside the event** as a single-letter tag. A client resolves a short address to its event with a single relay query and verifies it locally.
Edit: There's now a release event for this, as well as knowing how many clients adopted this, on https://nostr-ps.top/s1inn863mrxnuddgjqwzcreuerriwek814mxztdza1uc454d16ocb09d7
NIP-SHORT: Shortened Event Addresses for Nostr
Summary
NIP-SHORT defines short, compact references for Nostr events. Instead of sharing a long nevent1…, naddr1…, or note1…, the author embeds a compact code directly inside the event as a single-letter tag. A client resolves a short address to its event with a single relay query and verifies it locally.
A short address is formed by a leading marker, the author's public key in base 36, and a fixed-width code:
s<key36><code>
Where:
s→ the short-address marker, signaling that the string is a NIP-SHORT address (see Client Recognition)key36→ the event author's public key, encoded in base 36 as exactly 50 characters (see Author Key Encoding)code→ 6 lowercase hex characters deterministically derived from the event (see Derivation)
Example:
s5ininr1pe6onndbb89gw173g9j6swrdy5o2b4jccprabuun8yh1f4c2a
For reference: this short address is 57 characters, while the same event as a nevent (id, author, and kind, with no relay hints) is 132 characters. With future methods that shorten the author part, it could come down to as few as about 15 characters (see Can it be shorter?).
In the rare event of a collision, the address gains a client-side selector suffix (see Collision Handling); the marker, the base code, and the stored event never change.
Because the code lives inside the event itself, there is no separate mapping event to publish, maintain, or lose, and no batching to manage. The mapping is intrinsic to the event: if the event exists, its short address resolves; if the event is gone, there is nothing to resolve to. There is no disconnect state.
Motivation
Nostr references are long. A single nevent1… or naddr1… runs well past a hundred characters, and users consistently find them unpleasant to share: they clutter a message, wrap across several lines, and — because a long opaque string reads as suspicious — recipients often hesitate to click them, mistaking a legitimate reference for spam or a tracking link.
To cope, many users route their post links through centralized URL shorteners. This reintroduces the exact fragility Nostr exists to avoid: the shortened link now depends on a single third-party service. If that service deletes the link, changes its policy, or shuts down, the reference breaks permanently — even though the underlying event may still be perfectly available on relays. A censorship-resistant network ends up with its most-shared references sitting behind a centralized chokepoint that can rot or disappear.
NIP-SHORT solves this natively. It produces a compact reference with a fixed, predictable shape, carries no third-party dependency, and resolves through ordinary relays with mandatory client-side verification. The only thing that can break the link is the author deleting the event it points to; there is no external service in the path to fail, and no centralized party that can take it down.
Design Principles
- One lookup. Resolution is a single relay query scoped to the author.
- No dependencies beyond NIP-01. The author is identified by their public key itself, re-encoded locally in base 36; no name service or other infrastructure is involved.
- Self-contained. The short code is a signed field of the event; no external index can drift, break, or be deleted independently.
- Deterministic & verifiable. Any client can recompute the code from the fetched event and confirm it. The tag is only a relay-side filter hint; trust comes from recomputation plus the event's own signature.
- Author-scoped. The code only needs to be unique within a single author's events, so it can be short. Author scoping also removes any spam/pollution vector — only the author's own events can ever match.
Author Key Encoding
The author component of the address is the author's 32-byte public key written in base 36, using the lowercase alphabet 0123456789abcdefghijklmnopqrstuvwxyz. It carries exactly the same information as the hex pubkey or the npub, in fewer characters (50, against 64 for hex and 63 for npub).
Encoding (pubkey → key36):
- Read the 64-character hex pubkey as one unsigned 256-bit big-endian integer.
- Write that integer in base 36 using the alphabet above.
- Left-pad with
0to exactly 50 characters.
Decoding (key36 → pubkey):
- Lowercase the 50 characters and read them as one base-36 integer.
- Reject the address if the integer is 2²⁵⁶ or greater (any key36 above
6dp5qcb22im238nr3wvp0ic7q99w035jmy2iw7i6n43d37jtof). Such strings correspond to no pubkey. - Write the integer as 64 lowercase hex characters, left-padded with
0. This is the pubkey used in relay queries; clients that display the author convert it to annpubas usual.
Rules:
- key36 is always exactly 50 characters. Every 256-bit pubkey fits in 50 base-36 digits, so every author gets the same length; shorter values are padded with leading zeros. The fixed width is what lets clients parse the address by position.
- The canonical form is lowercase. Clients MUST produce lowercase and SHOULD accept uppercase by lowercasing before decoding.
- Conversion is exact and lossless in both directions: each pubkey has exactly one key36, and each valid key36 has exactly one pubkey.
- key36 has no checksum. A mistyped key36 decodes to a different, effectively random pubkey that in practice belongs to no one, so the relay query simply finds nothing.
Example:
hex dd664d5e4016433a8cd69f005ae1480804351789b59de5af06276de65633d319 (64)
npub npub1m4ny6hjqzepn4rxknuq94c2gpqzr29ufkkw7ttcxyak7v43n6vvsajc2jl (63)
key36 5ininr1pe6onndbb89gw173g9j6swrdy5o2b4jccprabuun8yh (50)
Reference implementation (JavaScript):
const toKey36 = (hex) => BigInt("0x" + hex).toString(36).padStart(50, "0");
const fromKey36 = (k) => {
k = k.toLowerCase();
if (!/^[0-9a-z]{50}$/.test(k)) throw new Error("invalid key36");
let n = 0n;
for (const c of k) n = n * 36n + BigInt(parseInt(c, 36));
if (n >= 1n << 256n) throw new Error("invalid key36");
return n.toString(16).padStart(64, "0");
};
The Short Tag
The author attaches a single-letter tag s to the event:
["s", "<code>"]
code→ the 6-character hex code (see Derivation). The tag value is always exactly the 6-char code — never the marker and never a collision suffix (those exist only in the shared address string).- The tag value does not include the author, since the author is the key36 component of the short address and is supplied as the
authorsfilter at resolution time.
Note on the two
s's. The address markers(the first character of the shareable string) and the event tags(a key inside the signed event) share a letter but are unrelated in parsing. The marker never appears in the event; the tag value is never the marker. They are handled in entirely separate contexts.
The single-letter tag s is indexed by relays per NIP-01 and is therefore queryable via a #s filter.
Coexistence with other uses of the s tag. Another specification may use a single-letter s tag for an unrelated purpose (a status, a label, and so on). This does not interfere with NIP-SHORT in either direction, for several compounding reasons:
- Relay filters are exact-match on the value. A
#squery returns only events whosesvalue is exactly the queried string. A NIP-SHORT code is always 6 lowercase hex characters — a narrow, constrained value space — so it is very unlikely to equal a status or label that another use would store (a few English words such asfacadeordecadeare valid 6-hex strings). Even when values coincide, the next two points ensure such events are never mistaken for one another. - NIP-SHORT resolution is author-scoped. Every lookup filters by
authors: [<pubkey>], so only the addressed author's own events are ever considered. - NIP-SHORT verifies before trusting. For each candidate the client reads the kind, recomputes the code from the event, and checks the signature. Anything that matched the
svalue by coincidence but is not the intended event fails this step and is discarded. - The reverse holds too. NIP-SHORT
stags do not disturb another use's#squeries, since those filter by their own event kinds and their own exactsvalues — neither of which a NIP-SHORT event carries.
The only shared resource is the relay-side s index, which simply holds more entries; correctness is unaffected.
Example event carrying its own short address:
{
"kind": 30023,
"pubkey": "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d",
"created_at": 1766200252,
"tags": [
["d", "my-article-slug"],
["title", "On Short Addresses"],
["s", "272756"]
],
"content": "..."
}
Derivation
The code is the first 6 lowercase hexadecimal characters of the SHA-256 digest of a canonical input string. The canonical input depends only on the event's stable identity and never on the event's tags — this is what avoids the self-reference problem (a code that fed into the event id, which in turn covers the tags, would be impossible to compute) and also makes the code independent of NIP-13 proof-of-work nonces.
There are two canonical inputs, selected by the event's kind. Both order the fields as kind, then pubkey, so the coordinate form is literally the standard NIP-01 coordinate string.
Coordinate-based (replaceable & addressable)
Applies when:
kind == 0 || kind == 3 || 10000 <= kind < 20000 || 30000 <= kind < 40000
Canonical input:
"a:" + <coordinate>
where <coordinate> is the standard NIP-01 a-tag / naddr coordinate string, kind + ":" + pubkey_hex + ":" + d_value:
- Addressable events fill the
dslot, e.g.a:30078:<hexpubkey>:my-slug. - Replaceable events (kinds
0,3,10000–19999) have nodtag, sod_valueis the empty string and the input ends in a trailing colon, e.g.a:0:<hexpubkey>:.
Do not strip the trailing colon. It is not decorative — it is the empty
dslot of the canonical coordinate string that every Nostr coordinate serializer already produces. Building this input as"a:" +your existing coordinate helper's output is automatically correct; special-casing the emptydto drop the colon would diverge from standard tooling and silently mismatch other implementations.
Because the code derives from the stable coordinate, it does not change when the author edits the event. A short link to a long-form article (or to a profile) survives every revision.
Content-based (regular events)
Applies to all other kinds (regular events such as kind 1).
Ephemeral kinds (
20000–29999) are not stored by relays, so a short address for one can never be resolved after the fact. Clients SHOULD NOT generate short addresses for ephemeral events.
Canonical input:
"e:" + kind + ":" + pubkey_hex + ":" + created_at + ":" + content
Regular events are immutable (a "note" is never edited — a new note is posted instead), so this input is inherently stable.
The a: / e: prefixes
The one-character prefix does two jobs: it domain-separates the two input forms so a coordinate input and a content input can never collide, and it is a mnemonic matching Nostr's own tag conventions — the a tag references an event by coordinate (the replaceable/addressable case) and the e tag references an event by id (the regular case). Any two distinct prefixes would work; a/e are chosen to make intent obvious.
Notes
pubkey_hexis the 64-character lowercase hex public key — not the key36 or thenpub. (key36 appears only in the shareable address, never in the hash.)- The digest is computed over the UTF-8 bytes of the canonical input.
- The base code width (6 hex ≈ 16.7M values) is fixed. Because uniqueness is only required within one author's events, 6 hex is ample; the collision path below covers the rare exception.
- The full digest is read left to right: the first 6 characters are the
code; the 7th, 8th, … characters are the collision-selector extension used only when disambiguation is needed (see Collision Handling).
Worked examples
Using pubkey 3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d:
Addressable (kind 30023, the example event above):
SHA-256("a:30023:3bf0c63f…aefa459d:my-article-slug") → 272756b85b… → code 272756
Addressable (kind 30078):
SHA-256("a:30078:3bf0c63f…aefa459d:my-slug") → ca2bd3cc3a… → code ca2bd3
Replaceable (kind 0, profile):
SHA-256("a:0:3bf0c63f…aefa459d:") → a5d08363ab… → code a5d083
Regular (kind 1, note):
SHA-256("e:1:3bf0c63f…aefa459d:1766200252:gm") → f756cae03a… → code f756ca
(The pubkey is abbreviated here; the hash input always uses the full 64 characters.)
Creating a Short Address (Publishers)
-
Finalize the event's identity-determining fields, select the canonical input for the kind, and compute
code = first 6 hex of SHA-256(canonical_input). -
Run a single scoped collision query, with a recommended 1–2 second timeout:
{ "authors": ["<pubkey_hex>"], "#s": ["<code>"] }One query at the base width is sufficient: any event sharing a longer prefix necessarily shares the 6-char prefix, so the returned set is the complete collision set. (This holds precisely because the stored tag is always 6 — nothing is hidden in a deeper exact-match bucket.)
-
Empty result (or timeout): publish the event with
["s", code]. The short address is"s" + key36 + code. -
Non-empty result: recompute the full SHA-256 hash of each returned event (using its kind-appropriate canonical input):
- If any candidate's full hash equals this event's full hash, it is the same event:
- Coordinate-based kinds: the candidate is an earlier version of this event (same coordinate). This is an edit, not a collision — publish normally with the same
["s", code]and the same short address. - Regular kinds: the candidate is an identical post (same kind, author,
created_at, and content) — do not publish; surface "already exists".
- Coordinate-based kinds: the candidate is an earlier version of this event (same coordinate). This is an edit, not a collision — publish normally with the same
- Otherwise this is a genuine collision. Still store
["s", code](the tag stays 6). Generate the shareable address with a selector suffix:"s" + key36 + code + "-" + <extra hex>, where the extra hex is the fewest additional characters of this event's hash needed to make it unique among the returned candidates (see Collision Handling).
- If any candidate's full hash equals this event's full hash, it is the same event:
Proof-of-work. Because the code excludes tags, adding a NIP-13 nonce tag does not change it, so the collision query MAY run in parallel with PoW mining. Caveat: if the PoW miner also mutates created_at, then for content-based (regular) events the code depends on created_at and MUST be computed after mining settles. Coordinate-based events are independent of both the nonce and created_at, so they may always parallelize.
Editing coordinate-based events. When republishing (editing) a replaceable or addressable event, the author MUST carry the s tag forward. The code is unchanged (the coordinate is stable), and because these kinds replace by coordinate, resolution naturally returns the latest version.
Publishers SHOULD publish to both their configured write relays and the client's default relay set to maximize discoverability (see FAQ).
Resolution (Clients)
Given a short address, e.g. s5ininr1pe6onndbb89gw173g9j6swrdy5o2b4jccprabuun8yh1f4c2a or the same address with a -a5 selector suffix:
1. Parse
- Strip the leading
smarker. - If the remainder contains a
-, split there: the left part iskey36 + code, the right part is the selector suffix. - The left part is always 56 characters: the first 50 are the
key36, the last 6 are thecode. Any other length means the address is invalid. - The full selector prefix a candidate must match is
code + suffix(equal to justcodewhen there is no suffix).
2. Decode the key
Decode key36 to the 64-char hex pubkey (see Author Key Encoding). If it contains characters outside [0-9a-z] or its value is 2²⁵⁶ or greater, the address is invalid. This step is local and needs no network.
3. Query relays
A single filter, scoped to the author:
{ "authors": ["<pubkey_hex>"], "#s": ["<code>"] }
No kind filter is required; the kind is read from each returned event.
4. Verify each candidate (MANDATORY)
For every returned event:
- Read its
kind, select the matching canonical input, recompute the code, and confirm it equals the address'scode. - Validate the event signature (standard NIP-01).
Discard any event that fails either check. The s tag alone is never trusted — it is only a relay-side index; authenticity comes from recomputation plus the signature.
5. Select and present
- Selector suffix present: recompute each verified candidate's full hash and keep the one whose hash starts with
code + suffix. Exactly one should remain → render it silently. - No suffix, one verified candidate: render it.
- Multiple candidates that the address cannot disambiguate (no suffix, or a stale suffix matching more than one): present a disambiguation UI; do not silently choose.
- None: the short address cannot currently be resolved (see FAQ).
Once a candidate is selected, the client can reconstruct the authoritative nevent/naddr/note from the event itself if a canonical reference is needed.
Collision Handling
A collision (two of the author's events sharing the same 6-char code) is extremely unlikely — the birthday bound only reaches ~50% at roughly 4,800 short-addressed events from a single author. It is handled without ever mutating an event.
The mechanism is simply reading further along the same hash. The SHA-256 digest is a long hex string; the first 6 characters are the code, and if two of the author's events share those 6, the selector suffix is just the next character(s) of that same digest — enough to tell them apart:
SHA-256(input) = 1f4c2a 9 5 e3b7d…
└────┘ │ └ 8th char → 2nd suffix char, e.g. "-95"
code └── 7th char → 1st suffix char, e.g. "-9"
- The
stag remains 6 hex for every event, so all colliding events stay in the same queryable bucket and a single query returns them all. - Disambiguation lives only in the shared address, as a
-<hex>suffix. The resolver selects by recomputing candidate hashes and prefix-matching — never by counting or ordering, so it is robust to partial relay visibility. - The suffix length is the minimum needed to make the target unique among the fetched candidates — almost always one character, occasionally two. It grows logarithmically with candidate count, not linearly.
- Because disambiguation is address-side, a more precise address can be minted later without republishing the event. An already-shared shorter address that a future event undercuts degrades gracefully to the disambiguation UI.
Clients MAY offer collision-safe address generation as a toggle for regular events (decided at compose time, since regular events are immutable) and as an on-demand "Generate short address" action for addressable events (which edits the event to add the s tag and republishes it, replacing by coordinate).
Address Marker, Delimiter, and Charsets
- Every short address begins with the marker
s. key36is base 36 ([0-9a-z], fixed 50 characters) and never contains-.codeand the selector suffix are lowercase hex ([0-9a-f]).- The selector separator is
-(hyphen), which cannot occur in the key36 or the code, so splitting on it is unambiguous.
Client Recognition of Short Addresses
A short address has a fixed shape:
s [0-9a-z]{50} [0-9a-f]{6} ( -[0-9a-f]+ )?
A string is treated as a NIP-SHORT short address only if it matches this shape exactly (57 characters, or more with a selector suffix) and its key36 decodes to a valid pubkey (value below 2²⁵⁶). Clients SHOULD require the address to stand alone as a token (bounded by whitespace, punctuation, or the start/end of the text) before treating it as one. This lets clients auto-detect short addresses in shared plain text (DMs, notes, QR codes) without attempting resolution.
Because base 36 has no distinctive prefix the way npub1 does, plain-text detection is less certain than for NIP-19 entities. Clients that link short addresses SHOULD prefer an explicit URL route or a nostr: link where one is available. Clients that expose short addresses in URLs (e.g. https://example.com/s5ininr1pe6onndbb89gw173g9j6swrdy5o2b4jccprabuun8yh1f4c2a) MAY additionally use a route of their choosing; the URL route is a client concern and is independent of the marker, which remains part of the canonical address string.
UX Recommendation: Step-by-Step Loading Indicator
Resolution involves a few sequential steps (the relay query, verification, rendering). To avoid appearing unresponsive — especially for direct URL navigation — clients SHOULD show a step-by-step indicator:
- Parsing address — stripping the marker, extracting and decoding the key36, the code, and any suffix
- Querying relays — fetching by
authors + #s - Verifying — recomputing the code and checking the signature
- Rendering — displaying the event
Each step SHOULD show an elapsed-time counter, with completed steps visually distinguished from in-progress and pending ones.
Benefits
- Compact and predictable — shorter than a raw
nevent/naddr, with a fixed length (57 characters, plus a short suffix in the rare collision case). - No external dependencies — only NIP-01 plus a local base-36 conversion.
- No separate mapping event — nothing to batch, append, preserve, or delete.
- No disconnect — the mapping cannot break independently of the event.
- Single-query resolution with mandatory client-side verification.
- No spam vector — author-scoped queries only ever match the author's events.
- Deterministic — any client computes the same code for the same event.
- Edit-safe for addressable/replaceable events — links survive revisions.
Examples
Normal (57 chars):
s5ininr1pe6onndbb89gw173g9j6swrdy5o2b4jccprabuun8yh1f4c2a
Two-way collision (1-char selector, 59 chars):
s5ininr1pe6onndbb89gw173g9j6swrdy5o2b4jccprabuun8yh1f4c2a-a
Deeper collision (2-char selector, 60 chars):
s5ininr1pe6onndbb89gw173g9j6swrdy5o2b4jccprabuun8yh1f4c2a-a5
Structure:
smarker +key36(50) +6-hex code+ optional-<hex selector>.
FAQ
What happens if a client cannot find the event?
Resolution depends on the client querying at least one relay that holds the event. If no queried relay has it, the short address cannot resolve. This is a general property of Nostr, not specific to NIP-SHORT — ordinary nevent/naddr references fail the same way when relay overlap is insufficient.
Why doesn't the short address include relay hints?
Relay hints add size and complexity. NIP-SHORT prioritizes human readability, minimal length, and deterministic parsing, and relies on relay overlap and publisher relay selection for discovery. Clients MAY also consult the author's NIP-65 relay list, which they can look up from the decoded pubkey.
How can clients improve discoverability?
Publishers SHOULD publish events to both the author's configured write relays and the client's default relay set. Overlap with other users of the same client, plus broad infrastructure relays, significantly improves the odds that a resolving client queries a relay that holds the event.
Can third parties mirror short-addressed events?
Yes. The event is an ordinary Nostr event: any relay may store it and any indexer may track it. Resolution is always verified client-side (recompute the code, validate the signature), so mirroring introduces no trust risk. Third parties cannot create a short address for someone else's event — the code is a tag inside the author's own signed event — but they can freely replicate the event.
Is resolution guaranteed globally?
No. Like all Nostr references, resolution depends on relay availability and propagation. NIP-SHORT improves usability and compactness, not global availability.
Why base 36 instead of an npub?
The goal of this NIP is the shortest practical link. An npub spends 11 of its 63 characters on the npub1 prefix and a 6-character checksum, and its alphabet holds 5 bits per character. Base 36 holds about 5.17 bits per character and drops the prefix and checksum, so the same key takes 50 characters and the address takes 57 instead of 70. Base 36 was chosen over denser encodings such as base 58 or base 62 because it is case-insensitive, so it survives URLs, search, and being read aloud.
The cost is the checksum: a typo in the key is not caught on its own. It decodes to an effectively random pubkey that belongs to no one, so it shows up as "not found" rather than as an error. Users see the author's npub in the client's UI as usual; key36 only appears inside links.
Can it be shorter?
Yes, potentially. Almost all of the address's length comes from the 50-character key; the code itself is only 6 characters. If a future system offers a shorter identifier that resolves to a pubkey with high confidence, it could take the key's place in the address. Everything else in this NIP stays the same: the code, the s tag, derivation, the relay query, and verification all depend only on the hex pubkey, not on how the author is written in the address. Such a system would be specified separately, and the key36 form described here would remain the baseline.
Discussion
Connect a key to comment.