wative-core 2.4.0 → 2.4.2

package/CHANGELOG.md

@@ -2,6 +2,94 @@
 
 All notable changes to `wative-core` are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.4.2] — 2026-08-11
+
+Importing a private key gets easier and does more: you no longer have to say
+which chain a key is for, more of the formats you actually hold are accepted,
+and one import now gives you an address on both chains.
+
+### Changed
+- **BREAKING. A PK wallet now holds two addresses instead of one.** Importing a
+  key gives you an address on the chain that key is for, plus one on the other
+  chain seeded by the same 32 secret bytes. The chain you imported for stays at
+  `addresses[0]`, so code reading that position is unaffected — but
+  `addresses.length` is now 2, and totals derived from it will differ.
+
+  ⚠️ **One secret controls both addresses.** There is only one key to import,
+  so both addresses come from it, and whoever learns that key holds both
+  chains. This is not how an HD account behaves: there a slot's two addresses
+  come from two derivation paths and are independent keys. Use an HD account,
+  or import a separate key per chain, if you need that separation.
+
+  Wallets already stored keep the single address they were written with. Only
+  new imports are paired.
+
+### Added
+- **`importPrivateKey(pk)` no longer needs a `vm`.** The accepted formats do not
+  overlap — 64 hex characters for EVM, 80–96 base58 for Solana — so the chain is
+  read off the key. Passing `vm` explicitly still works and still wins.
+- **`solana-keygen` JSON byte arrays are accepted.** The contents of
+  `~/.config/solana/id.json` can be handed to `importPrivateKey` as-is, instead
+  of being converted to base58 by hand first.
+
+### Fixed
+- **An out-of-range EVM private key is now `INVALID_PRIVATE_KEY`.** 32 bytes of
+  hex is not necessarily a key: zero, and anything at or above the secp256k1
+  group order, previously reached the curve library and surfaced as a bare
+  `Error` with no `code`, thrown from inside a queued mutation. It is refused at
+  the boundary now, like every other malformed key.
+- Corrected the README's account diagrams, which described a PK wallet as
+  carrying exactly one address as though it were a structural rule.
+
+## [2.4.1] — 2026-08-11
+
+One breaking item, and it is the kind worth reading before upgrading: a
+transaction no longer guesses which chain it is for. Alongside it, a browser and
+a Node process now each get a working storage backend without being told which
+one to use, and writing your own backend is documented with a runnable example.
+
+### Security
+- **BREAKING. `EvmTransaction` requires `chainId` and no longer defaults to
+  Ethereum mainnet.** Building a transaction without naming a chain used to
+  produce chain 1. That is not a harmless default: a signed transaction is a
+  bearer instrument, so the result was a genuine, broadcastable Ethereum
+  mainnet signature that the caller never asked for. The same applied to anyone
+  who reached for a `network` field — transactions have never had one, the key
+  was discarded, and chain 1 came back. Both are now refused with
+  `PARAMETER_ERROR`, and the message names the `network` trap directly.
+
+  TypeScript callers using the object form were already required to pass
+  `chainId` and are unaffected. This changes behaviour for JavaScript callers,
+  and for the positional form, where `opts` and its `chainId` are now required.
+
+  Nothing changes for `address.buildTransaction()`, which continues to take the
+  chain from the address's own network — that remains the shortest correct way
+  to build a transaction, and `chainId` there is still optional.
+
+  ```js
+  // before — signed for Ethereum, silently
+  new EvmTransaction({ from, to, value });
+
+  // after — name the chain
+  new EvmTransaction({ from, to, value, chainId: 8453 });
+  // or let the address decide
+  address.buildTransaction({ to, value });
+  ```
+
+### Added
+- **A default storage backend in both environments.** `Workspace.open(password)`
+  now works in a browser without importing a provider first, using IndexedDB.
+  Node continues to resolve its filesystem backend from `wative-core/node`.
+- **A worked example of a custom storage backend**, at
+  `examples/19-simple-provider.test.cjs`: six methods that move bytes, running a
+  whole workspace on a `Map`. The published type declarations now ship the
+  documentation for the types you implement against.
+
+### Changed
+- **Node's default backend is now `HybridProviderV3`**, falling back to
+  `HybridProvider` where the optional native dependency has no prebuilt binary.
+  Both read each other's containers, so the fallback costs no data.
+
 ## [2.4.0] — 2026-08-11
 
 Six breaking items, each one an operation that reported success without having

