Working with Sessions in Swig

This guide explains how to work with sessions in Swig, which allow you to create temporary authorities with limited permissions. Sessions are perfect for dApp integrations where you need to delegate authority for a specific duration. You can find all example code in the swig-ts/examples/basic/classic directory.

Examples with svm in the file name use LiteSVM for testing. Those without svm in the file name use a local validator. Which you can run with the bun start-validator command.

Creating a Basic Session

The simplest way to create a session is with Ed25519 keys. Here are the key parts:

Classic
Kit

import {
  Connection,
  Keypair,
  LAMPORTS_PER_SOL,
} from '@solana/web3.js';
import {
  Actions,
  createEd25519SessionAuthorityInfo,
  findSwigPda,
  getCreateSwigInstruction,
  getCreateSessionInstructions,
} from '@swig-wallet/classic';

// Setup - Create root authority and session keypair
const userRootKeypair = Keypair.generate();
const dappSessionKeypair = Keypair.generate();

const connection = new Connection('http://localhost:8899', 'confirmed');

// Create Swig with session support
const id = randomBytes(32);
const swigAccountAddress = findSwigPda(id);
const rootActions = Actions.set().all().get();

const ix = await getCreateSwigInstruction({
  id,
  authorityInfo: createEd25519SessionAuthorityInfo(
    userRootKeypair.publicKey,
    100n,
  ),
  actions: rootActions,
  payer: userRootKeypair.publicKey,
});

// Create a session that lasts 50 slots
const createSessionIx = await getCreateSessionInstructions(
  swig,
  rootRole.id,
  dappSessionKeypair.publicKey,
  50n,
);
// Create a session that lasts 50 slots
const createSessionIx = await getCreateSessionInstructions(
  swig,
  rootRole.id,
  dappSessionKeypair.publicKey,
  50n,
);

import {
  createSolanaRpc,
  createSolanaRpcSubscriptions,
  generateKeyPairSigner,
  lamports,
} from '@solana/kit';
import {
  Actions,
  createEd25519SessionAuthorityInfo,
  findSwigPda,
  getCreateSwigInstruction,
  getCreateSessionInstructions,
} from '@swig-wallet/kit';

// Setup - Create root authority and session keypair
const userRootKeypair = await generateKeyPairSigner();
const dappSessionKeypair = await generateKeyPairSigner();

const connection = {
  rpc: createSolanaRpc('http://localhost:8899'),
  rpcSubscriptions: createSolanaRpcSubscriptions('ws://localhost:8900'),
};

// Create Swig with session support
const id = randomBytes(32);
const swigAccountAddress = await findSwigPda(id);
const rootActions = Actions.set().all().get();

const createSwigIx = await getCreateSwigInstruction({
  id,
  authorityInfo: createEd25519SessionAuthorityInfo(userRootKeypair.address, 100n),
  actions: rootActions,
  payer: userRootKeypair.address,
});

// Create a session that lasts 50 slots
const createSessionIx = await getCreateSessionInstructions(
  swig,
  rootRole.id,
  dappSessionKeypair.address,
  50n,
);

Using Session Authority

Once a session is created, you can use it to sign transactions within its duration:

Classic
Kit

import {
  SystemProgram,
  LAMPORTS_PER_SOL,
} from '@solana/web3.js';
import {
  fetchSwig,
  getSignInstructions,
  getSwigWalletAddress,
} from '@swig-wallet/classic';

// Find the role by session key
const swig = await fetchSwig(connection, swigAccountAddress);
const swigWalletAddress = await getSwigWalletAddress(swig);
const rootRole = swig.findRoleBySessionKey(dappSessionKeypair.publicKey);

if (!rootRole || !rootRole.isSessionBased())
  throw new Error('Role not found for authority');

// Create and sign a transfer using session authority (use swigWalletAddress)
const transfer = SystemProgram.transfer({
  fromPubkey: swigWalletAddress,
  toPubkey: dappTreasury,
  lamports: 0.1 * LAMPORTS_PER_SOL,
});

const signTransfer = await getSignInstructions(
  swig,
  rootRole.id,
  [transfer],
  false,
  { payer: dappSessionKeypair.publicKey },
);

await sendTransaction(connection, signTransfer, dappSessionKeypair);

import {
  getTransferSolInstructionDataEncoder,
  SYSTEM_PROGRAM_ADDRESS,
} from '@solana-program/system';
import {
  AccountRole,
  type IInstruction,
} from '@solana/kit';
import {
  fetchSwig,
  getSignInstructions,
  getSwigWalletAddress,
} from '@swig-wallet/kit';

// Find the role by session key
const swig = await fetchSwig(connection.rpc, swigAccountAddress);
const swigWalletAddress = await getSwigWalletAddress(swig);
const sessionRole = swig.findRolesByEd25519SignerPk(dappSessionKeypair.address)[0];

if (!sessionRole || !sessionRole.isSessionBased())
  throw new Error('Role not found for authority');

// Create and sign a transfer using session authority (use swigWalletAddress)
const transferIx: IInstruction = {
  programAddress: SYSTEM_PROGRAM_ADDRESS,
  accounts: [
    { address: swigWalletAddress, role: AccountRole.WRITABLE_SIGNER },
    { address: dappTreasury.address, role: AccountRole.WRITABLE },
  ],
  data: new Uint8Array(
    getTransferSolInstructionDataEncoder().encode({
      amount: BigInt(0.1 * LAMPORTS_PER_SOL),
    })
  ),
};

const signTransfer = await getSignInstructions(
  swig,
  sessionRole.id,
  [transferIx],
  false,
  { payer: dappSessionKeypair.address },
);

await sendTransaction(connection, signTransfer, dappSessionKeypair);

