Migrating from 6.x.x to 7.x.x

Breaking Changes & Important Updates

Removal of Encryption Inclusion

Reference: Pull Request #608

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:

1. 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';
2. 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.
   • Import these exclusively from @lit-protocol/encryption.

     import { encryptString, decryptString } from '@lit-protocol/encryption';
3. Moved Functions and Interfaces:
   • Import the following from @lit-protocol/misc:

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

---

Changes to Enums and Constants

Reference: Pull Request #579

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:

1. Update Enums to Constants:

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

2. Specific Enum to Constant Replacements:

   Old Enum/Constant	New Constant
   WALLET_ERROR	WALLET_ERROR (as a constant)
   LitAbility	LIT_ABILITY
   LitNamespace	LIT_NAMESPACE
   LitRecapAbility	LIT_RECAP_ABILITY
   LitResourcePrefix	LIT_RESOURCE_PREFIX
   AuthMethodScope	AUTH_METHOD_SCOPE
   AuthMethodType	AUTH_METHOD_TYPE
   CENTRALISATION_BY_NETWORK	Use CENTRALISATION_BY_NETWORK.Custom
   EITHER_TYPE	EITHER_TYPE
   GENERAL_WORKER_URL_BY_NETWORK	Use GENERAL_WORKER_URL_BY_NETWORK.Custom
   HTTP_BY_NETWORK	Use HTTP_BY_NETWORK.Custom
   LIT_CURVE	LIT_CURVE
   LIT_ENDPOINT_VERSION	LIT_ENDPOINT_VERSION
   LIT_NETWORKS	Use LIT_NETWORKS.Custom
   LitErrorKind	LIT_ERROR_KIND
   LitNetwork	LIT_NETWORK
   METAMASK_CHAIN_INFO_BY_NETWORK	Use METAMASK_CHAIN_INFO_BY_NETWORK.Custom
   ProviderType	PROVIDER_TYPE
   RELAYER_URL_BY_NETWORK	Use RELAYER_URL_BY_NETWORK.Custom
   RPC_URL_BY_NETWORK	Use RPC_URL_BY_NETWORK.Custom
   StakingStates	STAKING_STATES
   VMTYPE	VMTYPE
   metamaskChainInfo	METAMASK_CHAIN_INFO
   LogLevel	LOG_LEVEL
   IRelayAuthStatus	RELAY_AUTH_STATUS

3. 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';

4. 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;

5. Backwards Compatibility:

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

---

Replacement of throwError Function

Reference: Pull Request #576migr

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:

1. 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

2. 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);
     }
   }
   

3. Refer to Documentation:

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

---

Removal of LitAuthClient

Reference: Pull Request #547

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:

1. 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 });

2. Replacing LitAuthClient.getAuthIdByAuthMethod:

   import { getAuthIdByAuthMethod } from '@lit-protocol/lit-auth-client';
   
   const authId = getAuthIdByAuthMethod(authMethod);

3. Minting PKPs with LitRelay:

   import { LitRelay } from '@lit-protocol/lit-auth-client';
   
   const relay = new LitRelay({ litNetwork: LIT_NETWORK.MAINNET });
   
   relay.mintPKPWithAuthMethods(authMethods, options);

4. 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);

5. 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);

---

Removal of PKPClient

Reference: Pull Request #541

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:

1. Replace Usage of PKPClient:

   // Old
   const pkpClient = new PKPClient(...);
   
   // New
   const pkpEthersWallet = new PKPEthersWallet(...);

2. Update Methods in PKPWalletConnect:

   Old Method	New Method
   addPKPClient	addPKPEthersWallet
   findPKPClientByRequestParams	findPKPEthersWalletByRequestParams
   getPKPClients	getPKPEthersWallets
   setPKPClients	setPKPEthersWallets

   • All methods now work with PKPEthersWallet instances instead of PKPClient.

3. Adjust Types and Interfaces:

   • Update any types or interfaces that used PKPClient to use PKPEthersWallet or PKPCosmosWallet.

4. Example of Updating Code:

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

5. Note on Supported Wallets:

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

---

Updates to PKP Wallet Classes

Reference: Pull Request #509

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:

1. 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 pkpEthersWallet = new PKPEthersWallet({
       pkpPublicKey,
       controllerAuthSig,
       litNodeClient,
     });
2. 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.
3. Removal of WalletFactory:
   • Since WalletFactory has been removed, instantiate PKP wallets directly.

     // Old way
     const pkpWallet = WalletFactory.createWallet(...);
     
     // New way
     const pkpWallet = new PKPEthersWallet({ ... });
4. Update PKPClient Usage:
   • If you use PKPClient, update it to align with the new PKP wallet classes.
5. Review Type Definitions:
   • Update any type definitions that may have changed due to stricter typing.
6. Demo App Testing:
   • If you have custom demo apps or tests, update them to use the new PKP wallet classes accordingly.

---

Migration of WASM Packages and Updates to Crypto Module

Reference: Pull Request #503

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:

1. 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';
2. 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);
3. Initialization of WASM Modules:
   • WASM modules now lazy-load when their functions are called. No manual initialization is required.
4. Update HD Key Derivation Usage:
   • Review any key derivation logic to ensure compatibility with the hd-keys-curves library.
5. Review Bundle Sizes:
   • With the consolidation, your application's bundle size may be reduced.
6. Testing:
   • Thoroughly test cryptographic functionalities in your application.

---

Renaming of getRequestId Method

Reference: Latest Pull Request

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:

1. 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 need a new request ID within a subclass, you can call:

         const requestId = this._getNewRequestId();
       • 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.
2. 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.
3. 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.

---

Removal of Compression Functions

Reference: Pull Request #621

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:

1. 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
2. Steps to Replace Removed Functions:
   • Compression:

     • 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.
3. Update Your Dependencies:
   • Add your chosen compression library to your project's dependencies.
4. Review Bundle Size:
   • By managing compression separately, you can optimize your bundle size based on your application's needs.
5. 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, ensuring better modularity, type safety, enhanced 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.