@streamr/dht 0.0.1-tatum.0

package/src/dht/store/DataStore.ts

@@ -0,0 +1,321 @@
+import {
+    DataEntry, DeleteDataRequest, DeleteDataResponse, MigrateDataRequest, MigrateDataResponse, PeerDescriptor,
+    StoreDataRequest, StoreDataResponse
+} from '../../proto/packages/dht/protos/DhtRpc'
+import { PeerID } from '../../helpers/PeerID'
+import { Any } from '../../proto/google/protobuf/any'
+import { ServerCallContext } from '@protobuf-ts/runtime-rpc'
+import { DhtCallContext } from '../../rpc-protocol/DhtCallContext'
+import { toProtoRpcClient } from '@streamr/proto-rpc'
+import { StoreServiceClient } from '../../proto/packages/dht/protos/DhtRpc.client'
+import { RoutingRpcCommunicator } from '../../transport/RoutingRpcCommunicator'
+import { IRecursiveFinder } from '../find/RecursiveFinder'
+import { isSamePeerDescriptor, peerIdFromPeerDescriptor } from '../../helpers/peerIdFromPeerDescriptor'
+import { Logger } from '@streamr/utils'
+import { LocalDataStore } from './LocalDataStore'
+import { IStoreService } from '../../proto/packages/dht/protos/DhtRpc.server'
+import { RemoteStore } from './RemoteStore'
+import { Timestamp } from '../../proto/google/protobuf/timestamp'
+import EventEmitter from 'eventemitter3'
+import { Events } from '../DhtNode'
+import { SortedContactList } from '../contact/SortedContactList'
+import { Contact } from '../contact/Contact'
+import { DhtPeer } from '../DhtPeer'
+
+interface DataStoreConfig {
+    rpcCommunicator: RoutingRpcCommunicator
+    recursiveFinder: IRecursiveFinder
+    ownPeerDescriptor: PeerDescriptor
+    localDataStore: LocalDataStore
+    serviceId: string
+    storeMaxTtl: number
+    storeHighestTtl: number
+    storeNumberOfCopies: number
+    dhtNodeEmitter: EventEmitter<Events>
+    getNodesClosestToIdFromBucket: (id: Uint8Array, n?: number) => DhtPeer[]
+}
+
+const logger = new Logger(module)
+
+export class DataStore implements IStoreService {
+
+    private readonly rpcCommunicator: RoutingRpcCommunicator
+    private readonly recursiveFinder: IRecursiveFinder
+    private readonly ownPeerDescriptor: PeerDescriptor
+    private readonly localDataStore: LocalDataStore
+    private readonly serviceId: string
+    private readonly storeMaxTtl: number
+    private readonly storeHighestTtl: number
+    private readonly storeNumberOfCopies: number
+    private readonly dhtNodeEmitter: EventEmitter<Events>
+    private readonly getNodesClosestToIdFromBucket: (id: Uint8Array, n?: number) => DhtPeer[]
+
+    constructor(config: DataStoreConfig) {
+        this.rpcCommunicator = config.rpcCommunicator
+        this.recursiveFinder = config.recursiveFinder
+        this.ownPeerDescriptor = config.ownPeerDescriptor
+        this.localDataStore = config.localDataStore
+        this.serviceId = config.serviceId
+        this.storeMaxTtl = config.storeMaxTtl
+        this.storeHighestTtl = config.storeHighestTtl
+        this.storeNumberOfCopies = config.storeNumberOfCopies
+        this.dhtNodeEmitter = config.dhtNodeEmitter
+        this.getNodesClosestToIdFromBucket = config.getNodesClosestToIdFromBucket
+        this.rpcCommunicator!.registerRpcMethod(StoreDataRequest, StoreDataResponse, 'storeData',
+            (request: StoreDataRequest, context: ServerCallContext) => this.storeData(request, context))
+        this.rpcCommunicator!.registerRpcMethod(MigrateDataRequest, MigrateDataResponse, 'migrateData',
+            (request: MigrateDataRequest, context: ServerCallContext) => this.migrateData(request, context))
+        this.rpcCommunicator!.registerRpcMethod(DeleteDataRequest, DeleteDataResponse, 'deleteData',
+            (request: DeleteDataRequest, context: ServerCallContext) => this.deleteData(request, context))
+
+        this.dhtNodeEmitter.on('newContact', (peerDescriptor: PeerDescriptor, _closestPeers: PeerDescriptor[]) => {
+            this.localDataStore.getStore().forEach((dataMap, _dataKey) => {
+                dataMap.forEach((dataEntry) => {
+                    if (this.shouldMigrateDataToNewNode(dataEntry.dataEntry, peerDescriptor)) {
+                        this.migrateDataToContact(dataEntry.dataEntry, peerDescriptor)
+                    }
+                })
+            })
+        })
+    }
+
+    private shouldMigrateDataToNewNode(dataEntry: DataEntry, newNode: PeerDescriptor): boolean {
+
+        const dataId = PeerID.fromValue(dataEntry.kademliaId)
+        const newNodeId = PeerID.fromValue(newNode.kademliaId)
+        const ownPeerId = PeerID.fromValue(this.ownPeerDescriptor.kademliaId)
+
+        const closestToData = this.getNodesClosestToIdFromBucket(dataEntry.kademliaId, 10)
+
+        const sortedList = new SortedContactList<Contact>(dataId, 20, undefined, true)
+        sortedList.addContact(new Contact(this.ownPeerDescriptor!))
+
+        closestToData.forEach((con) => {
+            if (!newNodeId.equals(PeerID.fromValue(con.getPeerDescriptor().kademliaId))) {
+                sortedList.addContact(new Contact(con.getPeerDescriptor()))
+            }
+        })
+
+        if (!sortedList.getAllContacts()[0].getPeerId().equals(ownPeerId!)) {
+            // If we are not the closes node to the data, do not migrate
+            return false
+        }
+
+        const newPeerId = PeerID.fromValue(newNode.kademliaId)
+        sortedList.addContact(new Contact(newNode))
+
+        const sorted = sortedList.getAllContacts()
+
+        let index = 0
+
+        for (index = 0; index < sorted.length; index++) {
+            if (sorted[index].getPeerId().equals(newPeerId)) {
+                break
+            }
+        }
+
+        // if new node is within the 5 closest nodes to the data
+        // do migrate data to it
+
+        if (index < 5) {
+            this.localDataStore.setStale(dataId, dataEntry.storer!, false)
+            return true
+        } else {
+            this.localDataStore.setStale(dataId, dataEntry.storer!, true)
+            return false
+        }
+    }
+
+    private async migrateDataToContact(dataEntry: DataEntry, contact: PeerDescriptor, doNotConnect: boolean = false): Promise<void> {
+        const remoteStore = new RemoteStore(
+            this.ownPeerDescriptor,
+            contact,
+            toProtoRpcClient(new StoreServiceClient(this.rpcCommunicator.getRpcClientTransport())),
+            this.serviceId
+        )
+        try {
+            const response = await remoteStore.migrateData({ dataEntry }, doNotConnect)
+            if (response.error) {
+                logger.debug('RemoteStore::migrateData() returned error: ' + response.error)
+            }
+        } catch (e) {
+            logger.debug('RemoteStore::migrateData() threw an exception ' + e)
+        }
+    }
+
+    public async storeDataToDht(key: Uint8Array, data: Any): Promise<PeerDescriptor[]> {
+        logger.debug(`Storing data to DHT ${this.serviceId}`)
+        const result = await this.recursiveFinder!.startRecursiveFind(key)
+        const closestNodes = result.closestNodes
+        const successfulNodes: PeerDescriptor[] = []
+        const ttl = this.storeHighestTtl // ToDo: make TTL decrease according to some nice curve
+        const storerTime = Timestamp.now()
+        for (let i = 0; i < closestNodes.length && successfulNodes.length < 5; i++) {
+            if (isSamePeerDescriptor(this.ownPeerDescriptor, closestNodes[i])) {
+                this.localDataStore.storeEntry({
+                    kademliaId: key, 
+                    storer: this.ownPeerDescriptor,
+                    ttl, 
+                    storedAt: Timestamp.now(), 
+                    data,
+                    stale: false,
+                    deleted: false,
+                    storerTime
+                })
+                successfulNodes.push(closestNodes[i])
+                continue
+            }
+            const remoteStore = new RemoteStore(
+                this.ownPeerDescriptor,
+                closestNodes[i],
+                toProtoRpcClient(new StoreServiceClient(this.rpcCommunicator.getRpcClientTransport())),
+                this.serviceId
+            )
+            try {
+                const response = await remoteStore.storeData({ kademliaId: key, data, ttl, storerTime })
+                if (!response.error) {
+                    successfulNodes.push(closestNodes[i])
+                    logger.trace('remoteStore.storeData() returned success')
+                } else {
+                    logger.debug('remoteStore.storeData() returned error: ' + response.error)
+                }
+            } catch (e) {
+                logger.debug('remoteStore.storeData() threw an exception ' + e)
+            }
+        }
+        return successfulNodes
+    }
+
+    private selfIsOneOfClosestPeers(dataId: Uint8Array): boolean {
+        const ownPeerId = PeerID.fromValue(this.ownPeerDescriptor.kademliaId)
+        const closestPeers = this.getNodesClosestToIdFromBucket(dataId, 5)
+        const sortedList = new SortedContactList<Contact>(ownPeerId, 5, undefined, true)
+        sortedList.addContact(new Contact(this.ownPeerDescriptor))
+        closestPeers.forEach((con) => sortedList.addContact(new Contact(con.getPeerDescriptor())))
+        return sortedList.getClosestContacts().some((node) => node.getPeerId().equals(ownPeerId))
+    }
+
+    public async deleteDataFromDht(key: Uint8Array): Promise<void> {
+        logger.debug(`Deleting data from DHT ${this.serviceId}`)
+        const result = await this.recursiveFinder!.startRecursiveFind(key)
+        const closestNodes = result.closestNodes
+        const successfulNodes: PeerDescriptor[] = []
+        for (let i = 0; i < closestNodes.length && successfulNodes.length < 5; i++) {
+            if (isSamePeerDescriptor(this.ownPeerDescriptor, closestNodes[i])) {
+                this.localDataStore.markAsDeleted(key, peerIdFromPeerDescriptor(this.ownPeerDescriptor))
+                successfulNodes.push(closestNodes[i])
+                continue
+            }
+            const remoteStore = new RemoteStore(
+                this.ownPeerDescriptor,
+                closestNodes[i],
+                toProtoRpcClient(new StoreServiceClient(this.rpcCommunicator.getRpcClientTransport())),
+                this.serviceId
+            )
+            try {
+                const response = await remoteStore.deleteData({ kademliaId: key })
+                if (response.deleted) {
+                    logger.trace('remoteStore.deleteData() returned success')
+                } else {
+                    logger.debug('could not delete data from ' + PeerID.fromValue(closestNodes[i].kademliaId))
+                }
+                successfulNodes.push(closestNodes[i])
+            } catch (e) {
+                logger.debug('remoteStore.deleteData() threw an exception ' + e)
+            }
+        }
+    }
+
+    // RPC service implementation
+    async storeData(request: StoreDataRequest, context: ServerCallContext): Promise<StoreDataResponse> {
+        const ttl = Math.min(request.ttl, this.storeMaxTtl)
+        const { incomingSourceDescriptor } = context as DhtCallContext
+        const { kademliaId, data, storerTime } = request
+        this.localDataStore.storeEntry({ 
+            kademliaId: kademliaId, 
+            storer: incomingSourceDescriptor!, 
+            ttl,
+            storedAt: Timestamp.now(),
+            storerTime,
+            data,
+            stale: !this.selfIsOneOfClosestPeers(kademliaId),
+            deleted: false
+        })
+        
+        if (!this.selfIsOneOfClosestPeers(kademliaId)) {
+            this.localDataStore.setAllEntriesAsStale(PeerID.fromValue(kademliaId))
+        }
+
+        logger.trace(this.ownPeerDescriptor.nodeName + ' storeData()')
+        return StoreDataResponse.create()
+    }
+
+    // RPC service implementation
+    async deleteData(request: DeleteDataRequest, context: ServerCallContext): Promise<DeleteDataResponse> {
+        const { incomingSourceDescriptor } = context as DhtCallContext
+        const { kademliaId } = request
+        const deleted = this.localDataStore.markAsDeleted(kademliaId, peerIdFromPeerDescriptor(incomingSourceDescriptor!))
+        return DeleteDataResponse.create({ deleted })
+    }
+
+    // RPC service implementation
+    public async migrateData(request: MigrateDataRequest, context: ServerCallContext): Promise<MigrateDataResponse> {
+        logger.trace(this.ownPeerDescriptor.nodeName + ' server-side migrateData()')
+        const dataEntry = request.dataEntry!
+
+        const wasStored = this.localDataStore.storeEntry(dataEntry)
+        
+        if (wasStored) {
+            this.migrateDataToNeighborsIfNeeded((context as DhtCallContext).incomingSourceDescriptor!, request.dataEntry!)
+        }
+        if (!this.selfIsOneOfClosestPeers(dataEntry.kademliaId)) {
+            this.localDataStore.setAllEntriesAsStale(PeerID.fromValue(dataEntry.kademliaId))
+        }
+        logger.trace(this.ownPeerDescriptor.nodeName + ' server-side migrateData() at end')
+        return MigrateDataResponse.create()
+    }
+
+    private migrateDataToNeighborsIfNeeded(incomingPeer: PeerDescriptor, dataEntry: DataEntry): void {
+
+        // sort own contact list according to data id
+        const ownPeerId = PeerID.fromValue(this.ownPeerDescriptor!.kademliaId)
+        const dataId = PeerID.fromValue(dataEntry.kademliaId)
+        const incomingPeerId = PeerID.fromValue(incomingPeer.kademliaId)
+        const closestToData = this.getNodesClosestToIdFromBucket(dataEntry.kademliaId, 10)
+
+        const sortedList = new SortedContactList<Contact>(dataId, 5, undefined, true)
+        sortedList.addContact(new Contact(this.ownPeerDescriptor!))
+
+        closestToData.forEach((con) => {
+            sortedList.addContact(new Contact(con.getPeerDescriptor()))
+        })
+
+        if (!sortedList.getAllContacts()[0].getPeerId().equals(ownPeerId)) {
+            // If we are not the closest node to the data, migrate only to the 
+            // closest one to the data
+
+            const contact = sortedList.getAllContacts()[0]
+            const contactPeerId = PeerID.fromValue(contact.getPeerDescriptor().kademliaId)
+            if (!incomingPeerId.equals(contactPeerId) && !ownPeerId.equals(contactPeerId)) {
+                this.migrateDataToContact(dataEntry, contact.getPeerDescriptor()).then(() => {
+                    logger.trace('migrateDataToContact() returned when migrating to only the closest contact')
+                }).catch((e) => {
+                    logger.error('migrating data to only the closest contact failed ' + e)
+                })
+            }
+        } else {
+            // if we are the closest to the data, migrate to all 5 nearest
+
+            sortedList.getAllContacts().forEach((contact) => {
+                const contactPeerId = PeerID.fromValue(contact.getPeerDescriptor().kademliaId)
+                if (!incomingPeerId.equals(contactPeerId) && !ownPeerId.equals(contactPeerId)) {
+                    this.migrateDataToContact(dataEntry, contact.getPeerDescriptor()).then(() => {
+                        logger.trace('migrateDataToContact() returned')
+                    }).catch((e) => {
+                        logger.error('migrating data to one of the closest contacts failed ' + e)
+                    })
+                }
+            })
+        }
+    }
+}

