Sub Accounts in Swig

This guide explains how to work with sub accounts in Swig, which allow authorities to create and manage dedicated sub account addresses with specific permissions. Sub accounts are perfect for use cases like portfolio management where you want to delegate complex operations without giving control over all assets. You can find complete working examples in the Swig repository:

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 use cases like portfolio management, where you want to allow an unlimited complexity of actions on behalf of a single address, but you don’t 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, Anagram’s onchain yield optimizer. Breeze can optimize the yield of a user’s portfolio without giving them control over their whole swig.

How Sub Accounts Work

To work with sub accounts, there are several key steps:

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.
Create Sub Account: Once the authority has the permission, they can create a sub account using the getCreateSubAccountInstructions.
Sub Account Sign: Once created, sub accounts can perform on-chain actions using the getSignInstructions with the isSubAccount parameter set to true.

Critical Requirement: Creating a subaccount requires a two-step process:

First: Add a SubAccount permission to a new or existing Authority on your Swig wallet
Second: Create the actual subaccount, which populates the blank SubAccount action with the subaccount’s public key

Important: Even if an authority has All permission, you must explicitly add the SubAccount permission with a blank subaccount ([0; 32] in Rust, or using Actions.set().subAccount().get() in TypeScript) to enable subaccount creation. The All permission alone is not sufficient for subaccount creation.

Creating a Sub Account Authority

First, you need to add an authority with sub account permissions:

Classic
Kit
Rust

import {
  Keypair,
  LAMPORTS_PER_SOL,
} from '@solana/web3.js';
import {
  Actions,
  createEd25519AuthorityInfo,
  findSwigPda,
  getAddAuthorityInstructions,
  getCreateSwigInstruction,
  fetchSwig,
} from '@swig-wallet/classic';

// Create authorities
const rootAuthority = Keypair.generate();
const subAccountAuthority = Keypair.generate();

// Create Swig with root authority
const id = Uint8Array.from(Array(32).fill(2));
const swigAddress = findSwigPda(id);

const createSwigIx = await getCreateSwigInstruction({
  payer: rootAuthority.publicKey,
  actions: Actions.set().all().get(),
  authorityInfo: createEd25519AuthorityInfo(rootAuthority.publicKey),
  id,
});

// Add sub account authority with sub account permissions
const swig = await fetchSwig(connection, swigAddress);
const rootRole = swig.roles[0];

const addAuthorityIx = await getAddAuthorityInstructions(
  swig,
  rootRole.id,
  createEd25519AuthorityInfo(subAccountAuthority.publicKey),
  Actions.set().subAccount().get(),
);

Creating a Sub Account

Once you have an authority with sub account permissions, you can create the sub account:

Classic
Kit
Rust

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

// Refetch swig to get updated roles
await swig.refetch();
const subAccountAuthRole = swig.roles[1];

// Create sub account
const createSubAccountIx = await getCreateSubAccountInstructions(
  swig,
  subAccountAuthRole.id,
);

await sendTransaction(connection, createSubAccountIx, subAccountAuthority);

// Get the sub account address
const subAccountAddress = findSwigSubAccountPda(
  subAccountAuthRole.swigId,
  subAccountAuthRole.id,
);

Creating Swig Account and SubAccount in One Transaction

If you’re creating a new Swig wallet and want to set up a subaccount immediately, you can create both the Swig account with subaccount authority and the subaccount itself in a single transaction. This reduces the number of transactions needed from 3 to 1.

Rust

use solana_program::pubkey::Pubkey;
use solana_sdk::{
    message::{v0, VersionedMessage},
    signature::Keypair,
    transaction::VersionedTransaction,
};
use swig_interface::{
    AuthorityConfig, ClientAction, CreateInstruction, CreateSubAccountInstruction,
};
use swig_state::{
    action::{all::All, sub_account::SubAccount},
    authority::AuthorityType,
    swig::{sub_account_seeds, swig_account_seeds, swig_wallet_address_seeds},
};

