@meshsdk/wallet 2.0.0-beta.2 → 2.0.0-beta.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +158 -129
  2. package/dist/index.cjs +3817 -494
  3. package/dist/index.d.cts +412 -1
  4. package/dist/index.d.ts +412 -1
  5. package/dist/index.js +3827 -491
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -1,48 +1,112 @@
1
- # mesh-wallet
1
+ # @meshsdk/wallet
2
2
 
3
- `mesh-wallet` is a package whose primary usage will be to allow dapps to sign transactions and messages from a private key or mnemonic.
3
+ 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.
4
4
 
5
- It has an extended functionality to allow for a simulation of [CIP-30](https://cips.cardano.org/cip/CIP-30) endpoints using a Cardano data provider such as Blockfrost/Maestro.
5
+ ```bash
6
+ npm install @meshsdk/wallet
7
+ ```
8
+
9
+ > **Migrating from v1 (`MeshWallet` or `BrowserWallet`)?** This version has breaking changes. See:
10
+ > - [`mesh-wallet-migration.md`](./mesh-wallet-migration.md) — for `MeshWallet` to `MeshCardanoHeadlessWallet`
11
+ > - [`browser-wallet-migration.md`](./browser-wallet-migration.md) — for `BrowserWallet` to `MeshCardanoBrowserWallet`
12
+
13
+ ---
14
+
15
+ ## Table of Contents
16
+
17
+ - [Architecture Overview](#architecture-overview)
18
+ - [Exported Classes](#exported-classes)
19
+ - [Headless Wallet (Server-Side)](#headless-wallet-server-side)
20
+ - [Browser Wallet (Client-Side)](#browser-wallet-client-side)
21
+ - [Low-Level Components](#low-level-components)
22
+ - [CIP-30 Compatibility](#cip-30-compatibility)
23
+ - [CardanoHeadlessWallet vs MeshCardanoHeadlessWallet](#cardanoheadlesswallet-vs-meshcardanoheadlesswallet)
24
+ - [Migration from v1](#migration-from-v1)
25
+
26
+ ---
27
+
28
+ ## Architecture Overview
29
+
30
+ This package uses a two-tier class hierarchy for both headless and browser wallets:
31
+
32
+ - **Base classes** (`CardanoHeadlessWallet`, `CardanoBrowserWallet`) implement the CIP-30 interface strictly — all methods return raw hex/CBOR exactly as CIP-30 specifies.
33
+ - **Mesh classes** (`MeshCardanoHeadlessWallet`, `MeshCardanoBrowserWallet`) extend the base classes with convenience methods (`*Bech32()`, `*Mesh()`, `signTxReturnFullTx()`) that return human-friendly formats.
34
+
35
+ **For most use cases, use the Mesh classes.** The base classes are for advanced users who need raw CIP-30 output.
36
+
37
+ ---
6
38
 
7
- NOTE: These are not a perfect replication of CIP-30 endpoints, CIP-30 requires a dedicated node and indexer realistically. The wallet therefore does not do any key derivations, and will only by default, derive keys for index 0 on all related derivation paths (payment, stake, drep).
39
+ ## Exported Classes
8
40
 
9
- It is possible that when querying balance for example, the same mnemonic will produce different results to a real wallet implementation, since real wallets will index multiple key derivations and search on-chain
41
+ | Class | Purpose | Use When |
42
+ |-------|---------|----------|
43
+ | `MeshCardanoHeadlessWallet` | Full-featured headless wallet with convenience methods | Server-side signing, backend transaction building, testing |
44
+ | `CardanoHeadlessWallet` | CIP-30 strict headless wallet (raw hex/CBOR returns) | You need raw CIP-30 output without conversion |
45
+ | `MeshCardanoBrowserWallet` | Full-featured browser wallet wrapper with convenience methods | dApp frontend integration with browser wallets (Eternl, Nami, etc.) |
46
+ | `CardanoBrowserWallet` | CIP-30 strict browser wallet wrapper (raw hex/CBOR returns) | You need raw CIP-30 passthrough from browser wallets |
47
+ | `InMemoryBip32` | BIP32 key derivation from mnemonic (keys stored in memory) | Deriving payment/stake/DRep keys from a mnemonic |
48
+ | `BaseSigner` | Ed25519 signer from raw private keys | Signing with raw private keys (normal or extended) |
49
+ | `CardanoAddress` | Cardano address construction and utilities | Building addresses from credentials |
50
+ | `ICardanoWallet` | Interface definition for Cardano wallets | Type-checking and implementing custom wallets |
10
51
 
11
- ## Usage
52
+ ---
12
53
 
13
- ### Signing Transactions
54
+ ## Headless Wallet (Server-Side)
14
55
 
15
- #### Deriving from mnemonic
56
+ ### Create from Mnemonic
16
57
 
17
58
  ```typescript
18
- const wallet = await MeshWallet.fromMnemonic({
19
- mnemonic:
20
- "globe cupboard camera aim congress cradle decorate enter fringe dove margin witness police coral junk genius harbor fire evolve climb rather broccoli post snack".split(
21
- " "
22
- ),
59
+ import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";
60
+
61
+ const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
62
+ mnemonic: "globe cupboard camera ...".split(" "),
23
63
  networkId: 0,
24
64
  walletAddressType: AddressType.Base,
25
65
  fetcher: fetcher,
26
66
  });
67
+ ```
68
+
69
+ 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.
70
+
71
+ ### Create from Raw Private Key
72
+
73
+ ```typescript
74
+ import { MeshCardanoHeadlessWallet, AddressType, BaseSigner } from "@meshsdk/wallet";
27
75
 
28
- wallet.signTx(txHex);
76
+ const paymentSigner = BaseSigner.fromNormalKeyHex(
77
+ "d4ffb1e83d44b66849b4f16183cbf2ba1358c491cfeb39f0b66b5f811a88f182"
78
+ );
79
+
80
+ const wallet = await MeshCardanoHeadlessWallet.fromCredentialSources({
81
+ networkId: 0,
82
+ walletAddressType: AddressType.Enterprise,
83
+ paymentCredentialSource: {
84
+ type: "signer",
85
+ signer: paymentSigner,
86
+ },
87
+ });
29
88
  ```
30
89
 
31
- The `BaseCardanoWallet` mostly needs a fetcher to function properly, because when signing a txCborHex, the wallet searches through the transaction to identify which part of the wallet needs to sign the transaction. Without a fetcher, input information cannot be obtained, and signing functionality doesn't work.
90
+ ### Sign a Transaction
32
91
 
33
- #### Blind signing
92
+ ```typescript
93
+ // Returns the full signed transaction (ready to submit)
94
+ const signedTx = await wallet.signTxReturnFullTx(unsignedTxHex);
34
95
 
35
- If you wanted to blindly sign a transaction (without first attempting to identify IF the wallet needs to sign). Then it is possible by using the more primitive classes that `BaseCardanoWallet` or `MeshWallet` was built upon.
96
+ // Returns only the witness set CBOR (for partial signing workflows)
97
+ const witnessSet = await wallet.signTx(unsignedTxHex);
98
+ ```
36
99
 
37
- #### In Memory BIP32
100
+ ### Custom Derivation Paths
38
101
 
39
- The `InMemoryBip32` Class allows users to derive keys from a mnemonic, it is denoted as "In memory" because both the mnemonic and derived keys will be stored in memory. It may be possible to create your own `Bip32` Class that doesn't store anything in memory, as long as the interface stays the same.
102
+ Use `InMemoryBip32` directly for custom key derivation:
40
103
 
41
104
  ```typescript
105
+ import { InMemoryBip32 } from "@meshsdk/wallet";
106
+
107
+ const HARDENED_OFFSET = 0x80000000;
42
108
  const bip32 = await InMemoryBip32.fromMnemonic(
43
- "globe cupboard camera aim congress cradle decorate enter fringe dove margin witness police coral junk genius harbor fire evolve climb rather broccoli post snack".split(
44
- " "
45
- )
109
+ "globe cupboard camera ...".split(" ")
46
110
  );
47
111
 
48
112
  const paymentSigner = await bip32.getSigner([
@@ -50,150 +114,115 @@ const paymentSigner = await bip32.getSigner([
50
114
  1815 + HARDENED_OFFSET,
51
115
  0 + HARDENED_OFFSET,
52
116
  0,
53
- 0,
117
+ 5, // key index 5
54
118
  ]);
119
+ ```
55
120
 
56
- paymentSigner.sign(txHash);
121
+ ### Blind Signing with CardanoSigner
122
+
123
+ For signing without wallet-level input resolution:
124
+
125
+ ```typescript
126
+ import { CardanoSigner } from "@meshsdk/wallet";
127
+
128
+ // Returns witness set CBOR
129
+ const txWitnessSet = CardanoSigner.signTx(txHex, [paymentSigner]);
130
+
131
+ // Returns full signed transaction CBOR
132
+ const signedTx = CardanoSigner.signTx(txHex, [paymentSigner], true);
57
133
  ```
58
134
 
59
- This would return the raw signature from the payment key. You can do this for any derivation paths.
135
+ ---
60
136
 
61
- #### CardanoSigner
137
+ ## Browser Wallet (Client-Side)
62
138
 
63
- The previous code snippet allows you to generate raw signatures, but in Cardano, generally a raw signature isn't very useful. CIP-30 for example, requires signatures to be wrapped in a `TransactionWitnessSet` and encoded as CBOR. To facilitate this, we have the `CardanoSigner` class.
139
+ ### Enable a Browser Wallet
64
140
 
65
141
  ```typescript
66
- const txWitnessSet = CardanoSigner.signTx(txHex, [paymentSigner]);
142
+ import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";
143
+
144
+ const wallet = await MeshCardanoBrowserWallet.enable("eternl");
67
145
  ```
68
146
 
69
- Furthermore, it might be somewhat useful to simply add the signature to the full transaction, ready for submission. There is a `returnFullTx` tag, that if set to `true` returns the entire tx CBOR hex with the signature added.
147
+ ### List Installed Wallets
70
148
 
71
149
  ```typescript
72
- const signedTx = CardanoSigner.signTx(txHex, [paymentSigner], true);
150
+ const wallets = MeshCardanoBrowserWallet.getInstalledWallets();
151
+ // Returns: Array<{ id, name, icon, version }>
73
152
  ```
74
153
 
75
- #### Other derivation paths
154
+ ### Common Operations
76
155
 
77
- The `MeshWallet` class is quite good out of the box as a single address wallet, but if you wanted to use other derivation paths, it is possible, but will be slightly more cumbersome.
156
+ ```typescript
157
+ const balance = await wallet.getBalanceMesh(); // Asset[]
158
+ const address = await wallet.getChangeAddressBech32(); // bech32 string
159
+ const utxos = await wallet.getUtxosMesh(); // UTxO[]
160
+ const collateral = await wallet.getCollateralMesh(); // UTxO[]
161
+ const networkId = await wallet.getNetworkId(); // number
162
+ const rewards = await wallet.getRewardAddressesBech32(); // string[]
163
+
164
+ // Sign and get the full transaction back (ready to submit)
165
+ const signedTx = await wallet.signTxReturnFullTx(unsignedTxHex, partialSign);
166
+
167
+ // Sign data
168
+ const signature = await wallet.signData(addressBech32, hexPayload);
169
+ ```
78
170
 
79
- `MeshWallet` has a constructor that allows custom `payment`, `staking` and `drep` credential sources. Note that these constructors do accept `scriptHash` or `ISigner` except for `payment` key.
171
+ ---
80
172
 
81
- `payment` key has to be able to be used for signing, but it is fully possible to use `scriptHash` for the staking and/or drep part. The wallet will not attempt to sign with any `scriptHash` keys, but will use them to derive the `BaseAddress` and `DrepIds`.
173
+ ## Low-Level Components
82
174
 
83
- ```typescript
84
- const paymentSigner = await bip32.getSigner([
85
- 1852 + HARDENED_OFFSET,
86
- 1815 + HARDENED_OFFSET,
87
- 0 + HARDENED_OFFSET,
88
- 0,
89
- 5,
90
- ]);
175
+ ### InMemoryBip32
91
176
 
92
- const wallet = await MeshWallet.fromCredentialSources({
93
- networkId: 0,
94
- walletAddressType: AddressType.Enterprise,
95
- paymentCredentialSource: {
96
- type: "signer",
97
- signer: paymentSigner,
98
- },
99
- });
100
- ```
177
+ 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.
101
178
 
102
- #### Raw Ed25519PrivateKey
179
+ ### BaseSigner
103
180
 
104
- It is also possible to create `BaseSigner` instances from raw `Ed25519PrivateKey`, both `fromExtendedKeyHex` and `fromNormalKeyHex` are supported.
181
+ Creates signers from raw Ed25519 private keys:
105
182
 
106
- ```typescript
107
- const paymentSigner = BaseSigner.fromNormalKeyHex(
108
- "d4ffb1e83d44b66849b4f16183cbf2ba1358c491cfeb39f0b66b5f811a88f182"
109
- );
183
+ - `BaseSigner.fromNormalKeyHex(hex)` — from a 32-byte normal private key
184
+ - `BaseSigner.fromExtendedKeyHex(hex)` — from a 64-byte extended private key
110
185
 
111
- const wallet = await MeshWallet.fromCredentialSources({
112
- networkId: 0,
113
- walletAddressType: AddressType.Enterprise,
114
- paymentCredentialSource: {
115
- type: "signer",
116
- signer: paymentSigner,
117
- },
118
- });
119
- ```
186
+ ### CardanoSigner
120
187
 
121
- ## BaseCardanoWallet vs MeshWallet
188
+ Signs Cardano transactions given an array of `ISigner` instances. Can return either a witness set or the full signed transaction.
122
189
 
123
- The `BaseCardanoWallet` class acts as the underlying CIP-30 compatible wallet implementation. It attempts to adhere to the available APIs and return types defined in CIP-30.
190
+ ---
124
191
 
125
- However, due to our experiences with Cardano development, the return types defined in CIP-30 are all in a very inconvenient format. Everything is returned in CBOR hex format, which is not very useful in its raw format, and generally has to be parsed using a serialization library to obtain it in a more readily consumable format.
192
+ ## CIP-30 Compatibility
126
193
 
127
- `MeshWallet` is an attempt to extend the `BaseCardanoWallet` in such a way that there are extra endpoints that do this parsing of the CBOR hex returns in a more readibly consumable way.
194
+ Both `MeshCardanoHeadlessWallet` and `MeshCardanoBrowserWallet` provide CIP-30 compatible methods: `getBalance`, `getChangeAddress`, `getNetworkId`, `getCollateral`, `getUtxos`, `getRewardAddresses`, `signTx`, `signData`, `submitTx`.
128
195
 
129
- Probably the most relevant of these APIs would be the difference between `signTx` and `signTxReturnFullTx`. As the name of the API suggests, `signTxReturnFullTx` returns the transaction in FULL, with the extra vkey witnesses placed into the witness set. While `signTx` returns the signatures serialized in a transaction witness set, which requires extra manipulation using a serialization library to place the signatures in the transaction's witness set before it can be submitted.
196
+ **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.
130
197
 
131
- ## CIP-30
198
+ ---
132
199
 
133
- Once a MeshWallet is set up, it is possible to use it as an instance of a CIP-30 wallet.
200
+ ## CardanoHeadlessWallet vs MeshCardanoHeadlessWallet
134
201
 
135
- ```typescript
136
- const meshWallet = await MeshWallet.fromMnemonic({
137
- networkId: 0,
138
- walletAddressType: AddressType.Base,
139
- mnemonic: mnemonic,
140
- fetcher: fetcher,
141
- });
202
+ `CardanoHeadlessWallet` adheres strictly to CIP-30 return types — everything comes back as CBOR hex, which requires a serialization library to parse.
142
203
 
143
- const meshWalletBalance = await meshWallet.getBalance();
144
- const meshWalletChangeAddress = await meshWallet.getChangeAddress();
145
- const meshWalletNetworkId = await meshWallet.getNetworkId();
146
- const meshWalletCollateral = await meshWallet.getCollateral();
147
- const meshWalletUtxos = await meshWallet.getUtxos();
148
- const meshWalletRewardAddresses = await meshWallet.getRewardAddresses();
204
+ `MeshCardanoHeadlessWallet` extends it with convenience methods:
149
205
 
150
- const meshWalletsignedData = await meshWallet.signData(
151
- meshWalletChangeAddress,
152
- "abc"
153
- );
154
- const signature = await meshWallet.signTx(transactionHex, true);
155
- ```
206
+ | Need | Base method (hex/CBOR) | Mesh method (parsed) |
207
+ |------|----------------------|---------------------|
208
+ | Balance | `getBalance()` → CBOR hex | `getBalanceMesh()` → `Asset[]` |
209
+ | Address | `getChangeAddress()` → hex | `getChangeAddressBech32()` → bech32 |
210
+ | UTxOs | `getUtxos()` → CBOR hex[] | `getUtxosMesh()` → `UTxO[]` |
211
+ | Sign tx | `signTx()` → witness set | `signTxReturnFullTx()` → full signed tx |
156
212
 
157
- ## Browser Wallet
213
+ The same pattern applies to `CardanoBrowserWallet` vs `MeshCardanoBrowserWallet`.
158
214
 
159
- `mesh-wallet` provides a class that helps with setting up Cardano Browser wallets.
215
+ ---
160
216
 
161
- Once enabled, the wallet object can be used the same way as a MeshWallet.
217
+ ## Migration from v1
162
218
 
163
- ```typescript
164
- const browserWallet = await CardanoBrowserWallet.enable("eternl");
165
-
166
- const browserBalance = await browserWallet.getBalance();
167
- const browserChangeAddress = await browserWallet.getChangeAddress();
168
- const browserCollateral = await browserWallet.getCollateral();
169
- const browserUtxos = await browserWallet.getUtxos();
170
- const browserNetworkId = await browserWallet.getNetworkId();
171
- const browserRewardAddresses = await browserWallet.getRewardAddresses();
172
-
173
- const browserSignedData = await browserWallet.signData(
174
- meshWalletChangeAddress,
175
- "abc"
176
- );
177
- const signature = await browserWallet.signTx(transactionHex, true);
178
- ```
219
+ This package (`@meshsdk/wallet` v2) has breaking changes from the previous `MeshWallet` and `BrowserWallet` classes.
179
220
 
180
- ## Mesh Browser Wallet
221
+ **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.
181
222
 
182
- `mesh-wallet` also provides a wrapper class around `CardanoBrowserWallet` called `MeshBrowserWallet` that implements all the convenient return types that might be easier to consume immediately.
223
+ | Migrating from | Migrating to | Guide |
224
+ |----------------|-------------|-------|
225
+ | `MeshWallet` (from `@meshsdk/wallet` or `@meshsdk/core`) | `MeshCardanoHeadlessWallet` | [`mesh-wallet-migration.md`](./mesh-wallet-migration.md) |
226
+ | `BrowserWallet` (from `@meshsdk/wallet` or `@meshsdk/core`) | `MeshCardanoBrowserWallet` | [`browser-wallet-migration.md`](./browser-wallet-migration.md) |
183
227
 
184
- ```typescript
185
- const meshBrowserWallet = await MeshBrowserWallet.enable("eternl");
186
-
187
- const browserBalance = await meshBrowserWallet.getBalanceMesh();
188
- const browserChangeAddress = await meshBrowserWallet.getChangeAddressBech32();
189
- const browserCollateral = await meshBrowserWallet.getCollateralMesh();
190
- const browserUtxos = await meshBrowserWallet.getUtxosMesh();
191
- const browserNetworkId = await meshBrowserWallet.getNetworkId();
192
- const browserRewardAddresses =
193
- await meshBrowserWallet.getRewardAddressesBech32();
194
-
195
- const signedTx = await meshBrowserWallet.signTxReturnFullTx(
196
- transactionHex,
197
- true
198
- );
199
- ```
228
+ 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.