perun-network / perun-polkadot-pallet

Perun channels on Polkadot.

Perun Polkadot Pallet

Perun Polkadot Pallet provides go-perun state channels for all Substrate compatible blockchains.
Using it in your blockchain means to include it just like any other Substrate Pallet.

Repo Structure

• src/
  • lib.rs pallet logic
  • types.rs type definitions
• tests/
  • common/
    • mock.rs test configuration
    • utils.rs test helpers
  • unit.rs pallet unit tests
  • function unit tests
• Cargo.toml module info and dependencies

Protocol

A channel is opened by depositing funds for it into the contract by calling Deposit. The participants of the channel can then do as many off-chain channel updates as they want. When all participants come to the conclusion that the channel should be closed, they set the final flag on the channel state, and call ConcludeFinal. All of them can then withdraw the outcome by calling Withdraw.

Dispute. If the participants do not arrive at a final channel state off-chain, they need to resolve a dispute on-chain. This allows any participant to enforce the last valid state, i.e., the mutually-signed state with the highest version number. A dispute is initiated by calling Dispute with the latest available state. A registered state can be refuted within a specified challenge period by calling Dispute with a newer state. After the challenge period, the dispute can be concluded by calling Conclude and the funds can be withdrawn.

On-chain progression. This is an optional phase for channels with an app. It takes place after the dispute registration and allows to update the channel state without full consenus by calling the function Progress.

State diagram

Tests

The tests require at least rust version 1.52.0 and can be run with:

cargo test

or in docker:

# Run this each time you change something.
docker build -t perun .
docker run --rm perun

Benchmarking

The benchmarks use cryptographic primitives which are only available in a Substrate node.
A node is provided by the Polkadot Node repo of which this repo is a sub-repo.
Have a look there for instructions on how to run the benchmarks.

Documentation

The in-code documentation can be opened with:

cargo doc --no-deps --open --package pallet-perun

Funding

The development of this project is supported by the Web3 Foundation through the Open Grants Program.
The development of the go-perun library is supported by the German Ministry of Education and Science (BMBF) through a Startup Secure grant.

Security Disclaimer

This software is still under development. The authors take no responsibility for any loss of digital assets or other damage caused by the use of it.

Copyright

Copyright 2022 PolyCrypt GmbH.
Use of the source code is governed by the Apache 2.0 license that can be found in the LICENSE file.

perun-polkadot-pallet's Issues

Unchecked Markdown linkes

Remove the markdown-link-check-disable from the README once the node repo is public.

Add MaxNumParts

The number of participants, and therefore the number of off-chain signatures is currently not limited.
The implementer should also check for other cases of arbitrary long inputs.

To get some deterministic bench-marking results, all inputs should have defined maximum lengths.

Distinct types for time Duration & Point

Time durations and time points currently both use Seconds which is not easy to understand.
Either add two different types or at least alias them.

Recover funds after failed funding

Currently, the Pallet does not allow to recover funds from an unfunded channel. A dispute conclusion will just fail in this case.

perun-polkadot-pallet/src/lib.rs

Line 466 in b5a1897

ensure!(sum_deposit >= sum_outcome, Error::<T>::InsufficientDeposits);

We need to revise the Pallet so that we payout the initial deposits in case of an underfunded channel.

Version in Event

The version is a small object. Shouldn't be a problem to persist it.

Originally posted by @matthiasgeihs in perun-network/perun-polkadot-backend#3 (comment)

Transactional conclusion

Currently, the conclude functionality has two writes:

1. Set the outcome.
2. Conclude the registered state.

Problem: There is a risk that the first transaction goes through, while the second fails. In this case we might end up in an inconsistent state.

We need to investigate further whether the current solution is problematic and if so, how to resolve the situation. Maybe using the transaction decorator might be a solution, as pointed out here.

Store hash of state instead of full state

Currently, we store the full state on-chain. However, as an optimization we could only store the hash of the state and provide the state always in the calldata. Then we simply check whether the hash of the provided state matches the hash in the state registry. Thereby we save on-chain storage.

Think about disputing unfunded channels

It is currently possible to dispute channels that were never funded. This could be used to inflate the on-chain state.
Im not sure if it is really a problem but it seems weird since the on-chian state should be minimal.

Add CodeCov

Add CodeCov to the CI so that it shows up here: https://app.codecov.io/gh/perun-network/perun-polkadot-pallet.
Seemed to work in the past.

Remove "open issues" from Readme and create corresponding Issue items