Lit Protocol Javascript/Typescript SDK V7.x.x

The Lit JavaScript SDK provides developers with a framework for implementing Lit functionality into their own applications. Find installation instructions in the docs to get started with the Lit SDK based on your use case:

https://developer.litprotocol.com/SDK/Explanation/installation

yarn add @lit-protocol/lit-node-client-nodejs
Copy

yarn add @lit-protocol/lit-node-client
Copy

Packages

📝 If you're looking to use the Lit SDK, you're probably all set with just the lit-node-client .
Get started with interacting with Lit network!

Package	Category	Download
@lit-protocol/lit-node-client-nodejs
@lit-protocol/lit-node-client

If you're a tech-savvy user and wish to utilize only specific submodules that our main module relies upon, you can find individual packages listed below. This way, you can import only the necessary packages that cater to your specific use case::

Package	Category	Download
@lit-protocol/access-control-conditions
@lit-protocol/auth-helpers
@lit-protocol/constants
@lit-protocol/contracts-sdk
@lit-protocol/core
@lit-protocol/crypto
@lit-protocol/encryption
@lit-protocol/event-listener
@lit-protocol/logger
@lit-protocol/misc
@lit-protocol/nacl
@lit-protocol/pkp-base
@lit-protocol/pkp-cosmos
@lit-protocol/pkp-ethers
@lit-protocol/pkp-sui
@lit-protocol/pkp-walletconnect
@lit-protocol/types
@lit-protocol/uint8arrays
@lit-protocol/wasm
@lit-protocol/wrapped-keys
@lit-protocol/wrapped-keys-lit-actions
@lit-protocol/auth-browser
@lit-protocol/misc-browser

API Doc

Version	Link
V7 (Current)	7.x.x docs
V6	6.x.x docs
V5	5.x.x docs
V2	2.x.x docs

Contributing and developing to this SDK

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js v19.0.0 or later
• Rust v1.70.0 or later
• wasm-pack for WebAssembly compilation

Development Tools

Recommended for better development experience:

• NX Console - Visual Studio Code extension for NX workspace management

Quick Start

To start developing with this repository:

1. Install dependencies:

yarn
Copy

2. Build the packages:

yarn build:dev
Copy

Building

Build the project using one of these commands:

// For local development (optimized, excludes production-only operations)
yarn build:dev

// For testing and publishing (full build with all operations)
yarn build
Copy

Run unit tests

yarn test:unit
Copy

Run E2E tests in nodejs

yarn test:local
Copy

Advanced

Creating a new library

nx generate @nx/js:library

Building

yarn build
Copy

Building target package

yarn nx run <project-name>:build
Copy

Building Local Changes

During development you may wish to build your code changes in packages/ in a client application to test the correctness of the functionality.

If you would like to establish a dependency between packages within this monorepo and an external client application that consumes these packages:

1. Run npm link at the root of the specific package you are making code changes in.

