wative-core 2.4.1 → 2.4.2

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 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

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.
@@ -233,17 +268,6 @@ produces the same keys.
 Nothing to install: it runs on a bundled WebAssembly build by default, with no
 native binary and no build step.
 
-### Browser: grant `'wasm-unsafe-eval'`
-
-```
-Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'
-```
-
-Optional. Without it nothing breaks and nothing throws — key derivation falls
-back to a slower implementation that produces identical results, so unlocking a
-wallet with a dozen addresses takes tens of seconds instead of about one. Grant
-it if that matters to you. `argon2BackendInfo()` reports which one ran.
-
 ### One derivation per container: `HybridProviderV3` (Node only)
 
 ```ts
@@ -262,15 +286,6 @@ 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.
 
-Two things to plan for:
-
-- **An existing workspace does not get faster on its own.** Secrets written
-  before the switch keep their own keys, so they keep costing one derivation
-  each. `account.resetPassword(old, new)` rewrites them.
-- ⚠️ **Older versions of this library cannot open a V3 workspace**, and there is
-  no way back. Once a workspace has been opened with V3, keep using a version
-  that supports it.
-
 ### Checking which implementation ran
 
 ```ts
@@ -312,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.