Solana Kit Adapter

Solana Adapter implementation powered by @solana/kit

Modern functional Solana integration for the Stablecoin Kits ecosystem

Table of Contents

• Solana Kit Adapter
  • Table of Contents
  • Overview
    • Why Solana Kit Adapter?
    • When and How Should I Use The Solana Kit Adapter?
      • I'm a developer using a kit
        • Example
      • I'm a developer making a Kit Provider
  • Installation
    • Peer Dependencies
    • Troubleshooting Peer Dependencies
      • Missing Peer Dependency Warning
      • Version Conflict
      • Choosing Between @solana/web3.js and @solana/kit
      • Using Incompatible Versions
  • Quick Start
    • 🚀 Easy Setup with Factory Methods (Recommended)
    • 🏭 Production Considerations
    • 🌐 Browser Support with Wallet Providers
    • 🔧 Advanced Manual Setup
  • Features
  • Usage Examples
    • Basic Usage with Factory Methods
    • Multiple Private Key Format Support
    • Cross-Chain Bridge (EVM → Solana)
    • Browser Wallet Integration
    • Manual Setup with @solana/kit Clients
  • Supported Networks
  • API Reference
    • Factory Methods
      • createSolanaKitAdapterFromPrivateKey(options)
      • createSolanaKitAdapterFromProvider(options)
    • Constructor Options
    • Methods
    • Additional Exports
  • Architecture
    • Key Differences from @solana/web3.js
    • Benefits of @solana/kit Architecture
    • Transaction Building Pattern
  • Integration with Stablecoin Kits
  • Development
  • Contributing
  • License

Overview

The Solana Kit Adapter is a strongly-typed implementation of the Adapter interface for the Solana blockchain. Built on top of the modern @solana/kit library (successor to @solana/web3.js), it provides type-safe, functional blockchain interactions through a unified interface designed to work seamlessly with the Bridge Kit for cross-chain USDC transfers between Solana and EVM networks, as well as any future kits for additional stablecoin operations.

Why Solana Kit Adapter?

• 🌟 @solana/kit Integration: Built using the modern, tree-shakeable @solana/kit library
• 🔗 Cross-Chain Ready: Designed for seamless integration with BridgeKit ecosystem
• 🛡️ Type-Safe: Full TypeScript support with strict type checking
• ⚡ Functional APIs: Leverages @solana/kit's functional transaction building patterns
• 🔧 Multiple Signers: Support for private key and wallet provider signers
• 📦 Tree-Shakeable: Optimized bundle sizes with selective imports
• 🎯 Action System: Comprehensive action handlers for token operations and CCTP

When and How Should I Use The Solana Kit Adapter?

I'm a developer using a kit

If you're using one of the kits to do some action, e.g. bridging from chain 'A' to chain 'B', then you only need to instantiate the adapter for your chain and pass it to the kit.

Example

const adapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!,
  chain: 'Solana',
})

See the Quick Start section below for a more in depth guide on how to use the Solana Kit Adapter.

I'm a developer making a Kit Provider

If you are making a provider for other Kit users to plug in to the kit, e.g. a BridgingProvider, and you'll need to interact with different chains, then you'll need to use the abstracted Adapter methods to execute on chain.

Installation

npm install @circle-fin/adapter-solana-kit @solana/kit @solana/web3.js
# or
yarn add @circle-fin/adapter-solana-kit @solana/kit @solana/web3.js

Peer Dependencies

This adapter requires @solana/kit and @solana/web3.js as peer dependencies, allowing you to manage the versions yourself and avoid conflicts with your existing dependencies.

Required peer dependencies:

• @solana/kit: ^3.0.0 (supports @solana/kit 3.0.0 through 3.x.x, excludes 4.x.x)
• @solana/web3.js: ^1.90.0 (supports @solana/web3.js 1.90.0 through 1.x.x, excludes 2.x.x)

Installation:

# Install the adapter and both peer dependencies
npm install @circle-fin/adapter-solana-kit @solana/kit @solana/web3.js

