12<html lang="en">3<head>4<meta charset="utf-8">5<meta name="viewport" content="width=device-width, initial-scale=1">6<title>NIP-08 - Handling Mentions — Nostr Instruction Manual</title>7<meta name="description" content="NIP-08: the original inline-mention notation for text notes. The #[index] placeholder and matching p/e tags. Deprecated in favor of NIP-27.">8<link rel="preload" href="../assets/fonts/michroma-400-latin.woff2" as="font" type="font/woff2" crossorigin>9<link rel="preload" href="../assets/fonts/exo2-var-latin.woff2" as="font" type="font/woff2" crossorigin>10<link rel="preload" href="../assets/fonts/sairacondensed-600-latin.woff2" as="font" type="font/woff2" crossorigin>11<link rel="preload" href="../assets/fonts/sairacondensed-700-latin.woff2" as="font" type="font/woff2" crossorigin>12<link rel="preload" href="../assets/fonts/sairacondensed-500-latin.woff2" as="font" type="font/woff2" crossorigin>13<link rel="preload" href="../assets/fonts/sharetechmono-400-latin.woff2" as="font" type="font/woff2" crossorigin>14<link rel="preload" href="../assets/fonts/exo2-400i-latin.woff2" as="font" type="font/woff2" crossorigin>15<link rel="icon" href="../assets/favicon.svg" type="image/svg+xml">16<link rel="stylesheet" href="../assets/manual.css">17</head>18<body>1920<svg width="0" height="0" style="position:absolute">21 <defs>22 <marker id="arr" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto">23 <path d="M1,1 L8,4.5 L1,8 Z" fill="#f26a00"/>24 </marker>25 <marker id="arrb" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto">26 <path d="M1,1 L8,4.5 L1,8 Z" fill="#2e5f9e"/>27 </marker>28 </defs>29</svg>3031<div class="page">32 <span class="staple s1"></span><span class="staple s2"></span>3334 <header class="band">35 <a class="logo" href="../index.html">NOSTR<b>▸</b>PROTOCOL MANUAL</a>36 <span class="booklet-note">Chapter 08 - Social</span>37 </header>38 <nav class="tabs">39 <a href="../index.html">Contents</a>40 <a href="#overview" class="on">Overview</a>41 <a href="#spec">Spec</a>42 <a href="#examples">Examples</a>43 <a href="#history">History</a>44 </nav>4546 <div class="chapter">47 <div class="nipno" data-n="08">08</div>48 <div class="titles">49 <div class="kicker">Nostr Implementation Possibility - Hex № 08</div>50 <h1>Handling Mentions</h1>51 <p class="sub">The original way a client marks an inline reference to another user or event inside a text note. Superseded by NIP-27.</p>52 </div>53 <div class="stamp">Deprecated</div>54 </div>5556 <main class="spread">57 <div class="main">5859 <h2 class="bar" id="overview"><span class="num">1</span> Overview</h2>60 <p>A user often wants to mention another user, or point to another event, inside the text of a note. NIP-08 defines how a client records that mention so any other client can read it.</p>61 <p>The technique has two parts. The writing client adds a <code>p</code> tag or an <code>e</code> tag to the event's <code>tags</code> array. It then writes a placeholder, <code>#[index]</code>, into <code>content</code> at the point of the mention. The number <code>index</code> points at the matching tag.</p>62 <p>This NIP applies to <code>text_note</code> events, <a href="01.html">kind 1</a>, and to any other kind whose <code>content</code> holds readable text. It does not define a new kind, tag name, or message type of its own. It only defines a notation.</p>6364 <div class="box danger">65 <span class="tag">Deprecated</span>66 <p>NIP-08 is <strong>unrecommended</strong>. Use <a href="27.html">NIP-27</a>, Text Note References, for all new work. NIP-27 replaces the numeric <code>#[index]</code> placeholder with a self-describing <code>nostr:</code> URI, so the reference still works even if a tag is reordered or dropped. Read this chapter to understand old events, not to build new features.</p>67 </div>6869 <h2 class="bar" id="spec"><span class="num">2</span> Writing a Mention</h2>70 <p>A client that lets a user create tagged mentions must follow two rules, in order.</p>7172 <div class="tscroll"><table class="ref">73 <caption>Mention notation rules</caption>74 <tr><th>Step</th><th>Requirement</th><th>Rule</th></tr>75 <tr><td class="btn">1. Detect</td><td>MUST</td><td>Show an autocomplete component, or something like it, when the user starts a mention (for example by typing <code>@</code>) or presses a button for it. A client may instead use any other method that unambiguously tells a mention apart from normal text.</td></tr>76 <tr><td class="btn">2. Encode</td><td>MUST</td><td>Add the mentioned pubkey or event ID to <code>tags</code>, using tag name <code>p</code> for a user or <code>e</code> for an event. Then replace the mention text in <code>content</code> with <code>#[index]</code>, where <code>index</code> is the 0-based position of that tag inside the <code>tags</code> array.</td></tr>77 </table></div>7879 <div class="crt">80 <div class="titlebar">Wire format - a mention notation</div>81<pre><span class="k">"content"</span>: <span class="s">"gm #[0], nice job on #[1]"</span>82<span class="k">"tags"</span>: [83 [<span class="s">"p"</span>, <span class="s">"27866e9d854c78ae625b867eefdfa9580434bc3e675be08d2acb526610d96fbe"</span>],84 [<span class="s">"e"</span>, <span class="s">"7b2e3a1f9c6d8508e6f9a1e6b8b6f4c1c1d1e59b0f6e6b1a4f7c9a2e1b3d4c5e"</span>]85]</pre>86 </div>87 <p>Here <code>#[0]</code> points at <code>tags[0]</code>, the <code>p</code> tag, a mention of that user. <code>#[1]</code> points at <code>tags[1]</code>, the <code>e</code> tag, a mention of that event.</p>8889 <div class="box tech">90 <span class="tag">Tech Note</span>91 <p>The source text never names <code>e</code> explicitly for event mentions. It only says "the same process applies for mentioning event IDs." The tag name <code>e</code> is implied by <a href="01.html">NIP-01</a> convention and by the later rule that only <code>e</code> and <code>p</code> tags are valid mention targets. The phrase "or a tag otherwise declared to support this notation" is also left undefined: no other NIP registers itself against NIP-08 this way.</p>92 </div>9394 <h2 class="bar" id="reading"><span class="num">3</span> Reading a Mention</h2>95 <p>A client that receives an event with <code>#[index]</code> placeholders in <code>content</code> can look up each index in <code>tags</code> and show something richer than raw text.</p>96 <div class="tscroll"><table class="ref">97 <caption>Reading rules</caption>98 <tr><th>Case</th><th>Requirement</th><th>Rule</th></tr>99 <tr><td class="btn">Valid index</td><td>CAN</td><td>Search and replace <code>#[index]</code> with the pubkey or event ID from the matching tag. The client may add context, such as a link to the user or a preview of the mentioned event.</td></tr>100 <tr><td class="btn">Invalid index</td><td>MUST NOT</td><td>When <code>index</code> is outside the range of <code>tags</code>, or the tag it points at is not <code>e</code>, not <code>p</code>, and not otherwise declared to support this notation, the client must not replace or augment it. It must display <code>#[index]</code> as plain text.</td></tr>101 </table></div>102 <div class="box hint">103 <span class="tag">Hint!</span>104 <p>Reading support is optional. A client with no interest in rich mentions can always show the raw <code>#[index]</code> text and still be a correct NIP-08 client.</p>105 </div>106107 <figure class="diagram">108 <div class="frame">109 <svg viewBox="0 0 560 150" role="img" aria-label="Writer types a mention, the client adds a tag and a numbered placeholder, publishes the event, and a reader client looks up the tag by index to display the mention">110 <rect class="d-actor" x="10" y="20" width="110" height="50" rx="8"/>111 <text class="d-actor-label" x="65" y="42" text-anchor="middle">Mention</text>112 <text class="d-note" x="65" y="58" text-anchor="middle">"@bob"</text>113 <rect class="d-actor" x="170" y="20" width="120" height="50" rx="8"/>114 <text class="d-actor-label" x="230" y="42" text-anchor="middle">Add tag</text>115 <text class="d-note" x="230" y="58" text-anchor="middle">["p", pubkey]</text>116 <rect class="d-actor" x="340" y="20" width="120" height="50" rx="8"/>117 <text class="d-actor-label" x="400" y="42" text-anchor="middle">Placeholder</text>118 <text class="d-note" x="400" y="58" text-anchor="middle">"#[0]" in content</text>119 <path class="d-msg d-flow" d="M122,45 L167,45"/>120 <path class="d-msg d-flow" d="M292,45 L337,45"/>121 <rect class="d-actor" x="340" y="100" width="120" height="40" rx="8"/>122 <text class="d-actor-label" x="400" y="124" text-anchor="middle">Publish event</text>123 <rect class="d-actor" x="170" y="100" width="120" height="40" rx="8"/>124 <text class="d-actor-label" x="230" y="124" text-anchor="middle">Reader looks up tags[0]</text>125 <path class="d-msg blue d-flow" d="M400,98 L400,80 L400,70"/>126 <path class="d-msg blue d-flow" d="M338,120 L292,120"/>127 <text class="d-note" x="65" y="120" text-anchor="middle">shows "@bob" link</text>128 <path class="d-msg blue d-flow" d="M168,118 L122,90"/>129 </svg>130 </div>131 <figcaption>Fig. 8-1 — <b>Mention round trip.</b> The writer's client adds a tag and a placeholder. The reader's client resolves the placeholder back to the tag.</figcaption>132 </figure>133134 <h2 class="bar" id="examples"><span class="num">4</span> Worked Example</h2>135 <p>Alice mentions Bob in a text note. Her client adds a <code>p</code> tag and writes <code>#[0]</code> in place of Bob's name. Carol's client then resolves it back to a link. Orange lines go to the relay. Blue lines come from the relay.</p>136 <div class="crt">137 <div class="titlebar">Session transcript - wss://relay.example.com</div>138<pre><span class="c">-- Alice's client turns "@bob" into a p tag plus a placeholder --</span>139<span class="send">→ ["EVENT", {"id":"a41c9e…","pubkey":"a1b2c3…","created_at":1749762600,140 "kind":1,"tags":[["p","27866e9d854c78ae625b867eefdfa9580434bc3e675be08d2acb526610d96fbe"]],141 "content":"gm #[0], see you at the meetup","sig":"e8551d85…"}]</span>142<span class="recv">← ["OK", "a41c9e…", true, ""]</span>143144<span class="c">-- Carol's client fetches the note --</span>145<span class="send">→ ["REQ", "feed", {"kinds":[1], "limit":10}]</span>146<span class="recv">← ["EVENT", "feed", {"id":"a41c9e…","kind":1,147 "tags":[["p","27866e9d854c78ae625b867eefdfa9580434bc3e675be08d2acb526610d96fbe"]],148 "content":"gm #[0], see you at the meetup", …}]</span>149<span class="recv">← ["EOSE", "feed"]</span>150151<span class="c">-- Carol's client resolves #[0] against tags[0] --</span>152<span class="c">-- index 0 is in range and points at a p tag: replace and link --</span>153<span class="c">-- displayed text: "gm @bob, see you at the meetup"</span>154155<span class="c">-- a malformed note, for comparison --</span>156<span class="c">-- content: "check #[3] out", tags has only 1 entry --</span>157<span class="c">-- index 3 is out of range: display "#[3]" as plain text, no link --</span></pre>158 </div>159160 <h2 class="bar" id="history"><span class="num">5</span> Version History</h2>161 <p>NIP-08 is final and deprecated; no further spec changes are expected. Notable changes, newest first:</p>162 <ul class="patchnotes">163 <li class="minor"><span class="ver">2023</span><span class="when">2023-11</span>Removed the <code>author:</code> tags from every NIP, including this one's <code>fiatjaf</code> and <code>scsibug</code> credits.</li>164 <li class="minor"><span class="ver">2023</span><span class="when">2023-04</span>Turned the deprecation warning's plain-text mention of NIP-27 into a link.</li>165 <li><span class="ver">2023</span><span class="when">2023-03-25</span>Added the <code>unrecommended</code> tag alongside <code>final</code>, formalizing the deprecation.</li>166 <li><span class="ver">2023</span><span class="when">2023-03-22</span>Changed the warning wording from "discouraged" to "deprecated".</li>167 <li><span class="ver">2023</span><span class="when">2023-03-21</span>Added the warning banner at the top of the document, pointing to the new <a href="27.html">NIP-27</a>.</li>168 <li><span class="ver">2023</span><span class="when">2023-03-05</span>Added the MUST NOT rule: clients must not resolve or augment a <code>#[index]</code> that is out of range or points at an unsupported tag.</li>169 <li><span class="ver">2022</span><span class="when">2022-11</span>Marked <code>final</code>: no further spec changes expected.</li>170 <li><span class="ver">Origin</span><span class="when">2022-05</span>Migrated into the <code>nostr-protocol/nips</code> repository, authored by fiatjaf and scsibug.</li>171 </ul>172173 <div class="credits">174 <h3 class="cardhead">Original Proposal - Credits</h3>175 <table>176 <tr><td>Author</td><td>fiatjaf (co-authored with scsibug)</td></tr>177 <tr><td>First commit</td><td>2022-05-01 — "migrate nips from main nostr repo."</td></tr>178 <tr><td>Status</td><td>final - unrecommended - optional — deprecated in favor of <a href="27.html">NIP-27</a></td></tr>179 <tr><td>Source</td><td><a href="https://github.com/nostr-protocol/nips/blob/master/08.md">08.md on GitHub</a> - <a href="https://github.com/nostr-protocol/nips/commits/master/08.md">full change history</a></td></tr>180 </table>181 </div>182183 <h2 class="bar"><span class="num">6</span> See Also</h2>184 <ul>185 <li><a href="27.html">NIP-27</a> — Text Note References. The recommended replacement, using <code>nostr:</code> URIs instead of numeric placeholders.</li>186 <li><a href="01.html">NIP-01</a> — base event format, <code>tags</code> array, and the <code>e</code>/<code>p</code> tags this notation depends on.</li>187 <li><a href="10.html">NIP-10</a> — text notes and reply threading, the main home of the <code>e</code> tag in <code>kind:1</code> notes.</li>188 <li><a href="19.html">NIP-19</a> — bech32 <code>npub</code>/<code>note</code> encodings used to display the pubkeys and event IDs a mention resolves to.</li>189 <li><a href="21.html">NIP-21</a> — the <code>nostr:</code> URI scheme that NIP-27 mentions use in place of <code>#[index]</code>.</li>190 </ul>191 </div>192193 <aside>194 <div class="cartridge">195 <div class="inner">196 <h3 class="cardhead">Spec Card</h3>197 <div class="lights"><span class="led err"></span><span class="led err"></span><span class="led err"></span></div>198 <dl>199 <dt>Status</dt><dd><span class="chip final">final</span><span class="chip unrecommended">unrecommended</span></dd>200 <dt>Defines</dt><dd><code>#[index]</code> mention notation - matching p/e tag additions</dd>201 <dt>Kind</dt><dd>none — applies inside <code>kind:1</code> and other text content</dd>202 <dt>Requires</dt><dd><a href="01.html">NIP-01</a></dd>203 <dt>Replaced by</dt><dd><a href="27.html">NIP-27</a></dd>204 <dt>First commit</dt><dd>2022-05-01</dd>205 <dt>Last updated</dt><dd>2023-11-15</dd>206 </dl>207 </div>208 </div>209 </aside>210 </main>211212 <nav class="navbtns">213 <a href="07.html">◀ NIP-07: window.nostr Capability for Web Browsers</a>214 <a href="09.html">NIP-09: Event Deletion Request ▶</a>215 </nav>216217 <footer class="pagefoot">218 <a href="../index.html">Nostr Protocol Manual</a>219 <span class="pageno">NIP 08 / F4</span>220 </footer>221</div>222223<script src="../assets/webmcp.js" defer></script>224</body>225</html>