cerc-io/laconic-nitro-docs
10
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Small update - working payment channels

Browse Source
This commit is contained in:
Roy Crihfield 2025-07-26 00:56:13 +08:00
parent 864300f10c
commit 5a08e3c6ce
1 changed files with 127 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
nitro-integration.md
View File

@ -1,10 +1,19 @@
# Laconic Nitro Integration
# 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.
Laconic has experimental support for making state channel payments using the [Nitro
protocol](https://docs.statechannels.org/), allowing low-latency, minimal-cost transfer of
Ethereum-native cryptoassets.
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.
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
@ -19,12 +28,13 @@ The Nitro protocol is a comprehensive state channel framework that enables secur
### Basic channel operations
- **Channel opening**: Can create ledger channels and payment channels between two parties
- **Channel closing**: Can close channels cooperatively
- **Create channels**: Can create ledger (on-chain) and virtual (off-chain) channels between two parties
- **Close chanels**: Can close channels cooperatively
- **Send payments**: Send payments over virtual channels
### Current use cases
- **Simple two-party channels** with a validator as counterparty
- **Simple two-party payment channels** with a validator as counterparty
- **Basic state channel experimentation** and testing
- **Foundation for future development** of full Nitro protocol support
@ -35,26 +45,23 @@ The Nitro protocol is a comprehensive state channel framework that enables secur
## 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)
- **Complex outcomes**: Currently only single-asset outcomes supported
- **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.
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 unsuitable for typical user-to-user payment scenarios
- Makes it currently 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
- Challenge and counter-challenge flows are not supported, could be resolved using `go-nitro` directly
## Architecture
@ -65,7 +72,7 @@ implementation level.
- **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
- In future, will act as main data store for Nitro state machine, leveraging state syncing and WAL
### Message Flow
@ -82,8 +89,8 @@ Required configuration parameters:
[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
@ -91,7 +98,7 @@ eth-ca-address = "0x..." # Consensus App contract
## Examples
### Opening a ledger channel
### Open a ledger channel
With a known Ethereum address `0xd4Fa489Eacc52BA59438993f37Be9fcC20090E39` for the counterparty, belonging to target a validator node:
@ -103,7 +110,7 @@ laconicd q tx 6BF863D28E9334B7CC74F283791FBB29C636970E96B48E36DA0ECE4AF1B8DF77 -
# -> {... "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
### Open a payment channel
After opening a ledger channel as above:
@ -115,19 +122,112 @@ laconicd q tx FE3CF32E49C2206EF730DB8D0804BFFD9B80A3CA458A728632B71AC1D36BC780 -
# -> {... "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
### Query channel information
TODO
The Nitro integration provides several query commands to inspect channel states and node information:
#### Get specific channel information
Query details about a specific ledger or payment channel:
```bash
# Get ledger channel information
laconicd nitro get-channel 0x6267f99810630ea2237a48be87e1892045d0cc2d114034935f94eea2327ffef1 --ledger
# -> {
# "ID": "0x6267f99810630ea2237a48be87e1892045d0cc2d114034935f94eea2327ffef1",
# "Status": "Open",
# "Balance": {
# "AssetAddress": "0x0000000000000000000000000000000000000000",
# "Me": "10000000000000000000",
# "Them": "0"
# },
# "ChannelMode": "Open"
# }
# Get payment channel information
laconicd nitro get-channel 0x9172ce4c708a33ed13113c209f8d68d3d6974a780f1957dda4ca7d183cb1fa1a --payment
# -> {
# "ID": "0x9172ce4c708a33ed13113c209f8d68d3d6974a780f1957dda4ca7d183cb1fa1a",
# "Status": "Open",
# "Balance": {...},
# "Route": [...]
# }
```
#### List all channels
List all ledger channels:
```bash
laconicd nitro list-channels
# -> [
# {
# "ID": "0x6267f99810630ea2237a48be87e1892045d0cc2d114034935f94eea2327ffef1",
# "Status": "Open",
# "Balance": {...}
# },
# ...
# ]
```
#### List payment channels by ledger
Get all payment channels associated with a specific ledger channel:
```bash
laconicd nitro list-payment-channels 0x6267f99810630ea2237a48be87e1892045d0cc2d114034935f94eea2327ffef1
# -> [
# {
# "ID": "0x9172ce4c708a33ed13113c209f8d68d3d6974a780f1957dda4ca7d183cb1fa1a",
# "Status": "Open",
# "Route": [...],
# "Balance": {...}
# }
# ]
```
#### Local-only queries
All channel query commands support a `--local` flag for offline queries that don't require
connecting to a remote node:
```bash
# Query local data only (no P2P connection setup)
laconicd nitro get-channel 0x6267... --ledger --local
laconicd nitro list-channels --local
laconicd nitro list-payment-channels 0x6267... --local
```
This is useful when:
- P2P connectivity is unavailable
- You only need locally cached channel data
- You want faster query performance without network overhead
### Get node identity
Retrieve the node's identity information:
```bash
# Get principal ID (default)
laconicd nitro identity
# -> 0xD9995BAE12FEe327256FFec1e3184d492bD94C31
# Get participant address explicitly
laconicd nitro identity --participant
# -> 0xD9995BAE12FEe327256FFec1e3184d492bD94C31
# Get network address
laconicd nitro identity --network
# -> 0x1234567890abcdef1234567890abcdef12345678
```
## Roadmap
The architecture provides a foundation for expanding to full Nitro protocol capabilities:
While incomplete, this gives 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
- **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 implementation represents early-stage integration suitable for development and testing, but not yet production-ready for general payment channel use cases.
This early-stage integration is ready for development and testing, but more robust features are
needed to handle general use cases.