Lit Protocol Javascript/Typescript SDK V2

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

This new V2 SDK is written in Typescript and is a complete rewrite of the old SDK. It is much more modular and easier to use, and has a much smaller bundle size.

ChangeLog: All notable changes to this project will be documented in this file.

Quick Start

NodeJS Only

Removed browser related methods eg. checkAndSignAuthSig

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

(Isomorphic) works on Node.js/browser

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

Vanilla JS (UMD)

<script src="https://cdn.jsdelivr.net/npm/@lit-protocol/lit-node-client-vanilla/lit-node-client.js"></script>
<script>
  const authSig = LitJsSdk_litNodeClient.checkAndSignAuthMessage({chain: 'ethereum'});
</script>

Packages

📝 If you're looking to use the Lit SDK, you're probably all set with just the lit-node-client . It's got everything most folks need. However, if you're the type who likes to keep things super lean and mean, and you need to keep an eagle eye on your bundle size, we've got individual packages too.

Individual packages are below so that you can import the minimum required packages for your use case.

Package	Category	Version	Download
@lit-protocol/lit-node-client-nodejs		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/lit-node-client		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/access-control-conditions		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/auth-helpers		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/bls-sdk		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/constants		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/contracts-sdk		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/core		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/crypto		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/ecdsa-sdk		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/encryption		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/lit-third-party-libs		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/misc		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/nacl		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/pkp-base		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/pkp-client		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/pkp-cosmos		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/pkp-ethers		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/pkp-walletconnect		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/types		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/uint8arrays		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/auth-browser		2.2.25	npm Vanilla JS (UMD)
@lit-protocol/misc-browser		2.2.25	npm Vanilla JS (UMD)

API Doc

http://docs.lit-js-sdk-v2.litprotocol.com/

Demo

App	Link
Simple Encrypt Decrypt	https://demo.encrypt-decrypt.react.litprotocol.com/
Contracts SDK	https://demo.contracts-sdk.react.litprotocol.com/
(Test) Html	http://test.lit-js-sdk-v2.html.litprotocol.com/
(Test) React	http://test.lit-js-sdk-v2.react.litprotocol.com/

NOTE: For (Test) apps, all packages and functions can be called inside the browser console. eg. window.LitJsSdk_[package_name].[function_name]

Contributing and developing to this SDK

Recommended VSCode Extensions

Nx Console

Download: https://nx.dev/core-features/integrate-with-editors

Restore Terminal

Download: https://marketplace.visualstudio.com/items?itemName=EthanSK.restore-terminals See Video

  "restoreTerminals.terminals": [
    {See [Video](https://streamable.com/e/5g52m4)
      "splitTerminals": [
        // {
        //   "name": "nx graph",
        //   "commands": ["yarn graph"]
        // },
        {
          "name": "nodejs",
          "commands": ["yarn nx run nodejs:serve"]
        },
        {
          "name": "html",
          "commands": ["yarn nx run html:serve"]
        },
        {
          "name": "react",
          "commands": ["yarn nx run react:serve"]
        },
        {
          "name": "custom",
          "commands": ["clear"]
        }
      ]
    }
  ]

Workflow

CLI (WIP)

yarn tools

Dev

// this will open
// html: http://localhost:4002
// react: http://localhost:4003
// nodejs: in this terminal
yarn tools --dev --apps

// usually i will open another temrinal to watch the package
// i'm developing
yarn tools --watch --target <package-name>

Creating a new library

By default, NX provides a command to generate a library nx generate @nrwl/js:library. However, it doesn't have an esbuild built-in so that we've created a custom tool that modify the build commands.

yarn gen:lib <package-name> <tag>

Create a new react demo app using the Lit JS SDK

yarn tools --create --react contracts-sdk --demo

Deleting a library

yarn tool:delete (--package OR --app) <project-name>

Building

yarn build

// or
yarn tools --build

Building target package

yarn nx run <project-name>:build

// or
yarn tools --build --target <project-name>

// or targeted env
yarn nx run <project-name>:_buildTsc
yarn nx run <project-name>:_buildWeb

Watching

// watch all packages change
yarn tools --watch

// watch a target package
yarn tools --watch <package-name>

// watch a target package with all its monorepo dependencies
yarn tools --watch <package-name>--deps

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.
2. Run yarn build:target <package> to build that specific package.
3. In the client application, run npm link <package> --force 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.

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.

Publishing

Run yarn bump to bump the version. You must have at least nodejs v18 to do this. Next, run yarn buildAndPublish to build and then publish.

to npm

yarn publish:packages

clone & publish to npm

yarn tools --clone <project-name> <clone-project-name> <(?) --publish> <(?) --remove-after>

// eg
yarn tools --clone lit-node-client @litprotocol/dev --publish --remove-after

HTML Test app to Vercel

yarn tool:buildHtml

Testing

Quick Start on E2E Testing

The following will serve the react testing app and launch the cypress e2e testing after

yarn test:e2e

Environments

There are currently three environments can be tested on, each of which can be generated from a custom command, which would automatically import all the libraries in ./packages/*. The UI of HTML & React are visually identical but they are using different libraries.

Environment	Generate Command	Test Location
HTML	yarn gen:html	http://localhost:4002
React	yarn gen:react	http://localhost:4003
NodeJs	yarn gen:nodejs	yarn nx run nodejs:serve

Unit Tests (for Node)

yarn test:unit

E2E Testing with Metamask using Cypress (for Browser)

Since both HTML & React UIs are identical, we can run the same test suite against two different environments of libraries. This is done by setting the PORT number before Cypress launch.

HTML

// E2E HTML
yarn tools --test --e2e html

React

// E2E React
yarn tools --test --e2e react

Other Commands

Interactive graph dependencies using NX

yarn graph

FAQs & Common Errors

(React) Failed to parse source map from

In your React package.json, add GENERATE_SOURCEMAP=false to your start script

eg.

  "scripts": {
    "start": "GENERATE_SOURCEMAP=false react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },

Web bundling using esbuild

It’s currently using a custom plugin @websaam/nx-esbuild which is a fork from @wanews/nx-esbuild

"_buildWeb": {
    "executor": "@websaam/nx-esbuild:package",
    "options": {
      "banner": {
        "js": "import { createRequire } from 'module';const require = createRequire(import.meta.url);"
      },
      "globalName": "LitJsSdk_CoreBrowser",
      "outfile":"dist/packages/core-browser-vanilla/core-browser.js",
      "entryPoints": ["./packages/core-browser/src/index.ts"],
      "define": { "global": "window" },
      "plugins":[
        {
          "package": "esbuild-node-builtins",
          "function": "nodeBuiltIns"
        }
      ]
    }
  }

Reference Error: crypto is not defined

import crypto, { createHash } from 'crypto';
Object.defineProperty(globalThis, 'crypto', {
  value: {
    getRandomValues: (arr: any) => crypto.randomBytes(arr.length),
    subtle: {
      digest: (algorithm: string, data: Uint8Array) => {
        return new Promise((resolve, reject) =>
          resolve(
            createHash(algorithm.toLowerCase().replace('-', ''))
              .update(data)
              .digest()
          )
        );
      },
    },
  },
});

error Command failed with exit code 13.

Make sure your node version is above v16.16.0