bitswap

README

go-bitswap

An implementation of the bitswap protocol in go!

Lead Maintainer

Dirk McCormick

Table of Contents

• Background
• Install
• Usage
• Implementation
• Contribute
• License

Background

Bitswap is the data trading module for ipfs. It manages requesting and sending blocks to and from other peers in the network. Bitswap has two main jobs:

• to acquire blocks requested by the client from the network
• to judiciously send blocks in its possession to other peers who want them

Bitswap is a message based protocol, as opposed to request-response. All messages contain wantlists or blocks.

A node sends a wantlist to tell peers which blocks it wants. When a node receives a wantlist it should check which blocks it has from the wantlist, and consider sending the matching blocks to the requestor.

When a node receives blocks that it asked for, the node should send out a notification called a 'Cancel' to tell its peers that the node no longer wants those blocks.

go-bitswap provides an implementation of the Bitswap protocol in go.

Learn more about how Bitswap works

Install

go-bitswap requires Go >= 1.11 and can be installed using Go modules

Usage

Initializing a Bitswap Exchange

import (
  "context"
  bitswap "github.com/ipfs/go-bitswap"
  bsnet "github.com/ipfs/go-bitswap/network"
  blockstore "github.com/ipfs/go-ipfs-blockstore"
  "github.com/libp2p/go-libp2p-core/routing"
  "github.com/libp2p/go-libp2p-core/host"
)

var ctx context.Context
var host host.Host
var router routing.ContentRouting
var bstore blockstore.Blockstore

network := bsnet.NewFromIpfsHost(host, router)
exchange := bitswap.New(ctx, network, bstore)

Parameter Notes:

1. ctx is just the parent context for all of Bitswap
2. network is a network abstraction provided to Bitswap on top of libp2p & content routing.
3. bstore is an IPFS blockstore

Get A Block Synchronously

var c cid.Cid
var ctx context.Context
var exchange bitswap.Bitswap

block, err := exchange.GetBlock(ctx, c)

Parameter Notes:

1. ctx is the context for this request, which can be cancelled to cancel the request
2. c is the content ID of the block you're requesting

Get Several Blocks Asynchronously

var cids []cid.Cid
var ctx context.Context
var exchange bitswap.Bitswap

blockChannel, err := exchange.GetBlocks(ctx, cids)

Parameter Notes:

1. ctx is the context for this request, which can be cancelled to cancel the request
2. cids is a slice of content IDs for the blocks you're requesting

Get Related Blocks Faster With Sessions

In IPFS, content blocks are often connected to each other through a MerkleDAG. If you know ahead of time that block requests are related, Bitswap can make several optimizations internally in how it requests those blocks in order to get them faster. Bitswap provides a mechanism called a Bitswap Session to manage a series of block requests as part of a single higher level operation. You should initialize a Bitswap Session any time you intend to make a series of block requests that are related -- and whose responses are likely to come from the same peers.

var ctx context.Context
var cids []cids.cid
var exchange bitswap.Bitswap

session := exchange.NewSession(ctx)
blocksChannel, err := session.GetBlocks(ctx, cids)
// later
var relatedCids []cids.cid
relatedBlocksChannel, err := session.GetBlocks(ctx, relatedCids)

Note that NewSession returns an interface with GetBlock and GetBlocks methods that have the same signature as the overall Bitswap exchange.

Tell bitswap a new block was added to the local datastore

var blk blocks.Block
var exchange bitswap.Bitswap

err := exchange.HasBlock(blk)

Contribute

PRs are welcome!

Small note: If editing the Readme, please conform to the standard-readme specification.

License

MIT © Juan Batiz-Benet

Documentation

Index

• Variables
• type Bitswap
  • func New(ctx context.Context, net network.BitSwapNetwork, bstore blockstore.Blockstore, ...) *Bitswap
• type Option
  • func EngineBlockstoreWorkerCount(count int) Option
  • func EngineTaskWorkerCount(count int) Option
  • func MaxOutstandingBytesPerPeer(count int) Option
  • func ProvideEnabled(enabled bool) Option
  • func ProviderSearchDelay(newProvSearchDelay time.Duration) Option
  • func RebroadcastDelay(newRebroadcastDelay delay.D) Option
  • func SetSendDontHaves(send bool) Option
  • func SetSimulateDontHavesOnTimeout(send bool) Option
  • func TaskWorkerCount(count int) Option
  • func WithPeerBlockRequestFilter(pbrf libipfs.PeerBlockRequestFilter) Option
  • func WithScoreLedger(scoreLedger server.ScoreLedger) Option
  • func WithTargetMessageSize(tms int) Option
  • func WithTaskComparator(comparator libipfs.TaskComparator) Option
  • func WithTracer(tap tracer.Tracer) Option
