From 1e83673f2398a6f2ae8b5611926a0a74d06480e6 Mon Sep 17 00:00:00 2001
From: Dmitry Holodov <dimalinux@protonmail.com>
Date: Fri, 2 Dec 2022 00:43:32 -0600
Subject: [PATCH] add package comments (#236)

package comments added to all packages
---
 .golangci.yml                              |  3 +--
 cliutil/utils.go                           |  1 +
 cmd/swapcli/main.go                        |  2 ++
 cmd/swapd/main.go                          |  6 ++++--
 cmd/swaptester/main.go                     |  2 ++
 common/consts.go                           |  1 +
 common/rpctypes/types.go                   |  2 ++
 common/types/status.go                     |  1 +
 crypto/hash.go                             |  2 ++
 crypto/monero/crypto.go                    |  2 ++
 crypto/monero/crypto_marshal_test.go       |  4 ++--
 crypto/secp256k1/secp256k1.go              |  2 ++
 db/database.go                             |  1 +
 dleq/dleq.go                               | 13 +++++--------
 ethereum/block/wait_for_timestamp.go       |  3 +++
 ethereum/contracts/SwapFactory.sol         |  2 +-
 ethereum/extethclient/eth_wallet_client.go |  2 ++
 ethereum/utils.go                          |  2 ++
 ethereum/watcher/watcher.go                |  1 +
 monero/wallet_client.go                    |  4 +++-
 net/host.go                                |  1 +
 net/message/message.go                     |  1 +
 protocol/backend/backend.go                |  2 ++
 protocol/common.go                         |  1 +
 protocol/swap/manager.go                   |  2 ++
 protocol/txsender/sender.go                |  5 +++++
 protocol/xmrmaker/net.go                   |  2 +-
 protocol/xmrmaker/offers/offer_manager.go  |  1 +
 protocol/xmrmaker/swap_state.go            |  4 +++-
 protocol/xmrtaker/message_handler.go       |  2 +-
 protocol/xmrtaker/net.go                   |  2 +-
 protocol/xmrtaker/swap_state.go            |  4 +++-
 relayer/relayer.go                         |  3 +++
 rpc/server.go                              |  3 +++
 rpcclient/client.go                        |  2 ++
 rpcclient/wsclient/wsclient.go             |  2 ++
 tests/integration_test.go                  |  3 +++
 37 files changed, 75 insertions(+), 21 deletions(-)

diff --git a/.golangci.yml b/.golangci.yml
index ab1bb1a6..52d65364 100644
--- a/.golangci.yml
+++ b/.golangci.yml
@@ -23,7 +23,6 @@ linters-settings:
     # Correct spellings using locale preferences for US or UK.
     # Default is to use a neutral variety of English.
     # Setting locale to US will correct the British spelling of 'colour' to 'color'.
-    locale: UK
   gocritic:
     # Enable multiple checks by tags, run `GL_DEBUG=gocritic golangci-lint` run to see all tags and checks.
     # Empty list by default. See https://github.com/go-critic/go-critic#usage -> section "Tags".
@@ -96,4 +95,4 @@ issues:
   max-per-linter: 0
 
   # Maximum count of issues with the same text. Set to 0 to disable. Default is 3.
-  max-same-issues: 0
\ No newline at end of file
+  max-same-issues: 0
diff --git a/cliutil/utils.go b/cliutil/utils.go
index a0312239..d5524c9f 100644
--- a/cliutil/utils.go
+++ b/cliutil/utils.go
@@ -1,3 +1,4 @@
+// Package cliutil provides utility functions intended for sharing by the main packages of multiple executables.
 package cliutil
 
 import (
diff --git a/cmd/swapcli/main.go b/cmd/swapcli/main.go
index fc63cefd..0e2ff8dc 100644
--- a/cmd/swapcli/main.go
+++ b/cmd/swapcli/main.go
@@ -1,3 +1,5 @@
+// Package main provides the entrypoint of swapcli, an executable for interacting with a
+// local swapd instance from the command line.
 package main
 
 import (
diff --git a/cmd/swapd/main.go b/cmd/swapd/main.go
index 0c148ae9..f6368475 100644
--- a/cmd/swapd/main.go
+++ b/cmd/swapd/main.go
@@ -1,3 +1,5 @@
+// Package main provides the entrypoint of swapd, a daemon that manages atomic swaps
+// between monero and ethereum assets.
 package main
 
 import (
@@ -100,8 +102,8 @@ var (
 			},
 			&cli.StringFlag{
 				Name:  flagDataDir,
-				Usage: "Path to store swap artifacts", //nolint:misspell
-				Value: "{HOME}/.atomicswap/{ENV}",     // For --help only, actual default replaces variables
+				Usage: "Path to store swap artifacts",
+				Value: "{HOME}/.atomicswap/{ENV}", // For --help only, actual default replaces variables
 			},
 			&cli.StringFlag{
 				Name:  flagLibp2pKey,
diff --git a/cmd/swaptester/main.go b/cmd/swaptester/main.go
index 6b308db6..47892e3f 100644
--- a/cmd/swaptester/main.go
+++ b/cmd/swaptester/main.go
@@ -1,3 +1,5 @@
+// Package main provides the entrypoint of swaptester, an executable used for
+// automatically testing multiple swaps.
 package main
 
 import (
diff --git a/common/consts.go b/common/consts.go
index 3a47a9e8..cb6002fd 100644
--- a/common/consts.go
+++ b/common/consts.go
@@ -1,3 +1,4 @@
+// Package common is for miscellaneous constants, types and interfaces used by many packages.
 package common
 
 const (
diff --git a/common/rpctypes/types.go b/common/rpctypes/types.go
index 250ad7c6..5d372ea1 100644
--- a/common/rpctypes/types.go
+++ b/common/rpctypes/types.go
@@ -1,3 +1,5 @@
+// Package rpctypes provides the serialized types for queries and responses shared by
+// swapd's JSON-RPC server and client-side libraries.
 package rpctypes
 
 import (
diff --git a/common/types/status.go b/common/types/status.go
index ba436d85..66fa3558 100644
--- a/common/types/status.go
+++ b/common/types/status.go
@@ -1,3 +1,4 @@
+// Package types is for types that are shared by multiple packages
 package types
 
 // Status represents the stage that a swap is at.
diff --git a/crypto/hash.go b/crypto/hash.go
index 81d4cc43..c8c5c0c5 100644
--- a/crypto/hash.go
+++ b/crypto/hash.go
@@ -1,3 +1,5 @@
+// Package crypto is for cryptographic code used by both Monero and Ethereum.
+// Chain specific crypto is in subpackages.
 package crypto
 
 import (
diff --git a/crypto/monero/crypto.go b/crypto/monero/crypto.go
index 13827302..a3efce40 100644
--- a/crypto/monero/crypto.go
+++ b/crypto/monero/crypto.go
@@ -1,3 +1,5 @@
+// Package mcrypto is for types and libraries that deal with Monero keys, addresses and
+// signing.
 package mcrypto
 
 import (
diff --git a/crypto/monero/crypto_marshal_test.go b/crypto/monero/crypto_marshal_test.go
index 8d43f205..41506e9e 100644
--- a/crypto/monero/crypto_marshal_test.go
+++ b/crypto/monero/crypto_marshal_test.go
@@ -14,7 +14,7 @@ func TestP_Marshal_success(t *testing.T) {
 	type SomeStruct struct {
 		PrivSpendKey   *PrivateSpendKey `json:"privSpendKey"`
 		PrivateViewKey *PrivateViewKey  `json:"privViewKey"`
-		PublicSpendKey *PublicKey       `json:"pupSpendKey"`
+		PublicSpendKey *PublicKey       `json:"pubSpendKey"`
 	}
 	ed25519.NewIdentityPoint().Bytes()
 	const (
@@ -24,7 +24,7 @@ func TestP_Marshal_success(t *testing.T) {
 		expectJSON           = `{
 			"privSpendKey": "ab0000000000000000000000000000000000000000000000000000000000cd00",
 			"privViewKey":  "cd0000000000000000000000000000000000000000000000000000000000ef00",
-			"pupSpendKey":  "5866666666666666666666666666666666666666666666666666666666666666"
+			"pubSpendKey":  "5866666666666666666666666666666666666666666666666666666666666666"
 		}`
 	)
 	spendKey, err := NewPrivateSpendKeyFromHex(expectedPrivSpendKey)
diff --git a/crypto/secp256k1/secp256k1.go b/crypto/secp256k1/secp256k1.go
index 08d921af..2173a16c 100644
--- a/crypto/secp256k1/secp256k1.go
+++ b/crypto/secp256k1/secp256k1.go
@@ -1,3 +1,5 @@
+// Package secp256k1 contains methods and types for working with Ethereum and possibly other
+// cryptocurrency keys that use the secp256k1 elliptic curve.
 package secp256k1
 
 import (
diff --git a/db/database.go b/db/database.go
index 9d697ff4..650a0038 100644
--- a/db/database.go
+++ b/db/database.go
@@ -1,3 +1,4 @@
+// Package db implements the APIs for interacting with our disk persisted key-value store.
 package db
 
 import (
diff --git a/dleq/dleq.go b/dleq/dleq.go
index 2e61642d..05a10573 100644
--- a/dleq/dleq.go
+++ b/dleq/dleq.go
@@ -1,3 +1,8 @@
+// Package dleq provides a sub-api built on top of the go-dleq package for our atomic
+// swaps. The API allows you to verify that a Monero public spend key on the ed25519 curve
+// have the same discrete logarithm (same shared secret) as a public key on the secp256k1
+// curve. A ZK DLEq proof is used to prove equivalence of the secret key corresponding to
+// public keys on both curves.
 package dleq
 
 import (
@@ -25,14 +30,6 @@ func NewProofWithoutSecret(p []byte) *Proof {
 	}
 }
 
-// NewProofWithSecret returns a new Proof with the given secret.
-// Note that the returned proof actually lacks the `proof` field.
-func NewProofWithSecret(s [32]byte) *Proof {
-	return &Proof{
-		secret: s,
-	}
-}
-
 // Secret returns the proof's 32-byte secret
 func (p *Proof) Secret() [32]byte {
 	var s [32]byte
diff --git a/ethereum/block/wait_for_timestamp.go b/ethereum/block/wait_for_timestamp.go
index d7cca291..5f40812a 100644
--- a/ethereum/block/wait_for_timestamp.go
+++ b/ethereum/block/wait_for_timestamp.go
@@ -1,3 +1,6 @@
+// Package block contains ethereum helper methods that center around blocks, like waiting
+// for a certain block timestamp, waiting for a transaction to be mined in a block, and
+// extracting an error for a transaction from the block that mined it.
 package block
 
 import (
diff --git a/ethereum/contracts/SwapFactory.sol b/ethereum/contracts/SwapFactory.sol
index 81b05519..a623407b 100644
--- a/ethereum/contracts/SwapFactory.sol
+++ b/ethereum/contracts/SwapFactory.sol
@@ -19,7 +19,7 @@ contract SwapFactory is ERC2771Context, Secp256k1 {
     }
 
     struct Swap {
-        // contract creator, Alice
+        // individual swap creator, Alice
         address payable owner;
         // address allowed to claim the ether in this contract
         address payable claimer;
diff --git a/ethereum/extethclient/eth_wallet_client.go b/ethereum/extethclient/eth_wallet_client.go
index 40f20269..689d8d6b 100644
--- a/ethereum/extethclient/eth_wallet_client.go
+++ b/ethereum/extethclient/eth_wallet_client.go
@@ -1,3 +1,5 @@
+// Package extethclient provides libraries for interacting with an ethereum node
+// using a specific private key.
 package extethclient
 
 import (
diff --git a/ethereum/utils.go b/ethereum/utils.go
index 3c622afd..83335203 100644
--- a/ethereum/utils.go
+++ b/ethereum/utils.go
@@ -1,3 +1,5 @@
+// Package contracts is for go bindings generated from Solidity contracts as well as
+// some utility functions for working with the contracts.
 package contracts
 
 import (
diff --git a/ethereum/watcher/watcher.go b/ethereum/watcher/watcher.go
index 5fa7634e..e01a578a 100644
--- a/ethereum/watcher/watcher.go
+++ b/ethereum/watcher/watcher.go
@@ -1,3 +1,4 @@
+// Package watcher provides tools to track events emitted from ethereum contracts.
 package watcher
 
 import (
diff --git a/monero/wallet_client.go b/monero/wallet_client.go
index a813fb71..570b3ef5 100644
--- a/monero/wallet_client.go
+++ b/monero/wallet_client.go
@@ -1,3 +1,6 @@
+// Package monero provides client libraries for working with wallet files and interacting
+// with a monero node. Management of monero-wallet-rpc daemon instances is fully
+// encapsulated by these libraries.
 package monero
 
 import (
@@ -495,7 +498,6 @@ func launchMoneroWalletRPCChild(walletRPCBin string, walletRPCBinArgs ...string)
 	cmd.Stdout = pWrite
 	cmd.Stderr = pWrite
 
-	//nolint:misspell
 	// Last entry wins if an environment variable is in the list multiple times.
 	// We parse some output, so we want to force English. NO_COLOR=1 failed to
 	// remove ansi colour escapes, but setting TERM=dumb succeeded.
diff --git a/net/host.go b/net/host.go
index 570a3a70..04e8f1c5 100644
--- a/net/host.go
+++ b/net/host.go
@@ -1,3 +1,4 @@
+// Package net provides libraries for direct communication between swapd nodes using libp2p.
 package net
 
 import (
diff --git a/net/message/message.go b/net/message/message.go
index 352a58fb..759f951c 100644
--- a/net/message/message.go
+++ b/net/message/message.go
@@ -1,3 +1,4 @@
+// Package message provides the types for messages that are sent between swapd instances.
 package message
 
 import (
diff --git a/protocol/backend/backend.go b/protocol/backend/backend.go
index 5ea5ab61..08be3709 100644
--- a/protocol/backend/backend.go
+++ b/protocol/backend/backend.go
@@ -1,3 +1,5 @@
+// Package backend provides the portion of top-level swapd instance
+// management that is shared by both the maker and the taker.
 package backend
 
 import (
diff --git a/protocol/common.go b/protocol/common.go
index 4424b469..ce6921cb 100644
--- a/protocol/common.go
+++ b/protocol/common.go
@@ -1,3 +1,4 @@
+// Package protocol has functions that are used by both the maker and taker during execution of the swap.
 package protocol
 
 import (
diff --git a/protocol/swap/manager.go b/protocol/swap/manager.go
index 8035279d..7986b239 100644
--- a/protocol/swap/manager.go
+++ b/protocol/swap/manager.go
@@ -1,3 +1,5 @@
+// Package swap provides the management layer used by swapd for tracking current and past
+// swaps.
 package swap
 
 import (
diff --git a/protocol/txsender/sender.go b/protocol/txsender/sender.go
index e6f2334d..9cd9a06f 100644
--- a/protocol/txsender/sender.go
+++ b/protocol/txsender/sender.go
@@ -1,3 +1,8 @@
+// Package txsender provides a common Sender interface for swapd instances. Each Sender
+// implementation is responsible for signing and submitting transactions to the network.
+// privateKeySender is the implementation using an ethereum private key directly managed
+// by swapd. ExternalSender provides an API for interacting with an external entity like
+// Metamask.
 package txsender
 
 import (
diff --git a/protocol/xmrmaker/net.go b/protocol/xmrmaker/net.go
index add68199..2bd4b8c7 100644
--- a/protocol/xmrmaker/net.go
+++ b/protocol/xmrmaker/net.go
@@ -8,7 +8,7 @@ import (
 	"github.com/athanorlabs/atomic-swap/net"
 	pcommon "github.com/athanorlabs/atomic-swap/protocol"
 
-	"github.com/fatih/color" //nolint:misspell
+	"github.com/fatih/color"
 )
 
 // EthereumAssetAmount represents an amount of an Ethereum asset (ie. ether or an ERC20)
diff --git a/protocol/xmrmaker/offers/offer_manager.go b/protocol/xmrmaker/offers/offer_manager.go
index 7567679d..20aadf12 100644
--- a/protocol/xmrmaker/offers/offer_manager.go
+++ b/protocol/xmrmaker/offers/offer_manager.go
@@ -1,3 +1,4 @@
+// Package offers provides management of the offers being made by a swapd instance.
 package offers
 
 import (
diff --git a/protocol/xmrmaker/swap_state.go b/protocol/xmrmaker/swap_state.go
index 367b31df..a885bfd3 100644
--- a/protocol/xmrmaker/swap_state.go
+++ b/protocol/xmrmaker/swap_state.go
@@ -1,3 +1,5 @@
+// Package xmrmaker manages the swap state of individual swaps where the local swapd
+// instance is offering Monero and accepting Ethereum assets in return.
 package xmrmaker
 
 import (
@@ -8,7 +10,7 @@ import (
 
 	ethcommon "github.com/ethereum/go-ethereum/common"
 	ethtypes "github.com/ethereum/go-ethereum/core/types"
-	"github.com/fatih/color" //nolint:misspell
+	"github.com/fatih/color"
 
 	"github.com/athanorlabs/atomic-swap/common"
 	"github.com/athanorlabs/atomic-swap/common/types"
diff --git a/protocol/xmrtaker/message_handler.go b/protocol/xmrtaker/message_handler.go
index 0f8696e8..3b705d17 100644
--- a/protocol/xmrtaker/message_handler.go
+++ b/protocol/xmrtaker/message_handler.go
@@ -13,7 +13,7 @@ import (
 	pcommon "github.com/athanorlabs/atomic-swap/protocol"
 
 	ethcommon "github.com/ethereum/go-ethereum/common"
-	"github.com/fatih/color" //nolint:misspell
+	"github.com/fatih/color"
 )
 
 // HandleProtocolMessage is called by the network to handle an incoming message.
diff --git a/protocol/xmrtaker/net.go b/protocol/xmrtaker/net.go
index 16dbe980..8f381ebd 100644
--- a/protocol/xmrtaker/net.go
+++ b/protocol/xmrtaker/net.go
@@ -8,7 +8,7 @@ import (
 	contracts "github.com/athanorlabs/atomic-swap/ethereum"
 	pcommon "github.com/athanorlabs/atomic-swap/protocol"
 
-	"github.com/fatih/color" //nolint:misspell
+	"github.com/fatih/color"
 )
 
 // EthereumAssetAmount represents an amount of an Ethereum asset (ie. ether or an ERC20)
diff --git a/protocol/xmrtaker/swap_state.go b/protocol/xmrtaker/swap_state.go
index 4b251f43..215e9ab2 100644
--- a/protocol/xmrtaker/swap_state.go
+++ b/protocol/xmrtaker/swap_state.go
@@ -1,3 +1,5 @@
+// Package xmrtaker manages the swap state of individual swaps where the local swapd
+// instance is offering Ethereum assets and accepting Monero in return.
 package xmrtaker
 
 import (
@@ -27,7 +29,7 @@ import (
 
 	ethcommon "github.com/ethereum/go-ethereum/common"
 	ethtypes "github.com/ethereum/go-ethereum/core/types"
-	"github.com/fatih/color" //nolint:misspell
+	"github.com/fatih/color"
 )
 
 const revertSwapCompleted = "swap is already completed"
diff --git a/relayer/relayer.go b/relayer/relayer.go
index 23e1e751..d19d3794 100644
--- a/relayer/relayer.go
+++ b/relayer/relayer.go
@@ -1,3 +1,6 @@
+// Package relayer provides client libraries that Bob (an XMR maker) can use to interact
+// with a relay server that will pay the Ethereum gas fees needed to receive an Ethereum
+// asset in exchange for Monero.
 package relayer
 
 import (
diff --git a/rpc/server.go b/rpc/server.go
index 0740d43a..efa25b66 100644
--- a/rpc/server.go
+++ b/rpc/server.go
@@ -1,3 +1,6 @@
+// Package rpc provides the HTTP server for incoming JSON-RPC and websocket requests to
+// swapd from the local host. The answers to these queries come from 3 subsystems: net,
+// personal and swap.
 package rpc
 
 import (
diff --git a/rpcclient/client.go b/rpcclient/client.go
index b66b2822..6385167f 100644
--- a/rpcclient/client.go
+++ b/rpcclient/client.go
@@ -1,3 +1,5 @@
+// Package rpcclient provides client libraries for interacting with a local swapd instance using
+// the JSON-RPC remote procedure call protocol.
 package rpcclient
 
 import (
diff --git a/rpcclient/wsclient/wsclient.go b/rpcclient/wsclient/wsclient.go
index ba38b94a..ea4d7d03 100644
--- a/rpcclient/wsclient/wsclient.go
+++ b/rpcclient/wsclient/wsclient.go
@@ -1,3 +1,5 @@
+// Package wsclient provides client libraries for interacting with a local swapd instance
+// over web sockets.
 package wsclient
 
 import (
diff --git a/tests/integration_test.go b/tests/integration_test.go
index 9be0bd12..f7050047 100644
--- a/tests/integration_test.go
+++ b/tests/integration_test.go
@@ -1,3 +1,6 @@
+// Package tests provides integration tests, which exercise fully built swapd instances
+// pre-launched by a script. The non *_test.go files are test helper methods for both
+// unit and integration tests.
 package tests
 
 import (