From 68c130c313354ce8b8c9f20a1dcb2f1b36c8d27e Mon Sep 17 00:00:00 2001 From: Max Pushkarov Date: Tue, 27 May 2025 15:51:01 +0300 Subject: [PATCH 1/4] docs: update package reference --- docs/nitrolite_client/index.mdx | 12 ++- docs/nitrolite_client/methods.mdx | 30 ++++++-- docs/nitrolite_client/types.md | 89 ++++++++++++++-------- docs/nitrolite_rpc/message_creation_api.md | 63 +++++++++------ docs/nitrolite_rpc/rpc_types.md | 4 +- 5 files changed, 135 insertions(+), 63 deletions(-) diff --git a/docs/nitrolite_client/index.mdx b/docs/nitrolite_client/index.mdx index d56e022..0ddb591 100644 --- a/docs/nitrolite_client/index.mdx +++ b/docs/nitrolite_client/index.mdx @@ -45,6 +45,7 @@ const nitroliteClient = new NitroliteClient({ guestAddress: '0x...', tokenAddress: '0x...' }, + chainId: 137, // Polygon mainnet challengeDuration: 100n }); @@ -59,8 +60,15 @@ const { channelId, initialState, txHash } = await nitroliteClient.createChannel( // 3. Resize the channel when needed const resizeTxHash = await nitroliteClient.resizeChannel({ - channelId, - candidateState: updatedState + resizeState: { + channelId, + stateData: '0x5678', + allocations: newAllocations, + version: 2n, + intent: StateIntent.RESIZE, + serverSignature: signature + }, + proofStates: [] }); // 4. Close the channel diff --git a/docs/nitrolite_client/methods.mdx b/docs/nitrolite_client/methods.mdx index d533197..2cd7f39 100644 --- a/docs/nitrolite_client/methods.mdx +++ b/docs/nitrolite_client/methods.mdx @@ -110,8 +110,15 @@ The deposit phase includes methods for managing funds in the custody contract an params={[{ name: "params", type: "ResizeChannelParams" }]} returns="Promise" example={`await client.resizeChannel({ - channelId, // The ID of the channel to resize - candidateState // The latest state reflecting the new desired total allocation + resizeState: { + channelId, + stateData: '0x5678', + allocations: newAllocations, + version: 2n, + intent: StateIntent.RESIZE, + serverSignature: signature + }, + proofStates: [] });`} /> @@ -176,7 +183,13 @@ For Account Abstraction support and transaction preparation methods, see the [Ab import { NitroliteClient } from '@erc7824/nitrolite'; // Initialize the client -const client = new NitroliteClient({/* config */}); +const client = new NitroliteClient({ + publicClient, + walletClient, + addresses: { custody, adjudicator, guestAddress, tokenAddress }, + chainId: 137, + challengeDuration: 100n +}); // 1. Deposit funds const depositTxHash = await client.deposit(1000000n); @@ -193,8 +206,15 @@ console.log(`Locked in channels: ${accountInfo.locked}`); // 4. Later, resize the channel const resizeTxHash = await client.resizeChannel({ - channelId, - candidateState: updatedState // With new allocations + resizeState: { + channelId, + stateData: '0x5678', + allocations: newAllocations, + version: 2n, + intent: StateIntent.RESIZE, + serverSignature: signature + }, + proofStates: [] }); // 5. Close the channel diff --git a/docs/nitrolite_client/types.md b/docs/nitrolite_client/types.md index 3eb8533..607f5e0 100644 --- a/docs/nitrolite_client/types.md +++ b/docs/nitrolite_client/types.md @@ -97,19 +97,32 @@ Represents a complete state channel state, including allocations and signatures. ```typescript interface NitroliteClientConfig { - // Required: viem PublicClient for reading blockchain data + /** The viem PublicClient for reading blockchain data. */ publicClient: PublicClient; - - // Required: viem WalletClient for sending transactions and account context + + /** + * The viem WalletClient used for: + * 1. Sending on-chain transactions in direct execution methods (e.g., `client.deposit`). + * 2. Providing the 'account' context for transaction preparation (`client.txPreparer`). + * 3. Signing off-chain states *if* `stateWalletClient` is not provided. + */ walletClient: WalletClient>; - - // Optional: Separate wallet client for signing states + + /** + * Optional: A separate viem WalletClient used *only* for signing off-chain state updates (`signMessage`). + * Provide this if you want to use a different key (e.g., a "hot" key from localStorage) + * for state signing than the one used for on-chain transactions. + * If omitted, `walletClient` will be used for state signing. + */ stateWalletClient?: WalletClient>; - - // Required: Contract addresses + + /** Contract addresses required by the SDK. */ addresses: ContractAddresses; - - // Required: Challenge duration in seconds + + /** Chain ID for the channel */ + chainId: number; + + /** Optional: Default challenge duration (in seconds) for new channels. Defaults to 0 if omitted. */ challengeDuration?: bigint; } ``` @@ -162,9 +175,15 @@ interface ChallengeChannelParams { } interface ResizeChannelParams { - channelId: ChannelId; // Channel ID to resize - candidateState: State; // State with new allocations - proofStates?: State[]; // Optional proof states + resizeState: { + channelId: ChannelId; + stateData: Hex; + allocations: [Allocation, Allocation]; + version: bigint; + intent: StateIntent; + serverSignature: Signature; + }; + proofStates: State[]; } ``` @@ -194,7 +213,6 @@ Parameters for collaboratively closing a channel. ```typescript interface AccountInfo { available: bigint; // Available funds in the custody contract - locked: bigint; // Funds locked in channels channelCount: bigint; // Number of channels } ``` @@ -230,10 +248,10 @@ const allowance: bigint = await client.getTokenAllowance() ```typescript // Create channel -const result: { - channelId: ChannelId; - initialState: State; - txHash: Hash +const result: { + channelId: ChannelId; + initialState: State; + txHash: Hash } = await client.createChannel({ initialAllocationAmounts: [bigint, bigint], stateData: Hex @@ -245,20 +263,31 @@ const result: { ```typescript // Resize await client.resizeChannel({ - channelId: ChannelId, - candidateState: State + resizeState: { + channelId: ChannelId, + stateData: Hex, + allocations: [Allocation, Allocation], + version: bigint, + intent: StateIntent, + serverSignature: Signature + }, + proofStates: State[] }): Promise -// State is structured as: -const state: State = { - intent: StateIntent.RESIZE, - version: 2n, // Incremented from previous - data: '0x1234', - allocations: [ - { destination: addr1, token: tokenAddr, amount: 600000n }, - { destination: addr2, token: tokenAddr, amount: 400000n } - ], - sigs: [signature1, signature2] +// Resize is structured as: +const resizeParams: ResizeChannelParams = { + resizeState: { + channelId, + stateData: '0x1234', + allocations: [ + { destination: addr1, token: tokenAddr, amount: 600000n }, + { destination: addr2, token: tokenAddr, amount: 400000n } + ], + version: 2n, // Incremented from previous + intent: StateIntent.RESIZE, + serverSignature: signature + }, + proofStates: [] } ``` @@ -343,4 +372,4 @@ const finalState = { ], sigs: [userSig, guestSig] }; -``` \ No newline at end of file +``` diff --git a/docs/nitrolite_rpc/message_creation_api.md b/docs/nitrolite_rpc/message_creation_api.md index 052dd2f..9c291cd 100644 --- a/docs/nitrolite_rpc/message_creation_api.md +++ b/docs/nitrolite_rpc/message_creation_api.md @@ -115,36 +115,35 @@ Functions for retrieving information from the broker. @@ -154,19 +153,37 @@ const getBalancesMsg = await createGetLedgerBalancesMessage(signer, channelId); description="Creates the signed, stringified message body for a 'get_app_definition' request to retrieve the definition of a specific application." params={[ { name: "signer", type: "MessageSigner", description: "The function to sign the request payload." }, - { name: "appId", type: "AccountID", description: "The Application ID to get the definition for." }, + { name: "appSessionId", type: "AccountID", description: "The Application Session ID to get the definition for." }, { name: "requestId", type: "RequestID", description: "Optional request ID. Defaults to a generated ID.", optional: true }, { name: "timestamp", type: "Timestamp", description: "Optional timestamp. Defaults to the current time.", optional: true } ]} returns="Promise" example={` import { createGetAppDefinitionMessage } from "@erc7824/nitrolite"; -// Assuming 'signer' and 'appId' are defined -const getAppDefMsg = await createGetAppDefinitionMessage(signer, appId); +// Assuming 'signer' and 'appSessionId' are defined +const getAppDefMsg = await createGetAppDefinitionMessage(signer, appSessionId); // Send getAppDefMsg via WebSocket `} /> + + ## Application Session Management Functions for creating and closing application sessions (state channels). @@ -177,15 +194,14 @@ Functions for creating and closing application sessions (state channels). params={[ { name: "signer", type: "MessageSigner", description: "The function to sign the request payload." }, { name: "params", type: "CreateAppSessionRequest[]", description: "An array of parameters defining the application session(s) to be created. See RPC Type Definitions for `CreateAppSessionRequest` structure." }, - { name: "intent", type: "Intent", description: "The initial allocation intent for the application session." }, { name: "requestId", type: "RequestID", description: "Optional request ID. Defaults to a generated ID.", optional: true }, { name: "timestamp", type: "Timestamp", description: "Optional timestamp. Defaults to the current time.", optional: true } ]} returns="Promise" example={` -import { createAppSessionMessage, Intent } from "@erc7824/nitrolite"; -// Assuming 'signer', 'appSessionParams', and 'initialIntent' are defined -const createAppMsg = await createAppSessionMessage(signer, appSessionParams, initialIntent); +import { createAppSessionMessage } from "@erc7824/nitrolite"; +// Assuming 'signer' and 'appSessionParams' are defined +const createAppMsg = await createAppSessionMessage(signer, appSessionParams); // Send createAppMsg via WebSocket `} /> @@ -196,15 +212,14 @@ const createAppMsg = await createAppSessionMessage(signer, appSessionParams, ini params={[ { name: "signer", type: "MessageSigner", description: "The function to sign the request payload." }, { name: "params", type: "CloseAppSessionRequest[]", description: "An array of parameters defining the application session(s) to be closed, including final allocations. See RPC Type Definitions for `CloseAppSessionRequest` structure." }, - { name: "intent", type: "Intent", description: "The final allocation intent for the application session." }, { name: "requestId", type: "RequestID", description: "Optional request ID. Defaults to a generated ID.", optional: true }, { name: "timestamp", type: "Timestamp", description: "Optional timestamp. Defaults to the current time.", optional: true } ]} returns="Promise" example={` -import { createCloseAppSessionMessage, Intent } from "@erc7824/nitrolite"; -// Assuming 'signer', 'closeParams', and 'finalIntent' are defined -const closeAppMsg = await createCloseAppSessionMessage(signer, closeParams, finalIntent); +import { createCloseAppSessionMessage } from "@erc7824/nitrolite"; +// Assuming 'signer' and 'closeParams' are defined +const closeAppMsg = await createCloseAppSessionMessage(signer, closeParams); // Send closeAppMsg via WebSocket `} /> @@ -218,7 +233,7 @@ Function for sending messages within an active application session. description="Creates the signed, stringified message body for sending a generic 'message' within an active application session (state channel). This is used for off-chain state updates and other application-specific communication." params={[ { name: "signer", type: "MessageSigner", description: "The function to sign the request payload." }, - { name: "appId", type: "AccountID", description: "The Application ID (state channel ID) the message is scoped to." }, + { name: "appSessionId", type: "Hex", description: "The Application Session ID the message is scoped to." }, { name: "messageParams", type: "any[]", description: "The actual message content/parameters being sent, specific to the application logic." }, { name: "requestId", type: "RequestID", description: "Optional request ID. Defaults to a generated ID.", optional: true }, { name: "timestamp", type: "Timestamp", description: "Optional timestamp. Defaults to the current time.", optional: true } @@ -226,8 +241,8 @@ Function for sending messages within an active application session. returns="Promise" example={` import { createApplicationMessage } from "@erc7824/nitrolite"; -// Assuming 'signer', 'appId', and 'appSpecificMessageData' are defined -const appMsg = await createApplicationMessage(signer, appId, [appSpecificMessageData]); +// Assuming 'signer', 'appSessionId', and 'appSpecificMessageData' are defined +const appMsg = await createApplicationMessage(signer, appSessionId, [appSpecificMessageData]); // Send appMsg via WebSocket `} /> @@ -249,8 +264,8 @@ Functions for managing the underlying ledger channels (direct channels with the returns="Promise" example={` import { createCloseChannelMessage } from "@erc7824/nitrolite"; -// Assuming 'signer', 'channelId', and 'destinationAddress' are defined -const closeChannelMsg = await createCloseChannelMessage(signer, channelId, destinationAddress); +// Assuming 'signer', 'channelId', and 'fundDestination' are defined +const closeChannelMsg = await createCloseChannelMessage(signer, channelId, fundDestination); // Send closeChannelMsg via WebSocket `} /> diff --git a/docs/nitrolite_rpc/rpc_types.md b/docs/nitrolite_rpc/rpc_types.md index f9a87b7..2848c31 100644 --- a/docs/nitrolite_rpc/rpc_types.md +++ b/docs/nitrolite_rpc/rpc_types.md @@ -249,9 +249,9 @@ const pingRequestMessage: NitroliteRPCMessage = { }; // Example Application-Specific Request -const appActionData: RequestData = [2, "app_action", [{ move: "rock" }], Date.now()]; +const appActionData: RequestData = [2, "message", [{ move: "rock" }], Date.now()]; const appActionMessage: ApplicationRPCMessage = { - acc: "0xAppChannelId...", + sid: "0xAppSessionId...", req: appActionData, // sig: ["0xSignature..."] }; From f8f3bf6878d88975f8d5cef0e37e744ece23135a Mon Sep 17 00:00:00 2001 From: Max Pushkarov Date: Tue, 27 May 2025 15:56:30 +0300 Subject: [PATCH 2/4] docs: add icons to doc cards for improved visual navigation --- docs/index.md | 20 ++++++++++---------- docs/nitrolite_client/index.mdx | 6 +++--- docs/nitrolite_rpc/index.md | 8 ++++---- 3 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/index.md b/docs/index.md index 8534416..9bef9e5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,52 +15,52 @@ The following guides will walk you through the complete lifecycle of state chann diff --git a/docs/nitrolite_client/index.mdx b/docs/nitrolite_client/index.mdx index 0ddb591..9efe236 100644 --- a/docs/nitrolite_client/index.mdx +++ b/docs/nitrolite_client/index.mdx @@ -13,17 +13,17 @@ The `NitroliteClient` class is the main entry point for interacting with Nitroli diff --git a/docs/nitrolite_rpc/index.md b/docs/nitrolite_rpc/index.md index 75d0d1f..5eb6c00 100644 --- a/docs/nitrolite_rpc/index.md +++ b/docs/nitrolite_rpc/index.md @@ -14,12 +14,12 @@ The NitroliteRPC provides a secure, reliable real-time communication protocol fo @@ -165,12 +165,12 @@ Dive deeper into the specifics of the RPC system: From 74e78c304044e6406171b8dee8d0549068a5a032 Mon Sep 17 00:00:00 2001 From: Max Pushkarov Date: Tue, 27 May 2025 16:10:56 +0300 Subject: [PATCH 3/4] docs: drop redundant old example --- docs/nitrolite_rpc/message_creation_api.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/nitrolite_rpc/message_creation_api.md b/docs/nitrolite_rpc/message_creation_api.md index 9c291cd..39e17ed 100644 --- a/docs/nitrolite_rpc/message_creation_api.md +++ b/docs/nitrolite_rpc/message_creation_api.md @@ -287,12 +287,6 @@ const resizeMsg = await createResizeChannelMessage(signer, resizeParams); // Send resizeMsg via WebSocket `} /> -// ...existing code... -// Assuming 'signer' and 'resizeParams' are defined -const resizeMsg = await createResizeChannelMessage(signer, resizeParams); -// Send resizeMsg via WebSocket -`} -/> ## Advanced: Creating a Local Signer for Development @@ -376,7 +370,7 @@ export const createEthersSigner = (privateKey: string): WalletSigner => { const messageToSign = JSON.stringify(payload); const messageHash = ethers.utils.id(messageToSign); // ethers.utils.id performs keccak256 const messageBytes = ethers.utils.arrayify(messageHash); - + const flatSignature = await wallet._signingKey().signDigest(messageBytes); const signature = ethers.utils.joinSignature(flatSignature); return signature as Hex; From db385fe3c0e43a820cab409b2f184564f1d67da0 Mon Sep 17 00:00:00 2001 From: Max Pushkarov Date: Tue, 27 May 2025 16:17:39 +0300 Subject: [PATCH 4/4] Revert "docs: add icons to doc cards for improved visual navigation" This reverts commit f8f3bf6878d88975f8d5cef0e37e744ece23135a. --- docs/index.md | 20 ++++++++++---------- docs/nitrolite_client/index.mdx | 6 +++--- docs/nitrolite_rpc/index.md | 8 ++++---- 3 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/index.md b/docs/index.md index 9bef9e5..8534416 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,52 +15,52 @@ The following guides will walk you through the complete lifecycle of state chann diff --git a/docs/nitrolite_client/index.mdx b/docs/nitrolite_client/index.mdx index 9efe236..0ddb591 100644 --- a/docs/nitrolite_client/index.mdx +++ b/docs/nitrolite_client/index.mdx @@ -13,17 +13,17 @@ The `NitroliteClient` class is the main entry point for interacting with Nitroli diff --git a/docs/nitrolite_rpc/index.md b/docs/nitrolite_rpc/index.md index 5eb6c00..75d0d1f 100644 --- a/docs/nitrolite_rpc/index.md +++ b/docs/nitrolite_rpc/index.md @@ -14,12 +14,12 @@ The NitroliteRPC provides a secure, reliable real-time communication protocol fo @@ -165,12 +165,12 @@ Dive deeper into the specifics of the RPC system: