@ouronet/ouronet-core 4.3.6

package/dist/codex/codec.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Codex serialization / deserialization — the shared codec between
+ * OuronetUI's "Export Codex" button and any future consumer that reads
+ * the same backup JSON (HUB's codex-import flow, CLI recovery tools,
+ * etc.).
+ *
+ * The written format is now `CodexExportV1_3` — the `"version": "1.3"`
+ * string. This was an INTENTIONAL 1.2→1.3 bump made under strict
+ * reader-before-writer discipline: `deserializeCodex` was widened to
+ * accept BOTH "1.2" and "1.3" (and to allow-list the optional
+ * `foreignKeys` block) BEFORE this writer began stamping "1.3". That
+ * ordering is what makes the bump safe — every previously downloaded
+ * `OuronetCodex_*.json` (still "1.2") keeps importing, and every new
+ * export ("1.3") deserializes through the same reader.
+ *
+ * Do NOT revert the writer to "1.2" in isolation, and do NOT narrow the
+ * reader back to "1.2"-only: emitting a version the reader rejects (or
+ * rejecting the version the writer emits) is a funds-loss inversion — a
+ * user's own fresh backup would fail to restore. Any future format change
+ * must keep the reader ahead of the writer.
+ *
+ * All pure. No password handling in here — the BYTES INSIDE the JSON are
+ * already encrypted at the codex-entry level (each wallet's `secret` field
+ * is a V1 or V2 blob). Serializing the codex doesn't touch those blobs;
+ * it just wraps them in the portable envelope.
+ */
+import type { CodexExportV1_2, CodexExportV1_3, PlaintextCodex } from "./types.js";
+/**
+ * Build a codex-export payload from a PlaintextCodex. Stamps the current
+ * `"1.3"` envelope version and `exportedAt` with the current ISO time.
+ * Returns the object — the caller stringifies it (so callers in a
+ * memory-constrained environment can stream it out instead of holding the
+ * whole string in RAM).
+ *
+ * The return type is the `CodexExportV1_2 | CodexExportV1_3` union so
+ * consumers written against the historical 1.2 shape still type-check
+ * against the widened output; the runtime value is always a 1.3 envelope.
+ *
+ * The optional `foreignKeys` block is EMITTED only when the source codex
+ * carries foreign keys. ouronet's `PlaintextCodex` has no foreign-key
+ * source field today, so the practical output is a bare 1.3 envelope with
+ * `foreignKeys` omitted — no mandatory empty block.
+ *
+ * Fields left out intentionally: `pureKeypairs`, `schemaVersion`,
+ * `lastUpdatedAt`, `lastUpdatedDevice` — see CodexExportV1_3 JSDoc for
+ * the rationale (historical shape, device-local fields don't travel).
+ */
+export declare function buildCodexExport<KS, OA, PK, AB, UI>(codex: PlaintextCodex<KS, OA, PK, AB, UI>): CodexExportV1_2<KS, OA, AB, UI> | CodexExportV1_3<KS, OA, AB, UI>;
+/**
+ * Stringify a PlaintextCodex into the `"1.3"` backup JSON format, the
+ * exact output of OuronetUI's LocalStorageCodexAdapter.downloadAsJson.
+ * Pretty-prints with 2-space indent because the file lands on disk and
+ * a human occasionally opens it to sanity-check account addresses.
+ */
+export declare function serializeCodex<KS, OA, PK, AB, UI>(codex: PlaintextCodex<KS, OA, PK, AB, UI>): string;
+/**
+ * Parse a codex-export JSON string. Does NOT decrypt any enclosed blobs
+ * — the returned object's `kadenaWallets[i].secret` etc. are still V1/V2
+ * encrypted strings. Caller is responsible for decrypting them with the
+ * codex password once they've validated the parse.
+ *
+ * Throws on:
+ *   - invalid JSON
+ *   - missing `"version"` field (malformed)
+ *   - version mismatch (not `"1.2"`)
+ *   - shape mismatch (kadenaWallets, ouronetWallets, addressBook not arrays; uiSettings not an object)
+ *
+ * The version check exists to fail-fast rather than silently mis-decoding
+ * a future V2 export format. Callers that want best-effort partial reads
+ * can catch the throw and fall through to a recovery path.
+ *
+ * Shape-validation errors NAME the offending field but never echo its
+ * value — a codex envelope can carry encrypted secrets and account
+ * addresses, and surfacing those into telemetry/logs would breach the
+ * codec's information-disclosure boundary.
+ */
+export declare function deserializeCodex<KS = unknown, OA = unknown, AB = unknown, UI = unknown>(json: string): CodexExportV1_2<KS, OA, AB, UI>;

