multiaddr
5.0.2

Introduction

JavaScript implementation of Multiaddr.

What is multiaddr?

Multiaddr is a standard way to represent addresses that:

  • Support any standard network protocols.
  • Self-describe (include protocols).
  • Have a binary packed format.
  • Have a nice string representation.
  • Encapsulate well.

You can read more about what Multiaddr is in the language-independent Github repository: https://github.com/multiformats/multiaddr

Multiaddr is a part of a group of values called Multiformats

Example

var Multiaddr = require('multiaddr')

var home = new Multiaddr('/ip4/127.0.0.1/tcp/80')
// <Multiaddr 047f000001060050 - /ip4/127.0.0.1/tcp/80>

home.buffer
// <Buffer 04 7f 00 00 01 06 00 50>

home.toString()
// '/ip4/127.0.0.1/tcp/80'

home.protos()
// [ { code: 4, size: 32, name: 'ip4' },
//   { code: 6, size: 16, name: 'tcp' } ]

home.nodeAddress()
// { family: 'IPv4', address: '127.0.0.1', port: '80' }

var proxy = new Multiaddr('/ip4/192.168.2.1/tcp/3128')
// <Multiaddr 04c0a80201060c38 - /ip4/192.168.2.1/tcp/3128>

var full = proxy.encapsulate(home)
// <Multiaddr 04c0a80201060c38047f000001060050 - /ip4/192.168.2.1/tcp/3128/ip4/127.0.0.1/tcp/80>

full.toString()
// '/ip4/192.168.2.1/tcp/3128/ip4/127.0.0.1/tcp/80'

Installation

npm

> npm install multiaddr

Setup

Node.js

var Multiaddr = require('multiaddr')

Browser: Browserify, Webpack, other bundlers

The code published to npm that gets loaded on require is in fact a ES5 transpiled version with the right shims added. This means that you can require it and use with your favourite bundler without having to adjust asset management process.

var Multiaddr = require('multiaddr')

Browser: <script> Tag

Loading this module through a script tag will make the Multiaddr obj available in the global namespace.

<script src="https://unpkg.com/multiaddr/dist/index.min.js"></script>
<!-- OR -->
<script src="https://unpkg.com/multiaddr/dist/index.js"></script>

Multiaddr

Creates a multiaddr from a Buffer, String or another Multiaddr instance public key.

Parameters

  1. addr: (String | Buffer | Multiaddr):  
    If String or Buffer, needs to adhere to the address format of a multiaddr

Example

Multiaddr('/ip4/127.0.0.1/tcp/4001')
// <Multiaddr 047f000001060fa1 - /ip4/127.0.0.1/tcp/4001>

static

Multiaddr.fromNodeAddress

fromNodeAddress(addr: String, transport: String): Multiaddr

Creates a Multiaddr from a node-friendly address object

Parameters

  1. addr: String:  
  2. transport: String:  

Returns

Multiaddr multiaddr

Throws

Error Throws error if addr is not truthy
Error Throws error if transport is not truthy

Example

Multiaddr.fromNodeAddress({address: '127.0.0.1', port: '4001'}, 'tcp')
// <Multiaddr 047f000001060fa1 - /ip4/127.0.0.1/tcp/4001>

Multiaddr.protocols

protocols

Object containing table, names and codes of all supported protocols. To get the protocol values from a Multiaddr, you can use .protos(), .protoCodes() or .protoNames()

Returns

{table: Array, names: Object, codes: Object}

Multiaddr.isName

isName(addr: Multiaddr): Bool

Returns if something is a Multiaddr that is a name

Parameters

  1. addr: Multiaddr:  

Returns

Bool isName

Multiaddr.resolve

resolve(addr: Multiaddr, callback: Function): Bool

Returns an array of multiaddrs, by resolving the multiaddr that is a name

Parameters

  1. addr: Multiaddr:  
  2. callback: Function:  

Returns

Bool isName

instance

Multiaddr.prototype.toString

toString(): String

Returns Multiaddr as a String

Returns

Example

Multiaddr('/ip4/127.0.0.1/tcp/4001').toString()
// '/ip4/127.0.0.1/tcp/4001'

Multiaddr.prototype.toOptions

toOptions(): {family: String, host: String, transport: String, port: String}

Returns Multiaddr as a convinient options object to be used with net.createConnection

Returns

{family: String, host: String, transport: String, port: String}

Example

Multiaddr('/ip4/127.0.0.1/tcp/4001').toOptions()
// { family: 'ipv4', host: '127.0.0.1', transport: 'tcp', port: '4001' }

Multiaddr.prototype.inspect

inspect(): String

Returns Multiaddr as a human-readable string

Returns

Example

Multiaddr('/ip4/127.0.0.1/tcp/4001').inspect()
// '<Multiaddr 047f000001060fa1 - /ip4/127.0.0.1/tcp/4001>'

Multiaddr.prototype.protos

protos(): Array<Object>

Returns the protocols the Multiaddr is defined with, as an array of objects, in left-to-right order. Each object contains the protocol code, protocol name, and the size of its address space in bits. See list of protocols

Returns

Array<Object> protocols - All the protocols the address is composed of
Number protocols[].code
Number protocols[].size
String protocols[].name

Example

Multiaddr('/ip4/127.0.0.1/tcp/4001').protos()
// [ { code: 4, size: 32, name: 'ip4' },
//   { code: 6, size: 16, name: 'tcp' } ]

Multiaddr.prototype.protoCodes

protoCodes(): Array<Number>

Returns the codes of the protocols in left-to-right order. See list of protocols

Returns

Array<Number> protocol codes

Example

Multiaddr('/ip4/127.0.0.1/tcp/4001').protoCodes()
// [ 4, 6 ]

Multiaddr.prototype.protoNames

protoNames(): Array<String>

Returns the names of the protocols in left-to-right order. See list of protocols

Returns

Array<String> protocol names

Example

Multiaddr('/ip4/127.0.0.1/tcp/4001').protoNames()
// [ 'ip4', 'tcp' ]

Multiaddr.prototype.tuples

tuples(): Array<Array>

Returns a tuple of parts

Returns

Array<Array> tuples
Number tuples[].0 code of protocol
Buffer tuples[].1 contents of address

Example

Multiaddr("/ip4/127.0.0.1/tcp/4001").tuples()
// [ [ 4, <Buffer 7f 00 00 01> ], [ 6, <Buffer 0f a1> ] ]

Multiaddr.prototype.stringTuples

stringTuples(): Array<Array>

Returns a tuple of string/number parts

Returns

Array<Array> tuples
Number tuples[].0 code of protocol
(String | Number) tuples[].1 contents of address

Example

Multiaddr("/ip4/127.0.0.1/tcp/4001").stringTuples()
// [ [ 4, '127.0.0.1' ], [ 6, 4001 ] ]

Multiaddr.prototype.encapsulate

encapsulate(addr: Multiaddr): Multiaddr

Encapsulates a Multiaddr in another Multiaddr

Parameters

  1. addr: Multiaddr:  
    Multiaddr to add into this Multiaddr

Returns

Example

const mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080')
// <Multiaddr 0408080808060438 - /ip4/8.8.8.8/tcp/1080>

const mh2 = Multiaddr('/ip4/127.0.0.1/tcp/4001')
// <Multiaddr 047f000001060fa1 - /ip4/127.0.0.1/tcp/4001>

const mh3 = mh1.encapsulate(mh2)
// <Multiaddr 0408080808060438047f000001060fa1 - /ip4/8.8.8.8/tcp/1080/ip4/127.0.0.1/tcp/4001>

mh3.toString()
// '/ip4/8.8.8.8/tcp/1080/ip4/127.0.0.1/tcp/4001'

Multiaddr.prototype.decapsulate

decapsulate(addr: Multiaddr): Multiaddr

Decapsulates a Multiaddr from another Multiaddr

Parameters

  1. addr: Multiaddr:  
    Multiaddr to remove from this Multiaddr

Returns

Example

const mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080')
// <Multiaddr 0408080808060438 - /ip4/8.8.8.8/tcp/1080>

const mh2 = Multiaddr('/ip4/127.0.0.1/tcp/4001')
// <Multiaddr 047f000001060fa1 - /ip4/127.0.0.1/tcp/4001>

const mh3 = mh1.encapsulate(mh2)
// <Multiaddr 0408080808060438047f000001060fa1 - /ip4/8.8.8.8/tcp/1080/ip4/127.0.0.1/tcp/4001>

mh3.decapsulate(mh2).toString()
// '/ip4/8.8.8.8/tcp/1080'

Multiaddr.prototype.getPeerId

getPeerId(): (String | null)

Extract the peerId if the multiaddr contains one

Returns

(String | null) peerId - The id of the peer or null if invalid or missing from the ma

Example

const mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080/ipfs/QmValidBase58string')
// <Multiaddr 0408080808060438 - /ip4/8.8.8.8/tcp/1080/ipfs/QmValidBase58string>

// should return QmValidBase58string or null if the id is missing or invalid
const peerId = mh1.getPeerId()

Multiaddr.prototype.equals

equals(addr: Multiaddr): Bool

Checks if two Multiaddrs are the same

Parameters

  1. addr: Multiaddr:  

Returns

Bool

Example

const mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080')
// <Multiaddr 0408080808060438 - /ip4/8.8.8.8/tcp/1080>

const mh2 = Multiaddr('/ip4/127.0.0.1/tcp/4001')
// <Multiaddr 047f000001060fa1 - /ip4/127.0.0.1/tcp/4001>

mh1.equals(mh1)
// true

mh1.equals(mh2)
// false

Multiaddr.prototype.nodeAddress

nodeAddress(): {family: String, address: String, port: String}

Gets a Multiaddrs node-friendly address object. Note that protocol information is left out: in Node (and most network systems) the protocol is unknowable given only the address.

Has to be a ThinWaist Address, otherwise throws error

Returns

{family: String, address: String, port: String}

Throws

Error Throws error if Multiaddr is not a Thin Waist address

Example

Multiaddr('/ip4/127.0.0.1/tcp/4001').nodeAddress()
// {family: 'IPv4', address: '127.0.0.1', port: '4001'}

Multiaddr.prototype.isThinWaistAddress

isThinWaistAddress(addr: Multiaddr?): Boolean

Returns if a Multiaddr is a Thin Waist address or not.

Thin Waist is if a Multiaddr adheres to the standard combination of:

{IPv4, IPv6}/{TCP, UDP}

Parameters

  1. addr: Multiaddr?:  
    Defaults to using this instance

Returns

Boolean isThinWaistAddress

Example

const mh1 = Multiaddr('/ip4/127.0.0.1/tcp/4001')
// <Multiaddr 047f000001060fa1 - /ip4/127.0.0.1/tcp/4001>
const mh2 = Multiaddr('/ip4/192.168.2.1/tcp/5001')
// <Multiaddr 04c0a80201061389 - /ip4/192.168.2.1/tcp/5001>
const mh3 = mh1.encapsulate(mh2)
// <Multiaddr 047f000001060fa104c0a80201061389 - /ip4/127.0.0.1/tcp/4001/ip4/192.168.2.1/tcp/5001>
mh1.isThinWaistAddress()
// true
mh2.isThinWaistAddress()
// true
mh3.isThinWaistAddress()
// false

Multiaddr.prototype.fromStupidString

fromStupidString(str: String?): undefined

Converts a "stupid string" into a Multiaddr.

Stupid string format:

<proto><IPv>://<IP Addr>[:<proto port>]
udp4://1.2.3.4:5678

Parameters

  1. str: String?:  
    String in the "stupid" format

Returns

Throws

NotImplemented

buffer