@fluxpointstudios/orynq-sdk-quickstart 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Flux Point Studios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @fluxpointstudios/orynq-sdk-quickstart
+
+Solo-developer quickstart for orynq. 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.
+
+## Installation
+
+```bash
+npm install --global @fluxpointstudios/orynq-sdk-quickstart
+```
+
+## CLI
+
+```bash
+orynq init       # Generate identity + faucet-drip MATRA. Idempotent.
+orynq trace      # Build + submit a chain-anchored first trace.
+orynq whoami     # Print the saved SS58 address.
+orynq status     # Show gateway + chain health.
+orynq help       # Show usage.
+```
+
+## Programmatic API
+
+```typescript
+import { bootstrapAndTrace } from "@fluxpointstudios/orynq-sdk-quickstart";
+
+const result = await bootstrapAndTrace({
+  // All defaults point at Materios preprod. Set any subset to override.
+  agentId: "my-agent",
+  summary: "anchored from my CI pipeline",
+  onProgress(step) {
+    // Optional live progress stream.
+    console.log(step.kind);
+  },
+});
+
+console.log("Trace URL:", result.urls.blobStatus);
+console.log("Cert hash:", result.certHash);
+```
+
+### Primitives
+
+If you don't want the all-in-one bootstrap, mix and match:
+
+```typescript
+import {
+  loadOrCreateIdentity,
+  requestFaucet,
+  firstTraceBundle,
+  buildExplorerUrls,
+  DEFAULT_RPC_URL,
+  DEFAULT_GATEWAY_URL,
+} from "@fluxpointstudios/orynq-sdk-quickstart";
+
+const identity = await loadOrCreateIdentity();
+await requestFaucet({ address: identity.address, gatewayBaseUrl: DEFAULT_GATEWAY_URL });
+const bundle = await firstTraceBundle({ agentId: "my-agent", summary: "hi" });
+// ...build your own MateriosProvider, submit, certify...
+const urls = buildExplorerUrls({ contentHash, blockHash, gatewayBaseUrl: DEFAULT_GATEWAY_URL, rpcUrl: DEFAULT_RPC_URL });
+```
+
+## Env variable overrides
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `ORYNQ_CONFIG_PATH` | `~/.orynq/config.json` | Identity file location |
+| `ORYNQ_RPC_URL` | `wss://materios.fluxpointstudios.com/rpc` | Substrate WS RPC URL |
+| `ORYNQ_GATEWAY_URL` | `https://materios.fluxpointstudios.com/blobs` | Blob-gateway base URL |
+| `ORYNQ_AGENT_ID` | `orynq-quickstart` | Agent ID stamped on the trace |
+| `ORYNQ_SUMMARY` | auto-generated | Observation event content |
+| `ORYNQ_SKIP_FAUCET` | `0` | Set to `1` to skip faucet drip |
+| `ORYNQ_VERBOSE` | `0` | Set to `1` for extra info on `whoami` |
+
+## Trust model
+
+`orynq init` generates a fresh sr25519 keypair and writes the mnemonic to `~/.orynq/config.json` with 0600 permissions (POSIX). On Materios preprod, that address can:
+
+- Faucet-drip test MATRA (one-shot per address)
+- Upload blob data to the public gateway via sig-only auth
+- Submit `submitReceipt` extrinsics on chain
+
+There is **no** automatic upgrade to a Materios-mainnet identity yet — the preprod identity is meant for "hello world" learning. To move a real workload to mainnet, generate a separate mainnet identity (recommended: hardware-wallet-backed) and point `ORYNQ_RPC_URL` / `ORYNQ_GATEWAY_URL` at the mainnet endpoints.
+
+## Sub-5-minute contract
+
+The package's CI exercises a fresh-install simulation that asserts `bootstrapAndTrace()` completes in under 300 seconds (5 minutes) including faucet drip, MOTRA generation, on-chain submission, and committee certification on Materios preprod.
+
+Measured end-to-end on Gemtek (4-core, 16 GB RAM, residential link, 2026-05-14):
+
+- `npm install --global` — ~10 s
+- `orynq trace` (cold start, fresh address, no funds) — 167.9 s
+- Total — ~178 s = 2:58, well under the 5-minute bar
+
+`orynq trace` is idempotent — rerunning prints the same identity and submits a new receipt without re-faucet (the per-address ledger reuses the existing balance).
+
+## License
+
+MIT

