@inversealtruism/cairn-sdk 0.6.0 → 0.8.0

package/README.md

@@ -8,7 +8,6 @@ The **Compute Substrate dApp kit:** one cohesive toolkit for building apps on CS
 | `cairn.chain` | Node RPC + transaction builders + a verifying **light client** (re-exports the `csd-*` primitives). |
 | `cairn.index` | The L2 **explorer/indexer**: REST + merkle proofs + live SSE/WS feeds. |
 | `cairn.content` | **Self-certifying content:** hash for an on-chain Propose, fetch with client-side verification. |
-| `cairn.registry` | L3 **peer / gateway / identity** resolution. |
 | `cairn.names` | **.csd names + CairnX reads:** name resolution, reverse/primary lookup, tokens, offers, bids, canonical state. |
 
 ```bash
@@ -40,8 +39,8 @@ cairn.index.streamAll({ onBlock: (e) => console.log("new block", e) });
 
 The SDK follows the exact model MetaMask uses, there is **no allowlist you maintain**:
 
-- **`connect()` / `getAddress()`** grant *address visibility*. The first time a site connects, the user approves once; after that the wallet answers silently (the site shows up under **Settings → Connected sites**, revocable anytime). This is the only "silent" call.
-- **Every signing / fund-moving call:** `send`, `propose`, `attest`, `signIn`, `sealClaim`, `revealClaim`, **always** opens the wallet's clear-signing approval window, **every time**, no matter what. Being "connected" never pre-approves a signature. A connected site cannot move a satoshi without an explicit, fully-disclosed approval click.
+- **`connect()` / `getAddress()`** grant *address visibility*. The first time a site connects, the user approves once; after that the wallet answers silently (the site shows up under **Settings → Connected sites**, revocable anytime). These are the only calls that can return the address without a prompt. `getPermissions()` (read this site's own grant) and `revokePermissions()` (drop it) are silent too; neither signs anything.
+- **Every signing / fund-moving call:** `send`, `propose`, `attest`, `fillOffer`, `sealClaim`, `revealClaim` and `signInWithCsd`, **always** opens the wallet's clear-signing approval window, **every time**, no matter what. Being "connected" never pre-approves a signature. A connected site cannot move a satoshi without an explicit, fully-disclosed approval click. The legacy `signIn()` is deprecated and first-party-only: the wallet refuses it from any other site with `FIRST_PARTY_ONLY` before prompting; use `signInWithCsd()`.
 
 ```ts
 import { connect, UserRejectedError, NotInstalledError } from "@inversealtruism/cairn-sdk";