package/README.md

@@ -44,28 +44,64 @@ Account "Trading Desk"   (HD)          one mnemonic
 └── …                                  account.deriveWallets(n)
 ```
 
-**PK** — imported keys. A `Wallet` is one key you handed in, on the one chain
-you imported it for. Wallets have no relationship to each other:
+**PK** — imported keys. Each import allocates its own `Wallet`, and that wallet
+gets an address on **both** chains: the key signs on its own curve, and the same
+32 secret bytes seed a keypair on the other one. The chain you imported for
+comes first.
 
 ```
 Account "Cold Storage"   (PK)          no mnemonic
 ├── Wallet 0                           the key passed to accounts.create()
-│   └── Address  vm: "evm"             0x90F8bf6A…
-├── Wallet 1                           account.importPrivateKey(pk, "evm")
-│   └── Address  vm: "evm"             0xFFcf8FDE…
-└── Wallet 2                           account.importPrivateKey(pk, "svm")
-    └── Address  vm: "svm"             7WktogJEd…      one chain per wallet
+│   ├── Address  vm: "evm"             0x90F8bf6A…    the imported key
+│   └── Address  vm: "svm"             HaWmh8svNQ…    same secret, other curve
+├── Wallet 1                           account.importPrivateKey(evmKey)
+│   ├── Address  vm: "evm"             0xFFcf8FDE…
+│   └── Address  vm: "svm"             Fgdy5QRxtP…
+└── Wallet 2                           account.importPrivateKey(svmKey)
+    ├── Address  vm: "svm"             3QVq8D876h…    the imported key
+    └── Address  vm: "evm"             0x1a740984…    same secret, other curve
+```
+
+A PK account can hold as many keys as you like, on any mix of chains — but it
+refuses the same identity twice, on either chain.
+
+> ⚠️ **One secret controls both addresses in a PK wallet.** There is only one
+> key to import, so both addresses come from it. Whoever learns that key holds
+> both chains.
+>
+> This is not how an HD account works. There, a slot's two addresses come from
+> two different derivation paths — the mnemonic is shared, the private keys are
+> independent. If you want independent keys per chain, use an HD account, or
+> import a separate key for each and read `addresses[0]` of each wallet.
+
+> **`wallet.addresses` is a list.** It holds one address per `(vm, network)`
+> pair and is free to carry several. Read it rather than assuming a position:
+>
+> ```ts
+> const evm = wallet.addresses.find((a) => a.vm === "evm");
+> ```
+
+**Which chain a key is for is read off the key** — `vm` is optional:
+
+```ts
+await acc.importPrivateKey(evmKey);                    // 64 hex chars  -> evm
+await acc.importPrivateKey(solanaKey);                 // base58        -> svm
+await acc.importPrivateKey(readFileSync("id.json"));   // solana-keygen -> svm
+await acc.importPrivateKey(key, "evm");                // or say so explicitly
 ```
 
-A PK account can hold as many keys as you like, and they can be on different
-chains — but it refuses the same identity twice.
+The formats do not overlap, so this is a decision rather than a guess. A value
+that is neither is refused with `INVALID_PRIVATE_KEY` — including 32 bytes of
+hex that is not a valid secp256k1 scalar, and a bare 32-byte base58 value,
+which is indistinguishable from a Solana *public* key.
 
 |                        | HD                            | PK                              |
 | ---------------------- | ----------------------------- | ------------------------------- |
 | Created from           | a BIP-39 mnemonic             | one private key                 |
 | Grows with             | `deriveWallets(n)`            | `importPrivateKey(pk, vm)`      |
 | A `Wallet` is          | a derivation slot             | one imported key                |
-| Addresses per `Wallet` | **2** — one evm, one svm      | **1** — the chain you imported  |
+| Addresses per `Wallet`  | **2** — one evm, one svm      | **2** — imported chain first    |
+| Those two addresses     | independent keys, two paths   | **one key, both curves**        |
 | `dumpMnemonic()`       | ✔                             | throws `UNSUPPORTED_OP`         |
 | `sliceWallets(n)`      | ✔                             | throws `UNSUPPORTED_OP`         |
 | `importPrivateKey()`   | throws `UNSUPPORTED_OP`       | ✔                               |
@@ -150,7 +186,6 @@ await ws.lock();
 | Storage        | encrypted files on disk                | IndexedDB                        |
 | Where it lives | `Workspace.open({ path })`, or default | `IdbProvider.create(name)`       |
 | Extra setup    | none                                   | `Buffer` polyfill                |
-| Keys can vanish| no                                     | yes — storage is evictable       |
 
 `HybridProvider`, `HybridProviderV3` and `FileSink` are re-exported from the
 package root in Node.
@@ -225,72 +260,13 @@ await otherProvider.importContainer(backup);     // same password opens it
 
 ## Key derivation
 
-Passwords are stretched with Argon2id (RFC 9106) at t=3, m=64 MiB, p=1 before
-they ever touch a key. That is deliberately expensive, and an account unlock
-runs one derivation per sealed secret — so the implementation matters.
-
-By default it runs on a vendored WebAssembly build: no native binary, no build
-step, nothing to install. Measured over a full workspace lifecycle it is about
-**25x** faster than the pure-JS implementation it replaced.
-
-### Browser: grant `'wasm-unsafe-eval'`
-
-```
-Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'
-```
-
-Without it the browser blocks WebAssembly compilation entirely — synchronously
-and asynchronously, main thread and worker alike. **Nothing throws.** Key
-derivation quietly falls back to a pure-JS implementation that produces
-identical bytes roughly 17x slower, so unlocking a wallet with a dozen addresses
-goes from under a second to tens of seconds. The fallback is announced once on
-the console and reported permanently by `argon2BackendInfo()`.
-
-## Upgrading to 2.3.0
-
-**v1 containers can no longer be opened.** Support for the v1 envelope
-(PBKDF2-HMAC-SHA256, written by wative-core 1.x) was removed and there is no
-migration path in this release. Containers written by any 2.x version are v2 and
-open unchanged.
-
-If you hold a v1 container, recover it with **2.2.x or earlier** before
-upgrading. `exportContainer()` will not do it — it copies sealed bytes without
-decrypting, so the export is as unreadable as the original. Use the accessors
-that return plaintext:
-
-```ts
-// under wative-core 2.2.x — NOT 2.3.0, which can no longer open a v1 container
-import { Workspace, HybridProvider } from "wative-core";
-
-const ws = await Workspace.open(new HybridProvider("~/wallets"), password);
-
-for (const account of ws.accounts) {
-  await account.tryUnlock(password);
+Passwords are stretched with Argon2id (RFC 9106) before they ever become a key.
+That is deliberately expensive, which is why unlocking takes a moment and why
+the sections below are about speed rather than correctness — every option
+produces the same keys.
 
-  // HD accounts: the mnemonic regenerates every derived key, so it is the only
-  // thing you need.
-  if (account.organizationType === "HD") {
-    console.log(account.slug, "mnemonic:", account.dumpMnemonic());
-    continue;
-  }
-
-  // PK accounts: there is no mnemonic, so every imported key must be kept.
-  // `dumpPrivateKey` lives on the WALLET and takes the VM of the address you
-  // want — a wallet holds at most one address per VM.
-  for (const wallet of account.wallets) {
-    for (const address of wallet.addresses) {
-      console.log(account.slug, wallet.id, address.vm, wallet.dumpPrivateKey(address.vm));
-    }
-  }
-}
-```
-
-Keep that material somewhere safe, upgrade, then re-import it with
-`accounts.create(...)` and `importPrivateKey(...)`.
-
-Three public members were removed with v1: `Provider.passwordTanren`,
-`ContainerProvider.passwordTanren` and `HybridProvider.kdfIterations`. All three
-existed only to expose the PBKDF2 derivation.
+Nothing to install: it runs on a bundled WebAssembly build by default, with no
+native binary and no build step.
 
 ### One derivation per container: `HybridProviderV3` (Node only)
 
@@ -300,34 +276,15 @@ import { Workspace, HybridProviderV3 } from "wative-core";
 const ws = await Workspace.open(new HybridProviderV3("~/wallets"), password);
 ```
 
