README

go-cid

GoDoc Coverage Status Travis CI

A package to handle content IDs in Go.

This is an implementation in Go of the CID spec. It is used in go-ipfs and related packages to refer to a typed hunk of data.

Lead Maintainer

Eric Myhre

Table of Contents

Install

go-cid is a standard Go module which can be installed with:

go get github.com/ipfs/go-cid

Usage

Running tests

Run tests with go test from the directory root

go test
Examples
Parsing string input from users
// Create a cid from a marshaled string
c, err := cid.Decode("bafzbeigai3eoy2ccc7ybwjfz5r3rdxqrinwi4rwytly24tdbh6yk7zslrm")
if err != nil {...}

fmt.Println("Got CID: ", c)
Creating a CID from scratch
// Create a cid manually by specifying the 'prefix' parameters
pref := cid.Prefix{
	Version: 1,
	Codec: cid.Raw,
	MhType: mh.SHA2_256,
	MhLength: -1, // default length
}

// And then feed it some data
c, err := pref.Sum([]byte("Hello World!"))
if err != nil {...}

fmt.Println("Created CID: ", c)
Check if two CIDs match
// To test if two cid's are equivalent, be sure to use the 'Equals' method:
if c1.Equals(c2) {
	fmt.Println("These two refer to the same exact data!")
}
Check if some data matches a given CID
// To check if some data matches a given cid, 
// Get your CIDs prefix, and use that to sum the data in question:
other, err := c.Prefix().Sum(mydata)
if err != nil {...}

if !c.Equals(other) {
	fmt.Println("This data is different.")
}

Contribute

PRs are welcome!

Small note: If editing the Readme, please conform to the standard-readme specification.

License

MIT © Jeromy Johnson

Expand ▾ Collapse ▴

Documentation

Overview

    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

    Constants

    View Source
    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
    	FilCommitmentUnsealed = 0xf101
    	FilCommitmentSealed   = 0xf102
    )

      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

      View Source
      const UnsupportedVersionString = "<unsupported cid version>"

        UnsupportedVersionString just holds an error message

        Variables

        View Source
        var (
        	// 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")
        )
        View Source
        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",
        	FilCommitmentUnsealed: "fil-commitment-unsealed",
        	FilCommitmentSealed:   "fil-commitment-sealed",
        }

          CodecToStr maps the numeric codec to its name

          View Source
          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,
          	"fil-commitment-unsealed": FilCommitmentUnsealed,
          	"fil-commitment-sealed":   FilCommitmentSealed,
          }

            Codecs maps the name of a codec to its type

            View Source
            var Undef = Cid{}

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

              Functions

              func ExtractEncoding

              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.

                Types

                type Builder

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

                type Cid

                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

                  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

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

                    func Decode

                    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
                      Output:
                      
                      bafkreie5qrjvaw64n4tjm6hbnm7fnqvcssfed4whsjqxzslbd3jwhsk3mm
                      

                      func NewCidV0

                      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

                        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

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

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

                            func (Cid) ByteLen

                            func (c Cid) ByteLen() int

                              ByteLen returns the length of the CID in bytes. It's equivalent to `len(c.Bytes())`, but works without an allocation, and should therefore be preferred.

                              (See also the WriteTo method for other important operations that work without allocation.)

                              func (Cid) Bytes

                              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

                                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

                                  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

                                    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

                                      func (c Cid) Hash() mh.Multihash

                                        Hash returns the multihash contained by a Cid.

                                        func (Cid) KeyString

                                        func (c Cid) KeyString() string

                                          KeyString returns the binary representation of the Cid as a string

                                          func (Cid) Loggable

                                          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

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

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

                                              func (Cid) MarshalJSON

                                              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

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

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

                                                  func (Cid) Prefix

                                                  func (c Cid) Prefix() Prefix

                                                    Prefix builds and returns a Prefix out of a Cid.

                                                    func (Cid) String

                                                    func (c Cid) String() string

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

                                                      func (Cid) StringOfBase

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

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

                                                        func (Cid) Type

                                                        func (c Cid) Type() uint64

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

                                                          func (*Cid) UnmarshalBinary

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

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

                                                            func (*Cid) UnmarshalJSON

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

                                                              UnmarshalJSON parses the JSON representation of a Cid.

                                                              func (*Cid) UnmarshalText

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

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

                                                                func (Cid) Version

                                                                func (c Cid) Version() uint64

                                                                  Version returns the Cid version.

                                                                  func (Cid) WriteBytes

                                                                  func (c Cid) WriteBytes(w io.Writer) (int, error)

                                                                    WriteBytes writes the CID bytes to the given writer. This method works without incurring any allocation.

                                                                    (See also the ByteLen method for other important operations that work without allocation.)

                                                                    type Prefix

                                                                    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

                                                                      func NewPrefixV0(mhType uint64) Prefix

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

                                                                        func NewPrefixV1

                                                                        func NewPrefixV1(codecType uint64, mhType uint64) Prefix

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

                                                                          func PrefixFromBytes

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

                                                                            PrefixFromBytes parses a Prefix-byte representation onto a Prefix.

                                                                            func (Prefix) Bytes

                                                                            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

                                                                              func (p Prefix) GetCodec() uint64

                                                                              func (Prefix) Sum

                                                                              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

                                                                                func (p Prefix) WithCodec(c uint64) Builder

                                                                                type Set

                                                                                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

                                                                                  func NewSet() *Set

                                                                                    NewSet initializes and returns a new Set.

                                                                                    func (*Set) Add

                                                                                    func (s *Set) Add(c Cid)

                                                                                      Add puts a Cid in the Set.

                                                                                      func (*Set) ForEach

                                                                                      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

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

                                                                                          Has returns if the Set contains a given Cid.

                                                                                          func (*Set) Keys

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

                                                                                            Keys returns the Cids in the set.

                                                                                            func (*Set) Len

                                                                                            func (s *Set) Len() int

                                                                                              Len returns how many elements the Set has.

                                                                                              func (*Set) Remove

                                                                                              func (s *Set) Remove(c Cid)

                                                                                                Remove deletes a Cid from the Set.

                                                                                                func (*Set) Visit

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

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

                                                                                                  type V0Builder

                                                                                                  type V0Builder struct{}

                                                                                                  func (V0Builder) GetCodec

                                                                                                  func (p V0Builder) GetCodec() uint64

                                                                                                  func (V0Builder) Sum

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

                                                                                                  func (V0Builder) WithCodec

                                                                                                  func (p V0Builder) WithCodec(c uint64) Builder

                                                                                                  type V1Builder

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

                                                                                                  func (V1Builder) GetCodec

                                                                                                  func (p V1Builder) GetCodec() uint64

                                                                                                  func (V1Builder) Sum

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

                                                                                                  func (V1Builder) WithCodec

                                                                                                  func (p V1Builder) WithCodec(c uint64) Builder

                                                                                                  Directories

                                                                                                  Path Synopsis
                                                                                                  _rsrch