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
preload	boolean	false	Whether to preload all blocks created during this operation

Returns

Type	Description
Promise<Uint8Array>	A Uint8Array containing the data of the block

Example

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

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	Uint8Array	The block of data to store

Options

An optional object which may have the following keys:

Name	Type	Default	Description
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	undefined	The hash length (only relevant for go-ipfs)
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
preload	boolean	false	Whether to preload all blocks created during this operation

Returns

Type	Description
Promise<CID>	A CID type object containing 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

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
preload	boolean	false	Whether to preload all blocks created during this operation

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 = CID.parse(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.