go-cid: github.com/ipfs/go-cid Index | Examples | Files

package cid

import "github.com/ipfs/go-cid"

Package cid implements the Content-IDentifiers specification (https://github.com/ipld/cid) in Go. CIDs are self-describing content-addressed identifiers useful for distributed information systems. CIDs are used in the IPFS (https://ipfs.io) project ecosystem.

CIDs have two major versions. A CIDv0 corresponds to a multihash of type DagProtobuf, is deprecated and exists for compatibility reasons. Usually, CIDv1 should be used.

A CIDv1 has four parts: 

<cidv1> ::= <multibase-prefix><cid-version><multicodec-packed-content-type><multihash-content-address>

As shown above, the CID implementation relies heavily on Multiformats, particularly Multibase (https://github.com/multiformats/go-multibase), Multicodec (https://github.com/multiformats/multicodec) and Multihash implementations (https://github.com/multiformats/go-multihash).

Index

Examples

Package Files

builder.go cid.go deprecated.go set.go varint.go

Constants

❖
const (
    Raw = 0x55

    DagProtobuf = 0x70
    DagCBOR     = 0x71
    Libp2pKey   = 0x72

    GitRaw = 0x78

    EthBlock           = 0x90
    EthBlockList       = 0x91
    EthTxTrie          = 0x92
    EthTx              = 0x93
    EthTxReceiptTrie   = 0x94
    EthTxReceipt       = 0x95
    EthStateTrie       = 0x96
    EthAccountSnapshot = 0x97
    EthStorageTrie     = 0x98
    BitcoinBlock       = 0xb0
    BitcoinTx          = 0xb1
    ZcashBlock         = 0xc0
    ZcashTx            = 0xc1
    DecredBlock        = 0xe0
    DecredTx           = 0xe1
    DashBlock          = 0xf0
    DashTx             = 0xf1
)

These are multicodec-packed content types. The should match the codes described in the authoritative document: https://github.com/multiformats/multicodec/blob/master/table.csv

❖
const UnsupportedVersionString = "<unsupported cid version>"

UnsupportedVersionString just holds an error message

Variables

❖
var (
    // ErrVarintBuffSmall means that a buffer passed to the cid parser was not
    // long enough, or did not contain an invalid cid
    ErrVarintBuffSmall = errors.New("reading varint: buffer too small")

    // ErrVarintTooBig means that the varint in the given cid was above the
    // limit of 2^64
    ErrVarintTooBig = errors.New("reading varint: varint bigger than 64bits" +
        " and not supported")

    // ErrCidTooShort means that the cid passed to decode was not long
    // enough to be a valid Cid
    ErrCidTooShort = errors.New("cid too short")

    // ErrInvalidEncoding means that selected encoding is not supported
    // by this Cid version
    ErrInvalidEncoding = errors.New("invalid base encoding")
)
❖
var CodecToStr = map[uint64]string{
    Raw:                "raw",
    DagProtobuf:        "protobuf",
    DagCBOR:            "cbor",
    GitRaw:             "git-raw",
    EthBlock:           "eth-block",
    EthBlockList:       "eth-block-list",
    EthTxTrie:          "eth-tx-trie",
    EthTx:              "eth-tx",
    EthTxReceiptTrie:   "eth-tx-receipt-trie",
    EthTxReceipt:       "eth-tx-receipt",
    EthStateTrie:       "eth-state-trie",
    EthAccountSnapshot: "eth-account-snapshot",
    EthStorageTrie:     "eth-storage-trie",
    BitcoinBlock:       "bitcoin-block",
    BitcoinTx:          "bitcoin-tx",
    ZcashBlock:         "zcash-block",
    ZcashTx:            "zcash-tx",
    DecredBlock:        "decred-block",
    DecredTx:           "decred-tx",
    DashBlock:          "dash-block",
    DashTx:             "dash-tx",
}

CodecToStr maps the numeric codec to its name

❖
var Codecs = map[string]uint64{
    "v0":                   DagProtobuf,
    "raw":                  Raw,
    "protobuf":             DagProtobuf,
    "cbor":                 DagCBOR,
    "libp2p-key":           Libp2pKey,
    "git-raw":              GitRaw,
    "eth-block":            EthBlock,
    "eth-block-list":       EthBlockList,
    "eth-tx-trie":          EthTxTrie,
    "eth-tx":               EthTx,
    "eth-tx-receipt-trie":  EthTxReceiptTrie,
    "eth-tx-receipt":       EthTxReceipt,
    "eth-state-trie":       EthStateTrie,
    "eth-account-snapshot": EthAccountSnapshot,
    "eth-storage-trie":     EthStorageTrie,
    "bitcoin-block":        BitcoinBlock,
    "bitcoin-tx":           BitcoinTx,
    "zcash-block":          ZcashBlock,
    "zcash-tx":             ZcashTx,
    "decred-block":         DecredBlock,
    "decred-tx":            DecredTx,
    "dash-block":           DashBlock,
    "dash-tx":              DashTx,
}

Codecs maps the name of a codec to its type

❖
var Undef = Cid{}

Undef can be used to represent a nil or undefined Cid, using Cid{} directly is also acceptable.

func ExtractEncoding Uses

❖
func ExtractEncoding(v string) (mbase.Encoding, error)

Extract the encoding from a Cid. If Decode on the same string did not return an error neither will this function.

type Builder Uses

❖
type Builder interface {
    Sum(data []byte) (Cid, error)
    GetCodec() uint64
    WithCodec(uint64) Builder
}

type Cid Uses

❖
type Cid struct {
    // contains filtered or unexported fields
}

Cid represents a self-describing content addressed identifier. It is formed by a Version, a Codec (which indicates a multicodec-packed content type) and a Multihash.

func Cast Uses

❖
func Cast(data []byte) (Cid, error)

Cast takes a Cid data slice, parses it and returns a Cid. For CidV1, the data buffer is in the form: 

<version><codec-type><multihash>

CidV0 are also supported. In particular, data buffers starting with length 34 bytes, which starts with bytes [18,32...] are considered binary multihashes.

Please use decode when parsing a regular Cid string, as Cast does not expect multibase-encoded data. Cast accepts the output of Cid.Bytes().

func CidFromBytes Uses

❖
func CidFromBytes(data []byte) (int, Cid, error)

func Decode Uses

❖
func Decode(v string) (Cid, error)

Decode parses a Cid-encoded string and returns a Cid object. For CidV1, a Cid-encoded string is primarily a multibase string: 

<multibase-type-code><base-encoded-string>

The base-encoded string represents a:

<version><codec-type><multihash>

Decode will also detect and parse CidV0 strings. Strings starting with "Qm" are considered CidV0 and treated directly as B58-encoded multihashes.

Example

Code: 

encoded := "bafkreie5qrjvaw64n4tjm6hbnm7fnqvcssfed4whsjqxzslbd3jwhsk3mm"
c, err := Decode(encoded)
if err != nil {
    fmt.Printf("Error: %s", err)
    return
}

fmt.Println(c)

Output:

bafkreie5qrjvaw64n4tjm6hbnm7fnqvcssfed4whsjqxzslbd3jwhsk3mm

func NewCidV0 Uses

❖
func NewCidV0(mhash mh.Multihash) Cid

NewCidV0 returns a Cid-wrapped multihash. They exist to allow IPFS to work with Cids while keeping compatibility with the plain-multihash format used used in IPFS. NewCidV1 should be used preferentially.

Panics if the multihash isn't sha2-256.

func NewCidV1 Uses

❖
func NewCidV1(codecType uint64, mhash mh.Multihash) Cid

NewCidV1 returns a new Cid using the given multicodec-packed content type.

Panics if the multihash is invalid.

func Parse Uses

❖
func Parse(v interface{}) (Cid, error)

Parse is a short-hand function to perform Decode, Cast etc... on a generic interface{} type.

func (Cid) Bytes Uses

❖
func (c Cid) Bytes() []byte

Bytes returns the byte representation of a Cid. The output of bytes can be parsed back into a Cid with Cast().

func (Cid) Defined Uses

❖
func (c Cid) Defined() bool

Defined returns true if a Cid is defined Calling any other methods on an undefined Cid will result in undefined behavior.

func (Cid) Encode Uses

❖
func (c Cid) Encode(base mbase.Encoder) string

Encode return the string representation of a Cid in a given base when applicable. Version 0 Cid's are always in Base58 as they do not take a multibase prefix.

func (Cid) Equals Uses

❖
func (c Cid) Equals(o Cid) bool

Equals checks that two Cids are the same. In order for two Cids to be considered equal, the Version, the Codec and the Multihash must match.

func (Cid) Hash Uses

❖
func (c Cid) Hash() mh.Multihash

Hash returns the multihash contained by a Cid.

func (Cid) KeyString Uses

❖
func (c Cid) KeyString() string

KeyString returns the binary representation of the Cid as a string

func (Cid) Loggable Uses

❖
func (c Cid) Loggable() map[string]interface{}

Loggable returns a Loggable (as defined by https://godoc.org/github.com/ipfs/go-log).

func (Cid) MarshalBinary Uses

❖
func (c Cid) MarshalBinary() ([]byte, error)

MarshalBinary is equivalent to Bytes(). It implements the encoding.BinaryMarshaler interface.

func (Cid) MarshalJSON Uses

❖
func (c Cid) MarshalJSON() ([]byte, error)

MarshalJSON procudes a JSON representation of a Cid, which looks as follows: 

{ "/": "<cid-string>" }

Note that this formatting comes from the IPLD specification (https://github.com/ipld/specs/tree/master/ipld)

func (Cid) MarshalText Uses

❖
func (c Cid) MarshalText() ([]byte, error)

MarshalText is equivalent to String(). It implements the encoding.TextMarshaler interface.

func (Cid) Prefix Uses

❖
func (c Cid) Prefix() Prefix

Prefix builds and returns a Prefix out of a Cid.

func (Cid) String Uses

❖
func (c Cid) String() string

String returns the default string representation of a Cid. Currently, Base58 is used as the encoding for the multibase string.

func (Cid) StringOfBase Uses

❖
func (c Cid) StringOfBase(base mbase.Encoding) (string, error)

String returns the string representation of a Cid encoded is selected base

func (Cid) Type Uses

❖
func (c Cid) Type() uint64

Type returns the multicodec-packed content type of a Cid.

func (*Cid) UnmarshalBinary Uses

❖
func (c *Cid) UnmarshalBinary(data []byte) error

UnmarshalBinary is equivalent to Cast(). It implements the encoding.BinaryUnmarshaler interface.

func (*Cid) UnmarshalJSON Uses

❖
func (c *Cid) UnmarshalJSON(b []byte) error

UnmarshalJSON parses the JSON representation of a Cid.

func (*Cid) UnmarshalText Uses

❖
func (c *Cid) UnmarshalText(text []byte) error

UnmarshalText is equivalent to Decode(). It implements the encoding.TextUnmarshaler interface.

func (Cid) Version Uses

❖
func (c Cid) Version() uint64

Version returns the Cid version.

type Prefix Uses

❖
type Prefix struct {
    Version  uint64
    Codec    uint64
    MhType   uint64
    MhLength int
}

Prefix represents all the metadata of a Cid, that is, the Version, the Codec, the Multihash type and the Multihash length. It does not contains any actual content information. NOTE: The use -1 in MhLength to mean default length is deprecated, 

use the V0Builder or V1Builder structures instead

func NewPrefixV0 Uses

❖
func NewPrefixV0(mhType uint64) Prefix

NewPrefixV0 returns a CIDv0 prefix with the specified multihash type. DEPRECATED: Use V0Builder

func NewPrefixV1 Uses

❖
func NewPrefixV1(codecType uint64, mhType uint64) Prefix

NewPrefixV1 returns a CIDv1 prefix with the specified codec and multihash type. DEPRECATED: Use V1Builder

func PrefixFromBytes Uses

❖
func PrefixFromBytes(buf []byte) (Prefix, error)

PrefixFromBytes parses a Prefix-byte representation onto a Prefix.

func (Prefix) Bytes Uses

❖
func (p Prefix) Bytes() []byte

Bytes returns a byte representation of a Prefix. It looks like: 

<version><codec><mh-type><mh-length>

func (Prefix) GetCodec Uses

❖
func (p Prefix) GetCodec() uint64

func (Prefix) Sum Uses

❖
func (p Prefix) Sum(data []byte) (Cid, error)

Sum uses the information in a prefix to perform a multihash.Sum() and return a newly constructed Cid with the resulting multihash.

func (Prefix) WithCodec Uses

❖
func (p Prefix) WithCodec(c uint64) Builder

type Set Uses

❖
type Set struct {
    // contains filtered or unexported fields
}

Set is a implementation of a set of Cids, that is, a structure to which holds a single copy of every Cids that is added to it.

func NewSet Uses

❖
func NewSet() *Set

NewSet initializes and returns a new Set.

func (*Set) Add Uses

❖
func (s *Set) Add(c Cid)

Add puts a Cid in the Set.

func (*Set) ForEach Uses

❖
func (s *Set) ForEach(f func(c Cid) error) error

ForEach allows to run a custom function on each Cid in the set.

func (*Set) Has Uses

❖
func (s *Set) Has(c Cid) bool

Has returns if the Set contains a given Cid.

func (*Set) Keys Uses

❖
func (s *Set) Keys() []Cid

Keys returns the Cids in the set.

func (*Set) Len Uses

❖
func (s *Set) Len() int

Len returns how many elements the Set has.

func (*Set) Remove Uses

❖
func (s *Set) Remove(c Cid)

Remove deletes a Cid from the Set.

func (*Set) Visit Uses

❖
func (s *Set) Visit(c Cid) bool

Visit adds a Cid to the set only if it is not in it already.

type V0Builder Uses

❖
type V0Builder struct{}

func (V0Builder) GetCodec Uses

❖
func (p V0Builder) GetCodec() uint64

func (V0Builder) Sum Uses

❖
func (p V0Builder) Sum(data []byte) (Cid, error)

func (V0Builder) WithCodec Uses

❖
func (p V0Builder) WithCodec(c uint64) Builder

type V1Builder Uses

❖
type V1Builder struct {
    Codec    uint64
    MhType   uint64
    MhLength int // MhLength <= 0 means the default length
}

func (V1Builder) GetCodec Uses

❖
func (p V1Builder) GetCodec() uint64

func (V1Builder) Sum Uses

❖
func (p V1Builder) Sum(data []byte) (Cid, error)

func (V1Builder) WithCodec Uses

❖
func (p V1Builder) WithCodec(c uint64) Builder

Package cid imports 9 packages (graph) and is imported by 548 packages. Updated 2019-12-09. Refresh now. Tools for package owners.