IPNS
![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)
ipns record definitions
This module contains all the necessary code for creating, understanding and validating IPNS records.
Lead Maintainer
Vasco Santos.
Table of Contents
Install
npm install ipns
Usage
Create record
import * as ipns from 'ipns'
const entryData = await ipns.create(privateKey, value, sequenceNumber, lifetime)
Validate record
import * as ipns from 'ipns'
await ipns.validate(publicKey, ipnsEntry)
Embed public key to record
import * as ipns from 'ipns'
const ipnsEntryWithEmbedPublicKey = await ipns.embedPublicKey(publicKey, ipnsEntry)
import * as ipns from 'ipns'
const publicKey = ipns.extractPublicKey(peerId, ipnsEntry)
Datastore key
import * as ipns from 'ipns'
ipns.getLocalKey(peerId)
Returns a key to be used for storing the ipns entry locally, that is:
/ipns/${base32(<HASH>)}
Marshal data with proto buffer
import * as ipns from 'ipns'
const entryData = await ipns.create(privateKey, value, sequenceNumber, lifetime)
const marshalledData = ipns.marshal(entryData)
Returns the entry data serialized.
Unmarshal data from proto buffer
import * as ipns from 'ipns'
const data = ipns.unmarshal(storedData)
Returns the entry data structure after being serialized.
Validator
import * as ipns from 'ipns'
const validator = ipns.validator
Contains an object with validate (marshalledData, key)
and select (dataA, dataB)
functions.
The validate
async function aims to verify if an IPNS record is valid. First the record is unmarshalled, then the public key is obtained and finally the record is validated (signature and validity are verified).
The select
function is responsible for deciding which ipns record is the best (newer) between two records. Both records are unmarshalled and their sequence numbers are compared. If the first record provided is the newer, the operation result will be 0
, otherwise the operation result will be 1
.
API
Create record
ipns.create(privateKey, value, sequenceNumber, lifetime)
Create an IPNS record for being stored in a protocol buffer.
privateKey
(PrivKey
RSA Instance): key to be used for cryptographic operations.value
(Uint8Array): ipfs path of the object to be published.sequenceNumber
(Number): number representing the current version of the record.lifetime
(Number): lifetime of the record (in milliseconds).
Returns a Promise
that resolves to an object with the entry's properties eg:
{
value: Uint8Array,
signature: Uint8Array,
validityType: 0,
validity: Uint8Array,
sequence: 2
}
Validate record
ipns.validate(publicKey, ipnsEntry)
Validate an IPNS record previously stored in a protocol buffer.
publicKey
(PubKey
RSA Instance): key to be used for cryptographic operations.ipnsEntry
(Object): ipns entry record (obtained using the create function).
Returns a Promise
, which may be rejected if the validation was not successful.
Datastore key
ipns.getDatastoreKey(peerId)
Get a key for storing the ipns entry in the datastore.
peerId
(Uint8Array
): peer identifier.
Marshal data with proto buffer
const marshalledData = ipns.marshal(entryData)
Returns the entry data serialized.
entryData
(Object): ipns entry record (obtained using the create function).
Unmarshal data from proto buffer
const data = ipns.unmarshal(storedData)
Returns the entry data structure after being serialized.
storedData
(Uint8Array): ipns entry record serialized.
Embed public key to record
const recordWithPublicKey = await ipns.embedPublicKey(publicKey, ipnsEntry)
Embed a public key in an IPNS entry. If it is possible to extract the public key from the peer-id
, there is no need to embed.
publicKey
(PubKey
RSA Instance): key to be used for cryptographic operations.ipnsEntry
(Object): ipns entry record (obtained using the create function).
Returns a Promise
. If the promise resolves to null it means the public key can be extracted directly from the peer-id
.
ipns.extractPublicKey(peerId, ipnsEntry, [callback])
Extract a public key from an IPNS entry.
peerId
(PeerId
Instance): peer identifier object.ipnsEntry
(Object): ipns entry record (obtained using the create function).
The returned public key (PubKey
RSA Instance): may be used for cryptographic operations.
Namespace
Namespace constants for records.
ipns.namespace
ipns.namespaceLength
Contribute
Feel free to join in. All welcome. Open an issue!
This repository falls under the IPFS Code of Conduct.
![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)
License
Copyright (c) Protocol Labs, Inc. under the MIT License. See LICENSE file for details.