> ## Documentation Index
> Fetch the complete documentation index at: https://swig-tracy-multiple-subaccounts-support.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration Guide: Beta to v1.0

> Complete guide for migrating from Swig TypeScript SDK beta versions 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

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

## Package Changes

### Before (Beta)

```typescript theme={null}
import {
  Actions,
  createSwig,
  Ed25519Authority,
  addAuthorityInstruction,
  signInstruction,
} from "@swig-wallet/classic";
```

### After (v1.0)

#### For Web3.js 1.x applications:

```typescript theme={null}
import {
  Actions,
  getCreateSwigInstruction,
  createEd25519AuthorityInfo,
  getAddAuthorityInstructions,
  getSignInstructions,
} from "@swig-wallet/classic";
```

#### For Web3.js 2.0 applications:

```typescript theme={null}
import {
  Actions,
  getCreateSwigInstruction,
  createEd25519AuthorityInfo,
  getAddAuthorityInstructions,
  getSignInstructions,
} from "@swig-wallet/kit";
```

### After (v1.0)

```typescript theme={null}
import {
  Actions,
  getCreateSwigInstruction,
  createEd25519AuthorityInfo,
  getAddAuthorityInstructions,
  getSignInstructions,
} from "@swig-wallet/classic";
```

## Function Migrations

### Creating a Swig

#### Before (Beta)

```typescript theme={null}
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)

```typescript theme={null}
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)

```typescript theme={null}
// 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)

```typescript theme={null}
// 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:

```typescript theme={null}
// 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:

```typescript theme={null}
// 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)

```typescript theme={null}
const rootAuthority = Ed25519Authority.fromPublicKey(user.publicKey);
```

### After (v1.0)

```typescript theme={null}
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

```typescript theme={null}
// 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

```typescript theme={null}
// 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "dependencies": {
    "@swig-wallet/kit": "^1.0.0",
    "@solana-program/token": "^0.5.1",
    "@solana/kit": "^2.1.0"
  }
}
```

Remove old dependencies:

```bash theme={null}
npm uninstall @solana/spl-token
```

Remove old dependencies:

```bash theme={null}
npm uninstall @solana/spl-token
```

## Migration Checklist

* [ ] Update package dependencies
* [ ] Replace single instruction functions with instruction array functions
* [ ] Update authority creation from classes to info functions
* [ ] Update PDA derivation calls
* [ ] Replace `Ed25519Authority.fromPublicKey()` with `createEd25519AuthorityInfo()`
* [ ] Replace `createSessionInstruction()` with `getCreateSessionInstructions()`
* [ ] Replace sub-account functions: `createSubAccountInstruction()`, `toggleSubAccountInstruction()`, `withdrawFromSubAccountInstruction()`
* [ ] Replace Swig static methods: `Swig.create()`, `Swig.fetch()`, `Swig.fetchNullable()`
* [ ] Update function parameters from `(role, payer, ...)` to `(swig, roleId, ...)`
* [ ] Update transaction building to spread instruction arrays
* [ ] Remove direct imports of removed modules (authority, role, rpc, utils, wallet)
* [ ] Test all functionality with the new API
* [ ] Update error handling for new function signatures

## Common Migration Issues

### Issue: Functions returning arrays instead of single instructions

**Solution**: Use the spread operator when adding to transactions:

```typescript theme={null}
// Before
transaction.add(instruction);

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

### Issue: Function parameter signatures changed

**Solution**: Update function calls to use new parameter structure:

```typescript theme={null}
// 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:

```typescript theme={null}
// 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:

```typescript theme={null}
// 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:

```typescript theme={null}
// 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:

1. Check the [API documentation](https://anagrambuild.github.io/swig-ts/modules.html)
2. Review the updated [tutorials](./index)
3. Examine the [example code](https://github.com/anagrambuild/swig-ts/tree/main/examples/classic/transfer/tutorial)
4. Open an issue on the [GitHub repository](https://github.com/anagrambuild/swig-ts/issues)

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.