BITSWAP.md

Bitswap API

• ipfs.bitswap.wantlist([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([peerId,] [options])

Returns the wantlist, optionally filtered by peer ID

Parameters

Name	Type	Description
peerId	PeerId, CID, String or Buffer	An optional 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.wantlist()
console.log(list)
// [ CID('QmHash') ]

const list2 = await ipfs.bitswap.wantlist(peerId)
console.log(list2)
// [ 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 peer IDs as Strings)
• blocksReceived is a BigNumber Int
• dataReceived is a BigNumber Int
• blocksSent is a BigNumber Int
• dataSent is a BigNumber Int
• dupBlksReceived is a BigNumber Int
• dupDataReceived is a BigNumber Int

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.