Workspace

A Workspace is the top-level encrypted container. Everything else in the library hangs off it: the accounts it holds, the networks they transact on, the imported assets, the workspace-wide config, and a logger. You obtain one with Workspace.open() and drive it through a small session lifecycle — unlock, lock, close.

import { Workspace } from "wative-core";

const ws = await Workspace.open({ path: "./my-wallet", password: "wsp-pwd" });

const account = await ws.accounts.create("Trading Desk", "wsp-pwd", MNEMONIC);
console.log(ws.accounts.length); // 1

await ws.lock();

Lifecycle

A workspace is always in one of three states, exposed by two boolean getters:

The transitions:

ws.accounts, ws.networks, ws.logger

These are the primary handles on a live workspace. ws.config and ws.logger require an unlocked session — reading either while locked throws WORKSPACE_LOCKED. The others — ws.accounts, ws.networks, ws.rootDescriptor and ws.damagedAccountSlugs — read even while locked (the collections simply read as empty until unlock).

ws.accounts and ws.networks are read-only accessors over private backing fields. There is no setter: ws.accounts = [] throws a TypeError in strict mode rather than silently replacing the collection.

The logger auto-persists its configuration. Mutating it — setLevel, setSinks — writes the new LoggerConfig back through the provider, so it survives a lock/reopen cycle:

await ws.logger.setLevel("debug");

await ws.lock();
const reopened = await Workspace.open({ path: "./my-wallet", password: "wsp-pwd" });
reopened.logger.config.minLevel; // "debug"

Stop emission entirely with ws.logger.setSinks([]).

lock() vs close()

Both end the current session; the difference is what happens to the storage backend.

close() is idempotent and single-flight — concurrent calls share one teardown and all resolve when it is done. Calling lock() on an already-closed workspace is a no-op, not an error.

Session keys

A workspace on a v3 provider (IdbProviderV3 in the browser, or HybridProviderV3 in Node) can hand out a 32-byte session key that reopens it later without the password. It is the resume path for a session that must survive the password leaving memory — for example restoring an unlocked wallet after a browser extension's background page is evicted, without re-prompting the user.

// `ws` is unlocked and backed by a v3 provider.
const key = ws.exportSessionKey(); // Uint8Array(32) — store it somewhere memory-only

// Later, with no password available — reopen the container from the key alone…
const resumed = await Workspace.openWithSessionKey(await IdbProviderV3.create("my-wallet"), key);

// …or resume a workspace handle you still hold:
await ws.unlockWithSessionKey(key);

Argon2 does not re-run on the key path. A wrong key is refused with BAD_PASSWORD and a non-32-byte key with PARAMETER_ERROR; either way the workspace stays locked, never half-open. The key opens the same records the password does, so guard it as carefully as the unlocked vault — it is not the password and cannot be reversed to it, but anything holding it can read every record. An account that carries its own password still needs that password after a key resume.

Re-read handles after unlock

lock() replaces the account and network collections with fresh, empty ones and wipes the previous session's state. Any reference you captured before locking is now stale, and the same is true across an idle-lock followed by unlock() — hydration builds fresh instances. Always re-read the handle from the workspace after a session boundary rather than reusing a cached reference.

let ws = await Workspace.open({ path: "./my-wallet", password: "wsp-pwd" });
const hd = await ws.accounts.create("Desk One", "wsp-pwd", MNEMONIC);

await ws.lock();
ws = await Workspace.open({ path: "./my-wallet", password: "wsp-pwd" });

// Re-read the account off the reopened workspace — `hd` above is stale.
const reopened = ws.accounts.bySlug(hd.slug);

What a stale handle does if you do reuse it is deliberately loud, never silent:

• A cached ws.networks collection refuses mutations with UNSUPPORTED_OP ("this networks collection is no longer live"). Re-read ws.networks.
• A cached account or address handle refuses operations that need key material with ACCOUNT_LOCKED, even while the reopened workspace is unlocked and holds a fresh twin.