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
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
Returns
Multiaddr
multiaddr
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()
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
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
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
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
Example
Multiaddr('/ip4/127.0.0.1/tcp/4001').protoNames()
// [ 'ip4', 'tcp' ]
Multiaddr.prototype.tuples
tuples(): Array<Array>
Returns a tuple of parts
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
Number
tuples[].0 code of protocol
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
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
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
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
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
addr: Multiaddr?
:Defaults to usingthis
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