# Or with yarn
yarn add @circle-fin/adapter-solana-kit @solana/kit @solana/web3.js

Version Compatibility:

| Package | Range | Meaning | | ----------------- | --------- | ---------------------------------------------------------------- | | @solana/kit | ^3.0.0 | ✅ 3.0.0 through 3.x.x❌ 4.x.x and above (breaking changes) | | @solana/web3.js | ^1.90.0 | ✅ 1.90.0 through 1.x.x❌ 2.x.x and above (breaking changes) |

Benefits of Peer Dependencies:

• Reduced bundle size: Avoids duplicate installations of Solana libraries
• Version control: Use the versions that work best with your project
• Conflict prevention: No version mismatches between adapter and your code
• Flexibility: Upgrade independently when needed
• Tree-shaking: @solana/kit's modular architecture benefits from a single installation

Note: The adapter leverages the shared CCTP functionality from @core/adapter-solana. Both @solana/kit and @solana/web3.js are used directly in the adapter's source code.

Troubleshooting Peer Dependencies

Missing Peer Dependency Warning

If you see warnings like:

npm WARN @circle-fin/[email protected] requires a peer of @solana/kit@^3.0.0 but none is installed.
npm WARN @circle-fin/[email protected] requires a peer of @solana/web3.js@^1.90.0 but none is installed.

Solution: Install both peer dependencies alongside the adapter:

npm install @solana/kit @solana/web3.js

Version Conflict

If you see errors about conflicting versions:

npm ERR! Could not resolve dependency:
npm ERR! peer @solana/kit@"^3.0.0" from @circle-fin/adapter-solana-kit
npm ERR! peer @solana/web3.js@"^1.90.0" from @circle-fin/adapter-solana-kit

Solution: Ensure your project uses compatible versions:

# Check your current versions
npm list @solana/kit @solana/web3.js

# Update to compatible versions if needed
npm install @solana/kit@^3.0.0 @solana/web3.js@^1.90.0

Choosing Between @solana/web3.js and @solana/kit

If you're unsure which Solana adapter to use:

• Use @circle-fin/adapter-solana-kit if:

  • You want modern functional APIs
  • You need tree-shaking for smaller bundles
  • You're starting a new project
  • You want to leverage @solana/kit's modular architecture

• Use @circle-fin/adapter-solana if:

  • You already use @solana/web3.js in your project
  • You need compatibility with existing web3.js code
  • You're migrating an existing project

Using Incompatible Versions

If you need to use newer major versions, the adapter may not work correctly:

For @solana/kit 4.x.x or @solana/web3.js 2.x.x:

1. Stay on supported versions: Use versions within the supported ranges
   • @solana/kit: 3.0.0 - 3.x.x
   • @solana/web3.js: 1.90.0 - 1.x.x
2. Check for updates: Look for newer adapter versions that support the newer library versions
3. Report compatibility: Open an issue on the Stablecoin Kits repository

For additional help, visit our Help Desk or Discord.

Quick Start

🚀 Easy Setup with Factory Methods (Recommended)

The simplest way to get started is with our factory methods. With reliable default RPC endpoints - no need to configure Solana RPC providers!

import { createSolanaKitAdapterFromPrivateKey } from '@circle-fin/adapter-solana-kit'

// Create an adapter with built-in reliable RPC endpoints
const adapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!, // Base58, Base64, or JSON array format
  chain: 'Solana', // Automatically uses reliable public RPC endpoints
})

// Ready to use with Stablecoin Kits!
const address = await adapter.getAddress(Solana)
console.log('Connected address:', address)

✨ Key Feature: All Solana chains include reliable default RPC endpoints using @solana/kit's createSolanaRpc().

🏭 Production Considerations

⚠️ Important for Production: The factory methods use public RPC endpoints by default when no custom RPC is provided, which may have rate limits and lower reliability. For production applications, we strongly recommend providing a custom RPC client.

