@meshsdk/wallet 1.9.0 → 2.0.0-beta.10

package/README.md

@@ -1,5 +1,228 @@
-# mesh-wallet
+# @meshsdk/wallet
 
-Wallets - [meshjs.dev/apis/wallets](https://meshjs.dev/apis/wallets)
+Cardano wallet library for signing transactions, managing keys, and interacting with browser wallets. Provides both headless (server-side / Node.js) and browser wallet support with a CIP-30 compatible interface.
 
-[meshjs.dev](https://meshjs.dev/)
+```bash
+npm install @meshsdk/wallet
+```
+
+> **Migrating from v1 (`MeshWallet` or `BrowserWallet`)?** This version has breaking changes. See:
+> - [`mesh-wallet-migration.md`](./mesh-wallet-migration.md) — for `MeshWallet` to `MeshCardanoHeadlessWallet`
+> - [`browser-wallet-migration.md`](./browser-wallet-migration.md) — for `BrowserWallet` to `MeshCardanoBrowserWallet`
+
+---
+
+## Table of Contents
+
+- [Architecture Overview](#architecture-overview)
+- [Exported Classes](#exported-classes)
+- [Headless Wallet (Server-Side)](#headless-wallet-server-side)
+- [Browser Wallet (Client-Side)](#browser-wallet-client-side)
+- [Low-Level Components](#low-level-components)
+- [CIP-30 Compatibility](#cip-30-compatibility)
+- [CardanoHeadlessWallet vs MeshCardanoHeadlessWallet](#cardanoheadlesswallet-vs-meshcardanoheadlesswallet)
+- [Migration from v1](#migration-from-v1)
+
+---
+
+## Architecture Overview
+
+This package uses a two-tier class hierarchy for both headless and browser wallets:
+
+- **Base classes** (`CardanoHeadlessWallet`, `CardanoBrowserWallet`) implement the CIP-30 interface strictly — all methods return raw hex/CBOR exactly as CIP-30 specifies.
+- **Mesh classes** (`MeshCardanoHeadlessWallet`, `MeshCardanoBrowserWallet`) extend the base classes with convenience methods (`*Bech32()`, `*Mesh()`, `signTxReturnFullTx()`) that return human-friendly formats.
+
+**For most use cases, use the Mesh classes.** The base classes are for advanced users who need raw CIP-30 output.
+
+---
+
+## Exported Classes
+
+| Class | Purpose | Use When |
+|-------|---------|----------|
+| `MeshCardanoHeadlessWallet` | Full-featured headless wallet with convenience methods | Server-side signing, backend transaction building, testing |
+| `CardanoHeadlessWallet` | CIP-30 strict headless wallet (raw hex/CBOR returns) | You need raw CIP-30 output without conversion |
+| `MeshCardanoBrowserWallet` | Full-featured browser wallet wrapper with convenience methods | dApp frontend integration with browser wallets (Eternl, Nami, etc.) |
+| `CardanoBrowserWallet` | CIP-30 strict browser wallet wrapper (raw hex/CBOR returns) | You need raw CIP-30 passthrough from browser wallets |
+| `InMemoryBip32` | BIP32 key derivation from mnemonic (keys stored in memory) | Deriving payment/stake/DRep keys from a mnemonic |
+| `BaseSigner` | Ed25519 signer from raw private keys | Signing with raw private keys (normal or extended) |
+| `CardanoAddress` | Cardano address construction and utilities | Building addresses from credentials |
+| `ICardanoWallet` | Interface definition for Cardano wallets | Type-checking and implementing custom wallets |
+
+---
+
+## Headless Wallet (Server-Side)
+
+### Create from Mnemonic
+
+```typescript
+import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";
+
+const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
+  mnemonic: "globe cupboard camera ...".split(" "),
+  networkId: 0,
+  walletAddressType: AddressType.Base,
+  fetcher: fetcher,
+});
+```
+
+The `fetcher` is needed for signing transactions — the wallet uses it to look up input information to determine which keys need to sign. Without a fetcher, signing will not work.
+
+### Create from Raw Private Key
+
+```typescript
+import { MeshCardanoHeadlessWallet, AddressType, BaseSigner } from "@meshsdk/wallet";
+
+const paymentSigner = BaseSigner.fromNormalKeyHex(
+  "d4ffb1e83d44b66849b4f16183cbf2ba1358c491cfeb39f0b66b5f811a88f182"
+);
+
+const wallet = await MeshCardanoHeadlessWallet.fromCredentialSources({
+  networkId: 0,
+  walletAddressType: AddressType.Enterprise,
+  paymentCredentialSource: {
+    type: "signer",
+    signer: paymentSigner,
+  },
+});
+```
+
+### Sign a Transaction
+
+```typescript
+// Returns the full signed transaction (ready to submit)
+const signedTx = await wallet.signTxReturnFullTx(unsignedTxHex);
+
+// Returns only the witness set CBOR (for partial signing workflows)
+const witnessSet = await wallet.signTx(unsignedTxHex);
+```
+
+### Custom Derivation Paths
+
+Use `InMemoryBip32` directly for custom key derivation:
+
+```typescript
+import { InMemoryBip32 } from "@meshsdk/wallet";
+
+const HARDENED_OFFSET = 0x80000000;
+const bip32 = await InMemoryBip32.fromMnemonic(
+  "globe cupboard camera ...".split(" ")
+);
+
+const paymentSigner = await bip32.getSigner([
+  1852 + HARDENED_OFFSET,
+  1815 + HARDENED_OFFSET,
+  0 + HARDENED_OFFSET,
+  0,
+  5, // key index 5
+]);
+```
+
+### Blind Signing with CardanoSigner
+
+For signing without wallet-level input resolution:
+
+```typescript
+import { CardanoSigner } from "@meshsdk/wallet";
+
+// Returns witness set CBOR
+const txWitnessSet = CardanoSigner.signTx(txHex, [paymentSigner]);
+
+// Returns full signed transaction CBOR
+const signedTx = CardanoSigner.signTx(txHex, [paymentSigner], true);
+```
+
+---
+
+## Browser Wallet (Client-Side)
+
+### Enable a Browser Wallet
+
+```typescript
+import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";
+
+const wallet = await MeshCardanoBrowserWallet.enable("eternl");
+```
+
+### List Installed Wallets
+
+```typescript
+const wallets = MeshCardanoBrowserWallet.getInstalledWallets();
+// Returns: Array<{ id, name, icon, version }>
+```
+
+### Common Operations
+
+```typescript
+const balance = await wallet.getBalanceMesh();           // Asset[]
+const address = await wallet.getChangeAddressBech32();   // bech32 string
+const utxos = await wallet.getUtxosMesh();               // UTxO[]
+const collateral = await wallet.getCollateralMesh();     // UTxO[]
+const networkId = await wallet.getNetworkId();           // number
+const rewards = await wallet.getRewardAddressesBech32(); // string[]
+
+// Sign and get the full transaction back (ready to submit)
+const signedTx = await wallet.signTxReturnFullTx(unsignedTxHex, partialSign);
+
+// Sign data
+const signature = await wallet.signData(addressBech32, hexPayload);
+```
+
+---
+
+## Low-Level Components
+
+### InMemoryBip32
+
+Derives Ed25519 signing keys from a BIP39 mnemonic. Keys are held in memory. You can implement your own `Bip32` class (e.g., HSM-backed) as long as it satisfies the same interface.
+
+### BaseSigner
+
+Creates signers from raw Ed25519 private keys:
+
+- `BaseSigner.fromNormalKeyHex(hex)` — from a 32-byte normal private key
+- `BaseSigner.fromExtendedKeyHex(hex)` — from a 64-byte extended private key
+
+### CardanoSigner
+
+Signs Cardano transactions given an array of `ISigner` instances. Can return either a witness set or the full signed transaction.
+
+---
+
+## CIP-30 Compatibility
+
+Both `MeshCardanoHeadlessWallet` and `MeshCardanoBrowserWallet` provide CIP-30 compatible methods: `getBalance`, `getChangeAddress`, `getNetworkId`, `getCollateral`, `getUtxos`, `getRewardAddresses`, `signTx`, `signData`, `submitTx`.
+
+**Important caveat for headless wallets:** The headless wallet simulates CIP-30 using a data provider (e.g., Blockfrost). It does not perform key derivation across multiple indices — it only derives keys at index 0 on all derivation paths (payment, stake, DRep). This means `getBalance` or `getUtxos` may return different results than a real browser wallet using the same mnemonic, since real wallets index multiple key derivations.
+
+---
+
+## CardanoHeadlessWallet vs MeshCardanoHeadlessWallet
+
+`CardanoHeadlessWallet` adheres strictly to CIP-30 return types — everything comes back as CBOR hex, which requires a serialization library to parse.
+
+`MeshCardanoHeadlessWallet` extends it with convenience methods:
+
+| Need | Base method (hex/CBOR) | Mesh method (parsed) |
+|------|----------------------|---------------------|
+| Balance | `getBalance()` → CBOR hex | `getBalanceMesh()` → `Asset[]` |
+| Address | `getChangeAddress()` → hex | `getChangeAddressBech32()` → bech32 |
+| UTxOs | `getUtxos()` → CBOR hex[] | `getUtxosMesh()` → `UTxO[]` |
+| Sign tx | `signTx()` → witness set | `signTxReturnFullTx()` → full signed tx |
+
+The same pattern applies to `CardanoBrowserWallet` vs `MeshCardanoBrowserWallet`.
+
+---
+
+## Migration from v1
+
+This package (`@meshsdk/wallet` v2) has breaking changes from the previous `MeshWallet` and `BrowserWallet` classes.
+
+**Do not attempt to upgrade without reading the migration guides.** Key breaking changes include renamed classes, swapped method parameters, changed return types, and removed methods. Many changes compile without errors but fail silently at runtime.
+
+| Migrating from | Migrating to | Guide |
+|----------------|-------------|-------|
+| `MeshWallet` (from `@meshsdk/wallet` or `@meshsdk/core`) | `MeshCardanoHeadlessWallet` | [`mesh-wallet-migration.md`](./mesh-wallet-migration.md) |
+| `BrowserWallet` (from `@meshsdk/wallet` or `@meshsdk/core`) | `MeshCardanoBrowserWallet` | [`browser-wallet-migration.md`](./browser-wallet-migration.md) |
+
+The migration guides are written for both human developers and LLM agents — they contain deterministic SEARCH/REPLACE patterns that can be applied file-by-file.