Self-describing content-addressed identifiers for distributed systems
A CID is a self-describing content-addressed identifier. It uses cryptographic hashes to achieve content addressing. It uses several multiformats to achieve flexible self-description, namely multihash for hashes, multicodec for data content types, and multibase to encode the CID itself into strings.
To use CID in your swift project simply include the package as a dependency in your Package.swift
let package = Package(
...
dependencies: [
// Dependencies declare other packages that this package depends on.
.package(url: "https://github.com/swift-libp2p/swift-cid.git", .upToNextMajor(from: "0.0.1")),
...
],
...
.target(
...
dependencies: [
...
.product(name: "CID", package: "swift-cid"),
]),
...
)
Initialize a v0 CID from a v0 CID String
import CID
let mhStr = "QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n"
let cid = try CID(mhStr)
cid.codec => .dag_pb
cid.code => 112
cid.version => .v0
cid.multibase => .base58btc
cid.toBaseEncodedString => "QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n"
cid.multihash.asString(base: .base58btc) => "QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n"
Initialize a v1 CID from a Multibase encoded v1 CID String
let peerIdStr = "k51qzi5uqu5dj16qyiq0tajolkojyl9qdkr254920wxv7ghtuwcz593tp69z9m" //LibP2P peerID
let cid = try CID(peerIdStr)
cid.codec => .libp2p_key
cid.code => 114
cid.version => .v1
cid.multibase => .base36
cid.toBaseEncodedString => "k51qzi5uqu5dj16qyiq0tajolkojyl9qdkr254920wxv7ghtuwcz593tp69z9m"
Initialize a v1 CID from parts
let mh = try Multihash(raw: "abc", hashedWith: .sha2_256)
let cid = try CID(version: .v1, codec: .dag_cbor, multihash: mh)
cid.codec => .dag_cbor
cid.code => 113
cid.version => .v1
cid.multibase => .base32
cid.toBaseEncodedString => "bafyreif2pall7dybz7vecqka3zo24irdwabwdi4wc55jznaq75q7eaavvu"
Check out CIDTests.swift for more examples on how you can instantiate and use CIDs
/// Initializers
/// Specify the version, codec and hash
CID.init(version:CIDVersion, codec:Codecs, hash:[UInt8])
CID.init(version:CIDVersion, codec:Codecs, hash:String)
/// From a Multihash
CID.init(v0WithMultihash multihash:Multihash)
/// From a CID compliant String / Data
CID.init(_ cid:String)
/// Properties
/// Integer based Enum, currently supports v0 or v1
CID.version:CIDVersion
/// The `Codec` used (ex: 'dag-pb')
CID.codec:Codecs
/// The Multibase used for encoding (ex: 'base32')
CID.multibase:BaseEncoding
/// The CIDs Multihash
CID.multihash:Multihash
/// Returns the Integer code of the Codec used by this CID (ex: dag-pb' -> 112)
CID.code:Int
/// Returns the entirety of the CID as Bytes (Prefixs and Multihash Digest)
CID.rawBuffer:[UInt8]
/// Returns the entirety of the CID as Data (Prefixs and Multihash Digest)
CID.rawData:Data
/// Returns the CIDs Prefix (includes everything but the multihash digest)
///
/// The CID prefix includes the following...
/// - [version] [codec] [hash-algo] [hash-length]
CID.prefix:[UInt8]
/// Convert between CID versions
CID.toV1()
CID.toV0()
CID is a format for referencing content in distributed information systems, like IPFS. It leverages content addressing, cryptographic hashing, and self-describing formats. It is the core identifier used by IPFS and IPLD. It uses a multicodec to indicate its version, making it fully self describing.
You can read an in-depth discussion on why this format was needed in IPFS here: https://github.com/ipfs/specs/issues/130 (first post reproduced here)
A CID is a self-describing content-addressed identifier. It uses cryptographic hashes to achieve content addressing. It uses several multiformats to achieve flexible self-description, namely multihash for hashes, multicodec for data content types, and multibase to encode the CID itself into strings.
Concretely, it's a typed content address: a tuple of (content-type, content-address)
.
Current version: CIDv1
A CIDv1 has four parts:
<cidv1> ::= <mb><multicodec-cidv1><mc><mh>
# or, expanded:
<cidv1> ::= <multibase-prefix><multicodec-cidv1><multicodec-content-type><multihash-content-address>
Where
<multibase-prefix>
is a multibase code (1 or 2 bytes), to ease encoding CIDs into various bases. NOTE: Binary (not text-based) protocols and formats may omit the multibase prefix when the encoding is unambiguous.<multicodec-cidv1>
is a multicodec representing the version of CID, here for upgradability purposes.<multicodec-content-type>
is a multicodec code representing the content type or format of the data being addressed.<multihash-content-address>
is a multihash value, representing the cryptographic hash of the content being addressed. Multihash enables CIDs to use many different cryptographic hash function, for upgradability and protocol agility purposes.That's it!
CIDs design takes into account many difficult tradeoffs encountered while building IPFS. These are mostly coming from the multiformats project.
It is advantageous to have a human readable description of a CID, solely for the purposes of debugging and explanation. We can easily transform a CID to a "Human Readable CID" as follows:
<hr-cid> ::= <hr-mbc> "-" <hr-cid-mc> "-" <hr-mc> "-" <hr-mh>
Where each sub-component is represented with its own human-readable form:
<hr-mbc>
is a human-readable multibase code (eg base58btc
)<hr-cid-mc>
is the string cidv#
(eg cidv1
or cidv2
)<hr-mc>
is a human-readable multicodec code (eg cbor
)<hr-mh>
is a human-readable multihash (eg sha2-256-256-abcdef0123456789...
)For example:
# example CID
zb2rhe5P4gXftAwvA4eXQ5HJwsER2owDyS9sKaQRRVQPn93bA
# corresponding human readable CID
base58btc - cidv1 - raw - sha2-256-256-6e6ff7950a36187a801613426e858dce686cd7d7e3c0fc42ee0330072d245c95
See: https://cid.ipfs.io/#zb2rhe5P4gXftAwvA4eXQ5HJwsER2owDyS9sKaQRRVQPn93bA
CIDv0 is a backwards-compatible version, where:
multibase
of the string representation is always base58btc
and implicit (not written)multicodec
is always dag-pb
and implicit (not written)cid-version
is always cidv0
and implicit (not written)multihash
is written as is but is always a full (length 32) sha256 hash.cidv0 ::= <multihash-content-address>
A CIDv1 has four parts:
<cidv1> ::= <mb><multicodec-cidv1><mc><mh>
# or, expanded:
<cidv1> ::= <multibase-prefix><multicodec-cidv1><multicodec-content-type><multihash-content-address>
To decode a CID, follow the following algorithm:
Qm...
, it's a CIDv0. Decode it as base58btc and continue to step 2.cid
):
[0x12, 0x20, ...]
, it's a CIDv0.
cid
.N
be the first varint in cid
. This is the CID's version.
N == 0x01
(CIDv1):
cid
cid
(after the second varint).N == 0x02
(CIDv2), or N == 0x03
(CIDv3), the CID version is reserved.N
is equal to some other multicodec, the CID is malformed.Contributions are welcomed! This code is very much a proof of concept. I can guarantee you there's a better / safer way to accomplish the same results. Any suggestions, improvements, or even just critques, are welcome!
Let's make this code better together! 🤝
MIT © 2022 Breth Inc.
link |
Stars: 2 |
Last commit: 10 weeks ago |
Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics