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

124 lines
3.0 KiB
Markdown
Raw Normal View History

<!--Specify versions for migration below-->
# Migrating to libp2p@31
A migration guide for refactoring your application code from libp2p v0.30.x to v0.31.0.
## Table of Contents
- [Types](#types)
- [API](#api)
- [Module Updates](#module-updates)
## Types
Most of the type definitions in the libp2p configuration were `any` or were not included before this release. This might cause breaking changes on upstream projects relying on the previous provided types, as well as to libp2p modules implemented by the libp2p community.
## API
### Core API
`libp2p.dialProtocol` does not accept empty or null protocols returning a connection anymore and `dial` must be used instead.
```js
const connection = await libp2p.dialProtocol(peerId)
```
**After**
```js
const connection = await libp2p.dial(peerId)
```
### Connection Manager Options
We updated the connection manager options naming in `libp2p@0.29` but kept it backward compatible until now.
**Before**
```js
const node = await Libp2p.create({
connectionManager: {
minPeers: 0
}
})
```
**After**
```js
const node = await Libp2p.create({
connectionManager: {
minConnections: 0
}
})
```
You can see full details on how to configure the connection manager [here](https://github.com/libp2p/js-libp2p/blob/master/doc/CONFIGURATION.md#configuring-connection-manager).
### Dialer and Keychain components
Internal property names to create a libp2p `Dialer` and `Keychain` were updated to reflect the properties naming in the libp2p configuration. These are internal modules of libp2p core and should not impact most of the users, but as it is possible to use them separately here follow the changes:
***Before**
```js
const dialer = new Dialer({
transportManager,
peerStore,
concurrency,
perPeerLimit,
timeout,
resolvers,
addressSorter
})
const keychain = new Keychain(datastore, {
passPhrase
})
```
**After**
```js
this.dialer = new Dialer({
transportManager,
peerStore,
maxParallelDials,
maxDialsPerPeer,
dialTimeout,
resolvers,
addressSorter
})
const keychain = new Keychain(datastore, {
pass
})
```
## 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.
feat: convert to typescript (#1172) Converts this module to typescript. - Ecosystem modules renamed from (e.g.) `libp2p-tcp` to `@libp2p/tcp` - Ecosystem module now have named exports - Configuration has been updated, now pass instances of modules instead of classes: - Some configuration keys have been renamed to make them more descriptive. `transport` -> `transports`, `connEncryption` -> `connectionEncryption`. In general where we pass multiple things, the key is now plural, e.g. `streamMuxer` -> `streamMuxers`, `contentRouting` -> `contentRouters`, etc. Where we are configuring a singleton the config key is singular, e.g. `connProtector` -> `connectionProtector` etc. - Properties of the `modules` config key have been moved to the root - Properties of the `config` config key have been moved to the root ```js // before import Libp2p from 'libp2p' import TCP from 'libp2p-tcp' await Libp2p.create({ modules: { transport: [ TCP ], } config: { transport: { [TCP.tag]: { foo: 'bar' } }, relay: { enabled: true, hop: { enabled: true, active: true } } } }) ``` ```js // after import { createLibp2p } from 'libp2p' import { TCP } from '@libp2p/tcp' await createLibp2p({ transports: [ new TCP({ foo: 'bar' }) ], relay: { enabled: true, hop: { enabled: true, active: true } } }) ``` - Use of `enabled` flag has been reduced - previously you could pass a module but disable it with config. Now if you don't want a feature, just don't pass an implementation. Eg: ```js // before await Libp2p.create({ modules: { transport: [ TCP ], pubsub: Gossipsub }, config: { pubsub: { enabled: false } } }) ``` ```js // after await createLibp2p({ transports: [ new TCP() ] }) ``` - `.multiaddrs` renamed to `.getMultiaddrs()` because it's not a property accessor, work is done by that method to calculate announce addresses, observed addresses, etc - `/p2p/${peerId}` is now appended to all addresses returned by `.getMultiaddrs()` so they can be used opaquely (every consumer has to append the peer ID to the address to actually use it otherwise). If you need low-level unadulterated addresses, call methods on the address manager. BREAKING CHANGE: types are no longer hand crafted, this module is now ESM only
2022-03-28 14:30:27 +01:00
It's recommended to check package.json changes for this:
`git diff <release> <prev> -- package.json`
-->
```json
"libp2p-bootstrap": "^0.12.3",
"libp2p-crypto": "^0.19.4",
"libp2p-interfaces": "^0.10.0",
"libp2p-delegated-content-routing": "^0.10.0",
"libp2p-delegated-peer-routing": "^0.9.0",
"libp2p-floodsub": "^0.25.1",
"libp2p-gossipsub": "^0.9.0",
"libp2p-kad-dht": "^0.22.0",
"libp2p-mdns": "^0.16.0",
"libp2p-noise": "^3.0.0",
"libp2p-tcp": "^0.15.4",
"libp2p-webrtc-star": "^0.22.2",
"libp2p-websockets": "^0.15.6"
```
One of the main changes in this new release is the update to `multiaddr@9.0.0`. This should also be updated in upstream projects to avoid several multiaddr versions in the bundle and to avoid potential problems when libp2p interacts with provided outdated multiaddr instances.