CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.12.0] Leda - 2024-11-19 💥

Flexibility in funding for payment channels and basic Layer-2 security.

Added 💥

• Egoistic funding allows users to wait for their peers to fund before they fund themselves. This change has to be adopted by the Perun backends to be usable (in case of Ethereum): #397

• Wire authentication for Layer2 communication between Perun clients, using TLS: #402 💥

• Support for Stellar backend in README: #408

Changed

• Update go to 1.22: #406

Legend

• 💥 This is a breaking change, e.g., it changes the external API.

0.11.0 Kiviuq - 2024-02-21 💥

Exposure of protobuf converters & SignedState, abstraction of tests and bug fixes.

Added

• Add Fabric to backend list in README: #377
• Create new type TransparentChannel to expose SignedState: #389
• Update backend compatibility list in README: #392
• Add MAINTAINERS.md file, Update NOTICE: #394

Fixed

• Fix sub-channel test: #359
• Fix Multi-Adjudicator Subscription: #366
• Use correct identity for client tests: #376
• Fix link to white paper in README: #379
• Fix linter copyright year checking in CI: #389
• Fix failing unit tests: #399

Changed 💥

• Abstract multiledger test, making it usable by backends: #355
• Abstract fund recovery test, making it usable by backends: #370
• Abstract virtual channel test, making it usable by backends: #375
• Expose protobuf converters: #384 #393
• Use absolute module path in wire.proto: #383
• Create AppID Type to generalize app identifiers: #378 💥

0.10.0 Janus - 2022-05-25 ⚠️

Multi-ledger payment channels.

Added

• Multi-ledger payment channels: #337
• App channel test: #339

Changed

• Revise dispute test: #340
• Enable require in client tests: #341

Fixed

• Satisfy linter warnings: #342

Removed

• Remove go-ethereum dependency: #338

0.9.1 Io Pioneer - 2022-04-14 ⚠️

Moved Ethereum backend to separate repository.

Added

• CloneAddresses helper: #331.
• Wire hybrid bus: #327.

Removed

• Moved Ethereum backend to separate repository: #355.

0.9.0 Io - 2022-02-22 ⚠️

Injectable wire encoding and a protobuf wire encoder.

Added

• ✨ Injectable wire encoding #233: The encoding used for messages that are sent across the network is now injectable.
  • Add binary marshalling: #272, #284, #298.
  • Add serializer interface: #297, #325.
  • Change the mechanism for generating ProposalID: #300, #307.
  • Rename message types #305.
  • Extend and refactor message serialization tests: #316, #317.
• ✨ Protobuf wire encoder #311: A wire encoder based on protobuf has been added #318.
• Minor additions: Introduce Asset.Equal #279, export proposer index #313.

Changed

• 💥 Rename Address.Equals to Address.Equal #264.
• 💥 Revise Channel.Update and Channel.ForceUpdate: #289, #291, #306.
• 🚚 pkg/io migration: #256, #271, #285, #287.
• 📝 Update README to include references to existing backends #314.
• 🚸 Minor usability improvements: #268, #278, #315.
• 👷 CI updates: #260, #274, #276, #277.
• ⬆️ Use LatestSigner in Ethereum contract backend and don't set GasLimit by default, so that EIP1559 TXs are sent #322.

Fixed

• 🐛 Fix a bug causing Channel.Watch to not work correctly for sub-channels and virtual channels #251.
• 🐛 Fix bugs causing ContractBackend.confirmNTimes to block indefintely or fail in some rare cases: #254, #309.
• ✅ Improve test stability: #310, #319.

Security

• 🔒 It is now checked that assets are not changed during a state update, which could otherwise cause a channel to become unfunded #304.

0.8.0 Hyperion - 2021-11-08 ⚠️

Reorg-resistance for the Ethereum backend and support for external Watchtowers.

Added

• ✨ Ethereum backend: Reorg resistance #19: The Ethereum backend now lets the user specify after how many blocks a transaction or an event should be considered confirmed.
• ✨ Watcher interface #172: The watcher logic is now injectable. The adjudicator takes a watcher instance as a setup parameter. This enables using remote watcher services. A local watcher implementation is provided.

Changed