import { createSolanaKitAdapterFromPrivateKey } from '@circle-fin/adapter-solana-kit'
import { createSolanaRpc } from '@solana/kit'

// Production-ready setup with custom RPC endpoints
const customRpc = createSolanaRpc(
  `https://solana-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
)

const adapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!,
  chain: 'Solana',
  rpc: customRpc,
})

🌐 Browser Support with Wallet Providers

For browser environments with wallet providers like Phantom, Solflare, or Backpack:

import { createSolanaKitAdapterFromProvider } from '@circle-fin/adapter-solana-kit'

// Create an adapter from a browser wallet
const adapter = await createSolanaKitAdapterFromProvider({
  provider: window.solana, // Phantom, Solflare, etc.
  chain: 'Solana',
})

📋 Implementation Status: ✅ Fully Implemented

• ✅ Connection Management: Complete RPC proxy and signer abstraction
• ✅ Type Safety: Full TransactionSigner interface with native crypto APIs
• ✅ Error Handling: Comprehensive validation and descriptive error messages
• ✅ Wallet Integration: Complete transaction format conversion between @solana/kit and Wallet Standard

Recommendation: Use createSolanaKitAdapterFromPrivateKey() for server-side applications. Browser wallet integration follows Wallet Standard patterns.

🔧 Advanced Manual Setup

For advanced use cases requiring full control over RPC and signer:

import { SolanaKitAdapter } from '@circle-fin/adapter-solana-kit'
import { createSolanaRpc, generateKeyPairSigner } from '@solana/kit'

// Use your existing @solana/kit setup
const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com')
const signer = await generateKeyPairSigner()

// Create the adapter
const adapter = new SolanaKitAdapter({
  rpc,
  signer,
})

Features

• ✅ Full Solana compatibility - Works with Solana mainnet and devnet
• ✅ @solana/kit integration - Uses modern functional APIs with tree-shaking support
• ✅ Wallet provider support - Works with Phantom, Solflare, and other Solana wallets
• ✅ Factory methods - Easy setup with sensible defaults
• ✅ Transaction lifecycle - Complete prepare/estimate/execute workflow using @solana/kit patterns
• ✅ Type safety - Full TypeScript support with strict mode
• ✅ Cross-chain ready - Seamlessly bridge USDC between Solana and EVM chains

Usage Examples

Basic Usage with Factory Methods

import { createSolanaKitAdapterFromPrivateKey } from '@circle-fin/adapter-solana-kit'
import { BridgeKit } from '@circle-fin/bridge-kit'

// Create adapter with factory method - supports multiple key formats!
const adapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!, // Accepts Base58, Base64, or JSON array
  chain: 'Solana',
})

// Use directly with Stablecoin Kits
const kit = new BridgeKit()
const result = await kit.bridge({
  from: evmAdapter, // EVM as source
  to: adapter, // Solana as destination
  amount: '10.50',
})

Multiple Private Key Format Support

The createSolanaKitAdapterFromPrivateKey function automatically detects and handles different private key formats:

// Base58 format (most common for Solana)
const adapterBase58 = createSolanaKitAdapterFromPrivateKey({
  privateKey: '5Kk7z8gvn...', // Base58 string
  chain: 'Solana',
})

// Base64 format
const adapterBase64 = createSolanaKitAdapterFromPrivateKey({
  privateKey: 'MIGHAgEAMB...', // Base64 string
  chain: 'Solana',
})

// JSON array format (array of bytes)
const adapterArray = createSolanaKitAdapterFromPrivateKey({
  privateKey: '[1,2,3,4,5,...]', // JSON array string
  chain: 'Solana',
})

Cross-Chain Bridge (EVM → Solana)

import { createSolanaKitAdapterFromPrivateKey } from '@circle-fin/adapter-solana-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
import { BridgeKit } from '@circle-fin/bridge-kit'

const kit = new BridgeKit()

// EVM source adapter
const evmAdapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.EVM_PRIVATE_KEY as `0x${string}`,
  chain: 'Base_Sepolia',
})

// Solana destination adapter
const solanaAdapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!,
  chain: 'Solana_Devnet',
})

// Execute cross-chain bridge operation
const result = await kit.bridge({
  from: evmAdapter,
  to: solanaAdapter,
  amount: '10.50',
})

Browser Wallet Integration

import { createSolanaKitAdapterFromProvider } from '@circle-fin/adapter-solana-kit'
import { BridgeKit } from '@circle-fin/bridge-kit'

// Connect to user's Solana wallet
const adapter = await createSolanaKitAdapterFromProvider({
  provider: window.solana, // Phantom, Solflare, etc.
  chain: 'Solana',
})

// Use with Stablecoin Kits
const kit = new BridgeKit()
const result = await kit.bridge({
  from: evmAdapter,
  to: adapter,
  amount: '50.0',
})

Manual Setup with @solana/kit Clients

import { SolanaKitAdapter } from '@circle-fin/adapter-solana-kit'
import { BridgeKit } from '@circle-fin/bridge-kit'
import { createSolanaRpc, generateKeyPairSigner } from '@solana/kit'

// Initialize with your @solana/kit setup
const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com')
const signer = await generateKeyPairSigner()

const adapter = new SolanaKitAdapter({
  rpc,
  signer,
})

// Use directly with Stablecoin Kits
const kit = new BridgeKit()
const result = await kit.bridge({
  from: evmAdapter,
  to: adapter,
  amount: '10.50',
})

Supported Networks

Works with all Solana networks supported by the Stablecoin Kits:

• Solana Mainnet - Production network
• Solana Devnet - Development and testing network

API Reference

Factory Methods

createSolanaKitAdapterFromPrivateKey(options)

Create an adapter from a private key (supports multiple formats).

interface CreateAdapterFromPrivateKeyParams {
  privateKey: string // Supports Base58, Base64, or JSON array formats
  chain: SolanaChainIdentifier // 'Solana' | 'Solana_Devnet' | Blockchain enum | ChainDefinition
  rpc?: Rpc<SolanaRpcApi> // Optional pre-configured @solana/kit RPC client
}

createSolanaKitAdapterFromProvider(options)

Create an adapter from a Solana wallet provider.

interface CreateAdapterFromProviderParams {
  provider: SolanaKitWalletProvider // Phantom, Solflare, etc.
  chain: SolanaChainIdentifier // 'Solana' | 'Solana_Devnet' | Blockchain enum | ChainDefinition
  rpc?: Rpc<SolanaRpcApi> // Optional pre-configured @solana/kit RPC client
}

Constructor Options

interface SolanaKitAdapterOptions {
  getRpc: (params: {
    chain: ChainDefinition
  }) => Promise<Rpc<SolanaRpcApi>> | Rpc<SolanaRpcApi>
  getSigner: (
    ctx: OperationContext,
  ) => TransactionSigner | Promise<TransactionSigner>
}

Caching & Performance:

The adapter implements intelligent caching for both RPC clients and signers:

• RPC Caching: RPC clients are cached per chain to prevent redundant initialization
• Signer Caching: Signers are cached per operation context (based on chain and address) to avoid recreating signers for the same context
• Concurrent Safety: Both caching mechanisms handle concurrent calls gracefully, preventing duplicate initialization

This ensures optimal performance when working with multiple chains or operation contexts.

Methods

• getAddress() - Get the connected wallet address
• getChain() - Get chain information
• prepare() - Prepare transactions for execution using @solana/kit patterns
• estimate() - Estimate transaction costs
• execute() - Execute prepared transactions
• waitForTransaction() - Wait for transaction confirmation
• calculateTransactionFee() - Calculate transaction fees with optional buffer

Additional Exports

CCTP Integration:

• CctpActionBuilder, SolanaAction - CCTP action interfaces
• CoreCctpActionBuilder - Bridge between core CCTP logic and @solana/kit

Utilities:

• convertInstruction, convertInstructions - Convert web3.js instructions to @solana/kit format

You can see the implementation of each method in the Solana Kit Adapter's main implementation file.

Architecture

Key Differences from @solana/web3.js

@solana/kit represents a complete architectural shift from class-based to functional programming patterns:

| Category | @solana/web3.js (Legacy) | @solana/kit 3.0.2 (Modern) | Migration Impact | | ---------------- | ------------------------------ | ---------------------------------------- | ---------------------- | | RPC Client | new Connection(rpcUrl) | createSolanaRpc(rpcUrl) | RPC proxy objects | | Signers | Keypair.fromSecretKey() | generateKeyPairSigner() | Native crypto APIs | | Addresses | new PublicKey(string) | address(string) | Branded type system | | Transactions | Transaction.add(ix) | pipe(createTransactionMessage, append) | Functional composition | | Signing | transaction.sign(signer) | signTransactionMessageWithSigners(tx) | Self-signing messages | | Instructions | TransactionInstruction | Instruction with role metadata | Enhanced account roles | | Execution | connection.sendTransaction() | rpc.sendTransaction().send() | Proxy method calls |

Benefits of @solana/kit Architecture

• Tree-shakeable: Complete library can be tree-shaken, drastically reducing bundle size
• Native crypto: Leverages browser's built-in CryptoKeyPair and SubtleCrypto APIs
• Immutable: Functional patterns with immutable transaction message building
• Composable: Pipeline-based pipe() composition for transaction construction
• Proxy-based: Dynamic RPC method construction keeps bundle size constant regardless of API coverage

Transaction Building Pattern

import {
  pipe,
  createTransactionMessage,
  setTransactionMessageFeePayerSigner,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
  signTransactionMessageWithSigners,
} from '@solana/kit'

// Functional transaction building with immutable message construction
const transactionMessage = pipe(
  createTransactionMessage({ version: 0 }),
  (tx) => setTransactionMessageFeePayerSigner(signer, tx),
  (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
  (tx) => appendTransactionMessageInstruction(instruction, tx),
)

// Self-signing transaction messages
const signedTransaction =
  await signTransactionMessageWithSigners(transactionMessage)

// Send using RPC proxy
await rpc.sendTransaction(signedTransaction, { encoding: 'base64' }).send()

Integration with Stablecoin Kits

This adapter is designed to work seamlessly across the Stablecoin Kits ecosystem. Here's an example with the Bridge Kit:

import { BridgeKit } from '@circle-fin/bridge-kit'
import { createSolanaKitAdapterFromPrivateKey } from '@circle-fin/adapter-solana-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

const kit = new BridgeKit()

// Solana adapter
const solanaAdapter = createSolanaKitAdapterFromPrivateKey({
  privateKey: process.env.SOLANA_PRIVATE_KEY!,
  chain: 'Solana',
})

// EVM adapter
const evmAdapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.EVM_PRIVATE_KEY as `0x${string}`,
  chain: 'Ethereum',
})

// Ready for cross-chain bridging!
await kit.bridge({
  from: evmAdapter,
  to: solanaAdapter,
  amount: '50.0',
})

Development

This package is part of the Stablecoin Kits monorepo.

# Build
nx build @circle-fin/adapter-solana-kit

# Test
nx test @circle-fin/adapter-solana-kit

Contributing

This adapter follows the established patterns from the stablecoin-kits ecosystem. When implementing new features:

1. Follow @solana/kit patterns: Use functional APIs and immutable data structures
2. Maintain type safety: Ensure strict TypeScript compliance
3. Document thoroughly: Include JSDoc comments and usage examples
4. Test comprehensively: Verify both unit and integration test coverage
5. Consider cross-chain use cases: Design for interoperability with EVM chains

See CONTRIBUTING.md for detailed development guidelines.

License

This project is licensed under the Apache 2.0 License. Contact support for details.

Ready to integrate?

Join Discord • Visit our Help-Desk

Built with ❤️ by Circle