chore(all): Rename and add comments to exported functions

Signed-off-by: Sophia Koehler <[email protected]>

channel/machine.go

@@ -576,6 +576,7 @@ func (m *machine) forceState(p Phase, s *State) {
 	m.addTx(m.newTransaction(s))
 }
 
+// AddressMapfromAccountMap returns a map of addresses from a map of accounts.
 func AddressMapfromAccountMap(accs map[wallet.BackendID]wallet.Account) map[wallet.BackendID]wallet.Address {
 	addresses := make(map[wallet.BackendID]wallet.Address)
 	for id, a := range accs {

channel/multi/adjudicator.go

@@ -35,13 +35,13 @@ func NewAdjudicator() *Adjudicator {
 
 // RegisterAdjudicator registers an adjudicator for a given ledger.
 func (a *Adjudicator) RegisterAdjudicator(l AssetID, la channel.Adjudicator) {
-	key := AssetIDKey{BackendID: l.BackendID(), LedgerID: string(l.LedgerId().MapKey())}
+	key := AssetIDKey{BackendID: l.BackendID(), LedgerID: string(l.LedgerID().MapKey())}
 	a.adjudicators[key] = la
 }
 
 // LedgerAdjudicator returns the adjudicator for a given ledger.
 func (a *Adjudicator) LedgerAdjudicator(l AssetID) (channel.Adjudicator, bool) {
-	key := AssetIDKey{BackendID: l.BackendID(), LedgerID: string(l.LedgerId().MapKey())}
+	key := AssetIDKey{BackendID: l.BackendID(), LedgerID: string(l.LedgerID().MapKey())}
 	adj, ok := a.adjudicators[key]
 	return adj, ok
 }
@@ -98,7 +98,7 @@ func (a *Adjudicator) dispatch(assetIds []AssetID, f func(channel.Adjudicator) e
 	for _, l := range assetIds {
 		go func(l AssetID) {
 			err := func() error {
-				key := AssetIDKey{BackendID: l.BackendID(), LedgerID: string(l.LedgerId().MapKey())}
+				key := AssetIDKey{BackendID: l.BackendID(), LedgerID: string(l.LedgerID().MapKey())}
 				adjs, ok := a.adjudicators[key]
 				if !ok {
 					return fmt.Errorf("adjudicator not found for id %v", l)

channel/multi/asset.go

@@ -30,7 +30,7 @@ type (
 	// AssetID represents an asset identifier.
 	AssetID interface {
 		BackendID() uint32
-		LedgerId() LedgerID
+		LedgerID() LedgerID
 	}
 
 	// LedgerIDMapKey is the map key representation of a ledger identifier.
@@ -55,7 +55,7 @@ func (a assets) LedgerIDs() ([]AssetID, error) {
 
 		assetID := ma.AssetID()
 
-		ids[AssetIDKey{BackendID: assetID.BackendID(), LedgerID: string(assetID.LedgerId().MapKey())}] = assetID
+		ids[AssetIDKey{BackendID: assetID.BackendID(), LedgerID: string(assetID.LedgerID().MapKey())}] = assetID
 	}
 	idsArray := make([]AssetID, len(ids))
 	i := 0
@@ -79,7 +79,7 @@ func IsMultiLedgerAssets(assets []channel.Asset) bool {
 		case !hasMulti:
 			hasMulti = true
 			id = multiAsset.AssetID()
-		case id.LedgerId().MapKey() != multiAsset.AssetID().LedgerId().MapKey():
+		case id.LedgerID().MapKey() != multiAsset.AssetID().LedgerID().MapKey():
 			return true
 		}
 	}

channel/multi/funder.go

@@ -46,14 +46,14 @@ func NewFunder() *Funder {
 
 // RegisterFunder registers a funder for a given ledger.
 func (f *Funder) RegisterFunder(l AssetID, lf channel.Funder) {
-	key := AssetIDKey{BackendID: l.BackendID(), LedgerID: string(l.LedgerId().MapKey())}
+	key := AssetIDKey{BackendID: l.BackendID(), LedgerID: string(l.LedgerID().MapKey())}
 	f.funders[key] = lf
 	f.egoisticChains[key] = false
 }
 
 // SetEgoisticChain sets the egoistic chain flag for a given ledger.
 func (f *Funder) SetEgoisticChain(l AssetID, id int, egoistic bool) {
-	key := AssetIDKey{BackendID: l.BackendID(), LedgerID: string(l.LedgerId().MapKey())}
+	key := AssetIDKey{BackendID: l.BackendID(), LedgerID: string(l.LedgerID().MapKey())}
 	f.egoisticChains[key] = egoistic
 }
 
@@ -75,7 +75,7 @@ func (f *Funder) Fund(ctx context.Context, request channel.FundingReq) error {
 	var nonEgoisticLedgers []AssetID
 
 	for _, l := range assetIDs {
-		key := AssetIDKey{BackendID: l.BackendID(), LedgerID: string(l.LedgerId().MapKey())}
+		key := AssetIDKey{BackendID: l.BackendID(), LedgerID: string(l.LedgerID().MapKey())}
 		if f.egoisticChains[key] {
 			egoisticLedgers = append(egoisticLedgers, l)
 		} else {
@@ -107,11 +107,11 @@ func fundLedgers(ctx context.Context, request channel.FundingReq, assetIDs []Ass
 	// Iterate over blockchains to get the LedgerIDs
 	for _, assetID := range assetIDs {
 		go func(assetID AssetID) {
-			key := AssetIDKey{BackendID: assetID.BackendID(), LedgerID: string(assetID.LedgerId().MapKey())}
+			key := AssetIDKey{BackendID: assetID.BackendID(), LedgerID: string(assetID.LedgerID().MapKey())}
 			// Get the Funder from the funders map
 			funder, ok := funders[key]
 			if !ok {
-				errs <- fmt.Errorf("funder map not found for blockchain %d and ledger %d", assetID.BackendID(), assetID.LedgerId())
+				errs <- fmt.Errorf("funder map not found for blockchain %d and ledger %d", assetID.BackendID(), assetID.LedgerID())
 				return
 			}
 

channel/params.go

@@ -58,6 +58,7 @@ func NonceFromBytes(b []byte) Nonce {
 // Zero is the default channelID.
 var Zero = ID{}
 
+// EqualIDs compares two IDs for equality.
 func EqualIDs(a, b map[wallet.BackendID]ID) bool {
 	if len(a) != len(b) {
 		return false
@@ -74,6 +75,7 @@ func EqualIDs(a, b map[wallet.BackendID]ID) bool {
 	return true
 }
 
+// Encode encodes the IDMap to the given writer.
 func (ids IDMap) Encode(w stdio.Writer) error {
 	length := int32(len(ids))
 	if err := perunio.Encode(w, length); err != nil {
@@ -90,6 +92,7 @@ func (ids IDMap) Encode(w stdio.Writer) error {
 	return nil
 }
 
+// Decode decodes the IDMap from the given reader.
 func (ids *IDMap) Decode(r stdio.Reader) error {
 	var mapLen int32
 	if err := perunio.Decode(r, &mapLen); err != nil {
@@ -110,6 +113,7 @@ func (ids *IDMap) Decode(r stdio.Reader) error {
 	return nil
 }
 
+// IDKey returns a string representation of the IDMap.
 func IDKey(ids IDMap) string {
 	var buff strings.Builder
 	length := int32(len(ids))
@@ -144,6 +148,7 @@ func sortIDMap(ids IDMap) ([]wallet.BackendID, []ID) {
 	return sortedIndexes, sortedIDs
 }
 
+// FromIDKey decodes an IDMap from a string representation.
 func FromIDKey(k string) IDMap {
 	buff := bytes.NewBuffer([]byte(k))
 	var numElements int32

channel/persistence/test/channel.go

@@ -91,26 +91,14 @@ func NewRandomChannel(
 func requireEqualPeers(t require.TestingT, expected, actual []map[wallet.BackendID]wire.Address) {
 	require.Equal(t, len(expected), len(actual))
 	for i, p := range expected {
-		if !EqualWireMaps(p, actual[i]) {
+		if !channel.EqualWireMaps(p, actual[i]) {
 			t.Errorf("restored peers for channel do not match\nexpected: %v\nactual: %v",
 				actual, expected)
 			t.FailNow()
 		}
 	}
 }
 
-func EqualWireMaps(a, b map[wallet.BackendID]wire.Address) bool {
-	if len(a) != len(b) {
-		return false
-	}
-	for i, addr := range a {
-		if !addr.Equal(b[i]) {
-			return false
-		}
-	}
-	return true
-}
-
 // AssertPersisted reads the channel state from the restorer and compares it
 // to the actual channel state. If an error occurs while restoring the channel
 // or if the restored channel does not match the actual channel state, then the

channel/persistence/test/persistrestorertest.go

@@ -187,7 +187,7 @@ func GenericPersistRestorerTest(
 peerLoop:
 	for idx, addr := range peers {
 		for _, paddr := range persistedPeers {
-			if EqualWireMaps(addr, paddr) {
+			if channel.EqualWireMaps(addr, paddr) {
 				continue peerLoop // found, next address
 			}
 		}

channel/state.go

@@ -162,6 +162,7 @@ func (s *State) ToSubAlloc() *SubAlloc {
 	return NewSubAlloc(s.ID, s.Allocation.Sum(), nil)
 }
 
+// EqualWireMaps compares two wire.Address maps for equality.
 func EqualWireMaps(a, b map[wallet.BackendID]wire.Address) bool {
 	if len(a) != len(b) {
 		return false

channel/test/randomizer.go

@@ -140,9 +140,9 @@ func NewRandomLockedIDs(rng *rand.Rand, opts ...RandomOpt) []map[wallet.BackendI
 		for i := range ids {
 			for j := range bIds {
 				ids[i] = make(map[wallet.BackendID]channel.ID)
-				cId := [32]byte{}
-				rng.Read(cId[:])
-				ids[i][wallet.BackendID(j)] = cId
+				cID := [32]byte{}
+				rng.Read(cID[:])
+				ids[i][wallet.BackendID(j)] = cID
 			}
 		}
 		return ids
@@ -152,14 +152,14 @@ func NewRandomLockedIDs(rng *rand.Rand, opts ...RandomOpt) []map[wallet.BackendI
 	for i := range ids {
 		if err != nil {
 			ids[i] = make(map[wallet.BackendID]channel.ID)
-			cId := [32]byte{}
-			rng.Read(cId[:])
-			ids[i][0] = cId
+			cID := [32]byte{}
+			rng.Read(cID[:])
+			ids[i][0] = cID
 		} else {
 			ids[i] = make(map[wallet.BackendID]channel.ID)
-			cId := [32]byte{}
-			rng.Read(cId[:])
-			ids[i][b] = cId
+			cID := [32]byte{}
+			rng.Read(cID[:])
+			ids[i][b] = cID
 		}
 	}
 	return ids
@@ -267,21 +267,21 @@ func NewRandomChannelID(rng *rand.Rand, opts ...RandomOpt) (id map[wallet.Backen
 	bIds, err := opt.BackendID()
 	if bIds != nil && err == nil {
 		for _, b := range bIds {
-			cId := [32]byte{}
-			rng.Read(cId[:])
-			id[b] = cId
+			cID := [32]byte{}
+			rng.Read(cID[:])
+			id[b] = cID
 		}
 		return
 	}
 	bId, err := opt.Backend()
 	if err != nil {
-		cId := [32]byte{}
-		rng.Read(cId[:])
-		id[0] = cId
+		cID := [32]byte{}
+		rng.Read(cID[:])
+		id[0] = cID
 	} else {
-		cId := [32]byte{}
-		rng.Read(cId[:])
-		id[bId] = cId
+		cID := [32]byte{}
+		rng.Read(cID[:])
+		id[bId] = cID
 	}
 	return
 }

client/test/backend.go

@@ -61,10 +61,12 @@ type (
 	LedgerID string
 )
 
-func (id AssetID) LedgerId() multi.LedgerID {
+// LedgerID returns the ledger identifier.
+func (id AssetID) LedgerID() multi.LedgerID {
 	return id.ledgerID
 }
 
+// BackendID returns the backend identifier.
 func (id AssetID) BackendID() uint32 {
 	return id.backendID
 }

client/test/multiledger.go

@@ -96,6 +96,7 @@ type MultiLedgerAsset struct {
 	asset channel.Asset
 }
 
+// AssetID returns the asset's ID.
 func (a *MultiLedgerAsset) AssetID() multi.AssetID {
 	return a.id
 }
@@ -115,7 +116,7 @@ func (a *MultiLedgerAsset) Equal(b channel.Asset) bool {
 		return false
 	}
 
-	return a.id.LedgerId().MapKey() == bm.id.LedgerId().MapKey() && a.asset.Equal(bm.asset) && a.id.BackendID() == bm.id.BackendID()
+	return a.id.LedgerID().MapKey() == bm.id.LedgerID().MapKey() && a.asset.Equal(bm.asset) && a.id.BackendID() == bm.id.BackendID()
 }
 
 // Address returns the asset's address.
@@ -131,7 +132,7 @@ func (a *MultiLedgerAsset) LedgerID() multi.AssetID {
 // MarshalBinary encodes the asset to its byte representation.
 func (a *MultiLedgerAsset) MarshalBinary() ([]byte, error) {
 	var buf bytes.Buffer
-	err := perunio.Encode(&buf, string(a.id.LedgerId().MapKey()), a.id.BackendID(), a.asset)
+	err := perunio.Encode(&buf, string(a.id.LedgerID().MapKey()), a.id.BackendID(), a.asset)
 	if err != nil {
 		return nil, err
 	}
@@ -142,7 +143,7 @@ func (a *MultiLedgerAsset) MarshalBinary() ([]byte, error) {
 // UnmarshalBinary decodes the asset from its byte representation.
 func (a *MultiLedgerAsset) UnmarshalBinary(data []byte) error {
 	buf := bytes.NewBuffer(data)
-	return perunio.Decode(buf, string(a.id.LedgerId().MapKey()), a.id.BackendID(), a.asset)
+	return perunio.Decode(buf, string(a.id.LedgerID().MapKey()), a.id.BackendID(), a.asset)
 }
 
 // MultiLedgerClient represents a test client.

wire/address.go

@@ -192,6 +192,7 @@ func Keys(addressMap map[wallet.BackendID]Address) AddrKey {
 	return AddrKey(strings.Join(keyParts, "|"))
 }
 
+// AddressMapfromAccountMap converts a map of accounts to a map of addresses.
 func AddressMapfromAccountMap(accs map[wallet.BackendID]Account) map[wallet.BackendID]Address {
 	addresses := make(map[wallet.BackendID]Address)
 	for id, a := range accs {

wire/net/endpoint_registry.go

@@ -21,7 +21,8 @@ import (
 	"time"
 	"unsafe"
 
-	"perun.network/go-perun/channel/persistence/test"
+	"perun.network/go-perun/channel"
+
 	"perun.network/go-perun/wallet"
 
 	"github.com/pkg/errors"
@@ -178,7 +179,7 @@ func (r *EndpointRegistry) setupConn(conn Conn) error {
 		return err
 	}
 
-	if test.EqualWireMaps(peerAddr, wire.AddressMapfromAccountMap(r.id)) {
+	if channel.EqualWireMaps(peerAddr, wire.AddressMapfromAccountMap(r.id)) {
 		r.Log().Error("dialed by self")
 		return errors.New("dialed by self")
 	}
@@ -194,7 +195,7 @@ func (r *EndpointRegistry) Endpoint(ctx context.Context, addr map[wallet.Backend
 	log := r.Log().WithField("peer", addr)
 	key := wire.Keys(addr)
 
-	if test.EqualWireMaps(addr, wire.AddressMapfromAccountMap(r.id)) {
+	if channel.EqualWireMaps(addr, wire.AddressMapfromAccountMap(r.id)) {
 		log.Panic("tried to dial self")
 	}
 

wire/net/exchange_addr.go

@@ -18,7 +18,8 @@ import (
 	"context"
 	"fmt"
 
-	"perun.network/go-perun/channel/persistence/test"
+	"perun.network/go-perun/channel"
+
 	"perun.network/go-perun/wallet"
 
 	"github.com/pkg/errors"
@@ -86,8 +87,8 @@ func ExchangeAddrsActive(ctx context.Context, id map[wallet.BackendID]wire.Accou
 			if check := VerifyAddressSignature(peer, msg.Signature); check != nil {
 				err = errors.WithMessage(check, "verifying peer address's signature")
 			}
-		} else if !test.EqualWireMaps(e.Recipient, wire.AddressMapfromAccountMap(id)) &&
-			!test.EqualWireMaps(e.Sender, peer) {
+		} else if !channel.EqualWireMaps(e.Recipient, wire.AddressMapfromAccountMap(id)) &&
+			!channel.EqualWireMaps(e.Sender, peer) {
 			err = NewAuthenticationError(e.Sender, e.Recipient, wire.AddressMapfromAccountMap(id), "unmatched response sender or recipient")
 		}
 	})
@@ -112,7 +113,7 @@ func ExchangeAddrsPassive(ctx context.Context, id map[wallet.BackendID]wire.Acco
 			err = errors.WithMessage(err, "receiving auth message")
 		} else if _, ok := e.Msg.(*wire.AuthResponseMsg); !ok {
 			err = errors.Errorf("expected AuthResponse wire msg, got %v", e.Msg.Type())
-		} else if !test.EqualWireMaps(e.Recipient, addrs) {
+		} else if !channel.EqualWireMaps(e.Recipient, addrs) {
 			err = NewAuthenticationError(e.Sender, e.Recipient, wire.AddressMapfromAccountMap(id), "unmatched response sender or recipient")
 		} else if msg, ok := e.Msg.(*wire.AuthResponseMsg); ok {
 			if err = VerifyAddressSignature(e.Sender, msg.Signature); err != nil {

wire/net/test/listenermap.go

@@ -17,7 +17,8 @@ package test
 import (
 	"sync"
 
-	"perun.network/go-perun/channel/persistence/test"
+	"perun.network/go-perun/channel"
+
 	"perun.network/go-perun/wallet"
 
 	"github.com/pkg/errors"
@@ -40,7 +41,7 @@ type listenerMap struct {
 // other functions.
 func (m *listenerMap) findEntry(key map[wallet.BackendID]wire.Address) (listenerMapEntry, int, bool) {
 	for i, v := range m.entries {
-		if test.EqualWireMaps(v.key, key) {
+		if channel.EqualWireMaps(v.key, key) {
 			return v, i, true
 		}
 	}