diff --git a/nitro-integration.md b/nitro-integration.md index 23f5949..304a259 100644 --- a/nitro-integration.md +++ b/nitro-integration.md @@ -22,8 +22,6 @@ necessary. - Routes P2P messaging through CometBFT instead of libp2p - Integrates with Ethereum L1 for on-chain adjudication -(TODO: architecture diagram here) - ## What works ### Basic channel operations @@ -40,31 +38,54 @@ necessary. ### Current limitations -- **Requires persistent counterparty connection**: Both parties must maintain active connections during operations -- **Validator-only counterparty**: In practice, this means channels only work with validator nodes as the counterparty +- **Requires persistent counterparty connection**: Both parties must maintain active connections + during operations, limiting usage to scenarios with reliable, long-lived connections. + - In practice, this means channels currently only work with validator nodes as the counterparty. +- **Nitro traffic** can become heavy and in extreme cases disrupt consensus. This is mitigated + effectively with rate limiting, and there is much room for optimization at the design and + implementation level. ## What doesn't work yet -- **Complex outcomes**: Currently only single-asset outcomes supported -- **Challenge mechanisms**: Dispute resolution not implemented - -### Known issues and limitations - -#### P2P performance -Nitro traffic can become heavy and in extreme cases disrupt consensus. This is mitigated effectively -with rate limiting, and there is much room for optimization at the design and implementation level. - -#### Connection requirements -- Both parties must maintain persistent connections -- Limits practical usage to scenarios with reliable, long-lived connections -- Makes it currently unsuitable for typical user-to-user payment scenarios - -#### Limited protocol support -- No support yet for advanced Nitro features like virtual channels or complex applications -- Challenge and counter-challenge flows are not supported, could be resolved using `go-nitro` directly +- **Complex outcomes**: Currently only single-asset outcomes are supported +- **Challenge mechanisms**: Dispute resolution is not yet implemented +- **ERC721, ERC1155, and qualified assets** and custom applications aren't yet supported ## Architecture +```mermaid +graph LR + %% Subgraph for the whole pipeline + subgraph Pipeline [ ] + direction LR + User[User] + + subgraph Laconicd [laconicd] + NitroSM["Nitro
state machine"] + end + + subgraph L1 ["ETH L1"] + NitroContracts[Nitro contracts] + end + end + + %% Connections + User -->|Transactions| Laconicd + Laconicd -->|Nitro
events| L1 + L1 -->|Nitro
updates| Laconicd + + %% Styling + classDef userNode fill:#e8f4fd,stroke:#1976d2,stroke-width:2px; + classDef l1Node fill:#e8f5e8,stroke:#388e3c,stroke-width:2px; + classDef stateNode fill:#fce4ec,stroke:#c2185b,stroke-width:2px; + classDef pipelineBox fill:#ffffff,stroke:#9e9e9e,stroke-width:2px,stroke-dasharray: 3 3; + + class User userNode; + class L1,NitroContracts l1Node; + class Laconicd,NitroSM stateNode; + class Pipeline pipelineBox; +``` + ### Core components - **Nitro server** (`server/nitro/`): Main integration point that instantiates go-nitro Node @@ -74,18 +95,39 @@ with rate limiting, and there is much room for optimization at the design and im - Currently just tracks state of opened channels - In future, will act as main data store for Nitro state machine, leveraging state syncing and WAL -### Message Flow +### Message flow -1. Client creates `MsgOpenChannel` transaction -2. go-nitro Node handles channel opening protocol -3. Protocol messages exchanged via CometBFT -4. Lifecycle events published to chain +Currently, operations proceed by first executing a Nitro operation, and then publishing chain lifecycle events. +For example, opening a Nitro ledger channel involves the following steps: + +1. `laconicd` parses and performs basic validation of the arguments. +1. A P2P connection is opened between our client and the target node (over CometBFT). +1. The request is passed to the `go-nitro` engine, which creates an *objective* object to initiate + the state transition. + 1. The two nodes exchange messages to negotiate the initial channel state. + 1. If both sides approve and sign the initial channel state, the channel is created. +1. A `MsgOpenChannel` transaction is published to the chain to reflect the update. + +Plans are to further integrate the Nitro engine and chain state, such that Nitro operations will +execute as part of a chain transaction to provide atomicity and better leverage the Cosmos-SDK +architecture. + +## Roadmap + +While incomplete, this gives a foundation for expanding to full Nitro protocol capabilities: + +- **Distributed signature infrastructure** exists but is not integrated +- **Integrating Nitro state** in consensus-managed storage will improve consistency and reliability +- **Performance improvements** in P2P messaging and state management will resolve consensus issues + +This integration is early-stage, but under active development. ## Configuration Required configuration parameters: ```toml +# in /config/app.toml [nitro] enable = true eth-url = "https://ethereum-rpc-endpoint" @@ -100,14 +142,14 @@ eth-ca-address = "0x..." # Consensus App contract ### Open a ledger channel -With a known Ethereum address `0xd4Fa489Eacc52BA59438993f37Be9fcC20090E39` for the counterparty, belonging to target a validator node: +With a known Ethereum address `0xd4Fa489Eacc52BA59438993f37Be9fcC20090E39` for the counterparty, belonging to a target validator node: ```bash -laconicd nitro open-channel 10eth 0xd4Fa489Eacc52BA59438993f37Be9fcC20090E39 --output json +laconicd nitro open-channel 0xd4Fa489Eacc52BA59438993f37Be9fcC20090E39 10eth --output json # -> {"height":"0","txhash":"6BF863D28E9334B7CC74F283791FBB29C636970E96B48E36DA0ECE4AF1B8DF77", ...} laconicd q tx 6BF863D28E9334B7CC74F283791FBB29C636970E96B48E36DA0ECE4AF1B8DF77 --output json -# -> {... "body":{"messages":[{"@type":"/cerc.nitrobank.v1.MsgOpenChannel","from_address":"laconic128czkp8j8azu3vvzxy0y2wg706jjdkrnlec6ek","funds":[{"denom":"eth","amount":"10"}],"nitro_address":"0xD9995BAE12FEe327256FFec1e3184d492bD94C31","counterparty":"0xd4Fa489Eacc52BA59438993f37Be9fcC20090E39","channel_id":"0x6267f99810630ea2237a48be87e1892045d0cc2d114034935f94eea2327ffef1"}], ...}} +# -> {..."body":{"messages":[{"@type":"/cerc.nitrobank.v1.MsgOpenChannel","from_address":"laconic128czkp8j8azu3vvzxy0y2wg706jjdkrnlec6ek","funds":[{"denom":"eth","amount":"10"}],"nitro_address":"0xD9995BAE12FEe327256FFec1e3184d492bD94C31","counterparty":"0xd4Fa489Eacc52BA59438993f37Be9fcC20090E39","channel_id":"0x6267f99810630ea2237a48be87e1892045d0cc2d114034935f94eea2327ffef1"}], ...}} ``` ### Open a payment channel @@ -115,11 +157,21 @@ laconicd q tx 6BF863D28E9334B7CC74F283791FBB29C636970E96B48E36DA0ECE4AF1B8DF77 - After opening a ledger channel as above: ```bash -laconicd nitro open-payment-channel 10eth 0xd4Fa489Eacc52BA59438993f37Be9fcC20090E39 --output json +laconicd nitro open-payment-channel 0xd4Fa489Eacc52BA59438993f37Be9fcC20090E39 10eth --output json # -> {"height":"0","txhash":"FE3CF32E49C2206EF730DB8D0804BFFD9B80A3CA458A728632B71AC1D36BC780", ...} laconicd q tx FE3CF32E49C2206EF730DB8D0804BFFD9B80A3CA458A728632B71AC1D36BC780 --output json -# -> {... "body":{"messages":[{"@type":"/cerc.nitrobank.v1.MsgCreatePaymentChannel","from_address":"laconic128czkp8j8azu3vvzxy0y2wg706jjdkrnlec6ek","intermediaries":[],"counterparty":"0xd4Fa489Eacc52BA59438993f37Be9fcC20090E39","challenge_duration":0,"funds":[{"denom":"eth","amount":"10"}],"channel_id":"0x9172ce4c708a33ed13113c209f8d68d3d6974a780f1957dda4ca7d183cb1fa1a"}], ...}} +# -> {..."body":{"messages":[{"@type":"/cerc.nitrobank.v1.MsgCreatePaymentChannel","from_address":"laconic128czkp8j8azu3vvzxy0y2wg706jjdkrnlec6ek","intermediaries":[],"counterparty":"0xd4Fa489Eacc52BA59438993f37Be9fcC20090E39","challenge_duration":0,"funds":[{"denom":"eth","amount":"10"}],"channel_id":"0x9172ce4c708a33ed13113c209f8d68d3d6974a780f1957dda4ca7d183cb1fa1a"}], ...}} +``` + +### Make a payment + +Send a payment over an existing virtual channel: + +```bash +# Make a payment of 5 ETH over virtual channel +laconicd nitro pay 0x9172ce4c708a33ed13113c209f8d68d3d6974a780f1957dda4ca7d183cb1fa1a 5eth +# -> Payment of 5eth sent successfully ``` ### Query channel information @@ -220,14 +272,3 @@ laconicd nitro identity --participant laconicd nitro identity --network # -> 0x1234567890abcdef1234567890abcdef12345678 ``` - -## Roadmap - -While incomplete, this gives a foundation for expanding to full Nitro protocol capabilities: - -- **Distributed signature infrastructure** exists but is not integrated -- **Integrating Nitro state** in consensus-managed storage will improve consistency and reliability -- **Performance improvements** in P2P messaging and state management will resolve consensus issues - -This early-stage integration is ready for development and testing, but more robust features are -needed to handle general use cases.