The latest version of the Lit SDK, v7, has just been released. Included are several improvements, feature additions, and breaking changes all aimed at enhancing the overall performance of the Lit SDK and developer experience on Lit. You can access the latest build (live on the Datil networks) here.

Here's everything you need to know about the latest changes and additions:

🚨 Breaking Changes & Important Updates

1. Removal of Encryption Inclusion

Changes:

• Encryption Functions:
  • Added encryptUint8Array and decryptToUint8Array in @lit-protocol/encryption for handling Uint8Array data types.
  • These functions unify encryption and decryption interfaces within the @lit-protocol/encryption package.
• Function Relocations:
  • The following have been moved from @lit-protocol/encryption to @lit-protocol/misc:
    • isTokenOperator
    • isValidBooleanExpression
    • safeParams
    • AccessControlConditionsValidatorProps
    • AuthMaterialValidatorProps
    • ParamsValidatorsType
• Export Changes:
  • Removed re-exports of @lit-protocol/encryption functions in @lit-protocol/lit-node-client-nodejs.

Migration Steps:

A. Encrypting and Decrypting Uint8Array: Replace usage of encrypt and decrypt functions in LitNodeClient with encryptUint8Array and decryptToUint8Array from @lit-protocol/encryption.

import { encryptUint8Array, decryptToUint8Array } from '@lit-protocol/encryption';

B. String and File Encryption/Decryption: Functions like encryptString, encryptFile, decryptString, and decryptFile are no longer exported from @lit-protocol/lit-node-client-nodejs or @lit-protocol/lit-node-client. These should now be imported exclusively from @lit-protocol/encryption.

import { encryptString, decryptString } from '@lit-protocol/encryption';

C. Moved Functions and Interfaces: Import the following from @lit-protocol/misc:

import {
  isTokenOperator,
  isValidBooleanExpression,
  safeParams,
  AccessControlConditionsValidatorProps,
  AuthMaterialValidatorProps,
  ParamsValidatorsType,
} from '@lit-protocol/misc';

2. Changes to Enums and Constants

Changes:

• Enums Replaced with Constants:
  • All enums are now constants in @lit-protocol/constants.
  • Types representing keys and values are exported with _TYPE and _VALUE suffixes.
• Adjusted Network Configurations:
  • Constants no longer include localhost or internalDev.
  • Use the .Custom property for custom networks.

Migration Steps:

A. Update Enums to Constants:

• Replace old enums with new constants.
• Use corresponding types for type safety.

B. Specific Enum to Constant Replacements:

C. Example of Updating Imports:

// Old import
import { LitNetwork } from '@lit-protocol/constants';

// New import
import { LIT_NETWORK, LIT_NETWORK_TYPE, LIT_NETWORK_VALUE } from '@lit-protocol/constants';

D. Handling Custom Networks:

• For configurations no longer including localhost, use the .Custom property.

const network = LIT_NETWORKS.Custom;
const rpcUrl = RPC_URL_BY_NETWORK.Custom;

E. Backwards Compatibility:

• Old names are temporarily available but will be removed in the future.
• Update your code to use the new constants.

3. Replacement of throwError Function

Changes:

• Error Handling:
  • The throwError function has been removed from the SDK.
  • Custom error classes based on VError are now used throughout the SDK for error handling.
• TypeScript and ESLint Improvements:
  • Types across the SDK have been improved to enhance TypeScript and ESLint validations.

Migration Steps:

A. Error Handling with VError:

• Update your error handling logic to work with VError instances.
• Errors thrown by the SDK can now be treated as VErrors, allowing for extended error information.
• Errors thrown from the SDK will all be instanceof Error (VError extends Error), and will include a .stack property

B. Update Error Catch Blocks:

import { VError } from '@openagenda/verror';

try {
  // SDK operations
} catch (error) {
  if (error instanceof VError) {
    // Extract extended error information
    const info = VError.info(error);
    console.error('Error message:', error.message);
    console.error('Error info:', info);
  } else {
    // Handle other errors
    console.error('An unexpected error occurred:', error);
  }
}

C. Refer to Documentation:

Check the project README.md or official documentation for detailed instructions on handling VError instances to obtain extended error information.

4. Removal of LitAuthClient

Changes:

• Removal of LitAuthClient:
  • The LitAuthClient class has been removed from the SDK.
  • Users should now initialize providers directly.
• Function Relocations:
  • Static method LitAuthClient.getAuthIdByAuthMethod is now a standalone function in @lit-protocol/lit-auth-client.
  • Method mintPKPWithAuthMethods in LitAuthClient is now a method in LitRelay.
• Export Changes:
  • LitRelay is now exported from @lit-protocol/lit-auth-client.
  • Added LitRelay.getRelayUrl(litNetwork: LitNetwork) static method.
• Deprecations and Additions:
  • Marked BaseProvider.fetchPKPsThroughRelayer as deprecated.
  • Added BaseProvider.getPKPsForAuthMethod and BaseProvider.fetchPKPs instance methods.

Migration Steps:

A. Initializing Providers Directly:

• Old Way with LitAuthClient:

const someProvider = litAuthClient.initProvider<SomeProvider>(ProviderType.ProviderType);

• New way without LitAuthClient:

import { LitRelay, EthWalletProvider } from '@lit-protocol/lit-auth-client';
import { LitNodeClient } from '@lit-protocol/lit-node-client';

const litNodeClient = new LitNodeClient();
await litNodeClient.connect();
const relay = new LitRelay({ litNetwork: LIT_NETWORK.MAINNET });

const ethWalletProvider = new EthWalletProvider({ relay, litNodeClient });

B. Replacing LitAuthClient.getAuthIdByAuthMethod:

import { getAuthIdByAuthMethod } from '@lit-protocol/lit-auth-client';

const authId = getAuthIdByAuthMethod(authMethod);

C. Minting PKPs with LitRelay:

import { LitRelay } from '@lit-protocol/lit-auth-client';

const relay = new LitRelay({ litNetwork: LIT_NETWORK.MAINNET });

relay.mintPKPWithAuthMethods(authMethods, options);

D. Updating Provider Methods:

• Deprecated Method:

provider.fetchPKPsThroughRelayer(...);

• Replacement Methods:

// Fetch PKPs directly from the blockchain
const pkps = await provider.fetchPKPs(...);

// Or get PKPs for a specific auth method
const pkps = await provider.getPKPsForAuthMethod(authMethod);

E. Using LitRelay.getRelayUrl:

import { LitRelay } from '@lit-protocol/lit-auth-client';
import { LIT_NETWORK } from '@lit-protocol/constants';

const relayUrl = LitRelay.getRelayUrl(LIT_NETWORK.MAINNET);

5. Removal of PKPClient

Changes:

• Removal of PKPClient:
  • PKPClient has been removed from the SDK.
  • Previously, PKPClient was used to abstract different wallet types.
• Updates to PKPWalletConnect:
  • Now uses PKPEthersWallet instead of PKPClient, as only Ethereum wallets are supported.
  • Methods in PKPWalletConnect have been updated to reflect this change.
  • Improved type definitions in PKPWalletConnect.

Migration Steps:

A. Replace Usage of PKPClient:

// Old
const pkpClient = new PKPClient(...);

// New
const pkpEthersWallet = new PKPEthersWallet(...);

B. Update Methods in PKPWalletConnect:

All methods now work with PKPEthersWallet instances instead of PKPClient.

C. Adjust Types and Interfaces:

• Update any types or interfaces that used PKPClient to use PKPEthersWallet or PKPCosmosWallet.
• Example of updating code:

// Old way
const pkpWalletConnect = new PKPWalletConnect();
pkpWalletConnect.addPKPClient(pkpClient);

// New way
const pkpWalletConnect = new PKPWalletConnect();
pkpWalletConnect.addPKPEthersWallet(pkpEthersWallet);

D. Note on Supported Wallets:

• Since only Ethereum wallets (PKPEthersWallet) are currently supported, ensure that your implementation aligns with this.

6. Updates to PKP Wallet Classes

Changes:

• Class Structure Adjustments:
  • PKPBase class has been made final (private constructor) to prevent extension.
  • PKPEthersWallet, PKPCosmosWallet, and PKPSuiWallet no longer extend PKPBase but implement a shared interface.
  • Public interfaces of these classes have been restricted for better encapsulation.
• Initialization Changes:
  • litNodeClient is now a required parameter when initializing PKP wallets.
  • Fields to create litNodeClient within PKP wallets have been removed; responsibility is delegated to the user.
• Removal of Redundant Instances:
  • Removed redundant litNodeClient instance inside authContext.
• Updates to PKPClient:
  • Updated PKPClient due to changes in PKP wallet classes.
• Type Definitions:
  • Fixed several type definitions for improved type safety.
• Demo App Updates:
  • Updated session signatures demo app to use all PKP wallet classes for testing signing.

Migration Steps:

A. Initialize PKP Wallets with litNodeClient:

• Old way:

const pkpEthersWallet = new PKPEthersWallet({ pkpPublicKey, controllerAuthSig });

• New way:

import { LitNodeClient } from '@lit-protocol/lit-node-client';

const litNodeClient = new LitNodeClient();
await litNodeClient.connect();

const pkpEthersWaellet = new PKPEthersWallet({
  pkpPublicKey,
  controllerAuthSig,
  litNodeClient,
});

B. Adjust Class Extensions and Interfaces:

• If you extended PKPBase, refactor your code as extending PKPBase is no longer supported.
• Implement the shared interface if custom PKP wallet functionality is needed.

C. Removal of WalletFactory:

• Since WalletFactory has been removed, instantiate PKP wallets directly.

// Old way
const pkpWallet = WalletFactory.createWallet(...);

// New way
const pkpWallet = new PKPEthersWallet({ ... });

D. Update PKPClient Usage:

• If you use PKPClient, update it to align with the new PKP wallet classes.

E. Review Type Definitions:

• Update any type definitions that may have changed due to stricter typing.

F. Demo App Testing:

• If you have custom demo apps or tests, update them to use the new PKP wallet classes accordingly.

7. Migration of WASM Packages and Updates to Crypto Module

Changes:

• Consolidation of WASM Packages:
  • Migrated the following repositories into a single packages/wasm directory within the SDK:
    • lit-bls-wasm
    • lit-ecdsa-wasm-combine
    • sev-snp-utils-wasm
• Build Process Updates:
  • The packages/wasm is now built with each run of the build pipelines.
  • Emits type declarations and new compiled binaries embedded into the binding wrapper.
  • Reduced the size of binding + WASM to approximately 393 KB.
• Cryptographic Implementations Upgrade:
  • Upgraded cryptographic implementations.
  • Now using the hd-keys-curves library over hand-migrated implementations for HD key derivation.
• Async Implementations in Crypto Module:
  • Migrated packages/crypto to async implementations.
  • Scoped invocation of loadModule to lazy-load the WASM module.
• CI/CD Pipeline Updates:
  • Updated GitHub Action jobs to use Rust toolchains for building packages/wasm.

Migration Steps:

A. Update Imports for WASM Modules:

• Update your imports to point to the new @lit-protocol/wasm package.

// Old import
import { someFunction } from 'lit-bls-wasm';

// New import
import { someFunction } from '@lit-protocol/wasm';

B. Handle Async Implementations in Crypto Module:

• Ensure that you await functions in the crypto module as they are now async.

// Old synchronous usage
const result = cryptoFunction(data);

// New async usage
const result = await cryptoFunction(data);

C. Initialization of WASM Modules:

• WASM modules now lazy-load when their functions are called. No manual initialization is required.

D. Update HD Key Derivation Usage:

• Review any key derivation logic to ensure compatibility with the hd-keys-curves library.

E. Review Bundle Sizes:

• With the consolidation, your application's bundle size may be reduced.

F. Testing:

• Thoroughly test cryptographic functionalities in your application.

8. Renaming of getRequestId Method

Changes:

• Method Renaming:
  • The method getRequestId has been renamed to _getNewRequestId to avoid confusion with getRequestIds.
  • The method _getNewRequestId is now a protected method.