package/bin/orynq.mjs

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+/**
+ * `orynq` — solo-developer CLI for orynq-sdk-quickstart.
+ *
+ * Subcommands:
+ *   orynq init         Generate identity + faucet drip + verify chain reach.
+ *                      No on-chain submission. Idempotent: reruns just print
+ *                      the current state.
+ *   orynq trace        Submit a one-event "hello" trace from the saved
+ *                      identity. Prints the explorer URLs at the end.
+ *                      Combines `init` + first submission.
+ *   orynq whoami       Print the saved address. No network calls.
+ *   orynq status       GET ${gateway}/health and print the summary.
+ *
+ * Env overrides:
+ *   ORYNQ_CONFIG_PATH    Path to identity file (default: ~/.orynq/config.json).
+ *   ORYNQ_RPC_URL        Substrate WS RPC URL (default: preprod).
+ *   ORYNQ_GATEWAY_URL    Blob-gateway URL (default: preprod).
+ *   ORYNQ_AGENT_ID       AgentId for the trace bundle.
+ *   ORYNQ_SUMMARY        Override the default observation event content.
+ *   ORYNQ_SKIP_FAUCET    "1" to skip the faucet step (already-funded addrs).
+ *
+ * Exit codes:
+ *   0   success
+ *   1   user-facing error (printed to stderr, no stack trace)
+ *   2   internal/unexpected error (full stack trace)
+ */
+import { argv, env, exit, stderr, stdout, version as nodeVersion } from "node:process";
+
+// Lazy-resolve the package's own dist so the CLI works both from the
+// monorepo dev tree and from a published tarball.
+async function loadSdk() {
+  return import("../dist/index.js").catch(() => import("../src/index.ts"));
+}
+
+function ansi(s, code) {
+  if (!stdout.isTTY) return s;
+  return `[${code}m${s}`;
+}
+const bold = (s) => ansi(s, "1");
+const dim = (s) => ansi(s, "2");
+const green = (s) => ansi(s, "32");
+const yellow = (s) => ansi(s, "33");
+const cyan = (s) => ansi(s, "36");
+const red = (s) => ansi(s, "31");
+
+function printUsage() {
+  stdout.write(
+    [
+      `${bold("orynq")} — solo-dev CLI for orynq-sdk-quickstart`,
+      ``,
+      `Usage:`,
+      `  ${bold("orynq init")}     Generate identity + faucet-drip MATRA.`,
+      `                            Idempotent — safe to rerun.`,
+      `  ${bold("orynq trace")}    Submit your first trace on Materios.`,
+      `                            Combines init + on-chain submit + cert.`,
+      `  ${bold("orynq whoami")}   Print the saved SS58 address.`,
+      `  ${bold("orynq status")}   Show gateway + chain health.`,
+      `  ${bold("orynq help")}     Show this message.`,
+      ``,
+      `Env overrides:`,
+      `  ORYNQ_CONFIG_PATH=<path>   Where to save identity (default: ~/.orynq/config.json)`,
+      `  ORYNQ_RPC_URL=<wss-url>    Substrate RPC (default: Materios preprod)`,
+      `  ORYNQ_GATEWAY_URL=<url>    Blob-gateway base URL`,
+      `  ORYNQ_SKIP_FAUCET=1        Skip the faucet drip step`,
+      ``,
+      `Docs: https://github.com/Flux-Point-Studios/orynq-sdk#quickstart`,
+      ``,
+    ].join("\n"),
+  );
+}
+
+async function cmdInit() {
+  const sdk = await loadSdk();
+  const identity = await sdk.loadOrCreateIdentity({
+    configPath: env.ORYNQ_CONFIG_PATH,
+  });
+
+  stdout.write(
+    `${bold("Identity")} ${identity.freshlyGenerated ? green("created") : dim("(reused)")}\n`,
+  );
+  stdout.write(`  address     ${cyan(identity.address)}\n`);
+  stdout.write(`  configPath  ${identity.configPath}\n`);
+  stdout.write(`  generatedAt ${identity.generatedAt}\n`);
+  for (const w of identity.warnings) {
+    stdout.write(`  ${yellow("warning")}     ${w}\n`);
+  }
+
+  if (env.ORYNQ_SKIP_FAUCET !== "1") {
+    const gateway = env.ORYNQ_GATEWAY_URL ?? sdk.DEFAULT_GATEWAY_URL;
+    stdout.write(`\n${bold("Faucet")} ${dim(`(${gateway})`)}\n`);
+    const result = await sdk.requestFaucet({
+      address: identity.address,
+      gatewayBaseUrl: gateway,
+    });
+    switch (result.kind) {
+      case "success":
+        stdout.write(`  ${green("dripped")} ${result.amount} units\n`);
+        stdout.write(`  txHash      ${result.txHash}\n`);
+        stdout.write(`  ${dim("MOTRA will generate over the next few blocks.")}\n`);
+        break;
+      case "already-funded":
+        stdout.write(
+          `  ${dim("(already funded — drip ledger says yes; will reuse existing balance)")}\n`,
+        );
+        break;
+      case "cooldown":
+        stdout.write(
+          `  ${yellow("cooldown")} retry in ~${Math.round((result.retryAfterMs ?? 0) / 1000)}s\n`,
+        );
+        break;
+      case "error":
+        stdout.write(`  ${red("error")} ${result.message} (HTTP ${result.status})\n`);
+        return 1;
+    }
+  } else {
+    stdout.write(`\n${bold("Faucet")} ${dim("(skipped via ORYNQ_SKIP_FAUCET=1)")}\n`);
+  }
+
+  stdout.write(`\n${green("init complete")}. Next:\n`);
+  stdout.write(`  ${bold("orynq trace")}    submit your first trace\n`);
+  return 0;
+}
+
+async function cmdTrace() {
+  const sdk = await loadSdk();
+  const traceStart = Date.now();
+
+  const result = await sdk.bootstrapAndTrace({
+    configPath: env.ORYNQ_CONFIG_PATH,
+    rpcUrl: env.ORYNQ_RPC_URL,
+    gatewayBaseUrl: env.ORYNQ_GATEWAY_URL,
+    agentId: env.ORYNQ_AGENT_ID,
+    summary: env.ORYNQ_SUMMARY,
+    skipFaucet: env.ORYNQ_SKIP_FAUCET === "1",
+    onProgress(step) {
+      const ts = ((Date.now() - traceStart) / 1000).toFixed(1).padStart(5, " ");
+      const tag = `${dim(`[+${ts}s]`)}`;
+      switch (step.kind) {
+        case "identity-loaded":
+          stdout.write(
+            `${tag} identity ${step.identity.freshlyGenerated ? green("created") : dim("(reused)")} ${cyan(step.identity.address)}\n`,
+          );
+          break;
+        case "faucet-result":
+          if (step.result.kind === "success") {
+            stdout.write(`${tag} faucet ${green("dripped")} ${step.result.amount} units (tx ${step.result.txHash.slice(0, 12)}...)\n`);
+          } else if (step.result.kind === "already-funded") {
+            stdout.write(`${tag} faucet ${dim("already funded — reusing balance")}\n`);
+          }
+          break;
+        case "waiting-for-motra":
+          stdout.write(`${tag} waiting for MOTRA fee currency to generate (~10-30s)...\n`);
+          break;
+        case "motra-ready":
+          stdout.write(`${tag} MOTRA ready (${step.balance.toString()} units)\n`);
+          break;
+        case "trace-built":
+          stdout.write(
+            `${tag} trace built — runId ${dim(step.bundle.runId.slice(0, 8))} rootHash ${dim(step.bundle.rootHash.slice(0, 12))}\n`,
+          );
+          break;
+        case "receipt-submitted":
+          stdout.write(
+            `${tag} receipt submitted — receiptId ${dim(step.receiptId.slice(0, 14))} block ${dim(step.blockHash.slice(0, 14))}\n`,
+          );
+          break;
+        case "certified":
+          stdout.write(
+            `${tag} ${green("certified")} certHash ${dim(step.certHash.slice(0, 14))}\n`,
+          );
+          break;
+        case "explorer-ready":
+          // Handled below in the summary block — keep the streaming
+          // output uncluttered.
+          break;
+      }
+    },
+  });
+
+  // Summary block — this is what the dev came for.
+  stdout.write(`\n${green("First trace anchored on Materios")} ${dim(`(${(result.elapsedMs / 1000).toFixed(1)}s)`)}\n\n`);
+  stdout.write(`${bold("View your trace:")}\n`);
+  stdout.write(`  blob status   ${cyan(result.urls.blobStatus)}\n`);
+  stdout.write(`  chain block   ${cyan(result.urls.explorer)}\n`);
+  stdout.write(`  chain info    ${dim(result.urls.chainInfo)}\n`);
+  stdout.write(`  health        ${dim(result.urls.gatewayHealth)}\n`);
+  stdout.write(`\n${bold("Hashes")}\n`);
+  stdout.write(`  receiptId     ${result.receiptId}\n`);
+  stdout.write(`  blockHash     ${result.blockHash}\n`);
+  stdout.write(`  rootHash      ${result.bundle.rootHash}\n`);
+  stdout.write(`  merkleRoot    ${result.bundle.merkleRoot}\n`);
+  if (result.certHash) {
+    stdout.write(`  certHash      ${result.certHash}\n`);
+  }
+  return 0;
+}
+
+async function cmdWhoami() {
+  const sdk = await loadSdk();
+  // Use loadOrCreateIdentity, which creates on first run. If the dev
+  // explicitly wants to refuse auto-create, they can rm the file before
+  // calling whoami — but the spec is "frictionless first call", so we
+  // create.
+  const identity = await sdk.loadOrCreateIdentity({
+    configPath: env.ORYNQ_CONFIG_PATH,
+  });
+  stdout.write(`${identity.address}\n`);
+  if (env.ORYNQ_VERBOSE === "1") {
+    stdout.write(`${dim("config: " + identity.configPath)}\n`);
+    stdout.write(`${dim("generatedAt: " + identity.generatedAt)}\n`);
+  }
+  return 0;
+}
+
+async function cmdStatus() {
+  const sdk = await loadSdk();
+  const gateway = env.ORYNQ_GATEWAY_URL ?? sdk.DEFAULT_GATEWAY_URL;
+  const base = gateway.replace(/\/blobs\/?$/, "").replace(/\/$/, "");
+  // /status is the cluster-wide rollup (gateway + cert-daemon + anchor-worker).
+  // /health is gateway-only. Prefer /status so the dev sees finality + L1
+  // anchor health at a glance.
+  const url = `${base}/status`;
+  let res;
+  try {
+    res = await fetch(url);
+  } catch (e) {
+    stderr.write(`${red("error")} could not reach ${url}: ${e instanceof Error ? e.message : String(e)}\n`);
+    return 1;
+  }
+  const text = await res.text();
+  if (!res.ok) {
+    stderr.write(`${red("error")} HTTP ${res.status} from ${url}\n${text}\n`);
+    return 1;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    stdout.write(text);
+    return 0;
+  }
+  stdout.write(`${bold("Materios")} ${cyan(base)}\n`);
+  stdout.write(`  status        ${parsed.overall ?? parsed.status ?? "unknown"}\n`);
+  if (parsed.components?.gateway) {
+    const g = parsed.components.gateway;
+    stdout.write(`  uptime        ${Math.round((g.uptime ?? 0) / 60)}m\n`);
+    stdout.write(`  totalReceipts ${g.storage?.totalReceipts ?? "?"}\n`);
+  }
+  if (parsed.components?.certDaemonAlice) {
+    const c = parsed.components.certDaemonAlice;
+    stdout.write(`  bestBlock     ${c.bestBlock}\n`);
+    stdout.write(`  finalityGap   ${c.finalityGap}\n`);
+  }
+  if (parsed.components?.anchorWorker) {
+    const a = parsed.components.anchorWorker;
+    stdout.write(`  anchorCount   ${a.anchorCount}\n`);
+    stdout.write(`  cardanoTxs    last=${a.lastTxHash?.slice(0, 12) ?? "?"}...\n`);
+  }
+  return 0;
+}
+
+async function main() {
+  const cmd = argv[2] ?? "help";
+  try {
+    switch (cmd) {
+      case "init":
+        return await cmdInit();
+      case "trace":
+        return await cmdTrace();
+      case "whoami":
+        return await cmdWhoami();
+      case "status":
+        return await cmdStatus();
+      case "help":
+      case "--help":
+      case "-h":
+        printUsage();
+        return 0;
+      case "--version":
+      case "-v": {
+        const sdk = await loadSdk();
+        stdout.write(`orynq-sdk-quickstart ${sdk.VERSION} (node ${nodeVersion})\n`);
+        return 0;
+      }
+      default:
+        stderr.write(`${red("error")} unknown command: ${cmd}\n\n`);
+        printUsage();
+        return 1;
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    // User-facing errors carry a leading-lowercase, no-trailing-period
+    // convention. Internal errors print the full stack.
+    if (err instanceof Error && /^[a-z]/.test(msg) && !/^Error:/.test(msg)) {
+      stderr.write(`${red("error")} ${msg}\n`);
+      return 1;
+    }
+    stderr.write(`${red("internal error")}\n`);
+    if (err instanceof Error && err.stack) stderr.write(err.stack + "\n");
+    else stderr.write(String(err) + "\n");
+    return 2;
+  }
+}
+
+main().then((code) => exit(code ?? 0));