powork

README

PoWork

A simple proof of work library for Golang

This is from bitbucket.org/RyanMarcus/powork originally

** PoWork v0.1 **

PoWork provides a solution-verification based proof of work system that uses a probabilistic iteration method, similar to the ever-popular Hashcash. The library seeks to provide an abstracted interface to users seeking to use proof of work systems.

Full documentation can be found on GoDoc.

You can import it with

import "github.com/Zumium/powork"

To create a proof-of-work:

worker := powork.NewWorker()
messageToProve := "I'll prove I did some work with this very message!"

// proof will contain both the message and the proof of work
proof, _ := worker.DoProofForString(messageToProve)

To verify that proof-of-work:

ok, _ := worker.ValidatePoWork(proof)
if ok {
	fmt.Printf("The proven message is: %v\n", proof.GetMessageString())
}

To change the proof difficulty (default: 10):

// the default is 10. Increases are exponential!
worker.SetDifficulty(15)

// do a harder proof
proof, _ = worker.DoProofForString(messageToProve)

To use a different hash function (default: SHA512):

// use the MD5 hash function (for example)
// the default is SHA512
// you'll need to import MD5 with: import "crypto/md5"
worker.SetHasher(md5.New())

// do a proof with the MD5 hash function
proof, _ = worker.DoProofForString(messageToProve)

To change the default timeout (default: 5 seconds)

// set a new timeout value of 10 seconds (in milliseconds)
worker.SetTimeout(10000)

// now the worker will try for 10 seconds instead of 5
proof, _ = worker.DoProofForString(messageToProve)

You can also use PoWork asynchronously by having PoWork return a channel:

worker := NewWorker()
messageToProve := []byte("This time with channels!")

// returns a channel that will eventually get the proof
recvr := worker.PrepareProof(messageToProve)

// prepare your message here
fmt.Printf("Preparing message...\n")


// wait on the result
res := <- recvr

if res.error != nil {
	t.Fatalf("Error: %v\n", res.error)
}

proof := res.PoWork
// this variable will contain the same thing as the
// proof variables from the other examples

You can also have PoWork send multiple proofs to the same channel:

worker := powork.NewWorker()
messageToProve := []byte("Will send a proof of this message to a channel")

c := powork.GetChannel(20)

worker.SendProofToChannel(messageToProve, c)

// do message preparation business here

res := <- c

if res.error != nil {
	t.Fatalf("Error occurred during proof generation: %v\n", res.error)
}

ok, _ := worker.ValidatePoWork(res.PoWork)
if !ok {
	t.Fatalf("Could not validate message\n")
}

Documentation

Overview

Package powork provides an easy-to-use proof of work library for golang

Index

• func GetChannel(buffer int) ...
• type PoWork
  • func (p *PoWork) GetMessage() []byte
  • func (p *PoWork) GetMessageString() string
• type Worker
  • func NewWorker() *Worker
  • func NewWorkerWithHash(h hash.Hash) *Worker
  • func (p *Worker) DoProofFor(msg []byte) (*PoWork, error)
  • func (p *Worker) DoProofForString(msg string) (*PoWork, error)
  • func (p *Worker) DoProofForStringWithContext(ctx context.Context, msg string) (*PoWork, error)
  • func (p *Worker) DoProofForWithContext(ctx context.Context, msg []byte) (*PoWork, error)
  • func (p *Worker) PrepareProof(msg []byte) ...
  • func (p *Worker) PrepareProofWithContext(ctx context.Context, msg []byte) ...
  • func (p *Worker) SendProofToChannel(msg []byte, c ...)
  • func (p *Worker) SendProofToChannelWithContext(ctx context.Context, msg []byte, c ...)
  • func (p *Worker) SetDifficulty(difficulty int) error
  • func (p *Worker) SetHasher(h hash.Hash)
  • func (p *Worker) SetTimeout(milliseconds int) error
  • func (p *Worker) ValidatePoWork(pow *PoWork) (bool, error)

Functions

func GetChannel

func GetChannel(buffer int) chan struct {
	*PoWork
	error
}

GetChannel returns a channel, with the given buffer, that can be used with SendProofToChannel

Types

type PoWork

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

A PoWork represents a (potentially valid) proof of work for a given message

func (*PoWork) GetMessage

func (p *PoWork) GetMessage() []byte

GetMessage gets the message that the proof of work relates to

func (*PoWork) GetMessageString

func (p *PoWork) GetMessageString() string

GetMessageString simply casts the result of GetMessage to a string

type Worker

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

Worker represents an object that calculates proofs of work and verifies them.

func NewWorker

func NewWorker() *Worker

NewWorker creates a new Worker with sensible defaults: SHA3-512, 10 bit difficulty, and a 5 second timeout.

func NewWorkerWithHash

func NewWorkerWithHash(h hash.Hash) *Worker

NewWorkerWithHash creates a new worker with given hash

func (*Worker) DoProofFor

func (p *Worker) DoProofFor(msg []byte) (*PoWork, error)

DoProofFor calculates a proof of work for a byte slice

func (*Worker) DoProofForString

func (p *Worker) DoProofForString(msg string) (*PoWork, error)

DoProofForString calculates a proof of work for a given string

func (*Worker) DoProofForStringWithContext

func (p *Worker) DoProofForStringWithContext(ctx context.Context, msg string) (*PoWork, error)

DoProofForStringWithContext does the same thing as DoProofForString except carrying a context

func (*Worker) DoProofForWithContext

func (p *Worker) DoProofForWithContext(ctx context.Context, msg []byte) (*PoWork, error)

DoProofForWithContext does the same thing as DoProofFor except carrying a context

func (*Worker) PrepareProof

func (p *Worker) PrepareProof(msg []byte) chan struct {
	*PoWork
	error
}

PrepareProof starts working on creating a proof of work for the passed message and returns immediately.

func (*Worker) PrepareProofWithContext

func (p *Worker) PrepareProofWithContext(ctx context.Context, msg []byte) chan struct {
	*PoWork
	error
}

PrepareProofWithContext does the same thing as PrepareProof except carrying a context

func (*Worker) SendProofToChannel

func (p *Worker) SendProofToChannel(msg []byte, c chan struct {
	*PoWork
	error
})

SendProofToChannel begins computing a proof of work for the given message, and sends it to the passed channel upon completion.

func (*Worker) SendProofToChannelWithContext

func (p *Worker) SendProofToChannelWithContext(ctx context.Context, msg []byte, c chan struct {
	*PoWork
	error
})

SendProofToChannelWithContext does the same thing as SendProofToChannel except carrying a context

func (*Worker) SetDifficulty

func (p *Worker) SetDifficulty(difficulty int) error

SetDifficulty sets the difficulty of the proof calculated. A higher value represents a more difficult proof. Increases exponentially.

func (*Worker) SetHasher

func (p *Worker) SetHasher(h hash.Hash)

SetHasher sets the hash object that the Worker will use

func (*Worker) SetTimeout

func (p *Worker) SetTimeout(milliseconds int) error

SetTimeout sets the amount of time a Worker will spend computing a proof of work before giving up.

func (*Worker) ValidatePoWork

func (p *Worker) ValidatePoWork(pow *PoWork) (bool, error)

ValidatePoWork checks the validity of a proof of work. If the proof is valid, true is returned. Otherwise, false. If true is returned, then the error returned must be nil.