Sub Accounts in Swig

“Its sub accounts all the way down” - Ancient Swig Proverb

Sub Accounts (Preview)

Sub account support in the TypeScript SDK is currently under development. However, full support is available in the Rust SDK. This guide provides an overview of the feature and its core concepts.

What are Sub Accounts?

Sub accounts in Swig allow an authority to create and manage a single sub account address and perform any actions on behalf of that sub account. This is a super high level of permission so use with care. It works for usecases like portfolio management, where you want to allow an unlimited complexity of actions on behalf of a single address, but you dont want to give the authority control over all the assets of the swig. The root authority can always pull funds SOL and tokens from the sub account back to the main Swig wallet. A great example of this is Breeze, anagrams onchain yield optimizer. Allows breeze to optimize the yield of a users portfolio without giving them control over their whole swig.

How Sub Accounts Work

To work with sub accounts, there are two key requirements:

1. Sub Account Permission: The authority must have the sub account permission to create the sub account. This permission is set when creating or modifying a role.

2. Sub Account Sign: Once created, sub accounts can perform on-chain actions using the sub_account_sign instruction.

Enhanced Withdrawal Safety

The TypeScript SDK now includes enhanced safety controls for withdrawing SOL from sub-accounts:

Rent-Exempt Validation

By default, withdrawals are prevented if they would drop the sub-account below the rent-exempt minimum (1,224,960 lamports). This protects against accidentally making sub-accounts unviable.

Explicit Override

You can explicitly allow withdrawals below the rent-exempt minimum when needed by setting allowBelowRentExempt: true.

Balance Validation

When using safety controls, you must provide the current balance for proper validation.

TypeScript SDK Examples

Basic Sub-Account Creation

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

const createSubAccountIx = await getCreateSubAccountInstructions(
  swig,
  roleId
);

Basic SOL Withdrawal

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

// Basic withdrawal (no safety validation)
const basicWithdrawIx = await getWithdrawFromSubAccountInstructions(
  swig,
  roleId,
  {
    amount: 1000000n // 0.001 SOL
  }
);

Safe SOL Withdrawal with Validation

Classic SDK

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

// Safe withdrawal with rent-exempt validation
const safeWithdrawIx = await getWithdrawFromSubAccountInstructionsChecked(
  swig,
  roleId,
  {
    amount: 1000000n, // 0.001 SOL
    currentBalance: 2000000n,
    allowBelowRentExempt: false // Default behavior - protects rent exemption
  }
);

Kit SDK

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

// Safe withdrawal with rent-exempt validation
const safeWithdrawIx = await getWithdrawFromSubAccountSubAccountInstructionsChecked(
  swig,
  roleId,
  {
    amount: 1000000n, // 0.001 SOL
    currentBalance: 2000000n,
    allowBelowRentExempt: false // Default behavior - protects rent exemption
  }
);

Explicit Override for Below Rent-Exempt

Classic SDK

// Allow withdrawal below rent-exempt minimum
const overrideWithdrawIx = await getWithdrawFromSubAccountInstructionsChecked(
  swig,
  roleId,
  {
    amount: 1000000n,
    currentBalance: 2000000n,
    allowBelowRentExempt: true // Explicitly allow below rent-exempt
  }
);

Kit SDK

// Allow withdrawal below rent-exempt minimum
const overrideWithdrawIx = await getWithdrawFromSubAccountSubAccountInstructionsChecked(
  swig,
  roleId,
  {
    amount: 1000000n,
    currentBalance: 2000000n,
    allowBelowRentExempt: true // Explicitly allow below rent-exempt
  }
);

Working Examples

You can find working examples in our test suite and in the TypeScript SDK examples:

• Classic SDK: examples/classic/transfer/withdraw-sol-subaccount.ts
• Kit SDK: examples/kit/transfer/withdraw-sol-subaccount.ts

These examples demonstrate:

• Creating sub-accounts
• Basic SOL withdrawals (no validation)
• Safe SOL withdrawals with rent-exempt validation
• Prevention of unsafe withdrawals that would drop below rent exemption
• Explicit override functionality for allowing below rent-exempt withdrawals