go-perun is a Go implementation of the Perun state channel protocols (introduction paper). The perun protocols provide payment and general state channel functionality to all existing blockchains that feature smart contracts. As a blockchain scalability solution, payment and state channels reduce transaction costs and increase the system throughput by executing incremental transactions off-chain. The Perun protocols have been proven cryptographically secure in the UC-framework. They are blockchain-agnostic and only rely on a blockchain's capability to execute smart contracts.
Do not use this software with real funds.
go-perun is still in development. The authors take no responsibility for any loss of digital assets or other damage caused by the use of this software.
Running go-perun requires a working Go distribution (version 1.15 or higher).
# Clone the repository into a directory of your choice
git clone https://github.com/hyperledger-labs/go-perun.git
# Or directly download it with go
# go get -d perun.network/go-perun
cd go-perun
# Run the unit tests
go test ./...You can import go-perun in your project like this:
import "perun.network/go-perun/client"go-perun implements the core state channel protocol in a blockchain-agnostic fashion by following the dependency inversion principle. For this reason, a blockchain backend has to be chosen and blockchain-specific initializations need to be executed at program startup.
The walkthrough tutorial describes how go-perun is used to build a simple micro-payment application on top of Ethereum.
More in-depth documentation can be found here and on go-perun's pkg.go.dev site.
go-perun currently supports all features needed for generalized two-party state channels. The following features are provided:
- Generalized two-party state channels, including app/sub-channels
- Cooperatively settling
- Channel disputes
- Dispute watchtower
- Data persistence
The following features are planned for future releases:
- Virtual two-party channels (direct dispute)
- Virtual two-party channels (indirect dispute)
- Multi-party ledger channels
- Virtual multi-party channels (direct dispute)
- Cross-blockchain virtual channels (indirect dispute)
There are multiple blockchain backends available as part of the current release: Ethereum (backend/ethereum), and a simulated, ideal blockchain backend (backend/sim).
A backend is automatically initialized when its top-level package backend/<name> is imported.
The Ethereum smart contracts can be found in the contracts-eth repository.
Logging and networking capabilities can also be injected by the user.
A default logrus implementation of the log.Logger interface can be set using log/logrus.Set.
The Perun framework relies on a user-injected wire.Bus for inter-peer communication.
go-perun ships with the wire/net.Bus implementation for TCP and Unix sockets.
Data persistence can be enabled to continuously persist new states and signatures. There are currently three persistence backends provided, namely, a test backend for testing purposes, an in-memory key-value persister and a LevelDB backend.
In essence, go-perun provides a state channel network client, akin to ethereum's ethclient package, to interact with a state channels network.
Once the client has been set up, it can be used to propose channels to other network peers, accept channel proposals, send updates on those channels and eventually settle them.
A minimal, illustrative usage is as follows
package main
import (
"context"
"time"
"perun.network/go-perun/channel"
"perun.network/go-perun/client"
"perun.network/go-perun/log"
"perun.network/go-perun/peer"
"perun.network/go-perun/wallet"
"perun.network/go-perun/wire"
// other imports
)
func main() {
// setup blockchain interaction
var funder channel.Funder
var adjudicator channel.Adjudicator
// setup perun network identity
var perunID wire.Address
// setup communication bus
var bus wire.Bus
// setup wallet for channel accounts
var w wallet.Wallet
// create state channel network client
c := client.New(perunID, bus, funder, adjudicator, w)
// choose how to react to incoming channel proposals
var proposalHandler client.ProposalHandler
// choose how to react to incoming channel update requests
var updateHandler client.UpdateHandler
// start incoming request handler
go c.Handle(proposalHandler, updateHandler)
// propose a new channel
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
defer cancel()
ch, err := c.ProposeChannel(ctx, client.NewLedgerChannelProposal(
// details of channel proposal, like peers, app, initial balances, challenge duration...
))
if err != nil { /* handle error */ }
// start watchtower
go func() {
err := ch.Watch()
log.Info("Watcher returned with error ", err)
}()
// send a channel update request to the other channel peer(s)
err = ch.UpdateBy(ctx, func(s *channel.State) error {
// update state s, e.g., moving funds or changing app data
})
if err != nil { /* handle error */ }
// send further updates and finally, settle/close the channel
if err := ch.Settle(ctx); err != nil { /* handle error */ }
}For a full-fledged example, have a look at our CLI Demo perun-eth-demo.
Go mobile wrappers for 
This project has been started at the Chair of Applied Cryptography at Technische Universität Darmstadt, Germany, and is currently developed and maintained by a group of dedicated hackers from PolyCrypt GmbH. We thank the German Federal Ministry of Education and Research (BMBF) for their funding through the StartUpSecure grants program as well as the German Science Foundation (DFG), the Foundation for Polish Science (FNP) and the Ethereum Foundation for their support in the research that preceded this implementation.
Copyright 2021 - See NOTICE file for copyright holders. Use of the source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
Contact us at [email protected].