pow

README

go-pow

go-pow is a simple Go package to add (asymmetric) Proof of Work to your service.

To create a Proof-of-Work request (with difficulty 5), use pow.NewRequest:

req := pow.NewRequest(5, someRandomNonce)

This returns a string like sha2bday-5-c29tZSByYW5kb20gbm9uY2U, which can be passed on to the client. The client fulfils the proof of work by running pow.Fulfil:

proof, _ := pow.Fulfil(req, []byte("some bound data"))

The client returns the proof (in this case AAAAAAAAAAMAAAAAAAAADgAAAAAAAAAb) to the server, which can check it is indeed a valid proof of work, by running:

ok, _ := pow.Check(req, proof, []byte("some bound data"))

Notes

1. There should be at least sufficient randomness in either the nonce passed to NewRequest or the data passed to Fulfil and Check. Thus it is fine to use the same bound data for every client, if every client get a different nonce in its proof-of-work request. It is also fine to use the same nonce in the proof-of-work request, if every client is (by the encapsulating protocol) forced to use different bound data.

2. The work to fulfil a request scales exponentially in the difficulty parameter. The work to check it proof is correct remains constant:

   Check on Difficulty=5  	  500000	      2544 ns/op
   Check on Difficulty=10 	  500000	      2561 ns/op
   Check on Difficulty=15 	  500000	      2549 ns/op
   Check on Difficulty=20 	  500000	      2525 ns/op
   Fulfil on Difficulty=5  	  100000	     15725 ns/op
   Fulfil on Difficulty=10 	   30000	     46808 ns/op
   Fulfil on Difficulty=15 	    2000	    955606 ns/op
   Fulfil on Difficulty=20 	     200	   6887722 ns/op
   

To do

• Support for equihash would be nice.
• Port to Python, Java, Javascript, ...
• Parallelize.

Documentation

Overview

Create and fulfill proof of work requests.

Example

// Create a proof of work request with difficulty 5
req := pow.NewRequest(5, []byte("some random nonce"))
fmt.Printf("req:   %s\n", req)

// Fulfil the proof of work
proof, _ := pow.Fulfil(req, []byte("some bound data"))
fmt.Printf("proof: %s\n", proof)

// Check if the proof is correct
ok, _ := pow.Check(req, proof, []byte("some bound data"))
fmt.Printf("check: %v", ok)

Output:

req:   sha2bday-5-c29tZSByYW5kb20gbm9uY2U
proof: AAAAAAAAAAMAAAAAAAAADgAAAAAAAAAb
check: true

Index

• func Check(request, proof string, data []byte) (bool, error)
• func Fulfil(request string, data []byte) (string, error)
• func NewRequest(difficulty uint32, nonce []byte) string
• type Algorithm
• type Proof
  • func (proof *Proof) Check(req Request, data []byte) bool
  • func (proof Proof) MarshalText() ([]byte, error)
  • func (proof *Proof) UnmarshalText(buf []byte) error
• type Request
  • func (req *Request) Fulfil(data []byte) Proof
  • func (req Request) MarshalText() ([]byte, error)
  • func (req *Request) UnmarshalText(buf []byte) error

Examples

• Package

Functions

func Check

func Check(request, proof string, data []byte) (bool, error)

Convenience function to check whether a proof of work is fulfilled

func Fulfil

func Fulfil(request string, data []byte) (string, error)

Convenience function to fulfil the proof of work request

func NewRequest

func NewRequest(difficulty uint32, nonce []byte) string

Convenience function to create a new sha3bday proof-of-work request as a string

Types

type Algorithm

type Algorithm string

const (
	Sha2BDay Algorithm = "sha2bday"
)

type Proof

type Proof struct {
	// contains filtered or unexported fields
}

Represents a completed proof-of-work

func (*Proof) Check

func (proof *Proof) Check(req Request, data []byte) bool

Check whether the proof is ok

func (Proof) MarshalText

func (proof Proof) MarshalText() ([]byte, error)

func (*Proof) UnmarshalText

func (proof *Proof) UnmarshalText(buf []byte) error

type Request

type Request struct {

	// The requested algorithm
	Alg Algorithm

	// The requested difficulty
	Difficulty uint32

	// Nonce to diversify the request
	Nonce []byte
}

Represents a proof-of-work request.

func (*Request) Fulfil

func (req *Request) Fulfil(data []byte) Proof

Fulfil the proof-of-work request.

func (Request) MarshalText

func (req Request) MarshalText() ([]byte, error)

func (*Request) UnmarshalText

func (req *Request) UnmarshalText(buf []byte) error