@vue-solana/core 4.1.0 → 4.1.2

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 (2) hide show
  1. package/README.md +100 -35
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -12,7 +12,9 @@ Framework-agnostic Solana primitives for Vue Solana libraries and apps that want
12
12
  This package is part of the Vue Solana family. Choose based on your app framework:
13
13
 
14
14
  - [`@vue-solana/core`](https://www.npmjs.com/package/@vue-solana/core) — framework-agnostic Solana primitives: Kit RPC client helpers, wallet types, Android MWA registration, iOS browser wallet helpers, message signing, token account reads, and transaction helpers. **Use this directly** when you want shared RPC/wallet/transaction helpers without installing a Vue plugin (non-Vue apps, server/relayer code, or your own framework integration).
15
+
15
16
  - [`@vue-solana/vue`](https://www.npmjs.com/package/@vue-solana/vue) — Vue 3 plugin plus composables for RPC, account, balance, wallet, message signing, live data, and transactions. **Use this** in plain Vue 3 apps (Vite, etc.).
17
+
16
18
  - [`@vue-solana/nuxt`](https://www.npmjs.com/package/@vue-solana/nuxt) — Nuxt module that installs the Vue plugin and auto-imports the composables. **Use this** in Nuxt 3/4 apps.
17
19
 
18
20
  This package (`@vue-solana/core`) is the foundation the other two build on; most apps should install `@vue-solana/vue` or `@vue-solana/nuxt` rather than this package directly.
@@ -24,29 +26,45 @@ Use this package directly when you want Kit RPC client helpers, shared wallet ty
24
26
  Official Solana docs:
25
27
 
26
28
  - [Solana Documentation](https://solana.com/docs)
29
+
27
30
  - [Solana RPC Methods](https://solana.com/docs/rpc)
31
+
28
32
  - [Solana Clusters](https://solana.com/docs/references/clusters)
29
33
 
30
34
  Full Vue Solana docs:
31
35
 
32
36
  - [`@vue-solana/core`](https://vue-solana-docs.vercel.app/packages/core)
37
+
33
38
  - [Live demo](https://vue-solana-docs.vercel.app/demo)
39
+
34
40
  - [Getting Started](https://vue-solana-docs.vercel.app/getting-started)
41
+
35
42
  - [Agent Skill](https://vue-solana-docs.vercel.app/agent-skill)
43
+
36
44
  - [Troubleshooting](https://vue-solana-docs.vercel.app/troubleshooting)
37
45
 
38
46
  ## Features
39
47
 
40
48
  - Cluster-aware RPC helpers with HTTP and WebSocket endpoint defaults.
49
+
41
50
  - A Kit `client` with lazy `rpc` and `rpcSubscriptions` plus the official transaction planner and RPC plan-sending executor through `createSolanaClient()` / `createSolanaContext()`.
51
+
42
52
  - Shared `SolanaConfig`, `SolanaContext`, and `SolanaWallet` types for framework integrations.
53
+
43
54
  - Wallet capability assertions for connection, message signing, and transaction signing flows.
55
+
44
56
  - Browser Wallet Standard adaptation primitives.
57
+
45
58
  - Android Mobile Wallet Adapter registration helpers.
59
+
46
60
  - iOS browser wallet link helpers for supported wallets.
61
+
47
62
  - Transaction submission and confirmation helpers.
63
+
48
64
  - SPL token account reads through Kit RPC `jsonParsed`.
49
- - Solana Pay transfer request URL encoding and parsing plus QR rendering, implemented directly on Kit.
65
+
66
+ - Solana Pay transfer request URL encoding and parsing, QR rendering, and reference-based settlement confirmation, implemented directly on Kit.
67
+
50
68
  - A framework-agnostic action state machine (`createSolanaActionStore`) for async Solana work with per-attempt `AbortSignal` handling.
51
69
 
52
70
  ## Compatibility
@@ -55,9 +73,11 @@ Full Vue Solana docs:
55
73
  | ------------- | ----------------------------------------------------------------- |
56
74
  | Runtime | ESM only (modern bundlers; Node needs ESM) |
57
75
  | TypeScript | TypeScript 5.x recommended |
58
- | Solana client | `@solana/kit@^8.5.0` (and `@solana/kit-plugin-rpc`) |
76
+ | Solana client | `@solana/kit@^8.6.0` (and `@solana/kit-plugin-rpc`) |
59
77
  | Clusters | `mainnet` (alias `mainnet-beta`), `devnet`, `testnet`, `localnet` |
60
78
 
79
+ <br>
80
+
61
81
  Since v3.0.0 this package is ESM only: there is no `require` export condition and no top-level `main`, so `require("@vue-solana/core")` fails with `No "exports" main defined`. Pin to `@vue-solana/core@^2` if you must stay on CommonJS.
62
82
 
63
83
  This package no longer depends on `@solana/web3-compat`. It depends on `@solana/kit` and `@solana/kit-plugin-rpc`, so apps do not need to install either directly for normal Vue Solana usage.
@@ -133,6 +153,8 @@ const config: SolanaConfig = {
133
153
  | `payer` | `TransactionSigner` | None | Kit client fee payer and signer for client-sent transactions. |
134
154
  | `payerSecretKey` | `string` | None | Base64 64-byte Ed25519 keypair, secret key first, resolved at client creation. |
135
155
 
156
+ <br>
157
+
136
158
  Supported clusters are `mainnet` (legacy alias `mainnet-beta`), `testnet`, `devnet`, and `localnet`. If `endpoint` is omitted, the package uses the public Solana RPC endpoint for the selected cluster. If `wsEndpoint` is omitted, it is derived from the RPC endpoint.
137
159
 
138
160
  `autoConnect` is consumed by the Vue plugin and Nuxt module. It defaults to `false`; when set to `true`, Vue Solana reconnects only a previously selected wallet identity that is discovered again on the client.
@@ -154,60 +176,87 @@ https://faucet.solana.com
154
176
  Direct subpaths:
155
177
 
156
178
  - `@vue-solana/core/action`
179
+
157
180
  - `@vue-solana/core/types`
181
+
158
182
  - `@vue-solana/core/address`
183
+
159
184
  - `@vue-solana/core/buffer-polyfill`
185
+
160
186
  - `@vue-solana/core/clusters`
187
+
161
188
  - `@vue-solana/core/errors`
189
+
162
190
  - `@vue-solana/core/ios-wallet`
191
+
163
192
  - `@vue-solana/core/kit`
193
+
164
194
  - `@vue-solana/core/mobile-wallet`
195
+
165
196
  - `@vue-solana/core/mobile-wallet-support`
197
+
166
198
  - `@vue-solana/core/rpc`
199
+
167
200
  - `@vue-solana/core/token-accounts`
201
+
168
202
  - `@vue-solana/core/solana-pay`
203
+
169
204
  - `@vue-solana/core/solana-pay-confirmation`
205
+
170
206
  - `@vue-solana/core/solana-pay-status`
207
+
171
208
  - `@vue-solana/core/timeout`
209
+
172
210
  - `@vue-solana/core/transaction`
211
+
173
212
  - `@vue-solana/core/wallet`
213
+
174
214
  - `@vue-solana/core/wallet-standard`
175
215
 
176
- | API | Description |
177
- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
178
- | `DEFAULT_CLUSTER` | Default cluster, currently `devnet`. |
179
- | `parseAddress(value)` | Parses an `Address`, address string, ref-like `{ value }`, getter, `null`, or `undefined` into an `Address \| null`. Invalid strings throw `INVALID_ADDRESS`. |
180
- | `createSolanaClient(config?)` | Creates a Kit client exposing `rpc`, `rpcSubscriptions`, the official transaction planner, and the official RPC transaction-sending executor. |
181
- | `createSolanaContext(config?)` | Creates `{ cluster, endpoint, wsEndpoint, client }`. |
182
- | `getClusterEndpoint(cluster?)` | Returns the HTTP RPC endpoint for a cluster. |
183
- | `getClusterWebSocketEndpoint(cluster?)` | Returns the WebSocket endpoint for a cluster. |
184
- | `getWebSocketEndpoint(endpoint)` | Converts `http`/`https` RPC URLs to `ws`/`wss` URLs. |
185
- | `isWalletConnected(wallet)` | Checks whether a wallet is connected and has an address. |
186
- | `assertWalletConnected(wallet)` | Throws if the wallet is not connected. |
187
- | `assertWalletCanSignMessage(wallet)` | Throws if the wallet is disconnected or cannot sign messages. |
188
- | `assertWalletCanSign(wallet)` | Throws if the wallet cannot sign transactions. |
189
- | `signAndSendTransaction(client, wallet, transaction, options?)` | Signs and sends raw wire bytes (`SolanaTransaction = Uint8Array`) using a configured wallet. |
190
- | `confirmTransactionSignature(client, signature, options?)` | Waits for a submitted signature to reach a requested commitment by polling `getSignatureStatuses`. Defaults to `confirmed` and a 60 second timeout. |
191
- | `getTokenAccountsByOwner(client, owner, options?)` | Returns SPL token accounts for an owner (token and token-2022 programs by default). |
192
- | `getTokenAccount(client, address, commitment?)` | Reads a single token account, returning `null` when it does not exist. |
193
- | `getTokenBalance(client, mint, owner, commitment?)` | Reads the token balance for an owner's associated token account as `{ amount, decimals }`. |
194
- | `encodeURL(fields)` | Builds a `solana:` transfer or transaction request URL from Kit `Address` values; transfer amounts are `bigint` lamports encoded as decimal SOL. |
195
- | `parseURL(value)` | Parses a transfer request into typed `recipient`, `amount`, `splToken`, `reference`, `label`, `message`, and `memo` fields, or a transaction request `link`. Throws `ParseURLError`. |
196
- | `createQR(url, size?, background?, color?)` | Renders a Solana Pay URL as an SVG string; `createQRDataURL()` and `createQRCanvas()` cover the other render targets. The `qrcode` encoder loads lazily. |
197
- | `createSolanaActionStore(fn)` | Wraps an async `(signal, ...args) => Promise` function into a `{ getState, subscribe, dispatch, reset, withSignal }` store; each dispatch aborts the prior in-flight call. |
216
+ | API | Description |
217
+ | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
218
+ | `DEFAULT_CLUSTER` | Default cluster, currently `devnet`. |
219
+ | `parseAddress(value)` | Parses an `Address`, address string, ref-like `{ value }`, getter, `null`, or `undefined` into an `Address \| null`. Invalid strings throw `INVALID_ADDRESS`. |
220
+ | `createSolanaClient(config?)` | Creates a Kit client exposing `rpc`, `rpcSubscriptions`, the official transaction planner, and the official RPC transaction-sending executor. |
221
+ | `createSolanaContext(config?)` | Creates `{ cluster, endpoint, wsEndpoint, client }`. |
222
+ | `getClusterEndpoint(cluster?)` | Returns the HTTP RPC endpoint for a cluster. |
223
+ | `getClusterWebSocketEndpoint(cluster?)` | Returns the WebSocket endpoint for a cluster. |
224
+ | `getWebSocketEndpoint(endpoint)` | Converts `http`/`https` RPC URLs to `ws`/`wss` URLs. |
225
+ | `isWalletConnected(wallet)` | Checks whether a wallet is connected and has an address. |
226
+ | `assertWalletConnected(wallet)` | Throws if the wallet is not connected. |
227
+ | `assertWalletCanSignMessage(wallet)` | Throws if the wallet is disconnected or cannot sign messages. |
228
+ | `assertWalletCanSign(wallet)` | Throws if the wallet cannot sign transactions. |
229
+ | `signAndSendTransaction(client, wallet, transaction, options?)` | Signs and sends raw wire bytes (`SolanaTransaction = Uint8Array`) using a configured wallet. |
230
+ | `confirmTransactionSignature(client, signature, options?)` | Waits for a submitted signature to reach a requested commitment by polling `getSignatureStatuses`. Defaults to `confirmed` and a 60 second timeout. |
231
+ | `getTokenAccountsByOwner(client, owner, options?)` | Returns SPL token accounts for an owner (token and token-2022 programs by default). |
232
+ | `getTokenAccount(client, address, commitment?)` | Reads a single token account, returning `null` when it does not exist. |
233
+ | `getTokenBalance(client, mint, owner, commitment?)` | Reads the token balance for an owner's associated token account as `{ amount, decimals }`. |
234
+ | `encodeURL(fields)` | Builds a `solana:` transfer or transaction request URL from Kit `Address` values; transfer amounts are `bigint` lamports encoded as decimal SOL. |
235
+ | `parseURL(value)` | Parses a transfer request into typed `recipient`, `amount`, `splToken`, `reference`, `label`, `message`, and `memo` fields, or a transaction request `link`. Throws `ParseURLError`. |
236
+ | `createQR(url, size?, background?, color?)` | Renders a Solana Pay URL as an SVG string; `createQRDataURL(url, options)` and `createQRCanvas(canvas, url, options)` cover the other render targets. The `qrcode` encoder loads lazily. |
237
+ | `encodeTransferRequestURL(fields)` / `encodeTransactionRequestURL(fields)` | Builds one request kind explicitly; `encodeURL()` picks the same one from the fields you pass. |
238
+ | `createRecipient(address)` / `createSPLToken(address)` / `isValidSolanaAddress(value)` | Address helpers for request fields and scanned-URL validation. |
239
+ | `createSolanaPayReference()` | Generates a reference `Address` that `getSignaturesForAddress()` can look up later. |
240
+ | `verifySolanaPayPayment(rpc, options)` | Polls the reference and verifies the settled transaction pays `expectedRecipient`, plus `expectedAmount` and `expectedTokenMint` when given. |
241
+ | `getSolanaPayPaymentStatus(rpc, reference)` | Non-verifying read: `pending` before a signature exists, `found` after one does, `error` when the RPC call fails. |
242
+ | `createSolanaActionStore(fn)` | Wraps an async `(signal, ...args) => Promise` function into a `{ getState, subscribe, dispatch, reset, withSignal }` store; each dispatch aborts the prior in-flight call. |
243
+ | `registerSolanaMobileWallet(config?)` | Registers an Android Mobile Wallet Adapter wallet through `@solana-mobile/wallet-standard-mobile`. |
244
+ | `isSolanaMobileWalletSupported()` | Android-support gate used to decide whether to lazy-load the MWA module. |
245
+ | `getSolanaIosWallets(options?)` | Builds iOS browser wallet entries (Phantom, Solflare, Backpack) as universal links. |
246
+ | `handleSolanaIosWalletCallback()` | Completes a pending iOS wallet deep-link callback after redirect. |
247
+ | `adaptSolanaStandardWallet(wallet)` | Adapts a Solana Wallet Standard wallet into `SolanaWallet`. |
248
+ | `disconnectSolanaStandardWallet(walletInfo)` | Disconnects a discovered Wallet Standard wallet through its own `standard:disconnect` feature, without adapting it. Resolves `false` if the wallet has no disconnect feature, and ignores failures after a 2 s timeout. |
249
+ | `getRegisteredSolanaWallets()` | Returns the Wallet Standard wallets currently registered in the app. |
250
+ | `withTimeout(promise, timeoutMs, options?)` | Races a promise against a timeout, with optional abort signal. |
251
+ | `withSolanaTimeout(promise, timeoutMs, options?)` | Solana-specific timeout wrapper with abort and error-code support. |
252
+ | `normalizeSolanaError(error)` | Normalizes an unknown error into a `SolanaError`. |
253
+ | `isSolanaActionAborted(error)` | Detects abort errors from superseded action dispatches. |
254
+
255
+ <br>
256
+
257
+ The Solana Pay request helpers live in `@vue-solana/core/solana-pay`; `createSolanaPayReference()` and `verifySolanaPayPayment()` live in `@vue-solana/core/solana-pay-confirmation`, and `getSolanaPayPaymentStatus()` lives in `@vue-solana/core/solana-pay-status`.
198
258
 
199
259
  The client-sent API is the official Kit `ClientWithTransactionSending` capability installed by `createSolanaClient()`. It does not use a wallet popup; `sent` is reached after the RPC executor completes its send-and-confirm operation at `confirmed` commitment. Use a `payer`, and keep funded keys in a trusted server or relayer context.
200
- | `registerSolanaMobileWallet(config?)` | Registers an Android Mobile Wallet Adapter wallet through `@solana-mobile/wallet-standard-mobile`. |
201
- | `isSolanaMobileWalletSupported()` | Android-support gate used to decide whether to lazy-load the MWA module. |
202
- | `getSolanaIosWallets(options?)` | Builds iOS browser wallet entries (Phantom, Solflare, Backpack) as universal links. |
203
- | `handleSolanaIosWalletCallback()` | Completes a pending iOS wallet deep-link callback after redirect. |
204
- | `adaptSolanaStandardWallet(wallet)` | Adapts a Solana Wallet Standard wallet into `SolanaWallet`. |
205
- | `disconnectSolanaStandardWallet(walletInfo)` | Disconnects a discovered Wallet Standard wallet through its own `standard:disconnect` feature, without adapting it. Resolves `false` if the wallet has no disconnect feature, and ignores failures after a 2 s timeout. |
206
- | `getRegisteredSolanaWallets()` | Returns the Wallet Standard wallets currently registered in the app. |
207
- | `withTimeout(promise, timeoutMs, options?)` | Races a promise against a timeout, with optional abort signal. |
208
- | `withSolanaTimeout(promise, timeoutMs, options?)` | Solana-specific timeout wrapper with abort and error-code support. |
209
- | `normalizeSolanaError(error)` | Normalizes an unknown error into a `SolanaError`. |
210
- | `isSolanaActionAborted(error)` | Detects abort errors from superseded action dispatches. |
211
260
 
212
261
  ## Wallet Interface
213
262
 
@@ -233,9 +282,13 @@ The Wallet Standard adapter verifies the signature a wallet returns from `signMe
233
282
  Current wallet support:
234
283
 
235
284
  - Browser extension wallets through Wallet Standard packages.
285
+
236
286
  - Android native mobile wallets through `@solana-mobile/wallet-standard-mobile` on Android Chrome and Chrome PWAs.
287
+
237
288
  - iOS browser wallets for Phantom, Solflare, and Backpack through wallet-specific universal links.
289
+
238
290
  - Message signing when the active wallet exposes `signMessage`.
291
+
239
292
  - Manual/custom wallet objects that implement `SolanaWallet`.
240
293
 
241
294
  Planned but not supported yet:
@@ -247,7 +300,9 @@ Planned but not supported yet:
247
300
  For complete runnable Vue and Nuxt examples that use this package through the framework integrations, see:
248
301
 
249
302
  - [Live demo](https://vue-solana-docs.vercel.app/demo)
303
+
250
304
  - <a href="https://vue-solana-docs.vercel.app/examples/vue-vite" target="_blank" rel="noopener noreferrer"><code>examples/vue-vite</code></a>
305
+
251
306
  - <a href="https://vue-solana-docs.vercel.app/examples/nuxt" target="_blank" rel="noopener noreferrer"><code>examples/nuxt</code></a>
252
307
 
253
308
  ## Bundle size and lean imports
@@ -257,11 +312,17 @@ The root barrel (`@vue-solana/core`) intentionally re-exports the full `@solana/
257
312
  Size-sensitive entries can avoid pulling the whole mirror by importing the narrow subpaths instead of the root:
258
313
 
259
314
  - `@vue-solana/core/address`
315
+
260
316
  - `@vue-solana/core/errors`
317
+
261
318
  - `@vue-solana/core/timeout`
319
+
262
320
  - `@vue-solana/core/clusters`
321
+
263
322
  - `@vue-solana/core/rpc`
323
+
264
324
  - `@vue-solana/core/types`
325
+
265
326
  - `@vue-solana/core/kit` (when you explicitly want the Kit surface)
266
327
 
267
328
  Avoid importing `@vue-solana/core/ios-wallet` or `@vue-solana/core/mobile-wallet` from lean code paths: they own `tweetnacl` and the Mobile Wallet Adapter protocol graph respectively. The `@vue-solana/core/mobile-wallet-support` subpath ships only the Android-support gate used to decide whether to lazy-load the MWA module.
@@ -281,9 +342,13 @@ Docs: [Vue Solana Agent Skill](https://vue-solana-docs.vercel.app/agent-skill)
281
342
  ## Caveats
282
343
 
283
344
  - Public Solana RPC endpoints are useful for development, but production apps should use dedicated RPC infrastructure.
345
+
284
346
  - Use `mainnet` for Solana mainnet. This is Solana's official mainnet cluster name; the legacy `mainnet-beta` spelling is still accepted and redirects to the same endpoint.
347
+
285
348
  - Transactions are raw wire bytes. Build transaction messages with `@vue-solana/core/kit` (`createTransactionMessage()`, `compileTransaction()`) and serialize them before passing them to wallet flows.
349
+
286
350
  - v2.0.0 removed `@solana/web3-compat` and the `web3` subpaths. See the [Kit Migration guide](https://vue-solana-docs.vercel.app/guides/kit-migration) for migrating from v1.
351
+
287
352
  - Desktop native app wallets are planned but not implemented yet.
288
353
 
289
354
  ## Status
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vue-solana/core",
3
- "version": "4.1.0",
3
+ "version": "4.1.2",
4
4
  "description": "Framework-agnostic primitives for Vue Solana libraries.",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -116,7 +116,7 @@
116
116
  },
117
117
  "dependencies": {
118
118
  "@solana-mobile/wallet-standard-mobile": "^0.5.3",
119
- "@solana/kit": "^8.5.0",
119
+ "@solana/kit": "^8.6.0",
120
120
  "@solana/kit-plugin-rpc": "^0.19.0",
121
121
  "@solana/wallet-standard-features": "^1.3.0",
122
122
  "@wallet-standard/app": "^1.1.1",