BLOCK.md

Block API

• ipfs.block.get(cid, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.block.put(block, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.block.rm(cid, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.block.stat(cid, [options])
  • Parameters
  • Options
  • Returns
  • Example

ipfs.block.get(cid, [options])

Get a raw IPFS block.

Parameters

Name	Type	Description
cid	CID, String or Uint8Array	A CID that corresponds to the desired block

Options

An optional object which may have the following keys:

Name	Type	Default	Description
timeout	Number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
Promise<Block>	A Block type object, containing both the data and the hash of the block

Example

const block = await ipfs.block.get(cid)
console.log(block.data)

A great source of examples can be found in the tests for this API.

ipfs.block.put(block, [options])

Stores input as an IPFS block.

Parameters

Name	Type	Description
block	A Uint8Array or Block instance	The block or data to store

Options

An optional object which may have the following keys:

Name	Type	Default	Description
cid	CID	undefined	A CID to store the block under
format	String	'dag-pb'	The codec to use to create the CID
mhtype	String	sha2-256	The hashing algorithm to use to create the CID
mhlen	Number
version	Number	0	The version to use to create the CID
pin	boolean	false	If true, pin added blocks recursively
timeout	Number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Note: If you pass a Block instance as the block parameter, you don't need to pass options, as the block instance will carry the CID value as a property.

Returns

Type	Description
Promise<Block>	A Block type object, containing both the data and the hash of the block

Example

// Defaults
const buf = new TextEncoder().encode('a serialized object')
const decoder = new TextDecoder()

const block = await ipfs.block.put(buf)

console.log(decoder.decode(block.data))
// Logs:
// a serialized object
console.log(block.cid.toString())
// Logs:
// the CID of the object

// With custom format and hashtype through CID
const CID = require('cids')
const buf = new TextEncoder().encode('another serialized object')
const cid = new CID(1, 'dag-pb', multihash)

const block = await ipfs.block.put(blob, cid)

console.log(decoder.decode(block.data))
// Logs:
// a serialized object
console.log(block.cid.toString())
// Logs:
// the CID of the object

A great source of examples can be found in the tests for this API.

ipfs.block.rm(cid, [options])

Remove one or more IPFS block(s).

Parameters

Name	Type	Description
cid	A CID or Array of CIDs	Blocks corresponding to the passed CID(s) will be removed

Options

An optional object which may have the following keys:

Name	Type	Default	Description
force	boolean	false	Ignores nonexistent blocks
quiet	boolean	false	Write minimal output
timeout	Number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
AsyncIterable<Object>	An async iterable that yields objects containing hash and (potentially) error strings

Each object yielded is of the form:

{
  cid: CID,
  error?: Error
}

Note: If an error is present for a given object, the block with that cid was not removed and the error will contain the reason why, for example if the block was pinned.

Example

for await (const result of ipfs.block.rm(cid)) {
  if (result.error) {
    console.error(`Failed to remove block ${result.cid} due to ${result.error.message}`)
  } else {
    console.log(`Removed block ${result.cid}`)
  }
}

A great source of examples can be found in the tests for this API.

ipfs.block.stat(cid, [options])

Print information of a raw IPFS block.

Parameters

Name	Type	Description
cid	A CID or Array of CIDs	The stats of the passed CID will be returned

Options

An optional object which may have the following keys:

Name	Type	Default	Description
timeout	Number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
Promise<Object>	An object containing the block's info

the returned object has the following keys:

{
  cid: CID
  size: number
}

Example

const multihashStr = 'QmQULBtTjNcMwMr4VMNknnVv3RpytrLSdgpvMcTnfNhrBJ'
const cid = new CID(multihashStr)

const stats = await ipfs.block.stat(cid)
console.log(stats.cid.toString())
// Logs: QmQULBtTjNcMwMr4VMNknnVv3RpytrLSdgpvMcTnfNhrBJ
console.log(stat.size)
// Logs: 3739

A great source of examples can be found in the tests for this API.