standardization, error handling, docs updates

Author: nottug

README.md

@@ -1,19 +1,19 @@
 # Proof of Work Algorithms
 
-[![Go Test](https://github.com/sencha-dev/go-pow/actions/workflows/go.yml/badge.svg)](https://github.com/sencha-dev/go-pow/actions/workflows/go.yml)
-[![PkgGoDev](https://pkg.go.dev/badge/github.com/sencha-dev/go-pow)](https://pkg.go.dev/github.com/sencha-dev/go-pow?tab=doc)
+[![Go Test](https://github.com/sencha-dev/powkit/actions/workflows/go.yml/badge.svg)](https://github.com/sencha-dev/powkit/actions/workflows/go.yml)
+[![PkgGoDev](https://pkg.go.dev/badge/github.com/sencha-dev/powkit)](https://pkg.go.dev/github.com/sencha-dev/powkit?tab=doc)
 
 # Overview
 
 *Note: This library is still in active development and is
 subject to breaking changes*
 
-Though there is a wide variety of Proof of Work algorithms, finding the technical details
+Though there are a wide variety of Proof of Work algorithms, finding the technical details
 for the implementations is quite a task. Both Kawpow and Firopow are variations off of ProgPow,
-though finding the exact differences is no easy task. This is meant to be a unified library to
+though finding the exact differences is painful. This is meant to be a unified library to
 make the implementation of existing Proof of Work algorithms easier. 
 
-All DAG-based algorithms only implement a light DAG, which is sufficient for verification
+All DAG-based algorithms only implement a light DAG, which is sufficient for validation
 but not full nodes or miners. For the DAG-based algorithms and verthash, data is cached in `~/.powcache`.
 Ethash will generally be between 40-80Mb per epoch (and generally 3 caches are stored), but verthash
 requires a strict 1.2Gb, so be careful if you're using verthash in memory. At the time of writing, running 
@@ -38,31 +38,21 @@ requires a strict 1.2Gb, so be careful if you're using verthash in memory. At th
 
 # Things to Note
 
-  - There is no validation on hash input sizes - generally it is 32 bytes but it can vary by algorithm. It absolutely *can* panic
-  if the wrong input size is used. I probably should be stricter about this, or at least define what the expectations are, but for 
-  now the best way to check is in the tests.
-  - Most of these algorithms are partially optimized, though there surely could be some improvements. However, that is not the goal since
-  these have never been intended to be used for miners. All of these algorithms far surpass a reasonable threshold for performance and I
+  - Most of these algorithms are partially optimized but I'm sure they could be improvemed. That being said, that will probably never happen
+  since these have never been intended to be used for miner clients. All of these algorithms far surpass a reasonable threshold for performance and I
   have no intention of hypertuning them.
   - Cuckoo Cycle is built specifically for Aeternity. There is a modification of the `sipnode` function in the current version
-  of tromp's cuckoo algorithms that Aeternity does not use (a Nicehash dev gives more details [here](https://forum.aeternity.com/t/support-aeternity-stratum-implementation/3140/6)). It wouldn't be hard to implement other Cuckoo Cycle algorithms (cuckatoo, cuckaroo),
-  there just isn't really a need at this point since Grin is fairly annoying. BlockCypher implements the other algorithms [here](https://github.com/blockcypher/libgrin/tree/master/core/pow).
+  of tromp's cuckoo algorithms that Aeternity does not use (a Nicehash dev gives more details [here](https://forum.aeternity.com/t/support-aeternity-stratum-implementation/3140/6)).
+  - The base ProgPow implementation ("ProgPow094") exists in the `internal/progpow` package.
   - Since ZelHash is such a minor Equihash variant, it is treated as just "twisted Equihash" (in `equihash/`).
   - All testing is done on linux, windows support is hazy at best. 
   - The library assumes the host architecture is little-endian, I'm fairly confident big-endian architectures will not function properly.
-  - The base ProgPow implementation ("ProgPow094") exists in the `internal/progpow` package.
   - As of now, the only other algorithms that are on the list of "maybes" are: [cryptonight](https://github.com/Equim-chan/cryptonight),
-  [randomx](https://git.dero.io/DERO_Foundation/RandomX), X25X, and the full cuckoo suite (cuckatoo, cuckaroo). 
+  [randomx](https://git.dero.io/DERO_Foundation/RandomX), X25X, and the full 
+  cuckoo suite ([cuckatoo, cuckaroo]((https://github.com/blockcypher/libgrin/tree/master/core/pow)). 
 
 # Roadmap
 
-Most profitable Proof of Work chains nowdays use some sort of DAG, and that is almost always the Ethash DAG.
-There are then layers on top of the Ethash DAG like ProgPow, which can be considered both a Proof of Work 
-algorithm and a class of algorithms (Kawpow, Firopow). There isn't really a good way to organize all of these
-into a given structure but even if there was, a new algorithm could appear tomorrow and break that structure.
-powkit takes the approach of allowing most parameters to be varied and will implement new algorithms on an
-as-needed basis.
-
 Currently, though powkit is used in production internally, it probably isn't a good idea to use yourself. The
 API is still in flux and each minor version will probably be breaking. Once we do a v1.0.0 release, the structure
 will probably be pretty set in stone. 

autolykos2/README.md

@@ -1,4 +1 @@
-# Autolykos2
-
-This is a rough version of the Autolykos2 algorithm for Ergo. It is quite fast
-and passes up-to-date test vectors. `Config` is likely to change in the future.
+# Autolykos2

autolykos2/autolykos2.go

@@ -8,35 +8,11 @@ import (
 	"github.com/sencha-dev/powkit/internal/crypto"
 )
 
-/* config */
-
-type Config struct {
-	k                      int
-	n                      int
-	nBase                  uint32
-	increaseStart          uint64
-	increasePeriodForN     uint64
-	nIncreasementHeightMax uint64
-}
-
-func New(k, n int) *Config {
-	cfg := &Config{
-		k:                      k,
-		n:                      n,
-		nBase:                  1 << n,
-		increaseStart:          600 * 1024,
-		increasePeriodForN:     50 * 1024,
-		nIncreasementHeightMax: 4198400,
-	}
-
-	return cfg
-}
-
-func NewErgo() *Config {
-	return New(32, 26)
-}
-
-/* helpers */
+const (
+	increaseStart          = 600 * 1024
+	increasePeriodForN     = 50 * 1024
+	nIncreasementHeightMax = 4198400
+)
 
 func concatBytes(a, b []byte) []byte {
 	c := make([]byte, len(a), len(a)+len(b))
@@ -55,16 +31,14 @@ func generateM(size uint64) []byte {
 	return m
 }
 
-/* algorithm */
-
-func (cfg *Config) calcN(height uint64) uint32 {
-	if height > cfg.nIncreasementHeightMax {
+func calcN(nBase uint32, height uint64) uint32 {
+	if height > nIncreasementHeightMax {
 		return 2143944600
 	}
 
-	n := cfg.nBase
-	if height >= cfg.increaseStart {
-		iters := int((height-cfg.increaseStart)/cfg.increasePeriodForN + 1)
+	var n uint32 = nBase
+	if height >= increaseStart {
+		iters := int((height-increaseStart)/increasePeriodForN + 1)
 		for i := 0; i < iters; i++ {
 			n = (n / 100) * 105
 		}
@@ -73,24 +47,24 @@ func (cfg *Config) calcN(height uint64) uint32 {
 	return n
 }
 
-func (cfg *Config) genIndexes(seed []byte, n uint32) []uint32 {
+func genIndexes(seed []byte, k, n uint32) []uint32 {
 	hash := crypto.Blake2b256(seed)
 	extendedHash := append(hash, hash...)
 
-	indexes := make([]uint32, cfg.k)
+	indexes := make([]uint32, k)
 	for i := range indexes {
 		indexes[i] = binary.BigEndian.Uint32(extendedHash[i:i+4]) % n
 	}
 
 	return indexes
 }
 
-func (cfg *Config) Compute(msg []byte, nonce, height uint64) []byte {
+func compute(k, nBase uint32, msg []byte, nonce, height uint64) []byte {
 	m := generateM(1024)
 	h := convutil.Uint32ToBytes(uint32(height), binary.BigEndian)
 	nonceBytes := convutil.Uint64ToBytes(nonce, binary.BigEndian)
 
-	n := cfg.calcN(height)
+	n := calcN(nBase, height)
 	bigN := new(big.Int).SetUint64(uint64(n))
 
 	fullMsg := concatBytes(msg, nonceBytes)
@@ -101,7 +75,7 @@ func (cfg *Config) Compute(msg []byte, nonce, height uint64) []byte {
 	f := crypto.Blake2b256(concatBytes(i, concatBytes(h, m)))[1:32]
 
 	seed := concatBytes(f, concatBytes(msg, nonceBytes))
-	indexes := cfg.genIndexes(seed, n)
+	indexes := genIndexes(seed, k, n)
 
 	f2 := new(big.Int)
 	for _, index := range indexes {

autolykos2/autolykos2_test.go

@@ -7,51 +7,61 @@ import (
 	"github.com/sencha-dev/powkit/internal/common/testutil"
 )
 
-func TestCalcNErgo(t *testing.T) {
+func TestCalcN(t *testing.T) {
 	tests := []struct {
+		nBase  uint32
 		height uint64
 		value  uint32
 	}{
 		{
+			nBase:  1 << 26,
 			height: 500000,
 			value:  67108864,
 		},
 		{
+			nBase:  1 << 26,
 			height: 600000,
 			value:  67108864,
 		},
 		{
+			nBase:  1 << 26,
 			height: 614400,
 			value:  70464240,
 		},
 		{
+			nBase:  1 << 26,
 			height: 665600,
 			value:  73987410,
 		},
 		{
+			nBase:  1 << 26,
 			height: 700000,
 			value:  73987410,
 		},
 		{
+			nBase:  1 << 26,
 			height: 788400,
 			value:  81571035,
 		},
 		{
+			nBase:  1 << 26,
 			height: 1051200,
 			value:  104107290,
 		},
 		{
+			nBase:  1 << 26,
 			height: 4198400,
 			value:  2143944600,
 		},
 		{
+			nBase:  1 << 26,
 			height: 41984000,
 			value:  2143944600,
 		},
 	}
 
 	for i, tt := range tests {
-		value := NewErgo().calcN(tt.height)
+		value := calcN(tt.nBase, tt.height)
 		if value != tt.value {
 			t.Errorf("failed on %d: have %d, want %d", i, value, tt.value)
 		}
@@ -86,8 +96,10 @@ func TestComputeErgo(t *testing.T) {
 	}
 
 	for i, tt := range tests {
-		result := NewErgo().Compute(tt.msg, tt.nonce, tt.height)
-		if bytes.Compare(result, tt.result) != 0 {
+		result, err := NewErgo().Compute(tt.msg, tt.height, tt.nonce)
+		if err != nil {
+			t.Errorf("failed on %d: %v", i, err)
+		} else if bytes.Compare(result, tt.result) != 0 {
 			t.Errorf("failed on %d: have %x, want %x", i, result, tt.result)
 		}
 	}

autolykos2/client.go

@@ -0,0 +1,33 @@
+package autolykos2
+
+import (
+	"fmt"
+)
+
+type Client struct {
+	k     uint32
+	n     uint32
+	nBase uint32
+}
+
+func New(k, n uint32) *Client {
+	c := &Client{
+		k:     k,
+		n:     n,
+		nBase: 1 << n,
+	}
+
+	return c
+}
+
+func NewErgo() *Client {
+	return New(32, 26)
+}
+
+func (c *Client) Compute(msg []byte, height, nonce uint64) ([]byte, error) {
+	if len(msg) != 32 {
+		return nil, fmt.Errorf("msg must be 32 bytes")
+	}
+
+	return compute(c.k, c.nBase, msg, nonce, height), nil
+}

beamhashiii/client.go

@@ -1,5 +1,9 @@
 package beamhashiii
 
+import (
+	"fmt"
+)
+
 type Client struct {
 	n        uint32
 	k        uint32
@@ -21,5 +25,11 @@ func NewBeam() *Client {
 }
 
 func (c *Client) Verify(header, soln []byte) (bool, error) {
+	if len(header) != 40 {
+		return false, fmt.Errorf("header must be 40 bytes")
+	} else if len(soln) != 104 {
+		return false, fmt.Errorf("soln must be 104 bytes")
+	}
+
 	return verify(c.n, c.k, c.personal, header, soln)
 }

cuckoo/client.go

@@ -3,38 +3,42 @@ package cuckoo
 import (
 	"encoding/base64"
 	"encoding/binary"
+	"fmt"
 
 	"github.com/sencha-dev/powkit/internal/crypto"
 )
 
-type Config struct {
+type Client struct {
 	proofSize int
 	edgeBits  int
 	edgeMask  uint64
 	nodeBits  int
 	nodeMask  uint64
 }
 
-func New(edgeBits, nodeBits, proofSize int) *Config {
-	edgeNum := uint64(1) << edgeBits
-	nodeNum := uint64(1) << nodeBits
-
-	cfg := &Config{
+func New(edgeBits, nodeBits, proofSize int) *Client {
+	c := &Client{
 		proofSize: proofSize,
 		edgeBits:  edgeBits,
-		edgeMask:  edgeNum - 1,
+		edgeMask:  (uint64(1) << edgeBits) - 1,
 		nodeBits:  nodeBits,
-		nodeMask:  nodeNum - 1,
+		nodeMask:  (uint64(1) << nodeBits) - 1,
 	}
 
-	return cfg
+	return c
 }
 
-func NewAeternity() *Config {
+func NewAeternity() *Client {
 	return New(29, 29, 42)
 }
 
-func (cfg *Config) Verify(hash []byte, nonce uint64, sols []uint64) bool {
+func (c *Client) Verify(hash []byte, nonce uint64, sols []uint64) (bool, error) {
+	if len(hash) != 32 {
+		return false, fmt.Errorf("hash must be 32 bytes")
+	} else if len(sols) != 42 {
+		return false, fmt.Errorf("sols must be 42 uint64s")
+	}
+
 	// encode header
 	nonceBytes := make([]uint8, 8)
 	binary.LittleEndian.PutUint64(nonceBytes, nonce)
@@ -51,5 +55,5 @@ func (cfg *Config) Verify(hash []byte, nonce uint64, sols []uint64) bool {
 		binary.LittleEndian.Uint64(h[24:32]),
 	}
 
-	return cfg.verify(keys, sols)
+	return verify(c.proofSize, c.edgeMask, keys, sols)
 }