@vue-solana/core 4.1.0 → 4.1.1

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 +93 -34
  2. package/package.json +1 -1
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
@@ -154,60 +172,85 @@ https://faucet.solana.com
154
172
  Direct subpaths:
155
173
 
156
174
  - `@vue-solana/core/action`
175
+
157
176
  - `@vue-solana/core/types`
177
+
158
178
  - `@vue-solana/core/address`
179
+
159
180
  - `@vue-solana/core/buffer-polyfill`
181
+
160
182
  - `@vue-solana/core/clusters`
183
+
161
184
  - `@vue-solana/core/errors`
185
+
162
186
  - `@vue-solana/core/ios-wallet`
187
+
163
188
  - `@vue-solana/core/kit`
189
+
164
190
  - `@vue-solana/core/mobile-wallet`
191
+
165
192
  - `@vue-solana/core/mobile-wallet-support`
193
+
166
194
  - `@vue-solana/core/rpc`
195
+
167
196
  - `@vue-solana/core/token-accounts`
197
+
168
198
  - `@vue-solana/core/solana-pay`
199
+
169
200
  - `@vue-solana/core/solana-pay-confirmation`
201
+
170
202
  - `@vue-solana/core/solana-pay-status`
203
+
171
204
  - `@vue-solana/core/timeout`
205
+
172
206
  - `@vue-solana/core/transaction`
207
+
173
208
  - `@vue-solana/core/wallet`
209
+
174
210
  - `@vue-solana/core/wallet-standard`
175
211
 
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. |
212
+ | API | Description |
213
+ | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
214
+ | `DEFAULT_CLUSTER` | Default cluster, currently `devnet`. |
215
+ | `parseAddress(value)` | Parses an `Address`, address string, ref-like `{ value }`, getter, `null`, or `undefined` into an `Address \| null`. Invalid strings throw `INVALID_ADDRESS`. |
216
+ | `createSolanaClient(config?)` | Creates a Kit client exposing `rpc`, `rpcSubscriptions`, the official transaction planner, and the official RPC transaction-sending executor. |
217
+ | `createSolanaContext(config?)` | Creates `{ cluster, endpoint, wsEndpoint, client }`. |
218
+ | `getClusterEndpoint(cluster?)` | Returns the HTTP RPC endpoint for a cluster. |
219
+ | `getClusterWebSocketEndpoint(cluster?)` | Returns the WebSocket endpoint for a cluster. |
220
+ | `getWebSocketEndpoint(endpoint)` | Converts `http`/`https` RPC URLs to `ws`/`wss` URLs. |
221
+ | `isWalletConnected(wallet)` | Checks whether a wallet is connected and has an address. |
222
+ | `assertWalletConnected(wallet)` | Throws if the wallet is not connected. |
223
+ | `assertWalletCanSignMessage(wallet)` | Throws if the wallet is disconnected or cannot sign messages. |
224
+ | `assertWalletCanSign(wallet)` | Throws if the wallet cannot sign transactions. |
225
+ | `signAndSendTransaction(client, wallet, transaction, options?)` | Signs and sends raw wire bytes (`SolanaTransaction = Uint8Array`) using a configured wallet. |
226
+ | `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. |
227
+ | `getTokenAccountsByOwner(client, owner, options?)` | Returns SPL token accounts for an owner (token and token-2022 programs by default). |
228
+ | `getTokenAccount(client, address, commitment?)` | Reads a single token account, returning `null` when it does not exist. |
229
+ | `getTokenBalance(client, mint, owner, commitment?)` | Reads the token balance for an owner's associated token account as `{ amount, decimals }`. |
230
+ | `encodeURL(fields)` | Builds a `solana:` transfer or transaction request URL from Kit `Address` values; transfer amounts are `bigint` lamports encoded as decimal SOL. |
231
+ | `parseURL(value)` | Parses a transfer request into typed `recipient`, `amount`, `splToken`, `reference`, `label`, `message`, and `memo` fields, or a transaction request `link`. Throws `ParseURLError`. |
232
+ | `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. |
233
+ | `encodeTransferRequestURL(fields)` / `encodeTransactionRequestURL(fields)` | Builds one request kind explicitly; `encodeURL()` picks the same one from the fields you pass. |
234
+ | `createRecipient(address)` / `createSPLToken(address)` / `isValidSolanaAddress(value)` | Address helpers for request fields and scanned-URL validation. |
235
+ | `createSolanaPayReference()` | Generates a reference `Address` that `getSignaturesForAddress()` can look up later. |
236
+ | `verifySolanaPayPayment(rpc, options)` | Polls the reference and verifies the settled transaction pays `expectedRecipient`, plus `expectedAmount` and `expectedTokenMint` when given. |
237
+ | `getSolanaPayPaymentStatus(rpc, reference)` | Non-verifying read: `pending` before a signature exists, `found` after one does, `error` when the RPC call fails. |
238
+ | `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. |
239
+ | `registerSolanaMobileWallet(config?)` | Registers an Android Mobile Wallet Adapter wallet through `@solana-mobile/wallet-standard-mobile`. |
240
+ | `isSolanaMobileWalletSupported()` | Android-support gate used to decide whether to lazy-load the MWA module. |
241
+ | `getSolanaIosWallets(options?)` | Builds iOS browser wallet entries (Phantom, Solflare, Backpack) as universal links. |
242
+ | `handleSolanaIosWalletCallback()` | Completes a pending iOS wallet deep-link callback after redirect. |
243
+ | `adaptSolanaStandardWallet(wallet)` | Adapts a Solana Wallet Standard wallet into `SolanaWallet`. |
244
+ | `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. |
245
+ | `getRegisteredSolanaWallets()` | Returns the Wallet Standard wallets currently registered in the app. |
246
+ | `withTimeout(promise, timeoutMs, options?)` | Races a promise against a timeout, with optional abort signal. |
247
+ | `withSolanaTimeout(promise, timeoutMs, options?)` | Solana-specific timeout wrapper with abort and error-code support. |
248
+ | `normalizeSolanaError(error)` | Normalizes an unknown error into a `SolanaError`. |
249
+ | `isSolanaActionAborted(error)` | Detects abort errors from superseded action dispatches. |
250
+
251
+ 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
252
 
199
253
  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
254
 
212
255
  ## Wallet Interface
213
256
 
@@ -233,9 +276,13 @@ The Wallet Standard adapter verifies the signature a wallet returns from `signMe
233
276
  Current wallet support:
234
277
 
235
278
  - Browser extension wallets through Wallet Standard packages.
279
+
236
280
  - Android native mobile wallets through `@solana-mobile/wallet-standard-mobile` on Android Chrome and Chrome PWAs.
281
+
237
282
  - iOS browser wallets for Phantom, Solflare, and Backpack through wallet-specific universal links.
283
+
238
284
  - Message signing when the active wallet exposes `signMessage`.
285
+
239
286
  - Manual/custom wallet objects that implement `SolanaWallet`.
240
287
 
241
288
  Planned but not supported yet:
@@ -247,7 +294,9 @@ Planned but not supported yet:
247
294
  For complete runnable Vue and Nuxt examples that use this package through the framework integrations, see:
248
295
 
249
296
  - [Live demo](https://vue-solana-docs.vercel.app/demo)
297
+
250
298
  - <a href="https://vue-solana-docs.vercel.app/examples/vue-vite" target="_blank" rel="noopener noreferrer"><code>examples/vue-vite</code></a>
299
+
251
300
  - <a href="https://vue-solana-docs.vercel.app/examples/nuxt" target="_blank" rel="noopener noreferrer"><code>examples/nuxt</code></a>
252
301
 
253
302
  ## Bundle size and lean imports
@@ -257,11 +306,17 @@ The root barrel (`@vue-solana/core`) intentionally re-exports the full `@solana/
257
306
  Size-sensitive entries can avoid pulling the whole mirror by importing the narrow subpaths instead of the root:
258
307
 
259
308
  - `@vue-solana/core/address`
309
+
260
310
  - `@vue-solana/core/errors`
311
+
261
312
  - `@vue-solana/core/timeout`
313
+
262
314
  - `@vue-solana/core/clusters`
315
+
263
316
  - `@vue-solana/core/rpc`
317
+
264
318
  - `@vue-solana/core/types`
319
+
265
320
  - `@vue-solana/core/kit` (when you explicitly want the Kit surface)
266
321
 
267
322
  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 +336,13 @@ Docs: [Vue Solana Agent Skill](https://vue-solana-docs.vercel.app/agent-skill)
281
336
  ## Caveats
282
337
 
283
338
  - Public Solana RPC endpoints are useful for development, but production apps should use dedicated RPC infrastructure.
339
+
284
340
  - 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.
341
+
285
342
  - Transactions are raw wire bytes. Build transaction messages with `@vue-solana/core/kit` (`createTransactionMessage()`, `compileTransaction()`) and serialize them before passing them to wallet flows.
343
+
286
344
  - 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.
345
+
287
346
  - Desktop native app wallets are planned but not implemented yet.
288
347
 
289
348
  ## 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.1",
4
4
  "description": "Framework-agnostic primitives for Vue Solana libraries.",
5
5
  "license": "MIT",
6
6
  "keywords": [