@dynamic-labs-sdk/solana 1.17.1 → 1.19.0

package/dist/index.cjs

@@ -1,9 +1,9 @@
 const require_chunk = require('./chunk-CbDLau6x.cjs');
-const require_solanaTransferAmount = require('./solanaTransferAmount-CgovN61n.cjs');
+const require_solanaTransferAmount = require('./solanaTransferAmount-B4keau5s.cjs');
 const require_assertBufferAvailable = require('./assertBufferAvailable-BPIt9Mmr.cjs');
-const require_addWaasSolanaExtension = require('./addWaasSolanaExtension-av0ucGCH.cjs');
-require('./createWalletProviderFromSolanaStandardWallet-CN-opURQ.cjs');
-const require_addSolanaWalletStandardExtension = require('./addSolanaWalletStandardExtension-Dtf-b3fq.cjs');
+const require_addWaasSolanaExtension = require('./addWaasSolanaExtension-wH_cvxuL.cjs');
+require('./createWalletProviderFromSolanaStandardWallet-Bt5TP7Lt.cjs');
+const require_addSolanaWalletStandardExtension = require('./addSolanaWalletStandardExtension-CyYa03dG.cjs');
 let _dynamic_labs_sdk_assert_package_version = require("@dynamic-labs-sdk/assert-package-version");
 let _dynamic_labs_sdk_client_core = require("@dynamic-labs-sdk/client/core");
 let _dynamic_labs_sdk_client = require("@dynamic-labs-sdk/client");
@@ -24,7 +24,16 @@ tweetnacl = require_chunk.__toESM(tweetnacl);
 * and the Dynamic WaaS Solana extension, enabling support for all Solana wallet types
 * including standard wallets and embedded wallets managed by Dynamic's infrastructure.
 *
+* @example
+* ```ts
+* const client = createDynamicClient({ environmentId: 'env-123' });
+* addSolanaExtension(client);
+* ```
+*
 * @param [client] - The Dynamic client instance. Only required when using multiple Dynamic clients.
