gill: A Comprehensive JavaScript/TypeScript Library for Solana Blockchain Development

Introduction to gill

If you’re looking to build applications on the Solana blockchain, having the right tools can make all the difference. gill is a JavaScript/TypeScript client library designed specifically for interacting with the Solana network. Whether you’re working in Node.js, building a web application, developing with React Native, or any other JavaScript environment, gill provides the essential functionality you need to connect with Solana’s powerful blockchain capabilities.

Built on top of the modern JavaScript libraries developed by Anza called @solana/kit (previously known as “web3.js v2”), gill maintains full compatibility with kit while offering additional features and simplifications that make development more straightforward. This means you can easily transition from using kit to gill without losing any functionality, while gaining access to enhanced capabilities.

Why Choose gill for Solana Development?

When compared to using @solana/kit directly, gill offers several advantages that can significantly improve your development experience:

• Simplified API: gill provides a more intuitive and developer-friendly interface for common blockchain operations
• Built-in transaction builders: Pre-configured templates for common tasks like token creation and transfers
• Debug mode: Enhanced troubleshooting capabilities with detailed logging
• Reduced boilerplate: Less code required for standard operations
• Tree-shakable architecture: Only include the components you actually use in your final bundle

These features combine to create a more efficient development workflow, allowing you to focus on building your application rather than wrestling with complex blockchain interactions.

Getting Started with gill

Installation Process

Adding gill to your project is straightforward with any of the major JavaScript package managers:

# Using npm
npm install gill

# Using pnpm
pnpm add gill

# Using yarn
yarn add gill

If you’re currently using @solana/kit in your project, transitioning to gill is seamless. Simply replace your import statements while keeping all your existing functionality intact. This backward compatibility ensures a smooth migration path while immediately giving you access to gill’s additional features.

Establishing a Solana Connection

The foundation of any Solana application is the connection to the blockchain network. gill simplifies this process with the createSolanaClient function:

import { createSolanaClient } from "gill";

// Connect to mainnet
const { rpc, rpcSubscriptions, sendAndConfirmTransaction } = createSolanaClient({
  urlOrMoniker: "mainnet",
});

// Alternatively, connect to devnet
const devnetClient = createSolanaClient({
  urlOrMoniker: "devnet",
});

// Or use a custom RPC endpoint
const customClient = createSolanaClient({
  urlOrMoniker: "https://your-custom-rpc-provider.com",
});

It’s important to note that while using network monikers like “mainnet” or “devnet” is convenient for development, these public endpoints are subject to rate limits. For production applications, you should use a dedicated RPC provider that can offer better performance and reliability.

Making RPC Calls

Once connected, you can make various JSON RPC method calls to interact with the Solana blockchain:

// Get the current slot
const slot = await rpc.getSlot().send();

// Retrieve the latest blockhash
const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();

// Fetch account information
const accountInfo = await rpc.getAccountInfo(accountAddress).send();

All RPC calls require explicitly calling the .send() method to actually transmit the request to the RPC provider and receive a response. This design gives you control over when network requests are made.

For more advanced scenarios, you can pass additional configuration options to your RPC calls:

// Using AbortController for request cancellation
const abortController = new AbortController();

// Cancel the request if needed
setTimeout(() => {
  abortController.abort();
}, 5000); // Cancel after 5 seconds

const slot = await rpc.getSlot().send({ 
  abortSignal: abortController.signal 
});

Key Management with gill

Generating KeyPairs and Signers

Most operations on the Solana blockchain require cryptographic signatures, which means you’ll need key pairs. gill provides secure methods for generating these essential components:

import { generateKeyPairSigner } from "gill";

// Create a non-extractable keypair signer (recommended)
const signer = await generateKeyPairSigner();
console.log("Signer address:", signer.address);

Non-extractable key pairs are more secure because they prevent the private key material from being accessed or exported from the signer instance. This is the recommended approach for most applications, as it reduces the risk of accidental private key exposure.

Extractable KeyPairs (When You Really Need Them)

There are specific scenarios where you might need to access the private key material, such as when you need to save the key for backup purposes or use it across multiple applications. For these cases, gill provides a separate function:

