@libp2p/interface-internal/dist/src/address-manager.d.ts

Interfaces implemented by internal libp2p components

import type { Multiaddr } from '@multiformats/multiaddr';
/**
 * The type of address:
 *
 * - 'transport' a listen address supplied by a transport
 * - 'announce' a pre-configured announce address
 * - 'observed' a peer reported this as a public address
 * - 'dns-mapping' a DNS address dynamically mapped to one or more public addresses
 * - 'ip-mapping' an external IP address dynamically mapped to a LAN address
 */
export type AddressType = 'transport' | 'announce' | 'observed' | 'dns-mapping' | 'ip-mapping';
/**
 * An address that has been configured or detected
 */
export interface NodeAddress {
    /**
     * The multiaddr that represents the address
     */
    multiaddr: Multiaddr;
    /**
     * Dynamically configured addresses such as observed or IP/DNS mapped ones
     * must be verified as valid by AutoNAT or some other means before the current
     * node will add them to it's peer record and share them with peers.
     *
     * When this value is true, it's safe to share the address.
     */
    verified: boolean;
    /**
     * The timestamp at which the address was last verified
     */
    lastVerified?: number;
    /**
     * A millisecond timestamp after which this address should be reverified
     */
    expires: number;
    /**
     * The source of this address
     */
    type: AddressType;
}
export interface ConfirmAddressOptions {
    /**
     * Override the TTL of the observed address verification
     */
    ttl?: number;
    /**
     * Allows hinting which type of address this is
     */
    type?: AddressType;
}
/**
 * The `AddressManager` provides an interface for managing peer addresses
 * in libp2p. It supports handling multiple types of addresses, verifying their validity,
 * and storing mappings between internal and external addresses.
 */
export interface AddressManager {
    /**
     * Get peer listen multiaddrs
     *
     * @returns An array of `Multiaddr` objects representing listen addresses.
     */
    getListenAddrs(): Multiaddr[];
    /**
     * Get peer announcing multiaddrs
     *
     * @returns An array of `Multiaddr` objects representing announce addresses.
     */
    getAnnounceAddrs(): Multiaddr[];
    /**
     * Get observed multiaddrs - these addresses may not have been confirmed as
     * publicly dialable yet
     *
     * @returns An array of `Multiaddr` objects representing observed addresses.
     */
    getObservedAddrs(): Multiaddr[];
    /**
     * Signal that we have confidence an observed multiaddr is publicly dialable -
     * this will make it appear in the output of `getAddresses()`
     *
     * @param addr - The observed address.
     * @param options - Additional options for confirmation.
     */
    confirmObservedAddr(addr: Multiaddr, options?: ConfirmAddressOptions): void;
    /**
     * Signal that we do not have confidence an observed multiaddr is publicly dialable -
     * this will remove it from the output of `getObservedAddrs()`
     *
     * @param addr - The observed address to remove.
     */
    removeObservedAddr(addr: Multiaddr): void;
    /**
     * Add peer observed addresses.  These will then appear in the output of `getObservedAddrs()`
     * but not `getAddresses()` until their dialability has been confirmed via a call to
     * confirmObservedAddr.
     *
     * @param addr - The observed address to add.
     */
    addObservedAddr(addr: Multiaddr): void;
    /**
     * Get the current node's addresses
     *
     * @returns An array of `Multiaddr` objects representing node addresses.
     */
    getAddresses(): Multiaddr[];
    /**
     * Return all known addresses with metadata
     *
     * @returns An array of `NodeAddress` objects.
     */
    getAddressesWithMetadata(): NodeAddress[];
    /**
     * Adds a mapping between one or more IP addresses and a domain name - when
     * `getAddresses` is invoked, where the IP addresses are present in a
     * multiaddr, an additional multiaddr will be added with `ip4` and `ip6`
     * tuples replaced with `dns4` and `dns6 ones respectively.
     *
     * @param domain - The domain name to map.
     * @param ipAddresses - The associated IP addresses.
     */
    addDNSMapping(domain: string, ipAddresses: string[]): void;
    /**
     * Remove a mapping previously added with `addDNSMapping`.
     *
     * @param domain - The domain name mapping to remove.
     */
    removeDNSMapping(domain: string): void;
    /**
     * Add a publicly routable address/port/protocol tuple that this node is
     * reachable on. Where this node listens on a link-local (e.g. LAN) address
     * with the same protocol for any transport, an additional listen address will
     * be added with the IP and port replaced with this IP and port.
     *
     * It's possible to add a IPv6 address here and have it added to the address
     * list, this is for the case when a router has an external IPv6 address with
     * port forwarding configured, but it does IPv6 -> IPv4 NAT.
     *
     * @param internalIp - The internal IP address.
     * @param internalPort - The internal port number.
     * @param externalIp - The external IP address.
     * @param externalPort - The external port number (optional).
     * @param protocol - The transport protocol (`tcp` or `udp`).
     */
    addPublicAddressMapping(internalIp: string, internalPort: number, externalIp: string, externalPort?: number, protocol?: 'tcp' | 'udp'): void;
    /**
     * Remove a publicly routable address that this node is no longer reachable on
     *
     * @param internalIp - The internal IP address.
     * @param internalPort - The internal port number.
     * @param externalIp - The external IP address.
     * @param externalPort - The external port number (optional).
     * @param protocol - The transport protocol (`tcp` or `udp`).
     */
    removePublicAddressMapping(internalIp: string, internalPort: number, externalIp: string, externalPort?: number, protocol?: 'tcp' | 'udp'): void;
}
//# sourceMappingURL=address-manager.d.ts.map