NitroliteService

The NitroliteService class is the core service that directly interacts with the Nitrolite Custody smart contract. It handles channel management, deposits, withdrawals, and all other channel-specific operations following the channel lifecycle.

Initialization

import { NitroliteService } from '@erc7824/nitrolite';

const nitroliteService = new NitroliteService(
  publicClient,  // viem PublicClient
  addresses,     // ContractAddresses
  walletClient,  // viem WalletClient
  account        // Account address
);

Channel Lifecycle Methods

1. Deposit Operations

Method	Description	Parameters	Return Type
`deposit`	Deposits tokens/ETH into the custody contract.	`tokenAddress: Address, amount: bigint`	`Promise<Hash>`
`withdraw`	Withdraws tokens from the custody contract.	`tokenAddress: Address, amount: bigint`	`Promise<Hash>`

Example:

// Deposit ETH or token
const txHash = await nitroliteService.deposit(tokenAddress, amount);

// Withdraw ETH or token
const txHash = await nitroliteService.withdraw(tokenAddress, amount);

2. Channel Creation

Method	Description	Parameters	Return Type
`createChannel`	Creates a new channel with the given parameters.	`channel: Channel, initialState: State`	`Promise<Hash>`

Example:

// Create a channel
const txHash = await nitroliteService.createChannel(channel, initialState);

Where:

channel defines the participants, adjudicator, challenge period, and nonce
initialState contains the initial allocation of funds and state data

3. Channel Operations

Method	Description	Parameters	Return Type
`checkpoint`	Checkpoints a state on-chain.	`channelId: ChannelId, candidateState: State, proofStates?: State[]`	`Promise<Hash>`
`challenge`	Challenges a channel with a candidate state.	`channelId: ChannelId, candidateState: State, proofStates?: State[]`	`Promise<Hash>`
`resize`	Resizes a channel with a candidate state.	`channelId: ChannelId, candidateState: State, proofStates?: State[]`	`Promise<Hash>`

Example:

// Checkpoint a channel state
const txHash = await nitroliteService.checkpoint(channelId, candidateState);

// Challenge a channel
const txHash = await nitroliteService.challenge(channelId, candidateState);

// Resize a channel
const txHash = await nitroliteService.resize(channelId, candidateState);

4. Channel Closing

Method	Description	Parameters	Return Type
`close`	Closes a channel using a final state.	`channelId: ChannelId, finalState: State`	`Promise<Hash>`

Example:

// Close a channel
const txHash = await nitroliteService.close(channelId, finalState);

5. Account Information

Method	Description	Parameters	Return Type
`getAccountChannels`	Gets channel IDs for an account.	`accountAddress: Address`	`Promise<ChannelId[]>`
`getAccountInfo`	Gets account info for a token.	`accountAddress: Address, tokenAddress: Address`	`Promise<AccountInfo>`

Example:

// Get all channels for an account
const channels = await nitroliteService.getAccountChannels(accountAddress);

// Get detailed account info
const info = await nitroliteService.getAccountInfo(accountAddress, tokenAddress);
console.log(`Available: ${info.available}, Locked: ${info.locked}`);

Transaction Preparation Methods

For Account Abstraction support, NitroliteService provides transaction preparation methods that return transaction data without executing it:

Method	Description	Parameters	Return Type
`prepareDeposit`	Prepares deposit transaction.	`tokenAddress: Address, amount: bigint`	`Promise<PreparedTransaction>`
`prepareCreateChannel`	Prepares channel creation transaction.	`channel: Channel, initialState: State`	`Promise<PreparedTransaction>`
`prepareCheckpoint`	Prepares checkpoint transaction.	`channelId: ChannelId, candidateState: State, proofStates?: State[]`	`Promise<PreparedTransaction>`
`prepareChallenge`	Prepares challenge transaction.	`channelId: ChannelId, candidateState: State, proofStates?: State[]`	`Promise<PreparedTransaction>`
`prepareResize`	Prepares resize transaction.	`channelId: ChannelId, candidateState: State, proofStates?: State[]`	`Promise<PreparedTransaction>`
`prepareClose`	Prepares close transaction.	`channelId: ChannelId, finalState: State`	`Promise<PreparedTransaction>`
`prepareWithdraw`	Prepares withdraw transaction.	`tokenAddress: Address, amount: bigint`	`Promise<PreparedTransaction>`

Example:

// Prepare deposit transaction
const tx = await nitroliteService.prepareDeposit(tokenAddress, amount);

// Use with your Account Abstraction provider
const userOp = await aaProvider.buildUserOperation({
  target: tx.to,
  data: tx.data,
  value: tx.value || 0n
});

Implementation Details

The NitroliteService connects to the Custody contract using:

A viem PublicClient for read operations
A viem WalletClient for write operations and signing
The contract address specified in the configuration

The service handles:

Contract interaction
Parameter validation
Error handling
Transaction preparation

Error Handling

The NitroliteService throws specific error types:

ContractCallError: When calls to the contract fail
InvalidParameterError: When parameters are invalid
MissingParameterError: When required parameters are missing
WalletClientRequiredError: When wallet client is needed but not provided
AccountRequiredError: When account is needed but not provided

Example:

try {
  await nitroliteService.deposit(tokenAddress, amount);
} catch (error) {
  if (error instanceof ContractCallError) {
    console.error(`Contract call failed: ${error.message}`);
    console.error(`Suggestion: ${error.suggestion}`);
  }
}

Advanced Usage

Custom Contract Interaction

For advanced use cases, you might need to interact directly with the contract:

// Get the custody contract address
const custodyAddress = nitroliteService.custodyAddress;

// Use with your own custom contract interaction
const customContract = getContract({
  address: custodyAddress,
  abi: custodyAbi,
  // Additional configuration...
});

Multiple Channel Management

For applications managing multiple channels:

// Get all channels for the account
const channels = await nitroliteService.getAccountChannels(accountAddress);

// Process each channel
for (const channelId of channels) {
  // Get channel info from contract
  // Process channel state
}

NitroliteService

On this page