API Reference

Imports

import WalletManagerSolanaGasless from '@tetherto/wdk-wallet-solana-gasless'

import {
  WalletAccountReadOnlySolanaGasless,
  WalletAccountSolanaGasless
} from '@tetherto/wdk-wallet-solana-gasless'

Exports

WalletManagerSolanaGasless

Derives and returns owned Solana gasless accounts from a BIP-39 seed phrase or seed bytes. Extends WalletManager from @tetherto/wdk-wallet.

Constructor

new WalletManagerSolanaGasless(
  seed: string | Uint8Array,
  config?: SolanaGaslessWalletConfig
)

Parameters:

• seed: BIP-39 mnemonic seed phrase or seed bytes.
• config: Solana RPC and Kora-compatible paymaster configuration.

Methods

getAccount

getAccount(index?: number): Promise<WalletAccountSolanaGasless>

Returns the account for m/44'/501'/index'/0'. If index is omitted, the module uses 0.

const wallet = new WalletManagerSolanaGasless(seedPhrase, config)
const account = await wallet.getAccount(0)

getAccountByPath

getAccountByPath(path: string): Promise<WalletAccountSolanaGasless>

Returns the account at a specific Solana SLIP-0010 derivation path.

const account = await wallet.getAccountByPath("0'/0'/1'")

WalletAccountSolanaGasless

Owned Solana gasless account. Extends WalletAccountReadOnlySolanaGasless and implements IWalletAccount from @tetherto/wdk-wallet.

Constructor

new WalletAccountSolanaGasless(
  seed: string | Uint8Array,
  path: string,
  config: SolanaGaslessWalletConfig
)

Parameters:

• seed: BIP-39 mnemonic seed phrase or seed bytes.
• path: SLIP-0010 derivation path, for example "0'/0'/0'".
• config: Solana RPC and Kora-compatible paymaster configuration.

Properties

Methods

getAddress

getAddress(): Promise<string>

Returns the account's base58-encoded Solana address.

sign

sign(message: string): Promise<string>

Signs a message and returns its signature.

signTransaction

signTransaction(
  tx: SolanaTransaction,
  config?: SolanaGaslessWalletPaymasterConfigOverrides
): Promise<FullySignedTransaction>

Signs a paymaster-funded transaction without broadcasting it. The module adds the paymaster payment instruction, checks the quoted payment against transactionMaxFee, signs with the account owner, asks the paymaster to sign, and returns the fully signed transaction.

The method throws when the quoted paymaster fee is greater than transactionMaxFee.

sendTransaction

sendTransaction(
  tx: SolanaTransaction | FullySignedTransaction,
  config?: SolanaGaslessWalletPaymasterConfigOverrides
): Promise<TransactionResult>

For an unsigned input, sends a paymaster-funded native transfer or prebuilt transaction message. For the exact FullySignedTransaction returned by signTransaction(), the module does not contact the paymaster: it searches for the embedded payment fee, applies transactionMaxFee, base64-encodes the signed wire transaction, and sends it through the configured Solana RPC with encoding: 'base64'.

const result = await account.sendTransaction({
  to: 'Recipient1111111111111111111111111111111',
  value: 1000000n
}, {
  transactionMaxFee: 500000n
})

console.log(result.hash)
console.log(result.fee)

The method throws when the payment fee is greater than transactionMaxFee; a fee equal to the cap is allowed. An unsigned-flow payment above Number.MAX_SAFE_INTEGER can be rounded internally before this comparison. A signed transaction retains its existing blockhash or durable nonce lifetime, payment instruction, and signatures. The method does not refresh or re-sign it.

transfer

transfer(
  options: TransferOptions,
  config?: SolanaGaslessWalletPaymasterConfigOverrides
): Promise<TransferResult>

Transfers SPL tokens through the paymaster. Native SOL transfers are handled by sendTransaction() instead.

const result = await account.transfer({
  token: 'TokenMint111111111111111111111111111111111',
  recipient: 'Recipient1111111111111111111111111111111',
  amount: 1000000n
}, {
  transferMaxFee: 500000n
})

The method throws when the quoted paymaster fee is greater than transferMaxFee.

quoteSendTransaction

quoteSendTransaction(
  tx: SolanaTransaction | FullySignedTransaction,
  config?: SolanaGaslessWalletPaymasterConfigOverrides
): Promise<Omit<TransactionResult, 'hash'>>