import { generateExtractableKeyPairSigner } from "gill";

// Create an extractable keypair signer (use with caution)
const extractableSigner = await generateExtractableKeyPairSigner();

Important Security Note: Extractable key pairs are inherently less secure because they allow access to the private key material. Only use this approach when you have a specific requirement to export or store the private key, and always follow security best practices for handling cryptographic keys.

Transaction Management

Creating Transactions

Transactions are fundamental to blockchain operations. gill simplifies transaction creation with the createTransaction function:

import { createTransaction } from "gill";

// Basic transaction creation
const transaction = createTransaction({
  version: 0, // Transaction version
  feePayer: signer.address, // Who pays the transaction fee
  instructions: [], // Array of instructions to include
});

// Transaction with compute budget settings (recommended)
const optimizedTransaction = createTransaction({
  version: 0,
  feePayer: signer.address,
  instructions: [],
  computeUnitLimit: 200000, // Maximum compute units
  computeUnitPrice: 5000, // Priority fee in micro-lamports
});

Including compute budget settings is highly recommended as it helps optimize your transaction’s chances of success by properly allocating resources and setting appropriate priority fees.

Setting Latest Blockhash

For transactions to be valid, they typically need to reference the latest blockhash. Here’s how to properly create a transaction with the current blockhash:

import { createTransaction } from "gill";

// First, get the latest blockhash
const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();

// Then create the transaction with the blockhash
const transaction = createTransaction({
  version: 0,
  feePayer: signer.address,
  instructions: [],
  latestBlockhash: latestBlockhash,
});

Signing Transactions

Once your transaction is prepared, it needs to be signed before it can be submitted to the network:

import { signTransactionMessageWithSigners } from "gill";

// Sign a transaction that already has a blockhash reference
const signedTransaction = await signTransactionMessageWithSigners(transaction);

// For transactions without a blockhash, set it during signing
const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
const signedTransaction = await signTransactionMessageWithSigners(
  setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, transaction)
);

Simulating Transactions

Before sending a transaction to the network, it’s good practice to simulate it first to identify any potential issues:

import { createSolanaClient } from "gill";

const { simulateTransaction } = createSolanaClient({
  urlOrMoniker: "mainnet",
});

const simulationResult = await simulateTransaction(transaction);
console.log("Simulation logs:", simulationResult.value.logs);

Simulation helps you catch errors without incurring actual transaction costs, making it an essential step in the development process.

Sending and Confirming Transactions

When you’re ready to submit your transaction to the network, gill provides a convenient method:

import { createSolanaClient } from "gill";

const { sendAndConfirmTransaction } = createSolanaClient({
  urlOrMoniker: "mainnet",
});

// Send and wait for confirmation
await sendAndConfirmTransaction(signedTransaction);

// With custom configuration
await sendAndConfirmTransaction(signedTransaction, {
  commitment: "confirmed", // Confirmation level
  skipPreflight: false, // Whether to skip preflight checks
  maxRetries: 5, // Number of retry attempts
});

The sendAndConfirmTransaction method handles both submitting the transaction and waiting for network confirmation, simplifying what would otherwise be a multi-step process.

Extracting Transaction Signatures

After signing a transaction, you can extract its signature (transaction ID) even before submitting it to the network:

import { getSignatureFromTransaction } from "gill";

const signature = getSignatureFromTransaction(signedTransaction);
console.log("Transaction signature:", signature);

This capability is useful for tracking transactions and providing users with immediate feedback about their actions.

Working with Solana Explorer

gill makes it easy to generate links to Solana Explorer, allowing you and your users to view transaction details, account information, and block data:

import { getExplorerLink } from "gill";

// Transaction link
const transactionLink = getExplorerLink({
  transaction: "4nzNU7YxPtPsVzeg16oaZvLz4jMPtbAzavDfEFmemHNv93iYXKKYAaqBJzFCwEVxiULqTYYrbjPwQnA1d9ZCTELg",
});

