> ## Documentation Index
> Fetch the complete documentation index at: https://build.onswig.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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/tutorial/classic)
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.