Migration Guide: Beta to v1.0

This guide helps you migrate from the beta versions of the Swig TypeScript SDK to the completely refactored v1.0 release.

Overview of Changes

The v1.0 release represents an overhaul with some breaking changes.

Key Changes

Modular Architecture: Core logic moved to @swig-wallet/lib
Instruction-Based API: Functions return TransactionInstruction[] instead of single instructions
Simplified Package Structure: @swig-wallet/classic now acts as a thin wrapper
Updated Dependencies: Moved from @solana/spl-token to @solana-program/token

Package Changes

Before (Beta)

import {
  Actions,
  createSwig,
  Ed25519Authority,
  addAuthorityInstruction,
  signInstruction,
} from "@swig-wallet/classic";

After (v1.0)

For Web3.js 1.x applications:

import {
  Actions,
  getCreateSwigInstruction,
  createEd25519AuthorityInfo,
  getAddAuthorityInstructions,
  getSignInstructions,
} from "@swig-wallet/classic";

For Web3.js 2.0 applications:

import {
  Actions,
  getCreateSwigInstruction,
  createEd25519AuthorityInfo,
  getAddAuthorityInstructions,
  getSignInstructions,
} from "@swig-wallet/kit";

After (v1.0)

import {
  Actions,
  getCreateSwigInstruction,
  createEd25519AuthorityInfo,
  getAddAuthorityInstructions,
  getSignInstructions,
} from "@swig-wallet/classic";

Function Migrations

Creating a Swig

Before (Beta)

const rootAuthority = Ed25519Authority.fromPublicKey(user.publicKey);
const rootActions = Actions.set().manageAuthority().get();
const tx = await createSwig(
  connection,
  id,
  rootAuthority,
  rootActions,
  user.publicKey,
  [user],
);

After (v1.0)

const rootAuthorityInfo = createEd25519AuthorityInfo(user.publicKey);

Swig Class Changes

The Swig class has been significantly refactored. All static methods have been removed and replaced with standalone functions.

Static Method Removal

Before (Beta)

// Creating a Swig
const createSwigIx = Swig.create({
  payer: user.publicKey,
  id,
  actions: rootActions,
  authorityInfo: rootAuthorityInfo,
});

// Fetching a Swig
const swig = await Swig.fetch(connection, swigAddress);

// Fetching with null handling
const swig = await Swig.fetchNullable(connection, swigAddress);

After (v1.0)

// Creating a Swig
const createSwigIx = await getCreateSwigInstruction({
  payer: user.publicKey,
  id,
  actions: rootActions,
  authorityInfo: rootAuthorityInfo,
});

// Fetching a Swig
const swig = await fetchSwig(connection, swigAddress);

// Fetching with null handling
const swig = await fetchNullableSwig(connection, swigAddress);

Instance Method Changes

The Swig instance methods remain largely the same, but some may have changed from synchronous to asynchronous:

// These methods are still available on Swig instances
const role = swig.findRoleById(roleId);
const roles = swig.findRolesByEd25519SignerPk(publicKey);
const roles = swig.findRolesBySecp256k1SignerAddress(address);

New Sub-Account Functions

The v1.0 release introduces several new sub-account management functions:

// Create sub-account
const createSubAccountInstructions = await getCreateSubAccountInstructions(
  swig,
  roleId,
  options
);

// Toggle sub-account enabled/disabled
const toggleSubAccountInstructions = await getToggleSubAccountInstructions(
  swig,
  roleId,
  enabled, // boolean
  options
);

// Withdraw from sub-account
const withdrawInstructions = await getWithdrawFromSubAccountSubAccountInstructions(
  swig,
  roleId,
  withdrawArgs,
  options
);

Authority Creation Changes

Before (Beta)

const rootAuthority = Ed25519Authority.fromPublicKey(user.publicKey);

After (v1.0)

const rootAuthorityInfo = createEd25519AuthorityInfo(user.publicKey);

Import Changes

The v1.0 release represents a complete restructuring of the package exports. Most functionality has been moved to @swig-wallet/lib and re-exported through the classic package.

Package Structure Changes

Before (Beta) - Direct Module Exports

// Beta exported many modules directly
export * from '@swig-wallet/coder';
export * from './actions';
export * from './authority';      // ❌ REMOVED
export * from './consts';
export * from './instructions';
export * from './role';          // ❌ REMOVED
export * from './rpc';           // ❌ REMOVED
export * from './swig';          // ❌ REMOVED
export * from './utils';         // ❌ REMOVED
export * from './wallet';        // ❌ REMOVED

After (v1.0) - Lib-Based Exports

// v1.0 exports primarily from lib with thin wrapper
export * from '@swig-wallet/lib';  // ✅ Most functionality here
export * from './accounts';
export * from './consts';
export * from './instructions';    // ✅ New wrapper functions

Removed Direct Imports

These modules are no longer directly exported from @swig-wallet/classic:

Authority classes: Ed25519Authority, Secp256k1Authority, etc.
Role utilities: Direct role manipulation functions
RPC helpers: Connection and RPC utilities
Swig class: Static methods removed, instance available via lib
Utils: Utility functions moved to lib
Wallet: Wallet-related functionality moved to lib

Core Classes