// Account link on devnet
const accountLink = getExplorerLink({
  cluster: "devnet",
  account: "nick6zJc6HpW3kfBm4xS2dmbuVRyb5F3AnUvj5ymzR5",
});

// Block link
const blockLink = getExplorerLink({
  cluster: "mainnet",
  block: "242233124",
});

When no cluster is specified, the function defaults to mainnet. These explorer links are invaluable for debugging and providing transparency to your users.

Calculating Rent Exemption

On Solana, accounts need to maintain a minimum balance to remain exempt from rent collection. gill provides a function to calculate this amount:

import { getMinimumBalanceForRentExemption } from "gill";

// Default calculation (0 bytes)
const defaultRent = getMinimumBalanceForRentExemption();
console.log("Default rent exemption:", defaultRent); // 890_880n lamports

// Calculation for a specific account size
const customRent = getMinimumBalanceForRentExemption(50); // 50 bytes
console.log("Rent for 50 bytes:", customRent); // 1,238,880n lamports

This function uses static values from the Solana runtime, allowing you to calculate rent costs without making network requests. This is more efficient than using the equivalent RPC call, which would introduce latency.

Node.js Specific Functionality

For server-side applications, gill provides additional utilities that leverage Node.js-specific capabilities:

// Import Node-specific utilities
import { 
  loadKeypairSignerFromFile, 
  saveKeypairSignerToFile 
} from "gill/node";

File-Based Key Management

Working with key files is common in Node.js environments, particularly when interacting with Solana CLI-generated keypairs:

// Load default keypair (~/.config/solana/id.json)
const defaultSigner = await loadKeypairSignerFromFile();

// Load from a specific path
const customSigner = await loadKeypairSignerFromFile("/path/to/keypair.json");

// Save an extractable keypair to file
await saveKeypairSignerToFile(extractableSigner, "/path/to/save/keypair.json");

Environment Variable Management

For application configuration, you might prefer storing keys in environment variables:

import { 
  loadKeypairSignerFromEnvironment,
  saveKeypairSignerToEnvFile
} from "gill/node";

// Load from environment variable
const envSigner = await loadKeypairSignerFromEnvironment("MY_KEYPAIR_VAR");

// Save to environment file
await saveKeypairSignerToEnvFile(
  extractableSigner, 
  "MY_KEYPAIR_VAR", 
  ".env" // Optional path, defaults to .env
);

// Load base58-encoded key from environment
const base58Signer = await loadKeypairSignerFromEnvironmentBase58("MY_BASE58_KEY");

These utilities streamline the process of managing keys in different deployment environments, from development to production.

Transaction Builders

One of gill’s most powerful features is its collection of transaction builders for common blockchain operations. These builders abstract away complexity while ensuring optimal transaction configuration.

Creating Tokens with Metadata

The process of creating a new token on Solana involves multiple steps and interactions with different programs. gill simplifies this with the buildCreateTokenTransaction builder:

import { buildCreateTokenTransaction } from "gill/programs/token";

const createTokenTx = await buildCreateTokenTransaction({
  feePayer: signer,
  latestBlockhash: latestBlockhash,
  mint: mintKeypair,
  metadata: {
    isMutable: true, // Can metadata be changed later
    name: "My Custom Token",
    symbol: "MCT",
    uri: "https://example.com/token-metadata.json",
  },
  decimals: 6, // Token precision
  tokenProgram: TOKEN_PROGRAM_ADDRESS, // Or TOKEN_2022_PROGRAM_ADDRESS
});

This builder handles both the original Token Program and the newer Token Extensions Program (Token 2022), automatically using the appropriate metadata approach for each.

Minting Tokens

Once you have a token created, you’ll likely want to mint additional supply:

import { buildMintTokensTransaction } from "gill/programs/token";

const mintTokensTx = await buildMintTokensTransaction({
  feePayer: signer,
  latestBlockhash: latestBlockhash,
  mint: mintAddress,
  mintAuthority: signer,
  amount: 1000000, // Amount in smallest units (consider decimals)
  destination: recipientAddress,
  tokenProgram: TOKEN_PROGRAM_ADDRESS,
});

