@fluxpointstudios/orynq-sdk-quickstart 0.2.0

package/src/faucet.ts

@@ -0,0 +1,158 @@
+/**
+ * @summary Free-tier MATRA faucet client.
+ *
+ * The Materios preprod blob-gateway exposes `POST /blobs/faucet/drip` (and
+ * `POST /faucet/drip` mounted at the same handler). One-shot per SS58
+ * address, IP-cooldown 5 min on the un-prefixed path. The dripped MATRA
+ * generates MOTRA (fee currency) over the next few blocks — that's how a
+ * fresh dev pays for their first `submit_receipt` extrinsic without an
+ * out-of-band funding step.
+ *
+ * Returns a discriminated union so callers can branch on `kind` without
+ * sniffing error messages.
+ */
+
+export interface FaucetDripSuccess {
+  kind: "success";
+  txHash: string;
+  amount: string;
+  message: string;
+}
+
+export interface FaucetDripAlreadyFunded {
+  kind: "already-funded";
+  drippedAtMs: number;
+}
+
+export interface FaucetDripCooldown {
+  kind: "cooldown";
+  retryAfterMs: number;
+  message: string;
+}
+
+export interface FaucetDripError {
+  kind: "error";
+  status: number;
+  message: string;
+}
+
+export type FaucetDripResult =
+  | FaucetDripSuccess
+  | FaucetDripAlreadyFunded
+  | FaucetDripCooldown
+  | FaucetDripError;
+
+export interface RequestFaucetOptions {
+  /** SS58 address to drip MATRA into. */
+  address: string;
+  /**
+   * Gateway base URL. Accepts either `https://host` or `https://host/blobs`.
+   * The /blobs/-prefixed faucet path is preferred (per-address ledger);
+   * the bare /faucet path adds an IP-level 5-min cooldown so we leave it
+   * alone here.
+   */
+  gatewayBaseUrl: string;
+  /**
+   * Optional fetch impl injection (for tests + Cloudflare Workers).
+   * Defaults to the global `fetch`.
+   */
+  fetchImpl?: typeof fetch | undefined;
+  /**
+   * Optional AbortSignal — propagated to the underlying fetch so callers
+   * can wire up a Ctrl-C handler.
+   */
+  signal?: AbortSignal | undefined;
+}
+
+/**
+ * Strip a trailing slash + trailing /blobs from a gateway base URL,
+ * leaving the bare origin. The faucet route is mounted on the express
+ * root (not the /blobs router) but is reachable via the nginx
+ * reverse-proxy that prefixes /blobs — so the publicly-working URL
+ * needs the /blobs segment exactly once.
+ */
+function normaliseToRoot(base: string): string {
+  let s = base.trim();
+  if (s.endsWith("/")) s = s.slice(0, -1);
+  if (s.endsWith("/blobs")) s = s.slice(0, -"/blobs".length);
+  return s;
+}
+
+/**
+ * Drip MATRA to a fresh SS58 address.
+ *
+ * Idempotent at the caller's level: if the address has already been
+ * dripped (per-address ledger), returns `kind: "already-funded"` instead
+ * of throwing — the caller can treat both `success` and `already-funded`
+ * as "we have MATRA, proceed".
+ */
+export async function requestFaucet(
+  opts: RequestFaucetOptions,
+): Promise<FaucetDripResult> {
+  const f = opts.fetchImpl ?? fetch;
+  const rootBase = normaliseToRoot(opts.gatewayBaseUrl);
+  // /blobs/faucet/drip == the per-address-ledger faucet (preferred).
+  // /faucet/drip == the IP-cooldown variant (we avoid it).
+  const url = `${rootBase}/blobs/faucet/drip`;
+
+  const fetchOpts: RequestInit = {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ address: opts.address }),
+  };
+  if (opts.signal) {
+    fetchOpts.signal = opts.signal;
+  }
+  const res = await f(url, fetchOpts);
+
+  const text = await res.text();
+  let json: Record<string, unknown> = {};
+  try {
+    json = text ? (JSON.parse(text) as Record<string, unknown>) : {};
+  } catch {
+    // Non-JSON body — surface the raw text as the error message.
+    return {
+      kind: "error",
+      status: res.status,
+      message: text.slice(0, 256),
+    };
+  }
+
+  if (res.ok && json["success"] === true) {
+    return {
+      kind: "success",
+      txHash: String(json["tx_hash"] ?? ""),
+      amount: String(json["amount"] ?? ""),
+      message: String(json["message"] ?? "MATRA dripped"),
+    };
+  }
+
+  // Per-address dedup: 409 + "Address already received a drip" + dripped_at.
+  if (res.status === 409 && typeof json["dripped_at"] === "number") {
+    return { kind: "already-funded", drippedAtMs: Number(json["dripped_at"]) };
+  }
+
+  // IP-level cooldown (the un-prefixed /faucet/drip path uses this).
+  if (
+    res.status === 429 ||
+    /cooldown/i.test(String(json["error"] ?? ""))
+  ) {
+    const retryAfterMs =
+      typeof json["cooldown_ms"] === "number"
+        ? Number(json["cooldown_ms"])
+        : typeof json["retry_after_seconds"] === "number"
+          ? Number(json["retry_after_seconds"]) * 1000
+          : 0;
+    return {
+      kind: "cooldown",
+      retryAfterMs,
+      message: String(json["error"] ?? "Faucet cooldown active"),
+    };
+  }
+
+  return {
+    kind: "error",
+    status: res.status,
+    message: String(json["error"] ?? text.slice(0, 256) ?? "Unknown faucet error"),
+  };
+}

