address

README

go-address

The filecoin address type, used for identifying actors on the filecoin network, in various formats.

Install

Install this library with go mod

Usage

Addresses support various types of encoding formats and have constructors for each format

// address from ID
idAddress := NewIDAddress(id)
// address from a secp pub key
secp256k1Address := NewSecp256k1Address(pubkey)
// address from data for actor protocol
actorAddress := NewActorAddress(data) 
// address from the BLS pubkey
blsAddress := NewBLSAddress(pubkey)

Serialization

var outBuf io.writer
err := address.MarshalCBOR(outbuf)
var inBuf io.reader
err := address.UnmarshalCBOR(inbuf)

Project-level documentation

The filecoin-project has a community repo that documents in more detail our policies and guidelines, such as discussion forums and chat rooms and Code of Conduct.

License

This repository is dual-licensed under Apache 2.0 and MIT terms.

Copyright 2019. Protocol Labs, Inc.

Documentation

Index

• Constants
• Variables
• func Checksum(ingest []byte) []byte
• func IDFromAddress(addr Address) (uint64, error)
• func NewForTestGetter() func() Address
• func ValidateChecksum(ingest, expect []byte) bool
• type Address
  • func NewActorAddress(data []byte) (Address, error)
  • func NewBLSAddress(pubkey []byte) (Address, error)
  • func NewDelegatedAddress(namespace uint64, subaddr []byte) (Address, error)
  • func NewFromBytes(addr []byte) (Address, error)
  • func NewFromString(addr string) (Address, error)
  • func NewIDAddress(id uint64) (Address, error)
  • func NewSecp256k1Address(pubkey []byte) (Address, error)
  • func (a Address) Bytes() []byte
  • func (a Address) Empty() bool
  • func (a Address) Marshal() ([]byte, error)
  • func (a Address) MarshalBinary() ([]byte, error)
  • func (a *Address) MarshalCBOR(w io.Writer) error
  • func (a Address) MarshalJSON() ([]byte, error)
  • func (a Address) Payload() []byte
  • func (a Address) Protocol() Protocol
  • func (a *Address) Scan(value interface{}) error
  • func (a Address) String() string
  • func (a Address) Unmarshal(b []byte) error
  • func (a *Address) UnmarshalBinary(b []byte) error
  • func (a *Address) UnmarshalCBOR(r io.Reader) error
  • func (a *Address) UnmarshalJSON(b []byte) error
• type Network
• type Protocol

Constants

const BlsPrivateKeyBytes = 32

BlsPrivateKeyBytes is the length of a BLS private key

const BlsPublicKeyBytes = 48

BlsPublicKeyBytes is the length of a BLS public key

const ChecksumHashLength = 4

ChecksumHashLength defines the hash length used for calculating address checksums.

const MainnetPrefix = "f"

MainnetPrefix is the main network prefix.

const MaxAddressStringLength = 2 + MaxInt64StringLength + 1 + 93

MaxAddressStringLength is the max length of an address encoded as a string (115).

const MaxInt64StringLength = 19

MaxInt64StringLength defines the maximum length of `int64` as a string.

const MaxSubaddressLen = 54

MaxSubaddressLen is the maximum length of a delegated address's sub-address.

const PayloadHashLength = 20

PayloadHashLength defines the hash length taken over addresses using the Actor and SECP256K1 protocols.

const TestnetPrefix = "t"

TestnetPrefix is the test network prefix.

Variables

var (
	// ErrUnknownNetwork is returned when encountering an unknown network in an address.
	ErrUnknownNetwork = errors.New("unknown address network")

	// ErrUnknownProtocol is returned when encountering an unknown protocol in an address.
	ErrUnknownProtocol = errors.New("unknown address protocol")
	// ErrInvalidPayload is returned when encountering an invalid address payload.
	ErrInvalidPayload = errors.New("invalid address payload")
	// ErrInvalidLength is returned when encountering an address of invalid length.
	ErrInvalidLength = errors.New("invalid address length")
	// ErrInvalidChecksum is returned when encountering an invalid address checksum.
	ErrInvalidChecksum = errors.New("invalid address checksum")
	// ErrInvalidEncoding is returned when encountering a non-standard encoding of an address.
	ErrInvalidEncoding = errors.New("invalid encoding")
)