-The default provider derives an Argon2 key per sealed secret, so unlocking an
-account costs one derivation per address — at production parameters that is
-essentially the whole cost, and it grows with the account. `HybridProviderV3`
-derives once per container instead. Measured: unlocking a 50-address account
-goes from 7.3 s to 144 ms, and the v3 figure does not grow with the address
-count.
-
-It is opt-in, and Node-only: it derives through native `@node-rs/argon2`, which
-has no browser build. In a browser use `HybridProvider`, which needs no binary
-and no install and is already about 25x faster than what preceded it.
-
-⚠️ **The speedup applies to records written as v3, not to ones you already
-have.** Pointing `HybridProviderV3` at a container built by 2.x keeps every
-existing secret on its own salt, so it keeps costing one derivation each — the
-container still opens, it just does not get faster. Rewriting an account's
-secrets with `account.resetPassword(old, new)` converts them. A container
-reaches one derivation once all of its records have been written as v3, which
-happens on its own only for containers created under v3.
+`HybridProvider` derives a key per stored secret, so unlocking an account costs
+one derivation per address and gets slower as the account grows.
+`HybridProviderV3` derives once per workspace instead — unlocking a 50-address
+account goes from about 7 seconds to under 200 ms, and stays there however many
+addresses you add.
 
-The first v3 unlock of an existing container costs one extra derivation, once,
-and converts its CONFIG record to v3 — after which wative-core 2.2.x and earlier
-can no longer open it.
-
-Reads do not depend on the choice — every record carries its own version byte,
-so either 2.3.0 provider opens either format, in both directions. ⚠️ But **older
-library versions cannot read v3**: wative-core 2.2.x and earlier know only v1 and
-v2 and will fail with `Unknown envelope version: 3`. Adopting v3 is a one-way
-door with respect to the library version.
+It is the Node default where `@node-rs/argon2` is installed, and Node-only: that
+package has no browser build. Construct it yourself only to pick a location, or
+to be sure you get it rather than the fallback.
 
 ### Checking which implementation ran
 