package/src/identity.ts

@@ -0,0 +1,193 @@
+/**
+ * @summary Local sr25519 identity bootstrap for solo-dev quickstart.
+ *
+ * Generates a fresh BIP39 mnemonic on first run, derives an sr25519 keypair,
+ * and persists the mnemonic to `~/.orynq/config.json` (or any caller-supplied
+ * path) with 0600 permissions on POSIX systems. Subsequent calls reload the
+ * same identity so the address stays stable across processes.
+ *
+ * This is intentionally pure-local: no network, no chain RPC, no faucet.
+ * Anchoring + faucet drip belong in `bootstrap.ts` so callers who already
+ * have an identity can skip identity generation entirely.
+ *
+ * Trust model: the mnemonic on disk is treated like any other developer
+ * secret. The config file is created with 0600 perms; an explicit warning is
+ * emitted via the returned `OrynqIdentity.warnings` array when the env
+ * suggests a shared filesystem (which is reserved for a follow-up — kept
+ * as `warnings: []` today so the public shape stays stable).
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "fs";
+import { dirname } from "path";
+import { homedir } from "os";
+import {
+  cryptoWaitReady,
+  mnemonicGenerate,
+  mnemonicValidate,
+} from "@polkadot/util-crypto";
+import { Keyring } from "@polkadot/keyring";
+
+/**
+ * Solo-dev identity loaded from disk or freshly generated.
+ *
+ * Fields:
+ *   - `mnemonic`     BIP39 12-word seed phrase. Required to sign on-chain
+ *                    txs and blob-gateway uploads. Treat as a secret.
+ *   - `address`      sr25519 SS58 address derived from `mnemonic`. Safe to
+ *                    log; this is the public chain identity.
+ *   - `generatedAt`  ISO timestamp of original generation.
+ *   - `configPath`   Where the identity is persisted.
+ *   - `freshlyGenerated`  True iff this call generated a new mnemonic (vs
+ *                    reloading an existing one). Lets the CLI print "saved
+ *                    new identity to..." only on the first run.
+ *   - `warnings`     Non-fatal advisories from the loader. Empty today;
+ *                    reserved for shared-FS / world-readable-perm checks.
+ */
+export interface OrynqIdentity {
+  mnemonic: string;
+  address: string;
+  generatedAt: string;
+  configPath: string;
+  freshlyGenerated: boolean;
+  warnings: string[];
+}
+
+export interface LoadOrCreateIdentityOptions {
+  /**
+   * Path to the persistent identity file. Defaults to
+   * `${HOME}/.orynq/config.json`. The parent directory is created
+   * recursively if it does not exist.
+   */
+  configPath?: string | undefined;
+
+  /**
+   * SS58 prefix for the encoded address. Defaults to 42 (generic Substrate).
+   * Materios uses 42 in v6 preprod; pass a different value here if you're
+   * targeting a chain with a custom prefix.
+   */
+  ss58Format?: number | undefined;
+}
+
+/**
+ * Default config-file location: `~/.orynq/config.json`.
+ *
+ * Exposed so other code (`bootstrap.ts`, the CLI) can reference the same
+ * default without duplicating the homedir join.
+ */
+export function defaultConfigPath(): string {
+  return `${homedir()}/.orynq/config.json`;
+}
+
+interface OnDiskConfig {
+  version: 1;
+  mnemonic: string;
+  address: string;
+  generatedAt: string;
+}
+
+/**
+ * Load an existing identity from `configPath`, or generate + persist a new
+ * one if the file does not exist.
+ *
+ * Throws if the config file exists but cannot be parsed — better to fail
+ * loudly than silently regenerate and orphan whatever identity used to be
+ * there (and any MATRA balance on it).
+ */
+export async function loadOrCreateIdentity(
+  opts: LoadOrCreateIdentityOptions = {},
+): Promise<OrynqIdentity> {
+  await cryptoWaitReady();
+
+  const configPath = opts.configPath ?? defaultConfigPath();
+  const ss58Format = opts.ss58Format ?? 42;
+  const warnings: string[] = [];
+
+  if (existsSync(configPath)) {
+    let parsed: OnDiskConfig;
+    try {
+      const raw = readFileSync(configPath, "utf-8");
+      parsed = JSON.parse(raw) as OnDiskConfig;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `orynq identity config at ${configPath} is corrupt and cannot be parsed: ${msg}. ` +
+          `Inspect the file by hand — do NOT delete it without first checking whether the ` +
+          `mnemonic inside is still recoverable. If you want a fresh identity, move the file ` +
+          `aside (e.g. mv ${configPath} ${configPath}.broken) and rerun.`,
+      );
+    }
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      typeof parsed.mnemonic !== "string" ||
+      typeof parsed.address !== "string"
+    ) {
+      throw new Error(
+        `orynq identity config at ${configPath} is missing required fields (mnemonic, address). ` +
+          `File contents may be from an older or unrelated tool. Move it aside and rerun.`,
+      );
+    }
+    if (!mnemonicValidate(parsed.mnemonic)) {
+      throw new Error(
+        `orynq identity config at ${configPath} has an invalid mnemonic. ` +
+          `Move it aside and rerun, or restore from your secure backup.`,
+      );
+    }
+    const keyring = new Keyring({ type: "sr25519", ss58Format });
+    const pair = keyring.addFromUri(parsed.mnemonic);
+    if (pair.address !== parsed.address) {
+      // Likely an SS58 prefix mismatch between when it was written and now.
+      // Re-encode at the caller-specified prefix and continue, but warn.
+      warnings.push(
+        `address re-encoded under ss58Format=${ss58Format} (config had ${parsed.address})`,
+      );
+    }
+    return {
+      mnemonic: parsed.mnemonic,
+      address: pair.address,
+      generatedAt: parsed.generatedAt,
+      configPath,
+      freshlyGenerated: false,
+      warnings,
+    };
+  }
+
+  // No config — generate fresh.
+  const mnemonic = mnemonicGenerate(12);
+  const keyring = new Keyring({ type: "sr25519", ss58Format });
+  const pair = keyring.addFromUri(mnemonic);
+  const generatedAt = new Date().toISOString();
+
+  const config: OnDiskConfig = {
+    version: 1,
+    mnemonic,
+    address: pair.address,
+    generatedAt,
+  };
+
+  mkdirSync(dirname(configPath), { recursive: true, mode: 0o700 });
+  // Set the file mode at creation time via the `mode` option (POSIX
+  // O_CREAT honors it). The previous post-create `chmodSync` left the
+  // file briefly world-readable in the window between write and chmod —
+  // for the default `~/.orynq/config.json` path the 0o700 parent dir
+  // mitigates, but for env-var paths whose parent dir pre-exists at
+  // 0o755 (e.g. /tmp/devkey.json) a co-tenant could race the chmod
+  // and read the mnemonic. Setting mode at open(2) closes that window.
+  // Sec-review finding: PR #54, MEDIUM, 9/10 confidence.
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
+  if (process.platform !== "win32") {
+    // Defense-in-depth — handles the case where the file already existed
+    // and `writeFileSync` overwrote without re-applying mode. (Per Node
+    // docs, `mode` is ignored when the file already exists.)
+    chmodSync(configPath, 0o600);
+  }
+
+  return {
+    mnemonic,
+    address: pair.address,
+    generatedAt,
+    configPath,
+    freshlyGenerated: true,
+    warnings,
+  };
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+/**
+ * @fluxpointstudios/orynq-sdk-quickstart
+ *
+ * Solo-developer DX surface. Get from `npm install` to a chain-anchored
+ * first trace in under 5 minutes — no signer URI to manage, no wallet to
+ * seed, no Cardano addresses to look up.
+ *
+ * Three layers:
+ *
+ *   - **CLI** (`bin/orynq.mjs`):    `orynq init`, `orynq trace`,
+ *                                    `orynq whoami`, `orynq status`.
+ *   - **One-call API**:              `bootstrapAndTrace()` — identity,
+ *                                    faucet, submit, certify, URL.
+ *   - **Primitives**:                `loadOrCreateIdentity`,
+ *                                    `firstTraceBundle`, `requestFaucet`,
+ *                                    `buildExplorerUrls`. Mix and match
+ *                                    when you're past the hello-world tier.
+ *
+ * All primitives are pure ESM, zero side-effects on import. The first
+ * filesystem write happens only when you call into `loadOrCreateIdentity`
+ * (or any helper that wraps it), so this package is safe to require()
+ * from a Cloudflare Worker or a Vite client bundle.
+ */
+
+export {
+  loadOrCreateIdentity,
+  defaultConfigPath,
+} from "./identity.js";
+export type {
+  OrynqIdentity,
+  LoadOrCreateIdentityOptions,
+} from "./identity.js";
+
+export { firstTraceBundle } from "./trace.js";
+export type {
+  TraceBundleLite,
+  FirstTraceBundleOptions,
+  DeterministicHooks,
+} from "./trace.js";
+
+export { requestFaucet } from "./faucet.js";
+export type {
+  FaucetDripResult,
+  FaucetDripSuccess,
+  FaucetDripAlreadyFunded,
+  FaucetDripCooldown,
+  FaucetDripError,
+  RequestFaucetOptions,
+} from "./faucet.js";
+
+export { buildExplorerUrls } from "./explorer.js";
+export type { ExplorerUrls, BuildExplorerUrlsInput } from "./explorer.js";
+
+export {
+  bootstrapAndTrace,
+  deriveAddress,
+  DEFAULT_RPC_URL,
+  DEFAULT_GATEWAY_URL,
+  DEFAULT_AGENT_ID,
+} from "./bootstrap.js";
+export type {
+  BootstrapAndTraceOptions,
+  BootstrapAndTraceResult,
+  BootstrapStep,
+} from "./bootstrap.js";
+
+export const VERSION = "0.1.0";

