Skip to content

Commit 0c73dba

Browse files
committed
Update JS examples to v1, add code sandbox
1 parent 7a710b9 commit 0c73dba

File tree

1 file changed

+55
-37
lines changed

1 file changed

+55
-37
lines changed

docs/concepts/content-addressing.md

Lines changed: 55 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -69,66 +69,73 @@ $ ipfs cid format -v 1 -b base32 QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR
6969
bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
7070
```
7171

72-
JavaScript users can also leverage the `toV1()` method provided by the [`cids`](https://www.npmjs.com/package/cids) library:
72+
JavaScript users can also leverage the `toV1()` method provided by the [`multiformats`](https://www.npmjs.com/package/multiformats) library:
73+
7374
```js
74-
const CID = require('cids')
75-
new CID('QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR').toV1().toString('base32')
76-
// → bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
75+
const v0 = CID.parse('QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n')
76+
v0.toString()
77+
//> 'QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n'
78+
v0.toV1().toString()
79+
//> 'bafybeihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenxquvyku'
7780
```
7881

79-
### Text to binary
82+
### v1 to v0
83+
84+
Given a CID v1, JS users can convert back to v0 using the `toV0()` method provided by the [`multiformats`](https://www.npmjs.com/package/multiformats) library:
85+
86+
```js
87+
const v1 = CID.parse('bafybeihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenxquvyku')
88+
v1.toString()
89+
//> 'bafybeihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenxquvyku'
90+
v1.toV0().toString()
91+
//> 'QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n'
92+
```
8093

81-
A CID can be represented as both text and as a stream of bytes. The latter may be a better choice when speed and storage efficiency are considerations.
94+
:::callout
95+
**See CID conversion in action**
96+
See the [interactive code sandbox](#codesandbox-converting-between-cid-versions-and-encodings) for an example JS application that converts between CID versions and ecnodings.
97+
:::
8298

83-
To convert a CIDv1 from text to binary form, simply read the first character
84-
and then decode the remainder using the encoding specified in the [multibase table](https://github.com/multiformats/multibase#multibase-table).
99+
### Converting between CID base encodings
85100

86-
JS users can leverage the [`cids`](https://www.npmjs.com/package/cids) library to get a binary version as `Uint8Array`:
101+
A CID can be encoded using any of the encodings specified in the [multibase table](https://github.com/multiformats/multibase#multibase-table). The use of different encodings can impact speed and storage efficiency.
87102

103+
To convert a CIDv1 `cidV1` from one encoding to another, use the `toString()` method. By default, `toString()` will return the `base32` string representation of the CID, but you can use other string representations:
88104

89105
```js
90-
const CID = require('cids')
91-
new CID('bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi').bytes
92-
// → Uint8Array [ 1, 112, 18, 32, 195, 196, 115, 62, ... ]
106+
const cidV1StringBase32 = cidV1.toString();
93107
```
94108

95-
::: warning Be mindful about parsing CIDs correctly. Avoid shortcuts.
96-
97-
Unless you are the one who imported the data to IPFS, the length of a CID is not deterministic and depends on the length of the multihash inside of it.
109+
The following example returns the base256 emoji encoding of the CID:
110+
```js
111+
const cidV1StringBase256 = cidV1.toString(base256emoji);
112+
```
98113

99-
To illustrate, passing a custom hash function will produce CIDs of varying lengths:
114+
Using `.bytes`, the following example returns the raw bytes of the CID:
100115

116+
```js
117+
const cidV1Bytes = cidV1.bytes
101118
```
102-
$ ipfs add --cid-version 1 --hash sha2-256 -nq cat.jpg | wc -c
103-
60
104-
$ ipfs add --cid-version 1 --hash blake2b-256 -nq cat.jpg | wc -c
105-
63
106-
$ ipfs add --cid-version 1 --hash sha3-512 -nq cat.jpg | wc -c
107-
111
108-
```
119+
120+
:::callout
121+
**See CID conversion in action**
122+
See the [interactive code sandbox](#codesandbox-converting-between-cid-versions-and-encodings) for an example JS application that converts between CID versions and ecnodings.
109123
:::
110124

111125

112126
### CID to hex
113127

114128
Sometimes, a [hexadecimal](https://en.wikipedia.org/wiki/Hexadecimal) representation of raw bytes is preferred for debug purposes.
115-
To get the hex for raw `.bytes` of an entire CID, one can use built-in support for `base16` encoding and skip the `f` (multibase prefix):
116-
117-
```javascript
118-
> cid.toString('base16')
119-
'f01701220c3c4733ec8affd06cf9e9ff50ffc6bcd2ec85a6170004bb709669c31de94391a'
129+
To get the hex for raw `.bytes` of a CIDv1 `cidV1`, use `base16` encoding:
120130

121-
> cid.toString('base16').substring(1)
122-
'01701220c3c4733ec8affd06cf9e9ff50ffc6bcd2ec85a6170004bb709669c31de94391a' // "cid as hex"
131+
```js
132+
const cidV1StringBase256 = cidV1.toString(base16);
123133
```
124134

125-
To convert back to a CIDv1, prepend the hex value with `f` ([multibase prefix](https://github.com/multiformats/multibase#multibase-table) for lowercase base16).
126-
Use it as-is (it is a [valid CID](https://ipfs.io/ipfs/f01701220c3c4733ec8affd06cf9e9ff50ffc6bcd2ec85a6170004bb709669c31de94391a)), or convert to a different multibase by passing it as an argument to `toString`:
127-
128-
```javascript
129-
> new CID('f' +'01701220c3c4733ec8affd06cf9e9ff50ffc6bcd2ec85a6170004bb709669c31de94391a').toString('base32')
130-
// → bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
131-
```
135+
:::callout
136+
**See CID conversion in action**
137+
See the [interactive code sandbox](#codesandbox-converting-between-cid-versions-and-encodings) for an example JS application that converts between CID versions and ecnodings.
138+
:::
132139

133140
::: tip
134141
[Subdomain gateways](../how-to/address-ipfs-on-web.md#subdomain-gateway) convert paths with custom bases like base16 to base32 or base36, in an effort to fit a CID in a DNS label:
@@ -138,6 +145,17 @@ Use it as-is (it is a [valid CID](https://ipfs.io/ipfs/f01701220c3c4733ec8affd06
138145
:::
139146

140147

148+
### CodeSandbox: Converting between CID versions and encodings
149+
150+
For a hand-on, interactive application that converts between CID versions and encodings, use the CodeSandbox below.
151+
152+
<iframe src="https://codesandbox.io/embed/converting-between-cid-versions-xrvqop?fontsize=14&hidenavigation=1&theme=dark"
153+
style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
154+
title="Converting between CID versions"
155+
allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
156+
sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
157+
></iframe>
158+
141159
## Further resources
142160

143161
Check out these links for more information on CIDs and how they work:

0 commit comments

Comments
 (0)