@inversealtruism/cairn-sdk 0.1.0

package/dist/indexer.d.cts

@@ -0,0 +1,103 @@
+import { H as Http, F as FetchLike } from './http-D2CzfOsm.cjs';
+
+interface MerkleProof {
+    block_height: number;
+    pos: number;
+    merkle: string[];
+    merkle_root: string;
+}
+type TrustLevel = "verified-inclusion" | "proof-consistent" | "not-found";
+interface InclusionResult {
+    included: boolean;
+    trustLevel: TrustLevel;
+    blockHeight?: number;
+    pos?: number;
+    merkleRoot?: string;
+    reason?: string;
+}
+/** A live index event ({ kind: "block" | "proposal" | "attestation" | "reorg", ... }). */
+interface IndexEvent {
+    kind: "block" | "proposal" | "attestation" | "reorg";
+    [k: string]: unknown;
+}
+interface IndexerClientOptions {
+    fetch?: FetchLike;
+    /** A WebSocket implementation (defaults to globalThis.WebSocket). */
+    WebSocketImpl?: typeof WebSocket;
+    /**
+     * Optional: given a block height, return its on-chain header merkle root. Wire
+     * this from the chain/light client to upgrade verifyInclusion() from
+     * "proof-consistent" to fully trust-minimized "verified-inclusion".
+     */
+    headerMerkleAt?: (height: number) => Promise<string>;
+}
+declare class IndexerClient {
+    private readonly http;
+    private readonly opts;
+    constructor(http: Http, opts?: IndexerClientOptions);
+    health(): Promise<unknown>;
+    tipHeight(): Promise<number>;
+    tipHash(): Promise<string>;
+    blockHashAtHeight(h: number): Promise<string>;
+    block(hash: string): Promise<unknown>;
+    blockTxids(hash: string): Promise<string[]>;
+    tx(id: string): Promise<unknown>;
+    txStatus(id: string): Promise<{
+        confirmed: boolean;
+        block_height: number;
+        confirmations: number;
+        final: boolean;
+    }>;
+    txMerkleProof(id: string): Promise<MerkleProof>;
+    address(a: string): Promise<unknown>;
+    addressTxs(a: string): Promise<unknown[]>;
+    addressUtxo(a: string): Promise<unknown[]>;
+    reputation(a: string): Promise<unknown>;
+    domains(): Promise<unknown[]>;
+    domainProposals(d: string): Promise<unknown[]>;
+    proposal(id: string): Promise<unknown>;
+    attestations(id: string): Promise<unknown[]>;
+    registryPeers(): Promise<unknown[]>;
+    registryGateways(): Promise<unknown[]>;
+    identity(handle: string): Promise<unknown>;
+    reverseIdentity(addr: string): Promise<unknown>;
+    /**
+     * Verify a tx is included in a block by folding its merkle branch to the root
+     * with csd-codec.verifyMerkleProof. If `headerMerkleAt` was provided, the
+     * proof's root is cross-checked against the ON-CHAIN header merkle at that
+     * height → trustLevel "verified-inclusion". Otherwise the proof is only
+     * internally consistent → "proof-consistent" (still useful, but the indexer is trusted).
+     */
+    verifyInclusion(txid: string): Promise<InclusionResult>;
+    /** Stream all events (blocks, proposals, attestations, reorgs) via SSE. */
+    streamAll(handlers: StreamHandlers): StreamHandle;
+    /** Stream blocks + reorgs only. */
+    streamBlocks(handlers: StreamHandlers): StreamHandle;
+    /** Stream proposals (+ reorgs) for a domain. */
+    streamDomain(domain: string, handlers: StreamHandlers): StreamHandle;
+    /**
+     * Subscribe over WebSocket with selective tracking. Returns a handle with
+     * `.close()`. `onEvent` receives every matching IndexEvent (incl. reorgs).
+     */
+    subscribe(sub: {
+        all?: boolean;
+        domains?: string[];
+        addresses?: string[];
+        proposals?: string[];
+    }, onEvent: (e: IndexEvent) => void, onError?: (err: unknown) => void): StreamHandle;
+    private sse;
+}
+interface StreamHandlers {
+    onEvent?: (e: IndexEvent) => void;
+    onBlock?: (e: IndexEvent) => void;
+    onProposal?: (e: IndexEvent) => void;
+    onAttestation?: (e: IndexEvent) => void;
+    onReorg?: (e: IndexEvent) => void;
+    onOpen?: () => void;
+    onError?: (err: unknown) => void;
+}
+interface StreamHandle {
+    close(): void;
+}
+
+export { type InclusionResult, type IndexEvent, IndexerClient, type IndexerClientOptions, type MerkleProof, type StreamHandle, type StreamHandlers, type TrustLevel };