var AddressEncoding = base32.NewEncoding(encodeStd)

AddressEncoding defines the base32 config used for address encoding and decoding.

var CurrentNetwork = Testnet

CurrentNetwork specifies which network the address belongs to

var Undef = Address{}

Undef is the type that represents an undefined address.

var UndefAddressString = "<empty>"

UndefAddressString is the string used to represent an empty address when encoded to a string.

Functions

func Checksum

func Checksum(ingest []byte) []byte

Checksum returns the checksum of `ingest`.

func IDFromAddress

func IDFromAddress(addr Address) (uint64, error)

func NewForTestGetter

func NewForTestGetter() func() Address

NewForTestGetter returns a closure that returns an address unique to that invocation. The address is unique wrt the closure returned, not globally.

func ValidateChecksum

func ValidateChecksum(ingest, expect []byte) bool

ValidateChecksum returns true if the checksum of `ingest` is equal to `expected`>

Types

type Address

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

Address is the go type that represents an address in the filecoin network.

var (
	// TestAddress is an account with some initial funds in it.
	TestAddress Address
	// TestAddress2 is an account with some initial funds in it.
	TestAddress2 Address
)

func NewActorAddress

func NewActorAddress(data []byte) (Address, error)

NewActorAddress returns an address using the Actor protocol.

func NewBLSAddress

func NewBLSAddress(pubkey []byte) (Address, error)

NewBLSAddress returns an address using the BLS protocol.

func NewDelegatedAddress

func NewDelegatedAddress(namespace uint64, subaddr []byte) (Address, error)

NewDelegatedAddress returns an address using the Delegated protocol.

func NewFromBytes

func NewFromBytes(addr []byte) (Address, error)

NewFromBytes return the address represented by the bytes `addr`.

func NewFromString

func NewFromString(addr string) (Address, error)

NewFromString returns the address represented by the string `addr`.

func NewIDAddress

func NewIDAddress(id uint64) (Address, error)

NewIDAddress returns an address using the ID protocol.

func NewSecp256k1Address

func NewSecp256k1Address(pubkey []byte) (Address, error)

NewSecp256k1Address returns an address using the SECP256K1 protocol.

func (Address) Bytes

func (a Address) Bytes() []byte

Bytes returns the address as bytes.

func (Address) Empty

func (a Address) Empty() bool

Empty returns true if the address is empty, false otherwise.

func (Address) Marshal

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

Marshal marshals the address to cbor.

func (Address) MarshalBinary

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

func (*Address) MarshalCBOR

func (a *Address) MarshalCBOR(w io.Writer) error

func (Address) MarshalJSON

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

MarshalJSON implements the json marshal interface.

func (Address) Payload

func (a Address) Payload() []byte

Payload returns the payload of the address.

func (Address) Protocol

func (a Address) Protocol() Protocol

Protocol returns the protocol used by the address.

func (*Address) Scan

func (a *Address) Scan(value interface{}) error

func (Address) String

func (a Address) String() string

String returns an address encoded as a string.

func (Address) Unmarshal

func (a Address) Unmarshal(b []byte) error

Unmarshal unmarshals the cbor bytes into the address.

func (*Address) UnmarshalBinary

func (a *Address) UnmarshalBinary(b []byte) error

func (*Address) UnmarshalCBOR

func (a *Address) UnmarshalCBOR(r io.Reader) error

func (*Address) UnmarshalJSON

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

UnmarshalJSON implements the json unmarshal interface.

type Network

type Network = byte

Network represents which network an address belongs to.

const (
	// Mainnet is the main network.
	Mainnet Network = iota
	// Testnet is the test network.
	Testnet
)

type Protocol

type Protocol = byte

Protocol represents which protocol an address uses.

const (
	// ID represents the address ID protocol.
	ID Protocol = iota
	// SECP256K1 represents the address SECP256K1 protocol.
	SECP256K1
	// Actor represents the address Actor protocol.
	Actor
	// BLS represents the address BLS protocol.
	BLS
	// Delegated represents the delegated (f4) address protocol.
	Delegated

	Unknown = Protocol(255)
)