@fluxpointstudios/orynq-sdk-quickstart 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,423 @@
+import { TraceBundle } from '@fluxpointstudios/orynq-sdk-process-trace';
+
+/**
+ * @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).
+ */
+/**
+ * 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.
+ */
+interface OrynqIdentity {
+    mnemonic: string;
+    address: string;
+    generatedAt: string;
+    configPath: string;
+    freshlyGenerated: boolean;
+    warnings: string[];
+}
+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.
+ */
+declare function defaultConfigPath(): 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).
+ */
+declare function loadOrCreateIdentity(opts?: LoadOrCreateIdentityOptions): Promise<OrynqIdentity>;
+
+/**
+ * @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.
+ */
+
+/**
+ * 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.
+ */
+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.
+ */
+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;
+}
+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.
+ */
+declare function firstTraceBundle(opts: FirstTraceBundleOptions): Promise<TraceBundleLite>;
+
+/**
+ * @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.
+ */
+interface FaucetDripSuccess {
+    kind: "success";
+    txHash: string;
+    amount: string;
+    message: string;
+}
+interface FaucetDripAlreadyFunded {
+    kind: "already-funded";
+    drippedAtMs: number;
+}
+interface FaucetDripCooldown {
+    kind: "cooldown";
+    retryAfterMs: number;
+    message: string;
+}
+interface FaucetDripError {
+    kind: "error";
+    status: number;
+    message: string;
+}
+type FaucetDripResult = FaucetDripSuccess | FaucetDripAlreadyFunded | FaucetDripCooldown | FaucetDripError;
+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;
+}
+/**
+ * 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".
+ */
+declare function requestFaucet(opts: RequestFaucetOptions): Promise<FaucetDripResult>;
+
+/**
+ * @summary Compose the user-facing URLs that close the loop on "first trace".
+ *
+ * The DX requirement (#175) is: after submission, the SDK MUST print a URL
+ * the developer can click and see something. Materios doesn't yet ship a
+ * native trace-detail explorer page, so we compose three known-good URLs:
+ *
+ *   1. `blobStatus`     — `${gateway}/blobs/<contentHash>/status` — gateway-
+ *                          side status of the receipt (HTTP 200 + JSON,
+ *                          browser-renderable).
+ *   2. `explorer`       — Polkadot.js apps explorer pre-pointed at the
+ *                          submission block. Shows the on-chain extrinsic
+ *                          with full SCALE-decoded args.
+ *   3. `chainInfo`      — `${gateway}/chain-info` — JSON with the live
+ *                          genesis hash + best block, useful as a sanity
+ *                          check that the gateway is the chain you think
+ *                          it is.
+ *   4. `gatewayHealth`  — `${gateway}/health` — cluster-health summary
+ *                          (cert-daemon, anchor-worker, storage usage).
+ *
+ * A follow-up will replace `explorer` with a first-party
+ * `https://materios.fluxpointstudios.com/trace/<contentHash>` page (filed
+ * separately) — at which point the field swaps and the rest of the SDK
+ * surface keeps working.
+ */
+interface BuildExplorerUrlsInput {
+    /**
+     * Hex content hash, with or without `0x` prefix. Used to build the
+     * gateway status URL.
+     */
+    contentHash: string;
+    /**
+     * Hex block hash from the on-chain submission, with or without `0x`.
+     * Used to build the Polkadot.js apps query URL.
+     */
+    blockHash: string;
+    /**
+     * Gateway base URL. Accepts either `https://host` or `https://host/blobs`
+     * — the function normalises so callers don't have to remember which
+     * variant the env exports.
+     */
+    gatewayBaseUrl: string;
+    /**
+     * Substrate websocket RPC URL. Used to build the Polkadot.js apps
+     * pre-pointed-at-this-chain URL.
+     */
+    rpcUrl: string;
+}
+interface ExplorerUrls {
+    /** Gateway blob status JSON. */
+    blobStatus: string;
+    /** Polkadot.js apps pre-pointed at this chain's submission block. */
+    explorer: string;
+    /** Gateway chain-info endpoint (genesis + best block). */
+    chainInfo: string;
+    /** Gateway top-level health roll-up. */
+    gatewayHealth: string;
+}
+declare function buildExplorerUrls(input: BuildExplorerUrlsInput): ExplorerUrls;
+
+/**
+ * @summary One-call solo-dev bootstrap.
+ *
+ * `bootstrapAndTrace()` does ALL of:
+ *
+ *   1. `loadOrCreateIdentity()`  — fresh sr25519 keypair on first run.
+ *   2. `requestFaucet()`         — free-tier MATRA drip on the gateway.
+ *   3. `firstTraceBundle()`      — build + finalise a "hello" trace.
+ *   4. `submitCertifiedReceipt()` — upload blob + submit receipt on chain.
+ *   5. `buildExplorerUrls()`     — compose the URLs the dev needs to click.
+ *
+ * Compared to the manual flow (e2e-flow.ts), this collapses ~10 lines of
+ * MateriosProvider config + 30 lines of error handling into a single
+ * `await bootstrapAndTrace({})`. Defaults target Materios preprod; pass
+ * env-driven overrides to point at a different chain.
+ *
+ * Designed to surface, not paper over, real failures. Faucet cooldown is
+ * NOT retried; certification timeout is NOT swallowed. The expectation is
+ * that a fresh dev sees a green path on first run and a clear error
+ * message otherwise — never a hung "loading...".
+ */
+
+declare const DEFAULT_RPC_URL = "wss://materios.fluxpointstudios.com/rpc";
+declare const DEFAULT_GATEWAY_URL = "https://materios.fluxpointstudios.com/blobs";
+declare const DEFAULT_AGENT_ID = "orynq-quickstart";
+interface BootstrapAndTraceOptions {
+    /** Path to the on-disk identity (defaults to `~/.orynq/config.json`). */
+    configPath?: string | undefined;
+    /** Substrate WS RPC URL. Defaults to preprod. */
+    rpcUrl?: string | undefined;
+    /** Blob-gateway base URL (with or without /blobs suffix). */
+    gatewayBaseUrl?: string | undefined;
+    /** AgentId stamped on the trace bundle. */
+    agentId?: string | undefined;
+    /**
+     * One-liner observation stamped as the public event of the first trace.
+     * Defaults to a self-describing message that includes the env's wall
+     * clock, so the trace is identifiable on the explorer.
+     */
+    summary?: string | undefined;
+    /**
+     * Wait this long for the cert-daemon committee to certify the receipt.
+     * Defaults to 120 s. Set to 0 to skip the cert wait entirely (returns
+     * as soon as the receipt is on chain). On preprod the cert window is
+     * ~30-90 s depending on attestor load + finality gap; 120 s gives the
+     * happy path a comfortable margin without keeping the dev hanging.
+     */
+    certTimeoutMs?: number | undefined;
+    /**
+     * If true, a cert timeout is treated as success — the receipt is on
+     * chain, the explorer URL is printed, and the cert is just "still
+     * pending". Defaults to true so a fresh dev sees a working trace URL
+     * even when the committee is mid-vote.
+     */
+    treatCertTimeoutAsSuccess?: boolean | undefined;
+    /**
+     * Hook fired after each major step. Lets the CLI render a live status
+     * line without coupling business logic to console.log.
+     */
+    onProgress?: ((step: BootstrapStep) => void) | undefined;
+    /**
+     * If true, the faucet step is skipped — useful when the dev has
+     * pre-funded their address via Discord faucet, an existing wallet, etc.
+     * Defaults to false.
+     */
+    skipFaucet?: boolean | undefined;
+}
+type BootstrapStep = {
+    kind: "identity-loaded";
+    identity: OrynqIdentity;
+} | {
+    kind: "faucet-result";
+    result: FaucetDripResult;
+} | {
+    kind: "waiting-for-motra";
+} | {
+    kind: "motra-ready";
+    balance: bigint;
+} | {
+    kind: "trace-built";
+    bundle: TraceBundleLite;
+} | {
+    kind: "blob-uploaded";
+    contentHash: string;
+} | {
+    kind: "receipt-submitted";
+    receiptId: string;
+    blockHash: string;
+} | {
+    kind: "certified";
+    certHash: string;
+} | {
+    kind: "explorer-ready";
+    urls: ExplorerUrls;
+};
+interface BootstrapAndTraceResult {
+    identity: OrynqIdentity;
+    bundle: TraceBundleLite;
+    receiptId: string;
+    blockHash: string;
+    certHash?: string;
+    urls: ExplorerUrls;
+    /** Wall-clock duration from start of bootstrap to URLs available. */
+    elapsedMs: number;
+}
+/**
+ * Bootstrap a fresh dev to a chain-anchored first trace.
+ *
+ * Steps (each emits a progress event via `onProgress`):
+ *   1. load-or-create identity            ~50 ms
+ *   2. faucet drip (skipped if funded)    ~2 s
+ *   3. wait for MOTRA to generate         ~10-30 s (chain block production)
+ *   4. build local trace bundle           ~10 ms
+ *   5. upload blob + submit receipt       ~6 s (1 block)
+ *   6. await certification (optional)     ~10-30 s (committee voting)
+ *   7. compose explorer URLs              instant
+ *
+ * Total budget on a fresh address: 30-60 s wall-clock. With faucet skipped
+ * and MOTRA already in hand: <10 s.
+ */
+declare function bootstrapAndTrace(opts?: BootstrapAndTraceOptions): Promise<BootstrapAndTraceResult>;
+/**
+ * Standalone helper: spin up a `Keyring` from a mnemonic. Exposed so the
+ * CLI can re-derive an address from the saved config without pulling in
+ * the full bootstrap path.
+ */
+declare function deriveAddress(mnemonic: string, ss58Format?: number): Promise<string>;
+
+/**
+ * @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.
+ */
+
+declare const VERSION = "0.1.0";
+
+export { type BootstrapAndTraceOptions, type BootstrapAndTraceResult, type BootstrapStep, type BuildExplorerUrlsInput, DEFAULT_AGENT_ID, DEFAULT_GATEWAY_URL, DEFAULT_RPC_URL, type DeterministicHooks, type ExplorerUrls, type FaucetDripAlreadyFunded, type FaucetDripCooldown, type FaucetDripError, type FaucetDripResult, type FaucetDripSuccess, type FirstTraceBundleOptions, type LoadOrCreateIdentityOptions, type OrynqIdentity, type RequestFaucetOptions, type TraceBundleLite, VERSION, bootstrapAndTrace, buildExplorerUrls, defaultConfigPath, deriveAddress, firstTraceBundle, loadOrCreateIdentity, requestFaucet };