package/src/dht/store/LocalDataStore.ts

@@ -0,0 +1,114 @@
+import { PeerID, PeerIDKey } from '../../helpers/PeerID'
+import { DataEntry, PeerDescriptor } from '../../proto/packages/dht/protos/DhtRpc'
+import { keyFromPeerDescriptor } from '../../helpers/peerIdFromPeerDescriptor'
+
+const MIN_TTL = 1 * 1000
+const MAX_TTL = 300 * 1000
+
+const createTtlValue = (ttl: number): number => {
+    if (ttl < MIN_TTL) {
+        return MIN_TTL
+    } else if (ttl > MAX_TTL) {
+        return MAX_TTL
+    } else {
+        return ttl
+    }
+}
+
+interface LocalDataEntry {
+    dataEntry: DataEntry
+    ttlTimeout: NodeJS.Timeout
+}
+
+export class LocalDataStore {
+    // A map into which each node can store one value per data key
+    // The first key is the key of the data, the second key is the
+    // PeerID of the storer of the data
+    private store: Map<PeerIDKey, Map<PeerIDKey, LocalDataEntry>> = new Map()
+
+    public storeEntry(dataEntry: DataEntry): boolean {
+        const publisherKey = PeerID.fromValue(dataEntry.storer!.kademliaId!).toKey()
+        const dataKey = PeerID.fromValue(dataEntry.kademliaId).toKey()
+        
+        if (!this.store.has(dataKey)) {
+            this.store.set(dataKey, new Map())
+        }
+
+        if (this.store.get(dataKey)!.has(publisherKey)) {
+            const storedMillis = (dataEntry.storerTime!.seconds * 1000) + (dataEntry.storerTime!.nanos / 1000000)
+            const oldLocalEntry = this.store.get(dataKey)!.get(publisherKey)!
+            const oldStoredMillis = (oldLocalEntry.dataEntry.storerTime!.seconds * 1000) + (oldLocalEntry.dataEntry.storerTime!.nanos / 1000000)
+        
+            // do nothing if old entry is newer than the one being migrated
+            if (oldStoredMillis >= storedMillis) {
+                return false
+            } else {
+                clearTimeout(oldLocalEntry.ttlTimeout)
+            }
+        }
+        this.store.get(dataKey)!.set(publisherKey, {
+            dataEntry,
+            ttlTimeout: setTimeout(() => {
+                this.deleteEntry(PeerID.fromValue(dataEntry.kademliaId), dataEntry.storer!)
+            }, createTtlValue(dataEntry.ttl))
+        })
+        return true
+    }
+
+    public markAsDeleted(id: Uint8Array, storer: PeerID): boolean {
+        const dataKey = PeerID.fromValue(id).toKey()
+        if (!this.store.get(dataKey)?.has(storer.toKey())) {
+            return false
+        }
+        const storedEntry = this.store.get(dataKey)!.get(storer.toKey())
+        storedEntry!.dataEntry.deleted = true
+        return true
+    }
+
+    public getStore(): Map<PeerIDKey, Map<PeerIDKey, LocalDataEntry>> {
+        return this.store
+    }
+
+    public getEntry(key: PeerID): Map<PeerIDKey, DataEntry> {
+        const dataEntries = new Map<PeerIDKey, DataEntry>
+        this.store.get(key.toKey())?.forEach((value, key) => {
+            dataEntries.set(key, value.dataEntry)
+        })
+        return dataEntries
+    }
+
+    public setStale(key: PeerID, storer: PeerDescriptor, stale: boolean): void {
+        const storerKey = keyFromPeerDescriptor(storer)
+        const storedEntry = this.store.get(key.toKey())?.get(storerKey)
+        if (storedEntry) {
+            storedEntry.dataEntry.stale = stale
+        }
+    }
+
+    public setAllEntriesAsStale(key: PeerID): void {
+        this.store.get(key.toKey())?.forEach((value) => {
+            value.dataEntry.stale = true
+        })
+    }
+
+    public deleteEntry(key: PeerID, storer: PeerDescriptor): void {
+        const storerKey = keyFromPeerDescriptor(storer)
+        const storedEntry = this.store.get(key.toKey())?.get(storerKey)
+        if (storedEntry) {
+            clearTimeout(storedEntry.ttlTimeout)
+            this.store.get(key.toKey())?.delete(storerKey)
+            if (this.store.get(key.toKey())?.size === 0) {
+                this.store.delete(key.toKey())
+            }
+        }
+    }
+
+    public clear(): void {
+        this.store.forEach((value) => {
+            value.forEach((value) => {
+                clearTimeout(value.ttlTimeout)
+            })
+        })
+        this.store.clear()
+    }
+}

