ipfs-log/docs/entry.js.html at main · orbitdb-archive/ipfs-log · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>JSDoc: Source: entry.js</title>

    <script src="scripts/prettify/prettify.js"> </script>
    <script src="scripts/prettify/lang-css.js"> </script>
    <!--[if lt IE 9]>
      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
    <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>

<body>

<div id="main">

    <h1 class="page-title">Source: entry.js</h1>


    <section>
        <article>
            <pre class="prettyprint source linenums"><code>'use strict'

const Clock = require('./lamport-clock')
const { isDefined, io } = require('./utils')
const stringify = require('json-stringify-deterministic')
const IpfsNotDefinedError = () => new Error('Ipfs instance not defined')
const IPLD_LINKS = ['next', 'refs']
const getWriteFormatForVersion = v => v === 0 ? 'dag-pb' : 'dag-cbor'
const getWriteFormat = e => Entry.isEntry(e) ? getWriteFormatForVersion(e.v) : getWriteFormatForVersion(e)

/*
 * @description
 * An ipfs-log entry
 */
class Entry {
  /**
   * Create an Entry
   * @param {IPFS} ipfs An IPFS instance
   * @param {Identity} identity The identity instance
   * @param {string} logId The unique identifier for this log
   * @param {*} data Data of the entry to be added. Can be any JSON.stringifyable data
   * @param {Array&lt;string|Entry>} [next=[]] Parent hashes or entries
   * @param {LamportClock} [clock] The lamport clock
   * @returns {Promise&lt;Entry>}
   * @example
   * const entry = await Entry.create(ipfs, identity, 'hello')
   * console.log(entry)
   * // { hash: null, payload: "hello", next: [] }
   */
  static async create (ipfs, identity, logId, data, next = [], clock, refs = [], pin) {
    if (!isDefined(ipfs)) throw IpfsNotDefinedError()
    if (!isDefined(identity)) throw new Error('Identity is required, cannot create entry')
    if (!isDefined(logId)) throw new Error('Entry requires an id')
    if (!isDefined(data)) throw new Error('Entry requires data')
    if (!isDefined(next) || !Array.isArray(next)) throw new Error("'next' argument is not an array")

    // Clean the next objects and convert to hashes
    const toEntry = (e) => e.hash ? e.hash : e
    const nexts = next.filter(isDefined).map(toEntry)

    const entry = {
      hash: null, // "zd...Foo", we'll set the hash after persisting the entry
      id: logId, // For determining a unique chain
      payload: data, // Can be any JSON.stringifyable data
      next: nexts, // Array of hashes
      refs: refs,
      v: 2, // To tag the version of this data structure
      clock: clock || new Clock(identity.publicKey)
    }

    const signature = await identity.provider.sign(identity, Entry.toBuffer(entry))

    entry.key = identity.publicKey
    entry.identity = identity.toJSON()
    entry.sig = signature
    entry.hash = await Entry.toMultihash(ipfs, entry, pin)

    return entry
  }

  /**
   * Verifies an entry signature.
   *
   * @param {IdentityProvider} identityProvider The identity provider to use
   * @param {Entry} entry The entry being verified
   * @return {Promise} A promise that resolves to a boolean value indicating if the signature is valid
   */
  static async verify (identityProvider, entry) {
    if (!identityProvider) throw new Error('Identity-provider is required, cannot verify entry')
    if (!Entry.isEntry(entry)) throw new Error('Invalid Log entry')
    if (!entry.key) throw new Error("Entry doesn't have a key")
    if (!entry.sig) throw new Error("Entry doesn't have a signature")

    const e = Entry.toEntry(entry, { presigned: true })
    const verifier = entry.v &lt; 1 ? 'v0' : 'v1'
    return identityProvider.verify(entry.sig, entry.key, Entry.toBuffer(e), verifier)
  }

  /**
   * Transforms an entry into a Buffer.
   * @param {Entry} entry The entry
   * @return {Buffer} The buffer
   */
  static toBuffer (entry) {
    const stringifiedEntry = entry.v === 0 ? JSON.stringify(entry) : stringify(entry)
    return Buffer.from(stringifiedEntry)
  }

  /**
   * Get the multihash of an Entry.
   * @param {IPFS} ipfs An IPFS instance
   * @param {Entry} entry Entry to get a multihash for
   * @returns {Promise&lt;string>}
   * @example
   * const multihash = await Entry.toMultihash(ipfs, entry)
   * console.log(multihash)
   * // "Qm...Foo"
   * @deprecated
   */
  static async toMultihash (ipfs, entry, pin = false) {
    if (!ipfs) throw IpfsNotDefinedError()
    if (!Entry.isEntry(entry)) throw new Error('Invalid object format, cannot generate entry hash')

    // // Ensure `entry` follows the correct format
    const e = Entry.toEntry(entry)
    return io.write(ipfs, getWriteFormat(e.v), e, { links: IPLD_LINKS, pin })
  }

  static toEntry (entry, { presigned = false, includeHash = false } = {}) {
    const e = {
      hash: includeHash ? entry.hash : null,
      id: entry.id,
      payload: entry.payload,
      next: entry.next
    }

    const v = entry.v
    if (v > 1) {
      e.refs = entry.refs // added in v2
    }
    e.v = entry.v
    e.clock = new Clock(entry.clock.id, entry.clock.time)

    if (presigned) {
      return e // don't include key/sig information
    }

    e.key = entry.key
    if (v > 0) {
      e.identity = entry.identity // added in v1
    }
    e.sig = entry.sig
    return e
  }

  /**
   * Create an Entry from a hash.
   * @param {IPFS} ipfs An IPFS instance
   * @param {string} hash The hash to create an Entry from
   * @returns {Promise&lt;Entry>}
   * @example
   * const entry = await Entry.fromMultihash(ipfs, "zd...Foo")
   * console.log(entry)
   * // { hash: "Zd...Foo", payload: "hello", next: [] }
   */
  static async fromMultihash (ipfs, hash) {
    if (!ipfs) throw IpfsNotDefinedError()
    if (!hash) throw new Error(`Invalid hash: ${hash}`)
    const e = await io.read(ipfs, hash, { links: IPLD_LINKS })

    const entry = Entry.toEntry(e)
    entry.hash = hash

    return entry
  }

  /**
   * Check if an object is an Entry.
   * @param {Entry} obj
   * @returns {boolean}
   */
  static isEntry (obj) {
    return obj &amp;&amp; obj.id !== undefined &amp;&amp;
      obj.next !== undefined &amp;&amp;
      obj.payload !== undefined &amp;&amp;
      obj.v !== undefined &amp;&amp;
      obj.hash !== undefined &amp;&amp;
      obj.clock !== undefined &amp;&amp;
      (obj.refs !== undefined || obj.v &lt; 2) // 'refs' added in v2
  }

  /**
   * Compares two entries.
   * @param {Entry} a
   * @param {Entry} b
   * @returns {number} 1 if a is greater, -1 is b is greater
   */
  static compare (a, b) {
    const distance = Clock.compare(a.clock, b.clock)
    if (distance === 0) return a.clock.id &lt; b.clock.id ? -1 : 1
    return distance
  }

  /**
   * Check if an entry equals another entry.
   * @param {Entry} a
   * @param {Entry} b
   * @returns {boolean}
   */
  static isEqual (a, b) {
    return a.hash === b.hash
  }

  /**
   * Check if an entry is a parent to another entry.
   * @param {Entry} entry1 Entry to check
   * @param {Entry} entry2 The parent Entry
   * @returns {boolean}
   */
  static isParent (entry1, entry2) {
    return entry2.next.indexOf(entry1.hash) > -1
  }

  /**
   * Find entry's children from an Array of entries.
   * Returns entry's children as an Array up to the last know child.
   * @param {Entry} entry Entry for which to find the parents
   * @param {Array&lt;Entry>} values Entries to search parents from
   * @returns {Array&lt;Entry>}
   */
  static findChildren (entry, values) {
    let stack = []
    let parent = values.find((e) => Entry.isParent(entry, e))
    let prev = entry
    while (parent) {
      stack.push(parent)
      prev = parent
      parent = values.find((e) => Entry.isParent(prev, e))
    }
    stack = stack.sort((a, b) => a.clock.time > b.clock.time)
    return stack
  }
}

module.exports = Entry
module.exports.IPLD_LINKS = IPLD_LINKS
module.exports.getWriteFormat = getWriteFormat
</code></pre>
        </article>
    </section>


</div>

<nav>
    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="GSet.html">GSet</a></li><li><a href="Log.html">Log</a></li></ul><h3>Global</h3><ul><li><a href="global.html#LastWriteWins">LastWriteWins</a></li><li><a href="global.html#NoZeroes">NoZeroes</a></li><li><a href="global.html#SortByClockId">SortByClockId</a></li><li><a href="global.html#SortByClocks">SortByClocks</a></li><li><a href="global.html#SortByEntryHash">SortByEntryHash</a></li></ul>
</nav>

<br class="clear">

<footer>
    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.6</a> on Fri Dec 11 2020 17:11:17 GMT-0500 (Eastern Standard Time)
</footer>

<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>