diff --git a/skills/alchemy-api/SKILL.md b/skills/alchemy-api/SKILL.md index 8b1e85e..f679dd0 100644 --- a/skills/alchemy-api/SKILL.md +++ b/skills/alchemy-api/SKILL.md @@ -137,6 +137,7 @@ Developers can always create a free API key at [https://dashboard.alchemy.com/]( | Simulate tx | `alchemy_simulateAssetChanges` | `references/data-simulation-api.md` | | Create webhook | `POST /create-webhook` | `references/webhooks-details.md` | | Solana NFT data | `getAssetsByOwner` (DAS) | `references/solana-das-api.md` | +| Solana realtime events (per-account / per-program / logs / tx status) | `accountSubscribe`, `programSubscribe`, `logsSubscribe`, `signatureSubscribe` (PubSub WebSocket) | `references/solana-websocket-subscriptions.md` | | Sui objects/txs | `GetObject`, `GetTransaction` (gRPC) | `references/sui-grpc-objects-and-ledger.md` | | Sui balances | `GetBalance`, `ListBalances` (gRPC) | `references/sui-grpc-state-and-balances.md` | | Sui checkpoints stream | `SubscribeCheckpoints` (gRPC) | `references/sui-grpc-subscriptions.md` | diff --git a/skills/alchemy-api/references/node-websocket-subscriptions.md b/skills/alchemy-api/references/node-websocket-subscriptions.md index 292cae8..a6c3802 100644 --- a/skills/alchemy-api/references/node-websocket-subscriptions.md +++ b/skills/alchemy-api/references/node-websocket-subscriptions.md @@ -1,7 +1,7 @@ --- id: references/node-websocket-subscriptions.md -name: 'WebSocket Subscriptions' -description: 'Use WebSockets for real-time blockchain events without polling. Best for pending transactions, new blocks, and logs.' +name: 'WebSocket Subscriptions (EVM)' +description: 'EVM WebSocket subscriptions via `eth_subscribe`. Use for real-time pending transactions, new blocks, and logs without polling. For Solana PubSub, see `solana-websocket-subscriptions.md`.' tags: - alchemy - node-apis @@ -10,14 +10,17 @@ tags: related: - node-json-rpc.md - webhooks-details.md -updated: 2026-04-22 + - solana-websocket-subscriptions.md +updated: 2026-05-06 --- -# WebSocket Subscriptions +# WebSocket Subscriptions (EVM) -Real-time blockchain events via WebSocket. No polling required. +Real-time blockchain events via WebSocket on EVM chains. No polling required. **Base URL**: `wss://.g.alchemy.com/v2/$ALCHEMY_API_KEY` +> **Solana?** Solana uses a separate PubSub WebSocket protocol with native `*Subscribe` / `*Unsubscribe` methods (no `eth_subscribe`). See `solana-websocket-subscriptions.md`. + ## Billing & Scope Guidance Alchemy bills WebSocket subscriptions on the bandwidth they deliver, so broad streams can scale compute unit usage quickly. Keep subscriptions narrow by default: @@ -206,5 +209,6 @@ ws.on("message", (data) => { - If WebSockets are unavailable, fall back to HTTP polling with coarse intervals and backoff. ## Official Docs -- [Subscription API Overview](https://www.alchemy.com/docs/reference/subscription-api) +- [Subscription API Overview](https://www.alchemy.com/docs/reference/subscription-api) (covers EVM chains and links to Solana) - [eth_subscribe](https://www.alchemy.com/docs/chains/ethereum/ethereum-api-endpoints/eth-subscribe) +- [Solana Subscription API Endpoints](https://www.alchemy.com/docs/reference/solana-subscription-api-endpoints) — Solana PubSub is documented separately diff --git a/skills/alchemy-api/references/skill-map.md b/skills/alchemy-api/references/skill-map.md index f1d7044..130d24a 100644 --- a/skills/alchemy-api/references/skill-map.md +++ b/skills/alchemy-api/references/skill-map.md @@ -15,7 +15,7 @@ Complete index of all reference files organized by product area. Use the Endpoin | `references/node-json-rpc.md` | JSON-RPC (EVM) | Use Alchemy's EVM JSON-RPC endpoints for standard blockchain reads and writes (e.g., `eth_call`, `eth_getLogs`, `eth_sendRawTransaction`). This is the baseline for any EVM integration | | `references/node-trace-api.md` | Trace API | Trace APIs expose internal call data and state changes for transactions and blocks. Useful for analytics and auditing | | `references/node-utility-api.md` | Utility API | Convenience RPC methods that reduce round trips for common tasks like bulk transaction receipt retrieval | -| `references/node-websocket-subscriptions.md` | WebSocket Subscriptions | Use WebSockets for real-time blockchain events without polling. Best for pending transactions, new blocks, and logs | +| `references/node-websocket-subscriptions.md` | WebSocket Subscriptions (EVM) | EVM `eth_subscribe` for real-time blockchain events without polling. Best for pending transactions, new blocks, and logs. For Solana PubSub, see `solana-websocket-subscriptions.md` | ## Data | File | Name | Short Description | @@ -56,6 +56,7 @@ Complete index of all reference files organized by product area. Use the Endpoin | `references/solana-grpc-subscribe-transactions.md` | Subscribe Transactions | Transaction streams deliver raw or decoded transaction data in near real-time | | `references/solana-rpc.md` | Solana JSON-RPC | Standard Solana JSON-RPC endpoints for account, program, and transaction data | | `references/solana-wallets.md` | Solana Wallet Integration | High-level guidance for integrating Solana wallets and signing transactions | +| `references/solana-websocket-subscriptions.md` | Solana WebSocket Subscriptions (PubSub) | Native `*Subscribe` / `*Unsubscribe` PubSub methods over WebSocket for real-time account, program, log, signature, slot, and root updates | ## Sui gRPC | File | Name | Short Description | @@ -80,8 +81,8 @@ Complete index of all reference files organized by product area. Use the Endpoin | `references/wallets-gas-manager.md` | Gas Manager | Gas Manager (paymaster) enables gas sponsorship and cost control for smart wallet flows | | `references/wallets-smart-wallets.md` | Smart Wallets (concept) | Smart wallets (account abstraction) are programmable accounts with features like session keys, batched transactions, and gas sponsorship. Alchemy exposes these via the Wallet APIs product | | `references/wallets-solana-notes.md` | Solana Wallet Notes | Solana wallet integration differs from EVM. Use Solana-specific tooling and RPC semantics | -| `references/wallets-supported-chains.md` | Wallet Supported Chains | Wallet tooling may support a subset of chains compared to raw RPC. Always confirm chain support before launch | -| `references/wallets-wallet-apis.md` | Wallet APIs | High-level wallet APIs enable programmatic wallet operations such as signing, transaction preparation, or account management. This guide stays minimal and focuses on integration awareness | +| `references/wallets-supported-chains.md` | Wallet Supported Chains | Wallet APIs run on a subset of chains, with separate availability per capability (Bundler, Gas Sponsorship, ERC-20 Gas Payments, BSOs). Always confirm chain × capability before launch | +| `references/wallets-wallet-apis.md` | Wallet APIs | High-level wallet APIs for programmatic wallet operations: signing, transaction preparation, account management (including the `accountType` selector for `wallet_requestAccount`), and EIP-7702 delegation/undelegation | ## Rollups | File | Name | Short Description | diff --git a/skills/alchemy-api/references/solana-overview.md b/skills/alchemy-api/references/solana-overview.md index d869463..ad09e09 100644 --- a/skills/alchemy-api/references/solana-overview.md +++ b/skills/alchemy-api/references/solana-overview.md @@ -4,7 +4,7 @@ name: solana description: Solana-specific APIs including standard JSON-RPC, Digital Asset Standard (DAS) for NFTs and compressed assets, and wallet integration. Use when building Solana applications that need RPC access, NFT/asset queries, or Solana wallet tooling. For high-throughput streaming, see the yellowstone-grpc skill. tags: [] related: [] -updated: 2026-02-14 +updated: 2026-05-06 metadata: author: alchemyplatform version: "1.0" @@ -12,12 +12,13 @@ metadata: # Solana APIs ## Summary -Solana-specific APIs and streaming endpoints, including DAS (Digital Asset Standard) and Yellowstone gRPC. +Solana-specific APIs and streaming endpoints, including DAS (Digital Asset Standard), PubSub WebSocket subscriptions, and Yellowstone gRPC. ## References (Recommended Order) 1. [solana-rpc.md](solana-rpc.md) - Standard Solana JSON-RPC usage patterns. 2. [solana-das-api.md](solana-das-api.md) - DAS endpoints for assets and metadata. -3. [solana-wallets.md](solana-wallets.md) - Solana wallet integration notes. +3. [solana-websocket-subscriptions.md](solana-websocket-subscriptions.md) - PubSub WebSocket subscriptions (`accountSubscribe`, `programSubscribe`, `logsSubscribe`, etc.). +4. [solana-wallets.md](solana-wallets.md) - Solana wallet integration notes. ## Cross-References - `yellowstone-grpc` skill for high-throughput streaming (accounts/transactions/blocks). diff --git a/skills/alchemy-api/references/solana-websocket-subscriptions.md b/skills/alchemy-api/references/solana-websocket-subscriptions.md new file mode 100644 index 0000000..bbb2a4e --- /dev/null +++ b/skills/alchemy-api/references/solana-websocket-subscriptions.md @@ -0,0 +1,112 @@ +--- +id: references/solana-websocket-subscriptions.md +name: 'Solana WebSocket Subscriptions (PubSub)' +description: 'Solana PubSub WebSocket subscriptions for real-time account, program, log, signature, slot, and root updates. Native `*Subscribe` / `*Unsubscribe` methods, not `eth_subscribe`.' +tags: + - alchemy + - solana + - json-rpc + - websocket +related: + - solana-rpc.md + - node-websocket-subscriptions.md + - solana-grpc-overview.md +updated: 2026-05-06 +--- +# Solana WebSocket Subscriptions (PubSub) + +Solana exposes a PubSub WebSocket API alongside its standard HTTP JSON-RPC. Each subscription opens a long-lived stream that pushes notifications when on-chain state changes. + +**Base URL**: `wss://solana-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY` (or `solana-devnet`) + +Solana uses native `*Subscribe` / `*Unsubscribe` methods. There is **no** `eth_subscribe` on Solana. Each `*Subscribe` call returns a numeric `subscription` id; pass it to the matching `*Unsubscribe` to cancel the stream. + +## When to Use Which Stream +| Goal | Use | +|---|---| +| Watch one account's lamports / data change | `accountSubscribe` | +| Watch all accounts owned by a program | `programSubscribe` (always filter — see below) | +| Watch transaction logs that mention a pubkey | `logsSubscribe` | +| Wait for a single transaction to reach commitment | `signatureSubscribe` (auto-cancels after firing) | +| Track validator slot progress | `slotSubscribe` | +| Track the validator's new root slot | `rootSubscribe` | +| High-throughput indexing across the cluster | switch to Yellowstone gRPC — see `solana-grpc-overview.md` | + +## Methods + +### `accountSubscribe` / `accountUnsubscribe` +Notifies on lamports or data change for one account. + +- Params: `pubkey` (base-58), optional `{ commitment, encoding }`. +- `encoding`: `base58`, `base64`, `base64+zstd`, or `jsonParsed`. + +### `programSubscribe` / `programUnsubscribe` +Notifies on changes to any account owned by a program. **Always pair with `dataSize` and/or `memcmp` filters** — unfiltered streams produce extreme volumes and bandwidth bills. + +- Params: program `pubkey`, optional `{ commitment, encoding, filters }`. +- Filters mirror `getProgramAccounts`: `[{ dataSize: }, { memcmp: { offset, bytes } }]`. + +### `logsSubscribe` / `logsUnsubscribe` +Notifies when committed transaction logs match a filter. + +- Filter: `"all"` (excluding vote txs), `"allWithVotes"`, or `{ "mentions": [""] }` with exactly one pubkey. +- Notification payload includes `signature`, `err`, `logs[]`. + +### `signatureSubscribe` / `signatureUnsubscribe` +Notifies once when a specific transaction signature reaches the requested commitment, then auto-cancels. + +- Params: `signature` (base-58), optional `{ commitment, enableReceivedNotification }`. +- `enableReceivedNotification: true` adds an additional `received` notification before commitment. + +### `slotSubscribe` / `slotUnsubscribe` +Notifies when the validator processes a new slot. Notification payload: `{ slot, parent, root }`. No params. + +### `rootSubscribe` / `rootUnsubscribe` +Notifies when the validator sets a new root slot. Notification payload: a single slot number. No params. + +## Request Format +PubSub uses JSON-RPC 2.0 over a persistent WebSocket. After a subscribe request succeeds, the server returns the numeric subscription id in the response, then pushes notifications under a method-specific name (`accountNotification`, `logsNotification`, etc.) keyed by that id. + +```json +// subscribe +{"jsonrpc":"2.0","id":1,"method":"accountSubscribe","params":["", {"encoding":"jsonParsed","commitment":"finalized"}]} + +// subscribe response +{"jsonrpc":"2.0","result":23784,"id":1} + +// notification (later, asynchronously) +{"jsonrpc":"2.0","method":"accountNotification","params":{"result":{...},"subscription":23784}} + +// unsubscribe +{"jsonrpc":"2.0","id":2,"method":"accountUnsubscribe","params":[23784]} +``` + +## SDK Mapping (`@solana/web3.js`) +The `Connection` class wraps subscribe/unsubscribe in typed listeners. Pass `wsEndpoint` alongside the HTTP URL. + +| RPC method | `Connection` helper | Removal helper | +|---|---|---| +| `accountSubscribe` | `onAccountChange` | `removeAccountChangeListener` | +| `programSubscribe` | `onProgramAccountChange` | `removeProgramAccountChangeListener` | +| `logsSubscribe` | `onLogs` | `removeOnLogsListener` | +| `signatureSubscribe` | `onSignature` | `removeSignatureListener` (auto-removed on fire) | +| `slotSubscribe` | `onSlotChange` | `removeSlotChangeListener` | +| `rootSubscribe` | `onRootChange` | `removeRootChangeListener` | + +## Pricing +Solana PubSub subscriptions are billed by **bandwidth** — pro-rated to the byte (1 byte = 0.0002 CU). Broad streams (especially unfiltered `programSubscribe`) can scale costs quickly. Recommended controls: + +- Always filter `programSubscribe` with `dataSize` / `memcmp`. +- Use a more specific stream over a broader one (`accountSubscribe` vs `programSubscribe`, `signatureSubscribe` vs `logsSubscribe`). +- Keep payloads small: `encoding: "base64"` over `jsonParsed` when you don't need parsed data. +- Set [usage limits](https://www.alchemy.com/docs/how-to-set-usage-limits-and-alerts-for-your-account) before deploying high-volume streams. + +## Notes +- Subscriptions are stateful. Handle reconnects and resubscribe after reconnect; you may receive duplicate notifications immediately after reconnect. +- Commitment defaults to `finalized` on every subscribe method that accepts it. +- For high-throughput cluster-wide indexing, prefer Yellowstone gRPC (`solana-grpc-overview.md`) — PubSub is a per-connection RPC, not a firehose. + +## Official Docs +- [Solana Subscription API Endpoints](https://www.alchemy.com/docs/reference/solana-subscription-api-endpoints) +- [Compute Unit Costs — Solana WebSocket Subscriptions](https://www.alchemy.com/docs/reference/compute-unit-costs#solana-websocket-subscriptions) +- [Solana Foundation PubSub reference](https://solana.com/docs/rpc/websocket) diff --git a/skills/alchemy-api/references/wallets-supported-chains.md b/skills/alchemy-api/references/wallets-supported-chains.md index 2e3c13f..33850b8 100644 --- a/skills/alchemy-api/references/wallets-supported-chains.md +++ b/skills/alchemy-api/references/wallets-supported-chains.md @@ -1,25 +1,50 @@ --- id: references/wallets-supported-chains.md name: 'Wallet Supported Chains' -description: 'Wallet tooling may support a subset of chains compared to raw RPC. Always confirm chain support before launch.' +description: 'Wallet APIs are exposed on a subset of chains, with separate availability per capability (Bundler, Gas Sponsorship, ERC-20 Gas Payments, BSOs). Always confirm chain × capability before launch.' tags: - alchemy - wallets related: - operational-supported-networks.md -updated: 2026-02-05 + - wallets-wallet-apis.md + - wallets-bundler.md + - wallets-gas-manager.md +updated: 2026-05-06 --- # Wallet Supported Chains ## Summary -Wallet tooling may support a subset of chains compared to raw RPC. Always confirm chain support before launch. +Wallet APIs (formerly "Smart Wallets") run on a subset of chains compared to raw RPC, and support varies *per capability* on each chain. Always confirm the specific capability you need is enabled on the chain you're targeting before launch. -## Guidance -- Check Alchemy dashboard for wallet-specific chain availability. -- Test on testnet before enabling production. +## Capability Axes +The supported-chains table lists each chain × four capability columns: + +- **Bundler** — submit ERC-4337 user operations on this chain. +- **Gas Sponsorship** — Gas Manager (paymaster) policies cover user op gas in the chain's native token. +- **ERC-20 Gas Payments** — users pay gas in a stable / project token instead of the native asset. +- **BSOs (Bundler Sponsored Operations)** — sponsored ops without a Gas Manager policy. Currently NOT available on MegaETH or Solana. + +Login and signer authentication are chain-agnostic — they work everywhere the SDK runs. The four columns above gate transaction sending and sponsorship. + +## Routing Logic +- "Does Wallet APIs work on chain X?" → check the [supported chains table](https://www.alchemy.com/docs/wallets/resources/supported-chains). Don't guess — the table changes weekly. +- "Can I sponsor gas on chain X?" → confirm the Gas Sponsorship column. +- "Can users pay gas in USDC on chain X?" → confirm the ERC-20 Gas Payments column. +- "Why doesn't BSO work on MegaETH / Solana?" → BSOs aren't enabled there yet (Gas Manager + Bundler are). +- Solana is supported for Gas Sponsorship only — no Bundler, no ERC-20 gas, no BSOs. +- Need a chain that isn't listed? Email `wallets@alchemy.com` or use the chain support [request form](https://alchemy.chilipiper.com/router/wallet-services-chain-support-requests). + +## Integration Notes +- Use the same Alchemy app across multiple chains; see the [multi-chain setup](https://www.alchemy.com/docs/wallets/recipes/multi-chain-setup) recipe. +- The chain identifier (e.g. `base-mainnet`) is what the SDK uses to construct RPC URLs of the form `https://.g.alchemy.com/v2/`. +- Always test on testnet (Sepolia variants, Solana Devnet, etc.) before enabling production. ## Related Files -- `operational-supported-networks.md` +- `operational-supported-networks.md` — node/RPC-level chain support (broader set). +- `wallets-wallet-apis.md` — the Wallet APIs surface that runs on these chains. +- `wallets-bundler.md`, `wallets-gas-manager.md` — capability-specific details. ## Official Docs -- [Supported Chains](https://www.alchemy.com/docs/reference/node-supported-chains) +- [Wallet APIs supported chains](https://www.alchemy.com/docs/wallets/resources/supported-chains) +- [Node Supported Chains](https://www.alchemy.com/docs/reference/node-supported-chains) diff --git a/skills/alchemy-api/references/wallets-wallet-apis.md b/skills/alchemy-api/references/wallets-wallet-apis.md index abcf9c0..11ee699 100644 --- a/skills/alchemy-api/references/wallets-wallet-apis.md +++ b/skills/alchemy-api/references/wallets-wallet-apis.md @@ -8,7 +8,7 @@ tags: related: - wallets-account-kit.md - operational-auth-and-keys.md -updated: 2026-04-22 +updated: 2026-05-06 --- # Wallet APIs @@ -20,6 +20,20 @@ High-level wallet APIs enable programmatic wallet operations such as signing, tr - Delegated signing or session-based flows (including existing session keys — see [Legacy session keys with Wallet APIs](https://www.alchemy.com/docs/wallets/smart-wallets/session-keys/legacy-session-keys) for migrating pre-existing session-key setups). - EIP-7702 account delegation and undelegation. +## Account Types (`wallet_requestAccount`) +Pass `accountType` inside `creationHint` to select which account `wallet_requestAccount` returns. Default is `"sma-b"` (Modular Account v2). Legacy types are enabled for everyone — no support ticket needed. + +| `accountType` | Account | Use when | +|---|---|---| +| `"sma-b"` | Modular Account v2 (MAv2) | Default. New SCA integrations. Single owner. | +| `"7702"` | Smart EOA (EIP-7702 MAv2) | Delegating an existing EOA. Default for EIP-7702 mode in the SDK. | +| `"la-v2"` | Light Account v2 | Backwards compat with existing v2 deployments. Single owner. | +| `"la-v2-multi-owner"` | Light Account v2 (Multi-Owner) | Backwards compat. Requires `initialOwners` array in `creationHint`. | +| `"ma-v1-multi-owner"` | Modular Account v1 (Multi-Owner) | Backwards compat with v1 multi-owner deployments. | +| `"la-v1.1.0"` / `"la-v1.0.2"` / `"la-v1.0.1"` | Light Account v1.x | Backwards compat with specific v1 versions. | + +**Routing logic for migrations:** if a customer is on a non-MAv2 account type (Light Account, MAv1) and asks how to keep using it via Wallet APIs, the answer is to pass the matching `accountType` value when calling `wallet_requestAccount` — not to enable it via support. Wallet APIs is no longer "MAv2 only." + ## EIP-7702 Undelegation Undelegation removes smart contract delegation from an EIP-7702 account by delegating to the zero address (`0x0000...0000`), restoring it to a plain EOA. Key details: - Gas is sponsored through a **BSO (Bundler Sponsorship) policy** — the account does not need native tokens.