ORDnet-SNS-client

Zero-dependency JavaScript client for resolving on-chain web3 names (alex.web3, info@earthlog.web3) against any conformant SNS resolver — with signed answers you can verify, and outpoints you can prove against the chain itself.

Implements ODNCA-STD-001 (SNS Resolution Specification). Runs on Node ≥ 18 and in every modern browser. No packages, no build step: one ESM file plus a crypto adapter.

Quick start

import { resolve, verifyAnswer, proveLive } from './sns-client.js'
import { nodeCrypto } from './adapters/node.js'

const answer = await resolve('info@earthlog.web3')
if (!answer.ok) throw new Error(answer.error)          // machine codes per STD-001 §8

// Level 2 — verify the signature against the pinned resolver key
// (pin on first use; GET <resolver>/pubkey is the live authority)
const verdict = verifyAnswer(answer, nodeCrypto, {
  resolverPubKey: PINNED_KEY,
  expectName: 'info@earthlog.web3'   // bind the answer to what you asked (required since 1.1.0)
})
if (!verdict.valid) throw new Error(verdict.reason)

// Level 3 — prove it live: current.txid:vout unspent at any node you trust
await proveLive(answer, mySpentSource)

pay(answer.holder_script)                              // the script IS the identity

The three verification levels are graded (STD-001 §9): trust the JSON, verify the signature, or prove the outpoint — each a strict superset of the previous, and skipping a level is always the client's choice, never the protocol's requirement.

API

Function	Purpose
parseAddress(raw)	Normalize any input (sns: scheme, @-forms, case rules) into a canonical address, or null
resolve(address, { resolverUrl })	One GET to a conformant resolver (default sns.ordnet.io)
signedPreimage(answer) / sighashOf(answer, crypto)	The exact STD-001 §7 signed bytes — exported for conformance testing
verifyAnswer(answer, crypto, { resolverPubKey, expectName })	Level-2 verification: binds the answer to the asked name (required), then expiry + ECDSA against the pinned key
proveLive(answer, spentSource)	Level-3 helper over any unspent-checker

The crypto adapter is two functions (sha256, ecdsaVerifyDer). The bundled Node adapter uses node:crypto plus a ~90-line pure-JS secp256k1 digest verifier (verification only — signing stays in your wallet library). In the browser, plug in @bsv/sdk, noble-secp256k1, or reuse the bundled verifier with a WebCrypto sha256.

Conformance

node test/run-tests.js

48 tests on bare Node, including the frozen STD-001 §7.1 conformance vector reproduced bit-exact:

sighash 28a4252e92fdcdb70d6fd287cdb602cda504d288963e106b47a6d8d19420ec6b

If your own implementation reproduces that sighash from the vector in test/run-tests.js, your serialization is correct — that is the entire certification.

Related

• ODNCA-standards — the full specification set
• ORDnet-web3names — the TypeScript browser module (address-bar classification, content loading)
• ODNCA-verify — offline ownership-certificate verification

License

MIT © ORDnet / ODNCA