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-20 - Command Results — Nostr Instruction Manual</title>7<meta name="description" content="NIP-20: the OK command result message. Merged into NIP-01 in 2023. This page explains what it defined and where the rules live now.">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 20 - Core</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="20">20</div>48 <div class="titles">49 <div class="kicker">Nostr Implementation Possibility - Hex № 20</div>50 <h1>Command Results</h1>51 <p class="sub">This chapter is closed. NIP-20 once defined the <code>OK</code> message. That rule is now part of the core protocol in <a href="01.html">NIP-01</a>.</p>52 </div>53 <div class="stamp merged">Merged</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>Before NIP-20, a client that published an event had no reliable way to know if a relay accepted it. A relay could only send a free-text <code>NOTICE</code> message, which no program could parse with confidence.</p>61 <p>NIP-20 fixed this with a new message type, <code>OK</code>. A relay sends exactly one <code>OK</code> for every <code>EVENT</code> command it receives, well-formed or not. The message carries a machine-readable status: true or false, plus a prefixed reason string.</p>6263 <div class="box hint">64 <span class="tag">Merged</span>65 <p>NIP-20 is closed and carries no separate rules of its own anymore. The <code>OK</code> message and its status prefixes now live in <a href="01.html#messages">NIP-01, section 5 (Client ↔ Relay Messages)</a>. Read this page for history, then read NIP-01 for the current spec.</p>66 </div>6768 <h2 class="bar" id="spec"><span class="num">2</span> What NIP-20 Defined</h2>69 <p>NIP-20 stated these rules, restated here in Simplified Technical English:</p>70 <div class="crt">71 <div class="titlebar">Wire format - OK message, as originally defined</div>72<pre>[<span class="s">"OK"</span>, <span class="c"><event_id></span>, <span class="c"><true|false></span>, <span class="c"><message></span>]</pre>73 </div>74 <ul>75 <li>The relay must send <code>true</code> when it saved the event, including when the event was already a duplicate.</li>76 <li>The relay must send <code>false</code> when it rejected the event and did not save it.</li>77 <li>The relay must not send <code>OK</code> for ephemeral events unless something failed.</li>78 <li>If the <code>EVENT</code> command itself is malformed and cannot be parsed, the relay sends <code>NOTICE</code> instead of <code>OK</code>.</li>79 </ul>80 <p>NIP-20 defined the message prefix convention: a single lower-case word, then a colon, then a human-readable reason. It defined five prefixes:</p>81 <div class="tscroll"><table class="ref">82 <caption>NIP-20 status prefixes, as originally defined</caption>83 <tr><th>Prefix</th><th>Meaning</th></tr>84 <tr><td class="btn">duplicate</td><td>The event was already saved.</td></tr>85 <tr><td class="btn">blocked</td><td>The pubkey or network address is blocked or not on a whitelist.</td></tr>86 <tr><td class="btn">invalid</td><td>The event fails validation, for example a bad signature or an out-of-range timestamp.</td></tr>87 <tr><td class="btn">pow</td><td>The event does not meet the relay's required proof-of-work difficulty.</td></tr>88 <tr><td class="btn">rate-limited</td><td>The client is sending events too fast.</td></tr>89 <tr><td class="btn">error</td><td>Anything else, such as a server-side failure.</td></tr>90 </table></div>9192 <h3>Where It Lives Now</h3>93 <p>NIP-01 kept the <code>OK</code> message and every original prefix. It added two more: <code>restricted</code>, for a client that is not allowed to write, and <code>mute</code>, for an ephemeral event nobody was listening for. NIP-01 also added a related message type, <code>CLOSED</code>, which reports subscription-level failures using the same prefix convention. <code>CLOSED</code> did not come from NIP-20; it was added directly to NIP-01 later.</p>9495 <h2 class="bar" id="examples"><span class="num">3</span> Historical Example</h2>96 <p>These are examples from the original NIP-20 text. They still match the wire format under NIP-01 today.</p>97 <div class="crt">98 <div class="titlebar">Examples - from the original NIP-20 text</div>99<pre><span class="recv">← ["OK", "b1a649ebe8…", true, ""]</span>100<span class="c">-- accepted, with a reason --</span>101<span class="recv">← ["OK", "b1a649ebe8…", true, "pow: difficulty 25>=24"]</span>102<span class="c">-- rejected: banned pubkey --</span>103<span class="recv">← ["OK", "b1a649ebe8…", false, "blocked: you are banned from posting here"]</span>104<span class="c">-- rejected: rate limited --</span>105<span class="recv">← ["OK", "b1a649ebe8…", false, "rate-limited: slow down there chief"]</span>106<span class="c">-- rejected: bad timestamp --</span>107<span class="recv">← ["OK", "b1a649ebe8…", false, "invalid: event creation date is too far off from the current time. Is your system clock in sync?"]</span></pre>108 </div>109110 <h2 class="bar" id="history"><span class="num">4</span> Version History</h2>111 <ul class="patchnotes">112 <li><span class="ver">Closed</span><span class="when">2023-08-13</span>Merged into <a href="01.html">NIP-01</a> along with <a href="12.html">NIP-12</a>, <a href="16.html">NIP-16</a>, and <a href="33.html">NIP-33</a> (PR <a href="https://github.com/nostr-protocol/nips/pull/703">#703</a>). All four were already "final, mandatory" — folding them into the root spec meant a client or relay only had to read one document to reach baseline compliance.</li>113 <li class="minor"><span class="ver">2023</span><span class="when">2023-11-15</span>Repo-wide cleanup removed the per-file author badge from the now-stub page.</li>114 <li class="minor"><span class="ver">2023</span><span class="when">2023-03-02</span>ennmichael fixed a typo.</li>115 <li class="minor"><span class="ver">2022</span><span class="when">2022-12-16</span>sgmoore made minor grammar fixes.</li>116 <li><span class="ver">Origin</span><span class="when">2022-11-10</span>William Casarin (jb55) published NIP-20 and, the same day, added the <code>invalid</code> and <code>pow</code> prefixes, clarified malformed-versus-invalid handling, and noted that server errors need their own prefix too.</li>117 </ul>118119 <div class="credits">120 <h3 class="cardhead">Original Proposal - Credits</h3>121 <table>122 <tr><td>Author</td><td>William Casarin (jb55)</td></tr>123 <tr><td>First commit</td><td>2022-11-10 — “NIP-20: Command Results”</td></tr>124 <tr><td>Status</td><td><span class="chip final">final</span> <span class="chip mandatory">mandatory</span> — merged, no longer a standalone document</td></tr>125 <tr><td>Source</td><td><a href="https://github.com/nostr-protocol/nips/blob/master/20.md">20.md on GitHub</a> - <a href="https://github.com/nostr-protocol/nips/commits/master/20.md">full change history</a></td></tr>126 </table>127 </div>128129 <h2 class="bar"><span class="num">5</span> See Also</h2>130 <ul>131 <li><a href="01.html">NIP-01</a> — the current, canonical home of the <code>OK</code> message and its status prefixes.</li>132 <li><a href="12.html">NIP-12</a> — generic tag queries, merged the same day as NIP-20.</li>133 <li><a href="16.html">NIP-16</a> — event treatment, merged the same day as NIP-20.</li>134 <li><a href="13.html">NIP-13</a> — proof of work, referenced by the <code>pow</code> status prefix.</li>135 </ul>136 </div>137138 <aside>139 <div class="cartridge">140 <div class="inner">141 <h3 class="cardhead">Spec Card</h3>142 <div class="lights"><span class="led on"></span><span class="led on"></span><span class="led on"></span></div>143 <dl>144 <dt>Status</dt><dd><span class="chip final">final</span><span class="chip mandatory">mandatory</span></dd>145 <dt>Defined</dt><dd><code>OK</code> message - status prefixes</dd>146 <dt>Now lives in</dt><dd><a href="01.html#messages">NIP-01 §5</a></dd>147 <dt>Requires</dt><dd><a href="01.html">NIP-01</a></dd>148 <dt>First commit</dt><dd>2022-11-10</dd>149 <dt>Merged</dt><dd>2023-08-13 (PR #703)</dd>150 <dt>Last updated</dt><dd>2023-11-15</dd>151 </dl>152 </div>153 </div>154 </aside>155 </main>156157 <nav class="navbtns">158 <a href="19.html">◀ NIP-19: bech32-encoded entities</a>159 <a href="21.html">NIP-21: `nostr:` URI scheme ▶</a>160 </nav>161162 <footer class="pagefoot">163 <a href="../index.html">Nostr Protocol Manual</a>164 <span class="pageno">NIP 20 / F4</span>165 </footer>166</div>167168<script src="../assets/webmcp.js" defer></script>169</body>170</html>