penguin

Documentation

Overview

Package penguin contains most basic and general Penguin concepts.

Index

• Constants
• Variables
• func Distance(x, y []byte) (*big.Int, error)
• func DistanceCmp(a, x, y []byte) (int, error)
• func DistanceRaw(x, y []byte) ([]byte, error)
• func ExtendedProximity(one, other []byte) (ret uint8)
• func Proximity(one, other []byte) (ret uint8)
• type Address
  • func MustParseHexAddress(s string) Address
  • func NewAddress(b []byte) Address
  • func ParseHexAddress(s string) (a Address, err error)
  • func (a Address) ByteString() string
  • func (a Address) Bytes() []byte
  • func (a Address) Equal(b Address) bool
  • func (a Address) IsZero() bool
  • func (a Address) MarshalJSON() ([]byte, error)
  • func (a Address) MemberOf(addrs []Address) bool
  • func (a Address) String() string
  • func (a *Address) UnmarshalJSON(b []byte) (err error)
• type AddressIterFunc
• type Chunk
  • func NewChunk(addr Address, data []byte) Chunk
• type Stamp

Constants

const (
	SpanSize                = 8
	SectionSize             = 32
	Branches                = 128
	EncryptedBranches       = Branches / 2
	BmtBranches             = 128
	ChunkSize               = SectionSize * Branches
	HashSize                = 32
	MaxPO             uint8 = 31
	ExtendedPO        uint8 = MaxPO + 5
	MaxBins                 = MaxPO + 1
	ChunkWithSpanSize       = ChunkSize + SpanSize
)

Variables

var (
	ErrInvalidChunk = errors.New("invalid chunk")
)

var (
	NewHasher = sha3.NewLegacyKeccak256
)

var ZeroAddress = NewAddress(nil)

ZeroAddress is the address that has no value.

Functions

func Distance

func Distance(x, y []byte) (*big.Int, error)

Distance returns the distance between address x and address y as a (comparable) big integer using the distance metric defined in the penguin specification. Fails if not all addresses are of equal length.

func DistanceCmp

func DistanceCmp(a, x, y []byte) (int, error)

DistanceCmp compares x and y to a in terms of the distance metric defined in the penguin specfication. it returns:

1 if x is closer to a than y
0 if x and y are equally far apart from a (this means that x and y are the same address)
-1 if x is farther from a than y

Fails if not all addresses are of equal length.

func DistanceRaw

func DistanceRaw(x, y []byte) ([]byte, error)

DistanceRaw returns the distance between address x and address y in big-endian binary format using the distance metric defined in the penguin specfication. Fails if not all addresses are of equal length.

func ExtendedProximity

func ExtendedProximity(one, other []byte) (ret uint8)

func Proximity

func Proximity(one, other []byte) (ret uint8)

Proximity returns the proximity order of the MSB distance between x and y

The distance metric MSB(x, y) of two equal length byte sequences x an y is the value of the binary integer cast of the x^y, ie., x and y bitwise xor-ed. the binary cast is big endian: most significant bit first (=MSB).

Proximity(x, y) is a discrete logarithmic scaling of the MSB distance. It is defined as the reverse rank of the integer part of the base 2 logarithm of the distance. It is calculated by counting the number of common leading zeros in the (MSB) binary representation of the x^y.

(0 farthest, 255 closest, 256 self)

Types

type Address

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

Address represents an address in Penguin metric space of Node and Chunk addresses.

func MustParseHexAddress

func MustParseHexAddress(s string) Address

MustParseHexAddress returns an Address from a hex-encoded string representation, and panics if there is a parse error.

func NewAddress

func NewAddress(b []byte) Address

NewAddress constructs Address from a byte slice.

func ParseHexAddress

func ParseHexAddress(s string) (a Address, err error)

ParseHexAddress returns an Address from a hex-encoded string representation.

func (Address) ByteString

func (a Address) ByteString() string

ByteString returns raw Address string without encoding.

func (Address) Bytes

func (a Address) Bytes() []byte

Bytes returns bytes representation of the Address.

func (Address) Equal

func (a Address) Equal(b Address) bool

Equal returns true if two addresses are identical.

func (Address) IsZero

func (a Address) IsZero() bool

IsZero returns true if the Address is not set to any value.

func (Address) MarshalJSON

func (a Address) MarshalJSON() ([]byte, error)

MarshalJSON returns JSON-encoded representation of Address.

func (Address) MemberOf

func (a Address) MemberOf(addrs []Address) bool

MemberOf returns true if the address is a member of the provided set.

func (Address) String

func (a Address) String() string

String returns a hex-encoded representation of the Address.

func (*Address) UnmarshalJSON

func (a *Address) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON sets Address to a value from JSON-encoded representation.

type AddressIterFunc

type AddressIterFunc func(address Address) error

AddressIterFunc is a callback on every address that is found by the iterator.

type Chunk

type Chunk interface {
	// Address returns the chunk address.
	Address() Address
	// Data returns the chunk data.
	Data() []byte
	// TagID returns the tag ID for this chunk.
	TagID() uint32
	// WithTagID attaches the tag ID to the chunk.
	WithTagID(t uint32) Chunk
	// Stamp returns the postage stamp associated with this chunk.
	Stamp() Stamp
	// WithStamp attaches a postage stamp to the chunk.
	WithStamp(Stamp) Chunk
	// Radius is the PO above which the batch is preserved.
	Radius() uint8
	// Depth returns the batch depth of the stamp - allowed batch size = 2^{depth}.
	Depth() uint8
	// WithBatch attaches batch parameters to the chunk.
	WithBatch(radius, depth uint8) Chunk
	// Equal checks if the chunk is equal to another.
	Equal(Chunk) bool
}

func NewChunk

func NewChunk(addr Address, data []byte) Chunk

type Stamp

type Stamp interface {
	BatchID() []byte
	Sig() []byte
	encoding.BinaryMarshaler
	encoding.BinaryUnmarshaler
}

Stamp interface for postage.Stamp to avoid circular dependency