theseus-site/dev/index.html

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Developers — Theseus.X</title>
<meta name="description" content="Theseus Navigator developer guide: how the embedded resolver works, how to write a plug-in or an extension, how to add Ariadne's Thread to your own app so your users can resolve BNS names.">
<link rel="icon" href="assets/favicon.svg" type="image/svg+xml">
<link rel="mask-icon" href="assets/favicon.svg" color="#d6ff3d">
<meta property="og:type" content="article">
<meta property="og:site_name" content="theseus.x">
<meta property="og:title" content="Developers — Theseus.X">
<meta property="og:description" content="Resolver spec, plug-in and extension APIs, and how to embed Ariadne's Thread in your own app.">
<meta property="og:url" content="https://theseus.x/dev/">

<style>
  :root{
    --bg:#0b0e14; --panel:#141a24; --panel2:#18202c; --line:rgba(255,255,255,.09);
    --ink:#e7eaf1; --mut:#8b98a9; --dim:#5e6678; --acid:#d6ff3d;
    --ok:#4fd1a5; --warn:#ffc75f;
  }
  *{box-sizing:border-box}
  html{scroll-behavior:smooth}
  body{margin:0;background:radial-gradient(1100px 560px at 50% -12%,#16202e,var(--bg));
       color:var(--ink);font:16px/1.65 system-ui,-apple-system,Segoe UI,Roboto,sans-serif;min-height:100vh;padding-top:52px}
  a{color:var(--acid)}
  .wrap{max-width:900px;margin:0 auto;padding:0 1.2rem}

  .topnav{position:fixed;top:0;left:0;right:0;z-index:20;display:flex;gap:2px;align-items:center;flex-wrap:wrap;
       padding:10px 1.2rem;background:rgba(11,14,20,.88);backdrop-filter:blur(10px)}
  .topnav .brand{font-weight:600;color:var(--ink);text-decoration:none;margin-right:14px;font-size:15px;
       letter-spacing:.2px;display:flex;align-items:center;gap:8px}
  .topnav .brand .g{color:var(--acid)}
  .topnav .brand svg{width:20px;height:20px}
  .topnav a{color:var(--mut);text-decoration:none;padding:6px 12px;border-radius:8px;font-size:14px;
       display:inline-flex;align-items:center;gap:6px}
  .topnav a:hover{color:var(--ink);background:var(--panel)}
  .topnav a.here{color:var(--acid);background:rgba(214,255,61,.08)}
  .topnav a svg.tabicon{width:15px;height:15px;flex:none}
  .topnav a .g{color:var(--acid)}
  .topnav .menu{display:none}
  @media (max-width:720px){
    .topnav{flex-wrap:nowrap;padding:10px 1rem}
    .topnav .brand{margin-right:0}
    .topnav > a:not(.brand){display:none}
    .topnav .menu{display:block;margin-left:auto;position:relative}
    .topnav .menu > summary{list-style:none;cursor:pointer;padding:8px 10px;
         border-radius:8px;color:var(--mut);display:inline-flex;align-items:center;gap:6px}
    .topnav .menu > summary::-webkit-details-marker{display:none}
    .topnav .menu > summary svg{width:22px;height:22px;display:block}
    .topnav .menu > summary:hover,
    .topnav .menu[open] > summary{color:var(--ink);background:var(--panel)}
    .topnav .menu .menu-panel{position:absolute;top:calc(100% + 6px);right:0;
         background:var(--bg);border:1px solid var(--line);border-radius:12px;
         padding:6px;min-width:220px;display:flex;flex-direction:column;gap:2px;
         box-shadow:0 10px 32px rgba(0,0,0,.55)}
    .topnav .menu .menu-panel a{padding:10px 14px;border-radius:8px;font-size:14.5px;
         color:var(--mut);text-decoration:none;display:flex;align-items:center;gap:8px}
    .topnav .menu .menu-panel a:hover{color:var(--ink);background:var(--panel)}
  }

  header.hero{text-align:center;padding:4rem 1.2rem 1.5rem}
  .lede-mark{display:inline-block}
  .lede-mark svg{width:72px;height:72px}
  h1{font-size:clamp(1.9rem,5vw,2.6rem);margin:.6rem 0 .4rem;letter-spacing:-.4px}
  h1 .g{color:var(--acid)}
  .tag{color:var(--mut);font-size:1.02rem;max-width:720px;margin:0 auto}
  .tag code{background:#0e131b;border:1px solid var(--line);border-radius:5px;padding:1px 5px;
       font-family:ui-monospace,monospace;font-size:.92em;color:var(--acid)}

  section{padding:2.2rem 0;border-top:1px solid var(--line);margin-top:2rem;scroll-margin-top:72px}
  section:first-of-type{border-top:none;margin-top:1rem}
  h2{font-size:1.4rem;margin:0 0 .5rem}
  h2 .g{color:var(--acid)}
  h3{font-size:1.05rem;margin:1.3rem 0 .4rem;color:var(--ink)}
  p{color:var(--mut);margin:0 0 .9rem}
  p b{color:var(--ink);font-weight:600}
  ul,ol{color:var(--mut);line-height:1.7;padding-left:1.3rem}
  ul li+li,ol li+li{margin-top:.25rem}
  code{background:#0e131b;border:1px solid var(--line);border-radius:5px;padding:1px 6px;
       font-family:ui-monospace,monospace;font-size:12.5px;color:var(--acid);word-break:break-all}
  pre{background:#0e131b;border:1px solid var(--line);border-radius:10px;padding:14px 16px;overflow-x:auto;
       font-family:ui-monospace,monospace;font-size:12.5px;line-height:1.55;color:#dde3ec;margin:.8rem 0}
  pre code{background:transparent;border:0;padding:0;color:inherit}
  pre .k{color:var(--acid)}
  pre .s{color:#9fd59f}
  pre .c{color:#5e6678;font-style:italic}
  pre .f{color:#8fc5ff}

  .cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(260px,1fr));gap:14px;margin:1rem 0}
  .card{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:16px 18px}
  .card h3{margin:0 0 .4rem;font-size:1rem}
  .card p{margin:0;font-size:13.5px}
  .card a.cta{display:inline-block;margin-top:.6rem;color:var(--acid);text-decoration:none;font-size:13px}
  .card a.cta:hover{text-decoration:underline}
  .note{background:var(--panel);border:1px solid var(--line);border-left:3px solid var(--acid);
       border-radius:10px;padding:14px 18px;color:var(--mut);font-size:14px;margin:1.2rem 0}
  .note b{color:var(--ink)}

  footer.deep{background:linear-gradient(180deg,transparent,rgba(255,255,255,.02));
       border-top:1px solid var(--line);padding:3rem 0 2rem;margin-top:3rem;color:var(--mut);font-size:13.5px}
  footer.deep .fwrap{max-width:980px;margin:0 auto;padding:0 1.2rem;display:grid;
       grid-template-columns:1.5fr repeat(3,1fr);gap:2rem}
  @media (max-width:820px){footer.deep .fwrap{grid-template-columns:1fr 1fr;gap:1.6rem}}
  @media (max-width:460px){footer.deep .fwrap{grid-template-columns:1fr;gap:1.4rem}}
  footer.deep .brand-col{max-width:280px}
  footer.deep .brand-col .brand{display:inline-flex;align-items:center;gap:8px;color:var(--ink);
       text-decoration:none;font-weight:600;font-size:16px;margin-bottom:.5rem}
  footer.deep .brand-col .brand .g{color:var(--acid)}
  footer.deep h5{color:var(--ink);font-size:12px;text-transform:uppercase;letter-spacing:.14em;
       margin:0 0 .8rem;font-weight:600}
  footer.deep ul{list-style:none;padding:0;margin:0;display:flex;flex-direction:column;gap:.5rem}
  footer.deep ul a{color:var(--mut);text-decoration:none;font-size:13.5px}
  footer.deep ul a:hover{color:var(--acid)}
  footer.deep ul a .g{color:var(--acid)}
  footer.deep ul a .ext{color:var(--dim);font-size:11px;margin-left:2px}
  footer.deep .bar{max-width:980px;margin:2rem auto 0;padding:1rem 1.2rem 0;
       border-top:1px solid var(--line);display:flex;justify-content:space-between;gap:1rem;
       flex-wrap:wrap;color:var(--dim);font-size:12px}
  footer.deep .bar .badge{background:rgba(214,255,61,.12);color:var(--acid);
       padding:2px 8px;border-radius:5px;font:600 10px/1.4 system-ui;
       letter-spacing:.14em;text-transform:uppercase;margin-right:8px}
  footer.deep .bar .mono{font-family:ui-monospace,monospace;font-size:11.5px}
</style>
</head>
<body>

<nav class="topnav">
  <a class="brand" href="../">
    <svg viewBox="0 0 64 64" aria-hidden="true">
      <rect width="64" height="64" rx="12" fill="#0b0e14"/>
      <path d="M32 6 L38 32 L26 32 Z" fill="#e04e4e"/>
      <path d="M38 32 L32 58 L26 32 Z" fill="#d6ff3d"/>
      <path d="M6 32 L32 27 L58 32 L32 37 Z" fill="#d6ff3d" opacity=".55"/>
      <circle cx="32" cy="32" r="3" fill="#0b0e14"/>
    </svg>
    <span>Theseus<span class="g">.X</span></span>
  </a>
  <a href="../plug-ins/">Plug-ins</a>
  <a href="../extensions/">Extensions</a>
  <a class="here" href="./">Developers</a>
  <a href="https://sirius.x/" title="Register a BCNR name"><svg class="tabicon" viewBox="0 0 64 64" aria-hidden="true"><rect width="64" height="64" rx="12" fill="#0b0e14"/><path d="M32 4 L36.4 27.6 L60 32 L36.4 36.4 L32 60 L27.6 36.4 L4 32 L27.6 27.6 Z" fill="#d6ff3d"/></svg><span>Sirius<span class="g">.X</span></span></a>
  <a class="get" href="../#download" style="margin-left:auto;background:rgba(214,255,61,.10);color:var(--acid);font-weight:500">Get Theseus</a>
  <details class="menu">
    <summary aria-label="Open menu">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M4 7h16M4 12h16M4 17h16"/></svg>
    </summary>
    <div class="menu-panel">
      <a href="../plug-ins/">Plug-ins</a>
      <a href="../extensions/">Extensions</a>
      <a href="./">Developers</a>
      <a href="https://sirius.x/">Sirius.X</a>
    </div>
  </details>
</nav>

<header class="hero">
  <div class="lede-mark">
    <svg viewBox="0 0 64 64" aria-hidden="true">
      <rect width="64" height="64" rx="12" fill="#0b0e14"/>
      <path d="M32 6 L38 32 L26 32 Z" fill="#e04e4e"/>
      <path d="M38 32 L32 58 L26 32 Z" fill="#d6ff3d"/>
      <path d="M6 32 L32 27 L58 32 L32 37 Z" fill="#d6ff3d" opacity=".55"/>
      <circle cx="32" cy="32" r="3" fill="#0b0e14"/>
    </svg>
  </div>
  <h1>Theseus for <span class="g">developers</span></h1>
  <p class="tag">
    Everything you need to extend Theseus Navigator, or borrow its superpower — on-device
    Bitcoin Cash Domain Name resolution — for whatever you are building. Theseus ships
    <a href="../plug-ins/">Ariadne's Thread</a> as a bundled plug-in; the same resolver can live
    inside your app too.
  </p>
</header>

<div class="wrap">

<section id="resolver">
  <h2>Resolve BNS names <span class="g">from your own code</span></h2>
  <p>The authoritative developer page is on Ariadne.X — the resolver is the Ariadne project. It
     covers the BNS1 protocol in one page, the record types, a 60-line Node.js resolver you can
     run as-is, and the pointers to every production implementation.</p>
  <div class="cards">
    <div class="card">
      <h3>→ Resolve a BNS name from your own code</h3>
      <p>Protocol, record types, minimum resolver, reference implementations, public endpoints.</p>
      <a class="cta" href="https://ariadne.x/dev/">ariadne.x/dev</a>
    </div>
    <div class="card">
      <h3>→ Ariadne's Thread</h3>
      <p>What it is, how it works, system-wide mode, trust model.</p>
      <a class="cta" href="https://ariadne.x/thread/">ariadne.x/thread</a>
    </div>
    <div class="card">
      <h3>→ Protocol spec</h3>
      <p>The authoritative BNS1 specification on the forge.</p>
      <a class="cta" href="https://code.silentmode.st/silentmode/ariadne/src/branch/master/Decentralized.DNS/PROTOCOL.md">PROTOCOL.md ↗</a>
    </div>
  </div>
</section>

<section id="embed">
  <h2>Add BNS to <span class="g">your own app</span></h2>
  <p>If you ship any kind of app with a browser surface — Electron, native, game launcher, mail
     client — your users can resolve <code>.bch</code>, <code>.x</code>, <code>.p2p</code> as soon
     as Ariadne's Thread is on the machine. Three paths:</p>

  <h3>Easiest — chain-install the Windows service</h3>
  <p>Bundle the Thread installer and run <code>AriadneResolver-Setup.exe /S</code> after your own
     install finishes. Theseus does this today. The resolver registers an NRPT rule that only
     affects BNS TLDs, so everything else on the machine is untouched.</p>

  <h3>JavaScript / Electron — import the resolver</h3>
  <pre><code><span class="k">import</span> { resolveName } <span class="k">from</span>
  <span class="s">"https://code.silentmode.st/silentmode/ariadne/raw/branch/master/Argus/src/lib/resolver-web.js"</span>;

<span class="k">const</span> { records } = <span class="k">await</span> <span class="f">resolveName</span>(<span class="s">"sirius.x"</span>);
<span class="c">// records.s3 → "bns/sirius.x/"</span></code></pre>

  <h3>Any language — HTTP API against a local Thread</h3>
  <p>If the Thread is installed, it exposes a local HTTP API on <code>127.0.0.1:4626</code>:</p>
  <pre><code>GET /api/name/&lt;name&gt;
GET /api/dns/&lt;name&gt;
GET /health</code></pre>

  <p>Full embedding guide, platform coverage table, and the NSIS/Inno chain-install snippets
     live on <a href="https://ariadne.x/dev/#embed">ariadne.x/dev/#embed</a>.</p>
</section>

<section id="extensions">
  <h2>Build an <span class="g">extension</span></h2>
  <p>Extensions are everyone's add-ons: published by any BCNR name holder, signed by that
     name's wallet, verified on your users' devices before a byte runs. They are not plug-ins —
     plug-ins are first-party and ship inside Theseus (see <a href="../plug-ins/">Plug-ins</a>).</p>

  <h3>Publish an extension</h3>
  <ol>
    <li>Register a <code>.x</code> name on <a href="https://sirius.x/">sirius.x</a>.</li>
    <li>Build your extension tarball — same manifest as Chrome extensions plus a Silent Mode
        <code>addon.json</code>.</li>
    <li>Upload it with <code>PUT /api/ext</code>, signed with the wallet that owns the name.</li>
    <li>Theseus verifies the signature against the on-chain owner before installing. Updates work
        the same way; your users' Theseus checks for a newer <code>updates.json</code> on your
        own Sia bucket.</li>
  </ol>
  <p>Walk-through: <a href="../extensions/publish/">theseus.x/extensions/publish</a>.</p>
</section>

<section id="plug-ins">
  <h2>Plug-ins <span class="g">(first-party)</span></h2>
  <p>Plug-ins are the few add-ons Silent Mode builds, signs with the operator key, and ships as
     part of Theseus — Aegis wallet, Ariadne's Thread, Shield blocker. Users enable or disable
     them from <b>Settings › Plug-ins</b>.</p>
  <p>If you have an idea for one, open an issue on
     <a href="https://code.silentmode.st/silentmode/theseus">silentmode/theseus</a> first — the
     plug-in surface is intentionally small and we triage proposals before accepting code.</p>
</section>

<section id="source">
  <h2>Where everything lives</h2>
  <ul>
    <li><a href="https://code.silentmode.st/silentmode/theseus">silentmode/theseus</a> — the browser</li>
    <li><a href="https://code.silentmode.st/silentmode/ariadne">silentmode/ariadne</a> — Ariadne.X site + resolver docs</li>
    <li><a href="https://code.silentmode.st/silentmode/sirius">silentmode/sirius</a> — the registrar</li>
    <li><a href="https://code.silentmode.st/silentmode/hephaestus">silentmode/hephaestus</a> — this forge</li>
  </ul>
</section>

</div>

<footer class="deep">
  <div class="fwrap">
    <div class="brand-col">
      <a class="brand" href="../">
        <svg viewBox="0 0 64 64" aria-hidden="true" width="24" height="24">
          <rect width="64" height="64" rx="12" fill="#0b0e14"/>
          <path d="M32 6 L38 32 L26 32 Z" fill="#e04e4e"/>
          <path d="M38 32 L32 58 L26 32 Z" fill="#d6ff3d"/>
          <path d="M6 32 L32 27 L58 32 L32 37 Z" fill="#d6ff3d" opacity=".55"/>
          <circle cx="32" cy="32" r="3" fill="#0b0e14"/>
        </svg>
        <span>Theseus<span class="g">.X</span></span>
      </a>
      <p>A Chromium-based browser that resolves Bitcoin Cash Domain Names on the device itself.</p>
    </div>
    <div>
      <h5>Developers</h5>
      <ul>
        <li><a href="./">Theseus dev guide</a></li>
        <li><a href="https://ariadne.x/dev/">Resolver guide <span class="ext">↗</span></a></li>
        <li><a href="https://code.silentmode.st/silentmode/theseus">Source <span class="ext">↗</span></a></li>
      </ul>
    </div>
    <div>
      <h5>Product</h5>
      <ul>
        <li><a href="../">Home</a></li>
        <li><a href="../plug-ins/">Plug-ins</a></li>
        <li><a href="../extensions/">Extensions</a></li>
        <li><a href="../brand/">Brand book</a></li>
        <li><a href="../whitepaper/">Whitepaper</a></li>
      </ul>
    </div>
    <div>
      <h5>Pantheon</h5>
      <ul>
        <li><a href="https://ariadne.x/">Ariadne<span class="g">.X</span> — mobile</a></li>
        <li><a href="https://sirius.x/">Sirius<span class="g">.X</span> — names</a></li>
        <li><a href="https://hephaestus.x/">Hephaestus<span class="g">.X</span> — forge</a></li>
      </ul>
    </div>
  </div>
  <div class="bar">
    <span><span class="badge">Alpha</span>theseus.x — a BCNR name resolving to a Sia-hosted site</span>
    <span class="mono">MPL-2.0 · docs CC BY 4.0</span>
  </div>
</footer>

</body>
</html>