From 5a08e3c6ce575263d4c8e6d6eb694544feb3ee54 Mon Sep 17 00:00:00 2001 From: Roy Crihfield Date: Sat, 26 Jul 2025 00:56:13 +0800 Subject: [PATCH] Small update - working payment channels --- nitro-integration.md | 154 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 127 insertions(+), 27 deletions(-) diff --git a/nitro-integration.md b/nitro-integration.md index 53941b2..23f5949 100644 --- a/nitro-integration.md +++ b/nitro-integration.md @@ -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.