Skip to content

Latest commit

 

History

History
251 lines (172 loc) · 9.12 KB

README.md

File metadata and controls

251 lines (172 loc) · 9.12 KB

Prerequisite

  • node (v20.x or above)
  • rust (v1.70.00 or above)
  • wasm-pack

Getting started

pnpm install && pnpm build

Running E2E Tests

Required Environment Variables

# (Optional) Request a private rpc url from
# https://hub.conduit.xyz/chronicle-yellowstone-testnet-9qgmzfcohk
LIT_YELLOWSTONE_PRIVATE_RPC_URL=<private-rpc-url>
# (Optional) Mainnet RPC override for naga-proto / naga
LIT_MAINNET_RPC_URL=<mainnet-rpc-url>

# For live networks (naga-dev, naga-staging)
LIVE_MASTER_ACCOUNT=<master-account-private-key>

# For local network (naga-local) (default Anvil account)
LOCAL_MASTER_ACCOUNT=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

When NETWORK is set to naga-proto or naga, the test helpers only top up generated accounts with 0.01 LIT and deposit 0.01 LIT into the Lit Ledger to avoid locking up excess mainnet funds.

Command

// eg. naga-dev
NETWORK=<network-name> pnpm run test:e2e all

Target a specific spec

Use test:target when you only need to exercise one file:

pnpm run test:target packages/e2e/src/tickets/delegation.spec.ts

Append additional Jest flags after the path if you need finer filtering.

QA Starter Kit workflow

When you need to validate SDK integrations against backend or node features, lean on the QA Starter Kit. That repo installs published packages, so it mirrors how downstream teams will consume the SDK.

  1. The node team opens a feature branch for their service.
  2. Create a matching SDK branch and build the integration for that node change.
  3. Publish a snapshot (prerelease) of the SDK packages so the QA Starter Kit can install them from npm.
  4. Point the QA Starter Kit to that snapshot to perform the e2e flow before promoting the release.

This keeps QA aligned with the packages that will actually ship and avoids the drift that comes with local linking.

Running it against a local network

Generate a fresh networkContext.json for local nodes with pnpm run gen:local-network-context before running the e2e tests against the naga-local local network.

Required Environment Variables

# path to the networkContext.json file
NETWORK_CONFIG=/<path-to-lit-assets>/lit-assets/blockchain/contracts/networkContext.json

# name of the output file
NETWORK_NAME=naga-develop

# target directory
DIRECTORY_NAME=naga-local

Command

NETWORK=naga-local pnpm run test:e2e all

Artillery Load Testing

Use the standalone Artillery project under packages/artillery

Preparation

# from the repo root
pnpm install

# pick your target network: naga-dev | naga-staging | naga-test | naga-local
export NETWORK=naga-staging
export LOG_LEVEL=info           # optional: debug | debug2 | silent

For live networks that read ABI data from the networks repo (for example naga-staging), run the sync script before firing Artillery so the contracts and addresses are up to date:

pnpm run sync:contracts  # requires GH_API_KEY in your environment

Testing a custom local network? Point the runner at your generated networkContext.json and RPC URL. (/lit-assets/blockchain/contracts/networkContext.json)

const networkModule = await nagaLocal
  .withLocalContext({
    networkContextPath:
      '/Users/<username>/Projects/lit-assets/blockchain/contracts/networkContext.json',
    networkName: 'naga-local',
  })
  .withOverrides({ rpcUrl: process.env.LOCAL_RPC_URL });

If you want Artillery Cloud reports, set ARTILLERY_KEY=<your-key> in .env before running a scenario.

One-time initialisation

Master account, auth data and PKP info are written to this file: packages/artillery/artillery-state.json.

pnpm nx run artillery:init

(optional) Check master balances before blasting a load test:

pnpm nx run artillery:balance-status

Run a workload

Each scenario is exposed as an Nx target. Use the run: prefixed name:

pnpm nx run artillery:run:pkp-sign          # PKP signing focus
pnpm nx run artillery:run:encrypt-decrypt   # Encryption/decryption focus
pnpm nx run artillery:run:execute           # Lit Action execution
pnpm nx run artillery:run:mix               # Mixed workload
pnpm nx run artillery:run:sign-session-key  # Session key signing

Manual Publishing

# Generate a changeset
pnpm changeset

# Version the changeset
pnpm changeset version

# Build the packages
pnpm build

# Commit the changes
git add .
git commit -m "chore: release v0.0.1"

# Publish the packages
pnpm changeset publish

Apps

This monorepo contains two apps: Lit Auth Server and Lit Login Server.Both apps support Docker builds.

Releasing Docker Images

  • Trigger the Release Docker Images GitHub Action (.github/workflows/release-docker-images.yml) from the Actions tab once the desired changes are on the branch you want to release from.
  • When starting the workflow, select the branch ref, set auth-server-released to true, and optionally provide a custom-tag to add an extra image tag alongside the branch/commit/latest tags.
  • The job installs the Rust toolchain and wasm-pack, builds both lit-auth-server and lit-login-server via their Nx docker-build targets, and pushes images to ghcr.io/lit-protocol/<app> using the repo's GITHUB_TOKEN (or the GHCR_USERNAME/GHCR_TOKEN secrets if you supply them).
  • Published images live under:
  • Leave auth-server-released unchecked to perform a no-op dry run and confirm the workflow is available without publishing images.

One Click Deployable Images

Lit Auth Server

Deploy on Railway

Lit Login Server

Deploy on Railway

Environment configuration

  • ORIGIN: required for OAuth callbacks. Railway asks for a value during deploy—drop in a placeholder like http://localhost:3000, let the app spin up, then replace it with the generated public HTTPS domain (or your custom domain) so Google and Discord redirect URIs match. Leaving it empty keeps the local-only default and will break production flows.

Keeping the contract address and ABIs in sync with the latest changes

This command must be run manually and is NOT part of the build process, as it requires a GitHub API key.

DEV_BRANCH=develop GH_API_KEY=github_pat_xxx pnpm run sync:contracts

Keeping the docs changelog in sync with the public site

Use the sync:docs-changelog script to refresh the changelog that powers naga.developer.litprotocol.com/changelog.

pnpm run sync:docs-changelog

Note: we currently run this manually after the Changeset PR lands in the naga main branch, though we expect to automate it in CI in the future.

The script collates the latest entries from packages/*/CHANGELOG.md and rewrites the target changelog.mdx. Commit and publish the regenerated file in the docs repo so the public changelog stays current.

Legacy Documentation for V7 and Earlier

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

Contact

You can reach the Lit Protocol team through Telegram, Discord, or X.