package/dist/codex/codec.js

@@ -0,0 +1,123 @@
+/**
+ * Codex serialization / deserialization — the shared codec between
+ * OuronetUI's "Export Codex" button and any future consumer that reads
+ * the same backup JSON (HUB's codex-import flow, CLI recovery tools,
+ * etc.).
+ *
+ * The written format is now `CodexExportV1_3` — the `"version": "1.3"`
+ * string. This was an INTENTIONAL 1.2→1.3 bump made under strict
+ * reader-before-writer discipline: `deserializeCodex` was widened to
+ * accept BOTH "1.2" and "1.3" (and to allow-list the optional
+ * `foreignKeys` block) BEFORE this writer began stamping "1.3". That
+ * ordering is what makes the bump safe — every previously downloaded
+ * `OuronetCodex_*.json` (still "1.2") keeps importing, and every new
+ * export ("1.3") deserializes through the same reader.
+ *
+ * Do NOT revert the writer to "1.2" in isolation, and do NOT narrow the
+ * reader back to "1.2"-only: emitting a version the reader rejects (or
+ * rejecting the version the writer emits) is a funds-loss inversion — a
+ * user's own fresh backup would fail to restore. Any future format change
+ * must keep the reader ahead of the writer.
+ *
+ * All pure. No password handling in here — the BYTES INSIDE the JSON are
+ * already encrypted at the codex-entry level (each wallet's `secret` field
+ * is a V1 or V2 blob). Serializing the codex doesn't touch those blobs;
+ * it just wraps them in the portable envelope.
+ */
+import { CodexUnknownFieldError } from "./errors.js";
+/**
+ * Build a codex-export payload from a PlaintextCodex. Stamps the current
+ * `"1.3"` envelope version and `exportedAt` with the current ISO time.
+ * Returns the object — the caller stringifies it (so callers in a
+ * memory-constrained environment can stream it out instead of holding the
+ * whole string in RAM).
+ *
+ * The return type is the `CodexExportV1_2 | CodexExportV1_3` union so
+ * consumers written against the historical 1.2 shape still type-check
+ * against the widened output; the runtime value is always a 1.3 envelope.
+ *
+ * The optional `foreignKeys` block is EMITTED only when the source codex
+ * carries foreign keys. ouronet's `PlaintextCodex` has no foreign-key
+ * source field today, so the practical output is a bare 1.3 envelope with
+ * `foreignKeys` omitted — no mandatory empty block.
+ *
+ * Fields left out intentionally: `pureKeypairs`, `schemaVersion`,
+ * `lastUpdatedAt`, `lastUpdatedDevice` — see CodexExportV1_3 JSDoc for
+ * the rationale (historical shape, device-local fields don't travel).
+ */
+export function buildCodexExport(codex) {
+    return {
+        version: "1.3",
+        exportedAt: new Date().toISOString(),
+        kadenaWallets: codex.kadenaWallets,
+        ouronetWallets: codex.ouronetWallets,
+        addressBook: codex.addressBook,
+        uiSettings: codex.uiSettings,
+    };
+}
+/**
+ * Stringify a PlaintextCodex into the `"1.3"` backup JSON format, the
+ * exact output of OuronetUI's LocalStorageCodexAdapter.downloadAsJson.
+ * Pretty-prints with 2-space indent because the file lands on disk and
+ * a human occasionally opens it to sanity-check account addresses.
+ */
+export function serializeCodex(codex) {
+    return JSON.stringify(buildCodexExport(codex), null, 2);
+}
+/**
+ * Parse a codex-export JSON string. Does NOT decrypt any enclosed blobs
+ * — the returned object's `kadenaWallets[i].secret` etc. are still V1/V2
+ * encrypted strings. Caller is responsible for decrypting them with the
+ * codex password once they've validated the parse.
+ *
+ * Throws on:
+ *   - invalid JSON
+ *   - missing `"version"` field (malformed)
+ *   - version mismatch (not `"1.2"`)
+ *   - shape mismatch (kadenaWallets, ouronetWallets, addressBook not arrays; uiSettings not an object)
+ *
+ * The version check exists to fail-fast rather than silently mis-decoding
+ * a future V2 export format. Callers that want best-effort partial reads
+ * can catch the throw and fall through to a recovery path.
+ *
+ * Shape-validation errors NAME the offending field but never echo its
+ * value — a codex envelope can carry encrypted secrets and account
+ * addresses, and surfacing those into telemetry/logs would breach the
+ * codec's information-disclosure boundary.
+ */
+export function deserializeCodex(json) {
+    const parsed = JSON.parse(json);
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error("deserializeCodex: not an object");
+    }
+    // Strict-equality membership only. No trim/normalize/prefix matching: a
+    // version string that merely LOOKS like an accepted one (" 1.3 ", "1.3.0",
+    // "1.3\n") must fail closed, so the reader never silently mis-decodes a
+    // format it doesn't actually understand.
+    const ACCEPTED_VERSIONS = new Set(["1.2", "1.3"]);
+    if (!ACCEPTED_VERSIONS.has(parsed.version)) {
+        throw new Error(`deserializeCodex: unsupported version ${String(parsed.version)} — expected "1.2" or "1.3"`);
+    }
+    const KNOWN_TOP_LEVEL_FIELDS = new Set([
+        "version", "exportedAt", "kadenaWallets", "ouronetWallets", "addressBook", "uiSettings", "foreignKeys",
+    ]);
+    const unknownFields = Object.keys(parsed).filter(k => !KNOWN_TOP_LEVEL_FIELDS.has(k));
+    if (unknownFields.length > 0) {
+        throw new CodexUnknownFieldError(`Codex envelope contains unknown top-level field(s): ${unknownFields.join(", ")}`);
+    }
+    if (!Array.isArray(parsed.kadenaWallets)) {
+        throw new Error("deserializeCodex: kadenaWallets must be an array");
+    }
+    if (!Array.isArray(parsed.ouronetWallets)) {
+        throw new Error("deserializeCodex: ouronetWallets must be an array");
+    }
+    if (!Array.isArray(parsed.addressBook)) {
+        throw new Error("deserializeCodex: addressBook must be an array");
+    }
+    if (typeof parsed.uiSettings !== "object" ||
+        parsed.uiSettings === null ||
+        Array.isArray(parsed.uiSettings)) {
+        throw new Error("deserializeCodex: uiSettings must be an object");
+    }
+    return parsed;
+}

