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 ¶
- Constants
- Variables
- func ExtractEncoding(v string) (mbase.Encoding, error)
- type Builder
- type Cid
- func Cast(data []byte) (Cid, error)
- func CidFromBytes(data []byte) (int, Cid, error)
- func CidFromReader(r io.Reader) (int, Cid, error)
- func Decode(v string) (Cid, error)
- func MustParse(v interface{}) Cid
- func NewCidV0(mhash mh.Multihash) Cid
- func NewCidV1(codecType uint64, mhash mh.Multihash) Cid
- func Parse(v interface{}) (Cid, error)
- func (c Cid) ByteLen() int
- func (c Cid) Bytes() []byte
- func (c Cid) Defined() bool
- func (c Cid) Encode(base mbase.Encoder) string
- func (c Cid) Equals(o Cid) bool
- func (c Cid) Hash() mh.Multihash
- func (c Cid) KeyString() string
- func (c Cid) Loggable() map[string]interface{}
- func (c Cid) MarshalBinary() ([]byte, error)
- func (c Cid) MarshalJSON() ([]byte, error)
- func (c Cid) MarshalText() ([]byte, error)
- func (c Cid) Prefix() Prefix
- func (c Cid) String() string
- func (c Cid) StringOfBase(base mbase.Encoding) (string, error)
- func (c Cid) Type() uint64
- func (c *Cid) UnmarshalBinary(data []byte) error
- func (c *Cid) UnmarshalJSON(b []byte) error
- func (c *Cid) UnmarshalText(text []byte) error
- func (c Cid) Version() uint64
- func (c Cid) WriteBytes(w io.Writer) (int, error)
- type Prefix
- type Set
- type V0Builder
- type V1Builder
Examples ¶
Constants ¶
const ( // common ones Raw = 0x55 DagProtobuf = 0x70 // https://ipld.io/docs/codecs/known/dag-pb/ DagCBOR = 0x71 // https://ipld.io/docs/codecs/known/dag-cbor/ DagJSON = 0x0129 // https://ipld.io/docs/codecs/known/dag-json/ Libp2pKey = 0x72 // https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md#peer-ids // other GitRaw = 0x78 DagJOSE = 0x85 // https://ipld.io/specs/codecs/dag-jose/spec/ 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 )
Consts below are DEPRECATED and left only for legacy reasons: <https://github.com/ipfs/go-cid/pull/137> Modern code should use consts from go-multicodec instead: <https://github.com/multiformats/go-multicodec>
const UnsupportedVersionString = "<unsupported cid version>"
UnsupportedVersionString just holds an error message
Variables ¶
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") )
var Undef = Cid{}
Undef can be used to represent a nil or undefined Cid, using Cid{} directly is also acceptable.
Functions ¶
Types ¶
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 ¶
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 CidFromReader ¶
CidFromReader reads a precise number of bytes for a CID from a given reader. It returns the number of bytes read, the CID, and any error encountered. The number of bytes read is accurate even if a non-nil error is returned.
It's recommended to supply a reader that buffers and implements io.ByteReader, as CidFromReader has to do many single-byte reads to decode varints. If the argument only implements io.Reader, single-byte Read calls are used instead.
func Decode ¶
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 ¶
encoded := "bafkreie5qrjvaw64n4tjm6hbnm7fnqvcssfed4whsjqxzslbd3jwhsk3mm" c, err := Decode(encoded) if err != nil { fmt.Printf("Error: %s", err) return } fmt.Println(c)
Output: bafkreie5qrjvaw64n4tjm6hbnm7fnqvcssfed4whsjqxzslbd3jwhsk3mm
func NewCidV0 ¶
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 ¶
NewCidV1 returns a new Cid using the given multicodec-packed content type.
Panics if the multihash is invalid.
func Parse ¶
Parse is a short-hand function to perform Decode, Cast etc... on a generic interface{} type.
func (Cid) ByteLen ¶
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 ¶
Bytes returns the byte representation of a Cid. The output of bytes can be parsed back into a Cid with Cast().
If c.Defined() == false, it return a nil slice and may not be parsable with Cast().
func (Cid) Defined ¶
Defined returns true if a Cid is defined Calling any other methods on an undefined Cid will result in undefined behavior.
func (Cid) Encode ¶
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 ¶
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) Loggable ¶
Loggable returns a Loggable (as defined by https://godoc.org/github.com/ipfs/go-log).
func (Cid) MarshalBinary ¶
MarshalBinary is equivalent to Bytes(). It implements the encoding.BinaryMarshaler interface.
func (Cid) MarshalJSON ¶
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 ¶
MarshalText is equivalent to String(). It implements the encoding.TextMarshaler interface.
func (Cid) 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 ¶
String returns the string representation of a Cid encoded is selected base
func (*Cid) UnmarshalBinary ¶
UnmarshalBinary is equivalent to Cast(). It implements the encoding.BinaryUnmarshaler interface.
func (*Cid) UnmarshalJSON ¶
UnmarshalJSON parses the JSON representation of a Cid.
func (*Cid) UnmarshalText ¶
UnmarshalText is equivalent to Decode(). It implements the encoding.TextUnmarshaler interface.
type Prefix ¶
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 ¶
NewPrefixV0 returns a CIDv0 prefix with the specified multihash type. DEPRECATED: Use V0Builder
func NewPrefixV1 ¶
NewPrefixV1 returns a CIDv1 prefix with the specified codec and multihash type. DEPRECATED: Use V1Builder
func PrefixFromBytes ¶
PrefixFromBytes parses a Prefix-byte representation onto a Prefix.
func (Prefix) Bytes ¶
Bytes returns a byte representation of a Prefix. It looks like:
<version><codec><mh-type><mh-length>
func (Prefix) Sum ¶
Sum uses the information in a prefix to perform a multihash.Sum() and return a newly constructed Cid with the resulting multihash.
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.