Logo for jsDocs.io

multiaddr

  • Version 10.0.1
  • Published
  • 97.9 kB
  • 6 dependencies
  • MIT license

Install

npm i multiaddr
yarn add multiaddr
pnpm add multiaddr

Overview

multiaddr implementation (binary + string representation of network addresses)

Index

Variables

Functions

Classes

Type Aliases

Namespaces

Variables

variable inspect

const inspect: Symbol;

    variable resolvers

    const resolvers: Map<string, Resolver>;

    • {Map<string, Resolver>}

    Functions

    function multiaddr

    multiaddr: (addr: MultiaddrInput) => Multiaddr;

    • Static factory

      Parameter addr

    Classes

    class Multiaddr

    class Multiaddr {}

    • Creates a [multiaddr](https://github.com/multiformats/multiaddr) from a Uint8Array, String or another Multiaddr instance public key.

    constructor

    constructor(addr?: MultiaddrInput);

    • Parameter addr

      If String or Uint8Array, needs to adhere to the address format of a [multiaddr](https://github.com/multiformats/multiaddr#string-format)

      Example 1

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

    property bytes

    bytes: Uint8Array;

    • {Uint8Array} - The raw bytes representing this multiaddress

    method [inspect]

    [inspect]: () => string;

    • Returns Multiaddr as a human-readable string. For post Node.js v10.0.0. https://nodejs.org/api/deprecations.html#deprecations_dep0079_custom_inspection_function_on_objects_via_inspect

      Returns

      {string}

      Example 1

      console.log(new Multiaddr('/ip4/127.0.0.1/tcp/4001'))
      // '<Multiaddr 047f000001060fa1 - /ip4/127.0.0.1/tcp/4001>'

    method decapsulate

    decapsulate: (addr: Multiaddr | string) => Multiaddr;

    • Decapsulates a Multiaddr from another Multiaddr

      Parameter addr

      Multiaddr to remove from this Multiaddr

      Returns

      {Multiaddr}

      Example 1

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

      const mh2 = new 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'

    method decapsulateCode

    decapsulateCode: (code: number) => Multiaddr;

    • A more reliable version of decapsulate if you are targeting a specific code, such as 421 (the p2p protocol code). The last index of the code will be removed from the Multiaddr, and a new instance will be returned. If the code is not present, the original Multiaddr is returned.

      Parameter code

      The code of the protocol to decapsulate from this Multiaddr

      Returns

      {Multiaddr}

      Example 1

      const addr = new Multiaddr('/ip4/0.0.0.0/tcp/8080/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC')
      // <Multiaddr 0400... - /ip4/0.0.0.0/tcp/8080/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC>
      

      addr.decapsulateCode(421).toString()
      // '/ip4/0.0.0.0/tcp/8080'
      

      new Multiaddr('/ip4/127.0.0.1/tcp/8080').decapsulateCode(421).toString()
      // '/ip4/127.0.0.1/tcp/8080'

    method encapsulate

    encapsulate: (addr: MultiaddrInput) => Multiaddr;

    • Encapsulates a Multiaddr in another Multiaddr

      Parameter addr

      Multiaddr to add into this Multiaddr

      Example 1

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

      const mh2 = new 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'

    method equals

    equals: (addr: Multiaddr) => boolean;

    • Checks if two Multiaddrs are the same

      Parameter addr

      Returns

      {boolean}

      Example 1

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

      const mh2 = new 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

    method fromNodeAddress

    static fromNodeAddress: (
        addr: { family: 4 | 6; address: string; port: number },
        transport: string
    ) => Multiaddr;

    • Creates a Multiaddr from a node-friendly address object

      Parameter addr

      Parameter transport

      Example 1

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

    method getPath

    getPath: () => string | null;

    • Extract the path if the multiaddr contains one

      Returns

      {string | null} path - The path of the multiaddr, or null if no path protocol is present

      Example 1

      const mh1 = new Multiaddr('/ip4/8.8.8.8/tcp/1080/unix/tmp/p2p.sock')
      // <Multiaddr 0408080808060438 - /ip4/8.8.8.8/tcp/1080/unix/tmp/p2p.sock>
      

      // should return utf8 string or null if the id is missing or invalid
      const path = mh1.getPath()

      js

    method 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 1

      const mh1 = new 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()

    method inspect

    inspect: () => string;

    • Returns Multiaddr as a human-readable string. Fallback for pre Node.js v10.0.0. https://nodejs.org/api/deprecations.html#deprecations_dep0079_custom_inspection_function_on_objects_via_inspect

      Returns

      {string}

      Example 1

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

    method isMultiaddr

    static isMultiaddr: (value: any) => value is Multiaddr;

    • Check if object is a CID instance

      Parameter value

      Returns

      {value is Multiaddr}

    method isName

    static isName: (addr: Multiaddr) => boolean;

    • Returns if something is a Multiaddr that is a name

      Parameter addr

      Returns

      {boolean} isName

    method isThinWaistAddress

    isThinWaistAddress: (addr?: Multiaddr | undefined) => 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}

      Parameter addr

      Defaults to using this instance

      Example 1

      const mh1 = new Multiaddr('/ip4/127.0.0.1/tcp/4001')
      // <Multiaddr 047f000001060fa1 - /ip4/127.0.0.1/tcp/4001>
      const mh2 = new 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>
      const mh4 = new Multiaddr('/ip4/127.0.0.1/tcp/2000/wss/p2p-webrtc-star/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSooo2a')
      // <Multiaddr 047f0000010607d0de039302a503221220d52ebb89d85b02a284948203a62ff28389c57c9f42beec4ec20db76a64835843 - /ip4/127.0.0.1/tcp/2000/wss/p2p-webrtc-star/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSooo2a>
      mh1.isThinWaistAddress()
      // true
      mh2.isThinWaistAddress()
      // true
      mh3.isThinWaistAddress()
      // false
      mh4.isThinWaistAddress()
      // false

    method nodeAddress

    nodeAddress: () => { family: 4 | 6; address: string; port: number };

    • 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: 4 | 6, address: string, port: number}}

      Throws

      {Error} Throws error if Multiaddr is not a Thin Waist address

      Example 1

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

    method protoCodes

    protoCodes: () => number[];

    • Returns the codes of the protocols in left-to-right order. [See list of protocols](https://github.com/multiformats/multiaddr/blob/master/protocols.csv)

      Returns

      {number[]} protocol codes

      Example 1

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

    method protoNames

    protoNames: () => string[];

    • Returns the names of the protocols in left-to-right order. [See list of protocols](https://github.com/multiformats/multiaddr/blob/master/protocols.csv)

      Returns

      {string[]} protocol names

      Example 1

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

    method protos

    protos: () => Protocol[];

    • 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](https://github.com/multiformats/multiaddr/blob/master/protocols.csv)

      Returns

      {Protocol[]} protocols - All the protocols the address is composed of

      Example 1

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

    method resolve

    resolve: () => Promise<Array<Multiaddr>>;

    • Resolve multiaddr if containing resolvable hostname.

      Returns

      {Promise<Array>}

      Example 1

      Multiaddr.resolvers.set('dnsaddr', resolverFunction)
      const mh1 = new Multiaddr('/dnsaddr/bootstrap.libp2p.io/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb')
      const resolvedMultiaddrs = await mh1.resolve()
      // [
      //   <Multiaddr 04934b5353060fa1a503221220c10f9319dac35c270a6b74cd644cb3acfc1f6efc8c821f8eb282599fd1814f64 - /ip4/147.75.83.83/tcp/4001/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb>,
      //   <Multiaddr 04934b53530601bbde03a503221220c10f9319dac35c270a6b74cd644cb3acfc1f6efc8c821f8eb282599fd1814f64 - /ip4/147.75.83.83/tcp/443/wss/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb>,
      //   <Multiaddr 04934b535391020fa1cc03a503221220c10f9319dac35c270a6b74cd644cb3acfc1f6efc8c821f8eb282599fd1814f64 - /ip4/147.75.83.83/udp/4001/quic/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb>
      // ]

    method stringTuples

    stringTuples: () => [number, (string | undefined)?][];

    • Returns a tuple of string/number parts - tuples[][0] = code of protocol - tuples[][1] = contents of address

      Example 1

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

    method toJSON

    toJSON: () => string;

    • Returns Multiaddr as a JSON encoded object

      Example 1

      JSON.stringify(new Multiaddr('/ip4/127.0.0.1/tcp/4001'))
      // '/ip4/127.0.0.1/tcp/4001'

    method toOptions

    toOptions: () => import('./types').MultiaddrObject;

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

      Example 1

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

    method toString

    toString: () => string;

    • Returns Multiaddr as a String

      Example 1

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

    method tuples

    tuples: () => [number, (Uint8Array | undefined)?][];

    • Returns a tuple of parts

      Example 1

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

    Type Aliases

    type MultiaddrInput

    type MultiaddrInput = string | Multiaddr | Uint8Array | null;

      type MultiaddrObject

      type MultiaddrObject = import('./types').MultiaddrObject;

        type Protocol

        type Protocol = import('./types').Protocol;

          type Resolver

          type Resolver = (addr: Multiaddr) => Promise<string[]>;

            Namespaces

            namespace Multiaddr

            namespace Multiaddr {}

              variable resolvers

              const resolvers: Map<string, Resolver>;

              • {Map<string, Resolver>}

              Package Files (1)

              Dependencies (6)

              Dev Dependencies (4)

              Peer Dependencies (0)

              No peer dependencies.

              Badge

              To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

              You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/multiaddr.

              • Markdown
                [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/multiaddr)
              • HTML
                <a href="https://www.jsdocs.io/package/multiaddr"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>