package/src/dht/store/RemoteStore.ts

@@ -0,0 +1,58 @@
+import { Remote } from '../contact/Remote'
+import { IStoreServiceClient } from '../../proto/packages/dht/protos/DhtRpc.client'
+import { 
+    DeleteDataRequest,
+    DeleteDataResponse,
+    MigrateDataRequest,
+    MigrateDataResponse,
+    StoreDataRequest,
+    StoreDataResponse
+} from '../../proto/packages/dht/protos/DhtRpc'
+import { DhtRpcOptions } from '../../rpc-protocol/DhtRpcOptions'
+import { keyFromPeerDescriptor } from '../../helpers/peerIdFromPeerDescriptor'
+
+export class RemoteStore extends Remote<IStoreServiceClient> {
+
+    async storeData(request: StoreDataRequest): Promise<StoreDataResponse> {
+        const options: DhtRpcOptions = {
+            sourceDescriptor: this.ownPeerDescriptor,
+            targetDescriptor: this.peerDescriptor,
+            timeout: 10000
+        }
+        try {
+            return await this.client.storeData(request, options)
+        } catch (err) {
+            throw Error(
+                `Could not store data to ${keyFromPeerDescriptor(this.peerDescriptor)} from ${keyFromPeerDescriptor(this.ownPeerDescriptor)} ${err}`
+            )
+        }
+    }
+
+    async deleteData(request: DeleteDataRequest): Promise<DeleteDataResponse> {
+        const options: DhtRpcOptions = {
+            sourceDescriptor: this.ownPeerDescriptor,
+            targetDescriptor: this.peerDescriptor,
+            timeout: 10000
+        }
+        try {
+            return await this.client.deleteData(request, options)
+        } catch (err) {
+            throw Error(
+                `Could not call delete data to ${keyFromPeerDescriptor(this.peerDescriptor)} ${err}`
+            )
+        }
+    }
+
+    async migrateData(request: MigrateDataRequest, doNotConnect: boolean = false): Promise<MigrateDataResponse> {
+        
+        const options: DhtRpcOptions = {
+            sourceDescriptor: this.ownPeerDescriptor,
+            targetDescriptor: this.peerDescriptor,
+            timeout: 10000,
+            doNotConnect: doNotConnect
+        }
+
+        return this.client.migrateData(request, options)      
+    }
+
+}

