CID (内容标识符)

用于分布式系统的自描述内容寻址标识符

概述

CID 是一种自描述的内容寻址标识符。它使用加密哈希来实现内容寻址。它使用多种 multiformats 来实现灵活的自描述性，即使用 multihash 用于哈希，multicodec 用于数据内容类型，以及 multibase 用于将 CID 本身编码为字符串。

安装

要在您的 swift 项目中使用 CID，只需将该软件包作为依赖项包含在您的 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"),
            ]),
    ...
)

使用方法

示例

从 v0 CID 字符串初始化 v0 CID

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"

从 Multibase 编码的 v1 CID 字符串初始化 v1 CID

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"

从部分初始化 v1 CID

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"

查看 CIDTests.swift 以获取有关如何实例化和使用 CID 的更多示例

API

/// 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 是一种用于在分布式信息系统中引用内容的格式，例如 IPFS。它利用内容寻址、加密哈希和自描述格式。它是 IPFS 和 IPLD 使用的核心标识符。它使用 multicodec 来指示其版本，使其完全自描述。

您可以在此处阅读关于为什么 IPFS 需要这种格式的深入讨论：ipfs/specs#130（第一篇文章转载于此处）

具体来说，它是一个类型化的内容地址：(内容类型, 内容地址) 的元组。

它是如何工作的？

当前版本：CIDv1

CIDv1 有四个部分

<cidv1> ::= <mb><multicodec-cidv1><mc><mh>
# or, expanded:
<cidv1> ::= <multibase-prefix><multicodec-cidv1><multicodec-content-type><multihash-content-address>

其中

<multibase-prefix> 是一个 multibase 代码（1 或 2 个字节），以便于将 CID 编码为各种 bases。注意： 二进制（非基于文本的）协议和格式在编码明确时可以省略 multibase 前缀。
<multicodec-cidv1> 是一个 multicodec，表示 CID 的版本，此处用于升级目的。
<multicodec-content-type> 是一个 multicodec 代码，表示被寻址数据的内容类型或格式。
<multihash-content-address> 是一个 multihash 值，表示被寻址内容的加密哈希。Multihash 使 CID 能够使用许多不同的加密哈希函数，以实现升级和协议敏捷性。

就是这样！

设计考虑

CID 的设计考虑了在构建 IPFS 时遇到的许多困难的权衡。这些主要来自 multiformats 项目。

紧凑性：CID 本质上是二进制的，以确保它们尽可能紧凑，因为它们旨在成为更长的路径标识符或 URI 的一部分。
传输友好性（或“复制粘贴性”）：CID 使用 multibase 编码，以便可以选择最佳的传输 base。例如，CID 可以编码为 base58btc，以产生更短且易于复制粘贴的哈希。
通用性：CID 旨在能够表示任何格式和任何加密哈希的值。
避免锁定：CID 防止锁定到旧的、可能过时的决策。
可升级性：CID 编码了一个版本，以确保 CID 格式本身可以进化。

人类可读的 CID

拥有 CID 的人类可读描述是有利的，仅用于调试和解释的目的。我们可以轻松地将 CID 转换为“人类可读的 CID”，如下所示

<hr-cid> ::= <hr-mbc> "-" <hr-cid-mc> "-" <hr-mc> "-" <hr-mh>

其中每个子组件都以其自身的人类可读形式表示

<hr-mbc> 是人类可读的 multibase 代码（例如 base58btc）
<hr-cid-mc> 是字符串 cidv#（例如 cidv1 或 cidv2）
<hr-mc> 是人类可读的 multicodec 代码（例如 cbor）
<hr-mh> 是人类可读的 multihash（例如 sha2-256-256-abcdef0123456789...）

例如

# example CID
zb2rhe5P4gXftAwvA4eXQ5HJwsER2owDyS9sKaQRRVQPn93bA
# corresponding human readable CID
base58btc - cidv1 - raw - sha2-256-256-6e6ff7950a36187a801613426e858dce686cd7d7e3c0fc42ee0330072d245c95

参见：https://cid.ipfs.io/#zb2rhe5P4gXftAwvA4eXQ5HJwsER2owDyS9sKaQRRVQPn93bA

版本

CIDv0

CIDv0 是一个向后兼容的版本，其中

字符串表示的 multibase 始终是 base58btc 并且是隐式的（未写入）
multicodec 始终是 dag-pb 并且是隐式的（未写入）
cid-version 始终是 cidv0 并且是隐式的（未写入）
multihash 按原样写入，但始终是完整的（长度为 32）sha256 哈希。

cidv0 ::= <multihash-content-address>

CIDv1