silentmode/sirius
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(sirius-x): explain private / co-sign TLDs and the name market

Browse source 
The two features shipped without a user-facing explanation; the docs
page now has a section on the three TLD switches (hidden, cosign,
frozen), how the co-sign rule is enforced by every resolver and what
each side does in the approval flow, and a section on one-transaction
name sales with the trust model and the market endpoints.
This commit is contained in:
Local Dev 2026-09-19 09:17:23 +02:00
parent 1fdfb9b393
commit 034281fc9d
1 changed files with 78 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

78
docs/index.html
View file

@ -121,6 +121,8 @@
<h4>Contents</h4>
<a href="#tld-registry">TLD registry</a>
<a href="#register-name">Register a name</a>
<a href="#private-tlds">Private &amp; co-sign TLDs</a>
<a href="#market">Buying &amp; selling names</a>
<a href="#records">Records &amp; hosting</a>
<a href="#signed-records">Signed off-chain records</a>
<a href="#host">Host your name</a>
@ -173,6 +175,82 @@
</ol>
</section>
<section id="private-tlds">
<h2>Private &amp; co-sign TLDs</h2>
<p class="lede">A TLD owner decides who may register names under it, and the decision is
enforced by every resolver, not just by the shop. Three switches live in the TLD's
on-chain records (a <code>TUPD</code> signed by the owner's key):</p>
<table class="pricing">
<tr><th>Record</th><th>Who can register</th><th>How it is enforced</th></tr>
<tr><td><code>hidden: 1</code> (switched off)</td>
<td>Only the owner, from the dashboard. Off the public list.</td>
<td>Co-sign rule (below).</td></tr>
<tr><td><code>policy: "cosign"</code></td>
<td>Anyone, but every registration needs the owner's approval.</td>
<td>Co-sign rule (below).</td></tr>
<tr><td><code>policy: "frozen"</code></td>
<td>Nobody, owner included.</td>
<td>Resolvers drop every new registration.</td></tr>
</table>
<h3 style="margin-top:1.4rem">The co-sign rule</h3>
<p>A registration under a <code>cosign</code> or <code>hidden</code> TLD is only recognised
when the same transaction also <b>carries the TLD's own certificate</b> — the TLD NFT
goes in as an input and comes back out to its owner. Only the owner's key can spend that
NFT, so its presence is a signature nobody can forge, and nothing is consumed: the
certificate returns in the same transaction. Every conforming client (gateway, Theseus,
Ariadne desktop and mobile) applies the rule when it builds its index, judging each
registration against the TLD policy <b>in force at that block</b>, so switching a TLD
off later never invalidates names registered while it was open.</p>
<ol class="steps">
<li><b>Owner registering under a private TLD.</b>
<span>Open the TLD in the dashboard, type a label, register. The certificate is added
from your own wallet; you pay only the platform share of the name price.</span></li>
<li><b>Anyone registering under a co-sign TLD.</b>
<span>The normal register flow builds the full transaction with the owner's certificate
as its last input, you sign your part, and the request waits in the gateway's approval
queue (<code>POST /api/cosign</code>). Nothing leaves your wallet until the owner
acts; requests expire after 7 days.</span></li>
<li><b>Owner approving.</b>
<span>Dashboard → the TLD → <b>Pending approvals</b>. Approve signs the certificate
input and broadcasts; Decline removes the request. The wallet refuses to sign any
request that would not return the certificate to you.</span></li>
</ol>
<div class="note"><b>Why not a covenant?</b> A covenant-gated mint is the mainnet plan for
fee enforcement; the co-sign rule needs no new script, works today with plain P2PKH
certificates, and gives the owner a human veto rather than a formula.</div>
</section>
<section id="market">
<h2>Buying &amp; selling names</h2>
<p class="lede">Any name can be sold to anyone, in <b>one transaction, with no escrow</b>.
The seller is paid exactly when the certificate moves — or not at all.</p>
<ol class="steps">
<li><b>Seller lists.</b>
<span>Dashboard → the name → <b>Sell</b>, set a price. Your wallet signs a partial
transaction — your certificate as input 0, the price to you as output 0 — with
<code>SIGHASH_SINGLE | ANYONECANPAY</code>. That signature says "whoever completes this
pays me this much"; it constrains nothing else. The gateway stores it and shows it on
the <a href="../market.html">market</a> after checking the signature, the on-chain
owner and that the certificate is still unspent.</span></li>
<li><b>Buyer completes.</b>
<span>Verify the offer locally, add your coins, add the certificate output to your own
token address plus a registry update so every resolver learns the new owner, sign your
inputs, broadcast. The seller's signature is already in place.</span></li>
<li><b>Seller cancels.</b>
<span>Cancelling removes the offer from the market and moves the certificate once (a
no-op update, a few cents), so the signed offer can never be completed afterwards.</span></li>
</ol>
<div class="note"><b>Trust model.</b> The gateway is a bulletin board. A forged or stale
listing fails the buyer's local check or the broadcast; a buyer can never pay without
receiving the certificate in the same transaction, and a seller can never lose the
certificate without being paid. Endpoints: <code>GET /api/market</code>,
<code>GET /api/market/&lt;name&gt;</code>, <code>POST /api/market</code> (a signed listing),
<code>DELETE /api/market/&lt;name&gt;</code> (owner-signed
<code>BNS-MARKET1
&lt;name&gt;
&lt;ts&gt;</code>).</div>
</section>
<section id="records">
<h2>Records &amp; hosting</h2>
<p class="lede">A registered name carries a small JSON records object. Every record is