The builder automatically handles associated token account creation if the recipient doesn’t already have one for the specific mint.

Transferring Tokens

Transferring tokens between accounts is another common operation that gill simplifies:

import { buildTransferTokensTransaction } from "gill/programs/token";

const transferTokensTx = await buildTransferTokensTransaction({
  feePayer: signer,
  latestBlockhash: latestBlockhash,
  mint: mintAddress,
  authority: signer, // Account with transfer authority
  amount: 500000, // Amount to transfer
  destination: recipientAddress,
  tokenProgram: TOKEN_PROGRAM_ADDRESS,
});

Like the minting builder, this also handles associated token account creation when necessary, reducing the complexity of your application code.

Debug Mode

Debugging blockchain transactions can be challenging. gill’s debug mode provides enhanced logging to help identify and resolve issues:

Enabling Debug Mode

You can enable debug mode through several mechanisms:

// Set environment variable
process.env.GILL_DEBUG = "true";

// Or set globally in Node.js
global.__GILL_DEBUG__ = true;

// Or in browser environments
window.__GILL_DEBUG__ = true;

You can also control the verbosity of debug output:

// Set debug level
process.env.GILL_DEBUG_LEVEL = "debug"; // debug, info, warn, or error

Custom Debug Logging

gill exposes its debug functions, allowing you to integrate custom debugging into your application:

import { debug, isDebugEnabled } from "gill";

if (isDebugEnabled()) {
  // Custom debug logic
  debug("Custom debug message", "debug");
}

The debug level parameter allows you to control when your messages appear, matching the configured debug level.

Program Clients

gill includes pre-built clients for popular Solana programs, all tree-shakable to ensure only the code you use is included in your final bundle:

// Import program clients
import { 
  SystemProgram,
  ComputeBudgetProgram,
  MemoProgram 
} from "gill/programs";

// Token program clients are under a subpath
import { 
  TokenProgram, 
  TOKEN_PROGRAM_ADDRESS 
} from "gill/programs/token";

Available Program Clients

gill includes clients for these essential Solana programs:

• System Program: Fundamental Solana functionality
• Compute Budget Program: Transaction resource management
• Memo Program: Simple on-chain memos
• Token Program: Original token functionality (SPL Token)
• Token Extensions Program: Enhanced token capabilities (Token 2022)
• Address Lookup Table Program: Efficient address referencing
• Token Metadata Program: NFT and token metadata management (Metaplex v3)

These clients are re-exported from their respective dedicated packages, ensuring you get well-maintained and up-to-date implementations.

Compatibility with Other Program Clients

While gill includes clients for the most commonly used programs, you can easily incorporate clients for additional programs:

# Install stake program client
npm install @solana-program/stake

# Install vote program client
npm install @solana-program/vote

These additional clients follow the same patterns as the built-in ones, ensuring a consistent development experience.

Generating Custom Program Clients

For programs not included with gill, you can generate your own clients using Codama from the program’s IDL:

# Generate client from IDL
npx codama generate --idl ./path/to/program.json --out ./src/generated-client

This approach lets you maintain full control over your program interactions while still benefiting from gill’s core functionality.

Conclusion

gill provides a comprehensive solution for Solana blockchain development in JavaScript and TypeScript environments. By building on the solid foundation of @solana/kit while adding significant enhancements and simplifications, it offers developers a more productive and enjoyable experience.

From key management and transaction handling to debug capabilities and pre-built program clients, gill addresses the common pain points of Solana development. Its modular, tree-shakable architecture ensures that your applications remain lean and efficient, including only the code you actually use.

Whether you’re building a decentralized finance application, an NFT marketplace, or any other blockchain-based solution, gill provides the tools and abstractions you need to focus on your application’s unique value rather than the complexities of blockchain interaction.

As the Solana ecosystem continues to evolve, gill’s commitment to compatibility and developer experience positions it as a valuable tool for both new and experienced blockchain developers. By reducing boilerplate, enhancing debugging capabilities, and providing thoughtful abstractions for common operations, gill helps accelerate development while maintaining the flexibility and power needed for sophisticated blockchain applications.