For an unsigned input, requests a paymaster fee quote for sendTransaction() or signTransaction() inputs. Beta.4 validates the returned SPL payment instruction but converts its u64 amount through Number; values above Number.MAX_SAFE_INTEGER can round before being returned as bigint. For a FullySignedTransaction, it does not call the paymaster or broadcast: it searches for a signed SPL token payment to the configured paymaster token account and decodes a matching u64 exactly. If there is no match, beta.4 returns 0n rather than rejecting. Neither form enforces transactionMaxFee during the quote.

quoteTransfer

quoteTransfer(
  options: TransferOptions,
  config?: SolanaGaslessWalletPaymasterConfigOverrides
): Promise<Omit<TransferResult, 'hash'>>

Quotes the paymaster fee for transfer() inputs. Quote methods return estimates and do not enforce transferMaxFee.

getTransactionReceipt

getTransactionReceipt(hash: string): Promise<SolanaTransactionReceipt | null>

Returns the native Solana transaction for a submitted signature, or null if it has not been included yet. This method is deprecated; use getTransaction() and read its transaction field for native data.

getTransaction

getTransaction(hash: string): Promise<TransactionReceipt & SolanaTransactionDetails>

Returns normalized status for a valid base58 Solana signature. processed maps to pending, confirmed maps to confirmed, and finalized maps to final. Settled receipts expose success, the slot in block, the fee when available, confirmation count, and the native transaction when returned by the configured RPC commitment.

An invalid signature throws ValueError; a well-formed signature absent from transaction history throws NoSuchElementError.

waitForTransaction

waitForTransaction(
  hash: string,
  options?: WaitForTransactionOptions
): Promise<TransactionReceipt & SolanaTransactionDetails>

Waits for the default confirmed target or for final when requested. The default polling interval is four seconds and timeout is 60 seconds. The Solana implementation does not currently emit dropped; a never-landed or evicted signature times out. Reaching the target does not prove successful execution, so inspect success.

toReadOnlyAccount

toReadOnlyAccount(): Promise<WalletAccountReadOnlySolanaGasless>

Returns a read-only account for the same address.

WalletAccountReadOnlySolanaGasless

Read-only Solana gasless account for an address. Extends WalletAccountReadOnly from @tetherto/wdk-wallet.

Constructor

new WalletAccountReadOnlySolanaGasless(
  addr: string,
  config: Omit<SolanaGaslessWalletConfig, 'transferMaxFee' | 'transactionMaxFee'>
)

Parameters:

• addr: Solana account address.
• config: Solana RPC and paymaster configuration. Read-only accounts do not accept transferMaxFee or transactionMaxFee.

Methods

Read-only and owned accounts have the same normalized transaction semantics. The package delegates these calls to the wrapped standard Solana read-only account.

Configuration Types

Normalized Transaction Types

type Finality = 'pending' | 'confirmed' | 'final' | 'dropped'
type WaitForTransactionTarget = 'confirmed' | 'final'

interface WaitForTransactionOptions {
  target?: WaitForTransactionTarget
  timeout?: number
  interval?: number
  maxPollErrors?: number
}

interface SolanaTransactionDetails {
  confirmations: number | null
  transaction: SolanaTransactionReceipt | null
}

TransactionReceipt adds hash, finality, and optional success, block, and fee fields. These types are re-exported from the package root.

SolanaGaslessWalletConfig

type SolanaGaslessWalletConfig =
  SolanaWalletConfig & SolanaGaslessWalletPaymasterConfig

Combines the base Solana wallet configuration with the required paymaster configuration.

SolanaGaslessWalletPaymasterConfig

type SolanaGaslessWalletPaymasterConfig = {
  paymasterUrl: string | KoraClientOptions | (string | KoraClientOptions)[]
  paymasterAddress: string
  paymasterToken: PaymasterTokenConfig
}

PaymasterTokenConfig

type PaymasterTokenConfig = {
  address: string
}

SolanaGaslessWalletPaymasterConfigOverrides

type SolanaGaslessWalletPaymasterConfigOverrides = Partial<
  Pick<SolanaGaslessWalletPaymasterConfig, 'paymasterToken'> &
  Pick<SolanaWalletConfig, 'transferMaxFee' | 'transactionMaxFee'>
>

Pass overrides as the second argument to quote, sign, send, or transfer methods.

ConfigurationError

The beta.4 TypeScript declarations include ConfigurationError, and the runtime uses that error name for missing required paymaster fields. The JavaScript root entrypoint does not re-export the runtime class, so JavaScript code should not import ConfigurationError from @tetherto/wdk-wallet-solana-gasless.

class ConfigurationError extends Error {
  constructor(message: string)
}

Missing paymasterUrl, paymasterAddress, or paymasterToken throws an error named ConfigurationError. An empty paymasterUrl failover list throws a plain Error.

Next Steps

Need Help?