@0xtrails/svm

Solana (SVM) adapter for the Trails SDK. Enables funding from a Solana wallet into any EVM chain via Relay edge payments.

Install

npm install 0xtrails @0xtrails/svm

Quick start

import { TrailsWidget, evmAdapter } from '0xtrails'
import { svmAdapter } from '@0xtrails/svm'

const adapters = [
  evmAdapter({ wallets: [{ id: 'injected', name: 'MetaMask' }] }),
  // Auto-detect Wallet Standard Solana wallets.
  svmAdapter({ rpcUrls: ['https://api.mainnet-beta.solana.com'] }),
]

export function App() {
  return (
    <TrailsWidget
      apiKey="YOUR_TRAILS_API_KEY"
      adapters={adapters}
      fundOptions={{ fundMethodsList: ['connected-wallet'] }}
      renderInline
    />
  )
}

svmAdapter

import { svmAdapter } from '@0xtrails/svm'

svmAdapter(options: SvmAdapterOptions): TrailsAdapterConfig

Returns a TrailsAdapterConfig for use in the adapters prop of TrailsWidget or TrailsProvider.

Options

| Option | Type | Description | |--------|------|-------------| | wallet | Wallet Standard wallet, standard-compatible wallet-adapter value, Kit-style wallet session, or serialized signer wallet | Optional connected Solana wallet source. Omit to auto-detect Wallet Standard wallets. Pass null to disable auto-detection. | | rpcUrls | readonly string[] | Optional RPC endpoints for auto-detection / wallet connection fallback | | preferredWalletId | string | Optional auto-detected wallet id to prefer | | silentReconnect | boolean | Whether to silently reconnect previously trusted wallets. Defaults to true. | | mobileWalletAdapter | boolean \| SvmMobileWalletAdapterOptions | Register Solana Mobile Wallet Adapter into Wallet Standard auto-detection. Defaults to enabled when wallet is omitted. Pass false to disable. | | account | Wallet Standard account | Optional explicit account | | connection | Solana RPC connection helpers | Optional RPC helpers | | chain | string | Optional Wallet Standard chain, e.g. solana:mainnet |

Serialized signer wallet

For legacy wallet libraries that require app-level bridging, pass a wallet object with Wallet Standard-style serialized transaction signing:

interface SolanaWalletContextValue {
  connected: boolean
  publicKey?: { toBase58(): string } | null
  signSerializedTransaction?: (transactionBytes: Uint8Array) => Promise<Uint8Array>
  connection?: {
    rpcEndpoint?: string
    rpcUrls?: string[]          // fallback RPC endpoints
    getLatestBlockhash?: (commitment?: string) => Promise<{ blockhash: string; lastValidBlockHeight: number }>
    sendRawTransaction: (serializedTransaction: unknown, options?: unknown) => Promise<string>
  } | null
  walletId?: string
  walletName?: string
  walletIcon?: string
  connect?: (() => Promise<void> | void) | null
  disconnect?: (() => Promise<void> | void) | null
}

This shape can be passed as svmAdapter({ wallet }). It is also compatible with wallets that expose the Wallet Standard solana:signTransaction feature.

Enabling Solana funding

Solana funding is available through the connected-wallet funding path when svmAdapter is configured:

<TrailsWidget
  apiKey={apiKey}
  adapters={[svmAdapter({ rpcUrls: ['https://api.mainnet-beta.solana.com'] })]}
  fundOptions={{
    fundMethodsList: ['connected-wallet', 'crypto-transfer'],
  }}
  renderInline
/>

Supported origin tokens: SOL, USDC, USDT, PYUSD.

Mobile Wallet Adapter

When wallet is omitted, @0xtrails/svm auto-registers Solana Mobile Wallet Adapter in supported browser contexts before listing Wallet Standard wallets. On Android Chrome over HTTPS, this adds a Mobile Wallet Adapter row that opens compatible native Solana wallets from the user's tap/click path.

svmAdapter({
  rpcUrls: ['https://api.mainnet-beta.solana.com'],
  mobileWalletAdapter: {
    enabled: true,
    appIdentity: {
      name: 'Trails Solana Mobile Example',
      // Defaults to window.location.origin in the browser.
      uri: 'https://example.com',
    },
    chains: ['solana:mainnet'],
    walletNotFoundBehavior: 'default', // or 'silent'
  },
})

Pass mobileWalletAdapter: false to keep only injected Wallet Standard detection. The adapter is not registered when you provide an explicit wallet value.

With wagmi

import { TrailsProvider } from '0xtrails'
import { wagmiAdapter } from '@0xtrails/adapter-wagmi'
import { svmAdapter } from '@0xtrails/svm'
import { WagmiProvider } from 'wagmi'

const adapters = [
  wagmiAdapter({ wagmiConfig }),
  svmAdapter({ wallet }),
]

export function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <TrailsProvider config={{ trailsApiKey: apiKey, adapters }}>
        <YourRoutes />
      </TrailsProvider>
    </WagmiProvider>
  )
}

Wallet inputs

Usually pass the host wallet directly to svmAdapter:

svmAdapter({ wallet })

wallet may be a Wallet Standard wallet, standard-compatible wallet-adapter value, Kit-style wallet session such as the wallet returned by @solana/react-hooks' useWalletConnection(), or a serialized signer wallet.

Use createSolanaWallet only when you need the adapted wallet shape yourself:

import { createSolanaWallet } from '@0xtrails/svm'

const solanaWallet = createSolanaWallet({
  wallet,
  account, // optional if the wallet already exposes accounts
  connection,
  chain: 'solana:mainnet',
})

For legacy @solana/wallet-adapter-react integrations, keep the @solana/web3.js bridge in your app and pass the resulting serialized signer as wallet:

const wallet = {
  connected,
  publicKey,
  signSerializedTransaction: async (bytes: Uint8Array) => {
    const tx = VersionedTransaction.deserialize(bytes)
    const signed = await signTransaction(tx)
    return signed.serialize()
  },
}

const adapters = [svmAdapter({ wallet })]

See apps/examples/solana-legacy-wallet-adapter for the full bridge.

For @solana/react-hooks, pass the connected session directly:

const { wallet } = useWalletConnection()
const adapters = [svmAdapter({ wallet })]

Wallet Standard inputs must expose solana:signTransaction. Kit-style wallet sessions must expose signTransaction. No @solana/web3.js transaction classes are required by @0xtrails/svm; legacy apps can bridge them before passing wallet.

License

Apache-2.0