package/dist/indexer.d.ts

@@ -0,0 +1,103 @@
+import { H as Http, F as FetchLike } from './http-D2CzfOsm.js';
+
+interface MerkleProof {
+    block_height: number;
+    pos: number;
+    merkle: string[];
+    merkle_root: string;
+}
+type TrustLevel = "verified-inclusion" | "proof-consistent" | "not-found";
+interface InclusionResult {
+    included: boolean;
+    trustLevel: TrustLevel;
+    blockHeight?: number;
+    pos?: number;
+    merkleRoot?: string;
+    reason?: string;
+}
+/** A live index event ({ kind: "block" | "proposal" | "attestation" | "reorg", ... }). */
+interface IndexEvent {
+    kind: "block" | "proposal" | "attestation" | "reorg";
+    [k: string]: unknown;
+}
+interface IndexerClientOptions {
+    fetch?: FetchLike;
+    /** A WebSocket implementation (defaults to globalThis.WebSocket). */
+    WebSocketImpl?: typeof WebSocket;
+    /**
+     * Optional: given a block height, return its on-chain header merkle root. Wire
+     * this from the chain/light client to upgrade verifyInclusion() from
+     * "proof-consistent" to fully trust-minimized "verified-inclusion".
+     */
+    headerMerkleAt?: (height: number) => Promise<string>;
+}
+declare class IndexerClient {
+    private readonly http;
+    private readonly opts;
+    constructor(http: Http, opts?: IndexerClientOptions);
+    health(): Promise<unknown>;
+    tipHeight(): Promise<number>;
+    tipHash(): Promise<string>;
+    blockHashAtHeight(h: number): Promise<string>;
+    block(hash: string): Promise<unknown>;
+    blockTxids(hash: string): Promise<string[]>;
+    tx(id: string): Promise<unknown>;
+    txStatus(id: string): Promise<{
+        confirmed: boolean;
+        block_height: number;
+        confirmations: number;
+        final: boolean;
+    }>;
+    txMerkleProof(id: string): Promise<MerkleProof>;
+    address(a: string): Promise<unknown>;
+    addressTxs(a: string): Promise<unknown[]>;
+    addressUtxo(a: string): Promise<unknown[]>;
+    reputation(a: string): Promise<unknown>;
+    domains(): Promise<unknown[]>;
+    domainProposals(d: string): Promise<unknown[]>;
+    proposal(id: string): Promise<unknown>;
+    attestations(id: string): Promise<unknown[]>;
+    registryPeers(): Promise<unknown[]>;
+    registryGateways(): Promise<unknown[]>;
+    identity(handle: string): Promise<unknown>;
+    reverseIdentity(addr: string): Promise<unknown>;
+    /**
+     * Verify a tx is included in a block by folding its merkle branch to the root
+     * with csd-codec.verifyMerkleProof. If `headerMerkleAt` was provided, the
+     * proof's root is cross-checked against the ON-CHAIN header merkle at that
+     * height → trustLevel "verified-inclusion". Otherwise the proof is only
+     * internally consistent → "proof-consistent" (still useful, but the indexer is trusted).
+     */
+    verifyInclusion(txid: string): Promise<InclusionResult>;
+    /** Stream all events (blocks, proposals, attestations, reorgs) via SSE. */
+    streamAll(handlers: StreamHandlers): StreamHandle;
+    /** Stream blocks + reorgs only. */
+    streamBlocks(handlers: StreamHandlers): StreamHandle;
+    /** Stream proposals (+ reorgs) for a domain. */
+    streamDomain(domain: string, handlers: StreamHandlers): StreamHandle;
+    /**
+     * Subscribe over WebSocket with selective tracking. Returns a handle with
+     * `.close()`. `onEvent` receives every matching IndexEvent (incl. reorgs).
+     */
+    subscribe(sub: {
+        all?: boolean;
+        domains?: string[];
+        addresses?: string[];
+        proposals?: string[];
+    }, onEvent: (e: IndexEvent) => void, onError?: (err: unknown) => void): StreamHandle;
+    private sse;
+}
+interface StreamHandlers {
+    onEvent?: (e: IndexEvent) => void;
+    onBlock?: (e: IndexEvent) => void;
+    onProposal?: (e: IndexEvent) => void;
+    onAttestation?: (e: IndexEvent) => void;
+    onReorg?: (e: IndexEvent) => void;
+    onOpen?: () => void;
+    onError?: (err: unknown) => void;
+}
+interface StreamHandle {
+    close(): void;
+}
+
+export { type InclusionResult, type IndexEvent, IndexerClient, type IndexerClientOptions, type MerkleProof, type StreamHandle, type StreamHandlers, type TrustLevel };