+* @returns void
+* @see isSolanaWalletAccount
+* @see isSolanaNetworkProvider
 * @notInstrumented
 */
 const addSolanaExtension = (client = (0, _dynamic_labs_sdk_client_core.getDefaultClient)()) => {
@@ -38,8 +47,17 @@ const addSolanaExtension = (client = (0, _dynamic_labs_sdk_client_core.getDefaul
 /**
 * Type guard function to check if a network provider is a Solana network provider.
 *
+* @example
+* ```ts
+* if (isSolanaNetworkProvider(networkProvider)) {
+*   const connection = getSolanaConnection({ networkData });
+* }
+* ```
+*
 * @param networkProvider - The network provider to check.
 * @returns True if the network provider is a Solana network provider, false otherwise.
+* @see isSolanaWalletAccount
+* @see addSolanaExtension
 * @notInstrumented
 */
 const isSolanaNetworkProvider = (networkProvider) => networkProvider.chain === "SOL";
@@ -58,11 +76,22 @@ const sleep = (ms) => new Promise((resolve) => {
 * and querying the network. It handles both legacy Transaction and VersionedTransaction
 * formats and includes retry logic for network requests.
 *
+* @example
+* ```ts
+* const feeData = await calculateSolanaTransactionFee({
+*   transaction,
+*   networkData,
+*   nativeTokenPriceUsd: 150,
+* });
+* ```
+*
 * @param params.transaction - The Solana transaction to estimate fees for.
 * @param params.networkData - Network configuration for RPC connection.
 * @param params.nativeTokenPriceUsd - Optional USD price of SOL for fee conversion.
 * @returns Fee data in lamports and human-readable SOL format.
 * @throws {FeeEstimationFailedError} If fee retrieval fails after retries.
+* @see simulateSolanaTransaction
+* @see getSolanaConnection
 * @notInstrumented
 */
 const calculateSolanaTransactionFee = async ({ transaction, networkData, nativeTokenPriceUsd }) => {
@@ -141,6 +170,8 @@ const calculateSolanaTransactionFee = async ({ transaction, networkData, nativeT
 * @throws {InvalidParamError} If wallet account is not a Solana account.
 * @throws {SimulationFailedError} If the simulation API call fails.
 * @throws {FeeEstimationFailedError} If includeFees is true and fee calculation fails.
+* @see calculateSolanaTransactionFee
+* @see isSolanaWalletAccount
 * @notInstrumented
 */
 const simulateSolanaTransaction = async ({ walletAccount, transaction, includeFees = false }, client = (0, _dynamic_labs_sdk_client.getDefaultClient)()) => {
@@ -335,18 +366,368 @@ const broadcastPhantomEvent = ({ args, event }, client) => {
 	});
 };
 
+//#endregion
+//#region src/phantomRedirect/errors/PhantomInvalidEncryptionPublicKeyError.ts
+var PhantomInvalidEncryptionPublicKeyError = class extends _dynamic_labs_sdk_client.BaseError {
+	constructor() {
+		super({
+			cause: null,
+			code: "phantom_invalid_encryption_public_key_error",
+			docsUrl: null,
+			name: "PhantomInvalidEncryptionPublicKeyError",
+			shortMessage: "Invalid Phantom encryption public key (low-order point rejected)."
+		});
+	}
+};
+
 //#endregion
 //#region src/phantomRedirect/utils/crypto/createNaClSharedSecret/createNaClSharedSecret.ts
 /**
+* The length, in bytes, of a Curve25519 public key.
+*/
+const CURVE25519_PUBLIC_KEY_LENGTH = 32;
+/**
+* The complete set of known Curve25519 low-order point encodings.
+*
+* A malicious Phantom redirect can supply one of these as
+* `phantom_encryption_public_key`. X25519 with a low-order base point produces
+* a small, universally-known shared secret (independent of our secret key),
+* letting an attacker decrypt/forge the connect response and overwrite the
+* connected wallet address. We reject them before deriving the box secret.
+*
+* Source: RFC 7748 / the canonical list of the 8 Curve25519 low-order points.
+*/
+const CURVE25519_LOW_ORDER_POINTS = [
+	new Uint8Array([
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0
+	]),
+	new Uint8Array([
+		1,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0
+	]),
+	new Uint8Array([
+		224,
+		235,
+		122,
+		124,
+		59,
+		65,
+		184,
+		174,
+		22,
+		86,
+		227,
+		250,
+		241,
+		159,
+		196,
+		106,
+		218,
+		9,
+		141,
+		235,
+		156,
+		50,
+		177,
+		253,
+		134,
+		98,
+		5,
+		22,
+		95,
+		73,
+		184,
+		0
+	]),
+	new Uint8Array([
+		95,
+		156,
+		149,
+		188,
+		163,
+		80,
+		140,
+		36,
+		177,
+		208,
+		177,
+		85,
+		156,
+		131,
+		239,
+		91,
+		4,
+		68,
+		92,
+		196,
+		88,
+		28,
+		142,
+		134,
+		216,
+		34,
+		78,
+		221,
+		208,
+		159,
+		17,
+		87
+	]),
+	new Uint8Array([
+		236,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		127
+	]),
+	new Uint8Array([
+		237,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		127
+	]),
+	new Uint8Array([
+		238,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		255,
+		127
+	]),
+	new Uint8Array([
+		205,
+		235,
+		122,
+		124,
+		59,
+		65,
+		184,
+		174,
+		22,
+		86,
+		227,
+		250,
+		241,
+		159,
+		196,
+		106,
+		218,
+		9,
+		141,
+		235,
+		156,
+		50,
+		177,
+		253,
+		134,
+		98,
+		5,
+		22,
+		95,
+		73,
+		184,
+		128
+	])
+];
+/**
+* Constant-time equality check for two byte arrays. No early-exit branches so
+* comparison duration does not leak the content being compared.
+*/
+const bytesEqual = ({ a, b }) => {
+	let diff = a.length ^ b.length;
+	const length = Math.min(a.length, b.length);
+	for (let i = 0; i < length; i += 1) diff |= a[i] ^ b[i];
+	return diff === 0;
+};
+/**
+* Validates that a decoded Curve25519 public key is safe to use for X25519 key
+* agreement, rejecting low-order / contributory points.
+*
+* Defense in depth:
+*   1. Enforce the canonical 32-byte length.
+*   2. Reject the known small set of low-order point encodings (blocklist).
+*   3. Reject any input whose raw X25519 output (`nacl.scalarMult`) is all-zero,
+*      which catches low-order inputs regardless of encoding.
+*
+* @param params.theirPublicKey - The decoded (32-byte) peer public key
+* @param params.ourSecretKey - The decoded (32-byte) local secret key
+* @throws {PhantomInvalidEncryptionPublicKeyError} If the key is invalid or low-order
+*/
+const assertValidCurve25519PublicKey = ({ theirPublicKey, ourSecretKey }) => {
+	if (theirPublicKey.length !== CURVE25519_PUBLIC_KEY_LENGTH) throw new PhantomInvalidEncryptionPublicKeyError();
+	for (const lowOrderPoint of CURVE25519_LOW_ORDER_POINTS) if (bytesEqual({
+		a: theirPublicKey,
+		b: lowOrderPoint
+	})) throw new PhantomInvalidEncryptionPublicKeyError();
+	const scalarMultOutput = tweetnacl.default.scalarMult(ourSecretKey, theirPublicKey);
+	if (bytesEqual({
+		a: scalarMultOutput,
+		b: new Uint8Array(scalarMultOutput.length)
+	})) throw new PhantomInvalidEncryptionPublicKeyError();
+};
+/**
 * Creates a shared secret for NaCl box encryption using our secret key and their public key.
 *
+* Rejects low-order / invalid Curve25519 public keys before deriving the shared
+* secret, preventing an attacker from forcing the X25519 output to a known
+* constant via a malicious `phantom_encryption_public_key`.
+*
 * @param params.ourSecretKey - Our base58-encoded secret key
 * @param params.theirPublicKey - Their base58-encoded public key
 * @returns The base58-encoded shared secret
+* @throws {PhantomInvalidEncryptionPublicKeyError} If their public key is invalid or a low-order point
 * @notInstrumented
 */
 const createNaClSharedSecret = ({ ourSecretKey, theirPublicKey }) => {
-	const sharedSecret = tweetnacl.default.box.before(bs58.default.decode(theirPublicKey), bs58.default.decode(ourSecretKey));
+	const theirPublicKeyBytes = bs58.default.decode(theirPublicKey);
+	const ourSecretKeyBytes = bs58.default.decode(ourSecretKey);
+	assertValidCurve25519PublicKey({
+		ourSecretKey: ourSecretKeyBytes,
+		theirPublicKey: theirPublicKeyBytes
+	});
+	const sharedSecret = tweetnacl.default.box.before(theirPublicKeyBytes, ourSecretKeyBytes);
 	return bs58.default.encode(sharedSecret);
 };
 
@@ -510,6 +891,17 @@ const completeAndEmitPhantomRedirectEvent = async ({ args, event }, client) => {
 * is returned to the originating tab. See the `phantomRedirectCloseTab` event
 * JSDoc for details on how to handle tab closing.
 *
+* @example
+* ```ts
+* const url = new URL(window.location.href);
+* if (await detectPhantomRedirect({ url })) {
+*   await completePhantomRedirect({ url });
+*   // Close this clone tab; the originating tab already received the result
+*   // via BroadcastChannel and will resolve its pending promise.
+*   window.close();
+* }
+* ```
+*
 * @param params.url - The callback URL received from Phantom
 * @param client - The Dynamic client instance
 * @throws {NoPendingPhantomRequestError} If no pending request is found in storage
@@ -517,6 +909,9 @@ const completeAndEmitPhantomRedirectEvent = async ({ args, event }, client) => {
 *   required encryption parameters (`phantom_encryption_public_key`, `data`,
 *   `nonce`) and does not carry an error code either
 * @throws {PhantomRedirectRejectedError} If the user rejected the request in Phantom
+* @returns void
+* @see detectPhantomRedirect
+* @see addPhantomRedirectSolanaExtension
 * @notInstrumented
 */
 const completePhantomRedirect = async ({ url }, client = (0, _dynamic_labs_sdk_client_core.getDefaultClient)()) => {
@@ -1099,9 +1494,17 @@ const createPhantomRedirectWalletProvider = ({ baseRedirectUrl, dynamicClient })
 * we fall back to checking whether a pending disconnect request exists in
 * storage.
 *
+* @example
+* ```ts
+* const url = new URL(window.location.href);
+* const isPhantomRedirect = await detectPhantomRedirect({ url });
+* ```
+*
 * @param params.url - The URL to check for Phantom redirect parameters
 * @param client - The Dynamic client instance
 * @returns A promise that resolves to true if the URL is a valid Phantom redirect, false otherwise
+* @see completePhantomRedirect
+* @see addPhantomRedirectSolanaExtension
 * @notInstrumented
 */
 const detectPhantomRedirect = async ({ url }, client = (0, _dynamic_labs_sdk_client_core.getDefaultClient)()) => {
@@ -1155,10 +1558,21 @@ const PHANTOM_REDIRECT_SOLANA_EXTENSION_KEY = "phantomRedirectSolana";
 * marker written during request initiation and does **not** emit
 * `phantomRedirectCloseTab`.
 *
+* @example
+* ```ts
+* addPhantomRedirectSolanaExtension({
+*   url: new URL(window.location.href),
+*   onCloseTab: () => window.close(),
+* });
+* ```
+*
 * @param params.url - The current page URL
 * @param params.onCloseTab - Callback invoked when the clone tab should close
 * @param params.disableAutoRedirectCompletion - Skip auto detection/completion
 * @param [client] - The Dynamic client. Only required for multiple clients.
+* @returns void
+* @see completePhantomRedirect
+* @see detectPhantomRedirect
 * @notInstrumented
 */
 const addPhantomRedirectSolanaExtension = async ({ disableAutoRedirectCompletion, onCloseTab, url }, client = (0, _dynamic_labs_sdk_client_core.getDefaultClient)()) => {
@@ -1214,11 +1628,23 @@ const addPhantomRedirectSolanaExtension = async ({ disableAutoRedirectCompletion
 //#endregion
 //#region src/signAllTransactions/signAllTransactions.ts
 /**
-* Signs multiple Solana transactions
-* @param params.transactions - The transactions to sign
-* @param params.walletAccount - The wallet account to sign the transactions with
+* Signs multiple Solana transactions in a single call.
+*
+* @example
+* ```ts
+* const { signedTransactions } = await signAllTransactions({
+*   walletAccount: solAccount,
+*   transactions: [tx1, tx2, tx3],
+* });
+* ```
+*
+* @param params.transactions - The transactions to sign.
+* @param params.walletAccount - The wallet account to sign the transactions with.
 * @param [client] - The Dynamic client instance. Only required when using multiple Dynamic clients.
-* @returns An object containing the signed transactions
+* @returns An object containing the signed transactions.
+* @throws {NotSolanaProviderError} If the wallet provider is not a Solana provider.
+* @see signTransaction
+* @see signAndSendTransaction
 * @notInstrumented
 */
 const signAllTransactions = async ({ walletAccount, transactions }, client = (0, _dynamic_labs_sdk_client.getDefaultClient)()) => {
@@ -1236,12 +1662,22 @@ const signAllTransactions = async ({ walletAccount, transactions }, client = (0,
 * Signs and sends a sponsored Solana transaction.
 * The transaction will be sponsored via Dynamic's gas sponsorship API.
 *
-* @param params.transaction - The transaction to sponsor, sign, and send
-* @param params.walletAccount - The wallet account to sign and send the transaction with
+* @example
+* ```ts
+* const { signature } = await signAndSendSponsoredTransaction({
+*   walletAccount: solAccount,
+*   transaction,
+* });
+* ```
+*
+* @param params.transaction - The transaction to sponsor, sign, and send.
+* @param params.walletAccount - The wallet account to sign and send the transaction with.
 * @param [client] - The Dynamic client instance. Only required when using multiple Dynamic clients.
-* @returns An object containing the signature
-* @throws {NotSolanaProviderError} If the wallet provider is not a Solana provider
-* @throws {MethodNotImplementedError} If the wallet provider does not implement signAndSendSponsoredTransaction
+* @returns An object containing the signature.
+* @throws {NotSolanaProviderError} If the wallet provider is not a Solana provider.
+* @throws {MethodNotImplementedError} If the wallet provider does not implement signAndSendSponsoredTransaction.
+* @see signAndSendTransaction
+* @see isSolanaGasSponsorshipEnabled
 * @notInstrumented
 */
 const signAndSendSponsoredTransaction = async ({ walletAccount, transaction, options }, client = (0, _dynamic_labs_sdk_client.getDefaultClient)()) => {
@@ -1258,11 +1694,23 @@ const signAndSendSponsoredTransaction = async ({ walletAccount, transaction, opt
 //#endregion
 //#region src/signTransaction/signTransaction.ts
 /**
-* Signs a Solana transaction
-* @param params.transaction - The transaction to sign
-* @param params.walletAccount - The wallet account to sign the transaction with
+* Signs a Solana transaction without sending it.
+*
+* @example
+* ```ts
+* const { signedTransaction } = await signTransaction({
+*   walletAccount: solAccount,
+*   transaction,
+* });
+* ```
+*
+* @param params.transaction - The transaction to sign.
+* @param params.walletAccount - The wallet account to sign the transaction with.
 * @param [client] - The Dynamic client instance. Only required when using multiple Dynamic clients.
-* @returns An object containing the signed transaction
+* @returns An object containing the signed transaction.
+* @throws {NotSolanaProviderError} If the wallet provider is not a Solana provider.
+* @see signAndSendTransaction
+* @see signAllTransactions
 * @notInstrumented
 */
 const signTransaction = async ({ walletAccount, transaction }, client = (0, _dynamic_labs_sdk_client.getDefaultClient)()) => {