@@ -352,7 +309,7 @@ An `examples/` folder ships with the package — runnable JavaScript files demon
 Copy them out of `node_modules` first, then run the whole set:
 
 ```bash
-cp -R node_modules/wative-core/tests wative-examples
+cp -R node_modules/wative-core/examples wative-examples
 node --test wative-examples/
 ```
 
@@ -362,7 +319,7 @@ The copy is required: Node's test runner skips anything under `node_modules`, so
 node node_modules/wative-core/examples/01-quick-start.test.cjs
 ```
 
-Files cover: quick start, HD vs PK accounts, network management, asset management, address signing, custom storage backends, persistence, workspace search, default-network selection, subpath imports, the workspace logger, workspace config, the ESM entry, and package resolution. See [examples/README.md](./examples/README.md) for the index.
+Files cover: quick start, HD vs PK accounts, network management, asset management, address signing, custom storage backends, persistence, workspace search, default-network selection, subpath imports, the workspace logger, workspace config, the ESM entry, package resolution, known-answer vectors, locked-state behaviour, and one-key-per-workspace derivation. See [examples/README.md](./examples/README.md) for the full index — it is the list that stays current.
 
 ## What you can do
 
@@ -370,7 +327,7 @@ The library is organized around seven things you'll work with:
 
 - **`Workspace`** — your top-level container. Holds the password, your accounts, your network and asset list, and a built-in logger.
 - **`Account`** — either an HD account (one BIP-39 mnemonic, can derive many wallets) or a PK account (raw private keys you import one at a time). Each account can have its own password or share the workspace password.
-- **`Wallet`** — a unit inside an account. HD wallets carry one EVM and one Solana address; PK wallets carry one address.
+- **`Wallet`** — a unit inside an account, holding one address per `(vm, network)`. Both kinds give you an EVM and a Solana address: an HD slot derives one per chain from the mnemonic, an import derives its sibling from the imported key. Treat `wallet.addresses` as the list it is.
 - **`Address`** — an on-chain identity. Sign messages, build transactions, send them.
 - **`Network`** — chain metadata. 10 networks ship pre-loaded.
 - **`Asset`** — token metadata. 25 tokens ship pre-loaded.
@@ -518,11 +475,10 @@ const svmAddr = hd.wallets[0].addresses.find((a) => a.vm === "svm")!;
 
 const sig = evmAddr.signMessage("hello hedgue");
 
-import { Network } from "wative-core";
-const tx = await evmAddr.buildTransaction({
+const tx = evmAddr.buildTransaction({
   to: "0x1234567890123456789012345678901234567890",
   value: 1_000_000_000_000_000n,
-  network: Network.Ethereum,
+  chainId: 1,
 });
 await evmAddr.signTransaction(tx);
 const tracker = await evmAddr.sendTransaction(tx);
@@ -606,7 +562,11 @@ const evmTx = new EvmTransaction({
   from: evmAddr.publicKey as EvmAddress,
   to: "0x1234567890123456789012345678901234567890" as EvmAddress,
   value: 10_000_000n,
-  network: Network.Base,
+  // The chain is set HERE, by id. `chainId` is required and has no default,
+  // and there is no `network` field on a transaction — both are refused
+  // rather than guessed, because a signed transaction for the wrong chain is
+  // still a valid transaction on that chain.
+  chainId: 8453 as ChainId,   // Base
   gasLimit: 21000n,
   maxFeePerGas: 50_000_000_000n,
   maxPriorityFeePerGas: 1_000_000_000n,
@@ -617,7 +577,7 @@ const evmTracker = await evmAddr.sendTransaction(evmTx);
 const receipt = await evmTracker.whenConfirmed(3);
 ```
 