package/dist/indexer.js

@@ -0,0 +1,6 @@
+import {
+  IndexerClient
+} from "./chunk-ETZYBDFC.js";
+export {
+  IndexerClient
+};

package/dist/registry.cjs

@@ -0,0 +1,77 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/registry.ts
+var registry_exports = {};
+__export(registry_exports, {
+  DOMAINS: () => import_csd_registry2.DOMAINS,
+  RegistryClient: () => RegistryClient,
+  buildGatewayRecord: () => import_csd_registry2.buildGatewayRecord,
+  buildIdentityCommit: () => import_csd_registry2.buildIdentityCommit,
+  buildIdentityReveal: () => import_csd_registry2.buildIdentityReveal,
+  buildPeerRecord: () => import_csd_registry2.buildPeerRecord,
+  epochOf: () => import_csd_registry2.epochOf,
+  fromRecords: () => import_csd_registry2.fromRecords,
+  verifyGateway: () => import_csd_registry2.verifyGateway,
+  verifyIdentitySig: () => import_csd_registry2.verifyIdentitySig,
+  verifyPeer: () => import_csd_registry2.verifyPeer
+});
+module.exports = __toCommonJS(registry_exports);
+var import_csd_registry = require("@inversealtruism/csd-registry");
+var import_csd_registry2 = require("@inversealtruism/csd-registry");
+var RegistryClient = class {
+  src;
+  constructor(opts) {
+    this.src = { baseUrl: opts.baseUrl.replace(/\/+$/, ""), fetch: opts.fetch };
+  }
+  /** Discover ranked content/pin gateways (GET /registry/gateways). */
+  gateways() {
+    return (0, import_csd_registry.discoverGateways)(this.src);
+  }
+  /** Discover ranked libp2p peers (GET /registry/peers). */
+  peers() {
+    return (0, import_csd_registry.discoverPeers)(this.src);
+  }
+  /** Resolve a handle → identity (GET /identity/:handle). Returns null if unresolved. */
+  resolveName(handle) {
+    return (0, import_csd_registry.resolveName)(this.src, handle);
+  }
+  /** Reverse-resolve an address → identity (GET /address/:addr/identity). */
+  reverseName(address) {
+    return (0, import_csd_registry.reverseName)(this.src, address);
+  }
+  /** The deterministic, client-side resolvers (recompute from raw ChainRecord[]). */
+  get fromRecords() {
+    return import_csd_registry.fromRecords;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DOMAINS,
+  RegistryClient,
+  buildGatewayRecord,
+  buildIdentityCommit,
+  buildIdentityReveal,
+  buildPeerRecord,
+  epochOf,
+  fromRecords,
+  verifyGateway,
+  verifyIdentitySig,
+  verifyPeer
+});

package/dist/registry.d.cts