Migration Steps:

A. Update Method Calls:

• If you were using getRequestId, you need to update your code as follows:
  • Old method:

const requestId = this.getRequestId();

• New method:
  • Since _getNewRequestId is now a protected method, it cannot be called from outside the class or subclass.
  • If you're outside the class and previously relied on getRequestId, you will need to refactor your code since the method is no longer publicly accessible.
  • If you're outside the class and previously relied on getRequestId, you will need to refactor your code since the method is no longer publicly accessible.

const requestId = this._getNewRequestId();

B. Avoid Misuse of Request IDs:

• The change aims to prevent consumers from generating request IDs that are not used.
• Review your code to ensure that request IDs are managed appropriately within the SDK's classes.

C. Refactor Code if Necessary:

• If your code relied on obtaining a new request ID from getRequestId, consider whether this is necessary.
• The SDK likely manages request IDs internally, and external generation is probably not needed.

9. Removal of Compression Functions

Changes:

• Removed Functions from @lit-protocol/encryption:
  • The following functions have been removed:
    • encryptZip
    • zipAndEncryptString
    • zipAndEncryptFiles
    • encryptFileAndZipWithMetadata
    • decryptToZip
    • decryptZipFileWithMetadata
• Dependency Removal:
  • Removed jszip from the bundle to reduce the bundle size.

Migration Steps:

A. Handle Compression Yourself:

• If you are using any of the removed functions, you now need to handle compression separately.
• Removed Functions:

• encryptZip
• zipAndEncryptString
• zipAndEncryptFiles
• encryptFileAndZipWithMetadata
• decryptToZip
• decryptZipFileWithMetadata

B. Steps to Replace Removed Functions:

• Use a compression library like jszip or pako directly in your application.
• Compress your data before encryption or decompress after decryption.

import { zip, unzip } from 'your-preferred-compression-library';
import { encryptUint8Array, decryptToUint8Array } from '@lit-protocol/encryption';

// Compress data
const compressedData = zip(data);

// Encrypt compressed data
const encryptedData = await encryptUint8Array({
  uint8Array: compressedData,
  // ...other parameters
});

// Decrypt data
const decryptedData = await decryptToUint8Array({
  // ...parameters
});

// Decompress data
const originalData = unzip(decryptedData);

• Encryption: Use the encryption functions provided in @lit-protocol/encryption after you handle compression.

C. Update Your Dependencies:

• Add your chosen compression library to your project's dependencies.

D. Review Bundle Size:

• By managing compression separately, you can optimize your bundle size based on your application's needs.

E. Testing:

• Test your compression and encryption/decryption flows thoroughly to ensure data integrity.

📈 General Recommendations

• Review and Update All Imports:
  • Ensure all your imports reference the correct packages and updated constants or functions.
• Type Safety:
  • Utilize the provided _TYPE and _VALUE types for enhanced type checking.
• Avoid Deprecated References:
  • Do not use old enums, classes, methods, or duplicated exports to benefit from reduced bundle sizes and future compatibility.
• Error Handling:
  • Update your error handling to accommodate the new custom error classes based on VError.
• Async Adjustments:
  • Update your code to handle async functions, especially in the crypto module.
• Compression Handling:
  • Manage compression independently using a library that suits your needs.
• Testing:
  • Thoroughly test your application after making these changes to ensure everything functions as expected.

Summary

By following this migration guide you will align your codebase with the latest updates to the Lit Protocol SDK. This will ensure enhanced modularity, type safety, error handling, and reduced bundle sizes. The updates simplify provider and wallet initialization, improve cryptographic implementations, enforce better encapsulation and method usage, and give you control over compression handling.

Note: While backward compatibility is temporarily maintained for some constants and functions, it is advisable to update your code promptly to use the new constants, functions, and error handling mechanisms to prevent future breaking changes.

As always, we're eager to hear your feedback and experiences with the new release. Your insights are invaluable in helping us continue to refine and improve the Lit SDK going forward.

You can join the Lit developer ecosystem on Discord and Telegram. We are eager to hear from you there 🙂