poc

Documentation

Index

• Constants
• Variables
• func EnsureBitLength(bitLength int) bool
• func ValidBitLength() []int
• func VerifyProof(proof *Proof, pubKeyHash pocutil.Hash, challenge pocutil.Hash) error
• type Proof
  • func NewEmptyProof() *Proof
  • func (proof *Proof) Decode(data []byte) error
  • func (proof *Proof) Encode() []byte
  • func (proof *Proof) GetHashVal(slot uint64, height uint64) pocutil.Hash
  • func (proof *Proof) GetQuality(slot, height uint64) *big.Int
  • func (proof *Proof) GetVerifiedQuality(pubKeyHash pocutil.Hash, challenge pocutil.Hash, slot, height uint64) (*big.Int, error)

Constants

const (
	// PoCSlot represents the unit Slot of PoC
	PoCSlot = 3

	// KiB represents KiByte
	KiB = 1024

	// MiB represents MiByte
	MiB = 1024 * KiB

	// MinValidBitLength represents smallest BitLength
	MinValidBitLength = 24

	// MaxValidBitLength represents biggest BitLength
	MaxValidBitLength = 40
)

Variables

var (
	// ErrProofDecodeDataSize indicates that the data length of serialized proof is invalid.
	ErrProofDecodeDataSize = errors.New("invalid data length on decode proof")

	// ErrProofInvalidBitLength indicates that the BitLength of Proof is invalid.
	ErrProofInvalidBitLength = errors.New("invalid bitLength")

	// ErrProofInvalidFlipValue indicates that x and x_prime is not matched.
	ErrProofInvalidFlipValue = errors.New("invalid flip value")

	// ErrProofInvalidChallenge indicates that challenge is not matched with proof.
	ErrProofInvalidChallenge = errors.New("invalid challenge")
)

var (
	// BitLengthDiskSize stores the disk size in byte of different BitLengths.
	// int.max is 1<<32 -1 = 4,294,967,295
	//           1<<40 = 1,099,511,627,776
	BitLengthDiskSize map[int]int

	// MinDiskSize represents the disk size in byte of the smallest BitLength.
	MinDiskSize = pocutil.RecordSize(MinValidBitLength) * 2 * (1 << uint(MinValidBitLength))
)

Functions

func EnsureBitLength

func EnsureBitLength(bitLength int) bool

EnsureBitLength returns whether it is a valid bitLength.

func ValidBitLength

func ValidBitLength() []int

ValidBitLength returns a slice of valid BitLength in increasing order.

func VerifyProof

func VerifyProof(proof *Proof, pubKeyHash pocutil.Hash, challenge pocutil.Hash) error

VerifyProof verifies proof: (1) make sure BitLength is Valid. Should be integer even number in [24, 40]. (2) perform function P on x and x_prime, the corresponding result

y and y_prime should be a bit-flip pair.

(3) perform function F on x and x_prime, the result z should

be equal to the bit-length-cut challenge.

It returns nil when proof is verified.

Types

type Proof

type Proof struct {
	X         []byte // 8 bytes
	XPrime    []byte // 8 bytes
	BitLength int    // 4 bytes | save 1 byte
}

Proof represents a single PoC Proof.

func NewEmptyProof

func NewEmptyProof() *Proof

NewEmptyProof returns a new Proof struct.

func (*Proof) Decode

func (proof *Proof) Decode(data []byte) error

Decode decodes proof from a 17-byte slice: +---------+---------+-------------+ | X | XPrime | BitLength | +---------+---------+-------------+ | 8 bytes | 8 bytes | 1 byte | +---------+---------+-------------+ X & XPrime is encoded in little endian

func (*Proof) Encode

func (proof *Proof) Encode() []byte

Encode encodes proof to 17 bytes: +---------+---------+-------------+ | X | XPrime | BitLength | +---------+---------+-------------+ | 8 bytes | 8 bytes | 1 byte | +---------+---------+-------------+ X & XPrime is encoded in little endian

func (*Proof) GetHashVal

func (proof *Proof) GetHashVal(slot uint64, height uint64) pocutil.Hash

GetHashVal returns SHA256(t//s,x,x',height).

func (*Proof) GetQuality

func (proof *Proof) GetQuality(slot, height uint64) *big.Int

GetQuality produces the relative quality of a proof.

Here we define: (1) H: (a hash value) as an (32-byte-big-endian-encoded) integer ranges in 0 ~ 2^256 - 1. (2) SIZE: the volume of record of certain BitLength, which equals to 2^BitLength.

The standard quality is : quality = (H / 2^256) ^ [1 / (SIZE * BitLength)], which means the more space you have, the bigger prob you get to generate a higher quality.

In Sukhavati we use an equivalent quality formula : Quality = (SIZE * BitLength) / [256 - log2(H)], which means the more space you have, the bigger prob you get to generate a higher Quality.

A proof is considered as valid when Quality >= target.

func (*Proof) GetVerifiedQuality

func (proof *Proof) GetVerifiedQuality(pubKeyHash pocutil.Hash, challenge pocutil.Hash, slot, height uint64) (*big.Int, error)

GetVerifiedQuality verifies the proof and then calculates its quality.