BITSWAP.md

Bitswap API

• ipfs.bitswap.wantlist([options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.bitswap.wantlistForPeer(peerId, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.bitswap.unwant(cids, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.bitswap.stat([options])
  • Parameters
  • Options
  • Returns
  • Example

ipfs.bitswap.wantlist([options])

Returns the wantlist for your node

Parameters

None

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<CID[]>	An array of CIDs currently in the wantlist

Example

const list = await ipfs.bitswap.wantlist()
console.log(list)
// [ CID('QmHash') ]

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

ipfs.bitswap.wantlistForPeer(peerId, [options])

Returns the wantlist for a connected peer

Parameters

Name	Type	Default	Description
peerId	PeerId	A peer ID to return the wantlist for

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<CID[]>	An array of CIDs currently in the wantlist

Example

const list = await ipfs.bitswap.wantlistForPeer(peerId)
console.log(list)
// [ CID('QmHash') ]

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

ipfs.bitswap.unwant(cids, [options])

Removes one or more CIDs from the wantlist

Parameters

Name	Type	Description
cids	A CID or Array of CIDs	The CIDs to remove from the wantlist

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<void>	A promise that resolves once the request is complete

Example

let list = await ipfs.bitswap.wantlist()
console.log(list)
// [ CID('QmHash') ]

await ipfs.bitswap.unwant(cid)

list = await ipfs.bitswap.wantlist()
console.log(list)
// []

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

ipfs.bitswap.stat([options])

Show diagnostic information on the bitswap agent.

Note: bitswap.stat and stats.bitswap can be used interchangeably.

Parameters

None

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 that contains information about the bitswap agent

The returned object contains the following keys:

• provideBufLen is an integer.
• wantlist (array of CIDs)
• peers (array of PeerIds)
• blocksReceived is a BigInt
• dataReceived is a BigInt
• blocksSent is a BigInt
• dataSent is a BigInt
• dupBlksReceived is a BigInt
• dupDataReceived is a BigInt

Example

const stats = await ipfs.bitswap.stat()
console.log(stats)
// {
//   provideBufLen: 0,
//   wantlist: [ CID('QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM') ],
//   peers:
//    [ 'QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM',
//      'QmSoLSafTMBsPKadTEgaXctDQVcqN88CNLHXMkTNwMKPnu',
//      'QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd' ],
//   blocksReceived: 0,
//   dataReceived: 0,
//   blocksSent: 0,
//   dataSent: 0,
//   dupBlksReceived: 0,
//   dupDataReceived: 0
// }

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