@@ -0,0 +1,30 @@
+import * as _inversealtruism_csd_registry from '@inversealtruism/csd-registry';
+export { BuiltRecord, ChainRecord, DOMAINS, RankedGateway, RankedPeer, ResolveOpts, ResolvedIdentity, buildGatewayRecord, buildIdentityCommit, buildIdentityReveal, buildPeerRecord, epochOf, fromRecords, verifyGateway, verifyIdentitySig, verifyPeer } from '@inversealtruism/csd-registry';
+import { F as FetchLike } from './http-D2CzfOsm.cjs';
+
+interface RegistryClientOptions {
+    /** Indexer base URL exposing /registry/* + /identity/* (e.g. https://cairn-substrate.com/indexer). */
+    baseUrl: string;
+    fetch?: FetchLike;
+}
+declare class RegistryClient {
+    private readonly src;
+    constructor(opts: RegistryClientOptions);
+    /** Discover ranked content/pin gateways (GET /registry/gateways). */
+    gateways(): Promise<_inversealtruism_csd_registry.RankedGateway[]>;
+    /** Discover ranked libp2p peers (GET /registry/peers). */
+    peers(): Promise<_inversealtruism_csd_registry.RankedPeer[]>;
+    /** Resolve a handle → identity (GET /identity/:handle). Returns null if unresolved. */
+    resolveName(handle: string): Promise<_inversealtruism_csd_registry.ResolvedIdentity | null>;
+    /** Reverse-resolve an address → identity (GET /address/:addr/identity). */
+    reverseName(address: string): Promise<_inversealtruism_csd_registry.ResolvedIdentity | null>;
+    /** The deterministic, client-side resolvers (recompute from raw ChainRecord[]). */
+    get fromRecords(): {
+        peers: (records: _inversealtruism_csd_registry.ChainRecord[], opts: _inversealtruism_csd_registry.ResolveOpts) => _inversealtruism_csd_registry.RankedPeer[];
+        gateways: (records: _inversealtruism_csd_registry.ChainRecord[], opts: _inversealtruism_csd_registry.ResolveOpts) => _inversealtruism_csd_registry.RankedGateway[];
+        name: (records: _inversealtruism_csd_registry.ChainRecord[], handle: string, opts: _inversealtruism_csd_registry.ResolveOpts) => _inversealtruism_csd_registry.ResolvedIdentity | null;
+        reverse: (records: _inversealtruism_csd_registry.ChainRecord[], address: string, opts: _inversealtruism_csd_registry.ResolveOpts) => _inversealtruism_csd_registry.ResolvedIdentity | null;
+    };
+}
+
+export { RegistryClient, type RegistryClientOptions };

package/dist/registry.d.ts

@@ -0,0 +1,30 @@
+import * as _inversealtruism_csd_registry from '@inversealtruism/csd-registry';
+export { BuiltRecord, ChainRecord, DOMAINS, RankedGateway, RankedPeer, ResolveOpts, ResolvedIdentity, buildGatewayRecord, buildIdentityCommit, buildIdentityReveal, buildPeerRecord, epochOf, fromRecords, verifyGateway, verifyIdentitySig, verifyPeer } from '@inversealtruism/csd-registry';
+import { F as FetchLike } from './http-D2CzfOsm.js';
+
+interface RegistryClientOptions {
+    /** Indexer base URL exposing /registry/* + /identity/* (e.g. https://cairn-substrate.com/indexer). */
+    baseUrl: string;
+    fetch?: FetchLike;
+}
+declare class RegistryClient {
+    private readonly src;
+    constructor(opts: RegistryClientOptions);
+    /** Discover ranked content/pin gateways (GET /registry/gateways). */
+    gateways(): Promise<_inversealtruism_csd_registry.RankedGateway[]>;
+    /** Discover ranked libp2p peers (GET /registry/peers). */
+    peers(): Promise<_inversealtruism_csd_registry.RankedPeer[]>;
+    /** Resolve a handle → identity (GET /identity/:handle). Returns null if unresolved. */
+    resolveName(handle: string): Promise<_inversealtruism_csd_registry.ResolvedIdentity | null>;
+    /** Reverse-resolve an address → identity (GET /address/:addr/identity). */
+    reverseName(address: string): Promise<_inversealtruism_csd_registry.ResolvedIdentity | null>;
+    /** The deterministic, client-side resolvers (recompute from raw ChainRecord[]). */
+    get fromRecords(): {
+        peers: (records: _inversealtruism_csd_registry.ChainRecord[], opts: _inversealtruism_csd_registry.ResolveOpts) => _inversealtruism_csd_registry.RankedPeer[];
+        gateways: (records: _inversealtruism_csd_registry.ChainRecord[], opts: _inversealtruism_csd_registry.ResolveOpts) => _inversealtruism_csd_registry.RankedGateway[];
+        name: (records: _inversealtruism_csd_registry.ChainRecord[], handle: string, opts: _inversealtruism_csd_registry.ResolveOpts) => _inversealtruism_csd_registry.ResolvedIdentity | null;
+        reverse: (records: _inversealtruism_csd_registry.ChainRecord[], address: string, opts: _inversealtruism_csd_registry.ResolveOpts) => _inversealtruism_csd_registry.ResolvedIdentity | null;
+    };
+}
+
+export { RegistryClient, type RegistryClientOptions };

