ipfs
0.34.4

Intro

Installable via npm install --save ipfs, it can also be used directly in the browser.

Download

The source is available for download from GitHub. Alternatively, you can install using npm:

$ npm install --save ipfs

You can then require() ipfs as normal:

const ipfs = require('ipfs')

In the Browser

Ipfs should work in any ES2015 environment out of the box.

Usage:

<script type="text/javascript" src="index.js"></script>

The portable versions of ipfs, including index.js and index.min.js, are included in the /dist folder. Ipfs can also be found on unpkg.com under

put

Put a value to the pubsub datastore indexed by the received key properly encoded.

Parameters

  1. key: Buffer:  
    identifier of the value.
  2. value: Buffer:  
    value to be stored.
  3. callback: function (Error):  

Returns

void

get

Get a value from the pubsub datastore indexed by the received key properly encoded. Moreover, the identifier topic is subscribed and the pubsub datastore records will be updated once new publishes occur.

Parameters

  1. key: Buffer:  
    identifier of the value to be obtained.
  2. callback: function (Error, Buffer):  

Returns

void

getSubscriptions

Get pubsub subscriptions related to ipns.

Parameters

  1. callback: function (Error, Object):  

Returns

void

cancel

Cancel pubsub subscriptions related to ipns.

Parameters

  1. name: String:  
    ipns path to cancel the pubsub subscription.
  2. callback: function (Error, Object):  

Returns

void

put

Put a value to the local datastore indexed by the received key properly encoded.

Parameters

  1. key: Buffer:  
    identifier of the value.
  2. value: Buffer:  
    value to be stored.
  3. callback: function (Error):  

Returns

void

get

Get a value from the local datastore indexed by the received key properly encoded.

Parameters

  1. key: Buffer:  
    identifier of the value to be obtained.
  2. callback: function (Error, Buffer):  

Returns

void

version

If the repo has been initialized, report the current version. Otherwise report the version that would be initialized.

Parameters

  1. callback: function (Error, Number)?:  

Returns

parseIpfsPath

Break an ipfs-path down into it's hash and an array of links.

examples: b58Hash -> { hash: 'b58Hash', links: [] } b58Hash/mercury/venus -> { hash: 'b58Hash', links: ['mercury', 'venus']} /ipfs/b58Hash/links/by/name -> { hash: 'b58Hash', links: ['links', 'by', 'name'] }

Parameters

  1. ipfsPath: String:  
    An ipfs-path

Returns

Object { hash: base58 string, links: [string] , ?err: Error }

Throws

any on an invalid @param ipfsPath

normalizePath

Returns a well-formed ipfs Path. The returned path will always be prefixed with /ipfs/ or /ipns/. If the received string is not a valid ipfs path, an error will be returned examples: b58Hash -> { hash: 'b58Hash', links: [] } b58Hash/mercury/venus -> { hash: 'b58Hash', links: ['mercury', 'venus']} /ipfs/b58Hash/links/by/name -> { hash: 'b58Hash', links: ['links', 'by', 'name'] }

Parameters

  1. pathStr: String:  
    An ipfs-path, or ipns-path or a cid

Returns

String ipfs-path or ipns-path

Throws

any on an invalid @param ipfsPath

resolvePath

Resolve various styles of an ipfs-path to the hash of the target node. Follows links in the path.

Accepts formats:

  • /link/to/venus
  • /ipfs//link/to/pluto
  • multihash Buffer
  • Arrays of the above

Parameters

  1. objectAPI: IPFS:  
    The IPFS object api
  2. callback: Function<err, res>:  
    res is Array<Buffer(hash)> if no callback is passed, returns a Promise

Returns

(Promise | void)

pin.proto

Protobuf interface from go-ipfs/pin/internal/pb/header.proto

glob-source

Create a pull stream source that can be piped to ipfs.addPullStream for the provided file paths.

Parameters

  1. args: ...any:  
  2. options: Object?:  
    Optional options
  3. options.recursive: Boolean?:  
    Recursively glob all paths in directories
  4. options.hidden: Boolean?:  
    Include .dot files in matched paths
  5. options.ignore: Array<String>?:  
    Glob paths to ignore
  6. options.followSymlinks: Boolean?:  
    follow symlinks

Returns

Function pull stream source

parseChunkerString

Parses chunker string into options used by DAGBuilder in ipfs-unixfs-engine

Parameters

  1. chunker: String:  
    Chunker algorithm supported formats: "size-{size}" "rabin" "rabin-{avg}" "rabin-{min}-{avg}-{max}"

Returns

Object Chunker options for DAGBuilder

parseRabinString

Parses rabin chunker string

Parameters

  1. chunker: String:  
    Chunker algorithm supported formats: "rabin" "rabin-{avg}" "rabin-{min}-{avg}-{max}"

Returns

Object rabin chunker options

get

Given a key, query the DHT for its best value.

Parameters

  1. key: Buffer:  
  2. callback: function (Error)?:  

Returns

(Promise | void)

put

Write a key/value pair to the DHT.

Given a key of the form /foo/bar and a value of any form, this will write that value to the DHT with that key.

Parameters

  1. key: Buffer:  
  2. value: Buffer:  
  3. callback: function (Error)?:  

Returns

(Promise | void)

findprovs

Find peers in the DHT that can provide a specific value, given a key.

Parameters

  1. key: CID:  
    They key to find providers for.
  2. callback: function (Error, Array<PeerInfo>)?:  

Returns

(Promise<PeerInfo> | void)

findpeer

Query the DHT for all multiaddresses associated with a PeerId.

Parameters

  1. peer: PeerId:  
    The id of the peer to search for.
  2. callback: function (Error, Array<Multiaddr>)?:  

Returns

(Promise<Array<Multiaddr>> | void)

provide

Announce to the network that we are providing given values.

Parameters

  1. keys: (CID | Array<CID>):  
    The keys that should be announced.
  2. options: Object (={}):  
  3. options.recursive: bool (=false):  
    Provide not only the given object but also all objects linked from it.
  4. callback: function (Error)?:  

Returns

(Promise | void)

query

Find the closest peers to a given PeerId, by querying the DHT.

Parameters

  1. peer: PeerId:  
    The PeerId to run the query agains.
  2. callback: function (Error, Array<PeerId>)?:  

Returns

(Promise<Array<PeerId>> | void)

cidToString

Stringify a CID encoded in the requested base, upgrading to v1 if necessary.

Setting upgrade to false will disable automatic CID upgrading from v0 to v1 which is necessary if the multibase is something other than base58btc. Note that it will also not apply the encoding (since v0 CIDs can only be encoded as base58btc).

Parameters

  1. cid: (CID | Buffer | String):  
    The CID to encode
  2. options: Object?:  
    Optional options
  3. options.base: String?:  
    Name of multibase codec to encode the CID with
  4. options.upgrade: Boolean?:  
    Automatically upgrade v0 CIDs to v1 when necessary. Default: true.

Returns

publish

IPNS is a PKI namespace, where names are the hashes of public keys, and the private key enables publishing new (signed) values. In both publish and resolve, the default name used is the node's own PeerID, which is the hash of its public key.

Parameters

  1. value: String:  
    ipfs path of the object to be published.
  2. options: Object:  
    ipfs publish options.
  3. options.resolve: boolean:  
    resolve given path before publishing.
  4. options.lifetime: String:  
    time duration that the record will be valid for. This accepts durations such as "300s", "1.5h" or "2h45m". Valid time units are "ns", "ms", "s", "m", "h". Default is 24h.
  5. options.ttl: String:  
    time duration this record should be cached for (NOT IMPLEMENTED YET). This accepts durations such as "300s", "1.5h" or "2h45m". Valid time units are "ns", "ms", "s", "m", "h" (caution: experimental).
  6. options.key: String:  
    name of the key to be used or a valid PeerID, as listed by 'ipfs key list -l'.
  7. callback: function (Error)?:  

Returns

(Promise | void)

resolve

Given a key, query the DHT for its best value.

Parameters

  1. name: String:  
    ipns name to resolve. Defaults to your node's peerID.
  2. options: Object:  
    ipfs resolve options.
  3. options.nocache: boolean:  
    do not use cached entries.
  4. options.recursive: boolean:  
    resolve until the result is not an IPNS name.
  5. callback: function (Error)?:  

Returns

(Promise | void)

state

Query the state of IPNS pubsub.

Returns

(Promise | void)

cancel

Cancel a name subscription.

Parameters

  1. name: String:  
    subscription name.
  2. callback: function (Error)?:  

Returns

(Promise | void)

subs

Show current name subscriptions.

Parameters

  1. callback: function (Error)?:  

Returns

(Promise | void)