package/dist/codex/errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Typed errors for codex validation. Covers strict-shape enforcement on
+ * deserialized codex payloads and seed-type migration input validation.
+ *
+ * Both classes follow the ES2022 Error.cause pattern mirroring WrongPasswordError
+ * in stoa-core/src/crypto/errors.ts. `this.name` is set explicitly so
+ * error-name-based branching works regardless of bundler minification.
+ */
+export declare class CodexUnknownFieldError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare class UnknownSeedTypeError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}

package/dist/codex/errors.js

@@ -0,0 +1,20 @@
+/**
+ * Typed errors for codex validation. Covers strict-shape enforcement on
+ * deserialized codex payloads and seed-type migration input validation.
+ *
+ * Both classes follow the ES2022 Error.cause pattern mirroring WrongPasswordError
+ * in stoa-core/src/crypto/errors.ts. `this.name` is set explicitly so
+ * error-name-based branching works regardless of bundler minification.
+ */
+export class CodexUnknownFieldError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "CodexUnknownFieldError";
+    }
+}
+export class UnknownSeedTypeError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "UnknownSeedTypeError";
+    }
+}

package/dist/codex/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @ouronet/ouronet-core/codex — portable Codex types + serialization
+ * codec + seed-type migration.
+ *
+ * Three small pieces that every codex consumer (OuronetUI, future HUB,
+ * any CLI/recovery tool) needs:
+ *
+ *   - `PlaintextCodex<...>` — generic in-memory shape. Consumer plugs
+ *     its own wallet/account/keypair types via the type params.
+ *   - `CodexExportV1_2` / `CodexExportV1_3` + `serializeCodex` /
+ *     `deserializeCodex` / `buildCodexExport` — the backup-JSON codec.
+ *     The writer now stamps `"1.3"`; the reader accepts both `"1.2"` and
+ *     `"1.3"` (reader-before-writer discipline — see codec.ts JSDoc).
+ *   - `SeedType` + `migrateSeedType` — the legacy↔canonical name
+ *     mapping, idempotent. Was inlined in OuronetUI's WalletStorage
+ *     before; lives here now so HUB doesn't have to rediscover it.
+ *
+ * Intentionally does NOT handle encryption. Each entry's `secret` field
+ * inside a codex is already an encrypted blob at rest; serializing /
+ * deserializing the codex doesn't touch those. For encryption see
+ * `@ouronet/ouronet-core/crypto`.
+ */
+export type { PlaintextCodex, CodexExportV1_2, CodexExportV1_3, CodexForeignKeyV1_3, CodexForeignKeysBlockV1_3, } from "./types.js";
+export { buildCodexExport, serializeCodex, deserializeCodex, } from "./codec.js";
+export type { SeedType, RawSeedType } from "./seedTypeMigration.js";
+export { migrateSeedType } from "./seedTypeMigration.js";
+export { CodexUnknownFieldError, UnknownSeedTypeError } from "./errors.js";

