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

<!--Specify versions for migration below-->
# 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](#migrating-to-libp2p30)
  - [Table of Contents](#table-of-contents)
  - [API](#api)
    - [Pubsub](#pubsub)
    - [Addresses](#addresses)
  - [Development and Testing](#development-and-testing)
  - [Module Updates](#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**

```js
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**

```js
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](https://github.com/libp2p/js-libp2p-interfaces/tree/master/src/pubsub) was updated on its message signing properties, taking into account the Gossipsub spec updates on [libp2p/specs#294](https://github.com/libp2p/specs/pull/294) and [libp2p/specs#299](https://github.com/libp2p/specs/pull/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**

```js
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**

```js
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**

```js
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**

```js
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:

```js
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:

<!--Specify module versions in JSON for migration below.
It's recommended to check package.json changes for this:
`git diff <release> <prev> -- package.json`
-->

```json
"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.