package/dist/registry.js

@@ -0,0 +1,26 @@
+import {
+  DOMAINS,
+  RegistryClient,
+  buildGatewayRecord,
+  buildIdentityCommit,
+  buildIdentityReveal,
+  buildPeerRecord,
+  epochOf,
+  fromRecords,
+  verifyGateway,
+  verifyIdentitySig,
+  verifyPeer
+} from "./chunk-G7FABIF4.js";
+export {
+  DOMAINS,
+  RegistryClient,
+  buildGatewayRecord,
+  buildIdentityCommit,
+  buildIdentityReveal,
+  buildPeerRecord,
+  epochOf,
+  fromRecords,
+  verifyGateway,
+  verifyIdentitySig,
+  verifyPeer
+};

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@inversealtruism/cairn-sdk",
+  "version": "0.1.0",
+  "description": "The Compute Substrate dApp kit — one cohesive toolkit to connect the Cairn Wallet, read the chain/board, publish self-certifying content, and resolve registries. Composes the published csd-* primitives.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./connect": {
+      "types": "./dist/connect.d.ts",
+      "import": "./dist/connect.js",
+      "require": "./dist/connect.cjs"
+    },
+    "./board": {
+      "types": "./dist/board.d.ts",
+      "import": "./dist/board.js",
+      "require": "./dist/board.cjs"
+    },
+    "./indexer": {
+      "types": "./dist/indexer.d.ts",
+      "import": "./dist/indexer.js",
+      "require": "./dist/indexer.cjs"
+    },
+    "./content": {
+      "types": "./dist/content.d.ts",
+      "import": "./dist/content.js",
+      "require": "./dist/content.cjs"
+    },
+    "./registry": {
+      "types": "./dist/registry.d.ts",
+      "import": "./dist/registry.js",
+      "require": "./dist/registry.cjs"
+    },
+    "./chain": {
+      "types": "./dist/chain.d.ts",
+      "import": "./dist/chain.js",
+      "require": "./dist/chain.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/connect.ts src/board.ts src/indexer.ts src/content.ts src/registry.ts src/chain.ts --format esm,cjs --dts --clean",
+    "test": "tsx test/sdk.test.ts && tsx test/connect.test.ts",
+    "test:live": "node examples/read-only.mjs",
+    "build:example": "node scripts/build-example.mjs",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
+  },
+  "dependencies": {
+    "@inversealtruism/csd-codec": "^0.1.3",
+    "@inversealtruism/csd-crypto": "^0.1.3",
+    "@inversealtruism/csd-tx": "^0.1.3",
+    "@inversealtruism/csd-client": "^0.1.3",
+    "@inversealtruism/csd-light": "^0.1.3",
+    "@inversealtruism/csd-registry": "^0.1.3"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.0"
+  },
+  "sideEffects": false,
+  "packageManager": "pnpm@10.32.1",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/InverseAltruism/cairn-sdk.git"
+  },
+  "homepage": "https://cairn-substrate.com",
+  "keywords": [
+    "compute-substrate",
+    "csd",
+    "cairn",
+    "wallet",
+    "dapp",
+    "sdk",
+    "blockchain"
+  ]
+}