fn create_swig_and_subaccount_in_one_tx(
    rpc_client: &RpcClient,
    authority: &Keypair,
    fee_payer: &Keypair,
) -> Result<(Pubkey, Pubkey), Box<dyn std::error::Error>> {
    let swig_id = rand::random::<[u8; 32]>();
    let program_id = swig_interface::program_id();

    // Derive the Swig account address
    let (swig_key, swig_bump) =
        Pubkey::find_program_address(&swig_account_seeds(&swig_id), &program_id);
    let (swig_wallet_address, wallet_address_bump) = Pubkey::find_program_address(
        &swig_wallet_address_seeds(swig_key.as_ref()),
        &program_id,
    );

    // Derive the sub-account address (role_id 0 since this is the initial authority)
    let role_id: u32 = 0;
    let role_id_bytes = role_id.to_le_bytes();
    let (sub_account, sub_account_bump) =
        Pubkey::find_program_address(&sub_account_seeds(&swig_id, &role_id_bytes), &program_id);

    // Step 1: Create instruction to create Swig account with All + SubAccount permissions
    let create_swig_ix = CreateInstruction::new(
        swig_key,
        swig_bump,
        fee_payer.pubkey(),
        swig_wallet_address,
        wallet_address_bump,
        AuthorityConfig {
            authority_type: AuthorityType::Ed25519,
            authority: authority.pubkey().as_ref(),
        },
        vec![
            ClientAction::All(All {}),
            ClientAction::SubAccount(SubAccount::new_for_creation()),
        ],
        swig_id,
    )?;

    // Step 2: Create instruction to create the subaccount
    // This uses role_id 0 since the authority is the initial/root authority
    let create_sub_account_ix = CreateSubAccountInstruction::new_with_ed25519_authority(
        swig_key,
        authority.pubkey(),
        fee_payer.pubkey(),
        sub_account,
        role_id,
        sub_account_bump,
    )?;

    // Step 3: Submit both instructions in a single transaction
    let recent_blockhash = rpc_client.get_latest_blockhash()?;
    let message = v0::Message::try_compile(
        &fee_payer.pubkey(),
        &[create_swig_ix, create_sub_account_ix],
        &[],
        recent_blockhash,
    )?;

    let tx = VersionedTransaction::try_new(
        VersionedMessage::V0(message),
        &[fee_payer, authority],
    )?;

    rpc_client.send_and_confirm_transaction(&tx)?;

    // Verify both accounts were created
    let swig_account = rpc_client.get_account(&swig_key)?;
    let sub_account_data = rpc_client.get_account(&sub_account)?;
    
    assert_eq!(sub_account_data.owner, solana_sdk::system_program::id());

    Ok((swig_key, sub_account))
}

Note: This approach attempts to create both the Swig account and subaccount atomically in a single transaction. While this can be more efficient, it may fail if the subaccount creation instruction requires the Swig account to be fully initialized and written to the blockchain first. If this fails, fall back to the multi-transaction approach shown in the previous examples.

Using Sub Accounts

Once created, you can use the sub account to perform transactions:

Classic
Kit
Rust

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

// Fund the sub account
await connection.requestAirdrop(subAccountAddress, LAMPORTS_PER_SOL);

// Create a transfer from the sub account
const recipient = Keypair.generate().publicKey;

const transfer = SystemProgram.transfer({
  fromPubkey: subAccountAddress,
  toPubkey: recipient,
  lamports: 0.1 * LAMPORTS_PER_SOL,
});

// Sign with sub account (note: isSubAccount = true)
const signIx = await getSignInstructions(
  swig,
  subAccountAuthRole.id,
  [transfer],
  true, // isSubAccount flag
);

await sendTransaction(connection, signIx, subAccountAuthority);

Key Features of Sub Accounts

Sub accounts in Swig have several important characteristics:

Dedicated Address: Each sub account has its own unique address derived from the Swig ID and role ID
Isolated Operations: Sub accounts can perform complex operations without affecting the main Swig balance
Root Authority Control: The root authority can always reclaim funds from sub accounts
Permission-Based: Only authorities with sub account permissions can create and manage sub accounts
Unlimited Actions: Sub accounts can perform any on-chain action within their permission scope

Testing Environment Options

These examples can be run in different environments:

Local Validator: Use the examples above
- Requires running a local Solana validator with bun start-validator
- Real blockchain environment
- Good for final testing
LiteSVM: For rapid development and testing
- 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');

Use Cases

Sub accounts are perfect for:

Portfolio Management: Allow complex DeFi operations without full wallet access
Yield Optimization: Automated strategies with isolated risk
Multi-Strategy Trading: Separate accounts for different trading strategies
Delegation: Give specific permissions for particular use cases

Additional Resources

You can find more working examples in our repositories:

Rust Examples: Swig test suite
Classic TypeScript: transfer-svm-subaccount.ts
Kit TypeScript: transfer-local-subaccount.ts
All Examples: Swig TypeScript examples

Basics

Payments

Ethereum Onboarding

Passkeys

Advanced

Sub Accounts in Swig

What are Sub Accounts?

How Sub Accounts Work

Creating a Sub Account Authority

Creating a Sub Account

Creating Swig Account and SubAccount in One Transaction

Using Sub Accounts

Key Features of Sub Accounts

Testing Environment Options

Use Cases

Additional Resources

Basics

Payments

Ethereum Onboarding

Passkeys

Advanced

​What are Sub Accounts?

​How Sub Accounts Work

​Creating a Sub Account Authority

​Creating a Sub Account

​Creating Swig Account and SubAccount in One Transaction

​Using Sub Accounts

​Key Features of Sub Accounts

​Testing Environment Options

​Use Cases

​Additional Resources

What are Sub Accounts?

How Sub Accounts Work

Creating a Sub Account Authority

Creating a Sub Account

Creating Swig Account and SubAccount in One Transaction

Using Sub Accounts

Key Features of Sub Accounts

Testing Environment Options

Use Cases

Additional Resources