package/dist/codex/index.js

@@ -0,0 +1,25 @@
+/**
+ * @ouronet/ouronet-core/codex — portable Codex types + serialization
+ * codec + seed-type migration.
+ *
+ * Three small pieces that every codex consumer (OuronetUI, future HUB,
+ * any CLI/recovery tool) needs:
+ *
+ *   - `PlaintextCodex<...>` — generic in-memory shape. Consumer plugs
+ *     its own wallet/account/keypair types via the type params.
+ *   - `CodexExportV1_2` / `CodexExportV1_3` + `serializeCodex` /
+ *     `deserializeCodex` / `buildCodexExport` — the backup-JSON codec.
+ *     The writer now stamps `"1.3"`; the reader accepts both `"1.2"` and
+ *     `"1.3"` (reader-before-writer discipline — see codec.ts JSDoc).
+ *   - `SeedType` + `migrateSeedType` — the legacy↔canonical name
+ *     mapping, idempotent. Was inlined in OuronetUI's WalletStorage
+ *     before; lives here now so HUB doesn't have to rediscover it.
+ *
+ * Intentionally does NOT handle encryption. Each entry's `secret` field
+ * inside a codex is already an encrypted blob at rest; serializing /
+ * deserializing the codex doesn't touch those. For encryption see
+ * `@ouronet/ouronet-core/crypto`.
+ */
+export { buildCodexExport, serializeCodex, deserializeCodex, } from "./codec.js";
+export { migrateSeedType } from "./seedTypeMigration.js";
+export { CodexUnknownFieldError, UnknownSeedTypeError } from "./errors.js";

package/dist/codex/seedTypeMigration.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Seed-type migration — the naming layer between historical codex blobs
+ * and the current canonical names.
+ *
+ * Background. Early OuronetUI wallets were written with `seedType: "legacy"`
+ * (Chainweaver-derived WASM path) and `seedType: "new"` (Koala HD-wallet
+ * nacl path). When ecko-wallet landed the third variant got a clean name
+ * ("eckowallet"), but the existing "legacy" / "new" strings stayed live in
+ * users' localStorage. Rather than break those codexes we migrate on load:
+ * `legacy → chainweaver`, `new → koala`, everything else passes through.
+ *
+ * Canonical seed types are `"koala" | "chainweaver" | "eckowallet"`. The
+ * migration is idempotent — applying it twice yields the same result.
+ *
+ * Moved out of OuronetUI's WalletStorage in Phase 4. It had no business
+ * being there; it's a pure string-to-string mapping that every codex
+ * consumer (UI + future HUB) needs.
+ */
+import type { SeedType } from "@stoachain/stoa-core/wallet";
+export type { SeedType } from "@stoachain/stoa-core/wallet";
+/** The string you might find in a raw codex blob — includes legacy names. */
+export type RawSeedType = SeedType | "legacy" | "new" | string;
+/**
+ * Migrate a raw seed-type string from a v1.x codex into a canonical SeedType.
+ *
+ * Throws `UnknownSeedTypeError` if the input is not in the recognized migration
+ * map — strict-by-default contract per REQ-12 (F-BUG-010, v4.1.1). Replaces the
+ * pre-v4.1.1 silent `|| "koala"` fallback that could route unknown seed types
+ * through koala derivation, masking codex-import drift.
+ *
+ * @param rawType - The seed-type string from the v1.x codex envelope
+ * @returns Canonical SeedType ("koala" | "chainweaver" | "eckowallet")
+ * @throws UnknownSeedTypeError when rawType is not in SEED_TYPE_MIGRATION
+ */
+export declare function migrateSeedType(rawType: string): SeedType;

package/dist/codex/seedTypeMigration.js