Actions class is now imported from @swig-wallet/lib (re-exported by @swig-wallet/classic)
Swig class is now imported from @swig-wallet/lib (re-exported by @swig-wallet/classic)
Authority classes have been completely replaced with info creation functions

Function Naming

createSwig() → getCreateSwigInstruction()
addAuthorityInstruction() → getAddAuthorityInstructions()
signInstruction() → getSignInstructions()
removeAuthorityInstruction() → getRemoveAuthorityInstructions()
createSessionInstruction() → getCreateSessionInstructions()
createSubAccountInstruction() → getCreateSubAccountInstructions()
toggleSubAccountInstruction() → getToggleSubAccountInstructions()
withdrawFromSubAccountInstruction() → getWithdrawFromSubAccountSubAccountInstructions()

Dependency Updates

For Web3.js 1.x applications:

{
  "dependencies": {
    "@swig-wallet/classic": "^1.0.0",
    "@solana-program/token": "^0.5.1",
    "@solana/web3.js": "^1.98.0"
  }
}

For Web3.js 2.0 applications:

{
  "dependencies": {
    "@swig-wallet/kit": "^1.0.0",
    "@solana-program/token": "^0.5.1",
    "@solana/kit": "^2.1.0"
  }
}

Remove old dependencies:

npm uninstall @solana/spl-token

Remove old dependencies:

npm uninstall @solana/spl-token

Migration Checklist

Common Migration Issues

Issue: Functions returning arrays instead of single instructions

Solution: Use the spread operator when adding to transactions:

// Before
transaction.add(instruction);

// After
transaction.add(...instructions);

Issue: Function parameter signatures changed

Solution: Update function calls to use new parameter structure:

// Before - functions took Role objects and payer PublicKey
const ix = await addAuthorityInstruction(
  rootRole,
  rootKeypair.publicKey,
  authorityInfo,
  actions
);

// After - functions take Swig instance and role ID
const instructions = await getAddAuthorityInstructions(
  swig,
  rootRole.id,
  authorityInfo,
  actions
);

Issue: Import errors for removed classes

Solution: Replace with new function-based API:

// Before
import { Ed25519Authority } from "@swig-wallet/classic";
const auth = Ed25519Authority.fromPublicKey(pk);

// After
import { createEd25519AuthorityInfo } from "@swig-wallet/classic";
const authInfo = createEd25519AuthorityInfo(pk);

Issue: Swig static methods no longer available

Solution: Use the new standalone functions:

// Before
const createIx = Swig.create(args);
const swig = await Swig.fetch(connection, address);
const swig = await Swig.fetchNullable(connection, address);

// After
const createIx = await getCreateSwigInstruction(args);
const swig = await fetchSwig(connection, address);
// For nullable fetch
const swig = await fetchNullableSwig(connection, swigAddress);

Issue: Sub-account functions not found

Solution: Use the new instruction array functions:

// Before
const ix = await createSubAccountInstruction(role, payer, options);

// After
const instructions = await getCreateSubAccountInstructions(swig, roleId, options);
const transaction = new Transaction().add(...instructions);

Getting Help

If you encounter issues during migration:

Check the API documentation
Review the updated tutorials
Examine the example code
Open an issue on the GitHub repository

The v1.0 release is designed to be more consistent and composable, making it easier to build complex Swig applications once you’ve completed the migration.

​Overview of Changes

​Key Changes

​Package Changes

​Before (Beta)

​After (v1.0)

​For Web3.js 1.x applications:

​For Web3.js 2.0 applications:

​After (v1.0)

​Function Migrations

​Creating a Swig

​Before (Beta)

​After (v1.0)

​Swig Class Changes

​Static Method Removal

​Before (Beta)

​After (v1.0)

​Instance Method Changes

​New Sub-Account Functions

​Authority Creation Changes

​Before (Beta)

​After (v1.0)

​Import Changes

​Package Structure Changes

​Before (Beta) - Direct Module Exports

​After (v1.0) - Lib-Based Exports

​Removed Direct Imports

​Core Classes

​Function Naming

​Dependency Updates

​For Web3.js 1.x applications:

​For Web3.js 2.0 applications:

​Migration Checklist

​Common Migration Issues

​Issue: Functions returning arrays instead of single instructions

​Issue: Function parameter signatures changed

​Issue: Import errors for removed classes

​Issue: Swig static methods no longer available

​Issue: Sub-account functions not found

​Getting Help

Overview of Changes

Key Changes

Package Changes

Before (Beta)

After (v1.0)

For Web3.js 1.x applications:

For Web3.js 2.0 applications:

After (v1.0)

Function Migrations

Creating a Swig

Before (Beta)

After (v1.0)

Swig Class Changes

Static Method Removal

Before (Beta)

After (v1.0)

Instance Method Changes

New Sub-Account Functions

Authority Creation Changes

Before (Beta)

After (v1.0)

Import Changes

Package Structure Changes

Before (Beta) - Direct Module Exports

After (v1.0) - Lib-Based Exports

Removed Direct Imports

Core Classes

Function Naming

Dependency Updates

For Web3.js 1.x applications:

For Web3.js 2.0 applications:

Migration Checklist

Common Migration Issues

Issue: Functions returning arrays instead of single instructions

Issue: Function parameter signatures changed

Issue: Import errors for removed classes

Issue: Swig static methods no longer available

Issue: Sub-account functions not found

Getting Help