From 8ba009a68c985b401deb02589ed3b5b0fcd89f54 Mon Sep 17 00:00:00 2001 From: anson Date: Tue, 21 Oct 2025 18:18:43 +0100 Subject: [PATCH 1/7] chore(docs): improve docs on how payment works in v8 --- docs/sdk/getting-started/auth-services.mdx | 19 +++ .../getting-started/payment-manager-setup.mdx | 116 ++++++++++++++---- 2 files changed, 110 insertions(+), 25 deletions(-) diff --git a/docs/sdk/getting-started/auth-services.mdx b/docs/sdk/getting-started/auth-services.mdx index f34a7c894..fed1db5d3 100644 --- a/docs/sdk/getting-started/auth-services.mdx +++ b/docs/sdk/getting-started/auth-services.mdx @@ -32,6 +32,25 @@ Lit hosts default Auth Service instances so you can build without deploying infr configuration. +## Payment Delegation APIs + +The Auth Service also exposes lightweight endpoints that sponsor user requests on the network. These are the same APIs the Lit SDK calls when you use `litClient.authService.registerPayer` / `delegateUsers` from the Payment Manager guide. + +- `POST /register-payer` + - Headers: `x-api-key`. + - Behaviour: generates a random `payerSecretKey`, hashes it with the API key, and derives a child wallet from `LIT_DELEGATION_ROOT_MNEMONIC`. + - Response: `{ success, payerWalletAddress, payerSecretKey }`. The service **does not** persist the secret—you must store it securely (KMS, vault, etc.). + - Rotation: call the endpoint again with the same API key to rotate the secret and derive a new child wallet. +- `POST /add-users` + - Headers: `x-api-key`, `payer-secret-key`; body is a JSON array of user addresses. + - Behaviour: recomputes the same child wallet on the fly and calls `PaymentManager.delegatePaymentsBatch` so the payer sponsors those users. + + + Running the Auth Service yourself keeps the derivation mnemonic and payer secrets inside your infrastructure. The Lit-hosted instance is great for quick starts, but you remain responsible for storing the returned `payerSecretKey`. + + +If you prefer not to run an Auth Service at all, you can still sponsor users manually: create a payer wallet, fund it, and call `paymentManager.delegatePayments*` directly from your backend. See [Payment Manager Setup](/sdk/getting-started/payment-manager-setup#sponsoring-your-users-capacity-delegation-replacement) for sample code. + ### Install the SDK diff --git a/docs/sdk/getting-started/payment-manager-setup.mdx b/docs/sdk/getting-started/payment-manager-setup.mdx index 22357b869..5a6b54c11 100644 --- a/docs/sdk/getting-started/payment-manager-setup.mdx +++ b/docs/sdk/getting-started/payment-manager-setup.mdx @@ -1,6 +1,6 @@ --- -title: "Payment Manager Setup" -description: "Configure payment system for the Lit JS SDK" +title: 'Payment Manager Setup' +description: 'Configure payment system for the Lit JS SDK' --- @@ -26,7 +26,7 @@ The Payment Manager demonstrates Lit Protocol's payment system - a billing syste - Encryption/Decryption - Secure data with programmable access control - PKP Signing - Cryptographic keys that can sign transactions based on conditions - Lit Actions - Serverless functions with cryptographic capabilities -Similar to how you pay AWS for cloud computing, this\system ensures the decentralised network can sustain itself and pay node operators. You can deposit funds, request withdrawals with security delays, and manage balances for yourself or other users (enabling applications to sponsor their users' costs for better UX). + Similar to how you pay AWS for cloud computing, this\system ensures the decentralised network can sustain itself and pay node operators. You can deposit funds, request withdrawals with security delays, and manage balances for yourself or other users (enabling applications to sponsor their users' costs for better UX). @@ -42,6 +42,7 @@ const litClient = await createLitClient({ network: nagaTest }); const paymentManager = await litClient.getPaymentManager({ account: yourAccount // viem account instance }); + ```` @@ -59,7 +60,7 @@ const { data: myAccount } = useWalletClient(); ```typescript viem/accounts // 1. import the privateKeyToAccount function from viem/accounts -import { privateKeyToAccount } from "viem/accounts"; +import { privateKeyToAccount } from 'viem/accounts'; // 2. Convert your private key to a viem account object that can be used for payment operations. const myAccount = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`); @@ -74,7 +75,7 @@ const myAccount = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`); ```typescript Deposit funds to your own account // 1. Deposit funds to your own account const result = await paymentManager.deposit({ - amountInEth: "0.1", + amountInEth: '0.1', }); console.log(`Deposit successful: ${result.hash}`); @@ -84,8 +85,8 @@ console.log(`Deposit successful: ${result.hash}`); ```typescript Deposit for another user // 1. Deposit funds for another user const result = await paymentManager.depositForUser({ - userAddress: "0x742d35Cc6638Cb49f4E7c9ce71E02ef18C53E1d5", - amountInEth: "0.05", + userAddress: '0x742d35Cc6638Cb49f4E7c9ce71E02ef18C53E1d5', + amountInEth: '0.05', }); console.log(`Deposit successful: ${result.hash}`); @@ -97,12 +98,84 @@ console.log(`Deposit successful: ${result.hash}`); +## Sponsoring Your Users (Capacity Delegation Replacement) + +If your app previously minted Capacity Credits and handed users a `CapacityDelegationAuthSig`, the equivalent Naga flow is: + +1. **Fund a payer wallet** – call `litClient.getPaymentManager({ account })` and deposit $LITKEY ($tstLPX in testnet) into the ledger contract (see examples above). +2. **Register the payer** – decide how you want to provision and operate the sponsor wallet: + - **Lit-hosted Auth Service** – call `authService.registerPayer`; Lit derives the wallet + `payerSecretKey` for you (ideal for prototypes). + - **Self-hosted Auth Service** – deploy the open-source service (see [Auth Services setup](/sdk/getting-started/auth-services)) so derivation stays within your infrastructure. You’ll supply your own `LIT_DELEGATION_ROOT_MNEMONIC`. + - **Manual (no Auth Service)** – generate a wallet yourself (e.g. `privateKeyToAccount`) and store the private key securely; you’ll call the Payment Manager directly in the next step. +3. **Delegate end-user addresses** – map users to the payer: + - Using an Auth Service: POST to `authService.add-users`. + - Manual route: call `paymentManager.delegatePayments*` with your server-side account; this writes to the same Payment Delegation contract. + + + For production environments we recommend running your own Auth Service (self-hosted) so you retain full custody over the `LIT_DELEGATION_ROOT_MNEMONIC` and derivation secrets. The Lit-hosted Auth Service is handy for prototypes and quick starts, but you still remain responsible for storing the returned `payerSecretKey` securely. + +4. **Users decrypt as normal** – the browser still calls `litClient.decrypt` with an auth context; the network draws fees from the delegated payer instead of the user’s wallet. + +```typescript server +// Manual delegation without Auth Service +import { createLitClient } from '@lit-protocol/lit-client'; +import { privateKeyToAccount } from 'viem/accounts'; +import { nagaTest } from '@lit-protocol/networks'; + +const payerAccount = privateKeyToAccount( + process.env.PAYER_PRIVATE_KEY as `0x${string}` +); +const litClient = await createLitClient({ network: nagaTest }); + +const paymentManager = await litClient.getPaymentManager({ + account: payerAccount, +}); + +// Delegate a single user +await paymentManager.delegatePayments({ userAddress: '0xUser...' }); + +// Or delegate multiple users in one transaction +await paymentManager.delegatePaymentsBatch({ + userAddresses: ['0xAlice...', '0xBob...'], +}); +``` + +```typescript +// Client-side decrypt with sponsored payments +const authContext = await authManager.createEoaAuthContext({ + litClient, + config: { account: walletClient }, + authConfig: { + resources: [ + ['access-control-condition-decryption', '*'], + ['lit-action-execution', '*'], + ], + }, +}); + +const response = await litClient.decrypt({ + data: encryptedData, + unifiedAccessControlConditions: accs, + authContext, + chain: 'ethereum', + userMaxPrice: BigInt('200000000000000000'), // optional guardrail +}); +``` + +Behind the scenes the SDK: + +- Builds a pricing context during handshake (product, per-node prices, threshold). +- Encrypts requests per node using the JIT keyset. +- Emits per-node max price in the session signature. +- Lets the validators call `Ledger.chargeUser` against the delegated payer wallet. + ## Auth Service API Endpoints -Leverage the hosted Auth Service to manage delegation without exposing private keys in your application: +Leverage the hosted Auth Service to manage delegation without exposing private keys in your application. Full request/response details live in the [Auth Services setup guide](/sdk/getting-started/auth-services#payment-delegation-apis). In practice you will: -- `POST /register-payer` - Send your `x-api-key` header to receive a delegated payer address and `payerSecretKey`. Persist this secret securely; it is required for all future delegation calls. -- `POST /add-users` - Provide headers `x-api-key` and `payer-secret-key` plus a JSON body containing an array of user addresses. The Auth Service uses the Payment Manager internally to delegate payments to each address in a single transaction. +- Call `authService.registerPayer` (hosted or self-hosted) to derive a payer wallet + `payerSecretKey`. +- Call `authService.delegateUsers` (`/add-users`) to sponsor a list of user addresses. +- Or skip the service entirely and use the Payment Manager methods directly (example below). > The legacy capacity-credit minting flow has been removed. Payment delegation now interacts directly with the Payment Manager contracts. @@ -118,8 +191,8 @@ const apiKey = process.env.LIT_API_KEY!; // 3. Register a payer wallet (store the secret securely server-side) const registerResponse = await litClient.authService.registerPayer({ -authServiceBaseUrl, -apiKey, + authServiceBaseUrl, + apiKey, }); console.log('Payer wallet:', registerResponse.payerWalletAddress); @@ -127,26 +200,19 @@ console.log('Payer secret (store securely!):', registerResponse.payerSecretKey); // 4. Later on, delegate payments for multiple users using the saved secret const delegateResponse = await litClient.authService.delegateUsers({ -authServiceBaseUrl, -apiKey, -payerSecretKey: registerResponse.payerSecretKey, -userAddresses: [ - '0x1234...abcd', - '0xabcd...1234', -], + authServiceBaseUrl, + apiKey, + payerSecretKey: registerResponse.payerSecretKey, + userAddresses: ['0x1234...abcd', '0xabcd...1234'], }); console.log('Delegation submitted with tx hash:', delegateResponse.txHash); // 5. Continue to use the same payer secret for future delegation calls -```` +``` ### How the Auth Service derives payer wallets -- The service holds a single root mnemonic (`LIT_DELEGATION_ROOT_MNEMONIC`). -- `/register-payer` combines the `x-api-key` header with a freshly generated `payerSecretKey`. That pair is hashed into a deterministic derivation index, which is then used with the root mnemonic to derive a unique child wallet. -- The response includes the derived wallet address and the random `payerSecretKey`. The server does not store this secret; you must persist it securely on the client side. -- Later, `/add-users` expects both headers (`x-api-key` and `payer-secret-key`). The service recomputes the same derivation index and wallet on the fly, so the same header pair always maps to the same child wallet. -- Calling `/register-payer` again with the same API key issues a new random `payerSecretKey`, which leads to a different child wallet. Choose whether to rotate secrets or keep the original one depending on your application needs. +- For hosted or self-hosted deployments, see the derivation and rotation notes in the [Auth Services guide](/sdk/getting-started/auth-services#payment-delegation-apis). Manual deployments can always provision and delegate entirely via the `PaymentManager` helper without touching these endpoints. ![](https://www.plantuml.com/plantuml/png/XPAn3jCm48PtFyMfKw8IiKSAQcab1a1K58c1CXpEaLWaJcHVIlFs6DkKcBHYYy-Vl_Floyuo6fxwJh3YZc0_SGjdCbSb2KuuzwGPZjHHWwm6BSJeS2NLYAw-ENJAxMy0BOJFT7ifyz3lGbodv3l5qG3lKMD3nlFn-ndh6RTyr3lSFTN5MYo96Xc_eINOh8F2OT1iKFeUzuKGLGKVgL6MoS28CnceAX5lNhnQ1YpXzE7y2LwQY1SUl-ZiLk2eYXyqvsA1hqw_8Kq6cKARCqb3VD57CkfAy1ExZXY-cw67NbC_Q2LX2quCJfnwdJXSi0ogp_xilguDMNlH2_rRcdt2-0m4aoLZ_viGwxhmv3BSYz2iiDuSAXxwydMLEmwaX8RYBBDSnABR_plY4fmCcToZEbUgMM1Ub0uxGoc7INCk0XNJf509Ibj6pGfvPVyNhUCZnRfzZIpRp4VCHGgxu_TVo1zSlAxuim75WoPy0qEIrCWhPJeBZxPeswUpjvEKP2rix-IET3trtIy0) From d69c453bed5bb5b7e08017d6aa40b60e23888642 Mon Sep 17 00:00:00 2001 From: Anson Date: Tue, 21 Oct 2025 18:21:57 +0100 Subject: [PATCH 2/7] Update docs/sdk/getting-started/payment-manager-setup.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Anson --- docs/sdk/getting-started/payment-manager-setup.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/getting-started/payment-manager-setup.mdx b/docs/sdk/getting-started/payment-manager-setup.mdx index 5a6b54c11..95c22e1aa 100644 --- a/docs/sdk/getting-started/payment-manager-setup.mdx +++ b/docs/sdk/getting-started/payment-manager-setup.mdx @@ -109,7 +109,7 @@ If your app previously minted Capacity Credits and handed users a `CapacityDeleg - **Manual (no Auth Service)** – generate a wallet yourself (e.g. `privateKeyToAccount`) and store the private key securely; you’ll call the Payment Manager directly in the next step. 3. **Delegate end-user addresses** – map users to the payer: - Using an Auth Service: POST to `authService.add-users`. - - Manual route: call `paymentManager.delegatePayments*` with your server-side account; this writes to the same Payment Delegation contract. + - Manual route: call `paymentManager.delegatePayments` (for a single user) or `paymentManager.delegatePaymentsBatch` (for multiple users) with your server-side account; this writes to the same Payment Delegation contract. For production environments we recommend running your own Auth Service (self-hosted) so you retain full custody over the `LIT_DELEGATION_ROOT_MNEMONIC` and derivation secrets. The Lit-hosted Auth Service is handy for prototypes and quick starts, but you still remain responsible for storing the returned `payerSecretKey` securely. From 1701eecfb2fec39086ce6ba62d8018baa76e31e8 Mon Sep 17 00:00:00 2001 From: anson Date: Tue, 21 Oct 2025 18:31:23 +0100 Subject: [PATCH 3/7] fix(docs): clarify payment manager setup instructions and update legacy flow description --- docs/sdk/getting-started/payment-manager-setup.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/sdk/getting-started/payment-manager-setup.mdx b/docs/sdk/getting-started/payment-manager-setup.mdx index 5a6b54c11..b6c711660 100644 --- a/docs/sdk/getting-started/payment-manager-setup.mdx +++ b/docs/sdk/getting-started/payment-manager-setup.mdx @@ -102,7 +102,7 @@ console.log(`Deposit successful: ${result.hash}`); If your app previously minted Capacity Credits and handed users a `CapacityDelegationAuthSig`, the equivalent Naga flow is: -1. **Fund a payer wallet** – call `litClient.getPaymentManager({ account })` and deposit $LITKEY ($tstLPX in testnet) into the ledger contract (see examples above). +1. **Fund a payer wallet** – call `litClient.getPaymentManager({ account })` and deposit `$LITKEY` (`$tstLPX` in testnet) into the ledger contract (see examples above). 2. **Register the payer** – decide how you want to provision and operate the sponsor wallet: - **Lit-hosted Auth Service** – call `authService.registerPayer`; Lit derives the wallet + `payerSecretKey` for you (ideal for prototypes). - **Self-hosted Auth Service** – deploy the open-source service (see [Auth Services setup](/sdk/getting-started/auth-services)) so derivation stays within your infrastructure. You’ll supply your own `LIT_DELEGATION_ROOT_MNEMONIC`. @@ -165,7 +165,7 @@ const response = await litClient.decrypt({ Behind the scenes the SDK: - Builds a pricing context during handshake (product, per-node prices, threshold). -- Encrypts requests per node using the JIT keyset. +- Encrypts requests per node using the keyset. - Emits per-node max price in the session signature. - Lets the validators call `Ledger.chargeUser` against the delegated payer wallet. @@ -177,7 +177,7 @@ Leverage the hosted Auth Service to manage delegation without exposing private k - Call `authService.delegateUsers` (`/add-users`) to sponsor a list of user addresses. - Or skip the service entirely and use the Payment Manager methods directly (example below). -> The legacy capacity-credit minting flow has been removed. Payment delegation now interacts directly with the Payment Manager contracts. +> The legacy (V7, Datil) capacity-credit minting flow has been removed. Payment delegation now interacts directly with the Payment Manager contracts. ```typescript import { createLitClient } from '@lit-protocol/lit-client'; @@ -214,5 +214,3 @@ console.log('Delegation submitted with tx hash:', delegateResponse.txHash); ### How the Auth Service derives payer wallets - For hosted or self-hosted deployments, see the derivation and rotation notes in the [Auth Services guide](/sdk/getting-started/auth-services#payment-delegation-apis). Manual deployments can always provision and delegate entirely via the `PaymentManager` helper without touching these endpoints. - -![](https://www.plantuml.com/plantuml/png/XPAn3jCm48PtFyMfKw8IiKSAQcab1a1K58c1CXpEaLWaJcHVIlFs6DkKcBHYYy-Vl_Floyuo6fxwJh3YZc0_SGjdCbSb2KuuzwGPZjHHWwm6BSJeS2NLYAw-ENJAxMy0BOJFT7ifyz3lGbodv3l5qG3lKMD3nlFn-ndh6RTyr3lSFTN5MYo96Xc_eINOh8F2OT1iKFeUzuKGLGKVgL6MoS28CnceAX5lNhnQ1YpXzE7y2LwQY1SUl-ZiLk2eYXyqvsA1hqw_8Kq6cKARCqb3VD57CkfAy1ExZXY-cw67NbC_Q2LX2quCJfnwdJXSi0ogp_xilguDMNlH2_rRcdt2-0m4aoLZ_viGwxhmv3BSYz2iiDuSAXxwydMLEmwaX8RYBBDSnABR_plY4fmCcToZEbUgMM1Ub0uxGoc7INCk0XNJf509Ibj6pGfvPVyNhUCZnRfzZIpRp4VCHGgxu_TVo1zSlAxuim75WoPy0qEIrCWhPJeBZxPeswUpjvEKP2rix-IET3trtIy0) From faf1d8b94f9ba7771b00284932184ad5d920bdda Mon Sep 17 00:00:00 2001 From: anson Date: Wed, 22 Oct 2025 17:53:12 +0100 Subject: [PATCH 4/7] chore(docs): update payment manager setup --- docs/sdk/getting-started/payment-manager-setup.mdx | 2 +- packages/lit-client/src/lib/LitClient/createLitClient.ts | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/sdk/getting-started/payment-manager-setup.mdx b/docs/sdk/getting-started/payment-manager-setup.mdx index 519131336..d867adb0e 100644 --- a/docs/sdk/getting-started/payment-manager-setup.mdx +++ b/docs/sdk/getting-started/payment-manager-setup.mdx @@ -158,7 +158,7 @@ const response = await litClient.decrypt({ unifiedAccessControlConditions: accs, authContext, chain: 'ethereum', - userMaxPrice: BigInt('200000000000000000'), // optional guardrail + userMaxPrice: 1000000000000000000n, // required for sponsored sessions, typically the same value as the restriction the sponsor set; optional guardrail when self-funded }); ``` diff --git a/packages/lit-client/src/lib/LitClient/createLitClient.ts b/packages/lit-client/src/lib/LitClient/createLitClient.ts index 089553ade..81acf039c 100644 --- a/packages/lit-client/src/lib/LitClient/createLitClient.ts +++ b/packages/lit-client/src/lib/LitClient/createLitClient.ts @@ -919,6 +919,7 @@ export const _createNagaLitClient = async ( pkpPublicKey: string | Hex; authContext: AuthContextSchema2; chainConfig: Chain; + userMaxPrice?: bigint }) => { const _pkpPublicKey = HexPrefixedSchema.parse(params.pkpPublicKey); @@ -934,6 +935,7 @@ export const _createNagaLitClient = async ( toSign: data, authContext: params.authContext, bypassAutoHashing: options?.bypassAutoHashing, + userMaxPrice: params.userMaxPrice, }); return res.signature; From e37a26b627e2e472f3842e42ce4137293bc9a88f Mon Sep 17 00:00:00 2001 From: anson Date: Wed, 22 Oct 2025 17:55:05 +0100 Subject: [PATCH 5/7] fix(docs): update auth service API details and remove outdated SDK information --- docs/sdk/getting-started/payment-manager-setup.mdx | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/docs/sdk/getting-started/payment-manager-setup.mdx b/docs/sdk/getting-started/payment-manager-setup.mdx index d867adb0e..26c3d89b5 100644 --- a/docs/sdk/getting-started/payment-manager-setup.mdx +++ b/docs/sdk/getting-started/payment-manager-setup.mdx @@ -162,13 +162,6 @@ const response = await litClient.decrypt({ }); ``` -Behind the scenes the SDK: - -- Builds a pricing context during handshake (product, per-node prices, threshold). -- Encrypts requests per node using the keyset. -- Emits per-node max price in the session signature. -- Lets the validators call `Ledger.chargeUser` against the delegated payer wallet. - ## Auth Service API Endpoints Leverage the hosted Auth Service to manage delegation without exposing private keys in your application. Full request/response details live in the [Auth Services setup guide](/sdk/getting-started/auth-services#payment-delegation-apis). In practice you will: @@ -186,8 +179,8 @@ import { nagaTest } from '@lit-protocol/networks'; // 1. Create the Lit client for the naga-test environment const litClient = await createLitClient({ network: nagaTest }); -const authServiceBaseUrl = 'https://naga-test-auth-service.example.com'; -const apiKey = process.env.LIT_API_KEY!; +const authServiceBaseUrl = 'https://naga-test-auth-service.getlit.dev/'; +const apiKey = process.env.YOUR_AUTH_SERVICE_API_KEY!; // 3. Register a payer wallet (store the secret securely server-side) const registerResponse = await litClient.authService.registerPayer({ From 3d4599f0b14a3cb7b33d06016b9ed7d541e3d79c Mon Sep 17 00:00:00 2001 From: anson Date: Wed, 22 Oct 2025 18:34:39 +0100 Subject: [PATCH 6/7] fmt --- packages/lit-client/src/lib/LitClient/createLitClient.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/lit-client/src/lib/LitClient/createLitClient.ts b/packages/lit-client/src/lib/LitClient/createLitClient.ts index 81acf039c..d2a8a239c 100644 --- a/packages/lit-client/src/lib/LitClient/createLitClient.ts +++ b/packages/lit-client/src/lib/LitClient/createLitClient.ts @@ -919,7 +919,7 @@ export const _createNagaLitClient = async ( pkpPublicKey: string | Hex; authContext: AuthContextSchema2; chainConfig: Chain; - userMaxPrice?: bigint + userMaxPrice?: bigint; }) => { const _pkpPublicKey = HexPrefixedSchema.parse(params.pkpPublicKey); From c6e6188cf692dd3e947e1b92b7d33bb72049083a Mon Sep 17 00:00:00 2001 From: anson Date: Wed, 29 Oct 2025 14:42:17 +0000 Subject: [PATCH 7/7] docs: update auth-services and payment-manager setup documentation for clarity and accuracy --- docs/sdk/getting-started/auth-services.mdx | 2 +- .../getting-started/payment-manager-setup.mdx | 105 +++++++++++------- 2 files changed, 67 insertions(+), 40 deletions(-) diff --git a/docs/sdk/getting-started/auth-services.mdx b/docs/sdk/getting-started/auth-services.mdx index fed1db5d3..a37e7af5c 100644 --- a/docs/sdk/getting-started/auth-services.mdx +++ b/docs/sdk/getting-started/auth-services.mdx @@ -24,7 +24,7 @@ Lit hosts default Auth Service instances so you can build without deploying infr | ----------- | ------------------------------------------- | ------------------------------ | ----- | | `naga-dev` | `https://naga-dev-auth-service.getlit.dev` | `https://login.litgateway.com` | Use Lit's hosted endpoints while you prototype. Configure your SDK or environment variables with the URLs in this table. | | `naga-test` | `https://naga-test-auth-service.getlit.dev` | `https://login.litgateway.com` | Start with the hosted endpoints for staging, then switch to your own infrastructure as you scale. | -| `naga` | `Run your own (recommended)` | `Run your own (recommended)` | Lit does not operate public Auth Service or Login Server endpoints for `naga` | +| `naga` | `Run your own (recommended)` | `Run your own (recommended)` | Lit does not (yet) operate public Auth Service or Login Server endpoints for `naga` | The hosted services are best suited for prototyping. Self-host the Auth diff --git a/docs/sdk/getting-started/payment-manager-setup.mdx b/docs/sdk/getting-started/payment-manager-setup.mdx index 26c3d89b5..c5f3a3688 100644 --- a/docs/sdk/getting-started/payment-manager-setup.mdx +++ b/docs/sdk/getting-started/payment-manager-setup.mdx @@ -4,8 +4,12 @@ description: 'Configure payment system for the Lit JS SDK' --- - ❗️ Currently free on the dev network, so no need to deposit funds. More - details coming soon for test and production networks. + ❗️ Payment status by network: + - **naga-dev** – usage is currently free; no deposits required. + - **naga-test** – payments are enabled using test tokens (see faucet link + below). + - **Mainnet** – coming soon; mainnet payment details will be announced + shortly. @@ -23,10 +27,11 @@ description: 'Configure payment system for the Lit JS SDK' The Payment Manager demonstrates Lit Protocol's payment system - a billing system for decentralised cryptographic services. Users pay for compute resources on the Lit network to access core services like: -- Encryption/Decryption - Secure data with programmable access control -- PKP Signing - Cryptographic keys that can sign transactions based on conditions -- Lit Actions - Serverless functions with cryptographic capabilities - Similar to how you pay AWS for cloud computing, this\system ensures the decentralised network can sustain itself and pay node operators. You can deposit funds, request withdrawals with security delays, and manage balances for yourself or other users (enabling applications to sponsor their users' costs for better UX). +- [Encryption/Decryption](/sdk/auth-context-consumption/encrypt-and-decrypt) - Secure data with programmable access control. +- [PKP Signing](/sdk/auth-context-consumption/pkp-sign) - Cryptographic keys that can sign transactions based on conditions. +- [Lit Actions](/sdk/auth-context-consumption/execute-js) - Serverless functions with cryptographic capabilities. + +Similar to how you pay AWS for cloud computing, this system ensures the decentralised network can sustain itself and pay node operators. Each payer keeps a balance in the on-chain Lit Ledger contract funded with `$LITKEY` (or `$tstLPX` on testnet), which the network debits as requests execute. You can deposit funds, request withdrawals with security delays, and manage balances for yourself or other users (enabling applications to sponsor their users' costs for better UX). @@ -40,7 +45,7 @@ const litClient = await createLitClient({ network: nagaTest }); // 2. Get PaymentManager instance (requires account for transactions) const paymentManager = await litClient.getPaymentManager({ -account: yourAccount // viem account instance + account: yourAccount // viem account instance }); ```` @@ -98,49 +103,73 @@ console.log(`Deposit successful: ${result.hash}`); -## Sponsoring Your Users (Capacity Delegation Replacement) +## Sponsoring Your Users -If your app previously minted Capacity Credits and handed users a `CapacityDelegationAuthSig`, the equivalent Naga flow is: + + -1. **Fund a payer wallet** – call `litClient.getPaymentManager({ account })` and deposit `$LITKEY` (`$tstLPX` in testnet) into the ledger contract (see examples above). -2. **Register the payer** – decide how you want to provision and operate the sponsor wallet: - - **Lit-hosted Auth Service** – call `authService.registerPayer`; Lit derives the wallet + `payerSecretKey` for you (ideal for prototypes). - - **Self-hosted Auth Service** – deploy the open-source service (see [Auth Services setup](/sdk/getting-started/auth-services)) so derivation stays within your infrastructure. You’ll supply your own `LIT_DELEGATION_ROOT_MNEMONIC`. - - **Manual (no Auth Service)** – generate a wallet yourself (e.g. `privateKeyToAccount`) and store the private key securely; you’ll call the Payment Manager directly in the next step. -3. **Delegate end-user addresses** – map users to the payer: - - Using an Auth Service: POST to `authService.add-users`. - - Manual route: call `paymentManager.delegatePayments` (for a single user) or `paymentManager.delegatePaymentsBatch` (for multiple users) with your server-side account; this writes to the same Payment Delegation contract. + Define spending limits for the users you want to sponsor (values are in wei). - - For production environments we recommend running your own Auth Service (self-hosted) so you retain full custody over the `LIT_DELEGATION_ROOT_MNEMONIC` and derivation secrets. The Lit-hosted Auth Service is handy for prototypes and quick starts, but you still remain responsible for storing the returned `payerSecretKey` securely. - -4. **Users decrypt as normal** – the browser still calls `litClient.decrypt` with an auth context; the network draws fees from the delegated payer instead of the user’s wallet. + -```typescript server -// Manual delegation without Auth Service -import { createLitClient } from '@lit-protocol/lit-client'; -import { privateKeyToAccount } from 'viem/accounts'; -import { nagaTest } from '@lit-protocol/networks'; +```typescript +await paymentManager.setRestriction({ + totalMaxPrice: '1000000000000000000', // 1 ETH equivalent limit + requestsPerPeriod: '100', // max number of sponsored requests in a period + periodSeconds: '3600', // rolling window (1 hour in this example) +}); +``` -const payerAccount = privateKeyToAccount( - process.env.PAYER_PRIVATE_KEY as `0x${string}` -); -const litClient = await createLitClient({ network: nagaTest }); + -const paymentManager = await litClient.getPaymentManager({ - account: payerAccount, -}); + + + -// Delegate a single user -await paymentManager.delegatePayments({ userAddress: '0xUser...' }); + With restrictions set, delegate one or more users to spend from your payer wallet. -// Or delegate multiple users in one transaction + + +```typescript await paymentManager.delegatePaymentsBatch({ userAddresses: ['0xAlice...', '0xBob...'], }); ``` + + + + + + + Undelegate users when you no longer want to sponsor them. + + + ```typescript +await paymentManager.undelegatePaymentsBatch({ + userAddresses: ['0xAlice...'], +}); +``` + + + + + + +## **Alternatively** + +Manage delegation via the hosted or self-hosted Auth Service (see [Auth Services setup](/sdk/getting-started/auth-services) for the full flow). + +## After Payment Delegation + +**Users decrypt as normal** – we still call `litClient.decrypt` with an auth context; the network draws fees from the delegated payer instead of the user’s wallet. + + + ℹ️ `userMaxPrice` is recommended for sponsored sessions, typically the same value or less than the the restriction the sponsor set; optional guardrail when self-funded. + + +```typescript highlight={18} // Client-side decrypt with sponsored payments const authContext = await authManager.createEoaAuthContext({ litClient, @@ -158,7 +187,7 @@ const response = await litClient.decrypt({ unifiedAccessControlConditions: accs, authContext, chain: 'ethereum', - userMaxPrice: 1000000000000000000n, // required for sponsored sessions, typically the same value as the restriction the sponsor set; optional guardrail when self-funded + userMaxPrice: 1000000000000000000n, }); ``` @@ -170,8 +199,6 @@ Leverage the hosted Auth Service to manage delegation without exposing private k - Call `authService.delegateUsers` (`/add-users`) to sponsor a list of user addresses. - Or skip the service entirely and use the Payment Manager methods directly (example below). -> The legacy (V7, Datil) capacity-credit minting flow has been removed. Payment delegation now interacts directly with the Payment Manager contracts. - ```typescript import { createLitClient } from '@lit-protocol/lit-client'; import { nagaTest } from '@lit-protocol/networks';