@@ -0,0 +1,45 @@
+/**
+ * Seed-type migration — the naming layer between historical codex blobs
+ * and the current canonical names.
+ *
+ * Background. Early OuronetUI wallets were written with `seedType: "legacy"`
+ * (Chainweaver-derived WASM path) and `seedType: "new"` (Koala HD-wallet
+ * nacl path). When ecko-wallet landed the third variant got a clean name
+ * ("eckowallet"), but the existing "legacy" / "new" strings stayed live in
+ * users' localStorage. Rather than break those codexes we migrate on load:
+ * `legacy → chainweaver`, `new → koala`, everything else passes through.
+ *
+ * Canonical seed types are `"koala" | "chainweaver" | "eckowallet"`. The
+ * migration is idempotent — applying it twice yields the same result.
+ *
+ * Moved out of OuronetUI's WalletStorage in Phase 4. It had no business
+ * being there; it's a pure string-to-string mapping that every codex
+ * consumer (UI + future HUB) needs.
+ */
+import { UnknownSeedTypeError } from "./errors.js";
+const SEED_TYPE_MIGRATION = {
+    "legacy": "chainweaver",
+    "new": "koala",
+    "chainweaver": "chainweaver",
+    "koala": "koala",
+    "eckowallet": "eckowallet",
+};
+/**
+ * Migrate a raw seed-type string from a v1.x codex into a canonical SeedType.
+ *
+ * Throws `UnknownSeedTypeError` if the input is not in the recognized migration
+ * map — strict-by-default contract per REQ-12 (F-BUG-010, v4.1.1). Replaces the
+ * pre-v4.1.1 silent `|| "koala"` fallback that could route unknown seed types
+ * through koala derivation, masking codex-import drift.
+ *
+ * @param rawType - The seed-type string from the v1.x codex envelope
+ * @returns Canonical SeedType ("koala" | "chainweaver" | "eckowallet")
+ * @throws UnknownSeedTypeError when rawType is not in SEED_TYPE_MIGRATION
+ */
+export function migrateSeedType(rawType) {
+    const result = SEED_TYPE_MIGRATION[rawType];
+    if (result === undefined) {
+        throw new UnknownSeedTypeError(`Unknown seed type: "${rawType}". Expected one of: ${Object.keys(SEED_TYPE_MIGRATION).join(", ")}`);
+    }
+    return result;
+}

package/dist/codex/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * PlaintextCodex — the portable shape of an Ouronet user's in-memory
+ * codex state. Consumers decide the concrete element types for each list
+ * via generics (OuronetUI plugs in its IKadenaSeed / IOuroAccount / etc;
+ * the future HUB can supply its own if it prefers, or reuse UI's via a
+ * shared `@ouronet/shared-types` package later).
+ *
+ * Why generic? Because the codec (serialize / deserialize) and any other
+ * core-side consumer only cares about the SHAPE — "there are N wallets,
+ * M accounts, K pure keypairs, an address book, and some ui settings".
+ * The field contents are consumer-defined. Generics let the type carry
+ * information without forcing core to own every wallet-domain type.
+ *
+ * Default type params are `unknown` so downstream code that doesn't need
+ * field-level types still works — `PlaintextCodex` with no args treats
+ * each list as `unknown[]`, which TypeScript allows assignment TO but
+ * nothing structured FROM (exactly right for a generic serializer).
+ */
+export interface PlaintextCodex<KadenaSeed = unknown, OuroAccount = unknown, PureKeypair = unknown, AddressBookEntry = unknown, UiSettings = unknown> {
+    /** HD seeds (koala / chainweaver / eckowallet variants) known to this codex. */
+    readonly kadenaWallets: KadenaSeed[];
+    /** Resident OURO accounts the user controls. */
+    readonly ouronetWallets: OuroAccount[];
+    /** Address-book entries (cached or user-added). */
+    readonly addressBook: AddressBookEntry[];
+    /** Raw pure Pact keypairs stored directly (encrypted privateKey). */
+    readonly pureKeypairs: PureKeypair[];
+    /** Non-sensitive UI preferences (dock position, zone state, etc). */
+    readonly uiSettings: UiSettings;
+    /**
+     * Schema version of this codex. `0` = pre-upgrade V1-encrypted; `1+` =
+     * post-upgrade V2-encrypted. Consumers can read this to decide whether
+     * to run the encryption upgrade on unlock.
+     */
+    readonly schemaVersion: number;
+    /** ISO timestamp of the last write to this codex (across any device). */
+    readonly lastUpdatedAt: string | null;
+    /** Which device family last wrote — used for dev/main cross-sync UX. */
+    readonly lastUpdatedDevice: "dev" | "main";
+}
+/**
+ * The exported-backup JSON shape (`version: "1.2"` — the historical string
+ * that OuronetUI has written since well before the extraction began).
+ *
+ * A codex backup is a subset of PlaintextCodex: no schemaVersion /
+ * lastUpdatedAt / lastUpdatedDevice (those are device-local), and no
+ * pureKeypairs in this historical shape (they ship inside `cloud-backup`
+ * alongside user settings — see the `downloadAsJson` → `exportForCloud`
+ * split in OuronetUI's LocalStorageCodexAdapter). The `"1.2"` label
+ * stays because a bump would break every existing user's recovery file.
+ */
+export interface CodexExportV1_2<KadenaSeed = unknown, OuroAccount = unknown, AddressBookEntry = unknown, UiSettings = unknown> {
+    readonly version: "1.2";
+    readonly exportedAt: string;
+    readonly kadenaWallets: KadenaSeed[];
+    readonly ouronetWallets: OuroAccount[];
+    readonly addressBook: AddressBookEntry[];
+    readonly uiSettings: UiSettings;
+}
+/**
+ * A single foreign (cross-chain) key entry inside a `foreignKeys` block. The
+ * `encryptedKeyfile` is already-encrypted at rest — this envelope only carries
+ * the ciphertext, never a plaintext key.
+ *
+ * This mirrors the codex-core (`@ancientpantheon`) V1_3 foreign-key shape by
+ * VALUE, not by import: the two orgs share no dependency edge, so the shape is
+ * an intentionally-duplicated peer kept structurally identical by hand.
+ */
+export interface CodexForeignKeyV1_3 {
+    readonly id: string;
+    readonly label?: string;
+    readonly chainId: string;
+    readonly encryptedKeyfile: string;
+}
+/** The optional `foreignKeys` block on a 1.3 envelope. */
+export interface CodexForeignKeysBlockV1_3 {
+    readonly schemaVersion: 1;
+    readonly keys: readonly CodexForeignKeyV1_3[];
+}
+/**
+ * The exported-backup JSON shape at `version: "1.3"`. Structurally identical to
+ * `CodexExportV1_2` except for the version literal and an OPTIONAL `foreignKeys`
+ * block. The bump was made under reader-before-writer discipline: the reader
+ * (`deserializeCodex`) was widened to accept "1.3" and to allow-list the
+ * `foreignKeys` field BEFORE the writer began stamping "1.3".
+ *
+ * ouronet's `PlaintextCodex` has no foreign-key source field, so the live
+ * writer emits `foreignKeys`-ABSENT (a bare 1.3 envelope). The block is typed
+ * as optional so the writer can emit it if a source is ever wired up, without a
+ * mandatory empty-block lie on every export.
+ */
+export interface CodexExportV1_3<KadenaSeed = unknown, OuroAccount = unknown, AddressBookEntry = unknown, UiSettings = unknown> {
+    readonly version: "1.3";
+    readonly exportedAt: string;
+    readonly kadenaWallets: KadenaSeed[];
+    readonly ouronetWallets: OuroAccount[];
+    readonly addressBook: AddressBookEntry[];
+    readonly uiSettings: UiSettings;
+    readonly foreignKeys?: CodexForeignKeysBlockV1_3;
+}

