Resolve a BNS name from your own code

What this page gets you

Follow it top to bottom and you'll be able to:

• Take a string like sirius.x or hello.bch, hit the Bitcoin Cash chain, and get back the records its owner published — without trusting navigate.st, silentmode.st, or any other operator-run service.
• Pick the right record (s3, u, ip, h, p, a, …), fetch the content and present it to your user.
• Verify what the chain says against the owner's wallet signature, so a malicious indexer can't rewrite answers in flight.
• Embed Ariadne's Thread — the production resolver — into your own Windows installer, Android app, Electron desktop app, or server, so your users don't have to install anything extra.

The complete spec lives in Decentralized.DNS/PROTOCOL.md on the forge. This page is the orientation that tells an agent where to look and what to copy.

BNS1 — the protocol in one page

Names are anchored by CashTokens certificates. Records travel in OP_RETURN. Discovery uses a beacon address. That is the whole protocol.

Three mechanisms

The three operations

• REG — one tx that mints the certificate and carries BNS1{"o":"REG","n":"<name>","r":{…}} and pays the beacon.
• UPD — one tx that spends-and-recreates the certificate (ownership proof) and carries BNS1{"o":"UPD","n":"<name>","r":{…}}.
• REL — spends the certificate without recreating it (burns it) and carries BNS1{"o":"REL","n":"<name>"}. The name returns to the pool after a one-block gap.

TLDs use the same shape with TREG / TUPD opcodes against a second beacon.

Network constants (chipnet)

// Everything you need to query the chain. These are constants —
// they do not change until the network is bumped.
const PREFIX           = "BNS1";
const BEACON           = "bchtest:qp8njaa9a3ahg7259s5qajnce526n0rttsq8qwx4jl";
const BEACON_SCRIPTHASH = "e1cdbba719436f49acb4bf245b44df875c6d6b405eda46a9d3e736d138102f3b";
const TLD_BEACON       = "bchtest:qzc4c76vtw9nd49g6x8nmvc0jz62uvk4dc7hmpmerh";
const TLD_SCRIPTHASH   = "c85db10e106606273422b2733b2a6fb8b35a4d0e7dbfb20cf59bdb0833c008b8";
const BEACON_DUST_SAT  = 600;
const NAME_RE          = /^[a-z0-9-]{1,32}$/;

The authoritative table — chipnet beacons, mainnet beacons (unpinned until mainnet launches), the Electrum pool, the operator address — is in Argus/src/lib/resolver-web.js. Memory rule: that file is the only source of truth; divergence is a consensus split.

Indexer rules you must apply (consensus-critical)

1. Fetch beacon history, sort by (height, txid); unconfirmed last.
2. Reorder causally — never process a tx before one it spends. Otherwise an UPD can land before its own REG and be dropped silently and permanently.
3. REG is valid only if the tx mints a certificate whose commitment matches the name, the name is free, and the category is created in this tx (output 0 spends the txid-outpoint) with exactly one NFT output and no fungible amount. First valid REG wins. If the name was released, REG must be at least one block after the release.
4. UPD is valid if some output of the tx carries the name's category.
5. REL is valid if the name is registered, no output carries its category, and an input spends an output of an earlier beacon tx carrying the certificate.
6. One message per transaction. A tx with more than one BNS payload carries none. (Added 2026-10-04.)

Record types

Records are a JSON object. Keep the full OP_RETURN payload under 200 bytes. All keys optional; mix freely.

The resolver picks the first record type it understands. The canonical precedence used by Theseus and Ariadne lives in Argus/src/lib/record-picker.js — follow it so answers match across clients.

Minimum viable resolver — under 100 lines of Node.js

The whole flow: open one Electrum WebSocket, pull the beacon's history, parse the OP_RETURNs, apply the rules, return a record. This runs without any Silent Mode code at all.

// bns-mini.mjs — a one-file BNS resolver for chipnet.
// node bns-mini.mjs sirius.x

import WebSocket from "ws";
import { createHash } from "crypto";

const BEACON_SCRIPTHASH =
  "e1cdbba719436f49acb4bf245b44df875c6d6b405eda46a9d3e736d138102f3b";
const ELECTRUM = "wss://chipnet.imaginary.cash:50004";
const PREFIX   = "BNS1";

const query = process.argv[2] || "sirius.x";
const [label, tld = "bch"] = query.toLowerCase().split(".");
const wantName = tld === "bch" ? label : `${label}.${tld}`;

// --- 1. open the Electrum socket ---
const ws = new WebSocket(ELECTRUM);
await new Promise(r => ws.on("open", r));
let id = 0;
const rpc = (method, params = []) => new Promise((resolve) => {
  const mine = ++id;
  ws.on("message", function h(m) {
    const msg = JSON.parse(m);
    if (msg.id === mine) { ws.off("message", h); resolve(msg.result); }
  });
  ws.send(JSON.stringify({ id: mine, method, params }));
});

// --- 2. pull the beacon's history ---
const hist = await rpc("blockchain.scripthash.get_history", [BEACON_SCRIPTHASH]);
hist.sort((a, b) => (a.height || 1e9) - (b.height || 1e9) ||
                   a.tx_hash.localeCompare(b.tx_hash));