cd ./packages/*/<package-name>
npm link
Copy

2. Build the packages with or without dependencies

yarn build
# or
yarn nx run lit-node-client-nodejs:build --with-deps=false
Copy

3. In the client application, run npm link <package> --save to ensure that the package.json of the client application is updated with a file: link to the dependency. This effectively creates a symlink in the node_modules of the client application to the local dependency in this repository.

cd path/to/client-application
npm link <package> --save
Copy

Having done this setup, this is what the development cycle looks like moving forward:

1. Make code change
2. Rebuild specific package
3. Rebuild client application.

Building Rust Components

For changes to WebAssembly components in packages/wasm, refer to the WebAssembly build guide.

Publishing New Versions

Prerequisites:

• Node.js v18.0.0 or later

Publishing steps:

1. Create a release PR:

   • Create a new branch from master with format vX.X.X-Publish
   • Add changelog as PR description
   • Add "Release" label to the PR
   • Reference example: https://github.com/LIT-Protocol/js-sdk/pull/753

2. After PR approval, proceed with publishing:

   • Update dependencies: yarn install
   • Increment version: yarn bump
   • Build packages: yarn build
   • Run tests:
     • Unit tests: yarn test:unit
     • E2E tests: yarn test:local
   • Generate documentation: yarn gen:docs --push
   • Publish packages: yarn publish:packages
   • Commit with message: "Published version X.X.X"

Testing Guide

Available Test Commands

Running Tests

1. Unit Tests:

   yarn test:unit
   Copy

2. End-to-End Tests:

   yarn test:local
   Copy

   Optional Environment Variables:

   • NETWORK=<network_name> (datil, datil-test, datil-dev, etc.)
   • DEBUG=true/false

   Optional Flags:

   • --filter=

   See more in local-tests/README.md

Local Development with Lit Node

Setup Local Environment

1. Deploy Lit Node Contracts (addresses will be read from ../lit-assets/blockchain/contracts/deployed-lit-node-contracts-temp.json)

2. Configure environment variables:

# Enable local node development
export LIT_JS_SDK_LOCAL_NODE_DEV="true"

# Set funded wallet for Chronicle testnet
export LIT_JS_SDK_FUNDED_WALLET_PRIVATE_KEY="your-funded-private-key"
Copy

Environment Variables

Error Handling Guide

Overview

The SDK implements a robust error handling system using @openagenda/verror. This system provides:

• Detailed error information with cause tracking
• Error composition and chaining
• Additional context through metadata
• Compatibility with native JavaScript Error handling

Using Error Handling

Basic Example

import { VError } from '@openagenda/verror';
import { LitNodeClientBadConfigError } from '@lit-protocol/constants';

try {
  // Simulate an error condition
  const someNativeError = new Error('some native error');

  // Throw a Lit-specific error with context
  throw new LitNodeClientBadConfigError(
    {
      cause: someNativeError,
      info: { foo: 'bar' },
      meta: { baz: 'qux' },
    },
    'some useful message'
  );
} catch (e) {
  // Access error details
  console.log(e.name); // LitNodeClientBadConfigError
  console.log(e.message); // some useful message: some native error
  console.log(e.info); // { foo: 'bar' }
  console.log(e.baz); // qux

  // Additional error information
  // - VError.cause(e): Original error (someNativeError)
  // - VError.info(e): Additional context ({ foo: 'bar' })
  // - VError.meta(e): Metadata ({ baz: 'qux', code: 'lit_node_client_bad_config_error', kind: 'Config' })
  // - VError.fullStack(e): Complete error chain stack trace
}
Copy

Creating Custom Errors

To add new error types:

1. Locate packages/constants/src/lib/errors.ts
2. Add your error definition to the LIT_ERROR object
3. Export the new error class
4. Import and use in your code with relevant context:

   throw new YourCustomError(
     {
       cause: originalError,
       info: {
         /* context */
       },
       meta: {
         /* metadata */
       },
     },
     'Error message'
   );
   Copy

Dockerfile

...coming soon

Other Commands

Core Systems and Services

The Lit Protocol SDK provides the following core systems:

• Cryptographic key management (PKP - Programmable Key Pair)
• Blockchain wallet interactions (Ethereum, Solana, Cosmos)
• Decentralized authentication and authorization
• Distributed computing and signing
• Smart contract management
• Access control and encryption services

Main Functions and Classes

Key components available across packages:

• PKPEthersWallet: Ethereum wallet management for PKP
• LitNodeClient: Network interaction client
• executeJs(): Decentralized JavaScript execution
• signMessageWithEncryptedKey(): Cryptographic signing
• generatePrivateKey(): Key generation utilities
• TinnyEnvironment: Testing environment setup

Troubleshooting Guide

Common Issues and Solutions

Crypto API Error

Problem: "Reference Error: crypto is not defined"

Solution: Add the following polyfill for environments without native crypto:

import crypto, { createHash } from 'crypto';

// Add crypto to global scope
Object.defineProperty(globalThis, 'crypto', {
  value: {
    // Implement getRandomValues
    getRandomValues: (arr: any) => crypto.randomBytes(arr.length),

    // Implement subtle crypto
    subtle: {
      digest: (algorithm: string, data: Uint8Array) => {
        return new Promise((resolve) =>
          resolve(
            createHash(algorithm.toLowerCase().replace('-', ''))
              .update(data)
              .digest()
          )
        );
      },
    },
  },
});
Copy

Unexpected Error on Node

Problem: Exit code 13

Solution: Make sure your node version is above v18.0.0