package/dist/codex/types.js

@@ -0,0 +1,19 @@
+/**
+ * PlaintextCodex — the portable shape of an Ouronet user's in-memory
+ * codex state. Consumers decide the concrete element types for each list
+ * via generics (OuronetUI plugs in its IKadenaSeed / IOuroAccount / etc;
+ * the future HUB can supply its own if it prefers, or reuse UI's via a
+ * shared `@ouronet/shared-types` package later).
+ *
+ * Why generic? Because the codec (serialize / deserialize) and any other
+ * core-side consumer only cares about the SHAPE — "there are N wallets,
+ * M accounts, K pure keypairs, an address book, and some ui settings".
+ * The field contents are consumer-defined. Generics let the type carry
+ * information without forcing core to own every wallet-domain type.
+ *
+ * Default type params are `unknown` so downstream code that doesn't need
+ * field-level types still works — `PlaintextCodex` with no args treats
+ * each list as `unknown[]`, which TypeScript allows assignment TO but
+ * nothing structured FROM (exactly right for a generic serializer).
+ */
+export {};

package/dist/constants/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./ouronet.js";
+export * from "./tokenIds.js";

package/dist/constants/index.js

@@ -0,0 +1,3 @@
+// @ouronet/ouronet-core/constants
+export * from "./ouronet.js";
+export * from "./tokenIds.js";