// --- 3. for each tx, parse the OP_RETURN; rebuild the name index ---
const names = new Map(); // name -> records
for (const { tx_hash } of hist) {
  const tx = await rpc("blockchain.transaction.get", [tx_hash, true]);
  for (const vout of tx.vout || []) {
    const script = vout.scriptPubKey?.hex || "";
    if (!script.startsWith("6a")) continue;        // not OP_RETURN
    const payload = extractPayload(script);
    if (!payload?.startsWith(PREFIX)) continue;
    let p;
    try { p = JSON.parse(payload.slice(PREFIX.length)); } catch { continue; }
    if (p.o === "REG" && !names.has(p.n)) names.set(p.n, p.r || {});
    else if (p.o === "UPD" && names.has(p.n)) names.set(p.n, p.r || {});
    else if (p.o === "REL") names.delete(p.n);
  }
}

console.log(wantName, "→", names.get(wantName) ?? "<not registered>");
ws.close();

// --- OP_RETURN parser (one push, enough for BNS1) ---
function extractPayload(hex) {
  let i = 2, len;
  const op = parseInt(hex.slice(i, i + 2), 16); i += 2;
  if (op <= 0x4b) len = op;
  else if (op === 0x4c) { len = parseInt(hex.slice(i, i + 2), 16); i += 2; }
  else return null;
  return Buffer.from(hex.slice(i, i + len * 2), "hex").toString("utf8");
}

Run it:

$ npm i ws
$ node bns-mini.mjs sirius.x
sirius.x → { s3: 'bns/sirius.x/' }

$ node bns-mini.mjs theseus.x
theseus.x → { s3: 'bns/theseus/', u: 'https://silentmode.st/tools/#theseus' }

Reference implementations

Every production BNS client is open-source. If your language or runtime matches one of these, port the parsers verbatim — divergence is a consensus bug.

Spec documents to copy into your test suite

• PROTOCOL.md — BNS1 core
• DESIGN-tld-registry.md — per-TLD NFTs on the TLD beacon
• DESIGN-signed-records-manifest.md — wallet-signed DNS block
• PROTOCOL-ADDENDUM-release.md — REL opcode
• PROTOCOL-ADDENDUM-blocklist.md — community blocklists

Public endpoints (convenience, not consensus)

Everything above gets you a resolver that trusts only the chain. The following endpoints are convenience caches on top; use them for prototyping, UX speed-ups, or servers that don't want to track the chain themselves — but understand the trust shift.

None of these are required. Theseus and Ariadne use them as warm-start caches; the same client also runs a live Electrum query in parallel so the authoritative chain answer always wins.

Embed Ariadne's Thread in your own app

If you ship software with a browser surface — an Electron app, a Chromium wrapper, a game launcher, a wallet, a CLI, a Node service — you can give your users BNS resolution for free. Three paths, in order of effort:

1 — Chain-install the Windows service

Easiest. The Ariadne's Thread installer is a standalone resolver that hooks into NRPT and the HTTPS loopback. Once it is installed, every browser and every app that follows the OS DNS stack can resolve .bch, .x, and the other BNS TLDs — Firefox, curl, your mail client, your own app.

In your installer, add a chain-install step that silently runs the Thread's AriadneResolver-Setup.exe /S after your own install finishes. The service is opt-out: present a checkbox and respect it. Theseus does this today.

; NSIS fragment (works in Inno Setup similarly)
Section "BNS resolution — Ariadne's Thread (recommended)" secAriadne
  SetOutPath "$TEMP"
  File "AriadneResolver-Setup.exe"
  ExecWait '"$TEMP\AriadneResolver-Setup.exe" /S'
  Delete "$TEMP\AriadneResolver-Setup.exe"
SectionEnd

2 — Use the resolver library directly

If your app is a JavaScript runtime (Node, Electron, browser-with-crypto), import the Argus resolver and skip the service:

import { resolveName } from
  "https://code.silentmode.st/silentmode/ariadne/raw/branch/master/Argus/src/lib/resolver-web.js";

const result = await resolveName("sirius.x");
// → { s3: "bns/sirius.x/" }

The function talks to the public Electrum pool out of the box; pass your own electrum array in the options to pin servers. Full API in the module header. License is MPL-2.0 — your project can be any license as long as changes to resolver-web.js itself stay MPL.

3 — Call the local HTTP API

If the user has the Thread installed, it exposes a tiny API on 127.0.0.1:4626 (and https://ariadne.local with the per-machine CA):

GET /api/name/<name>  →  { records, owner, category, chain_tip }
GET /api/dns/<name>   →  { A, AAAA, MX, TXT, NS, SRV, CAA, ... } (verified)
GET /api/tlds          →  { tlds: [...] }
GET /health            →  { ok, tip, electrum, snapshot_age_s }

Use this when you want BNS resolution without redistributing the Thread yourself. If the /health probe fails, degrade gracefully — the user may not have it installed yet, which is a good moment to link them at silentmode.st/releases.

Platforms we cover today

License, naming, attribution

• The Ariadne resolver, Thread service, and Theseus browser are MPL-2.0. You can embed them in a proprietary app; changes to the resolver files themselves must stay MPL and be upstreamed.
• The Argus indexer libraries are Apache-2.0 — permissive, re-license-friendly.
• Protocol spec documents are CC BY 4.0.
• You may call out "Supports BNS", "Uses Ariadne's Thread" or "Powered by Ariadne" in your UI. Please do not imply endorsement without asking first — see ariadne.x/brand.