-For Solana transactions, build instructions with `@solana/web3.js` (or your preferred Solana toolkit) and pass them to `new SvmTransaction({ from, instructions, network })`. The signing, sending, and tracker lifecycle then mirror the EVM flow.
+For Solana transactions, build instructions with `@solana/web3.js` (or your preferred Solana toolkit) and pass them to `new SvmTransaction({ from, recipient, amount, instructions })`. The signing, sending, and tracker lifecycle then mirror the EVM flow.
 
 #### Hand off to an external signer / RPC client
 
@@ -658,9 +618,100 @@ const address = await ws.filter("0xab12345678…cdef", "Address");
 const asset   = await ws.filter("USDC", "Asset");
 ```
 
+## Which storage backend you get
+
+`Workspace.open()` picks one for you unless you pass a provider:
+
+| environment | default | notes |
+|---|---|---|
+| Node, with `import "wative-core/node"` | `HybridProviderV3`, falling back to `HybridProvider` | encrypted files on disk |
+| Browser | `IdbProvider` | IndexedDB, in the current origin |
+| Node, without the node import | *none* — throws, and the message tells you to add the import | |
+
+The optional first argument means a **path** in Node and a **database name** in the browser, so the same call reads sensibly in both:
+
+```ts
+await Workspace.open("my-wallet", password);  // path in Node, database name in a browser
+await Workspace.open({ password });            // omit it for the conventional location / "wative"
+```
+
+Two things to know about the Node default:
+
+- It uses `HybridProviderV3` when `@node-rs/argon2` is installed, and `HybridProvider` when it is not. V3 derives one key per workspace instead of one per stored secret, so unlocking an account with many addresses is a single derivation rather than one each. `@node-rs/argon2` is an optional dependency because a few platforms have no prebuilt binary.
+- Either provider opens a workspace the other wrote, so falling back costs speed, not access. ⚠️ Older versions of this library cannot open a V3 workspace, and there is no way back — check `argon2BackendInfo()` if you need to know which you got.
+
+Pass a provider explicitly whenever you need to configure it — a non-default location, a named database, or acknowledging evictable browser storage:
+
+```ts
+import { Workspace, IdbProvider } from "wative-core";
+
+const provider = await IdbProvider.create("my-wallet", { acknowledgeEvictionRisk: true });
+const ws = await Workspace.open({ provider, password });
+```
+
+## Records
+
+Everything a workspace persists is a `Record` — an account, a network, an asset, the config. You mostly work with the domain objects (`Account`, `Network`, …) and never touch a Record directly; you need this when you write a custom backend, or when you read records straight off a provider.
+
+A Record arrives **locked** and holds ciphertext until you unlock it:
+
+```ts
+const record = await provider.loadRecord("ACCOUNTS", "alice");
+
+record.locked;            // true
+record.value;             // throws RECORD_LOCKED
+
+record.unlock(password);  // decrypts in memory
+record.value;             // your data
+
+record.value.displayName = "Alice Desk";
+await record.save();      // re-encrypts and writes back
+```
+
+| member | behaviour |
+|---|---|
+| `locked` | `true` until `unlock()` succeeds |
+| `value` | throws `RECORD_LOCKED` while locked |
+| `unlock(password)` | `BAD_PASSWORD` if wrong, `DECRYPT_FAILED` if the record cannot be read at all |
+| `save()` | throws if locked, or if the workspace that issued it has since been locked |
+
+Two things to plan for:
+
+- **A handle does not outlive its session.** A Record kept from an earlier unlock stops working once the workspace is locked, and cannot write over a record that has since been replaced or deleted. Reload it rather than holding it.
+- **Records are backend-independent.** `exportContainer()` in a browser imports into a desktop workspace and back — the storage you chose does not change what a workspace is.
+
 ## Custom storage backends
 
-By default, `Workspace.open(...)` stores everything as encrypted files under the path you pass it. If you want to store the workspace somewhere else — a database, an object store, a browser's IndexedDB — extend the `Provider` base class and pass an instance to `Workspace.open()`:
+To store a workspace somewhere else — Redis, S3, SQLite, OPFS, SFTP — extend **`ContainerProvider`** and implement six methods that move bytes. The session, the record API and all the encryption come from the base class, so this is the whole backend:
+
+```ts
+import { Workspace, ContainerProvider, WativeError } from "wative-core";
+
+class MyProvider extends ContainerProvider {
+  #store = new Map<string, Uint8Array>();
+
+  protected _exist(path: string)  { return this.#store.has(path); }
+  protected _read(path: string)   {
+    const v = this.#store.get(path);
+    if (!v) throw new WativeError("RECORD_NOT_FOUND", path);
+    return v;
+  }
+  protected _write(path: string, data: Uint8Array) { this.#store.set(path, data); }
+  protected _remove(path: string)                  { this.#store.delete(path); }
+  protected _ensureDir(_path: string)              {}
+  protected _listItems(prefix: string)             { /* names directly under prefix */ return []; }
+}
+
+const ws = await Workspace.open({ provider: new MyProvider("mem://desk"), password });
+```
+
+Each method may be sync or async — return a value or a promise — so a synchronous store and a network one share the same contract.
+
+Your code never encrypts anything: the base class hands you sealed bytes and opaque paths. A runnable version, including a check that no readable secret reaches the store, is in [19-simple-provider.test.cjs](./examples/19-simple-provider.test.cjs).
+
+### Taking over the record layer as well
+
+Extend `Provider` instead when the storage system has its own encryption or its own idea of a record. You then implement the six primitives *and* the container session and record API — see [07-custom-provider.test.cjs](./examples/07-custom-provider.test.cjs) for a complete one:
 
 ```ts
 import { Workspace, Provider, Record, type RecordInit, type RecordType } from "wative-core";