swarm

Documentation

Overview

Package swarm contains most basic and general Swarm concepts.

Index

• Constants
• Variables
• func ContainsAddress(addrs []Address, a Address) bool
• func ContainsChunkWithAddress(chunks []Chunk, a Address) bool
• func ContainsChunkWithData(chunks []Chunk, d []byte) bool
• func Distance(x, y Address) (*big.Int, error)
• func DistanceCmp(a, x, y Address) (int, error)
• func DistanceRaw(x, y Address) ([]byte, error)
• func ExtendedProximity(one, other []byte) (ret uint8)
• func IndexOfAddress(addrs []Address, a Address) int
• func IndexOfChunkWithAddress(chunks []Chunk, a Address) int
• func Proximity(one, other []byte) (ret uint8)
• func RandBatchID(tb testing.TB) []byte
• type Address
  • func MustParseHexAddress(s string) Address
  • func NewAddress(b []byte) Address
  • func ParseHexAddress(s string) (a Address, err error)
  • func RandAddress(tb testing.TB) Address
  • func RandAddressAt(tb testing.TB, self Address, prox int) Address
  • func RandAddresses(tb testing.TB, count int) []Address
  • func RemoveAddress(addrs []Address, a Address) []Address
  • func (a Address) ByteString() string
  • func (a Address) Bytes() []byte
  • func (a Address) Clone() Address
  • func (x Address) Closer(a Address, y Address) (bool, error)
  • 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
  • func FindStampWithBatchID(stamps []Stamp, batchID []byte) (Stamp, bool)

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
	SocSignatureSize        = 65
	SocMinChunkSize         = HashSize + SocSignatureSize + SpanSize
	SocMaxChunkSize         = SocMinChunkSize + ChunkSize
)

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 ContainsAddress

func ContainsAddress(addrs []Address, a Address) bool

ContainsAddress reports whether a is present in addrs.

func ContainsChunkWithAddress

func ContainsChunkWithAddress(chunks []Chunk, a Address) bool

ContainsChunkWithAddress reports whether Chunk with Address a is present in chunks.

func ContainsChunkWithData

func ContainsChunkWithData(chunks []Chunk, d []byte) bool

ContainsChunkWithAddress reports whether Chunk with data d is present in chunks.

func Distance

func Distance(x, y Address) (*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 swarm specification. Fails if not all addresses are of equal length.

func DistanceCmp

func DistanceCmp(a, x, y Address) (int, error)

DistanceCmp compares x and y to a in terms of the distance metric defined in the swarm specification. 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 Address) ([]byte, error)

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

func ExtendedProximity

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

func IndexOfAddress

func IndexOfAddress(addrs []Address, a Address) int

IndexOfAddress returns the index of the first occurrence of a in addrs, or -1 if not present.

func IndexOfChunkWithAddress

func IndexOfChunkWithAddress(chunks []Chunk, a Address) int

IndexOfChunkWithAddress returns the index of the first occurrence of Chunk with Address a in chunks, or -1 if not present.

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)

func RandBatchID

func RandBatchID(tb testing.TB) []byte

RandBatchID generates a random BatchID.

Types

type Address

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

Address represents an address in Swarm 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 RandAddress

func RandAddress(tb testing.TB) Address

RandAddress generates a random address.

func RandAddressAt

func RandAddressAt(tb testing.TB, self Address, prox int) Address

RandAddressAt generates a random address at proximity order prox relative to address.

func RandAddresses

func RandAddresses(tb testing.TB, count int) []Address

RandAddresses generates slice with a random address.

func RemoveAddress

func RemoveAddress(addrs []Address, a Address) []Address

RemoveAddress removes first occurrence of a in addrs, returning the modified slice.

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) Clone

func (a Address) Clone() Address

Clone returns deep clone of the Address.

func (Address) Closer

func (x Address) Closer(a Address, y Address) (bool, error)

Closer returns if x is closer to a than y

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
	// BucketDepth returns the bucket depth of the batch of the stamp - always < depth.
	BucketDepth() uint8
	// Immutable returns whether the batch is immutable
	Immutable() bool
	// WithBatch attaches batch parameters to the chunk.
	WithBatch(radius, depth, bucketDepth uint8, immutable bool) 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
	Index() []byte
	Sig() []byte
	Timestamp() []byte
	encoding.BinaryMarshaler
	encoding.BinaryUnmarshaler
}

Stamp interface for postage.Stamp to avoid circular dependency

func FindStampWithBatchID

func FindStampWithBatchID(stamps []Stamp, batchID []byte) (Stamp, bool)

FindStampWithBatchID returns the first occurrence of Stamp having the same batchID.