Configuration

Wallet Configuration

WalletManagerSolanaGasless accepts a seed phrase or seed bytes plus a Solana gasless wallet configuration. Beta.6 shares one Solana RPC client and one Kora paymaster client across manager-derived accounts and their read-only conversions:

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

const config = {
  provider: 'https://api.devnet.solana.com',
  commitment: 'confirmed',
  paymasterUrl: 'https://your-kora-paymaster.example',
  paymasterAddress: 'Paymaster111111111111111111111111111111111',
  paymasterToken: {
    address: 'TokenMint111111111111111111111111111111111'
  },
  transferMaxFee: 1000000n,
  transactionMaxFee: 1000000n
}

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

Account Configuration

You can also construct an owned or read-only account directly:

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

const account = new WalletAccountSolanaGasless(seedPhrase, "0'/0'", config)

const readOnlyAccount = new WalletAccountReadOnlySolanaGasless('SolanaAddress...', {
  provider: 'https://api.devnet.solana.com',
  commitment: 'confirmed',
  paymasterUrl: 'https://your-kora-paymaster.example',
  paymasterAddress: 'Paymaster111111111111111111111111111111111',
  paymasterToken: {
    address: 'TokenMint111111111111111111111111111111111'
  }
})

Read-only accounts do not accept transferMaxFee or transactionMaxFee in their public type because they cannot send transfers or sign transactions.

Configuration Options

provider

Solana RPC endpoint, an existing SolanaRpc client, or an ordered mixed list of URLs and clients for failover. This is required for balance reads, blockhash lookup, quotes, signing transactions, sending transactions, and transfers. A supplied client is reused as-is.

Type: string | SolanaRpc | Array<string | SolanaRpc>

Example:

const config = {
  provider: [
    'https://api.devnet.solana.com',
    'https://backup-solana-rpc.example'
  ]
}

rpcUrl

Deprecated alias for provider, inherited from the base Solana wallet module. New code should use provider.

Type: string | string[]

commitment

Solana commitment level used for RPC reads such as balances, blockhashes, and receipts.

Type: 'processed' | 'confirmed' | 'finalized'

paymasterUrl

Kora-compatible paymaster RPC endpoint, Kora client options object, an existing KoraClient, or an ordered mixed failover list. A supplied client is reused as-is, including an already configured failover wrapper.

Type: string | KoraClientOptions | KoraClient | Array<string | KoraClientOptions | KoraClient>

Required: Yes

Example:

const config = {
  paymasterUrl: [
    'https://primary-paymaster.example',
    { rpcUrl: 'https://backup-paymaster.example' }
  ]
}

An empty paymasterUrl array raises ValueError while constructing a manager or account. retries configures lists built by this module; it does not reconfigure an existing client or wrapper. Use RPC and paymaster clients for the same network and keep the paymaster address and fee token consistent with those services.

SolanaRpc is the return type of createSolanaRpc() from @solana/rpc. KoraClient is a runtime class from @solana/kora. If your application constructs either client, declare the corresponding direct dependency; beta.6 uses @solana/rpc@3.0.3 and @solana/kora@0.2.1.

paymasterAddress

Solana address used as the transaction fee payer. For prebuilt TransactionMessage inputs, an explicit feePayer must be absent or equal to this address.

Type: string

Required: Yes

paymasterToken

Token used by the paymaster to quote and charge fees.

Type:

type PaymasterTokenConfig = {
  address: string
}

Required: Yes

The module passes paymasterToken.address to the paymaster as the fee token and returns fees in that token's base units. For an unsigned flow, it derives the paymaster's associated token account for this mint, requires the returned payment instruction to be an SPL Token Transfer or TransferChecked to that account, and reads the instruction's encoded u64 amount instead of trusting separate quote metadata.

retries

Additional retry attempts used by failover providers when provider or paymasterUrl is an ordered list.

Type: number

Default: 3

transferMaxFee

Maximum allowed paymaster fee for transfer() calls, in the configured paymaster token's base units. transfer() throws when the quoted fee is greater than this cap.

Type: number | bigint

Required: No

Example:

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

transactionMaxFee

Maximum allowed paymaster fee for sendTransaction() and signTransaction() calls, in the configured paymaster token's base units. For unsigned inputs, the module obtains the payment instruction and checks this cap before either the account or paymaster signs, subject to the Number.MAX_SAFE_INTEGER conversion boundary above. For the exact FullySignedTransaction produced by signTransaction(), it decodes a matching embedded payment amount and checks this cap before broadcasting through Solana RPC. A fee equal to the cap is allowed; only a greater fee is rejected.

Signed quote/send raises NoSuchElementError when the payload has no payment instruction matching the effective fee token and configured paymaster destination. This check is not a complete signed-transaction validator. Independently validate untrusted payloads or reject them before this API.

Type: number | bigint

Required: No

Example:

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

Paymaster Overrides

Quote, send, sign, and transfer methods accept a second configuration object for per-call fee-token and fee-cap overrides:

const quote = await account.quoteTransfer({
  token: 'TokenMint111111111111111111111111111111111',
  recipient: 'Recipient1111111111111111111111111111111',
  amount: 1000000n
}, {
  paymasterToken: {
    address: 'AlternateFeeMint11111111111111111111111111'
  },
  transferMaxFee: 500000n
})

In 1.0.0-beta.6, overrides support paymasterToken, transferMaxFee, and transactionMaxFee. Use transferMaxFee for transfer() fee protection and transactionMaxFee for sendTransaction() or signTransaction() fee protection. quoteTransfer() and quoteSendTransaction() return estimates without enforcing either cap.

For an already signed transaction, its payment token and amount are fixed. Pass the same paymasterToken used at signing to both quoteSendTransaction(signedTransaction, config) and sendTransaction(signedTransaction, config). The effective token selects the embedded payment to decode; it does not replace that payment. A missing match raises NoSuchElementError. Signed send also reapplies transactionMaxFee before direct RPC broadcast.

Overrides whose value is undefined preserve the configured value. For example, { transactionMaxFee: undefined } does not disable an existing cap. The merge is shallow: supply a complete paymasterToken object when overriding it.

Security Considerations

• Use HTTPS Solana RPC and paymaster endpoints.
• Use RPC endpoints that serve the same Solana network when enabling failover.
• Keep paymaster tokens funded for the accounts that need sponsored transactions.
• Set transferMaxFee for token transfers and transactionMaxFee for send/sign flows when your application needs fee protection.
• Keep every trusted paymaster payment at or below Number.MAX_SAFE_INTEGER base units because beta.6's unsigned path still converts the decoded u64 through Number.
• Validate the paymaster address and paymaster token address before using them in production configuration.
• Treat Invalid payment instruction from paymaster. as a failed safety check. Do not sign, send, or retry by accepting a different destination automatically; verify the paymaster and token configuration first.
• Reject untrusted FullySignedTransaction input unless you independently validate its instructions, fee payer, payment destination, lifetime, and signatures. A matching payment instruction alone does not validate the whole payload.
• Call dispose() on owned accounts and wallet managers when private keys are no longer needed.

Need Help?