Secp256k1 Sessions (EVM Compatible)

For EVM compatibility, you can create sessions with Secp256k1 keys:

Classic
Kit

import { Wallet } from '@ethereumjs/wallet';
import {
  createSecp256k1SessionAuthorityInfo,
  getSigningFnForSecp256k1PrivateKey,
  getCreateSwigInstruction,
  getCreateSessionInstructions,
} from '@swig-wallet/classic';

// Setup with Ethereum wallet
const userWallet = Wallet.generate();

// Create Swig with Secp256k1 session support
const createSwigInstruction = await getCreateSwigInstruction({
  authorityInfo: createSecp256k1SessionAuthorityInfo(
    userWallet.getPublicKey(),
    100n,
  ),
  id,
  payer: userRootKeypair.publicKey,
  actions: rootActions,
});

// Create a session
const currentSlot = await connection.getSlot('confirmed');
const signingFn = getSigningFnForSecp256k1PrivateKey(
  userWallet.getPrivateKeyString(),
);

const sessionInstructions = await getCreateSessionInstructions(
  swig,
  rootRole.id,
  dappSessionKeypair.publicKey,
  50n,
  { 
    payer: userRootKeypair.publicKey,
    currentSlot: BigInt(currentSlot),
    signingFn,
  },
);

import { Wallet } from '@ethereumjs/wallet';
import {
  createSecp256k1SessionAuthorityInfo,
  getSigningFnForSecp256k1PrivateKey,
  getCreateSwigInstruction,
  getCreateSessionInstructions,
} from '@swig-wallet/kit';

// Setup with Ethereum wallet
const userWallet = Wallet.generate();

// Create Swig with Secp256k1 session support
const authorityInfo = createSecp256k1SessionAuthorityInfo(
  userWallet.getPublicKey(),
  100n, // Max session duration
);

const createSwigInstruction = await getCreateSwigInstruction({
  authorityInfo,
  id,
  payer: userRootKeypair.address,
  actions: rootActions,
});

// Create a session
const currentSlot = await connection.rpc.getSlot().send();
const signingFn = getSigningFnForSecp256k1PrivateKey(userWallet.getPrivateKey());

const sessionInstructions = await getCreateSessionInstructions(
  swig,
  rootRole.id,
  dappSessionKeypair.address,
  50n, // Session duration in slots
  { 
    payer: userRootKeypair.address,
    currentSlot,
    signingFn,
  },
);

Revoking Sessions

You can revoke a session by creating a new session with an all-zero session key:

Classic
Kit

import { getCreateSessionInstructions } from '@swig-wallet/classic';

// Create a zero key to revoke the session
const zeroKey = new Uint8Array(32).fill(0);

// Create revocation instruction
const revokeSessionIx = await getCreateSessionInstructions(
  swig,
  rootRole.id,
  zeroKey,
  1n, // Duration doesn't matter for revocation
);

await sendTransaction(connection, revokeSessionIx, userRootKeypair);

import { getCreateSessionInstructions } from '@swig-wallet/kit';

// Create a zero key to revoke the session
const zeroKey = new Uint8Array(32).fill(0);

// Create revocation instruction
const revokeSessionIx = await getCreateSessionInstructions(
  swig,
  rootRole.id,
  zeroKey,
  1n, // Duration doesn't matter for revocation
);

await sendTransaction(connection, revokeSessionIx, userRootKeypair);

Key Aspects of Sessions

Sessions in Swig have several important characteristics:

Temporary Authority: Sessions expire after their specified duration
Unique Keys: Each session must use a unique key (can’t reuse previous session keys)
Root Override: The root authority can always override or revoke session permissions
Inheritance: Sessions inherit permissions from their root role
Multiple Sessions: You can have multiple active sessions for the same root authority

Testing Environment Options

These examples can be run in different environments:

Local Validator: Use the examples with ‘local’ in the filename
- Requires running a local Solana validator with bun start-validator
- Real blockchain environment
- Good for final testing
LiteSVM: Use examples with svm in the filename
- No validator required
- Instant transaction confirmation
- Perfect for rapid development
- Simulates the Solana runtime
Devnet: All examples work with devnet
- Change connection URL to https://api.devnet.solana.com
- Real network environment
- Free to use with airdropped SOL

Classic
Kit

// Local validator
const connection = new Connection('http://localhost:8899', 'confirmed');

// Devnet
const connection = new Connection('https://api.devnet.solana.com', 'confirmed');

// Local validator
const connection = {
  rpc: createSolanaRpc('http://localhost:8899'),
  rpcSubscriptions: createSolanaRpcSubscriptions('ws://localhost:8900'),
};

// Devnet
const connection = {
  rpc: createSolanaRpc('https://api.devnet.solana.com'),
  rpcSubscriptions: createSolanaRpcSubscriptions('wss://api.devnet.solana.com'),
};

LiteSVM is recommended for initial development as it provides the fastest feedback loop. Move to local validator or devnet for more thorough testing.

Overview

Quickstarts

TypeScript Packages

Rust Packages

AI & MCP

Examples & Recipes

Error Types

Migration & Releases

Working with Sessions in Swig

Creating a Basic Session

Using Session Authority

Secp256k1 Sessions (EVM Compatible)

Revoking Sessions

Key Aspects of Sessions

Testing Environment Options

​Creating a Basic Session

​Using Session Authority

​Secp256k1 Sessions (EVM Compatible)

​Revoking Sessions

​Key Aspects of Sessions

​Testing Environment Options

Creating a Basic Session

Using Session Authority

Secp256k1 Sessions (EVM Compatible)

Revoking Sessions

Key Aspects of Sessions

Testing Environment Options