package/src/trace.ts

@@ -0,0 +1,210 @@
+/**
+ * @summary Minimal trace-bundle factory used by `orynq init` / `orynq trace`.
+ *
+ * Wraps `@fluxpointstudios/orynq-sdk-process-trace` with a one-call helper
+ * that produces a finalised bundle from a single observation event. The
+ * heavyweight builder (multi-span, multi-event, custom kinds) lives in
+ * the underlying package — quickstart deliberately ships only the
+ * "hello world" path so a fresh dev sees a trace land before they're
+ * forced to learn span semantics.
+ */
+
+import { createHash } from "crypto";
+import {
+  createTrace,
+  addSpan,
+  addEvent,
+  closeSpan,
+  finalizeTrace,
+} from "@fluxpointstudios/orynq-sdk-process-trace";
+import type { TraceBundle } from "@fluxpointstudios/orynq-sdk-process-trace";
+
+/**
+ * Slimmed-down public view of a `TraceBundle` — exposes only the fields
+ * `orynq init` / `orynq trace` needs to print + the raw `content` JSON the
+ * caller will upload as a blob. The full `bundle` is preserved on the
+ * returned object so power-users can still walk events/spans.
+ */
+export interface TraceBundleLite {
+  runId: string;
+  agentId: string;
+  rootHash: string;
+  merkleRoot: string;
+  /**
+   * SHA-256 of the canonical JSON content payload as a hex string. Set by
+   * `firstTraceBundle()` so the same hash that ends up in the on-chain
+   * receipt is available without re-canonicalising downstream.
+   */
+  manifestHash: string;
+  /**
+   * Canonical JSON serialisation of `bundle.publicView`. This is what we
+   * upload to the blob gateway under `contentHash = sha256(content)`.
+   */
+  content: string;
+  /** Original full bundle, in case callers want spans/events. */
+  bundle: TraceBundle;
+}
+
+/**
+ * Optional deterministic-clock + identifier hooks. Used by the
+ * documentation tests + recipes that need stable hashes across runs.
+ *
+ * In normal use (production), callers pass nothing here and let the
+ * trace-builder pick wall-clock timestamps + random UUIDs.
+ */
+export interface DeterministicHooks {
+  /** Pin `new Date()`/`Date.now()` for the duration of this call. */
+  now?: () => Date;
+  /** Pin the run UUID returned by `createTrace`. */
+  runId?: string;
+  /** Pin the span UUID returned by `addSpan`. */
+  spanId?: string;
+  /** Pin the event UUID returned by `addEvent`. */
+  eventId?: string;
+}
+
+export interface FirstTraceBundleOptions extends DeterministicHooks {
+  agentId: string;
+  /** Free-form one-liner appended as the public observation event. */
+  summary: string;
+}
+
+/**
+ * Build, finalise, and serialise a one-event, one-span trace bundle.
+ *
+ * The optional `now`/`runId`/`spanId`/`eventId` hooks are useful for tests
+ * that need byte-stable hashes; they patch the globals only for the
+ * duration of this single call and restore them in a `finally` block so
+ * we never leak the patch into surrounding code.
+ */
+export async function firstTraceBundle(
+  opts: FirstTraceBundleOptions,
+): Promise<TraceBundleLite> {
+  const restore = installDeterministicHooks(opts);
+  try {
+    const run = await createTrace({ agentId: opts.agentId });
+    const span = addSpan(run, { name: "first-trace", visibility: "public" });
+    await addEvent<"observation">(run, span.id, {
+      kind: "observation",
+      observation: opts.summary,
+      visibility: "public",
+    });
+    await closeSpan(run, span.id);
+    const bundle = await finalizeTrace(run);
+
+    // Canonicalise the public view (the part we publish) — this is the
+    // exact bytes the blob-gateway will checksum at upload time.
+    const content = canonicalJson(bundle.publicView);
+    const manifestHash = sha256Hex(content);
+
+    return {
+      runId: bundle.publicView.runId,
+      agentId: bundle.publicView.agentId,
+      rootHash: bundle.rootHash,
+      merkleRoot: bundle.merkleRoot,
+      manifestHash,
+      content,
+      bundle,
+    };
+  } finally {
+    restore();
+  }
+}
+
+/**
+ * Apply the deterministic-clock + UUID hooks and return a function that
+ * undoes them. No-op when no hooks are supplied — the production hot path
+ * pays zero cost.
+ */
+function installDeterministicHooks(hooks: DeterministicHooks): () => void {
+  // Capture all originals up front so multiple-restore is a no-op.
+  const originalRandomUuid = globalThis.crypto?.randomUUID?.bind(globalThis.crypto);
+  const originalDate = globalThis.Date;
+
+  let didPatchUuid = false;
+  let didPatchDate = false;
+
+  if (hooks.runId || hooks.spanId || hooks.eventId) {
+    const queue: string[] = [];
+    if (hooks.runId) queue.push(hooks.runId);
+    if (hooks.spanId) queue.push(hooks.spanId);
+    if (hooks.eventId) queue.push(hooks.eventId);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (globalThis.crypto as any).randomUUID = (): string => {
+      const next = queue.shift();
+      if (next) return next;
+      return originalRandomUuid
+        ? originalRandomUuid()
+        : "00000000-0000-4000-8000-000000000000";
+    };
+    didPatchUuid = true;
+  }
+
+  if (hooks.now) {
+    const fixed = hooks.now();
+    const fixedMs = fixed.getTime();
+    // Wrap the Date constructor so `new Date()` (no args) returns the
+    // pinned moment; `new Date(ms)` and `new Date(str)` still work.
+    const Wrapped = new Proxy(originalDate, {
+      construct(target, args) {
+        if (args.length === 0) {
+          return new (target as DateConstructor)(fixedMs);
+        }
+        return new (target as DateConstructor)(
+          ...(args as ConstructorParameters<DateConstructor>),
+        );
+      },
+      get(target, prop, receiver) {
+        if (prop === "now") return () => fixedMs;
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (globalThis as any).Date = Wrapped;
+    didPatchDate = true;
+  }
+
+  return function restore() {
+    if (didPatchUuid && originalRandomUuid) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (globalThis.crypto as any).randomUUID = originalRandomUuid;
+    }
+    if (didPatchDate) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (globalThis as any).Date = originalDate;
+    }
+  };
+}
+
+/**
+ * Minimal RFC 8785-ish canonical JSON.
+ *
+ * Sorts keys, strips nulls/undefined. The full RFC 8785 implementation
+ * lives in `@fluxpointstudios/orynq-sdk-core/utils` but we deliberately
+ * avoid that dependency here so quickstart stays tiny + has zero
+ * transitive deps beyond polkadot.
+ */
+function canonicalJson(value: unknown): string {
+  return JSON.stringify(sortValue(value));
+}
+
+function sortValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((v) => sortValue(v));
+  }
+  if (value !== null && typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(obj).sort()) {
+      const v = obj[key];
+      if (v === undefined || v === null) continue;
+      sorted[key] = sortValue(v);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+function sha256Hex(s: string): string {
+  return createHash("sha256").update(s, "utf-8").digest("hex");
+}