package/src/exports.ts

@@ -0,0 +1,19 @@
+export { DhtNode, DhtNodeEvents, DhtNodeOptions } from './dht/DhtNode'
+export { ListeningRpcCommunicator } from './transport/ListeningRpcCommunicator'
+export { Simulator, LatencyType } from './connection/Simulator/Simulator'
+export { SimulatorTransport } from './connection/Simulator/SimulatorTransport'
+export { getRandomRegion, getRegionDelayMatrix } from './connection/Simulator/pings'
+export { PeerDescriptor, Message, NodeType, DataEntry } from './proto/packages/dht/protos/DhtRpc'
+export { ITransport } from './transport/ITransport'
+export { ConnectionManager, ConnectionLocker } from './connection/ConnectionManager'
+export { PeerID, PeerIDKey } from './helpers/PeerID'
+export { DhtPeer } from './dht/DhtPeer'
+export { UUID } from './helpers/UUID'
+export { DhtRpcOptions } from './rpc-protocol/DhtRpcOptions'
+export { protoClasses } from './helpers/protoClasses'
+export { SortedContactList } from './dht/contact/SortedContactList'
+export { Contact } from './dht/contact/Contact'
+export { RecursiveFindResult } from './dht/find/RecursiveFinder'
+export { peerIdFromPeerDescriptor, keyFromPeerDescriptor, isSamePeerDescriptor } from './helpers/peerIdFromPeerDescriptor'
+export { IceServer } from './connection/WebRTC/WebRtcConnector'
+export { DhtCallContext } from './rpc-protocol/DhtCallContext'

