{"id":27134698,"url":"https://github.com/erc7824/nitrolite","last_synced_at":"2025-08-10T21:03:05.678Z","repository":{"id":285512412,"uuid":"958383771","full_name":"erc7824/nitrolite","owner":"erc7824","description":"Nitrolite is a simplified version of Nitro that facilitates prototyping of state-channel applications","archived":false,"fork":false,"pushed_at":"2025-08-07T10:04:06.000Z","size":40066,"stargazers_count":9,"open_issues_count":17,"forks_count":9,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-08-07T11:44:29.295Z","etag":null,"topics":["ethereum","evm","nitro","nitrolite","state-channels"],"latest_commit_sha":null,"homepage":"https://erc7824.org","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/erc7824.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-01T05:37:16.000Z","updated_at":"2025-08-07T10:03:18.000Z","dependencies_parsed_at":"2025-05-23T12:49:30.467Z","dependency_job_id":"9bb5a3da-0d70-4fc5-b63a-0b286ff1a821","html_url":"https://github.com/erc7824/nitrolite","commit_stats":null,"previous_names":["erc7824/nitrolite"],"tags_count":218,"template":false,"template_full_name":null,"purl":"pkg:github/erc7824/nitrolite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erc7824%2Fnitrolite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erc7824%2Fnitrolite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erc7824%2Fnitrolite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erc7824%2Fnitrolite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erc7824","download_url":"https://codeload.github.com/erc7824/nitrolite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erc7824%2Fnitrolite/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269252616,"owners_count":24385893,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-07T02:00:09.698Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ethereum","evm","nitro","nitrolite","state-channels"],"created_at":"2025-04-08T00:49:18.829Z","updated_at":"2025-08-10T21:03:05.665Z","avatar_url":"https://github.com/erc7824.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nitrolite: State Channel Framework\n\nNitrolite is a lightweight, efficient state channel framework for Ethereum and other EVM-compatible blockchains, enabling off-chain interactions while maintaining on-chain security guarantees.\n\n## Overview\n\nNitrolite is a complete state channel infrastructure consisting of three main components:\n\n1. **Smart Contracts**: On-chain infrastructure for state channel management\n2. **Clearnode**: A broker providing ledger services for the Clearnet protocol\n3. **TypeScript SDK**: Client-side library for building custom state channel applications\n\n### Key Benefits\n\n- **Instant Finality**: Transactions settle immediately between parties\n- **Reduced Gas Costs**: Most interactions happen off-chain, with minimal on-chain footprint\n- **High Throughput**: Support for thousands of transactions per second\n- **Security Guarantees**: Same security as on-chain, with cryptographic proofs\n- **Chain Agnostic**: Works with any EVM-compatible blockchain\n\n## Project Structure\n\nThis repository contains:\n\n- **[`/contract`](/contract)**: Solidity smart contracts for the state channel framework\n- **[`/clearnode`](/clearnode)**: Message broker implementation for the Clearnet protocol\n- **[`/sdk`](/sdk)**: TypeScript SDK for building applications with Nitrolite\n- **[`/docs`](/docs)**: Protocol specifications and documentation\n- **[`/examples`](/examples)**: Sample applications built with Nitrolite\n\n## Protocol\n\nNitrolite implements a state channel protocol that enables secure off-chain communication with minimal on-chain operations. The protocol includes:\n\n- **Channel Creation**: A funding protocol where participants lock assets in the custody contract\n- **Off-Chain Updates**: A mechanism for exchanging and signing state updates off-chain\n- **Channel Closure**: Multiple resolution paths including cooperative close and challenge-response\n- **Checkpointing**: The ability to record valid states on-chain without closing the channel\n- **Reset Capability**: Support for resizing allocations by closing and reopening channels\n\nSee the [protocol specification](/docs/PROTOCOL.md) for complete details.\n\n## Smart Contracts\n\nThe Nitrolite contract system provides:\n\n- **Custody** of ERC-20 tokens for each channel\n- **Mutual close** when participants agree on a final state\n- **Challenge/response** mechanism for unilateral finalization\n- **Checkpointing** for recording valid states without closing\n\n### Deployments\n\nFor the most up-to-date contract addresses on all supported networks, see the [contract deployments directory](/contract/deployments/).\n\nEach network directory contains deployment information with timestamps and contract addresses.\n\n### Interface Structure\n\nThe core interfaces include:\n\n- **IChannel**: Main interface for channel creation, joining, closing, and dispute resolution\n- **IAdjudicator**: Interface for state validation contracts\n- **IDeposit**: Interface for token deposits and withdrawals\n- **IComparable**: Interface for determining the ordering between states\n\nSee the [contract README](/contract/README.md) for detailed contract documentation.\n\n## Clearnode\n\nClearnode is an implementation of a message broker node providing ledger services for the Clearnet protocol. It enables efficient off-chain payment channels with on-chain settlement capabilities.\n\n### Features\n\n- **Multi-Chain Support**: Connect to multiple EVM blockchains (Polygon, Celo, Base)\n- **Off-Chain Payments**: Efficient payment channels for high-throughput transactions\n- **Virtual Applications**: Create multi-participant applications\n- **Message Forwarding**: Bi-directional message routing between application participants\n- **Flexible Database**: Support for both PostgreSQL and SQLite\n- **Prometheus Metrics**: Built-in monitoring and telemetry\n- **Quorum-Based Signatures**: Support for multi-signature schemes with weight-based quorums\n\nSee the [Clearnode Documentation](/clearnode/README.md) for detailed documentation.\n\n## TypeScript SDK\n\nThe SDK provides a simple client interface that allows developers to create and manage channels with their own application logic.\n\n### Installation\n\n```bash\nnpm install @erc7824/nitrolite\n```\n\n### Quick Start\n\n**[Check Quick Start Guide](https://erc7824.org/quick_start)**\n\n\nSee the [SDK README](/sdk/README.md) for detailed SDK documentation.\n\n## Examples\n\nThe repository includes several example applications built with Nitrolite:\n\n### Snake Game\n\nA multiplayer snake game that uses state channels for secure, off-chain gameplay payments:\n\n- **Real-time multiplayer**: WebSocket-based gameplay\n- **State channel integration**: Secure payments and state signing\n- **Fair fund distribution**: Based on game outcome\n\n[Learn more about Snake](/examples/snake)\n\n### Tic Tac Toe\n\nA simple tic-tac-toe game demonstrating the fundamentals of state channels:\n\n- **React frontend**: Simple, clean UI\n- **WebSocket backend**: For game coordination\n- **State channel integration**: For secure payments\n\n[Learn more about Tic Tac Toe](/examples/tictactoe)\n\n## Key Concepts\n\n### State Channels\n\nA state channel is a relationship between participants that allows them to exchange state updates off-chain, with the blockchain serving as the ultimate arbiter in case of disputes.\n\n```\n+---------+                    +---------+\n|         |   Off-chain state  |         |\n| Alice   |  \u003c-------------→   | Bob     |\n|         |      updates       |         |\n+---------+                    +---------+\n     ↑                              ↑\n     |      On-chain resolution     |\n     +------------+  +---------------+\n                  |  |\n             +----+--+----+\n             |            |\n             | Blockchain |\n             |            |\n             +------------+\n```\n\n### Channel Lifecycle\n\n1. **Creation**: Creator constructs channel config, defines initial state with `CHANOPEN` magic number\n2. **Joining**: Participants verify the channel and sign the same funding state\n3. **Active**: Once fully funded, the channel transitions to active state for off-chain operation\n4. **Off-chain Updates**: Participants exchange and sign state updates according to application logic\n5. **Resolution**:\n   - **Cooperative Close**: All parties sign a final state with `CHANCLOSE` magic number\n   - **Challenge-Response**: Participant can post a state on-chain and initiate challenge period\n   - **Checkpoint**: Record valid state on-chain without closing for future dispute resolution\n   - **Reset**: Close and reopen a channel to resize allocations\n\n### Data Structures\n\n- **Channel**: Configuration with participants, adjudicator, challenge period, and nonce\n- **State**: Application data, asset allocations, and signatures\n- **Allocation**: Destination address, token, and amount for each participant\n- **Status**: Channel lifecycle stages (VOID, INITIAL, ACTIVE, DISPUTE, FINAL)\n\n## Quick Start with Docker Compose\n\nGet started quickly with the local development environment using Docker Compose:\n\n```bash\n# Start the environment\ndocker-compose up -d\n\n# This will:\n# 1. Start a local Anvil blockchain on port 8545\n# 2. Deploy the Custody, ERC20, and FlagAdjudicator contracts\n# 3. Seed the database with test tokens information\n# 4. Start the Clearnode service.\n\n# To check the status:\ndocker-compose ps\n\n# To view logs:\ndocker-compose logs -f clearnode\n\n# To stop the environment:\ndocker-compose down\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the SDK\ncd sdk \u0026\u0026 npm run build\n\n# Run tests\ncd contract \u0026\u0026 forge test\ncd sdk \u0026\u0026 npm test\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferc7824%2Fnitrolite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferc7824%2Fnitrolite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferc7824%2Fnitrolite/lists"}