js-libp2p/doc/migrations/v0.29-v0.30.md

Migrating to libp2p@30

A migration guide for refactoring your application code from libp2p v0.29.x to v0.30.0.

Table of Contents

• Migrating to libp2p@30
  • Table of Contents
  • API
    • Pubsub
    • Addresses
  • Development and Testing
  • Module Updates

API

Pubsub

js-libp2p nodes prior to this version were emitting to self on publish by default. This default value was changed on the pubsub router layer in the past, but we kept it overwritten in libp2p to avoid an upstream breaking change. Now js-libp2p does not overwrite the pubsub router options anymore. Upstream projects that want this feature should enable it on their libp2p configuration.

Before

const Gossipsub from 'libp2p-gossipsub')
const Libp2p from 'libp2p')

const libp2p = await Libp2p.create({
  modules: {
    // ... Add required modules according to the Configuration docs
    pubsub: Gossipsub
  }
})

After

const Gossipsub from 'libp2p-gossipsub')
const Libp2p from 'libp2p')

const libp2p = await Libp2p.create({
  modules: {
    // ... Add required modules according to the Configuration docs
    pubsub: Gossipsub
  },
  config: {
    pubsub: {
      emitSelf: true
    }
  }
})

The Pubsub interface was updated on its message signing properties, taking into account the Gossipsub spec updates on libp2p/specs#294 and libp2p/specs#299

The signing property is now based on a globalSignaturePolicy option instead of the previous signMessages and strictSigning options. The default to strict signing pubsub messages was kept, but if you would like to disable it, the properties should be changed as follows:

Before

const Gossipsub from 'libp2p-gossipsub')
const Libp2p from 'libp2p')

const libp2p = await Libp2p.create({
  modules: {
    // ... Add required modules according to the Configuration docs
    pubsub: Gossipsub
  },
  config: {
    pubsub: {
      signMessages: false,
      strictSigning: false
    }
  }
})

After

const Gossipsub from 'libp2p-gossipsub')
const { SignaturePolicy } from 'libp2p-interfaces/src/pubsub/signature-policy')
const Libp2p from 'libp2p')

const libp2p = await Libp2p.create({
  modules: {
    // ... Add required modules according to the Configuration docs
    pubsub: Gossipsub
  },
  config: {
    pubsub: {
      globalSignaturePolicy: SignaturePolicy.StrictNoSign
    }
  }
})

Addresses

Libp2p has supported noAnnounce addresses configuration for some time now. However, it did not provide the best developer experience. In this release, we dropped the noAnnounce configuration property in favor of an announceFilter property function.

Before

const Libp2p from 'libp2p')

const libp2p = await Libp2p.create({
  addresses: {
    listen: ['/ip4/127.0.0.1/tcp/8000/ws'],
    noAnnounce: ['/ip4/127.0.0.1/tcp/8000/ws'],
  },
  // ... additional configuration per the Configuration docs
})

After

const Libp2p from 'libp2p')

// Libp2p utils has several multiaddr utils you can leverage
const isPrivate from 'libp2p-utils/src/multiaddr/is-private')

const libp2p = await Libp2p.create({
  addresses: {
    listen: ['/ip4/127.0.0.1/tcp/8000/ws'],
    // Filter function: (ma: Array<multiaddr>) => Array<multiaddr>
    announceFilter: (multiaddrs) => multiaddrs.filter(m => !isPrivate(m))
  },
  // ... additional configuration per the Configuration docs
})

It is important pointing out another change regarding address advertising. This is not an API breaking change, but it might have influence on your libp2p setup. Previously, when using the addresses announce property, its multiaddrs were concatenated with the listen multiaddrs and then they were filtered out by the noAnnounce multiaddrs, in order to create the list of multiaddrs to advertise. In libp2p@0.30 the logic now operates as follows:

• If announce addresses are provided, only they will be announced (no filters are applied)
• If announce is not provided, the transport addresses will be filtered (if a filter is provided)
  • if the announceFilter is provide it will be passed the transport addresses

Development and Testing

While this is not an API breaking change, there was a behavioral breaking change on the Websockets transport when in a browser environment. This change might create issues on local test setups. libp2p-websockets has allowed TCP and DNS addresses, both with ws or wss to be used for dial purposes. Taking into account security (and browser policies), we are now restricting addresses to DNS + wss in the browser With this new behavior, if you need to use non DNS addresses, you can configure your libp2p node as follows:

const Websockets from 'libp2p-websockets')
const filters from 'libp2p-websockets/src/filters')
const Libp2p from 'libp2p')

const transportKey = Websockets.prototype[Symbol.toStringTag]
const libp2p = await Libp2p.create({
  modules: {
    transport: [Websockets]
    // ... Add required modules according to the Configuration docs
  },
  config: {
    transport: {
      [transportKey]: {
        filter: filters.all
      }
    }
  }
})

Module Updates

With this release you should update the following libp2p modules if you are relying on them:

"libp2p-delegated-content-routing": "^0.8.0",
"libp2p-delegated-peer-routing": "^0.8.0",
"libp2p-floodsub": "^0.24.0",
"libp2p-gossipsub": "^0.7.0",
"libp2p-websockets": "^0.15.0",

Note that some of them do not need to be updated for this libp2p version to work as expected, but we suggest you to keep them updated as part of this release.