clone

every nostr nip as a chapter of an illustrated, early-2000s printed game manual

main
nip.guide / site / nips / cc.html
cc.html 39.7K
1<!DOCTYPE html>2<html lang="en">3<head>4<meta charset="utf-8">5<meta name="viewport" content="width=device-width, initial-scale=1">6<title>NIP-CC - Geocaching Events — Nostr Instruction Manual</title>7<meta name="description" content="NIP-CC: geocaching on Nostr. Cache listings, found logs, comment logs, cryptographic verification, type modifiers, and curation lists. Complete manual page.">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 CC - Recreation</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="CC">CC</div>48 <div class="titles">49 <div class="kicker">Nostr Implementation Possibility - Hex № CC</div>50 <h1>Geocaching Events</h1>51 <p class="sub">Hide treasures in the real world, list them as events, and let finders log and prove their visits — no central geocaching service required.</p>52 </div>53 </div>5455 <main class="spread">56 <div class="main">5758 <h2 class="bar" id="overview"><span class="num">1</span> Overview</h2>59 <p>A <strong>geocache</strong> is a physical container hidden at a real-world location. This NIP defines event kinds for geocaching on Nostr. Users create, share, and log geocaches in a decentralized manner. No company owns the cache database.</p>60 <p>The system uses five event kinds. A <strong>listing</strong> (kind 37516) describes one cache. A <strong>found log</strong> (kind 7516) records a successful visit. A <strong>comment log</strong> (kind 1111, per <a href="22.html">NIP-22</a>) records failures, notes, and maintenance reports. A <strong>verification event</strong> (kind 7517) gives cryptographic proof of physical presence. A <strong>curation list</strong> (kind 37517) groups caches into themed collections.</p>61 <p>The submitter owns the listing and maintains its core details. The community adds context through logs. Together the events show the current state and validity of each cache.</p>6263 <div class="box hint">64 <span class="tag">Hint!</span>65 <p>The difficulty, terrain, and size scales follow well-known geocaching standards, such as those documented on geocaching.com. Veteran cachers can read a Nostr listing at a glance.</p>66 </div>6768 <figure class="diagram">69 <div class="frame">70 <svg viewBox="0 0 560 240" role="img" aria-label="Found logs, comment logs, and curation lists all reference the geocache listing; the verification event is embedded inside the found log">71 <rect class="d-actor" x="400" y="90" width="140" height="56" rx="8"/>72 <text class="d-actor-label" x="470" y="114" text-anchor="middle">Listing</text>73 <text class="d-note" x="470" y="132" text-anchor="middle">kind 37516</text>74 <rect class="d-actor" x="20" y="14" width="140" height="44" rx="8"/>75 <text class="d-actor-label" x="90" y="33" text-anchor="middle">Found log</text>76 <text class="d-note" x="90" y="50" text-anchor="middle">kind 7516</text>77 <rect class="d-actor" x="20" y="98" width="140" height="44" rx="8"/>78 <text class="d-actor-label" x="90" y="117" text-anchor="middle">Comment log</text>79 <text class="d-note" x="90" y="134" text-anchor="middle">kind 1111</text>80 <rect class="d-actor" x="20" y="182" width="140" height="44" rx="8"/>81 <text class="d-actor-label" x="90" y="201" text-anchor="middle">Curation list</text>82 <text class="d-note" x="90" y="218" text-anchor="middle">kind 37517</text>83 <rect class="d-actor" x="200" y="14" width="130" height="44" rx="8"/>84 <text class="d-actor-label" x="265" y="33" text-anchor="middle">Verification</text>85 <text class="d-note" x="265" y="50" text-anchor="middle">kind 7517</text>86 <path class="d-msg blue" d="M198,36 L164,36"/>87 <path class="d-msg d-flow" d="M162,44 C300,60 340,84 397,102"/>88 <path class="d-msg d-flow" d="M162,120 L397,118"/>89 <path class="d-msg d-flow" d="M162,204 C300,190 340,160 397,136"/>90 <text class="d-label" x="270" y="80" text-anchor="middle">a</text>91 <text class="d-label" x="280" y="112" text-anchor="middle">A / a</text>92 <text class="d-label" x="270" y="176" text-anchor="middle">a (ordered)</text>93 <text class="d-label" x="181" y="30" text-anchor="middle">embed</text>94 <circle r="4" fill="#f26a00">95 <animateMotion dur="2.6s" repeatCount="indefinite" path="M162,44 C300,60 340,84 397,102"/>96 </circle>97 </svg>98 </div>99 <figcaption>Fig. CC-1 — <b>The event family.</b> Every log and list points at the addressable listing. The verification event rides inside the found log.</figcaption>100 </figure>101102 <h2 class="bar" id="spec"><span class="num">2</span> Geocache Listing — Kind 37516</h2>103 <p>A listing is an addressable event (see <a href="01.html">NIP-01</a>) of kind <code>37516</code>. It carries all information about the cache and all information relevant to finding it. The required data is the <code>name</code>, the location (<code>g</code>), the difficulty (<code>D</code>) and terrain (<code>T</code>) scores, and the size (<code>S</code>).</p>104105 <div class="crt">106 <div class="titlebar">Wire format - geocache listing</div>107<pre>{108 <span class="k">"kind"</span>: 37516,109 <span class="k">"content"</span>: <span class="c">&lt;cache description&gt;</span>,110 <span class="k">"tags"</span>: [111 [<span class="s">"d"</span>, <span class="c">&lt;cache-identifier&gt;</span>],112 [<span class="s">"name"</span>, <span class="c">&lt;cache-name&gt;</span>],113 [<span class="s">"g"</span>, <span class="c">&lt;geohash&gt;</span>],114 [<span class="s">"D"</span>, <span class="c">&lt;1-5&gt;</span>],115 [<span class="s">"T"</span>, <span class="c">&lt;1-5&gt;</span>],116 [<span class="s">"S"</span>, <span class="c">&lt;size&gt;</span>],117 [<span class="s">"t"</span>, <span class="c">&lt;type&gt;</span>],118 [<span class="s">"n"</span>, <span class="c">&lt;type-modifier&gt;</span>],119 [<span class="s">"hint"</span>, <span class="c">&lt;plaintext hint&gt;</span>],120 [<span class="s">"mission"</span>, <span class="c">&lt;key quest mission&gt;</span>],121 [<span class="s">"image"</span>, <span class="c">&lt;image-url&gt;</span>],122 [<span class="s">"r"</span>, <span class="c">&lt;relay-url&gt;</span>],123 [<span class="s">"verification"</span>, <span class="c">&lt;verification-pubkey-hex&gt;</span>]124 ]125}</pre>126 </div>127128 <p>The <code>content</code> field contains the cache description and any additional information about the cache.</p>129130 <div class="tscroll"><table class="ref">131 <caption>Listing tags</caption>132 <tr><th>Tag</th><th>Required</th><th>Rule</th></tr>133 <tr><td class="btn">d</td><td>yes</td><td>Unique identifier for the cache.</td></tr>134 <tr><td class="btn">name</td><td>yes</td><td>Human-readable name for the cache.</td></tr>135 <tr><td class="btn">g</td><td>yes</td><td>Geohash of the cache location. Include multiple <code>g</code> tags at different precision levels (3-9 characters) to allow proximity search.</td></tr>136 <tr><td class="btn">D</td><td>yes</td><td>Integer 1-5. Puzzle or finding difficulty. Indexed.</td></tr>137 <tr><td class="btn">T</td><td>yes</td><td>Integer 1-5. Terrain difficulty. Indexed.</td></tr>138 <tr><td class="btn">S</td><td>yes</td><td>Size. One of <code>micro</code>, <code>small</code>, <code>regular</code>, <code>large</code>, <code>other</code>. Indexed.</td></tr>139 <tr><td class="btn">t</td><td>no</td><td>Cache type. Common values: <code>traditional</code>, <code>multi</code>, <code>mystery</code>. Defaults to <code>traditional</code> if absent.</td></tr>140 <tr><td class="btn">n</td><td>no</td><td>Type modifier that affects lifecycle, claim semantics, or prize nature. See §7. Multiple <code>n</code> tags may be present, but at most one per modifier category.</td></tr>141 <tr><td class="btn">hint</td><td>no</td><td>Plaintext hint that helps a finder locate the cache.</td></tr>142 <tr><td class="btn">mission</td><td>no</td><td>Plaintext "Key Quest" mission. See below.</td></tr>143 <tr><td class="btn">image</td><td>no</td><td>Image URLs related to the cache.</td></tr>144 <tr><td class="btn">r</td><td>no</td><td>Preferred relay URLs for logs.</td></tr>145 <tr><td class="btn">verification</td><td>no</td><td>Hex-encoded public key that verifies finds at this cache. See §6.</td></tr>146 <tr><td class="btn">F</td><td>no</td><td>Locks in the first-to-find winner: <code>["F", &lt;winner-pubkey-hex&gt;]</code>. Valid only with the <code>first-to-find</code> modifier. At most one <code>F</code> tag should be present. See §7.</td></tr>147 </table></div>148149 <p>Cache types are determined by individual clients. Each client decides which cache types it supports, based on its implementation needs. The submitter owns the listing. The submitter maintains the core details. Community logs provide context on the current state and validity of the cache.</p>150151 <h3>The mission tag ("Key Quest")</h3>152 <p>A <code>mission</code> tag states a task that finders must complete to legitimately claim the cache. Examples: a passphrase, a riddle answer, or an item to bring. A treasure must not include more than one <code>mission</code> tag. If multiple are present, clients should use the first and ignore the rest.</p>153 <p>When a <code>mission</code> is present, clients should restrict found-log submission to finders who have proof of physical presence. That proof is typically the verification key from the cache location (§6). A client may record a completed mission as a NIP-GD Good Deed event whose <code>a</code> tag references the cache.</p>154155 <div class="box tech">156 <span class="tag">Tech Note</span>157 <p>The source spec links mission completions to "NIP-GD" Good Deed events. NIP-GD does not exist in the NIP repository or in this manual. The reference is dead until that NIP is published.</p>158 </div>159160 <h2 class="bar"><span class="num">3</span> Found Log — Kind 7516</h2>161 <p>A found log is a regular event of kind <code>7516</code>. It records one successful visit to one geocache. The <code>content</code> holds the log message.</p>162163 <div class="crt">164 <div class="titlebar">Wire format - found log</div>165<pre>{166 <span class="k">"kind"</span>: 7516,167 <span class="k">"content"</span>: <span class="c">&lt;log message&gt;</span>,168 <span class="k">"tags"</span>: [169 [<span class="s">"a"</span>, <span class="s">"37516:&lt;pubkey&gt;:&lt;d-tag&gt;"</span>]170 ]171}</pre>172 </div>173174 <div class="tscroll"><table class="ref">175 <caption>Found log tags</caption>176 <tr><th>Tag</th><th>Required</th><th>Rule</th></tr>177 <tr><td class="btn">a</td><td>yes</td><td>Reference to the geocache being logged: <code>37516:&lt;pubkey&gt;:&lt;d-tag&gt;</code>.</td></tr>178 <tr><td class="btn">image</td><td>no</td><td>Photos from the visit.</td></tr>179 <tr><td class="btn">verification</td><td>no</td><td>Embedded verification event as a JSON string. See §6.</td></tr>180 </table></div>181182 <h2 class="bar"><span class="num">4</span> Comment Logs — Kind 1111</h2>183 <p>Non-found logs use comment events of kind <code>1111</code>, following the <a href="22.html">NIP-22</a> comment structure. These events capture failures, notes, and status information about the cache via human reporting. In the NIP-22 threading model the geocache listing is both the root content and the parent content.</p>184185 <div class="crt">186 <div class="titlebar">Wire format - comment log</div>187<pre>{188 <span class="k">"kind"</span>: 1111,189 <span class="k">"content"</span>: <span class="c">&lt;log message&gt;</span>,190 <span class="k">"tags"</span>: [191 [<span class="s">"A"</span>, <span class="s">"37516:&lt;pubkey&gt;:&lt;d-tag&gt;"</span>],192 [<span class="s">"K"</span>, <span class="s">"37516"</span>],193 [<span class="s">"P"</span>, <span class="c">&lt;cache-owner-pubkey&gt;</span>],194 [<span class="s">"a"</span>, <span class="s">"37516:&lt;pubkey&gt;:&lt;d-tag&gt;"</span>],195 [<span class="s">"k"</span>, <span class="s">"37516"</span>],196 [<span class="s">"p"</span>, <span class="c">&lt;cache-owner-pubkey&gt;</span>],197 [<span class="s">"t"</span>, <span class="c">&lt;log-type&gt;</span>]198 ]199}</pre>200 </div>201202 <p>The uppercase <code>A</code>/<code>K</code>/<code>P</code> tags mark the root. The lowercase <code>a</code>/<code>k</code>/<code>p</code> tags mark the parent. Both follow <a href="22.html">NIP-22</a>. For these top-level comments, root and parent are identical: they reference the listing coordinate (<code>37516:&lt;pubkey&gt;:&lt;d-tag&gt;</code>), the kind <code>37516</code>, and the cache owner's pubkey.</p>203204 <div class="tscroll"><table class="ref">205 <caption>Comment log types (the t tag)</caption>206 <tr><th>Value</th><th>Meaning</th></tr>207 <tr><td class="btn">dnf</td><td>Did not find. The finder searched and failed.</td></tr>208 <tr><td class="btn">note</td><td>Helpful or neutral context. The default when the <code>t</code> tag is absent.</td></tr>209 <tr><td class="btn">maintenance</td><td>The cache needs attention.</td></tr>210 <tr><td class="btn">archived</td><td>The cache is officially retired. Only meaningful from the cache owner.</td></tr>211 </table></div>212213 <p>An <code>image</code> tag with photos from the visit is optional on comment logs too. The cache owner can officially retire a cache with the <code>archived</code> value in the <code>t</code> tag. This preserves the cache's history without fully deleting it.</p>214215 <h2 class="bar"><span class="num">5</span> Verification Event — Kind 7517</h2>216 <p>A verification event is a regular event of kind <code>7517</code>. It provides cryptographic proof that someone physically located a geocache. The cache's <strong>verification private key</strong> signs this event — not the finder's key.</p>217218 <div class="crt">219 <div class="titlebar">Wire format - verification event</div>220<pre>{221 <span class="k">"kind"</span>: 7517,222 <span class="k">"content"</span>: <span class="s">"Geocache verification for &lt;finder-npub&gt;"</span>,223 <span class="k">"tags"</span>: [224 [<span class="s">"a"</span>, <span class="s">"&lt;finder-pubkey-hex&gt;:&lt;geocache-naddr&gt;"</span>]225 ]226}</pre>227 </div>228229 <p>The <code>content</code> must follow the static format <code>"Geocache verification for &lt;finder-npub&gt;"</code>. Here <code>&lt;finder-npub&gt;</code> is the <a href="19.html">NIP-19</a> encoded public key (npub) of the person who found the cache.</p>230 <p>The single required <code>a</code> tag is a composite identifier. It contains the finder's pubkey in hex format, then a colon, then the naddr of the geocache being verified.</p>231 <p>A finder creates this event after obtaining the cache's verification private key, typically via a QR code at the cache location. The event must be signed by that verification private key. The finder can then deliver it in three ways:</p>232 <ol>233 <li>Embed it in the <code>verification</code> tag of the found log (kind 7516) as a JSON string.</li>234 <li>Publish it to relays as a standalone event.</li>235 <li>Both embed and publish, for redundancy.</li>236 </ol>237238 <div class="box tech">239 <span class="tag">Tech Note</span>240 <p>The kind 7517 <code>a</code> tag value (<code>&lt;pubkey-hex&gt;:&lt;naddr&gt;</code>) does not follow the <a href="01.html">NIP-01</a> <code>a</code> tag coordinate format (<code>&lt;kind&gt;:&lt;pubkey&gt;:&lt;d-value&gt;</code>). Relays index the composite string as-is, so standard <code>#a</code> queries for the cache coordinate will not match these events.</p>241 </div>242243 <h2 class="bar"><span class="num">6</span> Verified Finds</h2>244 <p>A cache with a <code>verification</code> tag can prove that a finder physically located it. The proof is a kind 7517 event signed by the cache's verification key.</p>245 <h3>Verification process (finder side)</h3>246 <ol>247 <li>Obtain the cache's verification private key, typically via a QR code at the cache location.</li>248 <li>Create a verification event (kind 7517). Sign it with this key.</li>249 <li>Embed the verification event in your log entry.</li>250 </ol>251 <h3>Validation (verifier side)</h3>252 <p>To validate a verified find, perform four checks:</p>253 <ol>254 <li>Check that the verification event is signed by the expected verification public key.</li>255 <li>Verify that the finder pubkey in the <code>a</code> tag matches the log author.</li>256 <li>Confirm that the geocache naddr in the <code>a</code> tag correctly references the target cache.</li>257 <li>Validate the event signature with standard Nostr verification.</li>258 </ol>259260 <figure class="diagram">261 <div class="frame">262 <svg viewBox="0 0 560 300" role="img" aria-label="Sequence diagram: finder scans the QR code at the cache, signs a kind 7517 verification with the cache key, embeds it in a kind 7516 found log, and publishes to the relay">263 <line class="d-wire" x1="110" y1="40" x2="110" y2="285" stroke-dasharray="3 4"/>264 <line class="d-wire" x1="450" y1="40" x2="450" y2="285" stroke-dasharray="3 4"/>265 <rect class="d-actor" x="55" y="8" width="110" height="30" rx="6"/>266 <text class="d-actor-label" x="110" y="28" text-anchor="middle">Finder</text>267 <rect class="d-actor" x="395" y="8" width="110" height="30" rx="6"/>268 <text class="d-actor-label" x="450" y="28" text-anchor="middle">Relay</text>269 <text class="d-note" x="110" y="66" text-anchor="middle">scan QR at cache →</text>270 <text class="d-note" x="110" y="82" text-anchor="middle">verification privkey</text>271 <text class="d-note" x="110" y="118" text-anchor="middle">sign kind 7517</text>272 <text class="d-note" x="110" y="134" text-anchor="middle">with cache key</text>273 <path class="d-msg" d="M110,170 L445,170"/>274 <text class="d-label" x="280" y="163" text-anchor="middle">["EVENT", kind 7516 + embedded 7517]</text>275 <path class="d-msg blue" d="M450,205 L115,205"/>276 <text class="d-label" x="280" y="198" text-anchor="middle">["OK", &lt;id&gt;, true, ""]</text>277 <path class="d-msg" d="M110,240 L445,240"/>278 <text class="d-label" x="280" y="233" text-anchor="middle">["EVENT", kind 7517] (optional standalone)</text>279 <text class="d-note" x="280" y="272" text-anchor="middle">Any client can now validate the find with the four checks above.</text>280 </svg>281 </div>282 <figcaption>Fig. CC-2 — <b>A verified find.</b> The QR code hands out the cache key. The finder proves presence by signing with it.</figcaption>283 </figure>284285 <div class="box warn">286 <span class="tag">Warning!</span>287 <p>The verification private key is a shared secret printed at the cache site. Anyone who ever visited the cache can sign new 7517 events later. The proof means "had QR access", not "was there at this timestamp".</p>288 </div>289290 <h2 class="bar"><span class="num">7</span> Type Modifiers</h2>291 <p>A listing may include one or more <code>n</code> tags that classify the geocache with additional type modifiers. The <code>t</code> cache-type tag describes <em>how</em> a cache is found. The <code>n</code> modifiers describe <em>how the cache behaves</em> once published — its lifecycle, claim semantics, or prize nature.</p>292 <p>The <code>mission</code> tag is also a type modifier in the broader sense. It uses its own dedicated tag because it carries a payload: the mission text. Clients should treat <code>mission</code> and <code>n</code> modifiers consistently for display purposes, such as badges and filters.</p>293 <h3>Rules</h3>294 <ol>295 <li>Each modifier value belongs to exactly one category.</li>296 <li>A geocache should include at most one <code>n</code> tag per category. If multiple values from the same category are present, clients should use the first occurrence and ignore the rest.</li>297 <li>Modifiers from different categories compose freely. Any combination is valid unless a specific modifier's definition states otherwise.</li>298 <li>Clients should ignore <code>n</code> values they do not recognize. This allows forward compatibility as new modifiers are defined.</li>299 </ol>300301 <div class="tscroll"><table class="ref">302 <caption>Defined modifiers</caption>303 <tr><th>Category</th><th>Value</th><th>Meaning</th></tr>304 <tr><td>Claim semantics</td><td class="btn">first-to-find</td><td>Single-claim listing. The first verified found log is the exclusive claim. Requires a <code>verification</code> tag on the listing.</td></tr>305 <tr><td>Prize nature</td><td class="btn">art</td><td>The geocache itself is a physical work of art: a print, sculpture, sticker, zine, painted object, mural, installation, and so on. Whether the work is takeable, viewable in place, or photographable only is determined by other modifiers and by the <code>content</code> description.</td></tr>306 </table></div>307308 <h3>Claim semantics: first-to-find</h3>309 <p>The first verified found log — a kind 7516 event with a valid embedded kind 7517 — constitutes the exclusive claim. Subsequent verified found logs remain valid records of physical presence at the location. They do not constitute additional claims. Once any valid verified found log exists, clients should render the listing as effectively archived: hide the find-submission affordances and display the winning finder prominently.</p>310 <p>Determine the provisional winner, before lock-in, with these rules:</p>311 <ul>312 <li>The winning log is the verified found log with the earliest <code>created_at</code> value.</li>313 <li>Break ties on <code>created_at</code> by ascending lexicographic comparison of the event <code>id</code>.</li>314 <li>All verified logs are evidence of physical presence — QR access was required to produce them. The exclusive claim goes only to the earliest one.</li>315 </ul>316 <p><strong>Locking in the winner (the F tag).</strong> Once the listing creator has confirmed the claim, the creator should publish a new revision of the listing that does both of these things: it archives the listing by adding <code>["t", "archived"]</code>, and it locks the winner in by appending an <code>F</code> tag:</p>317 <div class="crt">318 <div class="titlebar">Lock-in revision - extra tags</div>319<pre>[<span class="s">"t"</span>, <span class="s">"archived"</span>],320[<span class="s">"F"</span>, <span class="c">&lt;winner-pubkey-hex&gt;</span>]</pre>321 </div>322 <ul>323 <li>The <code>F</code> value is the winning finder's pubkey in lowercase hex. To recover the specific winning log, query for verified found logs whose <code>a</code> tag references this treasure and whose author matches the <code>F</code> pubkey.</li>324 <li>At most one <code>F</code> tag should be present. If multiple are present, clients should use the first.</li>325 <li>When an <code>F</code> tag is present, clients must attribute the exclusive claim to the pubkey in the <code>F</code> tag — regardless of which verified found log currently appears earliest. <code>created_at</code> is author-supplied and forgeable. The lock protects the claim from a later log with a forged earlier timestamp.</li>326 </ul>327328 <figure class="diagram">329 <div class="frame">330 <svg viewBox="0 0 560 130" role="img" aria-label="First-to-find lifecycle: listing published, first verified found log makes a provisional winner, owner republishes with archived t tag and F tag to lock the winner">331 <rect class="d-actor" x="10" y="35" width="140" height="56" rx="8"/>332 <text class="d-actor-label" x="80" y="59" text-anchor="middle">Published</text>333 <text class="d-note" x="80" y="76" text-anchor="middle">n = first-to-find</text>334 <rect class="d-actor" x="205" y="35" width="150" height="56" rx="8"/>335 <text class="d-actor-label" x="280" y="59" text-anchor="middle">Provisional</text>336 <text class="d-note" x="280" y="76" text-anchor="middle">earliest verified log</text>337 <rect class="d-actor" x="410" y="35" width="140" height="56" rx="8"/>338 <text class="d-actor-label" x="480" y="59" text-anchor="middle">Locked</text>339 <text class="d-note" x="480" y="76" text-anchor="middle">t=archived + F tag</text>340 <path class="d-msg d-flow" d="M152,63 L202,63"/>341 <path class="d-msg d-flow" d="M357,63 L407,63"/>342 <text class="d-label" x="177" y="28" text-anchor="middle">7516+7517</text>343 <text class="d-label" x="382" y="28" text-anchor="middle">owner revision</text>344 <text class="d-note" x="280" y="118" text-anchor="middle">After lock-in, the F pubkey wins even if an earlier-dated log appears.</text>345 </svg>346 </div>347 <figcaption>Fig. CC-3 — <b>First-to-find lifecycle.</b> Timestamps pick the provisional winner. The owner's <code>F</code> tag makes it final.</figcaption>348 </figure>349350 <h3>Forward compatibility</h3>351 <p>Future revisions of this NIP, or supplementary NIPs, may define new modifiers. New categories may also be introduced. Clients implementing this NIP should ignore unknown <code>n</code> values rather than reject the event.</p>352353 <h2 class="bar"><span class="num">8</span> Curation Lists — Kind 37517</h2>354 <p>A curation list is an addressable event of kind <code>37517</code>. It groups geocaches into a curated collection. Clients may present these as adventures, trails, treasure hunts, or any other themed experience.</p>355356 <div class="crt">357 <div class="titlebar">Wire format - curation list</div>358<pre>{359 <span class="k">"kind"</span>: 37517,360 <span class="k">"content"</span>: <span class="c">&lt;full description&gt;</span>,361 <span class="k">"tags"</span>: [362 [<span class="s">"d"</span>, <span class="c">&lt;list-identifier&gt;</span>],363 [<span class="s">"title"</span>, <span class="c">&lt;list-title&gt;</span>],364 [<span class="s">"description"</span>, <span class="c">&lt;short summary&gt;</span>],365 [<span class="s">"image"</span>, <span class="c">&lt;banner-image-url&gt;</span>],366 [<span class="s">"g"</span>, <span class="c">&lt;geohash&gt;</span>],367 [<span class="s">"theme"</span>, <span class="c">&lt;page-theme&gt;</span>],368 [<span class="s">"map"</span>, <span class="c">&lt;map-style&gt;</span>],369 [<span class="s">"a"</span>, <span class="s">"37516:&lt;pubkey&gt;:&lt;d-tag&gt;"</span>],370 [<span class="s">"a"</span>, <span class="s">"37516:&lt;pubkey&gt;:&lt;d-tag&gt;"</span>]371 ]372}</pre>373 </div>374375 <p>The <code>content</code> field contains the full description of the list — rules, tips, narrative, or any other context the creator wants to provide.</p>376377 <div class="tscroll"><table class="ref">378 <caption>Curation list tags</caption>379 <tr><th>Tag</th><th>Required</th><th>Rule</th></tr>380 <tr><td class="btn">d</td><td>yes</td><td>Unique identifier for the list.</td></tr>381 <tr><td class="btn">title</td><td>yes</td><td>Human-readable name for the list.</td></tr>382 <tr><td class="btn">a</td><td>yes, 1+</td><td>References to geocache listing events (kind 37516 or 37515). Order is preserved and meaningful.</td></tr>383 <tr><td class="btn">description</td><td>no</td><td>Short summary shown in browse and card views.</td></tr>384 <tr><td class="btn">image</td><td>no</td><td>Banner image URL.</td></tr>385 <tr><td class="btn">g</td><td>no</td><td>Geohash of the list's center location. Include multiple precision levels (3-6 characters) for discovery.</td></tr>386 <tr><td class="btn">theme</td><td>no</td><td>Default page theme for the list. Supported values: <code>adventure</code>, <code>mojave</code>. Clients apply it unless the user chose a different theme.</td></tr>387 <tr><td class="btn">map</td><td>no</td><td>Default map style for the list. Supported values: <code>original</code>, <code>dark</code>, <code>satellite</code>, <code>adventure</code>. Clients use it as the initial style but allow the user to change it.</td></tr>388 </table></div>389390 <p><strong>Cross-author references.</strong> A curation list can reference any public geocache, regardless of author. The <code>a</code> tags use the standard <a href="01.html">NIP-01</a> addressable event coordinates (<code>&lt;kind&gt;:&lt;pubkey&gt;:&lt;d-tag&gt;</code>). One list can span geocaches from multiple creators.</p>391392 <div class="box tech">393 <span class="tag">Tech Note</span>394 <p>The <code>a</code> tag rule permits references to "kind 37516 or 37515" listings. Kind 37515 is not defined anywhere in this NIP. It appears to be a legacy or external listing kind carried over without a definition.</p>395 </div>396397 <h2 class="bar"><span class="num">9</span> Client Guidelines</h2>398 <p>For the best geocaching experience, a client that implements this NIP should:</p>399 <ul>400 <li>Support hint encoding, such as ROT13, to prevent spoilers.</li>401 <li>Determine cache status from recent log patterns. Multiple DNF entries and/or maintenance notes indicate an issue with the cache.</li>402 <li>Publish logs to the relays listed in the cache's <code>r</code> tags, when available.</li>403 <li>Validate geohash precision before accepting a cache submission: at least 8 characters, and at least 9 for micro caches.</li>404 </ul>405406 <h2 class="bar" id="examples"><span class="num">10</span> Worked Example</h2>407 <p>One cache, one find, one failure, one collection. The owner hides a verified treasure in Oslo. A finder scans the QR code and posts a verified found log. Another visitor strikes out and posts a DNF comment.</p>408409 <div class="crt">410 <div class="titlebar">Event 1 - the listing (owner publishes)</div>411<pre>{412 <span class="k">"kind"</span>: 37516,413 <span class="k">"content"</span>: <span class="s">"High-security treasure requiring physical verification!"</span>,414 <span class="k">"tags"</span>: [415 [<span class="s">"d"</span>, <span class="s">"verified-treasure-1748619568669"</span>],416 [<span class="s">"name"</span>, <span class="s">"Verified Treasure"</span>],417 [<span class="s">"g"</span>, <span class="s">"u4x"</span>], [<span class="s">"g"</span>, <span class="s">"u4xsu6"</span>], [<span class="s">"g"</span>, <span class="s">"u4xsu6ry"</span>],418 [<span class="s">"D"</span>, <span class="s">"3"</span>],419 [<span class="s">"T"</span>, <span class="s">"2"</span>],420 [<span class="s">"S"</span>, <span class="s">"small"</span>],421 [<span class="s">"t"</span>, <span class="s">"traditional"</span>],422 [<span class="s">"hint"</span>, <span class="s">"Look for the secret code"</span>],423 [<span class="s">"verification"</span>, <span class="s">"6805d4e5c0df48b4…f34f1c07"</span>]424 ]425}</pre>426 </div>427428 <div class="crt">429 <div class="titlebar">Event 2 - verification (signed by the cache key from the QR)</div>430<pre>{431 <span class="k">"kind"</span>: 7517,432 <span class="k">"content"</span>: <span class="s">"Geocache verification for npub1qc0lc5lxnhxnf…qd8h2z3"</span>,433 <span class="k">"tags"</span>: [434 [<span class="s">"a"</span>, <span class="s">"0461fcbecc4c3374…35a474dd:naddr1qqxnzd3e8q6n2dfk8…qfgrf8"</span>]435 ],436 <span class="k">"pubkey"</span>: <span class="s">"6805d4e5c0df48b4…f34f1c07"</span>, <span class="c">// the cache's verification pubkey</span>437 <span class="k">"created_at"</span>: 1672531200,438 <span class="k">"sig"</span>: <span class="s">"a1b2c3d4e5f67890…cdef12"</span>439}</pre>440 </div>441442 <div class="crt">443 <div class="titlebar">Event 3 - verified found log (signed by the finder)</div>444<pre>{445 <span class="k">"kind"</span>: 7516,446 <span class="k">"content"</span>: <span class="s">"Found it! Great hiding spot."</span>,447 <span class="k">"tags"</span>: [448 [<span class="s">"a"</span>, <span class="s">"37516:0461fcbecc4c3374…35a474dd:verified-treasure-1748619568669"</span>],449 [<span class="s">"verification"</span>, <span class="s">"{\"kind\":7517,\"content\":\"Geocache verification for npub1qc0…\",…}"</span>]450 ]451}</pre>452 </div>453454 <div class="crt">455 <div class="titlebar">Event 4 - DNF comment - and the curation list</div>456<pre><span class="c">-- a less lucky visitor reports a DNF --</span>457{458 <span class="k">"kind"</span>: 1111,459 <span class="k">"content"</span>: <span class="s">"Searched for 30 minutes but couldn't find it. Maybe it's missing?"</span>,460 <span class="k">"tags"</span>: [461 [<span class="s">"A"</span>, <span class="s">"37516:0461fcbe…74dd:verified-treasure-1748619568669"</span>],462 [<span class="s">"K"</span>, <span class="s">"37516"</span>],463 [<span class="s">"P"</span>, <span class="s">"0461fcbe…74dd"</span>],464 [<span class="s">"a"</span>, <span class="s">"37516:0461fcbe…74dd:verified-treasure-1748619568669"</span>],465 [<span class="s">"k"</span>, <span class="s">"37516"</span>],466 [<span class="s">"p"</span>, <span class="s">"0461fcbe…74dd"</span>],467 [<span class="s">"t"</span>, <span class="s">"dnf"</span>]468 ]469}470471<span class="c">-- the owner groups this cache into a themed hunt --</span>472{473 <span class="k">"kind"</span>: 37517,474 <span class="k">"content"</span>: <span class="s">"Explore the festival grounds and find all hidden treasures!"</span>,475 <span class="k">"tags"</span>: [476 [<span class="s">"d"</span>, <span class="s">"ren-fest-hunt-1748619568670"</span>],477 [<span class="s">"title"</span>, <span class="s">"Texas Ren Fest Treasure Hunt"</span>],478 [<span class="s">"description"</span>, <span class="s">"Find all the hidden treasures at the festival!"</span>],479 [<span class="s">"g"</span>, <span class="s">"9vk"</span>], [<span class="s">"g"</span>, <span class="s">"9vk5b7"</span>],480 [<span class="s">"theme"</span>, <span class="s">"adventure"</span>],481 [<span class="s">"map"</span>, <span class="s">"adventure"</span>],482 [<span class="s">"a"</span>, <span class="s">"37516:0461fcbe…74dd:first-treasure-1748619568668"</span>],483 [<span class="s">"a"</span>, <span class="s">"37516:0461fcbe…74dd:verified-treasure-1748619568669"</span>]484 ]485}</pre>486 </div>487488 <p>For a first-to-find art drop, the listing adds <code>["n", "first-to-find"]</code> and <code>["n", "art"]</code>, plus a <code>verification</code> tag. After the first verified log arrives, the owner republishes the listing with <code>["t", "archived"]</code> and <code>["F", &lt;winner-pubkey-hex&gt;]</code> to lock the claim (§7).</p>489490 <h2 class="bar" id="history"><span class="num">11</span> Version History</h2>491 <p>NIP-CC is young. It landed in 2026 and received one major revision two weeks later:</p>492 <ul class="patchnotes">493 <li><span class="ver">2026</span><span class="when">2026-06</span>Major update by Chad Curtis (<a href="https://github.com/nostr-protocol/nips/pull/2365">#2365</a>): aligned the spec with the modern "NIP-GC" implementation — verification events, type modifiers (<code>first-to-find</code>, <code>art</code>), the <code>F</code> lock-in tag, missions, and curation lists.</li>494 <li><span class="ver">Origin</span><span class="when">2026-05-28</span>fiatjaf merged the initial "add NIP-CC: geocaching" spec: listings, found logs, and comment logs.</li>495 </ul>496497 <div class="credits">498 <h3 class="cardhead">Original Proposal - Credits</h3>499 <table>500 <tr><td>Author</td><td>fiatjaf</td></tr>501 <tr><td>First commit</td><td>2026-05-28 — “add NIP-CC: geocaching”</td></tr>502 <tr><td>Status</td><td><span class="chip draft">draft</span><span class="chip">optional</span></td></tr>503 <tr><td>Source</td><td><a href="https://github.com/nostr-protocol/nips/blob/master/CC.md">CC.md on GitHub</a> - <a href="https://github.com/nostr-protocol/nips/commits/master/CC.md">full change history</a></td></tr>504 </table>505 </div>506507 <h2 class="bar"><span class="num">12</span> See Also</h2>508 <ul>509 <li><a href="01.html">NIP-01</a> — addressable events, the <code>d</code> tag, <code>a</code> tag coordinates, and single-letter tag indexing used throughout.</li>510 <li><a href="22.html">NIP-22</a> — the comment structure (<code>A</code>/<code>K</code>/<code>P</code> and <code>a</code>/<code>k</code>/<code>p</code>) that kind 1111 logs follow.</li>511 <li><a href="19.html">NIP-19</a> — the npub and naddr encodings used in verification events.</li>512 <li><a href="52.html">NIP-52</a> — calendar events; another way to attach real-world activity to Nostr.</li>513 <li><a href="73.html">NIP-73</a> — external content IDs, useful for referencing off-Nostr cache databases.</li>514 </ul>515 </div>516517 <aside>518 <div class="cartridge">519 <div class="inner">520 <h3 class="cardhead">Spec Card</h3>521 <div class="lights"><span class="led on"></span><span class="led on"></span><span class="led on"></span></div>522 <dl>523 <dt>Status</dt><dd><span class="chip draft">draft</span><span class="chip">optional</span></dd>524 <dt>Defines</dt><dd>cache listings - found logs - verification proofs - type modifiers - curation lists</dd>525 <dt>Kinds</dt><dd>37516 - 7516 - 7517 - 37517 (+ 1111 comments)</dd>526 <dt>Requires</dt><dd><a href="01.html">NIP-01</a> - <a href="22.html">NIP-22</a> - <a href="19.html">NIP-19</a></dd>527 <dt>Location</dt><dd>geohash <code>g</code> tags, 3-9 chars</dd>528 <dt>Crypto</dt><dd>shared verification keypair via QR</dd>529 <dt>First commit</dt><dd>2026-05-28</dd>530 <dt>Last updated</dt><dd>2026-06-11</dd>531 </dl>532 </div>533 </div>534 </aside>535 </main>536537 <nav class="navbtns">538 <a href="c7.html">◀ NIP-C7: Chats</a>539 <a href="ee.html">NIP-EE: E2EE Messaging using MLS ▶</a>540 </nav>541542 <footer class="pagefoot">543 <a href="../index.html">Nostr Protocol Manual</a>544 <span class="pageno">NIP CC / F4</span>545 </footer>546</div>547548<script src="../assets/webmcp.js" defer></script>549</body>550</html>