• ⬆️ Update go to v1.17 and go-ethereum to v1.10.12.
• ✅ Extend support for additional blockchain backends by revising the generic tests (e.g., #225, #227, #228).
• 🚸 Improve usability (e.g., #124, #144, #196, #204, #240).

Fixed

• 🐛 Improve stability (e.g., #129, #134, #148, #191, #207, #218).

0.7.0 Ganymede - 2021-07-09 ⚠️

Virtual channels. And some other additions.

Added ✨

• Virtual Channels (#83, #114, #119, #123): Go-perun now supports virtual channels. A virtual channel is a channel that is funded and settled completely off-chain and therefore does not incur any on-chain transaction fees.
• Generic event subscription (#36, #86, #89, #94): In preparation for implementing a reorg-resistant event subscription, we implemented a generic event subscription that can be used across the whole library.
• Tutorial announcement (c8cff7cb): We now have a developer tutorial at http://tutorial.perun.network.
• Named errors (429a8934, #10, #11, #26, #34, #80): Specific error types help the library user to identify the cause of an error.
• Register asset at runtime #124: It is now possible to add assets to the Eth funder at runtime.
• Gatherer.OnFail (e3729a6a), Test wallet (12c78d33), GitHub CI (#3), ConcurrentT.WaitCtx (#112), Eth sim backend auto mining (#104)

Changed 🚧

• 💥 Asset holder validation (#111): Asset holder validation does no longer include adjudicator validation.
• Current state in HandleUpdate #33: The update handler now receives the current channel state as a parameter.
• Funder usability #74: Streamlined Eth funder setup.
• 2021 updates (2212847d), Update generate script (3f81e47c), Update links to HLL (#6), Update security disclaimer (#14, #51), Delete gitlab templates (#24), Dependency update (#30), Document parameters of NewLedgerChannelProposal (#43), CI speed-up (#44), Refactor Eth channel errors (#88), Log message type (#96)

Fixed 🐛

• Cache first channel update (#4, #129): Fixes a bug where a client receives channel messages before completing the channel setup.

• Subchannel off-chain settlement #59: Sub-channels had to be disputed on-chain before they could be settled. Sub-channels can now be collaboratively settled off-chain.

• ERC20 depositor nonce mismatch #134: Fixes an issue where the ERC20 depositor sometimes was not incrementing the transaction nonce correctly.

• Unitialized funder variable (af207adb), EndpointRegistry retry and timeout (28e535bb), Watcher return (cf9279c9), Thread-safe test wallet #17, Withdraw variable capture #50, NewRandomLedgerChannelProposal consistency #55, Enable logging per default in package client #66, Stabilize BlockTimeout test #90, Fix state hash test #120, Ensure custom error progagation #126

Security 🔒

• Ensure correct params ID after deserialization #60: Parameter deserialization did not assert that the encoded channel ID is correct. This is now fixed.
• Signature verification for sub-channel funding and settlement #61: Sub-channel funding and settlement requires an automated update in the parent channel. The signatures on that automated update were not correctly verified. This is now fixed.

0.6.0 Fenrir - 2020-12-18 ⚠️

Support for on-chain progression of app channels.

Added

• On-chain progression: The channel watcher is now interactive and informs the client when a channel has been registered on-chain. If the channel has a defined app logic with a valid state transition logic, clients can individually progress the app state on-chain according to the defined state transition logic by calling ProgressBy on the channel object.
• Settle with sub-channel disputes: Ledger channels can now be settled with funds locked in disputed sub-channels if the corresponding sub-channels have been registered and the disputes have been resolved on-chain.

Changed

• The channel watcher logic changed. The channel watcher now takes as input an event handler which gets notified about on-chain channel events. Before, the watcher automatically settled a channel in case of a dispute. Now, the watcher will automatically detect if an old state has been registered, refute with the most recent one, and notify the user. If the channel has a defined application logic, the user can further progress the channel on-chain. It is within the responsibility of the framework user to finally settle the channel and withdraw the funds.
• The channel settling logic changed. Before, a call to Settle on a channel object automatically registered the channel, concluded it, and withdrew the funds. Now, to accomodate on-chain progression functionality, the user must call Register independetly before being able to settle the channel. Afterwards, for app channels, the user has the opportunity to progress the channel state on-chain by calling ProgressBy. Finally, the user can settle the channel by calling Settle.
• ContractBackend.NewTransactor now sets the context on TransactOpts. Furthermore, parameter value has been removed.

Fixed

• Persistence: Sub-channels are now persisted and restored properly.

0.5.2 European Ecstasy - 2020-11-05 ⚠️

ERC20 and Funding Agreement support and many test fixes.

Added

• Funding agreement support: when proposing channels, the proposer can now optionally suggest to reallocate the funding responsibilities among the participants so that it differs from the initial channel allocation.
• ERC20 support.
• A context-aware WaitGroup implementation to pkg/sync.

Changed

• The eth/wallet/hd.Transactor to use the correct types.Signer if the Wallet has a correct SignHash method.
• The Go version to 1.15.

Fixed

• Many timeouts in tests that made slow CI pipelines fail.
• A bug in the Concurrent Tester.
• The Client role tests to not deadlock so easily.

0.5.0 Europa - 2020-10-17 ⚠️

The Sub-Channels release, enabling fully generalized state channels.

Added

• Sub-Channels: run app-channels inside parent (ledger) channels.
• Special NoApp for channels without app. Skips force-execution phase in disputes.
• Optimized Channel.SettleSecondary settlement method for the responding settler during optimistic channel settlements. Avoids wasting gas by not sending unnecessary transactions.
• ErrorGatherer type to pkg/errors package for errors accumulation.
• Transactor abstraction to allow different wallet implementations for transaction sending in Ethereum backend.
• App registry so that multiple apps can be used in a single program instance.

Changed

• channel.Update to accept a channel.State instead of channel.ChannelUpdate. This simplifies the usage.
• Contracts updated to handle sub-channels.
• Contracts now have distinct dispute and force-execution phases.
• Channel proposal protocol now uses shared nonce from all channel peers.

Fixed

• Channel peers persistence in key-value persistence backend.

0.4.0 Despina - 2020-07-23 ⚠️

Introduced a wire messaging abstraction. License changed to Apache 2.0.

Added

• Wire messages are now sent and received over an abstract wire.Bus. It serves as a wire messaging abstraction for the client package using pub/sub semantics.
  • wire.Msgs are wrapped in Envelopes that have a sender and recipient.
  • Two implementations available:
    • wire.LocalBus for multiple clients running in the same program instance.
    • wire/net.Bus for wire connections over networks.
• Consistent use of wallet.Addresses as map keys (wallet.AddrKey).
• Ordering to wallet.Addresseses to resolve ties in protocols.
• Contract validation to Ethereum backend.
• Consistent creation of PRNGs in tests (pkg/test.Prng).

Changed

• License to Apache 2.0.
• The packages peer, wire and pkg/io were restructured:
  • Serialization code was moved from wire into pkg/io.
  • The peer package was merged into the wire package.
  • Networking-specific wire components were moved into wire/net.
  • The simple TCP/IP and Unix Dialer and Listener implementations were moved into wire/net/simple.
• The ProposalHandler and UpdateHandler interfaces' methods were renamed to explicitly name what they handle (HandleProposal and HandleUpdate).
• The keyvalue persister uses an improved data model and doesn't cache peer-channels any more.
• Channel.Peers now returns the full list of channel network peers, including the own wire.Address.

Fixed

• A race in client synchronization.

Removed

• The net package, as it didn't contain anything useful.

0.3.0 Charon - 2020-05-29 ⚠️

Added persistence module to persist channel state data and handle client shutdowns/restarts, as well as disconnects/reconnects.

Added

• Persistence:
  • Persister, Restorer, ChannelIterator interfaces to allow for multiple persistence implementations.
    • sortedkv implementation provided (in-memory and LevelDB).
  • States and signatures are constantly persisted while channels progress.
  • Clients restore all saved channels on startup. State is synchronized with peers.
  • Client.OnNewChannel callback registration to deal with restored channels.
• Wallet interface for account unlocking abstraction.
  • Used during persistence to restore secret keys for signing.
  • Implemented for the Ethereum and simulated backend.
• Peer disconnect/reconnect handling.
• Channel.UpdateBy functional channel update method for better usability.

Changed

• License changed to Apache 2.0.
• Replaced Channel.ListenUpdates and Client.HandleChannelProposals with Client.Handle(ProposalHandler, UpdateHandler) - a single common handler routine per client.
• Adapted client to new persistence layer and wallet.
• Made Ethereum interactions idempotent (increased safety).
• Moved subpackage db to pkg/sortedkv.
• Swapped Balance dimensions of type channel.Allocation.
• Random type generators in package channel/test now accept options to customize random data generation.
• Channels now get automatically closed when peers disconnect (and restored on reconnect).

Fixed

• Ethereum backend: No funding transactions for zero own initial channel balances.

0.2.0 Belinda - 2020-03-23 ⚠️

Added direct disputes and watcher for two-party ledger channels, much polishing (refactors, bug fixes, documentation).

Added

• Ledger state channel disputes and watcher.
• channel.Adjudicator interface and Ethereum implementation for registering channel states and withdrawing concluded channels.
• Ethereum contracts for disputes
• Godoc
• Changelog
• goreportcard
• TCP and unix socket peer.Dialer and Listener implementations.
• Eventually tester in pkg/test to repeatedly run tests until they succeed.
• Concurrent testing tool in pkg/test to be able to call require in tests with multiple go routines.

Changed

• client.New now needs a Funder and Adjudicator, instead of a Settler.
• Serializable renamed to Serializer.
• Unified backend imports.
• pkg/io/test/bytewiseReader to iotest.OneByteReader.
• Improved peer message handling mechanism.
• Consistent handling of nil arguments in exported functions.
• Many refactors to improve the overall code quality and documentation.
• Updated Ethereum contract bindings to newest version.

Removed

• wallet.Wallet interface and sim backend implementation - it was never used.
• ethereum and sim/wallet.NewAddressFromBytes - only wallet.DecodeAddress should be used to create an Address from bytes.
• channel/machine Phase subscription logic.
• channel.Settler interface and backend implementations - replaced by Adjudicator.

Fixed

• Reduced cyclomatic complexity of complex functions.
• Deadlock in two-party payment channel test.
• Ethereum backend test timeouts and instabilities.
• Many minor bug fixes, mainly concurrency issues in tests.

0.1.0 Ariel - 2019-12-20 ⚠️

Initial release.

Added

• Two-party ledger state channels.
• Cooperatively settling two-party ledger channels.
• Ethereum blockchain backend.
• Logrus logging backend.

Legend

• ⚠️ This is a pre-release and not intended for usage with real funds.
• 💥 This is a breaking change, e.g., it changes the external API.