• type PeerBlockRequestFilter
• type Stat
• type TaskComparator
• type TaskInfo
• type Tracer

Variables

var HasBlockBufferSize = libipfs.HasBlockBufferSize

Deprecated: use github.com/ipfs/go-libipfs/bitswap.HasBlockBufferSize instead

Types

type Bitswap

type Bitswap = libipfs.Bitswap

Deprecated: use github.com/ipfs/go-libipfs/bitswap.Bitswap instead

func New

func New(ctx context.Context, net network.BitSwapNetwork, bstore blockstore.Blockstore, options ...Option) *Bitswap

Deprecated: use github.com/ipfs/go-libipfs/bitswap.New instead

type Option

type Option = libipfs.Option

Option is interface{} of server.Option or client.Option or func(*Bitswap) wrapped in a struct to gain strong type checking. Deprecated: use github.com/ipfs/go-libipfs/bitswap.Option instead

func EngineBlockstoreWorkerCount

func EngineBlockstoreWorkerCount(count int) Option

Deprecated: use github.com/ipfs/go-libipfs/bitswap.EngineBlockstoreWorkerCount instead

func EngineTaskWorkerCount

func EngineTaskWorkerCount(count int) Option

Deprecated: use github.com/ipfs/go-libipfs/bitswap.EngineTaskWorkerCount instead

func MaxOutstandingBytesPerPeer

func MaxOutstandingBytesPerPeer(count int) Option

Deprecated: use github.com/ipfs/go-libipfs/bitswap.MaxOutstandingBytesPerPeer instead

func ProvideEnabled

func ProvideEnabled(enabled bool) Option

Deprecated: use github.com/ipfs/go-libipfs/bitswap.ProvideEnabled instead

func ProviderSearchDelay

func ProviderSearchDelay(newProvSearchDelay time.Duration) Option

Deprecated: use github.com/ipfs/go-libipfs/bitswap.ProviderSearchDelay instead

func RebroadcastDelay

func RebroadcastDelay(newRebroadcastDelay delay.D) Option

Deprecated: use github.com/ipfs/go-libipfs/bitswap.RebroadcastDelay instead

func SetSendDontHaves

func SetSendDontHaves(send bool) Option

Deprecated: use github.com/ipfs/go-libipfs/bitswap.SetSendDontHaves instead

func SetSimulateDontHavesOnTimeout

func SetSimulateDontHavesOnTimeout(send bool) Option

Deprecated: use github.com/ipfs/go-libipfs/bitswap.SetSimulateDontHavesOnTimeout instead

func TaskWorkerCount

func TaskWorkerCount(count int) Option

Deprecated: use github.com/ipfs/go-libipfs/bitswap.TaskWorkerCount instead

func WithPeerBlockRequestFilter

func WithPeerBlockRequestFilter(pbrf libipfs.PeerBlockRequestFilter) Option

Deprecated: use github.com/ipfs/go-libipfs/bitswap.WithPeerBlockRequestFilter instead

func WithScoreLedger

func WithScoreLedger(scoreLedger server.ScoreLedger) Option

Deprecated: use github.com/ipfs/go-libipfs/bitswap.WithScoreLedger instead

func WithTargetMessageSize

func WithTargetMessageSize(tms int) Option

Deprecated: use github.com/ipfs/go-libipfs/bitswap.WithTargetMessageSize instead

func WithTaskComparator

func WithTaskComparator(comparator libipfs.TaskComparator) Option

Deprecated: use github.com/ipfs/go-libipfs/bitswap.WithTaskComparator instead

func WithTracer

func WithTracer(tap tracer.Tracer) Option

Deprecated: use github.com/ipfs/go-libipfs/bitswap.WithTracer instead

type PeerBlockRequestFilter

type PeerBlockRequestFilter = libipfs.PeerBlockRequestFilter

Deprecated: use github.com/ipfs/go-libipfs/bitswap.PeerBlockRequestFilter instead

type Stat

type Stat = libipfs.Stat

Deprecated: use github.com/ipfs/go-libipfs/bitswap.Stat instead

type TaskComparator

type TaskComparator = libipfs.TaskComparator

Deprecated: use github.com/ipfs/go-libipfs/bitswap.TaskComparator instead

type TaskInfo

type TaskInfo = libipfs.TaskInfo

Deprecated: use github.com/ipfs/go-libipfs/bitswap.TaskInfo instead

type Tracer

type Tracer = libipfs.Tracer

Deprecated: use github.com/ipfs/go-libipfs/bitswap.Tracer instead