First draft of intro document
This commit is contained in:
commit
864300f10c
133
nitro-integration.md
Normal file
133
nitro-integration.md
Normal file
@ -0,0 +1,133 @@
|
||||
# Laconic Nitro Integration
|
||||
|
||||
Laconic's Nitro functionality is currently a **limited subset** of the full Nitro protocol, focused on basic channel operations with significant constraints.
|
||||
|
||||
## Nitro: State channel framework
|
||||
|
||||
The Nitro protocol is a comprehensive state channel framework that enables secure off-chain token transfers with on-chain settlement guarantees. It creates "state channels" between participants that can update balances and execute application logic without requiring every transaction to be recorded on the blockchain, while maintaining the ability to dispute and resolve conflicts on-chain when necessary.
|
||||
|
||||
## Components
|
||||
|
||||
- Uses [go-nitro](https://github.com/statechannels/go-nitro) library as the underlying protocol implementation
|
||||
- Wraps go-nitro within Cosmos SDK server architecture
|
||||
- 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
|
||||
|
||||
- **Channel opening**: Can create ledger channels and payment channels between two parties
|
||||
- **Channel closing**: Can close channels cooperatively
|
||||
|
||||
### Current use cases
|
||||
|
||||
- **Simple two-party channels** with a validator as counterparty
|
||||
- **Basic state channel experimentation** and testing
|
||||
- **Foundation for future development** of full Nitro protocol support
|
||||
|
||||
### 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
|
||||
|
||||
## What doesn't work yet
|
||||
|
||||
- **Payment (virtual) channels**: Not functional until vouchers are implemented (low-effort addition)
|
||||
- **Query operations**: Not implemented (low-effort)
|
||||
- **Complex outcomes**: Currently only single-asset outcomes supported (low-effort)
|
||||
- **Challenge mechanisms**: Dispute resolution not implemented
|
||||
|
||||
### Known issues and limitations
|
||||
|
||||
#### P2P performance
|
||||
Nitro traffic can overwhelm CometBFT and in some 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 unsuitable for typical user-to-user payment scenarios
|
||||
|
||||
#### Limited protocol support
|
||||
- Only basic channel opening/closing is reliable
|
||||
- No support yet for advanced Nitro features like virtual channels or complex applications
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core components
|
||||
|
||||
- **Nitro server** (`server/nitro/`): Main integration point that instantiates go-nitro Node
|
||||
- **Ethereum integration**: Connects to Ethereum L1 for contract interactions
|
||||
- **Message service**: Routes protocol messages via CometBFT P2P
|
||||
- **Nitrobank module** (`x/nitrobank/`): Cosmos SDK module for state management
|
||||
- Currently just tracks state of opened channels
|
||||
- In future, could be used as
|
||||
|
||||
### 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
|
||||
|
||||
## Configuration
|
||||
|
||||
Required configuration parameters:
|
||||
|
||||
```toml
|
||||
[nitro]
|
||||
enable = true
|
||||
eth-url = "https://ethereum-rpc-endpoint"
|
||||
eth-key = "ethereum-key-name-in-keyring"
|
||||
node-key = "p2p-node-key-name"
|
||||
eth-na-address = "0x..." # Nitro Adjudicator contract
|
||||
eth-vpa-address = "0x..." # Virtual Payment App contract
|
||||
eth-ca-address = "0x..." # Consensus App contract
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Opening a ledger channel
|
||||
|
||||
With a known Ethereum address `0xd4Fa489Eacc52BA59438993f37Be9fcC20090E39` for the counterparty, belonging to target a validator node:
|
||||
|
||||
```bash
|
||||
laconicd nitro open-channel 10eth 0xd4Fa489Eacc52BA59438993f37Be9fcC20090E39 --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"}], ...}}
|
||||
```
|
||||
|
||||
### Opening a payment channel
|
||||
|
||||
After opening a ledger channel as above:
|
||||
|
||||
```bash
|
||||
laconicd nitro open-payment-channel 10eth 0xd4Fa489Eacc52BA59438993f37Be9fcC20090E39 --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"}], ...}}
|
||||
```
|
||||
|
||||
### Querying channel status
|
||||
|
||||
TODO
|
||||
|
||||
## Roadmap
|
||||
|
||||
The architecture provides a foundation for expanding to full Nitro protocol capabilities:
|
||||
|
||||
- **Distributed signature infrastructure** exists but is not integrated
|
||||
- **Payment voucher support** should be straightforward to add
|
||||
- **Query operations** are marked as straightforward additions
|
||||
- **Performance improvements** needed for P2P messaging
|
||||
- **Integrating Nitro state in chain store** will improve reliability and consisten
|
||||
- **Alternative to x/accounts module** needed for account integration
|
||||
|
||||
This implementation represents early-stage integration suitable for development and testing, but not yet production-ready for general payment channel use cases.
|
||||
Loading…
Reference in New Issue
Block a user