Merge pull request #306 from perun-network/155-revise-channel

💥 Channel.Update/ForceUpdate: updater no longer returns error

Relates to #155

Author: Manoranjith

README.md

@@ -146,7 +146,7 @@ func main() {
 	}()
 
 	// send a channel update request to the other channel peer(s)
-	err = ch.Update(ctx, func(s *channel.State) error {
+	err = ch.Update(ctx, func(s *channel.State) {
 		// update state s, e.g., moving funds or changing app data
 	})
 	if err != nil { /* handle error */ }

channel/machine.go

@@ -475,15 +475,15 @@ func (m *machine) expect(tr PhaseTransition) error {
 	return nil
 }
 
-// validTransition checks that the transition from the current to the provided
+// ValidTransition checks that the transition from the current to the provided
 // state is valid. The following checks are run:
 // * matching channel ids
 // * no transition from final state
 // * version increase by 1
 // * preservation of balances
 // A StateMachine will additionally check the validity of the app-specific
 // transition whereas an ActionMachine checks each Action as being valid.
-func (m *machine) validTransition(to *State) error {
+func (m *machine) ValidTransition(to *State) error {
 	if to.ID != m.params.id {
 		return errors.New("new state's ID doesn't match")
 	}

channel/statemachine.go

@@ -134,7 +134,7 @@ func (m *StateMachine) validTransition(to *State, actor Index) (err error) {
 	if actor >= m.N() {
 		return errors.New("actor index is out of range")
 	}
-	if err := m.machine.validTransition(to); err != nil {
+	if err := m.machine.ValidTransition(to); err != nil {
 		return err
 	}
 

client/adjudicate.go

@@ -178,16 +178,19 @@ func (c *Channel) registerDispute(ctx context.Context) error {
 	return nil
 }
 
-// ForceUpdate enforces a channel update on the adjudicator. `update` gets as
-// input a copy of the current state and is expected to modify the state as
-// intended. It should not to increment the version number as this is
-// automatically.
+// ForceUpdate enforces a state update through the adjudicator as specified by
+// the `updater` function.
+//
+// The updater function must adhere to the following rules:
+// - The version must not be changed. It is incremented automatically.
+// - The assets must not be changed.
+// - The locked allocation must not be changed.
 //
 // Returns TxTimedoutError when the program times out waiting for a transaction
 // to be mined. Returns ChainNotReachableError if the connection to the
 // blockchain network fails when sending a transaction to / reading from the
 // blockchain.
-func (c *Channel) ForceUpdate(ctx context.Context, update func(*channel.State) error) error {
+func (c *Channel) ForceUpdate(ctx context.Context, updater func(*channel.State)) error {
 	err := c.ensureRegistered(ctx)
 	if err != nil {
 		return err
@@ -204,10 +207,12 @@ func (c *Channel) ForceUpdate(ctx context.Context, update func(*channel.State) e
 
 	// Update state
 	state := ar.Tx.State.Clone()
+	updater(state)
 	state.Version++
-	err = update(state)
-	if err != nil {
-		return errors.WithMessage(err, "updating state")
+
+	// Check state transition.
+	if err := c.machine.ValidTransition(state); err != nil {
+		return errors.WithMessage(err, "validating state transition")
 	}
 
 	// Apply state in machine and generate signature

client/test/channel.go

@@ -98,21 +98,20 @@ func (ch *paymentChannel) acceptSubchannel(
 	return subchannel
 }
 
-func (ch *paymentChannel) sendUpdate(update func(*channel.State) error, desc string) {
+func (ch *paymentChannel) sendUpdate(updater func(*channel.State), desc string) {
 	ch.log.Debugf("Sending update: %s", desc)
 	ctx, cancel := context.WithTimeout(context.Background(), ch.r.timeout)
 	defer cancel()
 
-	err := ch.Update(ctx, update)
+	err := ch.Update(ctx, updater)
 	ch.log.Infof("Sent update: %s, err: %v", desc, err)
 	assert.NoError(ch.r.t, err)
 }
 
 func (ch *paymentChannel) sendTransfer(amount channel.Bal, desc string) {
 	ch.sendUpdate(
-		func(state *channel.State) error {
+		func(state *channel.State) {
 			transferBal(stateBals(state), ch.Idx(), amount)
-			return nil
 		},
 		desc,
 	)
@@ -157,9 +156,8 @@ func (ch *paymentChannel) assertBals(state *channel.State) {
 }
 
 func (ch *paymentChannel) sendFinal() {
-	ch.sendUpdate(func(state *channel.State) error {
+	ch.sendUpdate(func(state *channel.State) {
 		state.IsFinal = true
-		return nil
 	}, "final")
 	assert.True(ch.r.t, ch.State().IsFinal)
 }

client/test/progression.go

@@ -95,14 +95,13 @@ func (r *Paul) exec(_cfg ExecConfig, ch *paymentChannel) {
 	r.waitStage() // wait for setup complete
 
 	// progress
-	assert.NoError(ch.ForceUpdate(ctx, func(s *channel.State) error {
+	assert.NoError(ch.ForceUpdate(ctx, func(s *channel.State) {
 		bal := func(user channel.Index) int64 {
 			return s.Balances[assetIdx][user].Int64()
 		}
 		half := (bal(0) + bal(1)) / 2 //nolint:gomnd
 		s.Balances[assetIdx][0] = big.NewInt(half)
 		s.Balances[assetIdx][1] = big.NewInt(half)
-		return nil
 	}))
 
 	// await our progression confirmation
@@ -167,14 +166,13 @@ func (r *Paula) exec(_cfg ExecConfig, ch *paymentChannel, _ *acceptNextPropHandl
 	r.t.Logf("%v received progression confirmation 1", r.setup.Name)
 
 	// we progress
-	assert.NoError(ch.ForceUpdate(ctx, func(s *channel.State) error {
+	assert.NoError(ch.ForceUpdate(ctx, func(s *channel.State) {
 		bal := func(user channel.Index) int64 {
 			return s.Balances[assetIdx][user].Int64()
 		}
 		half := (bal(0) + bal(1)) / 2 //nolint:gomnd
 		s.Balances[assetIdx][0] = big.NewInt(half + paulPaulaBalTransferAmount)
 		s.Balances[assetIdx][1] = big.NewInt(half - paulPaulaBalTransferAmount)
-		return nil
 	}))
 
 	// await our progression confirmation

client/update.go

@@ -131,14 +131,18 @@ func (r *UpdateResponder) Reject(ctx context.Context, reason string) error {
 	return r.channel.handleUpdateRej(ctx, r.pidx, r.req, reason)
 }
 
-// Update updates the channel state using the update function and proposes the
-// new state to all other channel participants. The update function must not
-// update the version counter.
+// Update proposes a state update to the channel participants as
+// specified by the `updater` function.
+//
+// The updater function must adhere to the following rules:
+// - The version must not be changed. It is incremented automatically.
+// - The assets must not be changed.
+// - The locked allocation must not be changed.
 //
 // Returns nil if all peers accept the update. Returns RequestTimedOutError if
 // any peer did not respond before the context expires or is cancelled. Returns
 // an error if any runtime error occurs or any peer rejects the update.
-func (c *Channel) Update(ctx context.Context, update func(*channel.State) error) (err error) {
+func (c *Channel) Update(ctx context.Context, updater func(*channel.State)) error {
 	if ctx == nil {
 		return errors.New("context must not be nil")
 	}
@@ -152,9 +156,7 @@ func (c *Channel) Update(ctx context.Context, update func(*channel.State) error)
 	return c.update(ctx,
 		func(state *channel.State) error {
 			// apply update
-			if err := update(state); err != nil {
-				return err
-			}
+			updater(state)
 
 			// validate
 			return c.validTwoPartyUpdateState(state)
@@ -239,9 +241,9 @@ func (c *Channel) checkUpdateError(ctx context.Context, updateErr error) {
 	}
 }
 
-func (c *Channel) update(ctx context.Context, update func(*channel.State) error) (err error) {
+func (c *Channel) update(ctx context.Context, updater func(*channel.State) error) (err error) {
 	state := c.machine.State().Clone()
-	if err := update(state); err != nil {
+	if err := updater(state); err != nil {
 		return err
 	}
 	state.Version++

client/virtual_channel_test.go

@@ -268,15 +268,13 @@ func setupVirtualChannelTest(t *testing.T, ctx context.Context) (vct virtualChan
 		t.Fatalf("Error in go-routine: %v", err)
 	}
 
-	err = vct.chAliceBob.Update(ctx, func(s *channel.State) error {
+	err = vct.chAliceBob.Update(ctx, func(s *channel.State) {
 		s.Balances = channel.Balances{vct.virtualBalsUpdated}
-		return nil
 	})
 	require.NoError(err, "updating virtual channel")
 
-	err = vct.chAliceBob.Update(ctx, func(s *channel.State) error {
+	err = vct.chAliceBob.Update(ctx, func(s *channel.State) {
 		s.IsFinal = true
-		return nil
 	})
 	require.NoError(err, "updating virtual channel")
 	return vct