package/dist/constants/ouronet.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Ouronet-specific protocol constants — the `ouronet-ns` Pact namespace,
+ * the protocol-level autonomic accounts, the canonical token list.
+ *
+ * Lives in `@ouronet/ouronet-core/constants`. Pulled in by every
+ * `interactions/*` file that constructs `${KADENA_NAMESPACE}.<module>.*`
+ * Pact code, plus by the cfmBuilders Pact-code string assembler.
+ *
+ * Chain-generic constants (`KADENA_NETWORK`, `KADENA_CHAIN_ID`,
+ * `getPactUrl`, `getSpvUrl`, `STOA_CHAIN_COUNT`, `STOA_CHAINS`,
+ * `KADENA_CHAINS`) live in `@stoachain/stoa-core/constants` — they're
+ * re-exported here for backwards-compatibility with internal imports
+ * from `../constants` and pre-v4 consumer imports from
+ * `@ouronet/ouronet-core/constants`. Public-API consumers SHOULD
+ * import them from `@stoachain/stoa-core/constants` directly to make
+ * the chain-generic vs Ouronet-specific boundary explicit.
+ */
+export { KADENA_NETWORK, KADENA_CHAIN_ID, STOA_CHAIN_COUNT, STOA_CHAINS, KADENA_CHAINS, getPactUrl, getSpvUrl, } from "@stoachain/stoa-core/constants";
+/**
+ * The Pact module namespace prefix for every Ouronet smart contract.
+ * Every interaction file builds Pact code as `${KADENA_NAMESPACE}.<module>.*`.
+ */
+export declare const KADENA_NAMESPACE = "ouronet-ns";
+/** Ouroboros protocol account (staking/rewards engine) */
+export declare const STOA_AUTONOMIC_OUROBOROS = "c:XM-pkmuB5XUQlp87ZYSbfKt8qzmHY6O2EHAzMRVBt3k";
+/** LiquidPot account (native STOA vault — source of unwrapped tokens) */
+export declare const STOA_AUTONOMIC_LIQUIDPOT = "c:ZNfuj3iZI83n7MUSKGuoXoSxFg1cyMxCzB3szUHVvrI";
+/** Ouronet Gas Station (pays Kadena gas fees for all transactions) */
+export declare const STOA_AUTONOMIC_OURONETGASSTATION = "c:iQQFWj6gWtpGEzhM_O5ekW1QtnQQy55R8BRPGhj_0FU";
+export declare const MAIN_TOKENS: {
+    id: string;
+    name: string;
+}[];

package/dist/constants/ouronet.js

@@ -0,0 +1,59 @@
+/**
+ * Ouronet-specific protocol constants — the `ouronet-ns` Pact namespace,
+ * the protocol-level autonomic accounts, the canonical token list.
+ *
+ * Lives in `@ouronet/ouronet-core/constants`. Pulled in by every
+ * `interactions/*` file that constructs `${KADENA_NAMESPACE}.<module>.*`
+ * Pact code, plus by the cfmBuilders Pact-code string assembler.
+ *
+ * Chain-generic constants (`KADENA_NETWORK`, `KADENA_CHAIN_ID`,
+ * `getPactUrl`, `getSpvUrl`, `STOA_CHAIN_COUNT`, `STOA_CHAINS`,
+ * `KADENA_CHAINS`) live in `@stoachain/stoa-core/constants` — they're
+ * re-exported here for backwards-compatibility with internal imports
+ * from `../constants` and pre-v4 consumer imports from
+ * `@ouronet/ouronet-core/constants`. Public-API consumers SHOULD
+ * import them from `@stoachain/stoa-core/constants` directly to make
+ * the chain-generic vs Ouronet-specific boundary explicit.
+ */
+// Chain-generic re-exports (canonical home: @stoachain/stoa-core/constants)
+export { KADENA_NETWORK, KADENA_CHAIN_ID, STOA_CHAIN_COUNT, STOA_CHAINS, KADENA_CHAINS, getPactUrl, getSpvUrl, } from "@stoachain/stoa-core/constants";
+/**
+ * The Pact module namespace prefix for every Ouronet smart contract.
+ * Every interaction file builds Pact code as `${KADENA_NAMESPACE}.<module>.*`.
+ */
+export const KADENA_NAMESPACE = "ouronet-ns";
+// ─── Stoa Autonomic Accounts ───────────────────────────────────────────────
+// Canonical names for all protocol-level Stoa accounts.
+// Always reference these — never hardcode the address strings directly.
+/** Ouroboros protocol account (staking/rewards engine) */
+export const STOA_AUTONOMIC_OUROBOROS = "c:XM-pkmuB5XUQlp87ZYSbfKt8qzmHY6O2EHAzMRVBt3k";
+/** LiquidPot account (native STOA vault — source of unwrapped tokens) */
+export const STOA_AUTONOMIC_LIQUIDPOT = "c:ZNfuj3iZI83n7MUSKGuoXoSxFg1cyMxCzB3szUHVvrI";
+/** Ouronet Gas Station (pays Kadena gas fees for all transactions) */
+export const STOA_AUTONOMIC_OURONETGASSTATION = "c:iQQFWj6gWtpGEzhM_O5ekW1QtnQQy55R8BRPGhj_0FU";
+// v4.0.0: removed deprecated aliases.
+//   - `KADENA_BASE_URL` and `PACT_URL` (pinned to node2; use the failover
+//     accessors `getPactUrl(chainId)` / `getSpvUrl(chainId)` from
+//     `@stoachain/stoa-core/constants` instead — they delegate to the
+//     v2.1.0 failover layer)
+//   - `GAS_STATION` and `NATIVE_TOKEN_VAULT` (use the canonical
+//     `STOA_AUTONOMIC_*` names above directly).
+export const MAIN_TOKENS = [
+    { id: "AURYN-8Nh-JO8JO4F5", name: "AURYN" },
+    {
+        id: "ELITEAURYN-8Nh-JO8JO4F5",
+        name: "ELITEAURYN",
+    },
+    {
+        id: "SSTOA-8Nh-JO8JO4F5",
+        name: "SSTOA",
+    },
+    {
+        id: "OURO-8Nh-JO8JO4F5",
+        name: "OURO",
+    },
+    {
+        id: "VST-8Nh-JO8JO4F5",
+        name: "VST",
+    },
+];