@@ -57,29 +56,27 @@ try {
 
 ## API by namespace
 
-**`cairn.index`:** `tipHeight()`, `block()/blockTxids()`, `tx()/txStatus()/txMerkleProof()`, `address()/addressTxs()/addressUtxo()`, `domains()/domainProposals(domain)`, `proposal()/attestations()`, `reputation()`, `registryPeers()/registryGateways()/identity()`, **`verifyInclusion(txid)`** (trust-minimized), `streamAll()/streamBlocks()/streamDomain()` (SSE), `subscribe()` (WS).
+**`cairn.index`:** `tipHeight()`, `block()/blockTxids()`, `tx()/txStatus()/txMerkleProof()`, `address()/addressTxs()/addressUtxo()`, `domains()/domainProposals(domain)`, `proposal()/attestations()`, `reputation()`, **`verifyInclusion(txid)`** (trust-minimized), `streamAll()/streamBlocks()/streamDomain()` (SSE), `subscribe()` (WS).
 
-**`cairn.names`:** `resolve(name)` (display-path name to address), `name(name)`/`nameHistory(name)`, `primary(addr)` (reverse lookup)/`namesOf(addr)`, `names()`, `tokens()/token(ticker)`, `offers()`, `bids()`, `state()` (the canonical CairnX state). Reads go through the public `/trade/api/cairnx/*` proxy; for payment-grade name resolution verify through the wallet or a replaying resolver, not a bare read (see `src/names.ts` header).
+**`cairn.names`:** `resolve(name)` (display-path name to address), `name(name)`/`nameHistory(name)`, `primary(addr)` (reverse lookup)/`namesOf(addr)`, `names()`, `tokens()/token(ticker)`, `offers()`/`bids()` (open rows by default; pass `{ status }` for another status, or `{ status: "all" }` for every row), `state()` (the canonical CairnX state). Reads go through the public `/trade/api/cairnx/*` proxy; for payment-grade name resolution verify through the wallet or a replaying resolver, not a bare read (see `src/names.ts` header).
 
 **`cairn.content`:** `prepare(obj)`/`put(obj)` → `{ payloadHash, canonical, bytes }`; `get(hash)` / `getBytes(hash)` (fetch **and verify** `sha256(bytes) === hash`, throws `ContentVerificationError` on tamper); `hash(obj)`.
 
 **`cairn.chain`:** `tip()`, `utxos(addr)`, `submit(nodeJsonTx)`, `.client` (full `CsdClient`), `.light()` (verifying light client). The package also re-exports the primitives under the `/chain` subpath: `buildSend/buildPropose/buildAttest`, `signTx`, `keygen`, `payloadHash`, `verifyMerkleProof`, `LightClient`, etc.
 
-**`cairn.registry`:** `gateways()`, `peers()`, `resolveName(handle)`, `reverseName(addr)`, `.fromRecords` (deterministic local resolvers).
-
-Subpath imports are available for tree-shaking: `@inversealtruism/cairn-sdk/{connect,indexer,content,registry,chain,controller,react}`.
+Subpath imports are available for tree-shaking: `@inversealtruism/cairn-sdk/{connect,indexer,content,chain,controller,react}`.
 
 ## Examples
 
-- **`examples/read-only.mjs`:** runs today against live mainnet, no wallet, no build: `npm run test:live`. Demonstrates chain/indexer/registry reads + verified merkle inclusion + verified content fetch.
-- **`examples/hello-csd/`:** a no-framework browser dApp (connect → read recent proposals → live feed). Build the bundle with `npm run build:example`, then serve the folder from **localhost** (the wallet injects there) with the Cairn Wallet installed.
+- **`examples/read-only.mjs`:** runs against live mainnet with no wallet. It imports the built `dist/`, so run `pnpm build` first, then `pnpm test:live`. Demonstrates chain/indexer reads + verified merkle inclusion + verified content fetch.
+- **`examples/hello-csd/`:** a no-framework browser dApp (connect → read recent proposals → live feed). Build the bundle with `pnpm build:example`, then serve the folder from **localhost** (the wallet injects there) with the Cairn Wallet installed.
 
 ## Trust model & honest limits
 
-- **Content is always verified client-side.** `cairn.content.get()` rejects bytes that don't hash to the requested `payloadHash`, an untrusted gateway can't serve tampered content.
-- **Merkle inclusion is trust-minimized, to the strength of your header source.** `verifyInclusion()` folds the proof and cross-checks its root against a header merkle from `headerMerkleAt`. The default `Cairn` wiring backs that with a light client that PoW-verifies headers forward from a pinned checkpoint, so a match reads `trustLevel: "verified-inclusion"` with `included: true`. A header within 12 blocks of the light client's cached tip is first compared with the header the base serves at that height, so a block orphaned by a reorg stops counting; the hosted base edge-caches rows at or below its tip minus 6, so there this catches reorgs of up to 6 blocks. When no header can be verified (below the checkpoint, header source unreachable, no source configured) the result is `"proof-consistent"` with `included: false` and a `reason`: the indexer alone vouches for it. Gate on `included` or on `trustLevel === "verified-inclusion"`; they agree.
-- **Balances are RPC-trusted.** Headers don't commit to the UTXO set; balance reads trust the node/proxy (same as every light client).
-- **Indexer/swarm run behind the cairn proxy.** By default `cairn.index` and content resolution use the cairn server's hardened, read-only, rate-limited `/explorer/api` reverse proxy (no separate public indexer needed). **SSE works through it; `subscribe()` (WebSocket) needs a direct indexer endpoint:** set `baseUrls.indexer` to a private/localhost indexer for WS.
+Content bytes are always verified client-side; merkle inclusion is verified when a PoW-verified header backs it (`trustLevel: "verified-inclusion"`); balances are RPC-trusted. The full trust model (each `trustLevel`, the checkpoint, reorgs near the tip) is in [`docs/SDK-GUIDE.md`](docs/SDK-GUIDE.md#what-the-sdk-verifies-vs-trusts-read-this).
+
+- **Content comes from the cairn origin.** `cairn.content` reads `/content/<hash>` on the cairn base and verifies every byte against the hash.
+- **The indexer runs behind the cairn proxy.** By default `cairn.index` uses the cairn server's hardened, read-only, rate-limited `/explorer/api` reverse proxy (no separate public indexer needed). **SSE works through that proxy; `subscribe()` (WebSocket) needs a direct indexer endpoint:** set `baseUrls.indexer` to a private/localhost indexer for WS.
 - **The wallet injects on every site** (connect-anywhere shipped in 0.2.4x) behind a per-origin consent gate: a site sees nothing until the user approves the connection, and some request kinds stay first-party-only (the `FIRST_PARTY_ONLY` error code).
 
 ## Configuration
@@ -91,7 +88,6 @@ new Cairn({
     cairn:   "https://cairn-substrate.com",        // /api/rpc proxy + /api/headers + /content origin + names
     rpc:     "https://cairn-substrate.com/api/rpc", // node RPC (proxy)
     indexer: "https://cairn-substrate.com/explorer/api",
-    swarm:   undefined,                             // optional direct swarm gateway
   },
   fetch,            // custom fetch (Node <18, tests)
   timeoutMs: 15000,
@@ -103,8 +99,8 @@ new Cairn({
 
 ```bash
 pnpm build && pnpm test         # unit (offline): error mapping, client paths, content+merkle verify
-pnpm test:e2e:read              # live reads vs mainnet + adversarial (free)
-pnpm test:e2e:wallet            # real extension + real connector under Xvfb: connect/consent/sign (free)
+pnpm test:live                  # examples/read-only.mjs + live reads vs mainnet + adversarial (free)
+pnpm test:live:wallet           # real extension + real connector under Xvfb: connect/consent/sign (free)
 ```
 
 See [`test/e2e/README.md`](test/e2e/README.md) for coverage, requirements, and cost of each layer. All three suites are free; none spends CSD.

package/dist/{chunk-K5MGEYEU.js → chunk-CI7YODPP.js}

@@ -69,18 +69,6 @@ var IndexerClient = class {
   attestations(id) {
     return this.http.getJson(`/proposal/${encodeURIComponent(id)}/attestations`);
   }
-  registryPeers() {
-    return this.http.getJson("/registry/peers");
-  }
-  registryGateways() {
-    return this.http.getJson("/registry/gateways");
-  }
-  identity(handle) {
-    return this.http.getJson(`/identity/${encodeURIComponent(handle)}`);
-  }
-  reverseIdentity(addr) {
-    return this.http.getJson(`/address/${encodeURIComponent(addr)}/identity`);
-  }
   // ---- trust-minimized inclusion ----------------------------------------
   /**
    * Verify a tx is included in a block by folding its merkle branch to the root

package/dist/{chunk-QEYBWBXC.js → chunk-DTPADO7N.js}

@@ -1,17 +1,17 @@
 import {
   CairnError,
   ContentVerificationError
-} from "./chunk-2A4AJBO5.js";
+} from "./chunk-UAPWZZQK.js";
 
 // src/content.ts
 import { payloadHash, canonicalJson, verifyContentBytes } from "@inversealtruism/csd-codec";
 var ContentClient = class {
-  sources;
+  cairn;
   constructor(opts) {
-    this.sources = [];
-    if (opts.swarm) this.sources.push({ name: "swarm", http: opts.swarm, path: (h) => `/content/${h}` });
-    if (opts.indexer) this.sources.push({ name: "indexer", http: opts.indexer, path: (h) => `/content/${h}` });
-    if (opts.cairn) this.sources.push({ name: "cairn", http: opts.cairn, path: (h) => `/content/${h}` });
+    if (!opts?.cairn || typeof opts.cairn.getBytes !== "function") {
+      throw new TypeError("ContentClient needs a `cairn` Http client (the swarm and indexer sources were removed in 0.7.0)");
+    }
+    this.cairn = opts.cairn;
   }
   /**
    * Compute the canonical hash + bytes for an object, ready to anchor on-chain.
@@ -35,31 +35,21 @@ var ContentClient = class {
   }
   /**
    * Fetch content by hash and VERIFY it self-certifies (sha256(bytes) == hash).
-   * Tries each configured source in order; a source that is unreachable, lacks
-   * the content or serves bytes that don't match the hash is skipped. Returns the
-   * first verified bytes, or null if no source holds it. Throws
-   * ContentVerificationError only when no source served verified bytes and at
-   * least one served mismatching bytes (tampering / wrong object).
+   * Returns the verified bytes, or null when the origin does not hold the content
+   * or cannot be reached (as 0.6.0 did when every source failed). Throws
+   * ContentVerificationError when the origin serves bytes that don't match the hash.
    */
   async getBytes(hash) {
     const h = normalizeHash(hash);
-    let mismatched = false;
-    for (const src of this.sources) {
-      let got = null;
-      try {
-        got = await src.http.getBytes(src.path(h));
-      } catch {
-        continue;
-      }
-      if (!got) continue;
-      if (!verifyContentBytes(got.bytes, h)) {
-        mismatched = true;
-        continue;
-      }
-      return got.bytes;
+    let got = null;
+    try {
+      got = await this.cairn.getBytes(`/content/${h}`);
+    } catch {
+      return null;
     }
-    if (mismatched) throw new ContentVerificationError(h);
-    return null;
+    if (!got) return null;
+    if (!verifyContentBytes(got.bytes, h)) throw new ContentVerificationError(h);
+    return got.bytes;
   }
   /** Fetch + verify + parse as UTF-8 JSON. Returns null if not found. Throws a CairnError with code
    *  CONTENT_NOT_JSON when the verified bytes are not JSON. */

package/dist/{chunk-MLNW2RQB.js → chunk-JXBO4LV6.js}

@@ -1,6 +1,6 @@
 import {
   getWallet
-} from "./chunk-BMH2MACB.js";
+} from "./chunk-WWO3FXHG.js";
 
 // src/controller.ts
 var DISCONNECTED = Object.freeze({ status: "disconnected", account: null, error: null });

package/dist/{chunk-2A4AJBO5.js → chunk-UAPWZZQK.js}

@@ -1,5 +1,5 @@
 // src/errors.ts
-var SDK_VERSION = "0.6.0";
+var SDK_VERSION = "0.8.0";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */

package/dist/{chunk-BMH2MACB.js → chunk-WWO3FXHG.js}

@@ -4,7 +4,7 @@ import {
   UnsupportedMethodError,
   mapProviderError,
   mapSubmitResultError
-} from "./chunk-2A4AJBO5.js";
+} from "./chunk-UAPWZZQK.js";
 
 // src/connect.ts
 var DEFAULT_PROVIDER_TIMEOUT_MS = 10 * 6e4;

package/dist/connect.cjs

@@ -30,7 +30,7 @@ __export(connect_exports, {
 module.exports = __toCommonJS(connect_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.6.0";
+var SDK_VERSION = "0.8.0";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */

package/dist/connect.js

@@ -5,8 +5,8 @@ import {
   discoverProviders,
   getWallet,
   isInstalled
-} from "./chunk-BMH2MACB.js";
-import "./chunk-2A4AJBO5.js";
+} from "./chunk-WWO3FXHG.js";
+import "./chunk-UAPWZZQK.js";
 export {
   WalletConnection,
   connect,

package/dist/content.cjs

@@ -26,7 +26,7 @@ module.exports = __toCommonJS(content_exports);
 var import_csd_codec = require("@inversealtruism/csd-codec");
 
 // src/errors.ts
-var SDK_VERSION = "0.6.0";
+var SDK_VERSION = "0.8.0";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -80,12 +80,12 @@ var ContentVerificationError = class extends CairnError {
 
 // src/content.ts
 var ContentClient = class {
-  sources;
+  cairn;
   constructor(opts) {
-    this.sources = [];
-    if (opts.swarm) this.sources.push({ name: "swarm", http: opts.swarm, path: (h) => `/content/${h}` });
-    if (opts.indexer) this.sources.push({ name: "indexer", http: opts.indexer, path: (h) => `/content/${h}` });
-    if (opts.cairn) this.sources.push({ name: "cairn", http: opts.cairn, path: (h) => `/content/${h}` });
+    if (!opts?.cairn || typeof opts.cairn.getBytes !== "function") {
+      throw new TypeError("ContentClient needs a `cairn` Http client (the swarm and indexer sources were removed in 0.7.0)");
+    }
+    this.cairn = opts.cairn;
   }
   /**
    * Compute the canonical hash + bytes for an object, ready to anchor on-chain.
@@ -109,31 +109,21 @@ var ContentClient = class {
   }
   /**
    * Fetch content by hash and VERIFY it self-certifies (sha256(bytes) == hash).
-   * Tries each configured source in order; a source that is unreachable, lacks
-   * the content or serves bytes that don't match the hash is skipped. Returns the
-   * first verified bytes, or null if no source holds it. Throws
-   * ContentVerificationError only when no source served verified bytes and at
-   * least one served mismatching bytes (tampering / wrong object).
+   * Returns the verified bytes, or null when the origin does not hold the content
+   * or cannot be reached (as 0.6.0 did when every source failed). Throws
+   * ContentVerificationError when the origin serves bytes that don't match the hash.
    */
   async getBytes(hash) {
     const h = normalizeHash(hash);
-    let mismatched = false;
-    for (const src of this.sources) {
-      let got = null;
-      try {
-        got = await src.http.getBytes(src.path(h));
-      } catch {
-        continue;
-      }
-      if (!got) continue;
-      if (!(0, import_csd_codec.verifyContentBytes)(got.bytes, h)) {
-        mismatched = true;
-        continue;
-      }
-      return got.bytes;
+    let got = null;
+    try {
+      got = await this.cairn.getBytes(`/content/${h}`);
+    } catch {
+      return null;
     }
-    if (mismatched) throw new ContentVerificationError(h);
-    return null;
+    if (!got) return null;
+    if (!(0, import_csd_codec.verifyContentBytes)(got.bytes, h)) throw new ContentVerificationError(h);
+    return got.bytes;
   }
   /** Fetch + verify + parse as UTF-8 JSON. Returns null if not found. Throws a CairnError with code
    *  CONTENT_NOT_JSON when the verified bytes are not JSON. */

package/dist/content.d.cts

@@ -1,23 +1,19 @@
 import { H as Http } from './http-C9C4L4hz.cjs';
 
 interface ContentClientOptions {
-    /** Swarm gateway HTTP client (e.g. https://cairn-substrate.com/swarm). */
-    swarm?: Http;
-    /** Cairn origin HTTP client (serves /content as origin + fallback). */
-    cairn?: Http;
-    /** Indexer HTTP client (also joins the swarm gateway at /content). */
-    indexer?: Http;
+    /** Cairn origin HTTP client; it serves `/content/<hash>`. */
+    cairn: Http;
 }
 interface PreparedContent {
     /** The 0x-prefixed sha256 payload hash that goes on-chain. */
     payloadHash: string;
     /** The exact canonical JSON string that was hashed. */
     canonical: string;
-    /** UTF-8 bytes of the canonical JSON (what the swarm stores / serves). */
+    /** UTF-8 bytes of the canonical JSON (what the origin stores and serves). */
     bytes: Uint8Array;
 }
 declare class ContentClient {
-    private readonly sources;
+    private readonly cairn;
     constructor(opts: ContentClientOptions);
     /**
      * Compute the canonical hash + bytes for an object, ready to anchor on-chain.
@@ -30,11 +26,9 @@ declare class ContentClient {
     hash(obj: unknown): string;
     /**
      * Fetch content by hash and VERIFY it self-certifies (sha256(bytes) == hash).
-     * Tries each configured source in order; a source that is unreachable, lacks
-     * the content or serves bytes that don't match the hash is skipped. Returns the
-     * first verified bytes, or null if no source holds it. Throws
-     * ContentVerificationError only when no source served verified bytes and at
-     * least one served mismatching bytes (tampering / wrong object).
+     * Returns the verified bytes, or null when the origin does not hold the content
+     * or cannot be reached (as 0.6.0 did when every source failed). Throws
+     * ContentVerificationError when the origin serves bytes that don't match the hash.
      */
     getBytes(hash: string): Promise<Uint8Array | null>;
     /** Fetch + verify + parse as UTF-8 JSON. Returns null if not found. Throws a CairnError with code

package/dist/content.d.ts

@@ -1,23 +1,19 @@
 import { H as Http } from './http-C9C4L4hz.js';
 
 interface ContentClientOptions {
-    /** Swarm gateway HTTP client (e.g. https://cairn-substrate.com/swarm). */
-    swarm?: Http;
-    /** Cairn origin HTTP client (serves /content as origin + fallback). */
-    cairn?: Http;
-    /** Indexer HTTP client (also joins the swarm gateway at /content). */
-    indexer?: Http;
+    /** Cairn origin HTTP client; it serves `/content/<hash>`. */
+    cairn: Http;
 }
 interface PreparedContent {
     /** The 0x-prefixed sha256 payload hash that goes on-chain. */
     payloadHash: string;
     /** The exact canonical JSON string that was hashed. */
     canonical: string;
-    /** UTF-8 bytes of the canonical JSON (what the swarm stores / serves). */
+    /** UTF-8 bytes of the canonical JSON (what the origin stores and serves). */
     bytes: Uint8Array;
 }
 declare class ContentClient {
-    private readonly sources;
+    private readonly cairn;
     constructor(opts: ContentClientOptions);
     /**
      * Compute the canonical hash + bytes for an object, ready to anchor on-chain.
@@ -30,11 +26,9 @@ declare class ContentClient {
     hash(obj: unknown): string;
     /**
      * Fetch content by hash and VERIFY it self-certifies (sha256(bytes) == hash).
-     * Tries each configured source in order; a source that is unreachable, lacks
-     * the content or serves bytes that don't match the hash is skipped. Returns the
-     * first verified bytes, or null if no source holds it. Throws
-     * ContentVerificationError only when no source served verified bytes and at
-     * least one served mismatching bytes (tampering / wrong object).
+     * Returns the verified bytes, or null when the origin does not hold the content
+     * or cannot be reached (as 0.6.0 did when every source failed). Throws
+     * ContentVerificationError when the origin serves bytes that don't match the hash.
      */
     getBytes(hash: string): Promise<Uint8Array | null>;
     /** Fetch + verify + parse as UTF-8 JSON. Returns null if not found. Throws a CairnError with code

package/dist/content.js

@@ -1,7 +1,7 @@
 import {
   ContentClient
-} from "./chunk-QEYBWBXC.js";
-import "./chunk-2A4AJBO5.js";
+} from "./chunk-DTPADO7N.js";
+import "./chunk-UAPWZZQK.js";
 export {
   ContentClient
 };

package/dist/controller.cjs

@@ -25,7 +25,7 @@ __export(controller_exports, {
 module.exports = __toCommonJS(controller_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.6.0";
+var SDK_VERSION = "0.8.0";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */

package/dist/controller.js

@@ -1,8 +1,8 @@
 import {
   CairnController
-} from "./chunk-MLNW2RQB.js";
-import "./chunk-BMH2MACB.js";
-import "./chunk-2A4AJBO5.js";
+} from "./chunk-JXBO4LV6.js";
+import "./chunk-WWO3FXHG.js";
+import "./chunk-UAPWZZQK.js";
 export {
   CairnController
 };