hyperledger-labs/go-perun — 60 Stars

Topics

Language breakdown

No language data available.

▸ Files click to expand

README

Perun Blockchain-Agnostic State Channels Framework

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.

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.

Getting Started

Running go-perun requires a working Go distribution, see go.mod for the required version.

# 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.

Documentation

In-depth documentation can be found at perun-doc and on go-perun's pkg.go.dev site.

Our walkthrough tutorial describes how go-perun_ is used to build a simple micro-payment application on top of Ethereum.

A bunch of examples can be found at perun-examples.

Features

go-perun currently provides two-party channels with the following features:

Generalized state channels, including app/sub-channels
Dispute watchtower
Data persistence
Virtual payment channels (direct dispute)
Multi-ledger channels

The following features are planned for future releases:

Virtual payment channels (indirect dispute)
Virtual state channels
Multi-party channels
Multi-ledger app/virtual channels

Backends

go-perun supports multiple blockchain backends. A backend is automatically initialized when its top-level package backend/<name> is imported.#### Backend Map

| ID | Backend | Payment Channel Status | Cross-Chain Status | go-perun Version | Repository | | --- | ---------- | ---------------------- | ------------------ | ---------------- | ------------------------------------------------------------------------------------ | | 0 | SimBackend | 🧪 Testing only | 🧪 Testing only | v0.15.0 | Built-in (backend/sim) – represents an ideal blockchain backend for simulation | | 1 | Ethereum | ✅ Supported | ✅ Supported | v0.15.0 | perun-eth-backend | | 2 | Stellar | ✅ Supported | ✅ Supported | v0.15.0 | perun-stellar-backend | | 3 | Nervos | ✅ Supported | 🚧 In development | v0.15.0 | perun-ckb-backend | | 4 | Polkadot | ✅ Supported | 🚧 In development | v0.13.0 | perun-polkadot-backend | | 5 | Dfinity | ✅ Supported | 🚧 In development | v0.13.0 | perun-icp-backend | | 6 | Solana | 🚧 In development | 🚧 In development | v0.13.0 | perun-solana-backend | | - | Cosmos | ✅ Supported | 🟡 Single-chain | v0.7.0 | perun-cosmwasm-backend | | - | Cardano | ✅ Supported | 🟡 Single-chain | v0.10.6 | perun-cardano-backend | | - | Fabric | ✅ Supported | 🟡 Single-chain | v0.10.6 | perun-fabric |

Legend

✅ Supported – stable and available.
🚧 In development – actively worked on, not fully stable.
🟡 Single-chain – supports only local (non-cross-chain) payment/state channels.
🧪 Testing only – simulation backend, no real blockchain.

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.

API Primer

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/watcher" 	"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 wallet wallet.Wallet 	// setup channel watcher 	var watcher watcher.Watcher
// create state channel network client 	c := client.New(perunID, bus, funder, adjudicator, wallet, watcher)
// 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.Update(ctx, func(s *channel.State) { 		// 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 and iOS App development can be found at perun-eth-mobile.

Funding

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

Contact us at info@perun.network.

🔗 More in this category