package/dist/constants/tokenIds.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Ouronet DPTF token IDs — global constants.
+ * All share the same suffix: -8Nh-JO8JO4F5
+ */
+export declare const TOKEN_ID_OURO = "OURO-8Nh-JO8JO4F5";
+export declare const TOKEN_ID_IGNIS = "GAS-8Nh-JO8JO4F5";
+export declare const TOKEN_ID_AURYN = "AURYN-8Nh-JO8JO4F5";
+export declare const TOKEN_ID_ELITEAURYN = "ELITEAURYN-8Nh-JO8JO4F5";
+export declare const TOKEN_ID_WSTOA = "WSTOA-8Nh-JO8JO4F5";
+export declare const TOKEN_ID_SSTOA = "SSTOA-8Nh-JO8JO4F5";
+export declare const TOKEN_ID_GSTOA = "GSTOA-8Nh-JO8JO4F5";
+/** Ordered array — same order as primordials tokens[] */
+export declare const ALL_TOKEN_IDS: readonly ["OURO-8Nh-JO8JO4F5", "GAS-8Nh-JO8JO4F5", "AURYN-8Nh-JO8JO4F5", "ELITEAURYN-8Nh-JO8JO4F5", "WSTOA-8Nh-JO8JO4F5", "SSTOA-8Nh-JO8JO4F5", "GSTOA-8Nh-JO8JO4F5"];

package/dist/constants/tokenIds.js

@@ -0,0 +1,21 @@
+/**
+ * Ouronet DPTF token IDs — global constants.
+ * All share the same suffix: -8Nh-JO8JO4F5
+ */
+export const TOKEN_ID_OURO = "OURO-8Nh-JO8JO4F5";
+export const TOKEN_ID_IGNIS = "GAS-8Nh-JO8JO4F5";
+export const TOKEN_ID_AURYN = "AURYN-8Nh-JO8JO4F5";
+export const TOKEN_ID_ELITEAURYN = "ELITEAURYN-8Nh-JO8JO4F5";
+export const TOKEN_ID_WSTOA = "WSTOA-8Nh-JO8JO4F5";
+export const TOKEN_ID_SSTOA = "SSTOA-8Nh-JO8JO4F5";
+export const TOKEN_ID_GSTOA = "GSTOA-8Nh-JO8JO4F5";
+/** Ordered array — same order as primordials tokens[] */
+export const ALL_TOKEN_IDS = [
+    TOKEN_ID_OURO,
+    TOKEN_ID_IGNIS,
+    TOKEN_ID_AURYN,
+    TOKEN_ID_ELITEAURYN,
+    TOKEN_ID_WSTOA,
+    TOKEN_ID_SSTOA,
+    TOKEN_ID_GSTOA,
+];

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@ouronet/ouronet-core` — Ouronet protocol business logic on top of
+ * `@stoachain/stoa-core`.
+ *
+ * This root entry is intentionally near-empty. Consumers MUST reach
+ * the domain layers through subpath exports, which the package.json
+ * `exports` field enumerates:
+ *
+ *   import { ... } from "@ouronet/ouronet-core/codex";
+ *   import { ... } from "@ouronet/ouronet-core/interactions";
+ *   import { COIL_CONFIGS } from "@ouronet/ouronet-core/interactions/coilFunctions";
+ *   // ... etc.
+ *
+ * Chain-generic infrastructure (signing, wallet, crypto, network, gas,
+ * guard, reads, observability, dalos, errors) lives in
+ * `@stoachain/stoa-core` and is consumed via its subpaths.
+ */
+export {};