wative-core 2.4.7 → 2.5.1

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 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.5.1] — 2026-09-12
+
+Renames the transfer helper and improves fee handling.
+
+### Changed
+- BREAKING: `address.transfer(...)` is now `address.buildTransferPayload(...)`. It returns the transfer's parameters; pass them to `buildTransaction(...)` to sign and send — for example `buildTransaction({ ...buildTransferPayload({ to, asset, amount }), chainId }).send()`.
+- When you don't set gas fees, they are now chosen with more headroom, so a transaction is less likely to sit unconfirmed while network fees rise.
+- The built-in `evm` and `svm` chains can no longer be replaced through `registerDialect`; registering your own chain under a new name is unaffected.
+
+## [2.5.0] — 2026-09-12
+
+Adds token-aware transfers and a public way to add your own chain.
+
+### Added
+- `address.transfer({ to, asset, amount })` sends in one call: the native coin (omit `asset`), a token by its contract address or mint, or a token by symbol. Amounts are given in the token's smallest unit.
+- Support for a chain the library does not ship: subclass the exported `ChainDialect`, implement its methods, and register it with `registerDialect` — the same way you extend `Provider` for storage. `ChainDialect`, `ChainCtx` and the per-chain `EvmSigner` / `SvmSigner` types are now exported.
+
 ## [2.4.7] — 2026-09-11
 
 Adds more built-in networks and updates the Solana network identifiers.

package/README.md

@@ -308,7 +308,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, 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.
+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, one-key-per-workspace derivation, adding a custom chain, and token transfers. See [examples/README.md](./examples/README.md) for the full index — it is the list that stays current.
 
 ## What you can do
 
@@ -317,19 +317,21 @@ 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, 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.
+- **`Address`** — an on-chain identity. Sign messages, build transactions, transfer native coins or tokens, and send them.
+- **`Network`** — chain metadata. 14 networks ship pre-loaded.
+- **`Asset`** — token metadata. 29 tokens ship pre-loaded.
 - **`Transaction`** — `EvmTransaction` or `SvmTransaction`. Subscribe to lifecycle events (`change` / `confirmed` / `failed`) or await terminal states (`whenSubmitted` / `whenMined` / `whenConfirmed` / `whenFinalized`). Tracking stops at first inclusion, so `whenConfirmed(n)` with `n > 1` rejects `UNSUPPORTED_OP` — call it with no argument and poll `receipt.blockNumber` against the chain head if you need depth — and `whenFinalized()` rejects `UNSUPPORTED_OP` unless the node reported finality directly.
 
 Everything is encrypted on disk under your workspace password.
 
 ### Pre-loaded networks and tokens
 
-| Networks (10) | Tokens (25) |
+| Networks (14) | Tokens (29) |
 |---|---|
 | ethereum, base, bnbchain, arbitrum, optimism | native gas + USDC + USDT on each EVM mainnet (BSC versions are 18-decimal Binance-Peg); plus WETH on ethereum |
+| hyperevm, robinhood | native HYPE on HyperEVM; native ETH on Robinhood Chain |
 | sepolia, arbitrum-sepolia | native ETH on both testnets; plus USDC on arbitrum-sepolia |
+| hyperevm-testnet, robinhood-testnet | native HYPE / native ETH, mirroring their mainnets |
 | solana, solana-testnet, solana-devnet | native SOL + USDC + USDT + WSOL on solana mainnet; native-only on testnets |
 
 ## Examples by domain
@@ -489,6 +491,23 @@ const sim = await evmAddr.simulateTransaction(tx);
 console.log(sim.gasUsed);
 ```
 
+`buildTransferPayload()` is the one-call path for moving value — it works out the right payload for the asset (native value, ERC-20 calldata, or SPL instructions). You then pass that payload to `buildTransaction()` and send it like any other transaction:
+
+```ts
+// native coin (omit `asset`)
+const nativePayload = evmAddr.buildTransferPayload({ to: recipient, amount: 1_000_000_000_000_000n });
+// an ERC-20 / SPL token, by contract address or mint
+const tokenPayload = evmAddr.buildTransferPayload({ to: recipient, asset: { address: usdcAddress }, amount: 1_000_000n });
+// or by symbol, resolved against the network's known tokens
+const bySymbol = evmAddr.buildTransferPayload({ to: recipient, asset: { symbol: "USDC" }, amount: 1_000_000n });
+
+// build the transaction from the payload, then sign/send it
+const tx = evmAddr.buildTransaction({ ...nativePayload, chainId: 1 });
+await evmAddr.signTransaction(tx);
+```
+
+Amounts are in the token's smallest unit. `buildTransaction` fills in nonce/gas/fees for you when you omit them, or uses the values you pass. An SPL transfer to a recipient without a token account prepends the account-creation step for you.
+
 ### Network — pre-loaded networks + your own
 
 ```ts
@@ -761,6 +780,31 @@ may need to override:
   `unreadableRecordSlugs()` carry defaults in the same family — see their JSDoc
   before overriding either.
 
+## Adding a chain
+
+To support a blockchain the library does not ship — its own address format, signing and transactions — subclass **`ChainDialect`** and register it under a vm token. This is the chain-side parallel to extending `Provider` for storage: `Workspace` and `Address` route every per-chain operation through the registered dialect, so no library code branches on which chain you added.
+
+```ts
+import { ChainDialect, registerDialect, type ChainCtx } from "wative-core";
+
+class MyDialect extends ChainDialect {
+  readonly vm = "mychain";
+  readonly curve = "ed25519"; // reuse a built-in signing curve
+
+  signMessage(ctx: ChainCtx, message: string): string { /* build a digest, sign via ctx._signBytes, format */ }
+  buildTransaction(ctx, params) { /* return your chain's transaction */ }
+  buildTransferPayload(ctx, req) { /* lower { to, asset, amount } to a transfer payload */ }
+  derive(seed, index)           { /* return { publicKey, privateKey } at this index */ }
+  addressFromPrivateKey(pk)     { /* the address a key controls */ }
+  privateKeyMatches(pk, publicKey) { /* whether a key controls an address */ }
+  // signMessageEncoded / signTypedData round out the contract
+}
+
+registerDialect("mychain", () => new MyDialect());
+```
+
+Your dialect never receives the private key: it signs through a keyless view (`ctx._signBytes`) the library hands it and declares which built-in curve to use. A runnable end-to-end example — a fictional chain that signs, builds a transaction, transfers and derives — is in [20-custom-chain-dialect.test.cjs](./examples/20-custom-chain-dialect.test.cjs).
+
 ## Imports from sub-paths
 
 Heavier chain helpers are kept on separate import paths so you only pull them in if you need them: