From d755dc79e2bf08eac862d1423cb7cc7fc52cad33 Mon Sep 17 00:00:00 2001 From: George Knee Date: Thu, 17 Aug 2023 10:45:40 +0100 Subject: [PATCH 1/8] fix broken link --- docs/protocol-tutorial/0070-finalizing-a-channel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/protocol-tutorial/0070-finalizing-a-channel.md b/docs/protocol-tutorial/0070-finalizing-a-channel.md index 4e2f53f38..a47b17613 100644 --- a/docs/protocol-tutorial/0070-finalizing-a-channel.md +++ b/docs/protocol-tutorial/0070-finalizing-a-channel.md @@ -75,7 +75,7 @@ The `checkpoint` method allows anyone with a supported off-chain state to establ ### Call `challenge` again -It is important to understand that a challenge may be "cleared" by another more recent challenge. The channel will be left in challenge mode (so it has not really been 'cleared' in that sense), but some [on chain storage](./understand-adjudicator-status) will be updated, such as the deadline for responding. +It is important to understand that a challenge may be "cleared" by another more recent challenge. The channel will be left in challenge mode (so it has not really been 'cleared' in that sense), but some [on chain storage](./0040-lifecycle-of-a-channel.md#channel-modes) will be updated, such as the deadline for responding. ## Extract info from Adjudicator Events From 750aa4f0310fd2f3d05828b76c65bef8bffe571b Mon Sep 17 00:00:00 2001 From: George Knee Date: Thu, 17 Aug 2023 10:56:51 +0100 Subject: [PATCH 2/8] add GHA for checking links --- .github/workflows/md-link-checker.yml | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 .github/workflows/md-link-checker.yml diff --git a/.github/workflows/md-link-checker.yml b/.github/workflows/md-link-checker.yml new file mode 100644 index 000000000..48d03234f --- /dev/null +++ b/.github/workflows/md-link-checker.yml @@ -0,0 +1,12 @@ +name: Check Links in MD files +on: + push: + branches: [main] + pull_request: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: markdown-link-check + uses: gaurav-nelson/github-action-markdown-link-check@1.0.15 From 13b96c390ccd181e5e576b52d950bcd55fddc1bb Mon Sep 17 00:00:00 2001 From: George Knee Date: Thu, 17 Aug 2023 10:58:45 +0100 Subject: [PATCH 3/8] intentionally break a link to test link checker --- docs/faqs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faqs.md b/docs/faqs.md index 6636c6747..0f3f7d3d2 100644 --- a/docs/faqs.md +++ b/docs/faqs.md @@ -16,7 +16,7 @@ State channels can be programmed such that assets are redistributed according to ## What is Nitro Protocol? -Nitro protocol is a state of the art state channel protocol which is focussed on security, performance and extensibility. It has been developed over several [years of research](./research-papers.md). +Nitro protocol is a state of the art state channel protocol which is focussed on security, performance and extensibility. It has been developed over several [years of research](./research-paperz.md). One of the key features of Nitro are [_virtual_ channels](./protocol-tutorial/0060-funding-a-channel.md#fund-virtually), where peers can setup a direct connection with each other entirely off-chain. From 851e2b62dfdc35124f5017b51b326a70cb44bdc8 Mon Sep 17 00:00:00 2001 From: George Knee Date: Thu, 17 Aug 2023 11:02:40 +0100 Subject: [PATCH 4/8] remove link checker mkdocs has one built in. Not sure why it didn't catch d755dc7 --- .github/workflows/md-link-checker.yml | 12 ------------ docs/faqs.md | 2 +- 2 files changed, 1 insertion(+), 13 deletions(-) delete mode 100644 .github/workflows/md-link-checker.yml diff --git a/.github/workflows/md-link-checker.yml b/.github/workflows/md-link-checker.yml deleted file mode 100644 index 48d03234f..000000000 --- a/.github/workflows/md-link-checker.yml +++ /dev/null @@ -1,12 +0,0 @@ -name: Check Links in MD files -on: - push: - branches: [main] - pull_request: - -jobs: - build: - runs-on: ubuntu-latest - steps: - - name: markdown-link-check - uses: gaurav-nelson/github-action-markdown-link-check@1.0.15 diff --git a/docs/faqs.md b/docs/faqs.md index 0f3f7d3d2..6636c6747 100644 --- a/docs/faqs.md +++ b/docs/faqs.md @@ -16,7 +16,7 @@ State channels can be programmed such that assets are redistributed according to ## What is Nitro Protocol? -Nitro protocol is a state of the art state channel protocol which is focussed on security, performance and extensibility. It has been developed over several [years of research](./research-paperz.md). +Nitro protocol is a state of the art state channel protocol which is focussed on security, performance and extensibility. It has been developed over several [years of research](./research-papers.md). One of the key features of Nitro are [_virtual_ channels](./protocol-tutorial/0060-funding-a-channel.md#fund-virtually), where peers can setup a direct connection with each other entirely off-chain. From 098e35f935a795eeddbbf4ef4499aa4bd7ca381a Mon Sep 17 00:00:00 2001 From: George Knee Date: Thu, 17 Aug 2023 13:11:00 +0100 Subject: [PATCH 5/8] replace TODOs with on chain function signatures --- .../0070-finalizing-a-channel.md | 33 ++++++++++++------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/protocol-tutorial/0070-finalizing-a-channel.md b/docs/protocol-tutorial/0070-finalizing-a-channel.md index a47b17613..9973b0859 100644 --- a/docs/protocol-tutorial/0070-finalizing-a-channel.md +++ b/docs/protocol-tutorial/0070-finalizing-a-channel.md @@ -22,12 +22,12 @@ In the case where assets were deposited against the channel on chain (the case o The conclude method allows anyone with sufficient off-chain state to immediately finalize an outcome for a channel without having to wait for a challenge to expire (more on that later). -The off-chain state(s) is submitted (in an optimized format), and once relevant checks have passed, an expired challenge is stored against the `channelId`. (This is an implementation detail -- the important point is that the chain shows that the channel has been finalized.) - -```typescript -TODO example +```solidity + function conclude(FixedPart memory fixedPart, SignedVariablePart memory candidate) external ``` +The off-chain state(s) is submitted (in an optimized format), and once relevant checks have passed, an expired challenge is stored against the `channelId`. (This is an implementation detail -- the important point is that the chain shows that the channel has been finalized.) + ## Sad path When cooperation breaks down, it is possible to finalize a state channel without requiring on-demand cooperation of all `n` participants. This is the so-called 'sad' path to finalizing a channel, and it requires a supported (but not necessarily `isFinal`) state(s) being submitted to the chain. @@ -38,19 +38,21 @@ The required data for this method consists of a single state, along with `n` sig This delay allows the challenge to be cleared by a timely and well-formed [respond](./clear-a-challenge#call-respond) or [checkpoint](./clear-a-challenge#call-checkpoint) transaction. We'll get to those shortly. If no such transaction is forthcoming, the challenge will time out, allowing the `outcome` registered to be finalized. A finalized outcome can then be used to extract funds from the channel (more on that below, too). -```typescript -TODO example -``` - !!! tip The `challengeDuration` is a [fixed parameter](./execute-state-transitions#construct-a-state-with-the-correct-format) expressed in seconds, that is set when a channel is proposed. It should be set to a value low enough that participants may close a channel in a reasonable amount of time in the case that a counterparty becomes unresponsive; but high enough that malicious challenges can be detected and responded to without placing unreasonable liveness requirements on responders. A `challengeDuration` of 1 day is a reasonable starting point, but the "right" value will likely depend on your application. ### Call `challenge` -```typescript -TODO example -``` +````solidity + function challenge( + FixedPart memory fixedPart, + SignedVariablePart[] memory proof, + SignedVariablePart memory candidate, + Signature memory challengerSig + ) external + ``` + !!!note @@ -73,6 +75,14 @@ A challenge being registered does _not_ mean that the channel will inexorably fi The `checkpoint` method allows anyone with a supported off-chain state to establish a new and higher `turnNumRecord` on chain, and leave the resulting channel in the "Open" mode. It can be used to clear a challenge. +```solidity + function checkpoint( + FixedPart memory fixedPart, + SignedVariablePart[] memory proof, + SignedVariablePart memory candidate + ) external +``` + ### Call `challenge` again It is important to understand that a challenge may be "cleared" by another more recent challenge. The channel will be left in challenge mode (so it has not really been 'cleared' in that sense), but some [on chain storage](./0040-lifecycle-of-a-channel.md#channel-modes) will be updated, such as the deadline for responding. @@ -80,3 +90,4 @@ It is important to understand that a challenge may be "cleared" by another more ## Extract info from Adjudicator Events You may have noticed that to respond, the challenge state itself must be (re)submitted to the chain. To save gas, information is only stored on chain in a hashed format. Clients should, therefore, cache information emitted in Events emitted by the adjudicator, in order to be able to respond to challenges. +```` From cf08900fbd18dd13ffe9ff938c2344eb6754e58f Mon Sep 17 00:00:00 2001 From: George Knee Date: Thu, 17 Aug 2023 13:28:17 +0100 Subject: [PATCH 6/8] tidy up --- docs/protocol-tutorial/0070-finalizing-a-channel.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/protocol-tutorial/0070-finalizing-a-channel.md b/docs/protocol-tutorial/0070-finalizing-a-channel.md index 9973b0859..86c723346 100644 --- a/docs/protocol-tutorial/0070-finalizing-a-channel.md +++ b/docs/protocol-tutorial/0070-finalizing-a-channel.md @@ -44,15 +44,14 @@ This delay allows the challenge to be cleared by a timely and well-formed [respo ### Call `challenge` -````solidity +```solidity function challenge( FixedPart memory fixedPart, SignedVariablePart[] memory proof, SignedVariablePart memory candidate, Signature memory challengerSig ) external - ``` - +``` !!!note @@ -90,4 +89,3 @@ It is important to understand that a challenge may be "cleared" by another more ## Extract info from Adjudicator Events You may have noticed that to respond, the challenge state itself must be (re)submitted to the chain. To save gas, information is only stored on chain in a hashed format. Clients should, therefore, cache information emitted in Events emitted by the adjudicator, in order to be able to respond to challenges. -```` From a99b068d9d128d0c83087d4e3313620024e03420 Mon Sep 17 00:00:00 2001 From: George Knee Date: Thu, 17 Aug 2023 13:39:47 +0100 Subject: [PATCH 7/8] tweak notes about docs website --- contributing.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/contributing.md b/contributing.md index 5cc85830d..64b2da5ea 100644 --- a/contributing.md +++ b/contributing.md @@ -79,6 +79,20 @@ mkdocs serve and navigate to http://localhost:8000 . +### Using Docker + +``` +docker pull squidfunk/mkdocs-material +``` + +and then: + +``` +docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material serve +``` + +(specifying `serve` overrides the default command which happens to conflict with our use of `strict` mode). + ## Viewing Godocs website Run From 4da26709e257c98ad02d34fff841d6f39cae6fff Mon Sep 17 00:00:00 2001 From: George Knee Date: Thu, 17 Aug 2023 15:15:25 +0100 Subject: [PATCH 8/8] modify advice --- contributing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributing.md b/contributing.md index 64b2da5ea..f1b724484 100644 --- a/contributing.md +++ b/contributing.md @@ -88,10 +88,10 @@ docker pull squidfunk/mkdocs-material and then: ``` -docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material serve +docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material ``` -(specifying `serve` overrides the default command which happens to conflict with our use of `strict` mode). +You will need to diable `strict` mode to have this work https://github.com/mkdocs/mkdocs/issues/2108. ## Viewing Godocs website