package/src/helpers/AddressTools.ts

@@ -0,0 +1,26 @@
+import ipaddr from 'ipaddr.js'
+
+// IPv4 private address ranges as specified by RFC 1918
+const IPv4PrivateRanges = [
+    '10.0.0.0/8',
+    '172.16.0.0/12',
+    '192.168.0.0/16',
+].map((a) => ipaddr.parseCIDR(a))
+
+export function isPrivateIPv4(address: string): boolean {
+    if (ipaddr.IPv4.isValid(address)) {
+        const ip = ipaddr.IPv4.parse(address)
+        for (const range of IPv4PrivateRanges) {
+            if (ip.match(range)) {
+                return true
+            }
+        }
+    }
+
+    return false
+}
+
+export function getAddressFromIceCandidate(candidate: string): string | undefined {
+    const fields = candidate.split(' ').filter((field) => field.length > 0)
+    return fields.length >= 5 && ipaddr.isValid(fields[4]) ? fields[4] : undefined
+}

package/src/helpers/PeerID.ts

@@ -0,0 +1,95 @@
+import { BrandedString } from '@streamr/utils'
+import { UUID } from './UUID'
+import { IllegalArguments } from './errors'
+import crypto from 'crypto'
+
+export type PeerIDKey = BrandedString<'PeerIDKey'>
+
+export class PeerID {
+    // avoid creating a new instance for every operation
+    private static readonly textEncoder = new TextEncoder() 
+    private static readonly textDecoder = new TextDecoder()
+    
+    private readonly data!: Uint8Array
+    private readonly key: PeerIDKey  // precompute often-used form of data
+
+    protected constructor({ ip, value, stringValue }: { ip?: string, value?: Uint8Array, stringValue?: string } = {}) {
+        if (ip) {
+            this.data = new Uint8Array(20)
+            const ipNum = this.ip2Int(ip)
+            const view = new DataView(this.data.buffer)
+            view.setInt32(0, ipNum)
+
+            this.data.set((new UUID()).value, 4)
+        } else if (value) {
+            this.data = new Uint8Array(value.slice(0))
+        } else if (stringValue) {
+            const ab = PeerID.textEncoder.encode(stringValue) //toUTF8Array(stringValue)
+            this.data = ab
+        } else {
+            throw new IllegalArguments('Constructor of PeerID must be given either ip, value or stringValue')
+        }
+
+        this.key = Buffer.from(this.data).toString('hex') as PeerIDKey
+    }
+
+    static fromIp(ip: string): PeerID {
+        return new PeerID({ ip })
+    }
+
+    static fromValue(value: Uint8Array): PeerID {
+        return new PeerID({ value })
+    }
+
+    static fromKey(value: PeerIDKey): PeerID {
+        return new PeerID({ value: Buffer.from(value, 'hex') })
+    }
+
+    static fromString(stringValue: string): PeerID {
+        return new PeerID({ stringValue })
+    }
+
+    static generateRandom(): PeerID {
+        // generate 160 bit random Uint8array
+        const value = new Uint8Array(20)
+        crypto.randomFillSync(value)
+        return new PeerID({ value })
+    }
+
+    // TODO convert to static method?
+    // eslint-disable-next-line class-methods-use-this
+    private ip2Int(ip: string): number {
+        return ip.split('.').map((octet, index, array) => {
+            return parseInt(octet) * Math.pow(256, (array.length - index - 1))
+        }).reduce((prev, curr) => {
+            return prev + curr
+        })
+    }
+
+    equals(other: PeerID): boolean {
+        return (Buffer.compare(this.data, other.value) === 0)
+    }
+
+    toString(): string {
+        return PeerID.textDecoder.decode(this.data) //utf8ArrayToString(this.data)
+    }
+
+    toKey(): PeerIDKey {
+        return this.key
+    }
+
+    get value(): Uint8Array {
+        return this.data
+    }
+
+    hasSmallerHashThan(other: PeerID): boolean {
+        const myId = this.toKey()
+        const theirId = other.toKey()
+        return PeerID.offeringHash(myId + ',' + theirId) < PeerID.offeringHash(theirId + ',' + myId)
+    }
+
+    private static offeringHash(idPair: string): number {
+        const buffer = crypto.createHash('md5').update(idPair).digest()
+        return buffer.readInt32LE(0)
+    }
+}

package/src/helpers/UUID.ts

@@ -0,0 +1,30 @@
+import { v4, parse, stringify } from 'uuid'
+
+export class UUID {
+    private buf: Uint8Array
+
+    constructor(other?: (UUID | Uint8Array | string)) {
+        if (!other) {
+            this.buf = new Uint8Array(16)
+            v4(null, this.buf)
+        } else if (other.constructor === UUID) {
+            this.buf = other.buf
+        } else if (typeof other === 'string') {
+            this.buf = new Uint8Array(parse(other))
+        } else {
+            this.buf = other as Uint8Array
+        }
+    }
+
+    toString(): string {
+        return stringify(this.buf)
+    }
+
+    equals(other: UUID): boolean {
+        return (Buffer.compare(this.buf, other.value) === 0)
+    }
+
+    get value(): Uint8Array {
+        return this.buf
+    }
+}

package/src/helpers/debugHelpers.ts

@@ -0,0 +1,9 @@
+import { Logger } from '@streamr/utils'
+
+export const debugVars: Record<string, any> = []
+
+export function logInfoIf(logger: Logger, condition: boolean, msg: string): void {
+    if (condition) {
+        logger.info(msg)
+    }
+}