wative-core 2.4.0 → 2.4.2

package/dist/{svm-Ca4Xyw0Y.d.ts → svm-B51NevS8.d.ts}

@@ -1,4 +1,4 @@
-import { c as Address, G as SvmTxBuildParams, F as SvmTransaction } from './workspace-DdaY7sWa.js';
+import { c as Address, G as SvmTxBuildParams, F as SvmTransaction } from './workspace-CBxKR80D.js';
 
 interface SvmInstruction {
     readonly programId: string;

package/dist/{svm-B_c0L-rJ.d.cts → svm-DswX6XRv.d.cts}

@@ -1,4 +1,4 @@
-import { c as Address, G as SvmTxBuildParams, F as SvmTransaction } from './workspace-DdaY7sWa.cjs';
+import { c as Address, G as SvmTxBuildParams, F as SvmTransaction } from './workspace-CBxKR80D.cjs';
 
 interface SvmInstruction {
     readonly programId: string;

package/dist/{workspace-DdaY7sWa.d.cts → workspace-CBxKR80D.d.cts}

@@ -118,7 +118,7 @@ interface Settling<T> {
 }
 
 type RecordType = "CONFIG" | "ACCOUNTS" | "NETWORK" | "ASSET" | "LOG";
-
+/** Pre-unlock structural state of a provider's container — see `Provider.inspectContainer`. */
 type ContainerState = "empty" | "workspace" | "foreign";
 interface RecordInit<T> {
     readonly provider: Provider;
@@ -128,7 +128,11 @@ interface RecordInit<T> {
     readonly password?: string;
     readonly decrypt?: (ciphertext: Uint8Array, password: string) => Uint8Array;
     readonly persist?: (value: T, password: string) => Promise<void>;
-    
+    /**
+     * Throws if the session that issued this record has ended. Supplied by
+     * providers that HAVE a session; a provider without one omits it and the
+     * record behaves as before.
+     */
     readonly requireLiveSession?: () => void;
 }
 declare class Record$1<T> {
@@ -138,9 +142,19 @@ declare class Record$1<T> {
     constructor(slug: Slug, path: string, init?: RecordInit<T>);
     get locked(): boolean;
     get value(): T;
-    
+    /**
+     * Pure CPU — decrypts the in-memory blob. Sync.
+     *
+     * BAD_PASSWORD means the password is wrong: an AES-GCM auth-tag mismatch on
+     * the locked path, or a mismatch against the password that opened the record
+     * on the unlocked one. DECRYPT_FAILED means the record cannot answer —
+     * structural damage or corruption on the locked path, and on the unlocked
+     * path a record carrying neither a password nor ciphertext, which has nothing
+     * to verify against. Callers can still read the two apart as "wrong password"
+     * versus "cannot be checked".
+     */
     unlock(password: string): this;
-    
+    /** Persists changes via the owning Provider. */
     save(): Promise<void>;
 }
 declare abstract class Provider {
@@ -156,15 +170,38 @@ declare abstract class Provider {
     abstract unlockContainer(password: string): Promise<boolean>;
     abstract lockContainer(): Promise<void>;
     abstract isContainerUnlocked(): boolean;
-    
+    /**
+     * Structural inspection of the container BEFORE unlock. `Workspace.open()`
+     * uses it to auto-select create-vs-open without a `create` flag:
+     *   - `"empty"`     — no container yet; safe to initialize a new workspace.
+     *   - `"workspace"` — an existing wative workspace; open it.
+     *   - `"foreign"`   — non-empty storage that is NOT a wative workspace; `open()`
+     *                     refuses rather than scaffolding a workspace into it.
+     * The base default returns `"workspace"` (proceed as open-or-create, no guard),
+     * so existing custom providers are unaffected. Providers that can cheaply
+     * inspect their storage — e.g. `HybridProvider` on a filesystem — override this
+     * to detect `"foreign"` and stop a mistyped path from creating a workspace
+     * inside unrelated data.
+     */
     inspectContainer(): Promise<ContainerState>;
     abstract loadRecord<T>(type: RecordType, slug?: Slug): Promise<Record$1<T>>;
     abstract loadRecords<T>(type: RecordType): Promise<ReadonlyArray<Record$1<T>>>;
     abstract writeRecord<T>(type: RecordType, slug: Slug, value: T): Promise<void>;
     abstract dropRecord(type: RecordType, slug: Slug): Promise<void>;
-    
+    /**
+     * Initialize an empty container by writing the four root records
+     * (CONFIG, NETWORK, ASSET, LOG) from the bundled template files at
+     * `src/workspace_template/`. Idempotent: existing records are left
+     * untouched. The ACCOUNTS namespace is left empty — per-account records
+     * are created lazily by `accounts.create(...)`.
+     *
+     * Subclasses inherit this default; override only if a backend needs
+     * non-record initialization (e.g. allocating a database schema).
+     */
     initialize(): Promise<void>;
-    
+    /** Any storage at all under the accounts area, however named. Defaults to
+     *  "nothing", so a provider that does not implement it can only fail to add a
+     *  refusal reason — never cause one. */
     protected _hasRawAccountData(): Promise<boolean>;
     abstract close(): Promise<void>;
 }
@@ -314,8 +351,8 @@ declare class EvmTransaction implements Transaction {
         }>;
         address?: Address;
     });
-    constructor(from: EvmAddress, to: string, value: bigint, data?: string, opts?: {
-        chainId?: ChainId;
+    constructor(from: EvmAddress, to: string, value: bigint, data: string | undefined, opts: {
+        chainId: ChainId;
         type?: EvmTxType;
         nonce?: number;
         gasPrice?: bigint;
@@ -585,7 +622,8 @@ declare class Account {
         after: number;
         dropped: number;
     }>;
-    importPrivateKey(pk: string, vm: ChainVM): Promise<Wallet>;
+    
+    importPrivateKey(pk: string, vm?: ChainVM): Promise<Wallet>;
     drop(): Promise<void>;
     
     filterAddress(network: NetworkLike, addr?: string): Address | null;

package/dist/{workspace-DdaY7sWa.d.ts → workspace-CBxKR80D.d.ts}

@@ -118,7 +118,7 @@ interface Settling<T> {
 }
 
 type RecordType = "CONFIG" | "ACCOUNTS" | "NETWORK" | "ASSET" | "LOG";
-
+/** Pre-unlock structural state of a provider's container — see `Provider.inspectContainer`. */
 type ContainerState = "empty" | "workspace" | "foreign";
 interface RecordInit<T> {
     readonly provider: Provider;
@@ -128,7 +128,11 @@ interface RecordInit<T> {
     readonly password?: string;
     readonly decrypt?: (ciphertext: Uint8Array, password: string) => Uint8Array;
     readonly persist?: (value: T, password: string) => Promise<void>;
-    
+    /**
+     * Throws if the session that issued this record has ended. Supplied by
+     * providers that HAVE a session; a provider without one omits it and the
+     * record behaves as before.
+     */
     readonly requireLiveSession?: () => void;
 }
 declare class Record$1<T> {
@@ -138,9 +142,19 @@ declare class Record$1<T> {
     constructor(slug: Slug, path: string, init?: RecordInit<T>);
     get locked(): boolean;
     get value(): T;
-    
+    /**
+     * Pure CPU — decrypts the in-memory blob. Sync.
+     *
+     * BAD_PASSWORD means the password is wrong: an AES-GCM auth-tag mismatch on
+     * the locked path, or a mismatch against the password that opened the record
+     * on the unlocked one. DECRYPT_FAILED means the record cannot answer —
+     * structural damage or corruption on the locked path, and on the unlocked
+     * path a record carrying neither a password nor ciphertext, which has nothing
+     * to verify against. Callers can still read the two apart as "wrong password"
+     * versus "cannot be checked".
+     */
     unlock(password: string): this;
-    
+    /** Persists changes via the owning Provider. */
     save(): Promise<void>;
 }
 declare abstract class Provider {
@@ -156,15 +170,38 @@ declare abstract class Provider {
     abstract unlockContainer(password: string): Promise<boolean>;
     abstract lockContainer(): Promise<void>;
     abstract isContainerUnlocked(): boolean;
-    
+    /**
+     * Structural inspection of the container BEFORE unlock. `Workspace.open()`
+     * uses it to auto-select create-vs-open without a `create` flag:
+     *   - `"empty"`     — no container yet; safe to initialize a new workspace.
+     *   - `"workspace"` — an existing wative workspace; open it.
+     *   - `"foreign"`   — non-empty storage that is NOT a wative workspace; `open()`
+     *                     refuses rather than scaffolding a workspace into it.
+     * The base default returns `"workspace"` (proceed as open-or-create, no guard),
+     * so existing custom providers are unaffected. Providers that can cheaply
+     * inspect their storage — e.g. `HybridProvider` on a filesystem — override this
+     * to detect `"foreign"` and stop a mistyped path from creating a workspace
+     * inside unrelated data.
+     */
     inspectContainer(): Promise<ContainerState>;
     abstract loadRecord<T>(type: RecordType, slug?: Slug): Promise<Record$1<T>>;
     abstract loadRecords<T>(type: RecordType): Promise<ReadonlyArray<Record$1<T>>>;
     abstract writeRecord<T>(type: RecordType, slug: Slug, value: T): Promise<void>;
     abstract dropRecord(type: RecordType, slug: Slug): Promise<void>;
-    
+    /**
+     * Initialize an empty container by writing the four root records
+     * (CONFIG, NETWORK, ASSET, LOG) from the bundled template files at
+     * `src/workspace_template/`. Idempotent: existing records are left
+     * untouched. The ACCOUNTS namespace is left empty — per-account records
+     * are created lazily by `accounts.create(...)`.
+     *
+     * Subclasses inherit this default; override only if a backend needs
+     * non-record initialization (e.g. allocating a database schema).
+     */
     initialize(): Promise<void>;
-    
+    /** Any storage at all under the accounts area, however named. Defaults to
+     *  "nothing", so a provider that does not implement it can only fail to add a
+     *  refusal reason — never cause one. */
     protected _hasRawAccountData(): Promise<boolean>;
     abstract close(): Promise<void>;
 }
@@ -314,8 +351,8 @@ declare class EvmTransaction implements Transaction {
         }>;
         address?: Address;
     });
-    constructor(from: EvmAddress, to: string, value: bigint, data?: string, opts?: {
-        chainId?: ChainId;
+    constructor(from: EvmAddress, to: string, value: bigint, data: string | undefined, opts: {
+        chainId: ChainId;
         type?: EvmTxType;
         nonce?: number;
         gasPrice?: bigint;
@@ -585,7 +622,8 @@ declare class Account {
         after: number;
         dropped: number;
     }>;
-    importPrivateKey(pk: string, vm: ChainVM): Promise<Wallet>;
+    
+    importPrivateKey(pk: string, vm?: ChainVM): Promise<Wallet>;
     drop(): Promise<void>;
     
     filterAddress(network: NetworkLike, addr?: string): Address | null;

package/examples/03-pk-account.test.cjs

@@ -1,4 +1,18 @@
 // 03 — PK account flows. Heterogeneous private keys, one wallet per import.
+//
+// Two things worth noticing as you read:
+//
+//   * `vm` is optional. The key formats do not overlap — 64 hex characters for
+//     EVM, 80–96 base58 (or a solana-keygen JSON array) for Solana — so the
+//     chain is read off the key. Pass it anyway when you want the mismatch to
+//     be an error rather than an inference.
+//
+//   * One import gives you TWO addresses. The key signs on its own chain, and
+//     the same 32 secret bytes seed a keypair on the other one, so the wallet
+//     has an address on both. The chain you imported for stays first.
+//     ⚠️ One secret controls both addresses. That is different from an HD
+//     account, where a slot's two addresses come from two derivation paths and
+//     are independent keys.
 
 const test = require("node:test");
 const assert = require("node:assert");
@@ -10,6 +24,16 @@ const { Workspace } = require("wative-core");
 
 const EVM_PK = "0x4f3edf983ac636a65a842ce7c78d9aa706d3b113bce9c46f30d7d21715b23b1d";
 const SVM_PK = "xtGWcHvQsr5ue8zG2F5fm31bW8vyn597Y92gUWaZZg3S1Z6FeJMATL8KU3xJMGbLfALnokcct9y5wYtCRrwNXZW";
+// A second Solana key, base58 of its 64-byte secret key.
+const SVM_PK_2 = "gaiC7Rnf9J6tV3SGwJyzvMDdz9RMmreSWZDyDK682MUKZHaWdZbbqgf35qD7FSwXka2Rf2o4MuhbWQTg82W9mbV";
+// A third, in the shape `solana-keygen` writes: the 64 secret-key bytes as
+// JSON. This is literally the contents of ~/.config/solana/id.json.
+const SVM_KEYGEN_BYTES = [
+  51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51,
+  51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51,
+  23, 203, 121, 251, 43, 65, 32, 242, 177, 236, 101, 228, 25, 141, 110, 8,
+  178, 142, 129, 63, 235, 1, 228, 164, 0, 131, 155, 133, 225, 128, 128, 206,
+];
 
 test("PK account — create from EVM key + import a Solana key", async () => {
   const root = mkdtempSync(join(tmpdir(), "wative-pk-"));
@@ -24,11 +48,52 @@ test("PK account — create from EVM key + import a Solana key", async () => {
   );
   assert.strictEqual(acc.organizationType, "PK");
   assert.strictEqual(acc.wallets.length, 1);
+  // The chain the key is for comes first; its sibling follows.
   assert.strictEqual(acc.wallets[0].addresses[0].vm, "evm");
+  assert.strictEqual(acc.wallets[0].addresses[1].vm, "svm");
 
   await acc.importPrivateKey(SVM_PK, "svm");
   assert.strictEqual(acc.wallets.length, 2);
   assert.strictEqual(acc.wallets[1].addresses[0].vm, "svm");
+  assert.strictEqual(acc.wallets[1].addresses[1].vm, "evm");
+
+  await ws.lock();
+});
+
+// The three ways you are likely to be holding a private key, and what each
+// one does without being told which chain it belongs to.
+test("PK account — the key formats importPrivateKey accepts", async () => {
+  const root = mkdtempSync(join(tmpdir(), "wative-pk-fmt-"));
+  const ws = await Workspace.open({ path: root, password: "wsp-pwd" });
+  const acc = await ws.accounts.create("Formats", "wsp-pwd", EVM_PK, undefined, { kind: "PK" });
+
+  // 1. EVM: 32 bytes of hex, 0x-prefix optional. No vm argument needed.
+  const evm = await acc.importPrivateKey(
+    "0x6cbed15c793ce57650b9877cf6fa156fbef513c4e6134f022a85b1ffdd59b2a1",
+  );
+  assert.strictEqual(evm.addresses[0].vm, "evm");
+
+  // 2. Solana: base58 of the 64-byte secret key.
+  const svm = await acc.importPrivateKey(SVM_PK_2);
+  assert.strictEqual(svm.addresses[0].vm, "svm");
+
+  // 3. Solana: the JSON byte array `solana-keygen` writes to id.json. This is
+  //    what you get from `cat ~/.config/solana/id.json`, usable as-is.
+  const fromKeygen = await acc.importPrivateKey(JSON.stringify(SVM_KEYGEN_BYTES));
+  assert.strictEqual(fromKeygen.addresses[0].vm, "svm");
+
+  // A value that is neither is refused rather than guessed at.
+  await assert.rejects(
+    acc.importPrivateKey("definitely-not-a-key"),
+    (err) => err.code === "INVALID_PRIVATE_KEY",
+  );
+
+  // So is 32 bytes of hex that is not a valid secp256k1 scalar — being the
+  // right length is not the same as being a key.
+  await assert.rejects(
+    acc.importPrivateKey("0x" + "0".repeat(64), "evm"),
+    (err) => err.code === "INVALID_PRIVATE_KEY",
+  );
 
   await ws.lock();
 });

package/examples/15-package-resolution.test.cjs

@@ -1,7 +1,7 @@
-// 15 — Package resolution. Every other example imports `../dist/index.cjs`
-// directly, which bypasses the `exports` map in package.json entirely. This
-// file is the only one that resolves the package the way a real consumer does:
-// by its bare name. It therefore covers the export conditions (`import` vs
+// 15 — Package resolution. Every example now resolves the package by its bare
+// name, so they all exercise the `exports` map; this file is the one that tests
+// the map ITSELF rather than using it incidentally — every declared subpath,
+// under both conditions. It therefore covers the export conditions (`import` vs
 // `require`), the declared subpaths, and the parity between the two builds.
 //
 // It works without installing anything because Node resolves a package's own

package/examples/19-simple-provider.test.cjs

@@ -0,0 +1,134 @@
+// 19 — The SHORT way to write a storage backend.
+//
+// Example 07 extends `Provider` and implements the record layer by hand, which
+// is what you want when the storage system already has its own encryption or
+// its own idea of a record. Most of the time you want this instead: extend
+// `ContainerProvider` and implement six methods that move bytes around. It
+// supplies the container session, the record API and all the encryption, so a
+// working backend is about twenty lines.
+//
+// The store here is a plain Map with no persistence and no cleverness — the
+// point is how little you have to write, not the store itself.
+
+const test = require("node:test");
+const assert = require("node:assert");
+
+const { Workspace, ContainerProvider, WativeError } = require("wative-core");
+
+/** A whole storage backend. Keys are strings, values are bytes. */
+class MapProvider extends ContainerProvider {
+  #store = new Map();
+  #dirs = new Set([""]);
+
+  _exist(path) {
+    // A directory "exists" if anything sits under it — the library asks about
+    // both files and directories through this one method.
+    if (this.#store.has(path) || this.#dirs.has(path)) return true;
+    const prefix = path.endsWith("/") ? path : path + "/";
+    for (const k of this.#store.keys()) if (k.startsWith(prefix)) return true;
+    return false;
+  }
+
+  _read(path) {
+    const v = this.#store.get(path);
+    if (!v) throw new WativeError("RECORD_NOT_FOUND", `nothing at ${path}`);
+    return v;
+  }
+
+  _write(path, data) {
+    this.#store.set(path, data);
+  }
+
+  _remove(path) {
+    this.#store.delete(path);
+  }
+
+  _ensureDir(path) {
+    this.#dirs.add(path);
+  }
+
+  _listItems(path) {
+    const prefix = path.endsWith("/") ? path : path + "/";
+    const names = new Set();
+    for (const k of this.#store.keys()) {
+      if (!k.startsWith(prefix)) continue;
+      const head = k.slice(prefix.length).split("/")[0];
+      if (head) names.add(head);
+    }
+    return [...names];
+  }
+
+  /** Not part of the contract — this example looks at the raw bytes below. */
+  dumpForTest() {
+    return this.#store;
+  }
+}
+
+test("a twenty-line backend runs a whole workspace", async () => {
+  const provider = new MapProvider("map://desk");
+
+  let ws = await Workspace.open({ provider, password: "wsp-pwd" });
+  assert.strictEqual(ws.locked, false);
+
+  // The built-in networks are there, exactly as with any other backend.
+  assert.ok(ws.networks.map((n) => n.slug).includes("ethereum"));
+
+  const acc = await ws.accounts.create(
+    "Desk One",
+    "wsp-pwd",
+    "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
+  );
+  await acc.deriveWallets(2);
+  assert.strictEqual(acc.wallets.length, 3);
+
+  // An address, and a signature from it — the full stack, on a Map.
+  const evm = acc.wallets[0].evm;
+  assert.match(evm.publicKey, /^0x[0-9a-fA-F]{40}$/);
+  const sig = await evm.signMessage("hello from a Map");
+  assert.match(sig, /^0x[0-9a-fA-F]{130}$/);
+
+  await ws.lock();
+
+  // Reopen from the same store: everything came back.
+  ws = await Workspace.open({ provider, password: "wsp-pwd" });
+  const again = ws.accounts.bySlug(acc.slug);
+  assert.ok(again);
+  assert.strictEqual(again.wallets.length, 3);
+  await again.tryUnlock("wsp-pwd");
+  assert.strictEqual(again.wallets[0].evm.publicKey, evm.publicKey);
+
+  await ws.lock();
+});
+
+test("the encryption comes with the base class, not with your code", async () => {
+  // Nothing above encrypts anything, yet nothing readable reaches the store.
+  // That is the reason to extend `ContainerProvider`: a backend cannot weaken
+  // the encryption because a backend never performs it.
+  const provider = new MapProvider("map://opaque");
+  const ws = await Workspace.open({ provider, password: "wsp-pwd" });
+  await ws.accounts.create(
+    "Secret Holder",
+    "wsp-pwd",
+    "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
+  );
+  await ws.lock();
+
+  const everything = Buffer.concat(
+    [...provider.dumpForTest().values()].map((b) => Buffer.from(b)),
+  ).toString("latin1");
+
+  assert.ok(everything.length > 0, "the store should not be empty");
+  assert.ok(!everything.includes("abandon"), "the mnemonic must not appear in stored bytes");
+  assert.ok(!everything.includes("Secret Holder"), "the account name must not appear either");
+});
+
+test("a wrong password cannot open the container", async () => {
+  const provider = new MapProvider("map://guarded");
+  const ws = await Workspace.open({ provider, password: "right-pwd" });
+  await ws.lock();
+
+  await assert.rejects(
+    Workspace.open({ provider, password: "wrong-pwd" }),
+    (err) => err.code === "BAD_PASSWORD",
+  );
+});

package/examples/README.md

@@ -14,13 +14,13 @@ Most files are written as CommonJS (`.test.cjs`) because the CJS build is the mo
 From the repo root:
 
 ```bash
-node --test tests/
+node --test examples/
 ```
 
 Or run a single file:
 
 ```bash
-node --test tests/01-quick-start.test.cjs
+node --test examples/01-quick-start.test.cjs
 ```
 
 If you are reading this inside `node_modules` after installing the package, copy the folder out before running `--test` — Node's test runner skips anything under `node_modules`. A single file can still be run in place with plain `node <file>`.
@@ -33,11 +33,11 @@ All tests work fully offline — no RPC calls, no real networks. Each test creat
 |---|---|
 | [01-quick-start.test.cjs](01-quick-start.test.cjs) | Open a workspace, create an HD account, derive 5 wallets, inspect EVM + Solana addresses, lock. |
 | [02-hd-account.test.cjs](02-hd-account.test.cjs) | HD-specific flows — deriving / slicing wallets, dumping the mnemonic, account-level passwords with `resetPassword`, round-trip across lock + reopen. |
-| [03-pk-account.test.cjs](03-pk-account.test.cjs) | PK accounts — creating from a private key, importing more keys (mix EVM + Solana under one account), duplicate-import rejection, dropping wallets. |
+| [03-pk-account.test.cjs](03-pk-account.test.cjs) | PK accounts — creating from a private key, importing more keys, and the three key formats accepted (EVM hex, Solana base58, `solana-keygen` JSON) with the chain inferred from the key. Also shows each import producing an address on both chains, duplicate-import rejection, and dropping wallets. |
 | [04-network-management.test.cjs](04-network-management.test.cjs) | The 10 pre-loaded networks, adding a brand-new network, overriding a pre-loaded RPC URL via `update()`, dropping user networks, the built-in protection guard. |
 | [05-asset-management.test.cjs](05-asset-management.test.cjs) | The 25 pre-loaded tokens, adding a custom user token, id collision rejection, contract-address collision rejection, dropping user tokens, `workspace.filter(q, "Asset")` search. |
 | [06-address-signing.test.cjs](06-address-signing.test.cjs) | Personal-message signing on EVM and Solana, building a transaction fully offline (no RPC). |
-| [07-custom-provider.test.cjs](07-custom-provider.test.cjs) | Plugging your own storage backend by extending the `Provider` base class. The example uses an in-memory key-value store but the same shape works for databases, cloud storage, and browser storage like IndexedDB. |
+| [07-custom-provider.test.cjs](07-custom-provider.test.cjs) | Taking over the record layer as well, by extending `Provider` rather than `ContainerProvider` — for storage that has its own encryption or its own idea of a record. Longer than [19](19-simple-provider.test.cjs); start there unless you need this. |
 | [08-persistence.test.cjs](08-persistence.test.cjs) | Round-trip across `lock()` + reopen — multiple accounts, user networks, custom assets, and logger configuration. |
 | [09-workspace-filter.test.cjs](09-workspace-filter.test.cjs) | `workspace.filter(query, objective)` for all four objectives — Account (by name or slug), Wallet (by id or tag), Address (by public key), Asset (by symbol or contract address). |
 | [10-default-network.test.cjs](10-default-network.test.cjs) | `account.setDefaultNetwork(value)` accepts a slug, a chain id, a hex chain id, or a `Network` instance. The choice persists across reopen. Unknown networks are rejected. |
@@ -48,22 +48,21 @@ All tests work fully offline — no RPC calls, no real networks. Each test creat
 | [15-package-resolution.test.cjs](15-package-resolution.test.cjs) | Resolution by bare package name — every declared subpath under both `require()` and `import()`, identical export surfaces from the two builds, and the declared Node version. |
 | [16-known-answer-vectors.test.cjs](16-known-answer-vectors.test.cjs) | Exact expected values — published BIP-44 addresses for the canonical mnemonic, a known address from an imported private key, and a fixed EIP-191 signature. Catches derivation from the wrong path or signing with the wrong key. |
 | [17-locked-state.test.cjs](17-locked-state.test.cjs) | What locking enforces — which operations refuse and with which error code, that a locked account holds no mnemonic in the clear, and that unlocking restores identical behaviour. |
+| [18-envelope-v3.test.cjs](18-envelope-v3.test.cjs) | `HybridProviderV3` — writing a workspace that derives one key for the whole workspace instead of one per stored secret, reopening it, and confirming a wrong password is still refused. |
+| [19-simple-provider.test.cjs](19-simple-provider.test.cjs) | The short way to write a storage backend — extend `ContainerProvider` and implement six methods that move bytes. Runs a whole workspace on a `Map`, signs from a derived address, reopens it, and checks that nothing readable reaches the store. |
 
 ## Adapting for your project
 
-In each file, replace:
-
-```js
-const { Workspace } = require("../dist/index.cjs");
-```
-
-with:
+Nothing to change. Every file already imports the package by name:
 
 ```js
 const { Workspace } = require("wative-core");
 ```
 
-once you've done `pnpm add wative-core` (or `npm i wative-core`) in your own project. Or, if your project is ESM-flagged, use `import` instead — both syntax styles resolve to the right entry via the package's `exports` map.
+so once you have run `pnpm add wative-core` (or `npm i wative-core`), copying a
+file into your own project and running it works as-is. If your project is
+ESM-flagged, use `import` instead — both resolve through the package's `exports`
+map.
 
 ## Notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wative-core",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "Hyperscale crypto wallet management library — multi-workspace, multi-chain, originally designed for on-chain market makers",
   "type": "module",
   "main": "./dist/index.node.cjs",