Nitrolite is a lightweight, efficient state channel framework for Ethereum and other EVM-compatible blockchains, enabling off-chain interactions while maintaining on-chain security guarantees.

Nitrolite is a complete state channel infrastructure consisting of several main components:

1. Smart Contracts: On-chain infrastructure for state channel management (ChannelHub, ChannelEngine).
2. Clearnode: A broker providing ledger services and off-chain state management.
3. Go SDK: Comprehensive Go library for building backend and CLI applications.
4. TypeScript SDK: Client-side library for building web and mobile applications.
5. Cerebro (CLI): Interactive command-line interface for managing channels and assets.

• Instant Finality: Transactions settle immediately between parties off-chain.
• Reduced Gas Costs: Most interactions happen off-chain, with minimal on-chain footprint.
• High Throughput: Support for thousands of transactions per second.
• Security Guarantees: Same security as on-chain, backed by cryptographic proofs and challenge periods.
• Chain Agnostic: Works with any EVM-compatible blockchain.

This repository contains:

• /contracts: Solidity smart contracts for the state channel framework.
• /clearnode: Implementation of the Clearnode service.
• /sdk/go: Official Go SDK.
• /sdk/ts: Official TypeScript SDK.
• /cerebro: Clearnode CLI tool.
• /pkg: Shared Go packages (core state machine, signing, etc.).
• /docs: Protocol specifications and architectural documentation.

Nitrolite implements a state channel protocol that enables secure off-chain communication with minimal on-chain operations. The protocol includes:

• Channel Creation: A funding protocol where participants lock assets in the ChannelHub.
• Off-Chain Updates: A mechanism for exchanging and signing versioned state updates off-chain.
• Channel Closure: Multiple resolution paths including cooperative close and unilateral challenge-response.
• Checkpointing: The ability to record valid states on-chain without closing the channel.
• App Sessions: Support for multi-participant application sessions with arbitrary logic.
• Session Keys: Delegated signing authority for automated or restricted operations.

See the protocol description for complete details.

The Nitrolite contract system (built with Foundry) provides:

• ChannelHub: The central entry point for all channel operations.
• ChannelEngine: Logic for state verification and transition validation.
• Escrow Engines: Specialized logic for cross-chain deposits and withdrawals.
• SigValidators: Pluggable signature validation modules (e.g., Session Keys).

For the most up-to-date contract addresses on all supported networks, see the contract deployments directory.

See the contract README for detailed contract documentation.

Clearnode is a message broker and state manager that enables efficient off-chain payment channels.

• Multi-Chain Support: Connect to multiple EVM blockchains (Polygon, Celo, Base, etc.).
• Off-Chain Payments: High-throughput transfers with near-zero latency.
• App Sessions: Manage complex multi-party application states.
• Flexible Storage: Support for SQLite (embedded) and PostgreSQL.
• Quorum-Based Signatures: Weight-based quorum requirements for state updates.

See the Clearnode Documentation for more details.

The official Go SDK for building performant backend integrations or CLI tools.

go get github.com/erc7824/nitrolite/sdk/go

See SDK Go README.

The official TypeScript SDK for web-based applications.

npm install @erc7824/nitrolite

See SDK TS README.

Interactive CLI for interacting with Clearnode.

# From the root directory
go build -o nitrolite-cli ./cerebro
./nitrolite-cli wss://node.example.com/ws

See Cerebro README.

Get started quickly with the local development environment:

# Start the environment
docker-compose up -d

# This will:
# 1. Start a local Anvil blockchain on port 8545
# 2. Deploy core Nitrolite contracts
# 3. Seed test tokens and configuration
# 4. Start the Clearnode service.

# Run contract tests
cd contracts && forge test

# Run Go tests (requires GOCACHE redirection if restricted)
export GOCACHE=/tmp/gocache && go test ./...

Contributions are welcome! Please feel free to submit a Pull Request.

This project is licensed under the MIT License - see the LICENSE file for details.